:orphan:

Example gallery
===============

Choose a topic below. Each runnable script includes its calculation settings,
explanations, and figures alongside the code that produces them. Medium
volumes and 3D phase surfaces are interactive: drag to rotate, scroll to zoom,
and hover to inspect values. Angular curves and diagnostic plots use Matplotlib.
Inputs use SI-compatible quantities. Analytical examples describe
infinite-medium first-order scattering; numerical Born-series examples describe
finite samples.

Keep each separate figure in its own code cell: call ``plt.show()`` after
plotting, then insert a ``# %%`` separator and narrative comments before
creating the next figure. Multiple axes comparing related data may share a
single figure. This keeps each gallery image beside its plotting code and
displays figures one at a time when running the scripts locally.

Assign each Plotly figure to a named variable so the gallery can embed it.
When running a script, call ``figure.show(renderer="browser")`` unless
``--no-browser`` is supplied. The documentation builder uses that argument
and exports the figures with a shared local Plotly library, so the downloaded
documentation works offline. Keep static slices as secondary diagnostic views.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

Random media
============

Seeded random fields, numerical ensembles, phase functions, and wavelength dependence.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Generate a reproducible collection of identical spheres in a uniform background. Sphere centres are proposed uniformly within the part of the box that keeps each sphere fully inside. Overlapping proposals are rejected; the generator raises an error if it cannot place every requested sphere within its attempt limit. This is sequential placement, rather than an equilibrium hard-sphere model.">

.. only:: html

  .. image:: /auto_examples/random_media/images/thumb/sphx_glr_random_spheres_thumb.png
    :alt:

  :doc:`/auto_examples/random_media/random_spheres`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Random nonoverlapping spheres</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Compare finite-sample ensemble phase functions for three Gaussian covariance lengths at a vacuum wavelength of 633 nm. The phase function is a probability density per steradian, normalized over solid angle. The corresponding polar-angle density includes the factor 2pisin(theta) and integrates over radians.">

.. only:: html

  .. image:: /auto_examples/random_media/images/thumb/sphx_glr_phase_function_thumb.png
    :alt:

  :doc:`/auto_examples/random_media/phase_function`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Normalized phase function</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Sweep vacuum wavelength at fixed background refractive index, refractive-index fluctuation strength, and Gaussian covariance length. Total scattering and reduced scattering are different observables: forward scattering increases anisotropy and reduces the contribution to mu_s_prime = mu_s * (1 - g).">

.. only:: html

  .. image:: /auto_examples/random_media/images/thumb/sphx_glr_wavelength_dependence_thumb.png
    :alt:

  :doc:`/auto_examples/random_media/wavelength_dependence`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Wavelength dependence of scattering and anisotropy</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Compare two covariance models with the same refractive index standard deviation and the same length parameter. Their definitions differ: Gaussian covariance is sigma_n2  exp(-r2 / (2  ell2)), while exponential covariance is sigma_n2 * exp(-r / ell). Equal parameters therefore do not give identical real-space profiles or scattering spectra. Here, r is the distance between two points in the medium. The covariance describes how their refractive-index fluctuations vary together as that distance increases.">

.. only:: html

  .. image:: /auto_examples/random_media/images/thumb/sphx_glr_covariance_models_thumb.png
    :alt:

  :doc:`/auto_examples/random_media/covariance_models`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Gaussian and exponential spatial covariance</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Explore the full three-dimensional sample for each spatial covariance model. Drag to rotate, scroll to zoom, and hover to inspect the refractive index. Regions with lower refractive index are transparent; regions with higher refractive index are more opaque. Opacity is a display setting, not absorption. Histograms and central slices follow as secondary checks of the same seeded fields.">

.. only:: html

  .. image:: /auto_examples/random_media/images/thumb/sphx_glr_random_medium_thumb.png
    :alt:

  :doc:`/auto_examples/random_media/random_medium`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Visualize seeded three-dimensional random media</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Gaussian probability distributions and spatial covariance are separate choices. These simulations compare Gaussian, exponential and Matérn covariances using the same refractive-index standard deviation and correlation length. The plotted covariance estimate averages products within each realization, then averages independent realizations. No spatial sample mean is removed.">

.. only:: html

  .. image:: /auto_examples/random_media/images/thumb/sphx_glr_theory_random_fields_thumb.png
    :alt:

  :doc:`/auto_examples/random_media/theory_random_fields`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Theory figure: covariance and simulated random fields</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Structured media
================

Build spheres, finite layers, and combined structured and random samples.
Explore how geometry and relative positions affect directional scattering.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Define a finite three-dimensional refractive index field directly rather than drawing it from homogeneous random statistics. The sphere has a constant refractive index inside and is surrounded by a uniform background. The fluctuation array stores n(r) - background_refractive_index: zero outside the sphere, a constant contrast inside. The scattering problem&#x27;s background extends beyond the voxel box; the box is not an additional material boundary.">

.. only:: html

  .. image:: /auto_examples/structured_media/images/thumb/sphx_glr_dielectric_sphere_thumb.png
    :alt:

  :doc:`/auto_examples/structured_media/dielectric_sphere`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A dielectric sphere in a homogeneous background</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Compose finite slabs and shaped inclusions using absolute refractive indices. Later regions replace earlier ones where they overlap. Add a seeded Whittle–Matérn fluctuation field over the complete structure, then solve numerically. The background outside the voxel box stays homogeneous. This is a finite sample with edges, not an infinite planar stack calculation.">

.. only:: html

  .. image:: /auto_examples/structured_media/images/thumb/sphx_glr_structured_media_thumb.png
    :alt:

  :doc:`/auto_examples/structured_media/structured_media`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Layers and scatterers with numerical random fluctuations</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="At first Born order, translating a complete scatterer multiplies its far-field amplitude by a unit-modulus phase. Its intensity is unchanged. Adding a second scatterer changes relative phases and generally introduces azimuth-dependent interference. This figure compares these two effects on fixed voxel masks using the numerical solver, without realization averaging.">

.. only:: html

  .. image:: /auto_examples/structured_media/images/thumb/sphx_glr_theory_directional_interference_thumb.png
    :alt:

  :doc:`/auto_examples/structured_media/theory_directional_interference`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Theory figure: translation and directional interference</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Born orders and interference
============================

Compare cumulative Born orders and inspect coherent amplitude interference.
Field-term diagnostics alone do not certify convergence.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Compare finite-sample effective scattering coefficients through order three. The numerical ensemble retains amplitude interference and sampling errors. Integrated coefficients describe finite samples rather than an infinite medium. Error bars describe realization sampling, not discretization error. Field-term diagnostics alone do not certify convergence.">

.. only:: html

  .. image:: /auto_examples/born_orders/images/thumb/sphx_glr_compare_orders_thumb.png
    :alt:

  :doc:`/auto_examples/born_orders/compare_orders`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Compare numerical Born orders</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Cumulative Born scattering sums complex amplitudes before taking their squared magnitude. Adding isolated-term intensities omits the cross terms and produces a different result. This example compares those two operations on the same seeded finite volume and exposes the signed interference.">

.. only:: html

  .. image:: /auto_examples/born_orders/images/thumb/sphx_glr_born_interference_thumb.png
    :alt:

  :doc:`/auto_examples/born_orders/born_interference`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Coherent interference between Born terms</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Plotting and saving results
===========================

Plot differential scattering and directional phase functions, then save and
restore unitful results with their calculation settings.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Use plotting methods directly on a result, then call plt.show() to display angular Matplotlib figures. The docs embed interactive Plotly volumes and phase surfaces; drag to rotate and scroll to zoom.">

.. only:: html

  .. image:: /auto_examples/results/images/thumb/sphx_glr_result_plots_thumb.png
    :alt:

  :doc:`/auto_examples/results/result_plots`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Result plots and interactive 3D views</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Save a numerical result and restore it with its physical units, complex amplitudes, diagnostics, and original calculation settings. The versioned NumPy archive uses JSON metadata and loads without pickle.">

.. only:: html

  .. image:: /auto_examples/results/images/thumb/sphx_glr_save_load_results_thumb.png
    :alt:

  :doc:`/auto_examples/results/save_load_results`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Save results and inspect calculation provenance</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Numerical validation
====================

Check voxel and angular refinement, ensemble sampling uncertainty, and
finite-size effects independently.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Compare numerical first-order random-volume ensembles as sample size grows at fixed voxel spacing. The coefficients are cross sections divided by sample volume. Sample size, voxel resolution and realization count describe separate sources of uncertainty and must be checked independently.">

.. only:: html

  .. image:: /auto_examples/validation/images/thumb/sphx_glr_finite_size_comparison_thumb.png
    :alt:

  :doc:`/auto_examples/validation/finite_size_comparison`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Finite-sample size convergence</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Refine a fixed physical cube rather than drawing a new random field on each grid. Its first-order amplitude has an independent closed-form reference, so this example isolates voxel midpoint-quadrature error. It does not test higher-order Green-tensor discretization or random-field synthesis.">

.. only:: html

  .. image:: /auto_examples/validation/images/thumb/sphx_glr_grid_refinement_thumb.png
    :alt:

  :doc:`/auto_examples/validation/grid_refinement`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Grid refinement against an exact cube integral</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Increase the number of independent volumes at a fixed grid, covariance, and Born order. Curves show the estimated mean with one-standard-error bars. One realization has unknown error, represented by NaN. Standard errors measure sampling uncertainty, not voxel, quadrature, or finite-size error.">

.. only:: html

  .. image:: /auto_examples/validation/images/thumb/sphx_glr_ensemble_sampling_thumb.png
    :alt:

  :doc:`/auto_examples/validation/ensemble_sampling`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Realization count and sampling uncertainty</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Hold the random volumes, Born order, and voxel grid fixed while increasing polar Gauss-Legendre nodes and uniform azimuth samples. Plot angles are independent of the integration nodes: adding points to an angular plot does not refine the integral. The finest calculation is a numerical reference, not an exact solution, and both quadrature axes need checking independently.">

.. only:: html

  .. image:: /auto_examples/validation/images/thumb/sphx_glr_angular_convergence_thumb.png
    :alt:

  :doc:`/auto_examples/validation/angular_convergence`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Convergence of solid-angle quadrature</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /auto_examples/random_media/index.rst
   /auto_examples/structured_media/index.rst
   /auto_examples/born_orders/index.rst
   /auto_examples/results/index.rst
   /auto_examples/validation/index.rst



.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_