API Reference

This page documents the Python API for GOAD.

Simulation Classes

These are the main classes for running light scattering simulations.

Problem

Single-orientation scattering simulation.

Problem

A solvable physics problem.

geom `property`

geom

Getter function for the geometry

results `property`

results

Get the results object

settings `property`

settings

Setter function for the problem settings

MultiProblem

Multi-orientation averaging simulation.

MultiProblem

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

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}")

num_orientations `property`

num_orientations

Get the number of orientations

results `property`

results

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

save `method descriptor`

save(directory=None)

Save simulation results to disk.

Writes Mueller matrices, parameters, and other output files to the specified directory (or the directory configured in settings).

Parameters:

Name	Type	Description	Default
`directory`		Optional output directory path. If not provided, uses the directory from settings.	`None`

solve `method descriptor`

solve()

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

Convergence

Adaptive convergence-based simulation.

Convergence

count `property`

count

Get the max orientations (safety cap).

max_orientations `property`

max_orientations

mean `property`

mean

Access the current mean results (live during solve).

sem `property`

sem

Access the current standard error of the mean (live during solve).

add_target `method descriptor`

add_target(param, relative_error)

Add a convergence target for a parameter (Python API). Solver terminates when ALL targets are satisfied.

clear_targets `method descriptor`

clear_targets()

Clear all convergence targets (Python API).

save `method descriptor`

save(directory=None)

Save simulation results to disk.

Writes Mueller matrices, parameters, and other output files to the specified directory (or the directory configured in settings).

Parameters:

Name	Type	Description	Default
`directory`		Optional output directory path. If not provided, uses the directory from settings.	`None`

solve `method descriptor`

solve()

Solve the multi-orientation scattering problem using work-stealing. Periodically checks for Python signals (Ctrl-C) and interrupts if needed.

Configuration

Classes for configuring simulations.

Settings

Main configuration object for simulations.

Settings

Runtime configuration for the application.

beam_power_threshold `property`

beam_power_threshold

Set the beam power threshold

cutoff `property`

cutoff

Set the cutoff

distortion `property`

distortion

Set the distortion factor

eulers `property`

eulers

Set the euler angles

fov_factor `property`

fov_factor

Set the field of view factor

geom_path `property`

geom_path

Set the geometry file path

geom_scale `property`

geom_scale

Set the per-axis geometry scaling [x, y, z]

max_rec `property`

max_rec

Set the max recursion depth

max_tir `property`

max_tir

Set the max TIR bounces

medium_refr_index_im `property`

medium_refr_index_im

Set the medium refractive index (imaginary part)

medium_refr_index_re `property`

medium_refr_index_re

Set the medium refractive index (real part)

orientation `property`

orientation

Set the full orientation object

particle_refr_index_im `property`

particle_refr_index_im

Set the particle refractive index (imaginary part)

particle_refr_index_re `property`

particle_refr_index_re

Set the particle refractive index (real part)

quiet `property`

quiet

Set quiet mode (suppress progress bars)

seed `property`

seed

Set the seed for random number generation

wavelength `property`

wavelength

Set the wavelength

zones `property`

zones

Set the zones configuration

Orientation

Particle orientation configuration.

Orientation

euler_convention `property`

euler_convention

scheme `property`

scheme

Euler

Euler angle representation.

Euler

alpha `property`

alpha

beta `property`

beta

gamma `property`

gamma

BinningScheme

Angular binning configuration.

BinningScheme

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.

bins `method descriptor`

bins()

Returns all 2D bins as a numpy array of shape (n_bins, 2) with columns [theta, phi]

bins_1d `method descriptor`

bins_1d()

Returns unique 1D theta bins as a numpy array

custom `staticmethod`

custom(bins)

Create a custom binning scheme with explicit bin edges Each bin is specified as [[theta_min, theta_max], [phi_min, phi_max]]

interval `staticmethod`

interval(thetas, theta_spacings, phis, phi_spacings)

Create an interval binning scheme with variable spacing

num_bins `method descriptor`

num_bins()

Returns the number of bins

phis `method descriptor`

phis()

Returns a list of all phi bin centre values

simple `staticmethod`

simple(num_theta, num_phi)

Create a simple binning scheme with uniform theta and phi spacing

thetas `method descriptor`

thetas()

Returns a list of all theta bin centre values

ZoneConfig

Zone configuration for multi-zone simulations.

ZoneConfig

Configuration for a zone, as specified in TOML or via CLI.

binning `property`

binning

Get the binning scheme

label `property`

label

Get the zone label

Results

Classes for accessing simulation results.

Results

Complete simulation results container.

Results

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.

albedo `property`

albedo

Get the albedo

asymmetry `property`

asymmetry

Get the asymmetry parameter

backward_zone `property`

backward_zone

Get the backward zone (convenience method)

bins `property`

bins

Get the bins as a numpy array of shape (n_bins, 2) with columns [theta, phi]

bins_1d `property`

bins_1d

Get the 1D bins (theta values) as a numpy array

ext_cross `property`

ext_cross

Get the extinction cross section

forward_zone `property`

forward_zone

Get the forward zone (convenience method)

full_zone `property`

full_zone

Get the full zone (convenience method)

mueller `property`

mueller

Get the Mueller matrix as a numpy array

mueller_1d `property`

mueller_1d

Get the 1D Mueller matrix as a numpy array

mueller_1d_beam `property`

mueller_1d_beam

Get the 1D beam Mueller matrix as a numpy array

mueller_1d_ext `property`

mueller_1d_ext

Get the 1D external diffraction Mueller matrix as a numpy array

mueller_beam `property`

mueller_beam

Get the beam Mueller matrix as a numpy array

mueller_ext `property`

mueller_ext

Get the external diffraction Mueller matrix as a numpy array

powers `property`

powers

Get the powers as a dictionary

scat_cross `property`

scat_cross

Get the scattering cross section

zones `property`

zones

Get the zones collection

Zone

A single angular zone with its results.

Zone

A zone represents a region of the scattering sphere with its own binning, results, and computed parameters.

bins `property`

bins

Get the bins as a numpy array of shape (n_bins, 2) with columns [theta, phi]

bins_1d `property`

bins_1d

Get the 1D theta bins as a numpy array (if available)

label `property`

label

Get the zone label

mueller `property`

mueller

Get the Mueller matrix as a numpy array of shape (n_bins, 16)

mueller_1d `property`

mueller_1d

Get the 1D Mueller matrix as a numpy array (if available)

name `property`

name

Get the display name for this zone

num_bins `property`

num_bins

Get the number of bins in this zone

params `property`

params

Get zone-specific parameters as a dict

zone_type `property`

zone_type

Get the zone type

Zones

Collection of zones.

Zones

A collection of zones for a simulation.

all_zones `property`

all_zones

Get all zones as a list

backward `property`

backward

Get the backward zone (convenience method)

forward `property`

forward

Get the forward zone (convenience method)

full `property`

full

Get the full zone (convenience method)

get `method descriptor`

get(label)

Get a zone by label

get_by_type `method descriptor`

get_by_type(zone_type)

Get a zone by type (returns first matching zone)

Geometry

Classes for defining particle geometry.

Geom

Complete particle geometry (collection of shapes).

Geom

first_shape_vertices `property`

first_shape_vertices

Getter for the vertices of the first shape

Shape

A single 3D surface mesh.

Shape

Represents a 3D surface mesh.

Enumerations

Param

Available scattering parameters for convergence targets.

Param

eq `method descriptor`

__eq__(value)

Return self==value.

ge `method descriptor`

__ge__(value)

Return self>=value.

gt `method descriptor`

__gt__(value)

Return self>value.

int `method descriptor`

__int__()

int(self)

le `method descriptor`

__le__(value)

Return self<=value.

lt `method descriptor`

__lt__(value)

Return self<value.

ne `method descriptor`

__ne__(value)

Return self!=value.

repr `method descriptor`

__repr__()

Return repr(self).

ZoneType

Types of angular zones.

ZoneType

The type of zone, which determines what parameters can be computed.

Backward `class-attribute`

Backward = ZoneType.Backward

The type of zone, which determines what parameters can be computed.

Custom `class-attribute`

Custom = ZoneType.Custom

The type of zone, which determines what parameters can be computed.

Forward `class-attribute`

Forward = ZoneType.Forward

The type of zone, which determines what parameters can be computed.

Full `class-attribute`

Full = ZoneType.Full

The type of zone, which determines what parameters can be computed.

eq `method descriptor`

__eq__(value)

Return self==value.

ge `method descriptor`

__ge__(value)

Return self>=value.

gt `method descriptor`

__gt__(value)

Return self>value.

int `method descriptor`

__int__()

int(self)

le `method descriptor`

__le__(value)

Return self<=value.

lt `method descriptor`

__lt__(value)

Return self<value.

ne `method descriptor`

__ne__(value)

Return self!=value.

repr `method descriptor`

__repr__()

Return repr(self).

Mapping

Near-to-far field mapping methods.

Mapping

Enum representing different mapping methods from near to far field.

ApertureDiffraction `class-attribute`

ApertureDiffraction = Mapping.ApertureDiffraction

Enum representing different mapping methods from near to far field.

GeometricOptics `class-attribute`

GeometricOptics = Mapping.GeometricOptics

Enum representing different mapping methods from near to far field.

int `method descriptor`

__int__()

int(self)

new `builtin`

__new__(*args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

repr `method descriptor`

__repr__()

Return repr(self).