goad-py 0.5.6__tar.gz → 0.6.1__tar.gz

{goad_py-0.5.6 → goad_py-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: goad-py
-Version: 0.5.6
+Version: 0.6.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering :: Physics

goad_py-0.6.1/goad-py/examples/unified/10_advanced_parameters.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""
+Example 10: Advanced Parameters - Comprehensive Demonstration
+
+Demonstrates ALL modifiable parameters in run_convergence():
+- Optical parameters (wavelength, refractive indices)
+- Convergence parameters (batch size, max orientations, min batches)
+- Beam tracing parameters (thresholds, recursion limits, cutoff)
+- Geometry transformations (problem scale, per-axis scaling, distortion)
+- Advanced configuration (mapping, coherence, field of view)
+- Reproducibility (random seed)
+
+This example showcases the full flexibility of the unified convergence API.
+"""
+
+from pathlib import Path
+import goad_py as goad
+
+print("=" * 80)
+print("Example 10: Advanced Parameters - ALL Modifiable Parameters")
+print("=" * 80)
+
+# Get paths relative to this script's location
+script_dir = Path(__file__).parent
+geom_file = script_dir / "../../../examples/data/hex.obj"
+phips_bins_file = script_dir / "../../../phips_bins_edges.toml"
+
+# Resolve to absolute paths
+geom_file = str(geom_file.resolve())
+phips_bins_file = str(phips_bins_file.resolve())
+
+# Configuration summary
+print("\n" + "=" * 80)
+print("Configuration Summary:")
+print("=" * 80)
+print("OPTICAL PARAMETERS:")
+print("  Wavelength: 0.633 μm (HeNe laser)")
+print("  Particle refractive index: 1.5 + 0.01i (absorbing particle)")
+print("  Medium refractive index: 1.33 + 0.0i (water)")
+print()
+print("CONVERGENCE PARAMETERS:")
+print("  Batch size: 12 orientations per batch")
+print("  Max orientations: 500")
+print("  Min batches: 3")
+print()
+print("BEAM TRACING PARAMETERS:")
+print("  Beam power threshold: 0.01 (stricter than default 0.05)")
+print("  Beam area threshold factor: 2.0 (half of default 4.0)")
+print("  Cutoff: 0.0005 (stricter than default 0.001)")
+print("  Max recursion depth: 6 (limited for demonstration)")
+print("  Max TIR bounces: 50 (half of default 100)")
+print()
+print("GEOMETRY TRANSFORMATIONS:")
+print("  Problem scale: 2.0 (scales entire problem by 2x)")
+print("  Per-axis geometry scale: [1.0, 1.0, 1.5] (stretch z-axis by 1.5x)")
+print("  Distortion: 0.1 (adds 10% geometric distortion)")
+print()
+print("ADVANCED CONFIGURATION:")
+print("  Mapping: GeometricOptics (instead of default ApertureDiffraction)")
+print("  Coherence: True (enable coherent scattering calculations)")
+print("  Field of view factor: 2.0 (doubled FOV)")
+print()
+print("REPRODUCIBILITY:")
+print("  Random seed: 42 (for reproducible results)")
+print()
+print("CONVERGENCE TARGET:")
+print("  Mode: PHIPS detector convergence")
+print("  Detectors: Indices 1-19 (26° to 170°, skipping 18° forward scatter)")
+print("  Tolerance: 50% relative SEM (relaxed for demo)")
+print("=" * 80 + "\n")
+
+# Converge on all PHIPS detectors except the first one (indices 1-19)
+detector_indices = list(range(1, 20))  # [1, 2, 3, ..., 19]
+
+print(f"Starting convergence on {len(detector_indices)} PHIPS detectors...\n")
+
+# Run PHIPS convergence with ALL MODIFIABLE PARAMETERS
+results = goad.run_convergence(
+    # Required parameters
+    geometry=geom_file,
+    targets=[
+        {
+            "tolerance": 0.25,  # 50% relative SEM (relaxed for demo)
+            "tolerance_type": "relative",
+            "detector_indices": detector_indices,
+        }
+    ],
+    mode=goad.PHIPSMode(bins_file=phips_bins_file),
+    # ========================================================================
+    # OPTICAL PARAMETERS
+    # ========================================================================
+    wavelength=0.633,  # HeNe laser wavelength in microns
+    particle_refr_index_re=1.5,  # Real part of particle refractive index
+    particle_refr_index_im=0.01,  # Imaginary part (absorption)
+    medium_refr_index_re=1.33,  # Real part of medium refractive index (water)
+    medium_refr_index_im=0.0,  # Imaginary part (no absorption in medium)
+    # ========================================================================
+    # CONVERGENCE PARAMETERS
+    # ========================================================================
+    batch_size=12,  # Orientations per batch (smaller batches for finer control)
+    max_orientations=500,  # Maximum total orientations
+    min_batches=10,  # Minimum batches before checking convergence
+    mueller_1d=False,  # Mueller matrix output (N/A for PHIPS mode)
+    # ========================================================================
+    # BEAM TRACING PARAMETERS
+    # ========================================================================
+    beam_power_threshold=0.01,  # Beam power threshold (stricter than default)
+    beam_area_threshold_fac=0.001,  # Beam area threshold factor (tighter threshold)
+    cutoff=0.0005,  # Ray power cutoff (more accurate but slower)
+    max_rec=6,  # Maximum recursion depth (limited for demo)
+    max_tir=20,  # Maximum total internal reflection bounces
+    # ========================================================================
+    # GEOMETRY TRANSFORMATIONS
+    # ========================================================================
+    scale=1.0,  # Problem scaling factor (numerical changes only)
+    geom_scale=[3.0, 3.0, 6.0],  # Per-axis geometry scaling
+    distortion=0.0,  # Geometry distortion factor
+    # ========================================================================
+    # ADVANCED CONFIGURATION
+    # ========================================================================
+    mapping=goad.Mapping.ApertureDiffraction,  # or GeometricOptics
+    coherence=True,  # Enable coherent scattering calculations
+    fov_factor=2.0,  # Field of view factor (doubled)
+)
+
+# Print summary
+print(results.summary())
+
+# Save results
+results.save("10_advanced_parameters_results.json")
+
+# Show detailed PHIPS output
+print("\n" + "=" * 80)
+print("PHIPS Detector DSCS Values (all 20 detectors)")
+print("=" * 80)
+
+import json
+
+with open("10_advanced_parameters_results.json", "r") as f:
+    data = json.load(f)
+
+phips_dscs = data.get("phips_dscs")
+detector_angles = data.get("detector_angles")
+
+if phips_dscs and detector_angles:
+    print(
+        f"\n{'Detector':<10} {'Angle':<10} {'DSCS Mean':<15} {'DSCS SEM':<15} {'Rel. SEM':<10}"
+    )
+    print("-" * 70)
+
+    for i, (dscs_data, angle) in enumerate(zip(phips_dscs, detector_angles)):
+        mean, sem = dscs_data[0], dscs_data[1]
+        rel_sem = (sem / abs(mean) * 100) if mean != 0 else float("inf")
+
+        # Mark which detectors were converged on
+        marker = "✓" if i in detector_indices else "○"
+
+        print(
+            f"{marker} {i:<8} {angle:<10.1f} {mean:<15.4e} {sem:<15.4e} {rel_sem:<10.2f}%"
+        )
+
+print("\n" + "=" * 80)
+print("Legend:")
+print("  ✓ = Converged on this detector")
+print("  ○ = Not a convergence target (but still computed)")
+print("=" * 80)
+
+# Show configuration that was used
+print("\n" + "=" * 80)
+print("Configuration Used (from saved results):")
+print("=" * 80)
+
+config = data.get("config", {})
+if config:
+    print(f"\nOptical parameters:")
+    print(f"  Wavelength: {config.get('wavelength')} μm")
+    print(
+        f"  Particle refractive index: {config.get('particle_refr_index_re')} + {config.get('particle_refr_index_im')}i"
+    )
+    print(
+        f"  Medium refractive index: {config.get('medium_refr_index_re')} + {config.get('medium_refr_index_im')}i"
+    )
+
+    beam_tracing = config.get("beam_tracing", {})
+    if beam_tracing:
+        print(f"\nBeam tracing parameters:")
+        print(f"  Max recursion depth: {beam_tracing.get('max_rec')}")
+        print(f"  Max TIR bounces: {beam_tracing.get('max_tir')}")
+        print(f"  Cutoff: {beam_tracing.get('cutoff')}")
+        print(f"  Beam power threshold: {beam_tracing.get('beam_power_threshold')}")
+        print(
+            f"  Beam area threshold factor: {beam_tracing.get('beam_area_threshold_fac')}"
+        )
+
+    geom_transform = config.get("geometry_transform", {})
+    if geom_transform:
+        print(f"\nGeometry transformations:")
+        print(f"  Problem scale: {geom_transform.get('scale')}")
+        if geom_transform.get("distortion"):
+            print(f"  Distortion: {geom_transform.get('distortion')}")
+        if geom_transform.get("geom_scale"):
+            print(f"  Per-axis geometry scale: {geom_transform.get('geom_scale')}")
+
+    advanced = config.get("advanced_config", {})
+    if advanced:
+        print(f"\nAdvanced configuration:")
+        print(f"  Mapping: {advanced.get('mapping')}")
+        print(f"  Coherence: {advanced.get('coherence')}")
+        if advanced.get("fov_factor"):
+            print(f"  Field of view factor: {advanced.get('fov_factor')}")
+
+    if config.get("seed"):
+        print(f"\nReproducibility:")
+        print(f"  Random seed: {config.get('seed')}")
+
+print("\n✓ Example completed successfully!")

{goad_py-0.5.6 → goad_py-0.6.1}/goad-py/python/goad_py/unified_convergence.py

@@ -11,6 +11,8 @@ Features:
 - Strict input validation
 - Uniform output format (UnifiedResults)
 - Support for parameter sweeps
+- Full control over beam tracing, geometry transformations, and advanced optics
+- Reproducible results via random seed control
 """
 
 from dataclasses import dataclass, field, asdict
@@ -211,6 +213,96 @@ class PHIPSMode(ConvergenceMode):
 # ============================================================================
 
 
+@dataclass
+class BeamTracingConfig:
+    """Beam tracing performance and accuracy parameters."""
+
+    beam_power_threshold: float = 0.01
+    beam_area_threshold_fac: float = 0.01
+    cutoff: float = 0.999
+    max_rec: int = 10
+    max_tir: int = 10
+
+    def __post_init__(self):
+        """Validate beam tracing parameters."""
+        if self.beam_power_threshold <= 0 or self.beam_power_threshold > 1:
+            raise ValueError(
+                f"beam_power_threshold must be in range (0, 1], got {self.beam_power_threshold}"
+            )
+
+        if self.beam_area_threshold_fac <= 0:
+            raise ValueError(
+                f"beam_area_threshold_fac must be positive, got {self.beam_area_threshold_fac}"
+            )
+
+        if self.cutoff < 0 or self.cutoff > 1:
+            raise ValueError(f"cutoff must be between 0 and 1, got {self.cutoff}")
+
+        if self.max_rec < 0:
+            raise ValueError(f"max_rec must be non-negative, got {self.max_rec}")
+
+        if self.max_tir < 0:
+            raise ValueError(f"max_tir must be non-negative, got {self.max_tir}")
+
+
+@dataclass
+class GeometryTransformConfig:
+    """Geometry transformation parameters.
+
+    Attributes:
+        scale: Problem scaling factor - scales the entire problem including geometry,
+               wavelength, and beam area thresholds (default: 1.0)
+        distortion: Geometry distortion factor (optional)
+        geom_scale: Per-axis geometry scaling [x, y, z] - scales only the geometry
+                    in each dimension independently (optional)
+    """
+
+    scale: float = 1.0
+    distortion: Optional[float] = None
+    geom_scale: Optional[List[float]] = None
+
+    def __post_init__(self):
+        """Validate geometry transformations."""
+        if self.scale <= 0:
+            raise ValueError(f"scale must be positive, got {self.scale}")
+
+        if self.geom_scale is not None:
+            if len(self.geom_scale) != 3:
+                raise ValueError(
+                    f"geom_scale must have exactly 3 values [x, y, z], "
+                    f"got {len(self.geom_scale)}"
+                )
+            if any(s <= 0 for s in self.geom_scale):
+                raise ValueError("All geom_scale values must be positive")
+
+
+@dataclass
+class AdvancedConfig:
+    """Advanced optical calculation parameters."""
+
+    mapping: Optional[Any] = (
+        "ApertureDiffraction"  # String that will be converted to enum in __post_init__
+    )
+    coherence: bool = True
+    fov_factor: Optional[float] = None
+
+    def __post_init__(self):
+        """Validate advanced optics settings and convert mapping string to enum."""
+        # Convert string mapping to enum if needed
+        if isinstance(self.mapping, str):
+            if self.mapping == "ApertureDiffraction":
+                self.mapping = goad.Mapping.ApertureDiffraction
+            elif self.mapping == "GeometricOptics":
+                self.mapping = goad.Mapping.GeometricOptics
+            else:
+                raise ValueError(
+                    f"Invalid mapping '{self.mapping}'. Must be 'ApertureDiffraction' or 'GeometricOptics'"
+                )
+
+        if self.fov_factor is not None and self.fov_factor <= 0:
+            raise ValueError(f"fov_factor must be positive, got {self.fov_factor}")
+
+
 @dataclass
 class ConvergenceConfig:
     """
@@ -220,6 +312,29 @@ class ConvergenceConfig:
     - Standard convergence (integrated parameters, Mueller elements)
     - PHIPS detector convergence
     - Single geometry or ensemble averaging
+
+    Attributes:
+        geometry: Path to .obj file or directory of .obj files (ensemble)
+        mode: ConvergenceMode instance (StandardMode or PHIPSMode)
+        convergence_targets: List of convergence target dicts
+
+        wavelength: Wavelength in microns (default: 0.532)
+        particle_refr_index_re: Real part of particle refractive index (default: 1.31)
+        particle_refr_index_im: Imaginary part of particle refractive index (default: 0.0)
+        medium_refr_index_re: Real part of medium refractive index (default: 1.0)
+        medium_refr_index_im: Imaginary part of medium refractive index (default: 0.0)
+
+        batch_size: Orientations per batch (default: 24)
+        max_orientations: Maximum orientations (default: 100,000)
+        min_batches: Minimum batches before convergence check (default: 10)
+
+        beam_tracing: BeamTracingConfig instance for beam tracing parameters
+        geometry_transform: GeometryTransformConfig instance for geometry transformations
+        advanced_config: AdvancedConfig instance for advanced optical parameters
+        seed: Random seed for reproducibility (optional)
+
+        mueller_1d: Compute 1D Mueller matrix (default: True, standard mode only)
+        output_dir: Output directory path (optional)
     """
 
     # Required fields
@@ -239,6 +354,20 @@ class ConvergenceConfig:
     max_orientations: int = 100_000
     min_batches: int = 10
 
+    # Beam tracing configuration
+    beam_tracing: BeamTracingConfig = field(default_factory=BeamTracingConfig)
+
+    # Geometry transformations
+    geometry_transform: GeometryTransformConfig = field(
+        default_factory=GeometryTransformConfig
+    )
+
+    # Advanced optics
+    advanced_config: AdvancedConfig = field(default_factory=AdvancedConfig)
+
+    # Random seed for reproducibility
+    seed: Optional[int] = None
+
     # Mueller matrix output (only for StandardMode)
     mueller_1d: bool = True
 
@@ -312,6 +441,24 @@ class ConvergenceConfig:
             "batch_size": self.batch_size,
             "max_orientations": self.max_orientations,
             "min_batches": self.min_batches,
+            "beam_tracing": {
+                "beam_power_threshold": self.beam_tracing.beam_power_threshold,
+                "beam_area_threshold_fac": self.beam_tracing.beam_area_threshold_fac,
+                "cutoff": self.beam_tracing.cutoff,
+                "max_rec": self.beam_tracing.max_rec,
+                "max_tir": self.beam_tracing.max_tir,
+            },
+            "geometry_transform": {
+                "scale": self.geometry_transform.scale,
+                "distortion": self.geometry_transform.distortion,
+                "geom_scale": self.geometry_transform.geom_scale,
+            },
+            "advanced_config": {
+                "mapping": str(self.advanced_config.mapping),
+                "coherence": self.advanced_config.coherence,
+                "fov_factor": self.advanced_config.fov_factor,
+            },
+            "seed": self.seed,
             "mueller_1d": self.mueller_1d,
             "is_ensemble": self.is_ensemble(),
         }
@@ -664,7 +811,7 @@ class UnifiedConvergence:
         else:
             geom_path_str = str(self.config.geometry)
 
-        # Create GOAD settings
+        # Create GOAD settings with all parameters
         settings = goad.Settings(
             geom_path=geom_path_str,
             wavelength=self.config.wavelength,
@@ -673,8 +820,32 @@ class UnifiedConvergence:
             medium_refr_index_re=self.config.medium_refr_index_re,
             medium_refr_index_im=self.config.medium_refr_index_im,
             binning=self.config.mode.get_binning(),
+            # Beam tracing parameters
+            beam_power_threshold=self.config.beam_tracing.beam_power_threshold,
+            beam_area_threshold_fac=self.config.beam_tracing.beam_area_threshold_fac,
+            cutoff=self.config.beam_tracing.cutoff,
+            max_rec=self.config.beam_tracing.max_rec,
+            max_tir=self.config.beam_tracing.max_tir,
+            # Geometry transformations
+            scale=self.config.geometry_transform.scale,
+            # Advanced configuration
+            mapping=self.config.advanced_config.mapping,
+            coherence=self.config.advanced_config.coherence,
         )
 
+        # Set optional parameters if provided
+        if self.config.seed is not None:
+            settings.seed = self.config.seed
+
+        if self.config.geometry_transform.distortion is not None:
+            settings.distortion = self.config.geometry_transform.distortion
+
+        if self.config.geometry_transform.geom_scale is not None:
+            settings.geom_scale = self.config.geometry_transform.geom_scale
+
+        if self.config.advanced_config.fov_factor is not None:
+            settings.fov_factor = self.config.advanced_config.fov_factor
+
         # Create convergence instance based on mode
         if isinstance(self.config.mode, StandardMode):
             self._setup_standard(settings)
@@ -881,19 +1052,46 @@ def run_convergence(
         tolerance_type: "relative" or "absolute"
         mode: ConvergenceMode instance, or string "auto"/"standard"/"phips"
         **kwargs: Additional settings:
+            # Optical settings
             - wavelength: Wavelength in microns (default: 0.532)
             - particle_refr_index_re: Real part of particle refractive index
             - particle_refr_index_im: Imaginary part of particle refractive index
             - medium_refr_index_re: Real part of medium refractive index
             - medium_refr_index_im: Imaginary part of medium refractive index
+
+            # Convergence parameters
             - batch_size: Orientations per batch (default: 24)
             - max_orientations: Maximum orientations (default: 100,000)
             - min_batches: Minimum batches before convergence (default: 10)
             - mueller_1d: Compute 1D Mueller matrix (default: True, standard mode only)
+
+            # Mode settings
             - phips_bins_file: Path to PHIPS bins TOML (required if mode="phips")
             - n_theta: Number of theta bins for standard mode (default: 181)
             - n_phi: Number of phi bins for standard mode (default: 181)
 
+            # Beam tracing parameters
+            - beam_power_threshold: Beam power threshold (default: 0.05)
+            - beam_area_threshold_fac: Beam area threshold factor (default: 4.0)
+            - cutoff: Ray power cutoff (default: 0.001)
+            - max_rec: Max recursion depth (default: 100)
+            - max_tir: Max TIR bounces (default: 100)
+
+            # Geometry transformations
+            - scale: Problem scaling factor - scales entire problem including geometry,
+                     wavelength, and beam area thresholds (default: 1.0)
+            - distortion: Geometry distortion factor (optional)
+            - geom_scale: Per-axis geometry scaling [x, y, z] - scales only geometry
+                          in each dimension independently (optional)
+
+            # Advanced configuration
+            - mapping: DSCS mapping scheme (default: goad.Mapping.ApertureDiffraction)
+            - coherence: Enable coherent scattering (default: False)
+            - fov_factor: Field of view factor (optional)
+
+            # Reproducibility
+            - seed: Random seed for orientations (optional)
+
     Returns:
         UnifiedResults object
 
@@ -924,7 +1122,44 @@ def run_convergence(
             [{"variable": "S11", "tolerance": 0.1, "theta_indices": [180]}],
             batch_size=12
         )
+
+        # Advanced: custom beam tracing and geometry scaling
+        results = run_convergence(
+            "complex_particle.obj",
+            "asymmetry",
+            max_rec=200,
+            max_tir=150,
+            cutoff=0.0001,
+            scale=2.0,
+            seed=42
+        )
     """
+    # Extract beam tracing parameters from kwargs
+    beam_tracing = BeamTracingConfig(
+        beam_power_threshold=kwargs.pop("beam_power_threshold", 0.05),
+        beam_area_threshold_fac=kwargs.pop("beam_area_threshold_fac", 4.0),
+        cutoff=kwargs.pop("cutoff", 0.001),
+        max_rec=kwargs.pop("max_rec", 100),
+        max_tir=kwargs.pop("max_tir", 100),
+    )
+
+    # Extract geometry transform parameters
+    geometry_transform = GeometryTransformConfig(
+        scale=kwargs.pop("scale", 1.0),
+        distortion=kwargs.pop("distortion", None),
+        geom_scale=kwargs.pop("geom_scale", None),
+    )
+
+    # Extract advanced configuration parameters
+    advanced_config = AdvancedConfig(
+        mapping=kwargs.pop("mapping", "ApertureDiffraction"),
+        coherence=kwargs.pop("coherence", False),
+        fov_factor=kwargs.pop("fov_factor", None),
+    )
+
+    # Extract seed
+    seed = kwargs.pop("seed", None)
+
     # Normalize targets to list of dicts
     target_dicts = _normalize_targets(targets, tolerance, tolerance_type)
 
@@ -946,9 +1181,16 @@ def run_convergence(
                 f"Invalid mode string '{mode}'. Must be 'auto', 'standard', or 'phips'"
             )
 
-    # Build config
+    # Build config with new parameters
     config = ConvergenceConfig(
-        geometry=geometry, mode=mode, convergence_targets=target_dicts, **kwargs
+        geometry=geometry,
+        mode=mode,
+        convergence_targets=target_dicts,
+        beam_tracing=beam_tracing,
+        geometry_transform=geometry_transform,
+        advanced_config=advanced_config,
+        seed=seed,
+        **kwargs,  # Remaining kwargs (wavelength, particle_refr_index_re, etc.)
     )
 
     # Run

{goad_py-0.5.6 → goad_py-0.6.1}/goad-py/src/lib.rs

@@ -1,6 +1,7 @@
 use goad::{
     self,
     bins::BinningScheme,
+    diff::Mapping,
     geom::Geom,
     geom::Shape,
     multiproblem::MultiProblem,
@@ -75,6 +76,9 @@ fn _goad_py(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<Orientation>()?;
     m.add_class::<Scheme>()?;
 
+    // Mapping enum
+    m.add_class::<Mapping>()?;
+
     // Helper functions for orientations
     m.add_function(wrap_pyfunction!(uniform_orientation, m)?)?;
     m.add_function(wrap_pyfunction!(discrete_orientation, m)?)?;

{goad_py-0.5.6 → goad_py-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "goad-py"
-version = "0.5.6"
+version = "0.6.1"
 description = "Physical optics light scattering computation"
 authors = [{name = "Harry Ballington", email = "ballington@uni-wuppertal.de"}]
 license = {text = "GPL-3.0"}