batplot 1.8.4__py3-none-any.whl → 1.8.11__py3-none-any.whl

batplot/converters.py

@@ -2,7 +2,7 @@
 
 This module provides functions to convert X-ray diffraction data between
 different representations, primarily from angle-based (2θ) to momentum
-transfer (Q) space.
+transfer (Q) space, and between different wavelengths.
 
 WHY CONVERT BETWEEN 2θ AND Q?
 -----------------------------
@@ -24,8 +24,8 @@ Converting to Q-space is useful for:
 - Direct comparison with theoretical calculations (often in Q-space)
 - Combining datasets from different experiments
 
-CONVERSION FORMULA:
-------------------
+CONVERSION FORMULAS:
+-------------------
 The conversion uses Bragg's law:
     Q = (4π sin(θ)) / λ
     
@@ -34,6 +34,9 @@ Where:
     - θ: Half of the diffraction angle (2θ/2) in radians
     - λ: X-ray wavelength in Angstroms
 
+To convert from Q back to 2θ:
+    2θ = 2 × arcsin(Q × λ / (4π)) × (180/π)
+    
 Physical meaning:
     - Q represents the momentum transferred from X-ray to sample
     - Higher Q = smaller d-spacing (shorter distances in crystal)
@@ -46,159 +49,205 @@ import os
 import numpy as np
 
 
-def convert_to_qye(filenames, wavelength: float):
+def convert_xrd_data(filenames, from_param: str, to_param: str):
     """
-    Convert 2θ-based XRD files to Q-based .qye files.
-    
-    HOW IT WORKS:
-    ------------
-    This function reads XRD data files that have 2θ (two-theta) angles as the
-    x-axis and converts them to Q-space (momentum transfer). The conversion
-    process:
+    Convert XRD data files between different representations.
     
-    1. Read input file (2θ in degrees, intensity, optional error bars)
-    2. Convert 2θ to θ (half-angle): θ = 2θ / 2
-    3. Convert θ from degrees to radians: θ_rad = θ × π/180
-    4. Apply conversion formula: Q = 4π sin(θ_rad) / λ
-    5. Save output as .qye file (Q, intensity, [error])
+    This function handles three conversion modes:
+    1. Wavelength-to-wavelength: Convert 2θ values from one wavelength to another
+    2. Wavelength-to-Q: Convert 2θ (with given wavelength) to Q space
+    3. Q-to-wavelength: Convert Q space to 2θ (with given wavelength)
     
-    INPUT FORMAT:
+    HOW IT WORKS:
     ------------
-    Expected columns in input file:
-    - Column 1: 2θ values in degrees (e.g., 10.0, 10.1, 10.2, ...)
-    - Column 2: Intensity values (e.g., 100, 150, 200, ...)
-    - Column 3 (optional): Error bars (e.g., 5, 7, 10, ...)
-    
-    OUTPUT FORMAT:
-    -------------
-    Saved .qye file contains:
-    - Column 1: Q values in Å⁻¹ (momentum transfer)
-    - Column 2: Intensity values (unchanged)
-    - Column 3 (if present): Error bars (unchanged)
-    - Header comment: Documents conversion parameters
+    The function reads input files, determines the conversion type based on
+    the from/to parameters, applies the appropriate conversion formula, and
+    saves the converted data to a new 'converted' subfolder.
     
-    WAVELENGTH VALUES:
-    -----------------
-    Common X-ray wavelengths:
-    - Cu Kα: 1.5406 Å (most common lab source)
-    - Mo Kα: 0.7093 Å (higher energy, shorter wavelength)
-    - Synchrotron: 0.6199 Å (or other, depends on beamline)
-    - Co Kα: 1.7889 Å
-    - Fe Kα: 1.9360 Å
+    CONVERSION MODES:
+    ----------------
+    1. Wavelength-to-wavelength (e.g., --convert 1.54 0.25):
+       - Input: 2θ values measured with wavelength1
+       - Process: Convert 2θ → Q using wavelength1, then Q → 2θ using wavelength2
+       - Output: 2θ values for wavelength2
+       
+    2. Wavelength-to-Q (e.g., --convert 1.54 q):
+       - Input: 2θ values measured with given wavelength
+       - Process: Convert 2θ → Q using the wavelength
+       - Output: Q values (Å⁻¹)
+       
+    3. Q-to-wavelength (e.g., --convert q 1.54):
+       - Input: Q values (Å⁻¹)
+       - Process: Convert Q → 2θ using the given wavelength
+       - Output: 2θ values for the given wavelength
     
     Args:
         filenames: List of file paths to convert (e.g., ['data.xy', 'pattern.xye'])
-        wavelength: X-ray wavelength in Angstroms (Å)
-                   Examples:
-                   - 1.5406 for Cu Kα (most common)
-                   - 0.7093 for Mo Kα
-                   - 0.6199 for synchrotron
+        from_param: Source parameter - either a wavelength (float as string) or 'q'
+        to_param: Target parameter - either a wavelength (float as string) or 'q'
     
     Output:
-        Creates .qye files alongside input files with same basename.
-        Example: data.xy → data.qye
+        Creates converted files in a 'converted' subfolder within the directory
+        containing the input files. Files keep their original names but may have
+        different extensions (.qye for Q-space, original extension for 2θ).
         
     Example:
-        >>> # Convert Cu Kα data to Q-space
-        >>> convert_to_qye(['pattern.xy'], wavelength=1.5406)
-        Saved pattern.qye
+        >>> # Convert 2θ from Cu Kα (1.54 Å) to Mo Kα (0.709 Å)
+        >>> convert_xrd_data(['pattern.xy'], '1.54', '0.709')
+        Saved converted/pattern.xy
+        
+        >>> # Convert 2θ to Q space
+        >>> convert_xrd_data(['pattern.xy'], '1.54', 'q')
+        Saved converted/pattern.qye
         
-        >>> # Convert multiple files from synchrotron
-        >>> convert_to_qye(['scan1.xy', 'scan2.xy'], wavelength=0.6199)
-        Saved scan1.qye
-        Saved scan2.qye
+        >>> # Convert Q to 2θ
+        >>> convert_xrd_data(['pattern.qye'], 'q', '1.54')
+        Saved converted/pattern.xy
     """
-    # ====================================================================
-    # PROCESS EACH FILE
-    # ====================================================================
-    # Loop through each input file and convert it to Q-space.
-    # Each file is processed independently (errors in one don't stop others).
-    # ====================================================================
+    # Parse parameters
+    try:
+        from_is_q = (from_param.lower() == 'q')
+        to_is_q = (to_param.lower() == 'q')
+        
+        if from_is_q:
+            from_wl = None
+        else:
+            from_wl = float(from_param)
+            
+        if to_is_q:
+            to_wl = None
+        else:
+            to_wl = float(to_param)
+    except ValueError:
+        print(f"Error: Invalid conversion parameters. Expected wavelengths (numbers) or 'q', got '{from_param}' and '{to_param}'")
+        return
+    
+    # Determine conversion type
+    if not from_is_q and not to_is_q:
+        # Wavelength-to-wavelength conversion
+        conversion_type = "wavelength_to_wavelength"
+    elif not from_is_q and to_is_q:
+        # Wavelength-to-Q conversion
+        conversion_type = "wavelength_to_q"
+    elif from_is_q and not to_is_q:
+        # Q-to-wavelength conversion
+        conversion_type = "q_to_wavelength"
+    else:
+        print("Error: Cannot convert Q to Q (no conversion needed)")
+        return
+    
+    # Process each file
     for fname in filenames:
-        # STEP 1: Validate file exists
+        # Validate file exists
         if not os.path.isfile(fname):
             print(f"File not found: {fname}")
-            continue  # Skip this file, continue with next
+            continue
         
-        # STEP 2: Read data from file
-        # np.loadtxt() reads numeric data, skipping lines starting with '#'
-        # This handles comment lines in data files
+        # Read data from file
         try:
             data = np.loadtxt(fname, comments="#")
         except Exception as e:
             print(f"Error reading {fname}: {e}")
-            continue  # Skip if file can't be read
+            continue
         
-        # STEP 3: Ensure data is 2D array (handle edge cases)
-        # Some files might have only one row, which numpy reads as 1D array
-        # We reshape to 2D so indexing works consistently
+        # Ensure data is 2D array
         if data.ndim == 1:
-            data = data.reshape(1, -1)  # Reshape to (1, n_columns)
+            data = data.reshape(1, -1)
         
-        # STEP 4: Validate data format
-        # Need at least 2 columns: x (2θ) and y (intensity)
+        # Validate data format
         if data.shape[1] < 2:
             print(f"Invalid data format in {fname}: need at least 2 columns (x, y)")
             continue
         
-        # STEP 5: Extract columns
-        x = data[:, 0]  # 2θ values in degrees (first column)
-        y = data[:, 1]  # Intensity values (second column)
-        e = data[:, 2] if data.shape[1] >= 3 else None  # Error bars (third column, optional)
-        
-        # ====================================================================
-        # STEP 6: CONVERT 2θ TO Q
-        # ====================================================================
-        # This is the core conversion using Bragg's law.
-        #
-        # Mathematical steps:
-        # 1. Get θ (half-angle): θ = 2θ / 2
-        #    Example: 2θ = 20° → θ = 10°
-        #
-        # 2. Convert to radians: θ_rad = θ × (π/180)
-        #    Example: θ = 10° → θ_rad = 0.1745 radians
-        #    (NumPy's np.radians() does this conversion)
-        #
-        # 3. Apply conversion formula: Q = 4π sin(θ_rad) / λ
-        #    Example: θ_rad = 0.1745, λ = 1.5406 Å
-        #             Q = 4π sin(0.1745) / 1.5406 = 1.42 Å⁻¹
-        #
-        # Why sin(θ)?
-        # The momentum transfer Q is proportional to sin(θ), not θ itself.
-        # This is because diffraction follows a sine relationship (Bragg's law).
-        # ====================================================================
+        # Extract columns
+        x = data[:, 0]  # X values (2θ or Q)
+        y = data[:, 1]  # Intensity values
+        e = data[:, 2] if data.shape[1] >= 3 else None  # Error bars (optional)
         
-        # Get θ (half of 2θ) and convert to radians
-        # x contains 2θ values in degrees, so x/2 gives θ in degrees
-        theta_rad = np.radians(x / 2)  # Convert degrees to radians
+        # Perform conversion based on type
+        if conversion_type == "wavelength_to_wavelength":
+            # Step 1: Convert 2θ (from_wl) → Q
+            theta_rad = np.radians(x / 2)  # Convert 2θ to θ in radians
+            q = 4 * np.pi * np.sin(theta_rad) / from_wl
+            
+            # Step 2: Convert Q → 2θ (to_wl)
+            # Q = 4π sin(θ) / λ, so sin(θ) = Q × λ / (4π)
+            # θ = arcsin(Q × λ / (4π))
+            # 2θ = 2 × θ × (180/π)
+            sin_theta = q * to_wl / (4 * np.pi)
+            # Clamp sin_theta to valid range [-1, 1] to avoid domain errors
+            sin_theta = np.clip(sin_theta, -1.0, 1.0)
+            theta_rad_new = np.arcsin(sin_theta)
+            x_new = 2 * np.degrees(theta_rad_new)  # Convert to 2θ in degrees
+            output_ext = os.path.splitext(fname)[1]  # Keep original extension
+            
+        elif conversion_type == "wavelength_to_q":
+            # Convert 2θ → Q
+            theta_rad = np.radians(x / 2)  # Convert 2θ to θ in radians
+            x_new = 4 * np.pi * np.sin(theta_rad) / from_wl
+            output_ext = ".qye"
+            
+        elif conversion_type == "q_to_wavelength":
+            # Convert Q → 2θ
+            # Q = 4π sin(θ) / λ, so sin(θ) = Q × λ / (4π)
+            sin_theta = x * to_wl / (4 * np.pi)
+            # Clamp sin_theta to valid range [-1, 1] to avoid domain errors
+            sin_theta = np.clip(sin_theta, -1.0, 1.0)
+            theta_rad = np.arcsin(sin_theta)
+            x_new = 2 * np.degrees(theta_rad)  # Convert to 2θ in degrees
+            output_ext = ".xy"
         
-        # Apply conversion formula: Q = 4π sin(θ) / λ
-        # This gives Q in units of Å⁻¹ (inverse Angstroms)
-        q = 4 * np.pi * np.sin(theta_rad) / wavelength
-        
-        # STEP 7: Prepare output data
-        # Combine Q, intensity, and optional error bars into output array
+        # Prepare output data
         if e is None:
-            # No error bars: output has 2 columns (Q, intensity)
-            out_data = np.column_stack((q, y))
+            out_data = np.column_stack((x_new, y))
         else:
-            # With error bars: output has 3 columns (Q, intensity, error)
-            out_data = np.column_stack((q, y, e))
+            out_data = np.column_stack((x_new, y, e))
+        
+        # Create output directory (converted subfolder)
+        input_dir = os.path.dirname(os.path.abspath(fname))
+        if not input_dir:
+            input_dir = os.getcwd()
+        output_dir = os.path.join(input_dir, "converted")
+        os.makedirs(output_dir, exist_ok=True)
+        
+        # Generate output filename
+        base = os.path.basename(os.path.splitext(fname)[0])
+        output_fname = os.path.join(output_dir, f"{base}{output_ext}")
         
-        # STEP 8: Generate output filename
-        # Replace input extension with .qye
-        # Example: data.xy → data.qye, pattern.xye → pattern.qye
-        base, _ = os.path.splitext(fname)
-        out_fname = f"{base}.qye"
+        # Create header comment
+        if conversion_type == "wavelength_to_wavelength":
+            header = f"# Converted from {os.path.basename(fname)}: 2θ (λ={from_wl} Å) → Q → 2θ (λ={to_wl} Å)"
+        elif conversion_type == "wavelength_to_q":
+            header = f"# Converted from {os.path.basename(fname)}: 2θ (λ={from_wl} Å) → Q"
+        else:  # q_to_wavelength
+            header = f"# Converted from {os.path.basename(fname)}: Q → 2θ (λ={to_wl} Å)"
         
-        # STEP 9: Save converted data
-        # Save with:
-        # - Header comment documenting the conversion (wavelength used)
-        # - 6 decimal places precision (sufficient for most XRD data)
-        # - Space-padded format for readability
-        np.savetxt(out_fname, out_data, fmt="% .6f",
-                   header=f"# Converted from {fname} using λ={wavelength} Å")
-        print(f"Saved {out_fname}")
+        # Save converted data
+        try:
+            # Use UTF-8 encoding to support Greek letters (θ) in headers on all platforms
+            np.savetxt(output_fname, out_data, fmt="% .6f", header=header, encoding='utf-8')
+            print(f"Saved {output_fname}")
+        except Exception as e:
+            print(f"Error saving {output_fname}: {e}")
+
+
+def convert_to_qye(filenames, wavelength: float):
+    """
+    Convert 2θ-based XRD files to Q-based .qye files.
+    
+    This is a legacy function maintained for backward compatibility.
+    For new code, use convert_xrd_data() instead.
+    
+    Args:
+        filenames: List of file paths to convert (e.g., ['data.xy', 'pattern.xye'])
+        wavelength: X-ray wavelength in Angstroms (Å)
+    
+    Output:
+        Creates .qye files alongside input files with same basename.
+        Example: data.xy → data.qye
+    """
+    # Convert to new format: wavelength to Q
+    convert_xrd_data(filenames, str(wavelength), 'q')
 
 
-__all__ = ["convert_to_qye"]
+__all__ = ["convert_xrd_data", "convert_to_qye"]