Skip to main content

MomentRT — light transport through a finite element volume.

Badge

Status

Python versions

Python versions

Documentation

Documentation build status

Tests

Test workflow status

Coverage workflow

Coverage workflow status

PyPI package

PyPI version

PyPI downloads

Monthly PyPI downloads

Anaconda package

Anaconda version

Anaconda downloads

Anaconda downloads

Latest Anaconda release

Latest Anaconda release date

MomentRT

MomentRT is an open-source Python package for deterministic light transport using angular-moment methods. It models steady-state P1 diffusion in homogeneous infinite media and finite structured samples. Its API keeps the sample, illumination, mesh, and solver explicit, and its results include unit-bearing optical fields and power diagnostics.

Features

  • Analytical P1 diffusion from an isotropic point source in an infinite, homogeneous medium.

  • Boundary-aware P1 diffusion for finite samples, solved with linear tetrahedral finite elements.

  • Layered samples with box and sphere structures, plus resolved material cross-sections.

  • Explicit diffuse surface illumination and Robin or reflecting conditions on all six sample faces.

  • Interactive Plotly views for sample geometry, fluence, sections, and element-centered flux. Volume plots include an opacity control.

  • Unit-bearing fields, per-face escaping power, and solver diagnostics.

  • Circular contact detector apertures with explicit angular acceptance under a Lambertian escape model.

  • Tabulated wavelength-dependent materials and monochromatic sweeps on a fixed source, sample, and detector geometry.

  • Detector mesh-refinement studies and reusable finite-element preparation across wavelengths.

  • A coupled SP3 finite-element solver with explicit scattering anisotropy and matched-index boundaries, alongside the P1 diffusion solver.

  • A full three-dimensional P3 finite-element solver with matched-index faces.

  • Scalar Henyey–Greenstein, isotropic, Rayleigh, and tabulated scattering phase functions for SP3 and P3.

MomentRT offers P1, SP3, and P3 approximations. It does not currently solve the full radiative transfer equation or implement collimated LED propagation, free-space detector optics, broadband spectral integration, time dependence, or inverse estimation. Read the scientific guide for the equations, approximations, validation limits, and complete workflow.

Installation

Install the released Python package with Plotly visualization support:

python -m pip install "MomentRT[viz]"

Or install the conda package and its dependencies:

conda install -c martinpdes -c conda-forge momentrt

Verify the installation with the same Python interpreter you will use for your calculations:

python -c "import MomentRT; print(MomentRT.__version__)"

The base package includes the numerical dependencies. Plotly is optional for interactive plots; PyVista is optional for VTK export. Install both plotting extras with python -m pip install "MomentRT[viz,vtk]".

First simulation

The infinite-medium solver is a quick way to calculate and inspect a fluence field. This example uses explicit units and places the source between grid nodes, avoiding the singular point-source location.

import numpy as np
import MomentRT

from MomentRT import (
    CartesianMesh,
    HomogeneousMedium,
    InfiniteDiffusion,
    Material,
    PointSource,
    Simulation,
    ureg,
)

material = Material(
    absorption=0.02 / ureg.millimeter,
    reduced_scattering=1.0 / ureg.millimeter,
    refractive_index=1.4,
    phase_function=MomentRT.phase_function.HenyeyGreenstein(),
)

medium = HomogeneousMedium(material=material)

mesh = CartesianMesh(
    shape=(40, 40, 40),
    spacing=np.full(3, 0.4) * ureg.millimeter,
    origin=np.full(3, -7.8) * ureg.millimeter,
)

source = PointSource(
    position=np.zeros(3) * ureg.millimeter,
    wavelength=970 * ureg.nanometer,
    optical_power=1 * ureg.milliwatt,
)

solver = InfiniteDiffusion()

simulation = Simulation(
    medium=medium,
    source=source,
    mesh=mesh,
    solver=solver,
)

result = simulation.run()

figure = result.fluence.plot(
    scale="log",
)

result.fluence is a nodal fluence-rate field with units of W/m². The infinite solver evaluates an analytical Green function; the observation grid does not create physical sample boundaries.

Finite-sample FEM workflow

For a finite sample, define its geometry and materials, create a mesh, specify surface illumination and all six boundary faces, then run Diffusion. This example uses the same explicit effective reflectance on each face and a circular diffuse source on the upper face.

import numpy as np
import MomentRT

from MomentRT import (
    CartesianMesh,
    Diffusion,
    Material,
    RobinBoundary,
    Simulation,
    StructuredMedium,
    SurfaceSource,
    ureg,
)

background = Material(
    absorption=0.02 / ureg.millimeter,
    reduced_scattering=1.0 / ureg.millimeter,
    refractive_index=1.4,
    phase_function=MomentRT.phase_function.HenyeyGreenstein(),
)

upper_material = Material(
    absorption=0.04 / ureg.millimeter,
    reduced_scattering=1.5 / ureg.millimeter,
    refractive_index=1.4,
    phase_function=MomentRT.phase_function.HenyeyGreenstein(),
)

sample = StructuredMedium(
    origin=(-4, -4, 0) * ureg.millimeter,
    size=(8, 8, 4) * ureg.millimeter,
)

sample.add_background(material=background)

sample.add_layer(
    name="Upper layer",
    thickness=1 * ureg.millimeter,
    material=upper_material,
)

mesh = CartesianMesh.from_sample(
    sample=sample,
    shape=(25, 25, 17),
)

source = SurfaceSource(
    face="z_min",
    position=np.array([0, 0, 0]) * ureg.millimeter,
    radius=1 * ureg.millimeter,
    wavelength=970 * ureg.nanometer,
    optical_power=1 * ureg.milliwatt,
)

boundary = RobinBoundary(effective_reflectance=0.5)

solver = Diffusion(
    boundaries={
        "x_min": boundary,
        "x_max": boundary,
        "y_min": boundary,
        "y_max": boundary,
        "z_min": boundary,
        "z_max": boundary,
    },
)

simulation = Simulation(
    medium=sample,
    source=source,
    mesh=mesh,
    solver=solver,
)

geometry = simulation.plot_system(
    show=False,
)

result = simulation.run()

figure = result.fluence.plot(
    view="volume",
    scale="log",
)

print(f"Incoming power: {result.energy_balance['incoming_power']}")
print(f"Absorbed power: {result.energy_balance['absorbed_power']}")
print(f"Escaping power: {result.energy_balance['escaping_power']}")

The finite Diffusion solver uses P1 diffusion with linear tetrahedral FEM. Its sample mesh must span the sample exactly. Internal refractive indices must be equal because the solver models continuous fluence and does not resolve refracting interfaces. SurfaceSource.optical_power is diffuse power already coupled into the sample; incident beam propagation and specular entry losses are not included. The supplied effective reflectance is a diffuse partial-current coefficient, not a Fresnel value inferred from refractive index.

Visualization

The default fluence plot is a Plotly volume view. Adjust opacity from 0 to 1 using its browser slider, or choose a starting value with opacity:

figure = result.fluence.plot(
    view="volume",
    scale="log",
    opacity=0.12,
    show=False,
)

figure.write_html("fluence.html")

Other scalar-field views include central mesh slices and isosurfaces. result.flux.plot() displays element-centered diffusive flux vectors. sample.plot() shows the transparent construction surfaces; sample.plot_section(...) displays a sampled material or optical-property map. Log color scales change the displayed colors only; hover values retain their physical units.

The following figures were generated from MomentRT examples and results. The live documentation contains interactive Plotly versions.

MomentRT view of a layered sample with a spherical inclusion. Logarithmic volume rendering of fluence around an isotropic point source. Logarithmic fluence on three central planes in a finite sample.

Documentation

The online documentation includes:

  • The P1 moment equations, infinite-medium Green function, and approximation limits.

  • The finite-sample Robin boundary condition, weak form, and FEM assembly.

  • Complete workflows, visualization guidance, results, and API reference.

  • An executable example gallery.

Build the docs and run the examples locally with:

python -m pip install -e ".[documentation,viz]"
make docs PYTHON=.venv/bin/python

Common issues

  • Point-source singularity: do not place an observation node exactly at the point source. MomentRT reports this instead of silently regularizing it.

  • No visible internal interface: construction plots use transparent geometry surfaces. Use a sampled section to inspect the resolved material precedence.

  • Finite solver rejects refractive indices: the current FEM formulation requires equal internal refractive indices; it does not model internal refraction.

  • Unexpected surface-source power: source power is already coupled diffuse power in the sample. Collimated illumination and specular entry losses are outside the model.

  • Slow or changing fields under refinement: element-centroid materials, source quadrature, interface alignment, and P1 validity can all affect the result. Refine meshes and compare independent references; energy balance alone does not validate the physical approximation.

  • Log plot rejects values: logarithmic rendering requires strictly positive values and does not clip zeros or negative values.

Developer setup

Clone the repository, install the development extras, and build the docs with the same Python interpreter used for development:

git clone https://github.com/MartinPdeS/MomentRT.git
cd MomentRT
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[testing,documentation,dev,viz]"
make check PYTHON=.venv/bin/python
make docs PYTHON=.venv/bin/python

make check runs quality checks and tests. The codebase intentionally keeps the package flat, with type hints and NumPy-style API docstrings. Run make typecheck docstring-check to validate annotations and public parameter documentation.

Citation and license

MomentRT is distributed under the MIT license. If you use it in research, cite the version recorded in CITATION.cff. For bibliographic metadata, see the CITATION.cff file.

Metadata

Release files for MomentRT 0.8.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for MomentRT 0.8.1
File Size Uploaded Provenance Actions
momentrt-0.8.1.tar.gz 80.0 kB Without provenance Details for momentrt-0.8.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for MomentRT 0.8.1
File Interpreter ABI Platform Actions
momentrt-0.8.1-py3-none-any.whl Python 3 none any Details for momentrt-0.8.1-py3-none-any.whl

Total release size: 168.4 kB

Release files / momentrt-0.8.1.tar.gz

Download URL momentrt-0.8.1.tar.gz
Size 80.0 kB
Tags Source
SHA-256 checksum
How to use checksums
641f083ef608233bbb0181ecfbc71fce38eec8da5b3b1afd7116f1c78efe91da
BLAKE2b-256 checksum
How to use checksums
44f3193db30726f8296a15ec2986a785bd5373508679730905c376a6271ac24a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Release files / momentrt-0.8.1-py3-none-any.whl

Download URL momentrt-0.8.1-py3-none-any.whl
Size 88.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bea7978768afe22b9fa1612d305bd29422a8a33c119d62c4a28095652f30508c
BLAKE2b-256 checksum
How to use checksums
ab13885a198dc2df449ec27019cc34e02561786b90fa03ea635aee61447da300
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Security for MomentRT 0.8.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page