Quick start

from bornsim import EnsembleSampling, Grid, Solver, Source
from bornsim.medium.random_medium import GaussianMedium
from bornsim.units import ureg

grid = Grid(shape=(16, 16, 16), spacing=50 * ureg.nanometer)
medium = GaussianMedium(
    background_refractive_index=1.33,
    refractive_index_std=0.01,
    correlation_length=100 * ureg.nanometer,
)

solver = Solver(
    source=Source(wavelength=633 * ureg.nanometer),
    order=3,
)

result = solver.ensemble(
    medium=medium,
    grid=grid,
    ensemble_sampling=EnsembleSampling(realizations=4, seed=42),
)

print(result.mu_s.to("1 / millimeter"))
print(result.g)
print(result.mu_s_prime.to("1 / millimeter"))
result.plot()

For one fixed structured sample, use solver.solve(target=volume). The result can also be visualized directly:

volume = medium.to_volume(grid=grid, seed=42)
medium_figure = volume.plot_3d(
    field="refractive_index",
    opacity_scale="increasing",
)
phase_figure = solver.solve(target=volume).plot_phase_function(view="3d")
medium_figure.write_html("medium.html", include_plotlyjs=True)
phase_figure.write_html("phase_function.html", include_plotlyjs=True)

What BornSim models

• Media: Gaussian, exponential, and Whittle–Matérn random fields, seeded random spheres, and composable structured geometry.

• Numerics: vector volume-integral propagation with configurable Born order, angular quadrature, grid spacing, and ensemble sampling.

• Results: differential scattering, full directional phase functions, cross sections, uncertainty estimates, saved provenance, and Matplotlib or Plotly visualizations.

• Reliability: integral-equation residuals, explicit refinement reports, and weak-contrast absorbing-sphere validation against Mie theory.

• Absorption and ensembles: passive absorbing materials and random fields, absorption uncertainty, and coherent/diffuse scattering decomposition.

• Units: explicit physical units for wavelengths, lengths, angles, and scattering coefficients through bornsim.units.ureg.

Installation

BornSim requires Python 3.11 or newer.

$ python -m pip install BornSim

For development:

$ git clone https://github.com/MartinPdeS/BornSim.git
$ cd BornSim
$ python -m pip install -e ".[testing,documentation]"
$ python -m pytest tests

Learn more

• Documentation — theory, API reference, numerical conventions, and visualization guidance.

• Examples — random media, structured samples, Born orders, validation, and result plots.

• Medium visualization guide — interactive 3D volume and phase-function views.

• Repository — issues and contributions.

Scientific scope

BornSim uses the linearized dielectric contrast \(\delta\varepsilon \approx 2 n_0 \delta n\). Its coefficients describe finite numerical samples and are not automatically intrinsic infinite-medium transport coefficients. Check grid, angular, sample-size, synthesis-box, and ensemble convergence before interpreting results quantitatively.

License

BornSim is released under the MIT License. See LICENSE.