Examples#
Browse runnable examples by topic: random media, structured media, Born orders and interference, plotting and saving results, and numerical validation. Each gallery example includes a three-dimensional view of its input medium. Ensemble examples show a labelled seeded realization on the calculation grid; that view is one finite sample, rather than the ensemble average. Comparisons of covariance models, correlation lengths, or sphere arrangements show each medium separately. Each figure has its own code cell and output, including individual three-dimensional views in comparisons. The Medium visualization guide explains how to inspect input voxel fields and choose spatial views.
Seeded fields, covariance models, and wavelength dependence.
Spheres, layers, and coherent directional scattering.
Cumulative scattering and interference between complex amplitudes.
Plot, save, and reload unitful scattering results.
Grid, angular, ensemble, and finite-size comparisons.
Interactive 3D volumes, opacity, slices, and voxel geometry.
Random media#
Random nonoverlapping spheres generates seeded, fully contained nonoverlapping spheres with an explicit count, radius, and refractive indices.
Start with Visualize seeded three-dimensional random media for seeded samples, and Wavelength dependence of scattering and anisotropy for numerical finite-sample ensemble coefficients across wavelengths.
Gaussian and exponential spatial covariance compares Gaussian and exponential spatial covariance at the same length parameter, showing both covariance profiles and their numerical ensemble phase functions. These length parameters have different definitions; equal values do not describe identical statistics.
Visualize seeded three-dimensional random media leads with interactive Gaussian and exponential volumes whose higher refractive index regions are more opaque. Central slices and voxel histograms follow as diagnostic checks. It distinguishes the Gaussian one-point probability distribution from the choice of spatial covariance, and explains why a finite correlated sample need not have exactly the ensemble mean or variance.
Structured media#
Medium is the abstract interface. GaussianMedium describes statistically
homogeneous fluctuations; StructuredMedium composes geometric materials. Volume accepts an explicit
three-dimensional field and can therefore represent spatially structured
media. Its background refractive index is uniform, while its fluctuation array may vary
from voxel to voxel.
A dielectric sphere in a homogeneous background builds two constant refractive index spheres in a homogeneous background and plots their voxelized geometry, full directional 3D phase density and a selected physical meridian. The curved interface is voxelized and the dielectric contrast remains linearized; the example does not replace an exact Mie calculation.
Layers and scatterers with numerical random fluctuations combines finite layers, a sphere, and additive seeded random fluctuations in a custom voxel field.
Normalized phase function#
This example compares analytical first-order scattering for three Gaussian covariance lengths at a vacuum wavelength of 633 nm. The phase function is the differential scattering coefficient divided by the total scattering coefficient:
Here p is a probability density per steradian, not per polar angle.
For this axially symmetric model, the polar-angle density is
2*pi*p(theta)*sin(theta) and integrates to one with respect to angle in
radians. Its values retain units of inverse radians even when the plot’s
horizontal axis displays degrees. The mean cosine of the distribution is
the anisotropy g.
See Normalized phase function for the plot and its top-level code.
A zero scattering coefficient has no normalized phase function. This example uses the analytical infinite-medium model. A single random volume’s angular cut is insufficient to normalize a phase function over solid angle.
Result plots and interactive 3D directions#
The medium occupies three spatial dimensions. Scattering directions lie on
the unit sphere and are described by polar angle theta and azimuth
phi. For the isotropic analytical medium under unpolarized illumination,
the incident beam defines the +z axis and rotational symmetry gives
p(theta, phi) = p(theta). This symmetry does not mean scattering is equally
likely in all directions: the phase function can still be strongly forward
peaked. The one-dimensional angular curve describes the full axisymmetric
distribution on the sphere.
Result.phase_function provides normalized per-steradian quantities.
Result.plot_phase_function plots angular curves, a polar meridian cut, or
a 3D surface whose radius and color are the phase-function value. The surface
is a visualization in direction space; its coordinates are not positions
inside the medium. The 3D view requires angles spanning 0 to pi and defaults
to the highest available cumulative order.
For full-volume solves and numerical ensembles, the 3D surface retains
both theta and phi without
azimuth averaging. A fixed realization or a structured medium can therefore
show rotational asymmetry. Multiple realizations retain their intensity
average. Angular and polar plots select sampled meridians; call
result.azimuth_average() explicitly for averaged curves.
Only explicit single-volume angular cuts lack the integrated coefficient
needed for phase normalization. Their differential scattering and field-term
norms can still be plotted directly.
import matplotlib.pyplot as plt
result.plot()
result.plot_phase_function()
result.plot_phase_function(view='polar')
phase_figure = result.plot_phase_function(view='3d')
phase_figure.show()
numerical.plot_field_norms()
plt.show()
Ensemble plot() retains differential-scattering standard-error bars.
Normalized phase plots do not infer errors by dividing those bars by the
mean total coefficient: uncertainty in a ratio also depends on numerator-
denominator covariance, which is not retained in the result.
See Result plots and interactive 3D views for direct result plotting calls and Matplotlib angular figures and an interactive 3D phase-function surface. Sphinx Gallery executes the examples and embeds interactive Plotly volumes and surfaces alongside their cells when the documentation is built.
Coherent terms and reusable results#
Compare numerical Born orders plots ensemble scattering through successive Born orders with sampling-error bars and per-realization field norms. Coherent interference between Born terms shows why cumulative intensities cannot be reconstructed by summing isolated-term intensities: complex Born amplitudes interfere within each incident polarization. Its second panel shows the signed interference contribution for a fixed volume.
Save results and inspect calculation provenance saves and restores a unitful numerical result, inspects its provenance, and plots the restored data. It uses a temporary directory and retains complex amplitudes. Archives preserve result data and settings; they do not store the original voxel field.
Numerical validation#
The validation gallery separates four questions. None is answered by decreasing successive Born terms alone.
Grid refinement against an exact cube integral refines a fixed physical cube and compares its first-order amplitude with an exact volume integral. It isolates midpoint-quadrature error without changing the input field.
Convergence of solid-angle quadrature increases polar and azimuth integration independently on identical seeded volumes. Plot sampling is separate from solid-angle quadrature.
Realization count and sampling uncertainty increases independent realization count at fixed geometry. Standard errors describe sampling uncertainty; they do not include discretization or finite-size error.
Finite-sample size convergence compares first-order finite ensembles of increasing size with the analytical infinite-medium model. Finite windows, spectral synthesis, and limited resolution can produce differences that remain outside the sampling error bars.
Theory illustrations#
The Theory and numerical methods section embeds simulated figures with the associated equations. Theory figure: covariance and simulated random fields compares seeded field texture and empirical covariance with the discrete spectral and continuum predictions. Theory figure: translation and directional interference verifies first-order translation invariance and shows how relative sphere positions introduce azimuth-dependent interference. Both examples expose their grids, materials, seeds and numerical settings.