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 a Python library for deterministic light transport in scattering media. It is designed for biomedical optics workflows such as exploring how layered skin, diffuse illumination, and a contact detector influence the light reaching a sensor.

Define the tissue, source, detector, boundary conditions, mesh, and transport model as separate objects. MomentRT solves for unit-bearing optical fields and reports detector power and energy-balance diagnostics. Its general-purpose transport API also supports nonbiological media and instruments.

Three-dimensional calculated fluence in a layered skin sample with a surface source and detector.

A P1 finite-element solution for an illustrative three-layer skin sample. The colored volume shows fluence interpolated from the nodal solution onto a display grid. Explore the interactive example.

What you can model

  • Tissue and phantoms: finite layered samples with inclusions, named skin models, and user-supplied monochromatic or wavelength-dependent materials.

  • Contact instruments: diffuse disk or full-face illumination and circular detector apertures with explicit orientation and angular acceptance.

  • Light transport: analytical infinite-medium P1 and finite-sample P1, SP3, and full three-dimensional P3 angular-moment models.

  • Time-resolved transport: coupled transient P1 fluence and current for explicit diffuse pulse profiles, with time-resolved contact-detector power.

  • Spectral response: monochromatic sweeps, source spectra, and linear detector responsivity for broadband optical power and photocurrent.

  • Inspection and verification: interactive 3D fields, sample sections, sampled footprint areas, energy diagnostics, and detector mesh studies.

Install

python -m pip install MomentRT

Or install from conda:

conda install -c martinpdes -c conda-forge momentrt

Skin contact-sensor example

This complete example constructs a finite skin sample and a source and detector on its upper face, refines a tetrahedral mesh around the contacts, and solves with P1. The preset contains coefficients near 850 nm interpolated from one ex vivo skin dataset; its dimensions and optical properties are illustrative rather than patient-specific.

import MomentRT
from MomentRT.models.skin import ShimojoThreeLayer850nm

ureg = MomentRT.ureg

sample = ShimojoThreeLayer850nm(
    origin=(-3, -3, 0) * ureg.mm,
    size=(6, 6, 4) * ureg.mm,
)

source = MomentRT.source.SurfaceSource.on_face(
    sample=sample,
    face="z_min",
    coordinates=(-1, 0) * ureg.mm,
    radius=0.8 * ureg.mm,
    wavelength=850 * ureg.nm,
    optical_power=1 * ureg.mW,
)

detector = MomentRT.detector.SurfaceDetector.on_face(
    sample=sample,
    face="z_min",
    coordinates=(1, 0) * ureg.mm,
    radius=0.8 * ureg.mm,
    orientation="outward_normal",
    acceptance_angle=90 * ureg.degree,
)

mesh = MomentRT.mesh.TetrahedralMesh.from_sample(
    sample=sample,
    resolution=0.4 * ureg.mm,
)
mesh.refine_near(
    objects=[source, detector],
    resolution=0.2 * ureg.mm,
    distance=0.3 * ureg.mm,
)

solver = MomentRT.transport.P1(
    boundaries=MomentRT.boundary.Boundaries.uniform(
        condition=MomentRT.boundary.RobinBoundary(effective_reflectance=0),
    ),
)
simulation = MomentRT.simulation.Simulation(
    medium=sample,
    source=source,
    mesh=mesh,
    solver=solver,
    detectors={"contact": detector},
)

result = simulation.run()
measurement = result.detectors["contact"]

print(f"Collected power: {measurement.collected_power.to('uW'):~P}")
print(f"Sampled source area: {result.source_sampled_area.to('mm^2'):~P}")
print(f"Geometric source area: {result.source_geometric_area.to('mm^2'):~P}")
print(f"Sampled detector area: {measurement.sampled_area.to('mm^2'):~P}")
print(f"Geometric detector area: {measurement.geometric_area.to('mm^2'):~P}")
print(f"Minimum nodal fluence: {result.fluence.values.min().to('W/m^2'):~P}")

system_figure = simulation.plot_system(show=False)
mesh_figure = mesh.plot(max_edges=4000, show=False)
fluence_figure = result.fluence.plot(
    view="volume",
    scale="log",
    display_resolution=0.3 * ureg.mm,
    opacity=0.3,
    overlays=[source, detector],
    show=False,
)
fluence_figure.show()

The figure objects are Plotly figures; call .show() on any of them to rotate, zoom, and inspect values interactively. The complete executable example includes the same configuration and generated figures.

Three-dimensional skin sample with surface source and detector.

The skin construction and contact footprints. Positive z points into the sample. Transparent layer surfaces show the construction geometry.

Tetrahedral mesh of the skin sample with refinement near the surface contacts.

Tetrahedral mesh refined near the source and detector. Only a subset of edges is displayed; the solve uses the full mesh.

Interpreting the result

  • Skin properties: the preset uses a shared refractive index and fixed coefficients interpolated to 850 nm from Shimojo et al. (2020), doi:10.1117/1.JBO.25.4.045002. Individual skin properties, blood content, and optical behavior vary. Use explicit or spectral materials when needed.

  • Source and boundaries: surface-source power is diffuse power already coupled into the sample. The model does not simulate collimated LED propagation or specular entry losses. Robin effective reflectance is a supplied diffuse partial-current coefficient, not a Fresnel value inferred from refractive index. Finite solvers currently reject internal index jumps.

  • Detector: the circular aperture integrates escaping irradiance using a Lambertian angular approximation. It is not a Fresnel-resolved radiance or a simulation of external detector optics.

  • Accuracy: P1, SP3, and P3 are distinct approximations to transport, not full radiative transfer. Check mesh and source/detector footprint convergence, and compare the intended geometry against an independent transport reference or measurements. Energy balance and footprint-area agreement alone do not establish physical accuracy, especially near illumination. Negative nodal values can occur as numerical artifacts; they are reported, not clipped.

The scientific guide explains the equations and limitations, and the detector convergence guide shows how to examine mesh refinement.

Explore further

  • Example gallery: sample construction, meshes, contact sensors, spectral calculations, and comparisons of transport models.

  • Seven-fiber skin probe: six illumination fibers and one collection aperture on layered skin.

  • Spectral modeling: spectral materials, source power density, detector responsivity, and wavelength-integration convergence.

  • Model selection: choose between the available approximations and review their limits.

Development and citation

To work on the package or build the executable documentation locally:

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

See the contributor guide and changelog. MomentRT is distributed under the MIT license. If you use it in research, cite the version recorded in CITATION.cff.

Metadata

Release files for MomentRT 0.12.0

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.12.0
File Size Uploaded Provenance Actions
momentrt-0.12.0.tar.gz 124.7 kB Without provenance Details for momentrt-0.12.0.tar.gz

Built distribution (wheel)

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

Total release size: 259.1 kB

Release files / momentrt-0.12.0.tar.gz

Download URL momentrt-0.12.0.tar.gz
Size 124.7 kB
Tags Source
SHA-256 checksum
How to use checksums
aba0c3bc0f5b7e1d956e0cf181945c7fc4787d48fb8bc8ac85e560e51fc233d5
BLAKE2b-256 checksum
How to use checksums
3bded8a429027dca5e16ef130122786965eea0017df658b95d5baa71bcb30678
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

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

Download URL momentrt-0.12.0-py3-none-any.whl
Size 134.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c5cd2b15a181ff834839a01d989b9d16d4dc039d5b02374261ed991c4f5b634a
BLAKE2b-256 checksum
How to use checksums
4c9cf8aef98b23c8fc126fd70f09ef9b7817d2d412d551186c128f2e8901ab55
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Security for MomentRT 0.12.0

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