Metadata-Version: 2.4
Name: goscat
Version: 1.0.1
Summary: Geometric optics light scattering for randomly-shaped particles.
Home-page: https://github.com/DwaipayanDeb/goscat
Author: Dwaipayan Deb
Author-email: dwaipayandeb@yahoo.co.in
License: BSD-3-Clause
Keywords: light scattering geometric optics particle ray tracing spherical harmonics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.8
Requires-Dist: matplotlib>=3.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# goscat User Manual

## 1. What is this code about?

`goscat` is a Python package for generating randomly deformed particle shapes and estimating their light-scattering behavior in the geometric optics regime.

It is designed for irregular particles whose surface can be represented by spherical-harmonic perturbations. The package provides:

- `DeformedSphere`: generate a volume-equivalent random particle shape and compute its surface points and normals
- `ExposedPoints`: identify which surface points are illuminated by a plane beam and compute incidence angles
- `ScatCalc`: simulate geometric-optics scattering using ray tracing across exposed surface points

This package is intended for researchers and engineers working with irregular particles, aerosol optics, and geometric-optics scattering calculations.

## 2. Basic theory

### 2.1 Random particle shape generation

The particle surface is defined by a function `r(Î¸, Ï†)` on the sphere. The radius is built from a base sphere of effective radius `r_eff`, plus a random perturbation using spherical harmonics.

The key points are:

- The particle volume is always rescaled to match a perfect sphere with radius `r_eff`.
- Random surface features are controlled by `L_max`, `sigma`, and `spectral_decay`.
- `L_max` controls the maximum spherical-harmonic degree and therefore the number of surface bumps.
- `sigma` controls deformation amplitude relative to `r_eff`.
- `spectral_decay` controls how quickly higher-frequency harmonic components are suppressed.
 - `seed` â€” optional integer seed for the random number generator. Providing a fixed `seed` makes the generated particle deterministic and reproducible across runs; omit or set to `None` for a different random particle each time.

The generator also computes outward unit normals for every surface point. These normals are essential for ray tracing and incident-angle calculations.

### 2.2 Exposed surface points

A collimated beam is assumed to travel in the XZ plane, with incidence defined as the angle measured from the +Z axis.

A surface point is considered exposed if the beam hits the outside surface face. This is determined by the sign of the dot product between the beam direction and the outward normal:

- Exposed when `d Â· n_hat < 0`

The incidence angle at each exposed point is then:

- `Î± = arccos(-d Â· n_hat)`

This package makes it easy to compute both the exposed points and the corresponding incidence angles.

### 2.3 Geometric-optics scattering

`ScatCalc` performs a simplified geometric-optics ray tracing calculation. It traces light from each exposed point through the particle and computes:

- reflected intensity components for `s` and `p` polarization
- refracted rays inside the particle
- exit rays after internal interactions
- scattering bins in spherical coordinates (`Î¸`, `Ï†`)

The calculation uses Fresnel formulas with complex refractive index `m = n + ik` and includes internal absorption when `k > 0`.

### 2.4 Main user-facing classes and methods

| Function / Class | Parameters (brief) | Description |
|---|---|---|
| `gs.DeformedSphere(...)` | `r_eff` â€” effective radius<br>`L_max` â€” max spherical harmonic degree<br>`sigma` â€” deformation amplitude<br>`spectral_decay` â€” high-frequency suppression<br>`N_theta`, `N_phi` â€” angular grid sizes<br>`seed` â€” RNG seed<br>`load` â€” load from `.npz` file | Generate or load a particle. Exposes `r`, `points`, `normals`, `info()`, `plot()`, `save()`.
| `gs.ExposedPoints(...)` | `points` â€” Cartesian surface points<br>`normals` â€” outward normals<br>`incidence` â€” beam angle from +Z (deg) | Find illuminated surface points and incidence angles. Exposes `points` (list), `angles` (list), `info()`, `plot()`.
| `gs.ScatCalc(...)` | `points`, `normals`, `exp_points`, `incidence`, `n`, `k`, `wavelength`, `beam_theta`, `d_theta`, `d_phi`, `I_cutoff`, `point_weights` | Ray-trace scattering from exposed points. Results: `Iscatt` list, `info()`, `plot()`, and `compute_efficiencies()` method.
| `sct.compute_efficiencies(...)` | `r_eff` â€” effective radius<br>`point_weights` â€” optional per-point area weights<br>`surface_area` â€” optional total surface area | Compute efficiencies and cross-sections. Returns both standard (`Q_sca`, `Q_abs`, `Q_ext`, `albedo`) and diffraction-corrected (`Q_sca_diff`, `Q_ext_diff`, `albedo_diff`) values.

## 3. Usage with examples

The examples below use the package interface from the `goscat` namespace.

### 3.1 Installation

Install with:

```bash
pip install goscat
```

### 3.2 Generate a random particle

```python
import goscat as gs

particle = gs.DeformedSphere(
    r_eff=10.0,
    L_max=6,
    sigma=0.20,
    spectral_decay=2.0,
    N_theta=120,
    N_phi=240,
    seed=42,
)

print(particle.r.shape)          # grid shape: (N_theta, N_phi)
print(particle.points.shape)     # flattened Cartesian points: (N, 3)
print(particle.normals.shape)    # flattened normals: (N, 3)

particle.info()
particle.plot()
```

### 3.3 Save and load a particle

```python
particle.save('my_particle.npz')

loaded = gs.DeformedSphere(load='my_particle.npz')
print(loaded.r_eff)
print(loaded.points.shape)
```

### 3.4 Identify exposed points

```python
from goscat import ExposedPoints

particle = gs.DeformedSphere(load='particle2.npz')

exposed = gs.ExposedPoints(
    points=particle.points,
    normals=particle.normals,
    incidence=30.0,
)

print(f'Exposed points: {len(exposed.points)}')
print(f'First incidence angle: {exposed.angles[0]:.3f}Â°')
exposed.info()
exposed.plot()
```

### 3.5 Perform scattering calculation

```python
sct = gs.ScatCalc(
    points=particle.points,
    normals=particle.normals,
    exp_points=exposed.points,
    incidence=exposed.angles,
    n=1.5,
    k=0.01,
    wavelength=0.535,
    beam_theta=30.0,
    d_theta=2.0,
    d_phi=2.0,
)

print(f'Computed bins: {len(sct.Iscatt)}')
print('First bin:', sct.Iscatt[0])

sct.info()
# sct.plot()
```

### 3.6 Compute efficiencies

`ScatCalc.compute_efficiencies()` returns several derived scattering quantities.
The package computes two versions of the efficiencies and albedo:

- **Without diffraction correction**: `Q_sca`, `Q_abs`, `Q_ext`, and `albedo`
- **With diffraction correction**: `Q_sca_diff`, `Q_ext_diff`, and `albedo_diff`

The diffraction-corrected values are intended as a rough adjustment to account
for the missing diffraction component in the pure geometric-optics ray-tracing
model.

```python
results = sct.compute_efficiencies(particle.r_eff)
print('Q_sca =', results['Q_sca'])
print('Q_abs =', results['Q_abs'])
print('Q_ext =', results['Q_ext'])
print('albedo =', results['albedo'])
print('Q_sca_diff =', results['Q_sca_diff'])
print('Q_ext_diff =', results['Q_ext_diff'])
print('albedo_diff =', results['albedo_diff'])
```

Note that the raw geometric-optics quantities are usually the most directly
meaningful for the internal ray-tracing calculation; the diffraction-corrected
values are a convenient secondary estimate when comparing with measurements or
theory that include wave effects.

### 3.7 Example workflow

A typical workflow with `goscat` is:

1. Generate or load a `DeformedSphere` particle.
2. Compute which points are illuminated with `ExposedPoints`.
3. Trace scattering from those points using `ScatCalc`.
4. Compute scattering efficiencies and inspect the output.

## 4. Notes and tips

- Use `sigma` between `0.05` and `0.30` for stable, realistic shapes.
- Keep `N_theta` and `N_phi` large enough to resolve surface detail, but be mindful of runtime.
- The package is best for geometric optics / ray-tracing style scattering, not exact Mie theory for spheres.
- `beam_theta` controls the incoming beam orientation in the XZ plane.

## 5. Available module exports

From `goscat` you can access:

- `DeformedSphere`
- `ExposedPoints`
- `ScatCalc`
- `generate_random_particle`
- `compute_normals`
- `particle_metrics`

## 6. Recommended follow-up

If you want to extend the package later, consider adding:

- batch generation of multiple particles
- support for different beam geometries
- richer output formats for scattering patterns
- GPU acceleration for large point sets

---

This manual is intended to make `goscat` easy to use for light-scattering experiments and ray-tracing analysis. Happy modeling!
