goad-py 0.5.1__tar.gz → 0.5.5__tar.gz

{goad_py-0.5.1 → goad_py-0.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: goad-py
-Version: 0.5.1
+Version: 0.5.5
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering :: Physics
@@ -15,6 +15,8 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Operating System :: OS Independent
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: toml>=0.10.0
 Summary: Physical optics light scattering computation
 Keywords: light-scattering,optics,simulation,scientific-computing,physics
 Home-Page: https://github.com/hballington12/goad

{goad_py-0.5.1 → goad_py-0.5.5}/config/default.toml

@@ -50,22 +50,14 @@ theta_spacings =[2]
 phis = [0, 360]
 phi_spacings = [4]
 
-# [binning.scheme.Custom] # Custom binning with specified [theta,phi] angular bins
+# [binning.scheme.Custom] # Custom binning with specified bin edges [[theta_min, theta_max], [phi_min, phi_max]]
 # bins = [
-#     [
-#         0,
-#         0,
-#     ],
-#     [
-#         0,
-#         40,
-#     ],
-#     [
-#         20,
-#         180,
-#     ],
-# ] # custom bins, unless a file is specified below
-# file = "phips_bins.toml" # File containing custom bins, relative to working directory
+#     [[0.0, 10.0], [0.0, 90.0]],      # First bin: theta 0-10°, phi 0-90°
+#     [[0.0, 10.0], [90.0, 180.0]],    # Second bin: theta 0-10°, phi 90-180°
+#     [[10.0, 20.0], [0.0, 90.0]],     # Third bin: theta 10-20°, phi 0-90°
+#     [[10.0, 20.0], [90.0, 180.0]],   # Fourth bin: theta 10-20°, phi 90-180°
+# ]
+# file = "phips_bins_edges.toml" # Or load bins from external file (relative to working directory)
 
 
 [orientation] # Orientation configuration

goad_py-0.5.5/goad-py/UNIFIED_API.md

@@ -0,0 +1,307 @@
+# Unified Convergence API
+
+A single, consistent interface for all GOAD convergence studies.
+
+## Overview
+
+The unified convergence API provides a single entry point for running convergence studies with GOAD, supporting:
+
+- **Standard mode**: Integrated scattering parameters (asymmetry, scattering/extinction cross-sections, albedo) and Mueller matrix elements (S11-S44)
+- **PHIPS mode**: Custom detector DSCS values at 20 PHIPS detectors
+- **Single geometry** or **ensemble averaging** (multiple geometries)
+- **Parameter sweeps** for sensitivity studies
+- **JSON serialization** for saving/loading results
+
+## Quick Start
+
+### Simple Example
+
+```python
+import goad_py as goad
+
+# Run convergence on asymmetry parameter
+results = goad.run_convergence(
+    geometry="hex.obj",
+    targets="asymmetry",
+    tolerance=0.01,  # 1% relative tolerance
+)
+
+print(results.summary())
+results.save("results.json")
+```
+
+### Multiple Targets
+
+```python
+results = goad.run_convergence(
+    geometry="hex.obj",
+    targets=["asymmetry", "scatt", "ext"],
+    tolerance=0.05,  # 5% relative tolerance
+    batch_size=24,
+)
+```
+
+### Mueller Matrix Elements
+
+```python
+# Converge all theta bins
+results = goad.run_convergence(
+    geometry="hex.obj",
+    targets="S11",
+    tolerance=0.25,
+)
+
+# Or converge specific bins only (e.g., backscattering)
+results = goad.run_convergence(
+    geometry="hex.obj",
+    targets=[{
+        "variable": "S11",
+        "tolerance": 0.10,
+        "theta_indices": [180]  # Only backscattering
+    }],
+)
+```
+
+### Ensemble Convergence
+
+```python
+# Pass a directory instead of a file
+results = goad.run_convergence(
+    geometry="./geometries/",  # Directory with .obj files
+    targets=["asymmetry", "scatt"],
+    tolerance=0.05,
+)
+```
+
+### PHIPS Detector Convergence
+
+```python
+results = goad.run_convergence(
+    geometry="hex.obj",
+    targets="phips_dscs",
+    tolerance=0.25,
+    mode="phips",
+    phips_bins_file="phips_bins_edges.toml",
+)
+```
+
+## Advanced Usage
+
+### Using ConvergenceConfig
+
+For full control over all parameters:
+
+```python
+from goad_py import ConvergenceConfig, StandardMode, UnifiedConvergence
+
+config = ConvergenceConfig(
+    geometry="hex.obj",
+    mode=StandardMode(n_theta=181, n_phi=181),
+    convergence_targets=[
+        {"variable": "asymmetry", "tolerance": 0.005, "tolerance_type": "absolute"},
+        {"variable": "scatt", "tolerance": 0.01, "tolerance_type": "relative"},
+    ],
+    wavelength=0.633,  # Red laser
+    particle_refr_index_re=1.5,
+    particle_refr_index_im=0.01,
+    batch_size=24,
+    max_orientations=10_000,
+    min_batches=10,
+    mueller_1d=True,
+)
+
+conv = UnifiedConvergence(config)
+results = conv.run()
+```
+
+### Parameter Sweeps
+
+```python
+from goad_py import ConvergenceConfig, StandardMode, run_convergence_sweep
+
+# Wavelength sweep
+wavelengths = [0.532, 0.633, 0.780]
+configs = [
+    ConvergenceConfig(
+        geometry="hex.obj",
+        mode=StandardMode(),
+        convergence_targets=[{"variable": "asymmetry", "tolerance": 0.05}],
+        wavelength=wl,
+    )
+    for wl in wavelengths
+]
+
+results_list = run_convergence_sweep(configs)
+
+for wl, result in zip(wavelengths, results_list):
+    print(f"λ={wl}: asymmetry = {result.values['asymmetry']:.6f}")
+```
+
+## API Reference
+
+### Functions
+
+#### `run_convergence(geometry, targets, tolerance=0.05, tolerance_type="relative", mode="auto", **kwargs)`
+
+Main entry point for convergence studies.
+
+**Parameters:**
+- `geometry` (str|Path): Path to .obj file or directory
+- `targets` (str|list): What to converge on (e.g., "asymmetry", ["asymmetry", "scatt"], or list of dicts)
+- `tolerance` (float): Default tolerance for convergence
+- `tolerance_type` (str): "relative" or "absolute"
+- `mode` (str|ConvergenceMode): "auto", "standard", "phips", or a ConvergenceMode instance
+- `**kwargs`: Additional settings (wavelength, batch_size, etc.)
+
+**Returns:** `UnifiedResults`
+
+#### `run_convergence_sweep(configs, parallel=False)`
+
+Run multiple convergence studies for parameter sweeps.
+
+**Parameters:**
+- `configs` (List[ConvergenceConfig]): List of configurations
+- `parallel` (bool): Run in parallel (not yet implemented)
+
+**Returns:** `List[UnifiedResults]`
+
+### Classes
+
+#### `StandardMode(n_theta=181, n_phi=181)`
+
+Standard convergence mode for integrated parameters and Mueller elements.
+
+**Valid targets:**
+- Scalar: `asymmetry`, `scatt`, `ext`, `albedo`
+- Mueller: `S11`, `S12`, ..., `S44`
+- Mueller with specific bins: `{"variable": "S11", "theta_indices": [0, 180]}`
+
+#### `PHIPSMode(bins_file)`
+
+PHIPS detector convergence mode.
+
+**Parameters:**
+- `bins_file` (str): Path to PHIPS bins TOML file
+
+**Valid targets:**
+- Only supports a single target with tolerance specification
+- Optionally specify `detector_indices` to converge specific detectors
+
+#### `ConvergenceConfig`
+
+Full configuration for convergence studies.
+
+**Required fields:**
+- `geometry` (str|Path): Geometry file or directory
+- `mode` (ConvergenceMode): StandardMode or PHIPSMode
+- `convergence_targets` (List[dict]): List of target specifications
+
+**Optional fields:**
+- `wavelength` (float): Default 0.532 μm
+- `particle_refr_index_re/im` (float): Refractive index (default: 1.31+0j)
+- `medium_refr_index_re/im` (float): Medium refractive index (default: 1.0+0j)
+- `batch_size` (int): Orientations per batch (default: 24)
+- `max_orientations` (int): Maximum orientations (default: 100,000)
+- `min_batches` (int): Minimum batches before convergence (default: 10)
+- `mueller_1d` (bool): Compute 1D Mueller matrix (default: True, standard mode only)
+- `mueller_2d` (bool): Compute 2D Mueller matrix (default: False, standard mode only)
+
+#### `UnifiedResults`
+
+Results container with uniform interface.
+
+**Attributes:**
+- `converged` (bool): Whether convergence criteria were met
+- `n_orientations` (int): Total orientations run
+- `mode` (str): "standard" or "phips"
+- `is_ensemble` (bool): Whether ensemble averaging was used
+- `values` (dict): Final mean values
+- `sem_values` (dict): Final SEM values
+- `mueller_1d` (ndarray): 1D Mueller matrix (if computed)
+- `mueller_2d` (ndarray): 2D Mueller matrix (if computed)
+- `convergence_history` (list): Convergence progress
+- `warning` (str): Warning message (if any)
+
+**Methods:**
+- `summary()`: Generate human-readable summary
+- `save(path)`: Save to JSON file
+- `load(path)`: Load from JSON file (class method)
+- `to_dict()`: Convert to dictionary
+
+## Validation
+
+The API performs comprehensive input validation:
+
+### Mode-Specific Validation
+
+**StandardMode:**
+- Rejects invalid variable names
+- Rejects `theta_indices` on non-Mueller variables
+- Validates theta_indices are within range
+
+**PHIPSMode:**
+- Requires valid PHIPS bins TOML file
+- Only allows a single convergence target
+- Rejects `mueller_1d` and `mueller_2d` options (not compatible with custom binning)
+
+### Config Validation
+
+- Geometry path must exist
+- `mode` must be a ConvergenceMode instance
+- `convergence_targets` cannot be empty
+- Numeric parameters must be positive
+- Mode-specific targets are validated
+
+**The API throws errors immediately rather than failing silently.**
+
+## Examples
+
+See `unified_convergence_example.py` for comprehensive examples covering:
+
+1. Simple convergence on single parameter
+2. Multiple convergence targets
+3. Mueller matrix element convergence
+4. Backscatter convergence (specific theta bins)
+5. Ensemble convergence
+6. PHIPS detector convergence
+7. PHIPS ensemble convergence
+8. Advanced usage with ConvergenceConfig
+9. Parameter sweeps
+10. Save/load results
+
+## Migration from Legacy API
+
+The legacy convergence classes (`Convergence`, `EnsembleConvergence`, `PHIPSConvergence`, etc.) are still available, but the unified API is recommended for new code.
+
+### Before (Legacy):
+```python
+from goad_py import Convergence, Convergable
+
+convergables = [
+    Convergable('asymmetry', 'relative', 0.01),
+    Convergable('scatt', 'relative', 0.05),
+]
+conv = Convergence(settings, convergables, batch_size=24)
+results = conv.run()
+```
+
+### After (Unified):
+```python
+from goad_py import run_convergence
+
+results = run_convergence(
+    geometry="hex.obj",
+    targets=[
+        {"variable": "asymmetry", "tolerance": 0.01},
+        {"variable": "scatt", "tolerance": 0.05},
+    ],
+    batch_size=24,
+)
+```
+
+## Future Work
+
+- Parallel execution for parameter sweeps
+- Additional output formats (HDF5, NetCDF)
+- Plotting utilities integrated into UnifiedResults
+- Progress callbacks for long-running convergences

goad_py-0.5.5/goad-py/UNIFIED_API_SUMMARY.md

@@ -0,0 +1,224 @@
+# Unified Convergence API - Implementation Summary
+
+## What We Built
+
+A unified, single-entry-point API for all GOAD convergence studies with:
+
+✅ **Strict validation** - Errors are thrown immediately for invalid inputs
+✅ **Mode-based architecture** - StandardMode and PHIPSMode with specific validation rules
+✅ **Uniform output** - UnifiedResults with JSON serialization
+✅ **Auto-detection** - Automatically selects appropriate mode based on targets
+✅ **Single or ensemble** - Automatically handles file vs directory geometry input
+✅ **Parameter sweeps** - Built-in support for running multiple configurations
+✅ **Backward compatible** - Legacy API still available
+
+## Files Created
+
+1. **`python/goad_py/unified_convergence.py`** (~850 lines)
+   - `ConvergenceMode` abstract base class
+   - `StandardMode` - for integrated parameters and Mueller elements
+   - `PHIPSMode` - for PHIPS detector DSCS
+   - `ConvergenceConfig` - validated configuration dataclass
+   - `UnifiedResults` - results container with JSON save/load
+   - `UnifiedConvergence` - main convergence runner
+   - `run_convergence()` - primary entry point
+   - `run_convergence_sweep()` - parameter sweep support
+
+2. **`python/goad_py/__init__.py`** - Updated exports
+
+3. **`unified_convergence_example.py`** - Comprehensive examples
+
+4. **`test_unified_validation.py`** - Validation tests (all passing ✓)
+
+5. **`test_unified_quick.py`** - End-to-end tests (all passing ✓)
+
+6. **`UNIFIED_API.md`** - Complete documentation
+
+## Key Design Decisions
+
+### 1. Mode Classes Enforce Validation
+
+```python
+class StandardMode:
+    VALID_SCALAR_TARGETS = {"asymmetry", "scatt", "ext", "albedo"}
+    VALID_MUELLER_TARGETS = {"S11", "S12", ..., "S44"}
+    
+class PHIPSMode:
+    def __init__(self, bins_file: str):
+        # Validates bins file exists and is valid TOML
+        # Loads custom bins for later use
+```
+
+**Rationale:** Each mode knows what's valid for itself. StandardMode can't be used with PHIPS bins, and PHIPSMode can't compute integrated parameters.
+
+### 2. ConvergenceConfig Validates in __post_init__
+
+```python
+@dataclass
+class ConvergenceConfig:
+    def __post_init__(self):
+        # Validate geometry exists
+        # Validate mode is correct type
+        # Let mode validate its targets
+        # Validate numeric parameters > 0
+        # Check mode-specific constraints
+```
+
+**Rationale:** Fail fast with clear error messages rather than mysterious failures during convergence.
+
+### 3. Single Entry Point with Smart Defaults
+
+```python
+run_convergence(
+    geometry="hex.obj",
+    targets="asymmetry",  # Can be string, list of strings, or list of dicts
+    tolerance=0.05,       # Applied to all unless overridden
+    mode="auto",          # Auto-detect from targets
+)
+```
+
+**Rationale:** Easy for simple cases, but can scale to complex configurations.
+
+### 4. Uniform Results Format
+
+```python
+@dataclass
+class UnifiedResults:
+    converged: bool
+    n_orientations: int
+    mode: str
+    is_ensemble: bool
+    values: Dict[str, Union[float, np.ndarray]]
+    sem_values: Dict[str, Union[float, np.ndarray]]
+    # ... plus save/load/summary methods
+```
+
+**Rationale:** Same interface regardless of mode, making parameter sweeps trivial.
+
+## Usage Examples
+
+### Simplest Case
+```python
+results = goad.run_convergence("hex.obj", "asymmetry", tolerance=0.01)
+```
+
+### Multiple Targets
+```python
+results = goad.run_convergence(
+    "hex.obj", 
+    ["asymmetry", "scatt"],
+    tolerance=0.05
+)
+```
+
+### Mueller Elements with Specific Bins
+```python
+results = goad.run_convergence(
+    "hex.obj",
+    [{"variable": "S11", "tolerance": 0.1, "theta_indices": [180]}]
+)
+```
+
+### Ensemble
+```python
+results = goad.run_convergence("./geometries/", "asymmetry", tolerance=0.05)
+```
+
+### PHIPS
+```python
+results = goad.run_convergence(
+    "./geometries/",
+    "phips_dscs",
+    tolerance=0.25,
+    mode="phips",
+    phips_bins_file="phips_bins_edges.toml"
+)
+```
+
+### Parameter Sweep
+```python
+configs = [
+    ConvergenceConfig(
+        geometry="hex.obj",
+        mode=StandardMode(),
+        convergence_targets=[{"variable": "asymmetry", "tolerance": 0.05}],
+        wavelength=wl
+    )
+    for wl in [0.532, 0.633, 0.780]
+]
+results_list = run_convergence_sweep(configs)
+```
+
+## Validation Features
+
+### What Gets Validated
+
+✓ Geometry path exists (file or directory)
+✓ Mode is correct type (StandardMode or PHIPSMode)
+✓ Targets are valid for the mode
+✓ PHIPS bins file exists and is valid TOML
+✓ Numeric parameters are positive
+✓ Mueller options not used in PHIPS mode
+✓ theta_indices only used with Mueller elements
+✓ Empty convergence_targets rejected
+
+### Error Examples
+
+```python
+# Invalid geometry
+config = ConvergenceConfig(geometry="nonexistent.obj", ...)
+# FileNotFoundError: Geometry path does not exist
+
+# Invalid target for StandardMode
+run_convergence("hex.obj", targets="invalid_target")
+# ValueError: Invalid target 'invalid_target' for StandardMode
+
+# Mueller options in PHIPS mode
+ConvergenceConfig(mode=PHIPSMode(...), mueller_1d=True, ...)
+# ValueError: mueller_1d not supported in PHIPSMode
+
+# theta_indices on non-Mueller variable
+run_convergence("hex.obj", [{
+    "variable": "asymmetry", 
+    "theta_indices": [180]
+}])
+# ValueError: theta_indices can only be used with Mueller elements
+```
+
+## Testing
+
+All tests passing ✓
+
+**Validation tests** (`test_unified_validation.py`):
+- StandardMode creation and validation
+- PHIPSMode validation
+- ConvergenceConfig validation
+- Invalid input rejection
+- Config serialization
+
+**End-to-end tests** (`test_unified_quick.py`):
+- Simple convergence
+- Multiple targets
+- Mueller element convergence
+- Save/load JSON
+- Using ConvergenceConfig directly
+- Summary and serialization
+
+## Future Enhancements
+
+1. **Parallel parameter sweeps** - Use multiprocessing for sweep execution
+2. **Plotting integration** - `results.plot()` method for standard visualizations
+3. **HDF5/NetCDF output** - For large datasets and Mueller matrices
+4. **Progress callbacks** - For monitoring long convergences
+5. **Convergence diagnostics** - Autocorrelation, effective sample size, etc.
+
+## Migration Path
+
+The legacy API (`Convergence`, `EnsembleConvergence`, `PHIPSConvergence`) remains available and functional. Users can migrate incrementally:
+
+1. **Phase 1**: Use unified API for new scripts
+2. **Phase 2**: Update documentation to recommend unified API
+3. **Phase 3**: Add deprecation warnings to legacy API
+4. **Phase 4**: Remove legacy API (major version bump)
+
+No breaking changes in this release.