Choosing a mesh for detector collection#
MeshConvergence compares detector power and footprint
sampling across explicit finite meshes. It keeps the sample, source,
detector apertures, wavelength, and boundaries fixed, returning a
DetectorConvergenceResult without changing the original configuration.
The study uses the simulation source wavelength; run separate studies for
multiple wavelengths.
simulation.convergence_study(...) remains a compatibility alias for
simulation.mesh_convergence(...) with the same arguments and behavior.
See the worked refinement example for comparison plots and a
fluence volume with instrument overlays.
For progress during mesh generation and solves, enable Python logging before running the study. This reports timings, sampled areas, detector powers, and unresolved levels:
import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger("MomentRT.convergence").setLevel(logging.INFO)
Running a study#
Configure a finite P1, SP3, or P3 simulation with at least one named detector,
then supply meshes from coarse to fine:
study = MomentRT.MeshConvergence(
simulation=simulation,
mesh_shapes=[
(9, 7, 7),
(13, 10, 10),
(17, 13, 13),
(25, 19, 19),
],
power_rtol=0.01,
area_rtol=0.02,
power_atol=0 * ureg.watt,
required_consecutive=2,
)
result = study.run()
print(result.summary())
figure = result.plot(
power_unit="mW",
area_unit="mm^2",
show=False,
)
print(f"Recommended mesh shape: {result.recommended_shape}")
By default, the study prints a row after each mesh is generated and solved.
The table reports detector powers in microwatts, relative changes from the
previous level, footprint-area errors, per-level elapsed time, and diagnostics.
Each level time includes mesh generation, solving, and detector measurements;
the total time also includes study setup. Set progress=False
to suppress the table.
The plot shades the power tolerance around each finest-mesh detector value (including any absolute power tolerance) and the area tolerances around each geometric footprint. The bands alone do not prove convergence: the study also checks adjacent refinements, failures, and negative outputs.
Every shape contains three node counts of at least two. Each successive mesh must refine at least one axis and coarsen none. At least two levels are required, but two consecutive passing refinements need at least three resolved levels. The study evaluates all supplied levels rather than stopping at the first apparent plateau.
For interface-fitted tetrahedra, give global target sizes from coarse to fine. Optional contact refinement applies the same local element target near the source disks and all detector apertures at every level:
study = simulation.mesh_convergence(
mesh_resolutions=[
1.5 * ureg.mm,
1.0 * ureg.mm,
0.7 * ureg.mm,
],
contact_resolution=0.25 * ureg.mm,
contact_distance=0.5 * ureg.mm,
power_rtol=0.02,
area_rtol=0.03,
)
print(f"Recommended target resolution: {study.recommended_resolution}")
The global sizes must decrease strictly. A contact target must be no larger
than any global target and is applied within contact_distance of each disk,
with a gradual transition to the global size. For a uniform full-face source,
the local rule covers detectors; the source already spans the face. Each level
is generated from the original sample and its own contact geometry. The report
continues to compare sampled source and aperture areas with their geometric
areas and detector power across levels. Target element size is not a strict
bound on every tetrahedron edge, and satisfying these criteria does not
establish transport accuracy.
These tolerances are numerical choices, not claims about transport-model error. A study uses the configured source wavelength. Repeat it at demanding wavelengths when assessing a spectral experiment.
Power and area criteria#
Let \(P_{d,k}\) be detector power at mesh level \(k\) and
\(A_{d,k}\) the sampled detector area. Its geometric disk area is
\(A_d=\pi r_d^2\). The source has sampled area \(A_{s,k}\) and
geometric area \(A_s\): a disk area for SurfaceSource or the
complete face area for UniformSurfaceSource.
Both errors compare sampled areas with geometry, rather than only with the previous mesh. Two coarse meshes could sample the same incorrect area. Source normalization preserves incoming power even when a footprint is poorly sampled, so energy conservation cannot replace this area check.
Successive powers pass when
The report also records relative change \(|P_{d,k}-P_{d,k-1}|/|P_{d,k}|\). The first value is NaN because no previous estimate exists. Two zero powers have relative change zero. A change to zero from nonzero power has infinite relative change, but may still pass an explicitly supplied absolute tolerance. Missing observations never pass.
Defaults are power_rtol=0.01, area_rtol=0.02, zero absolute
power tolerance, and required_consecutive=2. A nonzero
power_atol requires an explicit power quantity; choose it according to
the numerical accuracy needed for a small signal.
Recommendation rule#
A level passes only when every detector passes its successive power check,
all source and detector area errors are within area_rtol, and there
are no unresolved footprints or reported negative fields at that level.
The finest end of the sequence must have at least
required_consecutive uninterrupted passing refinements. A later failure
discards an earlier apparent plateau. Among candidates in that final stable
sequence, the first acceptable mesh must also agree with the final level’s
detector powers:
This prevents small successive changes from accumulating into a large discrepancy with the finest supplied observation. The recommendation is evidence from a finite sequence, not a rigorous error bound relative to an infinitely refined solution.
recommended_mesh is None and converged is False when the criteria are
not met. recommended_shape applies to Cartesian meshes;
recommended_resolution reports the target size for a generated tetrahedral
mesh. The final mesh is not automatically declared sufficient.
Inspecting the report#
The report retains:
meshes, storagemesh_shapes,mesh_resolutions,node_counts, and actualtetrahedron_counts.Unit-bearing
detector_power[name],detector_sampled_area[name], anddetector_geometric_area[name].source_sampled_areaandsource_geometric_area.power_relative_change[name]andpower_relative_to_finest[name].detector_area_relative_error[name]andsource_area_relative_error.meets_tolerances,stable_refinements, andlevel_errors.results, containing the available finite solution at each level.
records groups quantities and diagnostics by mesh level:
for record in study.records:
measurement = record["detectors"]["reflection"]
print(f"Mesh: {record['mesh_shape']}")
print(f"Collected power: {measurement['collected_power'].to('mW'):~P}")
print(f"Aperture area error: {measurement['area_relative_error']:.2%}")
The plot compares powers and sampled footprint areas against mesh node count; dashed area curves are the geometric references. Missing observations remain gaps.
Unresolved levels and configuration errors#
If no quadrature point samples a source disk, the level records
SourceResolutionError, source area zero, and results[k]=None.
Detector powers and areas for that unsolved level are unknown and NaN.
The study continues on finer meshes.
If a solve succeeds but an aperture contains no quadrature points,
DetectorResolutionError is recorded for that detector. Its sampled area
is zero and its power is unknown. Other measurements remain available.
An unresolved level breaks a stable sequence. Negative nodal fluence or
escaping irradiance in an aperture is preserved and flagged rather than
clipped or accepted for a recommendation.
Both resolution exceptions inherit from ValueError, preserving existing exception handling for single solves. Other errors, such as an aperture outside the sample or unsupported index mismatch, propagate as configuration errors rather than being disguised as coarse-mesh failures.
This study assesses resolution of the tested observables and footprints. It does not establish P1, SP3, or P3 accuracy against RTE, validate material spectra or detector optics, or guarantee convergence of unrelated local field values. See Finite-sample P1 solver and Finite-aperture surface detectors for those distinctions.
Performance measurements#
The repository includes a repeatable finite spectral sweep benchmark. For example:
.venv/bin/python tools/benchmark_sweeps.py --solver p1 --shape 9 9 9 --wavelengths 3
.venv/bin/python tools/benchmark_sweeps.py --solver sp3 --shape 15 15 11 --wavelengths 5
The JSON output records the mesh, solver, software versions, geometry preparation
and individual solve times, and the peak memory tracked by Python’s
tracemalloc during the sweep and, where available, peak process RSS since
process start (including imports and setup). Traced memory may exclude native
solver allocations; peak RSS is unavailable on Windows. Compare runs on the same machine and software
configuration; these illustrative cases do not establish numerical convergence.
For isolated tetrahedral mesh and direct-solver scaling, use:
.venv/bin/python tools/benchmark_scaling.py \
--solvers p1 sp3 p3 \
--resolutions-mm 2.0 1.5 1.0
Each solver and target-size pair runs in a fresh process. The JSON report includes mesh generation time, solve time, node and tetrahedron counts, and process peak RSS. RSS includes imports, mesh generation, assembly, and solve; compare runs on the same machine and software configuration. Target size is only a mesher request, so use the reported element counts when comparing meshes. The results characterize current direct-solver scaling; they do not estimate accuracy or recommend a mesh.