goad-py 1.1.2__cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl

goad/__init__.py

@@ -0,0 +1 @@
+from ._goad import *

goad/_goad.pyi

@@ -0,0 +1,707 @@
+# This file is automatically generated by pyo3_stub_gen
+# ruff: noqa: E501, F401
+
+import builtins
+import enum
+import numpy
+import numpy.typing
+import typing
+
+@typing.final
+class BinningScheme:
+    r"""
+    Angular binning scheme for scattering calculations.
+    
+    Defines how to discretize the scattering sphere into angular bins
+    for Mueller matrix and amplitude computations. Supports simple
+    regular grids, custom intervals, and arbitrary bin arrangements.
+    """
+    def __new__(cls, bins: typing.Sequence[typing.Sequence[typing.Sequence[builtins.float]]]) -> BinningScheme: ...
+    @staticmethod
+    def simple(num_theta: builtins.int, num_phi: builtins.int) -> BinningScheme:
+        r"""
+        Create a simple binning scheme with uniform theta and phi spacing
+        """
+    @staticmethod
+    def interval(thetas: typing.Sequence[builtins.float], theta_spacings: typing.Sequence[builtins.float], phis: typing.Sequence[builtins.float], phi_spacings: typing.Sequence[builtins.float]) -> BinningScheme:
+        r"""
+        Create an interval binning scheme with variable spacing
+        """
+    @staticmethod
+    def custom(bins: typing.Sequence[typing.Sequence[typing.Sequence[builtins.float]]]) -> BinningScheme:
+        r"""
+        Create a custom binning scheme with explicit bin edges
+        Each bin is specified as [[theta_min, theta_max], [phi_min, phi_max]]
+        """
+    def thetas(self) -> builtins.list[builtins.float]:
+        r"""
+        Returns a list of all theta bin centre values
+        """
+    def phis(self) -> builtins.list[builtins.float]:
+        r"""
+        Returns a list of all phi bin centre values
+        """
+    def bins(self) -> numpy.typing.NDArray[numpy.float32]:
+        r"""
+        Returns all 2D bins as a numpy array of shape (n_bins, 2) with columns [theta, phi]
+        """
+    def bins_1d(self) -> numpy.typing.NDArray[numpy.float32]:
+        r"""
+        Returns unique 1D theta bins as a numpy array
+        """
+    def num_bins(self) -> builtins.int:
+        r"""
+        Returns the number of bins
+        """
+
+@typing.final
+class Convergence:
+    @property
+    def mean(self) -> Results:
+        r"""
+        Access the current mean results (live during solve).
+        """
+    @property
+    def sem(self) -> Results:
+        r"""
+        Access the current standard error of the mean (live during solve).
+        """
+    @property
+    def count(self) -> builtins.int:
+        r"""
+        Get the max orientations (safety cap).
+        """
+    @property
+    def max_orientations(self) -> builtins.int: ...
+    @max_orientations.setter
+    def max_orientations(self, value: builtins.int) -> None:
+        r"""
+        Set the max orientations (safety cap).
+        """
+    def __new__(cls, settings: Settings, geoms: typing.Optional[typing.Sequence[Geom]] = None) -> Convergence: ...
+    def solve(self) -> None:
+        r"""
+        Solve the multi-orientation scattering problem using work-stealing.
+        Periodically checks for Python signals (Ctrl-C) and interrupts if needed.
+        """
+    def add_target(self, param: Param, relative_error: builtins.float) -> None:
+        r"""
+        Add a convergence target for a parameter (Python API).
+        Solver terminates when ALL targets are satisfied.
+        """
+    def clear_targets(self) -> None:
+        r"""
+        Clear all convergence targets (Python API).
+        """
+    def py_reset(self) -> None:
+        r"""
+        Reset the solver to initial state.
+        """
+    def py_reset_sampler(self) -> None:
+        r"""
+        Reset the orientation sampler (for reproducibility).
+        """
+    def save(self, directory: typing.Optional[builtins.str] = None) -> None:
+        r"""
+        Save simulation results to disk.
+        
+        Writes Mueller matrices, parameters, and other output files to the
+        specified directory (or the directory configured in settings).
+        
+        Args:
+            directory: Optional output directory path. If not provided, uses
+                       the directory from settings.
+        """
+
+@typing.final
+class Euler:
+    @property
+    def alpha(self) -> builtins.float: ...
+    @alpha.setter
+    def alpha(self, value: builtins.float) -> None: ...
+    @property
+    def beta(self) -> builtins.float: ...
+    @beta.setter
+    def beta(self, value: builtins.float) -> None: ...
+    @property
+    def gamma(self) -> builtins.float: ...
+    @gamma.setter
+    def gamma(self, value: builtins.float) -> None: ...
+    def __new__(cls, alpha: builtins.float, beta: builtins.float, gamma: builtins.float) -> Euler: ...
+    def __repr__(self) -> builtins.str: ...
+
+@typing.final
+class Geom:
+    @property
+    def first_shape_vertices(self) -> builtins.list[tuple[builtins.float, builtins.float, builtins.float]]:
+        r"""
+        Getter for the vertices of the first shape
+        """
+    def __new__(cls, shapes: typing.Sequence[Shape]) -> Geom: ...
+    @staticmethod
+    def from_file(filename: builtins.str) -> builtins.list[Geom]: ...
+
+@typing.final
+class MultiProblem:
+    r"""
+    Multi-orientation light scattering simulation for a single geometry.
+    
+    Computes orientation-averaged scattering properties by running multiple
+    single-orientation simulations and averaging the results. Supports both
+    random and systematic orientation sampling schemes. Results include
+    Mueller matrices, cross-sections, and derived optical parameters.
+    
+    # Examples
+    ```python
+    import goad_py as goad
+    
+    # Create orientation scheme and settings
+    orientations = goad.create_uniform_orientation(100)
+    settings = goad.Settings("particle.obj", orientation=orientations)
+    
+    # Run multi-orientation simulation
+    mp = goad.MultiProblem(settings)
+    mp.py_solve()
+    
+    # Access averaged results
+    results = mp.results
+    print(f"Scattering cross-section: {results.scat_cross}")
+    ```
+    """
+    @property
+    def results(self) -> Results:
+        r"""
+        Access the orientation-averaged simulation results.
+        
+        Returns the complete Results object containing Mueller matrices,
+        amplitude matrices, power distributions, and derived parameters
+        averaged over all orientations.
+        
+        # Returns
+        Results - Complete scattering simulation results
+        """
+    @property
+    def num_orientations(self) -> builtins.int:
+        r"""
+        Get the number of orientations
+        """
+    def __new__(cls, settings: Settings, geoms: typing.Optional[typing.Sequence[Geom]] = None) -> MultiProblem: ...
+    def solve(self) -> None:
+        r"""
+        Solve the multi-orientation scattering problem.
+        
+        Computes scattering properties averaged over all orientations using
+        parallel processing. The Global Interpreter Lock (GIL) is released
+        during computation to allow concurrent Python operations.
+        
+        # Returns
+        PyResult<()> - Success or error if computation fails
+        """
+    def save(self, directory: typing.Optional[builtins.str] = None) -> None:
+        r"""
+        Save simulation results to disk.
+        
+        Writes Mueller matrices, parameters, and other output files to the
+        specified directory (or the directory configured in settings).
+        
+        Args:
+            directory: Optional output directory path. If not provided, uses
+                       the directory from settings.
+        """
+    def py_reset(self) -> None:
+        r"""
+        Reset the multiproblem to initial state
+        """
+    def py_regenerate_orientations(self) -> None:
+        r"""
+        Regenerate orientations (useful for random schemes)
+        """
+
+@typing.final
+class Orientation:
+    @property
+    def scheme(self) -> Scheme: ...
+    @scheme.setter
+    def scheme(self, value: Scheme) -> None: ...
+    @property
+    def euler_convention(self) -> EulerConvention: ...
+    @euler_convention.setter
+    def euler_convention(self, value: EulerConvention) -> None: ...
+    @staticmethod
+    def uniform(num_orients: builtins.int, euler_convention: typing.Optional[EulerConvention] = None) -> Orientation: ...
+    @staticmethod
+    def discrete(eulers: typing.Sequence[Euler], euler_convention: typing.Optional[EulerConvention] = None) -> Orientation: ...
+    def __repr__(self) -> builtins.str: ...
+
+@typing.final
+class Problem:
+    r"""
+    A solvable physics problem.
+    """
+    @property
+    def settings(self) -> Settings:
+        r"""
+        Getter function for the problem settings
+        """
+    @settings.setter
+    def settings(self, value: Settings) -> None:
+        r"""
+        Setter function for the problem settings
+        """
+    @property
+    def geom(self) -> Geom:
+        r"""
+        Getter function for the geometry
+        """
+    @property
+    def results(self) -> Results:
+        r"""
+        Get the results object
+        """
+    def __new__(cls, settings: typing.Optional[Settings] = None, geom: typing.Optional[Geom] = None) -> Problem: ...
+    def py_solve(self) -> None: ...
+    def py_print_stats(self) -> None: ...
+
+@typing.final
+class Results:
+    r"""
+    Complete results from a GOAD light scattering simulation.
+    
+    Contains all computed scattering data including Mueller matrices,
+    amplitude matrices, power distributions, and derived parameters.
+    Supports both 2D angular distributions and 1D integrated results.
+    """
+    ...
+
+@typing.final
+class Settings:
+    r"""
+    Runtime configuration for the application.
+    """
+    @property
+    def eulers(self) -> builtins.list[builtins.float]:
+        r"""
+        Get the euler angle, assuming the orientation scheme is discrete
+        """
+    @eulers.setter
+    def eulers(self, value: builtins.list[builtins.float]) -> None:
+        r"""
+        Set the euler angles
+        """
+    @property
+    def orientation(self) -> Orientation:
+        r"""
+        Get the full orientation object
+        """
+    @orientation.setter
+    def orientation(self, value: Orientation) -> None:
+        r"""
+        Set the full orientation object
+        """
+    @property
+    def geom_path(self) -> builtins.str:
+        r"""
+        Get the geometry file path
+        """
+    @geom_path.setter
+    def geom_path(self, value: builtins.str) -> None:
+        r"""
+        Set the geometry file path
+        """
+    @property
+    def wavelength(self) -> builtins.float:
+        r"""
+        Get the wavelength
+        """
+    @wavelength.setter
+    def wavelength(self, value: builtins.float) -> None:
+        r"""
+        Set the wavelength
+        """
+    @property
+    def particle_refr_index_re(self) -> builtins.float:
+        r"""
+        Get the particle refractive index (real part)
+        """
+    @particle_refr_index_re.setter
+    def particle_refr_index_re(self, value: builtins.float) -> None:
+        r"""
+        Set the particle refractive index (real part)
+        """
+    @property
+    def particle_refr_index_im(self) -> builtins.float:
+        r"""
+        Get the particle refractive index (imaginary part)
+        """
+    @particle_refr_index_im.setter
+    def particle_refr_index_im(self, value: builtins.float) -> None:
+        r"""
+        Set the particle refractive index (imaginary part)
+        """
+    @property
+    def medium_refr_index_re(self) -> builtins.float:
+        r"""
+        Get the medium refractive index (real part)
+        """
+    @medium_refr_index_re.setter
+    def medium_refr_index_re(self, value: builtins.float) -> None:
+        r"""
+        Set the medium refractive index (real part)
+        """
+    @property
+    def medium_refr_index_im(self) -> builtins.float:
+        r"""
+        Get the medium refractive index (imaginary part)
+        """
+    @medium_refr_index_im.setter
+    def medium_refr_index_im(self, value: builtins.float) -> None:
+        r"""
+        Set the medium refractive index (imaginary part)
+        """
+    @property
+    def beam_power_threshold(self) -> builtins.float:
+        r"""
+        Get the beam power threshold
+        """
+    @beam_power_threshold.setter
+    def beam_power_threshold(self, value: builtins.float) -> None:
+        r"""
+        Set the beam power threshold
+        """
+    @property
+    def cutoff(self) -> builtins.float:
+        r"""
+        Get the cutoff
+        """
+    @cutoff.setter
+    def cutoff(self, value: builtins.float) -> None:
+        r"""
+        Set the cutoff
+        """
+    @property
+    def max_rec(self) -> builtins.int:
+        r"""
+        Get the max recursion depth
+        """
+    @max_rec.setter
+    def max_rec(self, value: builtins.int) -> None:
+        r"""
+        Set the max recursion depth
+        """
+    @property
+    def max_tir(self) -> builtins.int:
+        r"""
+        Get the max TIR bounces
+        """
+    @max_tir.setter
+    def max_tir(self, value: builtins.int) -> None:
+        r"""
+        Set the max TIR bounces
+        """
+    @property
+    def zones(self) -> builtins.list[ZoneConfig]:
+        r"""
+        Get the zones configuration
+        """
+    @zones.setter
+    def zones(self, value: builtins.list[ZoneConfig]) -> None:
+        r"""
+        Set the zones configuration
+        """
+    @property
+    def geom_scale(self) -> typing.Optional[builtins.list[builtins.float]]:
+        r"""
+        Get the per-axis geometry scaling [x, y, z]
+        """
+    @geom_scale.setter
+    def geom_scale(self, value: typing.Optional[builtins.list[builtins.float]]) -> None:
+        r"""
+        Set the per-axis geometry scaling [x, y, z]
+        """
+    @property
+    def seed(self) -> typing.Optional[builtins.int]:
+        r"""
+        Get the seed for random number generation
+        """
+    @seed.setter
+    def seed(self, value: typing.Optional[builtins.int]) -> None:
+        r"""
+        Set the seed for random number generation
+        """
+    @property
+    def distortion(self) -> typing.Optional[builtins.float]:
+        r"""
+        Get the distortion factor
+        """
+    @distortion.setter
+    def distortion(self, value: typing.Optional[builtins.float]) -> None:
+        r"""
+        Set the distortion factor
+        """
+    @property
+    def fov_factor(self) -> typing.Optional[builtins.float]:
+        r"""
+        Get the field of view factor
+        """
+    @fov_factor.setter
+    def fov_factor(self, value: typing.Optional[builtins.float]) -> None:
+        r"""
+        Set the field of view factor
+        """
+    @property
+    def quiet(self) -> builtins.bool:
+        r"""
+        Get quiet mode
+        """
+    @quiet.setter
+    def quiet(self, value: builtins.bool) -> None:
+        r"""
+        Set quiet mode (suppress progress bars)
+        """
+    def __new__(cls, geom_path: builtins.str, wavelength: builtins.float = 0.5320000052452087, particle_refr_index_re: builtins.float = 1.309999942779541, particle_refr_index_im: builtins.float = 0.0, medium_refr_index_re: builtins.float = 1.0, medium_refr_index_im: builtins.float = 0.0, orientation: typing.Optional[Orientation] = None, zones: typing.Optional[typing.Sequence[ZoneConfig]] = None, beam_power_threshold: builtins.float = 0.004999999888241291, beam_area_threshold_fac: builtins.float = 0.10000000149011612, cutoff: builtins.float = 0.9900000095367432, max_rec: builtins.int = 10, max_tir: builtins.int = 10, scale: builtins.float = 1.0, distortion: typing.Optional[builtins.float] = None, directory: builtins.str = 'goad_run', mapping: Mapping = ..., coherence: builtins.bool = True, quiet: builtins.bool = False, seed: typing.Optional[builtins.int] = None) -> Settings: ...
+
+@typing.final
+class Shape:
+    r"""
+    Represents a 3D surface mesh.
+    """
+    def __new__(cls, vertices: typing.Sequence[tuple[builtins.float, builtins.float, builtins.float]], face_indices: typing.Sequence[typing.Sequence[builtins.int]], id: builtins.int, refr_index_re: builtins.float, refr_index_im: builtins.float) -> Shape: ...
+
+@typing.final
+class Zone:
+    r"""
+    A zone represents a region of the scattering sphere with its own binning,
+    results, and computed parameters.
+    """
+    @property
+    def label(self) -> typing.Optional[builtins.str]:
+        r"""
+        Get the zone label
+        """
+    @property
+    def zone_type(self) -> ZoneType:
+        r"""
+        Get the zone type
+        """
+    @property
+    def name(self) -> builtins.str:
+        r"""
+        Get the display name for this zone
+        """
+    @property
+    def num_bins(self) -> builtins.int:
+        r"""
+        Get the number of bins in this zone
+        """
+    @property
+    def bins(self) -> numpy.typing.NDArray[numpy.float32]:
+        r"""
+        Get the bins as a numpy array of shape (n_bins, 2) with columns [theta, phi]
+        """
+    @property
+    def mueller(self) -> numpy.typing.NDArray[numpy.float32]:
+        r"""
+        Get the Mueller matrix as a numpy array of shape (n_bins, 16)
+        """
+    @property
+    def mueller_1d(self) -> typing.Optional[numpy.typing.NDArray[numpy.float32]]:
+        r"""
+        Get the 1D Mueller matrix as a numpy array (if available)
+        """
+    @property
+    def bins_1d(self) -> typing.Optional[numpy.typing.NDArray[numpy.float32]]:
+        r"""
+        Get the 1D theta bins as a numpy array (if available)
+        """
+    @property
+    def params(self) -> typing.Any:
+        r"""
+        Get zone-specific parameters as a dict
+        """
+    def __repr__(self) -> builtins.str: ...
+
+@typing.final
+class ZoneConfig:
+    r"""
+    Configuration for a zone, as specified in TOML or via CLI.
+    """
+    @property
+    def label(self) -> typing.Optional[builtins.str]:
+        r"""
+        Get the zone label
+        """
+    @label.setter
+    def label(self, value: typing.Optional[builtins.str]) -> None:
+        r"""
+        Set the zone label
+        """
+    @property
+    def binning(self) -> BinningScheme:
+        r"""
+        Get the binning scheme
+        """
+    @binning.setter
+    def binning(self, value: BinningScheme) -> None:
+        r"""
+        Set the binning scheme
+        """
+    def __new__(cls, binning: BinningScheme, label: typing.Optional[builtins.str] = None) -> ZoneConfig:
+        r"""
+        Create a new zone configuration.
+        
+        Args:
+            binning: The binning scheme for this zone
+            label: Optional label for the zone
+        """
+    def __repr__(self) -> builtins.str: ...
+
+@typing.final
+class Zones:
+    r"""
+    A collection of zones for a simulation.
+    """
+    @property
+    def full(self) -> typing.Optional[Zone]:
+        r"""
+        Get the full zone (convenience method)
+        """
+    @property
+    def forward(self) -> typing.Optional[Zone]:
+        r"""
+        Get the forward zone (convenience method)
+        """
+    @property
+    def backward(self) -> typing.Optional[Zone]:
+        r"""
+        Get the backward zone (convenience method)
+        """
+    @property
+    def all_zones(self) -> builtins.list[Zone]:
+        r"""
+        Get all zones as a list
+        """
+    def __len__(self) -> builtins.int:
+        r"""
+        Get the number of zones
+        """
+    def __getitem__(self, index: builtins.int) -> Zone:
+        r"""
+        Get a zone by index
+        """
+    def get(self, label: builtins.str) -> typing.Optional[Zone]:
+        r"""
+        Get a zone by label
+        """
+    def get_by_type(self, zone_type: ZoneType) -> typing.Optional[Zone]:
+        r"""
+        Get a zone by type (returns first matching zone)
+        """
+    def __repr__(self) -> builtins.str: ...
+    def __iter__(self) -> ZonesIterator: ...
+
+@typing.final
+class ZonesIterator:
+    r"""
+    Iterator for Zones in Python
+    """
+    def __iter__(self) -> ZonesIterator: ...
+    def __next__(self) -> typing.Optional[Zone]: ...
+
+@typing.final
+class EulerConvention(enum.Enum):
+    r"""
+    Euler angle order for the discrete orientation scheme.
+    """
+    XZX = ...
+    XYX = ...
+    YXY = ...
+    YZY = ...
+    ZYZ = ...
+    ZXZ = ...
+    XZY = ...
+    XYZ = ...
+    YXZ = ...
+    YZX = ...
+    ZYX = ...
+    ZXY = ...
+
+@typing.final
+class Mapping(enum.Enum):
+    r"""
+    Enum representing different mapping methods from near to far field.
+    """
+    GeometricOptics = ...
+    ApertureDiffraction = ...
+
+@typing.final
+class Param(enum.Enum):
+    Asymmetry = ...
+    Albedo = ...
+    ScatCross = ...
+    ExtCross = ...
+    BackscatterCross = ...
+    LidarRatio = ...
+    DepolarizationRatio = ...
+    BackscatterS11S22 = ...
+    ExtCrossOpticalTheorem = ...
+
+@typing.final
+class Scheme(enum.Enum):
+    Uniform = ...
+    r"""
+    Solve the problem by averaging over a uniform distribution of angles.
+    Example: `uniform 100`
+    """
+    Discrete = ...
+    r"""
+    Solve the problem by averaging over a discrete set of angles (in degrees).
+    Example: `discrete 0,0,0 20,30,40`
+    """
+
+@typing.final
+class ZoneType(enum.Enum):
+    r"""
+    The type of zone, which determines what parameters can be computed.
+    """
+    Full = ...
+    r"""
+    Full 0-180 degree theta coverage. Computes: asymmetry, scattering cross-section.
+    """
+    Forward = ...
+    r"""
+    Forward scattering zone. Computes: extinction cross-section (optical theorem).
+    """
+    Backward = ...
+    r"""
+    Backscatter zone. Computes: lidar ratio, backscatter cross-section.
+    """
+    Custom = ...
+    r"""
+    Custom angular range. Parameters depend on coverage.
+    """
+
+def create_discrete_orientation(eulers: typing.Sequence[Euler], euler_convention: typing.Optional[EulerConvention] = None) -> Orientation:
+    r"""
+    Create an Orientation with discrete scheme and default convention
+    """
+
+def create_uniform_orientation(num_orients: builtins.int, euler_convention: typing.Optional[EulerConvention] = None) -> Orientation:
+    r"""
+    Create an Orientation with uniform scheme and default convention
+    """
+
+def discrete_orientation(eulers: typing.Sequence[Euler]) -> Scheme:
+    r"""
+    Create a discrete orientation scheme from a list of Euler angles
+    """
+
+def sum_as_string(a: builtins.int, b: builtins.int) -> builtins.str:
+    r"""
+    Formats the sum of two numbers as string.
+    """
+
+def uniform_orientation(num_orients: builtins.int) -> Scheme:
+    r"""
+    Create a uniform orientation scheme with specified number of orientations
+    """
+