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 :doc:`getting_started` for examples and :doc:`theory` and :doc:`finite_element` for their physical interpretation. Public namespaces ----------------- The main API groups objects by responsibility. The existing top-level imports remain available as convenience aliases. .. list-table:: :widths: 28 72 :header-rows: 1 * - 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 :doc:`spectral`. 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 :doc:`spectral` 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 :doc:`detectors` for the integral, conventions, and limits. Meshes and solvers ------------------ For interface-fitted tetrahedra and local region/contact refinement, see :doc:`meshes`. ``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. .. code-block:: python 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 :doc:`phase function `. The Henyey–Greenstein function requires material ``anisotropy``. It supports reflecting faces and zero-reflectance Robin faces with isotropic incoming diffuse radiance. See :doc:`sp3` 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 :doc:`p3` 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 :doc:`spectral`. ``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 :doc:`convergence` 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 :doc:`results` for examples. ``VectorField.plot(...)`` returns a Plotly cone plot and accepts ``max_vectors``, ``length_unit``, and ``show``. The public classes are exported from :mod:`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. .. toctree:: :maxdepth: 1 python_api ``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 :doc:`spectral` for grid merging and spectral tolerance definitions.