Public API reference#

All public constructors and methods use keyword arguments, apart from add_structures(*structures) and Python’s implicit self and cls. Dimensional values require quantities from MomentRT.ureg. See Getting started for examples and Transport theory and approximations and Finite-sample P1 solver for their physical interpretation.

Public namespaces#

The main API groups objects by responsibility. The existing top-level imports remain available as convenience aliases.

Namespace

Examples

MomentRT.material

Material, SpectralMaterial

MomentRT.materials

Epidermis, Dermis, Water, Intralipid

MomentRT.medium and MomentRT.geometry

StructuredMedium, HomogeneousMedium, Layer, Sphere, Box

MomentRT.source and MomentRT.detector

SurfaceSource, SourceSpectrum, SurfaceDetector, DetectorResponsivity

MomentRT.boundary and MomentRT.mesh

Boundaries, RobinBoundary, TetrahedralMesh, CartesianMesh

MomentRT.transport

P1, InfiniteP1, TransientP1, SP3, P3

MomentRT.simulation and MomentRT.results

Simulation, SimulationResult, TransientResult

MomentRT.phase_function and MomentRT.fields

HenyeyGreenstein, Rayleigh, ScalarField, VectorField

MomentRT.models

Named builders in skin, phantom, and spectrum

Materials and media#

Material requires absorption, reduced_scattering, refractive_index, and a phase_function object. The first two are nonnegative/positive inverse-length quantities; refractive index is a positive plain number. Henyey–Greenstein also requires anisotropy for SP3/P3.

SpectralMaterial requires a strictly increasing wavelengths vector, same-length absorption and reduced_scattering quantities, and a scalar or same-length plain refractive_index, and an explicit phase_function object. Its at(wavelength=...) method linearly interpolates a monochromatic Material and rejects extrapolation. Fixed Material objects also support at(wavelength=...) and retain their fixed coefficients.

HomogeneousMedium wraps one material for the infinite-medium model. StructuredMedium requires unit-bearing origin and positive size vectors. Set its background with add_background(material=...) and add ordered Layer, Box, or Sphere objects with add_structures(*structures). add_layer(...) stacks below the deepest existing layer.

Both media support at(wavelength=...). Finite sample geometry and insertion order are preserved on the resolved copy. Property sampling and display methods accept an explicit wavelength for spectral samples. See Wavelength-dependent materials and sweeps.

Parameterized materials are available as MomentRT.materials.Intralipid(concentration=, wavelength=, refractive_index=), MomentRT.materials.Epidermis(melanin_fraction=, wavelength=, refractive_index=), MomentRT.materials.Dermis(hydration=, wavelength=, refractive_index=), and MomentRT.materials.Water(wavelength=, refractive_index=). Intralipid concentration is particle volume fraction in percent: 22.7 is undiluted 20% stock. Its empirical equation has a wavelength-dependent validity limit. The simple skin models put melanin in the epidermis; the dermis model mixes water and a baseline absorber and omits blood-vessel structure. These literature parameterizations are starting points, not patient-specific properties. Pure water’s very low scattering also makes it outside the useful regime of MomentRT’s diffusion solvers.

Sources#

The same source classes accept spectrum=SourceSpectrum(...) instead of the monochromatic wavelength and optical_power pair. Density values carry W per wavelength units, and Simulation.run() explicitly integrates the resulting collected power over the source grid. Detectors optionally accept responsivity=DetectorResponsivity(...) in A/W for photocurrent. See Wavelength-dependent materials and sweeps for the complete API, quadrature, and validation limits.

PointSource requires position, wavelength, and positive optical_power. It is supported by InfiniteP1 only.

SurfaceSource requires a boundary face, absolute 3D position, positive radius, wavelength, and optical_power. The spot is a circular top-hat and must fit fully on the face. UniformSurfaceSource requires a face, wavelength, and optical power, and illuminates the complete face. Both finite-source classes specify power already coupled into the sample. SurfaceSourceGroup(sources=[...]) combines circular surface sources on the same face and wavelength into one simultaneous incoming profile and one transport solve. Passing an iterable of SurfaceSource objects as Simulation(source=...) creates this group automatically. Each member disk is normalized to its own optical power.

Detectors#

SurfaceDetector requires a sample boundary face, unit-bearing position and positive radius, a nonzero plain collection_axis pointing outward, and a unit-bearing acceptance_angle from zero to 90 degrees. The circular contact aperture lies in the sample face. The angle is a cone half-angle around the collection axis.

measure(result=...) returns a DetectorResult with collected_power, sampled_area, geometric_area, angular_fraction, minimum_escaping_irradiance, wavelength, and a snapshot of the detector configuration. This uses a Lambertian escape assumption. See Finite-aperture surface detectors for the integral, conventions, and limits.

Meshes and solvers#

For interface-fitted tetrahedra and local region/contact refinement, see Meshes and local refinement. TetrahedralMesh uses a scalar target resolution and stores nodal fields as (N,) arrays; all finite transport models accept it.

CartesianMesh.from_sample accepts a physical resolution: a scalar length applies to all three axes, and a length vector specifies x/y/z spacing. Resolution is a maximum spacing; each axis is divided into enough uniform intervals to fit the sample exactly without exceeding that spacing, within floating-point precision. For example, a 1 mm extent with a requested 0.3 mm resolution has four intervals of 0.25 mm and five nodes.

mesh = MomentRT.CartesianMesh.from_sample(
    sample=sample,
    resolution=100 * MomentRT.ureg.um,
)

mesh = MomentRT.CartesianMesh.from_sample(
    sample=sample,
    resolution=(50, 50, 200) * MomentRT.ureg.um,
)

mesh.resolution retains the requested scalar or vector quantity, mesh.spacing reports actual node separations, and mesh.shape gives node counts. Supply exactly one of resolution or shape to from_sample. Existing shape=... configurations remain supported and have mesh.resolution is None. The low-level CartesianMesh constructor continues to accept explicit shape, spacing, and origin.

InfiniteP1 evaluates the analytical P1 Green function for a HomogeneousMedium and PointSource. P1 requires a mapping that configures exactly six faces with RobinBoundary or ReflectingBoundary objects. The finite solver accepts SurfaceSource, SurfaceSourceGroup, or UniformSurfaceSource.

SP3 solves two coupled moment equations on the same finite sample and uses each material’s explicit phase function. The Henyey–Greenstein function requires material anisotropy. It supports reflecting faces and zero-reflectance Robin faces with isotropic incoming diffuse radiance. See SP3 transport model for the equations and limitations.

P3 solves the full three-dimensional angular expansion through degree three with six even-parity nodal fields. It requires material phase moments, isotropic incoming diffuse sources, and zero-reflectance Robin conditions on all faces. Reflecting and refracting boundaries are not supported. See Full three-dimensional P3 transport for the formulation and validation limits.

RobinBoundary requires a plain effective_reflectance in [0, 1). ReflectingBoundary imposes zero normal current and does not accept illumination.

Boundaries.uniform(condition=...) applies an explicitly chosen condition to all six faces. boundaries.with_overrides(conditions={...}) returns a new mapping with selected faces replaced. Both solvers also accept ordinary six-face mappings.

For circular surface objects, SurfaceSource.on_face(...) and SurfaceDetector.on_face(...) accept the sample, face, and two absolute in-plane coordinates. Coordinates follow Cartesian axis order: (y, z) for x faces, (x, z) for y faces, and (x, y) for z faces. A detector requires orientation="outward_normal"; use its full constructor for a tilted collection axis. The resulting objects expose their full 3D positions and detector axis.

Simulation and results#

Simulation composes medium, source, mesh, and solver, plus an optional detectors mapping from names to SurfaceDetector objects. Call simulation.run() to receive a SimulationResult containing fluence and, for the finite solver, flux, energy_balance, outgoing_power_by_face, boundary_fields, and diagnostics. Configured measurements are in result.detectors; the result.detector_power property maps their names to collected powers. Boundary fields are BoundaryField snapshots of triangle-quadrature positions, area weights, escaping irradiance, geometry, and wavelength.

simulation.validate(wavelengths=...) checks configuration and, for finite samples, measures source and detector footprint areas using boundary quadrature. Its ValidationReport contains valid, errors, warnings, and sampled areas. Omit wavelengths to check the source wavelength. Call report.summary() or result.summary() for readable diagnostics. A valid configuration does not establish mesh convergence or accuracy of the physical model.

simulation.sweep(wavelengths=..., optical_power=...) returns a SpectralSimulationResult with ordered wavelengths, per-wavelength results, and detector-power vectors in detector_power. Optional optical power is a scalar or a vector matching the wavelength shape; omitting it retains the configured source power. Its plot(wavelength_unit=..., power_unit=..., show=...) method plots collected power for configured detectors. Each solve evaluates material tables at the current wavelength without mutating the original configuration.

Finite sweeps prepare geometry, material labels, region matrices, and boundary quadrature once per call. Spectral diagnostics include preparation and per-wavelength timing quantities. See Wavelength-dependent materials and sweeps.

simulation.mesh_convergence(mesh_shapes=...) compares explicit Cartesian levels; mesh_resolutions=... compares interface-fitted tetrahedra and can apply local contact_resolution / contact_distance refinement. The method returns a DetectorConvergenceResult for configured finite detectors. It retains per-level powers, footprint areas, errors, fields, and convergence flags. recommended_mesh is None when no supported recommendation can be made; recommended_shape and recommended_resolution describe the matching mesh type. Its plot(power_unit=..., area_unit=..., show=...) method compares powers and areas. See Choosing a mesh for detector collection for the criteria and unresolved levels.

ScalarField.plot(...) returns a Plotly figure. Its view may be volume (default), slices, or isosurfaces; scale may be linear or log; length_unit controls displayed coordinates; opacity chooses the initial opacity for volume and isosurface views; isosurface_count sets the number of iso levels in volume and isosurface views while leaving their default counts intact when omitted (it only applies to those views); and show controls whether the figure is immediately opened. The optional overlays argument adds sources and detectors to any scalar field’s 3D view. Supply a sequence of source and detector objects; their name and color attributes control legend labels and plot colors. Their spatial coordinates are converted to length_unit. Full-face sources require the physical sample bounds saved by the finite solver. See Results and visualization for examples. VectorField.plot(...) returns a Plotly cone plot and accepts max_vectors, length_unit, and show.

The public classes are exported from MomentRT; plotting dependencies are optional and guarded at module scope.

Detailed Python API#

The reference below is generated from NumPy-style docstrings and type hints. Dimensional annotations use pint.Quantity; the docstrings specify the required physical units and array shapes. Runtime unit validation remains in force. Third-party solvers can implement the TransportSolver protocol without inheriting from it.

simulation.spectral_convergence(wavelength_grids=...) compares integrated optical power and optional photocurrent over nested wavelength grids while preserving source table knots and fixed geometry. Its inspectable grids, per-level changes, and failures support a recommendation only after a stable final sequence. convergence_study remains an alias for mesh_convergence. See Wavelength-dependent materials and sweeps for grid merging and spectral tolerance definitions.