Getting started

Install

Use Python 3.11 or newer. From a checkout of BornSim, create a virtual environment and install the package:

python -m venv .venv
.venv/bin/python -m pip install -e .

First scattering calculation

Define a source, material, and grid, then average independent seeded random volumes. Quantity inputs use the BornSim unit registry; dimensional inputs require explicit units. The wavelength is the vacuum wavelength.

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

source = Source(wavelength=633 * ureg.nanometer)

grid = Grid(
    shape=(8, 8, 8),
    spacing=50 * ureg.nanometer,
)

medium = GaussianMedium(
    background_refractive_index=1.33,
    refractive_index_std=0.01,
    correlation_length=100 * ureg.nanometer,
)

ensemble_sampling = EnsembleSampling(
    realizations=4,
    seed=42,
)

solver = Solver(
    source=source,
    order=3,
)

result = solver.ensemble(
    medium=medium,
    grid=grid,
    ensemble_sampling=ensemble_sampling,
)

print(f"mu_s = {result.mu_s.to('1 / millimeter')}, g = {result.g}, mu_s_prime = {result.mu_s_prime.to('1 / millimeter')}")

The returned coefficients describe finite samples. The ensemble standard errors describe sampling uncertainty, not discretization or finite-size error. See Theory and numerical methods before interpreting higher Born orders.

Interactive three-dimensional views

Plotly is included with BornSim and is the default for 3D views. Stronger refractive-index regions can be made more opaque:

volume = medium.to_volume(
    grid=grid,
    seed=42,
)

medium_figure = volume.plot_3d(
    field='refractive_index',
    opacity_scale='increasing',
)

medium_figure.show()

phase_figure = result.plot_phase_function(view='3d')

phase_figure.show()

The medium view shows physical positions. The phase surface shows scattering directions, with radius and color representing probability density per steradian. Angular and polar plots use Matplotlib.

Next steps

• Guide for physical conventions and the broader package overview.

• Examples for runnable material, plotting, and validation examples.

• Public Python API for keyword-only constructor and method arguments.

• Resources for reproducibility and development checks.