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 L_max — max spherical harmonic degree sigma — deformation amplitude spectral_decay — high-frequency suppression N_theta, N_phi — angular grid sizes seed — RNG seed load — load from .npz file	Generate or load a particle. Exposes r, points, normals, info(), plot(), save().
gs.ExposedPoints(...)	points — Cartesian surface points normals — outward normals 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 point_weights — optional per-point area weights 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:

pip install goscat

3.2 Generate a random particle

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

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

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

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.

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!