BornSim 0.3.0__tar.gz → 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of BornSim might be problematic. Click here for more details.

Files changed (122) hide show
  1. {bornsim-0.3.0 → bornsim-0.5.0}/.zenodo.json +2 -2
  2. {bornsim-0.3.0 → bornsim-0.5.0/BornSim.egg-info}/PKG-INFO +2 -1
  3. {bornsim-0.3.0 → bornsim-0.5.0}/BornSim.egg-info/SOURCES.txt +1 -5
  4. {bornsim-0.3.0 → bornsim-0.5.0}/CITATION.cff +1 -1
  5. {bornsim-0.3.0/BornSim.egg-info → bornsim-0.5.0}/PKG-INFO +2 -1
  6. bornsim-0.5.0/bornsim/_version.py +1 -0
  7. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/angular_data.py +6 -4
  8. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/ensemble.py +1 -2
  9. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/ensemble_sampling.py +1 -1
  10. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/geometry.py +184 -126
  11. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/grid.py +47 -2
  12. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/medium/random_medium.py +1 -2
  13. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/medium/random_spheres.py +1 -2
  14. bornsim-0.5.0/bornsim/results.py +1210 -0
  15. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/rotation.py +24 -4
  16. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/sampling.py +129 -13
  17. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/series.py +1 -2
  18. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/solver.py +20 -12
  19. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/units.py +10 -1
  20. bornsim-0.5.0/bornsim/volume.py +695 -0
  21. {bornsim-0.3.0 → bornsim-0.5.0}/conda.recipe/meta.yaml +1 -1
  22. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/random_media/covariance_models.py +2 -2
  23. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/random_media/phase_function.py +3 -3
  24. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/random_media/theory_random_fields.py +3 -3
  25. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/random_media/wavelength_dependence.py +2 -2
  26. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/structured_media/structured_media.py +37 -24
  27. bornsim-0.5.0/docs/source/api.rst +211 -0
  28. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/development.rst +8 -14
  29. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/medium_visualization.rst +18 -18
  30. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/research.rst +3 -3
  31. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/theory.rst +3 -2
  32. {bornsim-0.3.0 → bornsim-0.5.0}/pyproject.toml +3 -2
  33. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_configuration.py +109 -0
  34. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_directional_api.py +11 -29
  35. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_geometry.py +56 -0
  36. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_medium_composition.py +87 -0
  37. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_medium_metadata.py +38 -0
  38. bornsim-0.5.0/tests/numerical/test_rotation.py +140 -0
  39. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_volume_plotting.py +50 -107
  40. {bornsim-0.3.0 → bornsim-0.5.0}/tools/check_wheel.py +0 -5
  41. bornsim-0.3.0/bornsim/_archives.py +0 -110
  42. bornsim-0.3.0/bornsim/_result_plotting.py +0 -445
  43. bornsim-0.3.0/bornsim/_result_validation.py +0 -86
  44. bornsim-0.3.0/bornsim/_validation.py +0 -10
  45. bornsim-0.3.0/bornsim/_version.py +0 -1
  46. bornsim-0.3.0/bornsim/_volume_plotting.py +0 -395
  47. bornsim-0.3.0/bornsim/results.py +0 -627
  48. bornsim-0.3.0/bornsim/volume.py +0 -242
  49. bornsim-0.3.0/docs/source/api.rst +0 -130
  50. {bornsim-0.3.0 → bornsim-0.5.0}/.coveragerc +0 -0
  51. {bornsim-0.3.0 → bornsim-0.5.0}/.pre-commit-config.yaml +0 -0
  52. {bornsim-0.3.0 → bornsim-0.5.0}/BornSim.egg-info/dependency_links.txt +0 -0
  53. {bornsim-0.3.0 → bornsim-0.5.0}/BornSim.egg-info/requires.txt +0 -0
  54. {bornsim-0.3.0 → bornsim-0.5.0}/BornSim.egg-info/top_level.txt +0 -0
  55. {bornsim-0.3.0 → bornsim-0.5.0}/CONTRIBUTING.md +0 -0
  56. {bornsim-0.3.0 → bornsim-0.5.0}/LICENSE +0 -0
  57. {bornsim-0.3.0 → bornsim-0.5.0}/MANIFEST.in +0 -0
  58. {bornsim-0.3.0 → bornsim-0.5.0}/README.rst +0 -0
  59. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/__init__.py +0 -0
  60. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/api.py +0 -0
  61. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/directions.py +0 -0
  62. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/green.py +0 -0
  63. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/material.py +0 -0
  64. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/medium/__init__.py +0 -0
  65. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/medium/base.py +0 -0
  66. {bornsim-0.3.0 → bornsim-0.5.0}/bornsim/source.py +0 -0
  67. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/README.rst +0 -0
  68. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/born_orders/README.rst +0 -0
  69. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/born_orders/born_interference.py +0 -0
  70. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/born_orders/compare_orders.py +0 -0
  71. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/random_media/README.rst +0 -0
  72. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/random_media/random_medium.py +0 -0
  73. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/random_media/random_spheres.py +0 -0
  74. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/results/README.rst +0 -0
  75. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/results/result_plots.py +0 -0
  76. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/results/save_load_results.py +0 -0
  77. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/structured_media/README.rst +0 -0
  78. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/structured_media/dielectric_sphere.py +0 -0
  79. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/structured_media/theory_directional_interference.py +0 -0
  80. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/validation/README.rst +0 -0
  81. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/validation/angular_convergence.py +0 -0
  82. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/validation/ensemble_sampling.py +0 -0
  83. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/validation/finite_size_comparison.py +0 -0
  84. {bornsim-0.3.0 → bornsim-0.5.0}/docs/examples/validation/grid_refinement.py +0 -0
  85. {bornsim-0.3.0 → bornsim-0.5.0}/docs/images/branding-prompts.rst +0 -0
  86. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/_static/favicon.png +0 -0
  87. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/_static/logo.png +0 -0
  88. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/_static/phase_function.svg +0 -0
  89. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/conf.py +0 -0
  90. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/examples.rst +0 -0
  91. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/gallery_config.py +0 -0
  92. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/getting_started.rst +0 -0
  93. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/guide.rst +0 -0
  94. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/index.rst +0 -0
  95. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/overview.rst +0 -0
  96. {bornsim-0.3.0 → bornsim-0.5.0}/docs/source/resources.rst +0 -0
  97. {bornsim-0.3.0 → bornsim-0.5.0}/makefile +0 -0
  98. {bornsim-0.3.0 → bornsim-0.5.0}/pytest.ini +0 -0
  99. {bornsim-0.3.0 → bornsim-0.5.0}/setup.cfg +0 -0
  100. {bornsim-0.3.0 → bornsim-0.5.0}/tests/analytical/reference.py +0 -0
  101. {bornsim-0.3.0 → bornsim-0.5.0}/tests/analytical/test_model.py +0 -0
  102. {bornsim-0.3.0 → bornsim-0.5.0}/tests/analytical/test_numerical_reference.py +0 -0
  103. {bornsim-0.3.0 → bornsim-0.5.0}/tests/conftest.py +0 -0
  104. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_api.py +0 -0
  105. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_api_keywords.py +0 -0
  106. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_api_ownership.py +0 -0
  107. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_api_scope.py +0 -0
  108. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_directions.py +0 -0
  109. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_engine.py +0 -0
  110. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_explicit_physics.py +0 -0
  111. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_media.py +0 -0
  112. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_plot_contract.py +0 -0
  113. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_random_spheres.py +0 -0
  114. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_result.py +0 -0
  115. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_result_contract.py +0 -0
  116. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_series.py +0 -0
  117. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_unit_contract.py +0 -0
  118. {bornsim-0.3.0 → bornsim-0.5.0}/tests/numerical/test_units.py +0 -0
  119. {bornsim-0.3.0 → bornsim-0.5.0}/tests/packaging/test_release_tools.py +0 -0
  120. {bornsim-0.3.0 → bornsim-0.5.0}/tools/check_release.py +0 -0
  121. {bornsim-0.3.0 → bornsim-0.5.0}/tools/next_release_version.py +0 -0
  122. {bornsim-0.3.0 → bornsim-0.5.0}/tools/release_tag.py +0 -0
@@ -8,11 +8,11 @@
8
8
  }
9
9
  ],
10
10
  "license": "mit",
11
- "version": "0.3.0",
11
+ "version": "0.5.0",
12
12
  "keywords": [
13
13
  "Born approximation",
14
14
  "light scattering",
15
15
  "random media"
16
16
  ],
17
- "publication_date": "2026-10-09"
17
+ "publication_date": "2026-10-13"
18
18
  }
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: BornSim
3
- Version: 0.3.0
3
+ Version: 0.5.0
4
4
  Summary: Vector Born-series scattering from continuous random dielectric media
5
5
  Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
6
6
  License-Expression: MIT
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3
12
12
  Classifier: Programming Language :: Python :: 3.11
13
13
  Classifier: Programming Language :: Python :: 3.12
14
14
  Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Programming Language :: Python :: 3.14
15
16
  Classifier: Topic :: Scientific/Engineering :: Physics
16
17
  Classifier: Topic :: Scientific/Engineering :: Visualization
17
18
  Requires-Python: >=3.11
@@ -15,12 +15,7 @@ BornSim.egg-info/dependency_links.txt
15
15
  BornSim.egg-info/requires.txt
16
16
  BornSim.egg-info/top_level.txt
17
17
  bornsim/__init__.py
18
- bornsim/_archives.py
19
- bornsim/_result_plotting.py
20
- bornsim/_result_validation.py
21
- bornsim/_validation.py
22
18
  bornsim/_version.py
23
- bornsim/_volume_plotting.py
24
19
  bornsim/angular_data.py
25
20
  bornsim/api.py
26
21
  bornsim/directions.py
@@ -104,6 +99,7 @@ tests/numerical/test_plot_contract.py
104
99
  tests/numerical/test_random_spheres.py
105
100
  tests/numerical/test_result.py
106
101
  tests/numerical/test_result_contract.py
102
+ tests/numerical/test_rotation.py
107
103
  tests/numerical/test_series.py
108
104
  tests/numerical/test_unit_contract.py
109
105
  tests/numerical/test_units.py
@@ -2,7 +2,7 @@ cff-version: 1.2.0
2
2
  message: "If you use BornSim in research, please cite the software version used."
3
3
  title: "BornSim"
4
4
  type: software
5
- version: "0.3.0"
5
+ version: "0.5.0"
6
6
  authors:
7
7
  - family-names: "Poinsinet de Sivry-Houle"
8
8
  given-names: "Martin"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: BornSim
3
- Version: 0.3.0
3
+ Version: 0.5.0
4
4
  Summary: Vector Born-series scattering from continuous random dielectric media
5
5
  Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
6
6
  License-Expression: MIT
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3
12
12
  Classifier: Programming Language :: Python :: 3.11
13
13
  Classifier: Programming Language :: Python :: 3.12
14
14
  Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Programming Language :: Python :: 3.14
15
16
  Classifier: Topic :: Scientific/Engineering :: Physics
16
17
  Classifier: Topic :: Scientific/Engineering :: Visualization
17
18
  Requires-Python: >=3.11
@@ -0,0 +1 @@
1
+ __version__ = version = "0.5.0"
@@ -296,9 +296,10 @@ class AngularData:
296
296
  def plot(self, *, terms=False, log_y=False, title=None, azimuth=0):
297
297
  """Plot one sampled meridian, or an explicitly averaged curve."""
298
298
 
299
- from ._result_plotting import _ResultPlotter
299
+ from .results import Result
300
300
 
301
- return _ResultPlotter(result=self).plot(
301
+ return Result._plot_differential(
302
+ result=self,
302
303
  terms=terms,
303
304
  log_y=log_y,
304
305
  title=title,
@@ -308,9 +309,10 @@ class AngularData:
308
309
  def plot_phase_function(self, *, view="angular", order=None, log_y=False, azimuth=0, backend=None):
309
310
  """Plot normalized directional densities with the same Result interface."""
310
311
 
311
- from ._result_plotting import _ResultPlotter
312
+ from .results import Result
312
313
 
313
- return _ResultPlotter(result=self).plot_phase_function(
314
+ return Result._plot_phase_function(
315
+ result=self,
314
316
  view=view,
315
317
  order=order,
316
318
  log_y=log_y,
@@ -2,13 +2,12 @@
2
2
 
3
3
  from typing import Any
4
4
  import numpy as np
5
- from ._validation import _integer
6
5
  from .medium import Medium
7
6
  from .grid import Grid
8
7
  from .sampling import AngularSampling
9
8
  from .ensemble_sampling import EnsembleSampling
10
9
  from .series import BornSeries
11
- from .units import Quantity, validate_units, ureg
10
+ from .units import Quantity, _integer, validate_units, ureg
12
11
 
13
12
 
14
13
  def ensemble_scattering(
@@ -2,7 +2,7 @@
2
2
 
3
3
  from dataclasses import dataclass
4
4
  from collections.abc import Sequence
5
- from ._validation import _integer
5
+ from .units import _integer
6
6
 
7
7
 
8
8
  @dataclass(frozen=True, kw_only=True, init=False)
@@ -6,14 +6,16 @@ law. Interfaces are sampled at cell centres without subvoxel averaging.
6
6
  """
7
7
 
8
8
  from dataclasses import asdict, dataclass, field, replace
9
+ from copy import deepcopy
9
10
  import numpy as np
11
+ from numpy.typing import NDArray
10
12
  from typing import Any
11
13
  from .units import _refractive_index_values, Quantity, validate_units, ureg
12
14
  from .medium import Medium
13
15
  from .medium.random_medium import RandomFieldMedium
14
16
  from .volume import Volume
15
17
  from .grid import Grid
16
- from .rotation import Rotation
18
+ from .rotation import Rotation, RotationInput, RotationMatrix
17
19
  from .material import Material
18
20
  import warnings
19
21
 
@@ -38,6 +40,13 @@ def _axis(*, value):
38
40
  return int(value)
39
41
 
40
42
 
43
+ class _RotationUnset:
44
+ pass
45
+
46
+
47
+ _ROTATION_UNSET = _RotationUnset()
48
+
49
+
41
50
  @dataclass(frozen=True, kw_only=True)
42
51
  class _Transformable:
43
52
  """Return transformed immutable shapes in global SI coordinates."""
@@ -46,6 +55,43 @@ class _Transformable:
46
55
  refractive_index: float | None = None
47
56
  material: Material | None = None
48
57
 
58
+ def _validate_transform(
59
+ self,
60
+ *,
61
+ rotation: RotationInput | _RotationUnset = _ROTATION_UNSET,
62
+ ) -> None:
63
+ material = Material._resolve(material=self.material, refractive_index=self.refractive_index)
64
+
65
+ object.__setattr__(self, "material", material)
66
+
67
+ object.__setattr__(self, "refractive_index", material.refractive_index)
68
+
69
+ validate_units(
70
+ self.centre,
71
+ unit="meter",
72
+ name="centre",
73
+ scalar=False,
74
+ )
75
+
76
+ if np.shape(self.centre) != (3,):
77
+ raise ValueError("centre must contain three coordinates.")
78
+
79
+ if np.any(~np.isfinite(self.centre)):
80
+ raise ValueError("centre must be finite.")
81
+
82
+ if not isinstance(rotation, _RotationUnset):
83
+ matrix = Rotation._matrix(rotation=rotation)
84
+
85
+ object.__setattr__(
86
+ self,
87
+ "rotation",
88
+ (
89
+ (float(matrix[0, 0]), float(matrix[0, 1]), float(matrix[0, 2])),
90
+ (float(matrix[1, 0]), float(matrix[1, 1]), float(matrix[1, 2])),
91
+ (float(matrix[2, 0]), float(matrix[2, 1]), float(matrix[2, 2])),
92
+ ),
93
+ )
94
+
49
95
  def _replaced(self, *, settings: dict[str, Any]) -> "_Transformable":
50
96
  """Clone geometry while retaining unit-bearing lengths."""
51
97
 
@@ -73,12 +119,13 @@ class _Transformable:
73
119
 
74
120
  return self._replaced(settings={"centre": centre, "refractive_index": None})
75
121
 
76
- def rotated(self, *, rotation: Rotation | np.ndarray, about: Quantity | None = None) -> "_Transformable":
122
+ def _rotation_settings(self, *, matrix: NDArray[np.float64]) -> dict[str, RotationMatrix]:
123
+ return {}
124
+
125
+ def rotated(self, *, rotation: RotationInput, about: Quantity | None = None) -> "_Transformable":
77
126
  """Return a rotated shape around its centre or an explicit global point.
78
127
 
79
- Rotation is active: R maps local column coordinates to the global
80
- frame. Successive world rotations compose as R_new @ R_existing.
81
- Membership uses local row coordinates (positions-centre) @ R.
128
+ See :class:`bornsim.rotation.Rotation` for the rotation convention.
82
129
  """
83
130
 
84
131
  matrix = Rotation._matrix(rotation=rotation)
@@ -105,14 +152,28 @@ class _Transformable:
105
152
 
106
153
  settings: dict[str, Any] = {"centre": centre, "refractive_index": None}
107
154
 
108
- if hasattr(self, "rotation"):
109
- settings["rotation"] = tuple(tuple(row) for row in matrix @ np.asarray(self.rotation))
155
+ settings.update(self._rotation_settings(matrix=matrix))
110
156
 
111
157
  return self._replaced(settings=settings)
112
158
 
113
159
 
160
+ class _RotatableTransformable(_Transformable):
161
+ rotation: RotationInput
162
+
163
+ def _rotation_settings(self, *, matrix: NDArray[np.float64]) -> dict[str, RotationMatrix]:
164
+ rotated = matrix @ np.asarray(self.rotation)
165
+
166
+ return {
167
+ "rotation": (
168
+ (float(rotated[0, 0]), float(rotated[0, 1]), float(rotated[0, 2])),
169
+ (float(rotated[1, 0]), float(rotated[1, 1]), float(rotated[1, 2])),
170
+ (float(rotated[2, 0]), float(rotated[2, 1]), float(rotated[2, 2])),
171
+ )
172
+ }
173
+
174
+
114
175
  @dataclass(frozen=True, kw_only=True)
115
- class Layer(_Transformable):
176
+ class Layer(_RotatableTransformable):
116
177
  """A slab with absolute refractive index inside ``lower <= local[axis] < upper``.
117
178
 
118
179
  Bounds are SI lengths in the slab local frame, offset by centre and
@@ -120,6 +181,9 @@ class Layer(_Transformable):
120
181
  z (2); x and y are 0 and 1. The half-open interval gives adjacent slabs an
121
182
  unambiguous interface. The slab spans the voxel box in transverse axes;
122
183
  it represents a finite sample, not an infinite planar background.
184
+
185
+ Use :meth:`from_center_and_thickness` to specify a slab by its centre and
186
+ full thickness instead of its local lower and upper bounds.
123
187
  """
124
188
 
125
189
  lower: Quantity
@@ -128,7 +192,40 @@ class Layer(_Transformable):
128
192
  material: Material | None = None
129
193
  axis: int = 2
130
194
  centre: Quantity = field(default_factory=lambda: np.zeros(3) * ureg.meter)
131
- rotation: tuple = ((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))
195
+ rotation: RotationInput = ((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))
196
+
197
+ @classmethod
198
+ def from_center_and_thickness(
199
+ cls,
200
+ *,
201
+ thickness: Quantity,
202
+ centre: Quantity,
203
+ refractive_index: float | None = None,
204
+ material: Material | None = None,
205
+ axis: int = 2,
206
+ rotation: RotationInput = ((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0)),
207
+ ) -> "Layer":
208
+ """Create a slab from its centre and full thickness along ``axis``."""
209
+
210
+ validate_units(
211
+ thickness,
212
+ unit="meter",
213
+ name="thickness",
214
+ scalar=True,
215
+ )
216
+
217
+ if not np.isfinite(thickness) or thickness <= 0:
218
+ raise ValueError("thickness must be finite and positive.")
219
+
220
+ return cls(
221
+ lower=-thickness / 2,
222
+ upper=thickness / 2,
223
+ centre=centre,
224
+ refractive_index=refractive_index,
225
+ material=material,
226
+ axis=axis,
227
+ rotation=rotation,
228
+ )
132
229
 
133
230
  def __post_init__(self) -> None:
134
231
  validate_units(
@@ -151,28 +248,9 @@ class Layer(_Transformable):
151
248
  if np.any(~np.isfinite(self.upper)):
152
249
  raise ValueError("upper must be finite.")
153
250
 
154
- material = Material._resolve(material=self.material, refractive_index=self.refractive_index)
155
-
156
- object.__setattr__(self, "material", material)
157
-
158
- object.__setattr__(self, "refractive_index", material.refractive_index)
159
-
160
251
  object.__setattr__(self, "axis", _axis(value=self.axis))
161
252
 
162
- validate_units(
163
- self.centre,
164
- unit="meter",
165
- name="centre",
166
- scalar=False,
167
- )
168
-
169
- if np.shape(self.centre) != (3,):
170
- raise ValueError("centre must contain three coordinates.")
171
-
172
- if np.any(~np.isfinite(self.centre)):
173
- raise ValueError("centre must be finite.")
174
-
175
- object.__setattr__(self, "rotation", tuple(tuple(row) for row in Rotation._matrix(rotation=self.rotation)))
253
+ self._validate_transform(rotation=self.rotation)
176
254
 
177
255
  if self.lower >= self.upper:
178
256
  raise ValueError("lower must be smaller than upper.")
@@ -215,24 +293,7 @@ class Sphere(_Transformable):
215
293
  if np.any(~np.isfinite(self.radius)) or np.any(self.radius <= 0):
216
294
  raise ValueError("radius must be finite and positive.")
217
295
 
218
- material = Material._resolve(material=self.material, refractive_index=self.refractive_index)
219
-
220
- object.__setattr__(self, "material", material)
221
-
222
- object.__setattr__(self, "refractive_index", material.refractive_index)
223
-
224
- validate_units(
225
- self.centre,
226
- unit="meter",
227
- name="centre",
228
- scalar=False,
229
- )
230
-
231
- if np.shape(self.centre) != (3,):
232
- raise ValueError("centre must contain three coordinates.")
233
-
234
- if np.any(~np.isfinite(self.centre)):
235
- raise ValueError("centre must be finite.")
296
+ self._validate_transform()
236
297
 
237
298
  def mask(self, *, positions: Quantity) -> np.ndarray:
238
299
  """Return membership at unit-bearing voxel positions, shape (..., 3)."""
@@ -247,7 +308,7 @@ class Sphere(_Transformable):
247
308
 
248
309
 
249
310
  @dataclass(frozen=True, kw_only=True)
250
- class Ellipsoid(_Transformable):
311
+ class Ellipsoid(_RotatableTransformable):
251
312
  """Set absolute refractive index where ``sum((local/radii)**2) <= 1``.
252
313
 
253
314
  Three positive semi-axis radii align with local x, y, z. All lengths use SI or
@@ -258,7 +319,7 @@ class Ellipsoid(_Transformable):
258
319
  refractive_index: float | None = None
259
320
  material: Material | None = None
260
321
  centre: Quantity = field(default_factory=lambda: np.zeros(3) * ureg.meter)
261
- rotation: tuple = ((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))
322
+ rotation: RotationInput = ((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))
262
323
 
263
324
  def __post_init__(self) -> None:
264
325
  validate_units(
@@ -274,26 +335,7 @@ class Ellipsoid(_Transformable):
274
335
  if np.any(~np.isfinite(self.radii)) or np.any(self.radii <= 0):
275
336
  raise ValueError("radii must be finite and positive.")
276
337
 
277
- material = Material._resolve(material=self.material, refractive_index=self.refractive_index)
278
-
279
- object.__setattr__(self, "material", material)
280
-
281
- object.__setattr__(self, "refractive_index", material.refractive_index)
282
-
283
- validate_units(
284
- self.centre,
285
- unit="meter",
286
- name="centre",
287
- scalar=False,
288
- )
289
-
290
- if np.shape(self.centre) != (3,):
291
- raise ValueError("centre must contain three coordinates.")
292
-
293
- if np.any(~np.isfinite(self.centre)):
294
- raise ValueError("centre must be finite.")
295
-
296
- object.__setattr__(self, "rotation", tuple(tuple(row) for row in Rotation._matrix(rotation=self.rotation)))
338
+ self._validate_transform(rotation=self.rotation)
297
339
 
298
340
  def mask(self, *, positions: Quantity) -> np.ndarray:
299
341
  """Return membership at unit-bearing voxel positions, shape (..., 3)."""
@@ -310,7 +352,7 @@ class Ellipsoid(_Transformable):
310
352
 
311
353
 
312
354
  @dataclass(frozen=True, kw_only=True)
313
- class Box(_Transformable):
355
+ class Box(_RotatableTransformable):
314
356
  """Set absolute refractive index where ``abs(local) <= size/2`` in every axis.
315
357
 
316
358
  Size contains three positive full side lengths along the local axes.
@@ -321,7 +363,7 @@ class Box(_Transformable):
321
363
  refractive_index: float | None = None
322
364
  material: Material | None = None
323
365
  centre: Quantity = field(default_factory=lambda: np.zeros(3) * ureg.meter)
324
- rotation: tuple = ((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))
366
+ rotation: RotationInput = ((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))
325
367
 
326
368
  def __post_init__(self) -> None:
327
369
  validate_units(
@@ -337,26 +379,7 @@ class Box(_Transformable):
337
379
  if np.any(~np.isfinite(self.size)) or np.any(self.size <= 0):
338
380
  raise ValueError("size must be finite and positive.")
339
381
 
340
- material = Material._resolve(material=self.material, refractive_index=self.refractive_index)
341
-
342
- object.__setattr__(self, "material", material)
343
-
344
- object.__setattr__(self, "refractive_index", material.refractive_index)
345
-
346
- validate_units(
347
- self.centre,
348
- unit="meter",
349
- name="centre",
350
- scalar=False,
351
- )
352
-
353
- if np.shape(self.centre) != (3,):
354
- raise ValueError("centre must contain three coordinates.")
355
-
356
- if np.any(~np.isfinite(self.centre)):
357
- raise ValueError("centre must be finite.")
358
-
359
- object.__setattr__(self, "rotation", tuple(tuple(row) for row in Rotation._matrix(rotation=self.rotation)))
382
+ self._validate_transform(rotation=self.rotation)
360
383
 
361
384
  def mask(self, *, positions: Quantity) -> np.ndarray:
362
385
  """Return membership at unit-bearing voxel positions, shape (..., 3)."""
@@ -373,7 +396,7 @@ class Box(_Transformable):
373
396
 
374
397
 
375
398
  @dataclass(frozen=True, kw_only=True)
376
- class Cylinder(_Transformable):
399
+ class Cylinder(_RotatableTransformable):
377
400
  """A finite circular cylinder with absolute refractive index and closed boundary.
378
401
 
379
402
  Membership requires ``abs(local[axis]) <= height/2`` and squared
@@ -387,7 +410,7 @@ class Cylinder(_Transformable):
387
410
  material: Material | None = None
388
411
  centre: Quantity = field(default_factory=lambda: np.zeros(3) * ureg.meter)
389
412
  axis: int = 2
390
- rotation: tuple = ((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))
413
+ rotation: RotationInput = ((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))
391
414
 
392
415
  def __post_init__(self) -> None:
393
416
  validate_units(
@@ -410,28 +433,9 @@ class Cylinder(_Transformable):
410
433
  if np.any(~np.isfinite(self.height)) or np.any(self.height <= 0):
411
434
  raise ValueError("height must be finite and positive.")
412
435
 
413
- material = Material._resolve(material=self.material, refractive_index=self.refractive_index)
414
-
415
- object.__setattr__(self, "material", material)
416
-
417
- object.__setattr__(self, "refractive_index", material.refractive_index)
418
-
419
- validate_units(
420
- self.centre,
421
- unit="meter",
422
- name="centre",
423
- scalar=False,
424
- )
425
-
426
- if np.shape(self.centre) != (3,):
427
- raise ValueError("centre must contain three coordinates.")
428
-
429
- if np.any(~np.isfinite(self.centre)):
430
- raise ValueError("centre must be finite.")
431
-
432
436
  object.__setattr__(self, "axis", _axis(value=self.axis))
433
437
 
434
- object.__setattr__(self, "rotation", tuple(tuple(row) for row in Rotation._matrix(rotation=self.rotation)))
438
+ self._validate_transform(rotation=self.rotation)
435
439
 
436
440
  def mask(self, *, positions: Quantity) -> np.ndarray:
437
441
  """Return membership at unit-bearing voxel positions, shape (..., 3)."""
@@ -468,16 +472,20 @@ class StructuredMedium(Medium):
468
472
  Later regions win, earlier regions win, or reject shared voxel centres.
469
473
  warn_on_clipping : bool
470
474
  Warn when geometry extends beyond the voxel box; default False.
475
+ fluctuations : RandomFieldMedium, configured with :meth:`add_fluctuations`
476
+ Optional additive field applied over the background and every region.
471
477
 
472
478
  Notes
473
479
  -----
474
- Configure this mutable builder with ``add_background`` and ``add_structures``.
480
+ Configure this mutable builder with ``add_background``, ``add_structures``,
481
+ and optionally ``add_fluctuations``.
475
482
  An empty builder has no background; voxelization requires an explicit one.
476
483
  Medium remains abstract; random statistics and geometry shapes remain frozen.
477
484
  Calls update the builder and return None. Previously generated volumes do
478
485
  not change. Constructor regions are still accepted for existing callers.
479
- Voxelization returns ``delta_refractive_index(r) = n(r) - background_refractive_index``. The
480
- numerical solver uses ``epsilon_r = n0**2 + 2*n0*delta_refractive_index``, omitting
486
+ Voxelization returns ``delta_refractive_index(r) = n(r) - background_refractive_index``. A
487
+ configured additive fluctuation field is added after the absolute-index regions are composed.
488
+ The numerical solver uses ``epsilon_r = n0**2 + 2*n0*delta_refractive_index``, omitting
481
489
  ``delta_refractive_index**2`` even at higher Born orders. Strong refractive index differences
482
490
  can invalidate this constitutive approximation or Born iteration.
483
491
  Regions crossing the box are clipped. Layers therefore have finite lateral
@@ -489,6 +497,7 @@ class StructuredMedium(Medium):
489
497
  overlap: str = "replace"
490
498
  warn_on_clipping: bool = False
491
499
  _background: RandomFieldMedium | None = field(default=None, init=False, repr=False)
500
+ _fluctuations: RandomFieldMedium | None = field(default=None, init=False, repr=False)
492
501
 
493
502
  def __post_init__(self) -> None:
494
503
  regions = tuple(self.regions)
@@ -539,18 +548,53 @@ class StructuredMedium(Medium):
539
548
 
540
549
  background_refractive_index = _refractive_index(value=refractive_index)
541
550
 
551
+ if (
552
+ self._fluctuations is not None
553
+ and background_refractive_index != self._fluctuations.background_refractive_index
554
+ ):
555
+ raise ValueError("background_refractive_index must match the configured fluctuations.")
556
+
557
+ if background is not None and self._fluctuations is not None:
558
+ raise ValueError("A random background cannot be combined with additive fluctuations.")
559
+
542
560
  self.background_refractive_index = background_refractive_index
543
561
 
544
562
  self._background = background
545
563
 
564
+ def add_fluctuations(self, *, medium):
565
+ """Set an additive random field applied over the background and all structures.
566
+
567
+ The statistical medium must share the configured uniform background.
568
+ This replaces any previously configured additive fluctuation field.
569
+ Random backgrounds and additive fluctuations are mutually exclusive.
570
+ Returns None. Generated volumes record the medium and seed as provenance.
571
+ """
572
+
573
+ if not isinstance(medium, RandomFieldMedium):
574
+ raise TypeError("medium must be a RandomFieldMedium.")
575
+
576
+ fluctuations = replace(medium)
577
+
578
+ if self.background_refractive_index is None:
579
+ raise ValueError("Set a uniform background before adding fluctuations.")
580
+
581
+ if self._background is not None:
582
+ raise ValueError("Additive fluctuations cannot be combined with a random background.")
583
+
584
+ if fluctuations.background_refractive_index != self.background_refractive_index:
585
+ raise ValueError("fluctuation medium background_refractive_index must match the structured medium.")
586
+
587
+ self._fluctuations = fluctuations
588
+
546
589
  def add_structures(self, *structures):
547
590
  """Append material regions in argument order; return None.
548
591
 
549
592
  Accepts any number of positional Layer, Sphere, Ellipsoid, Box, or
550
- Cylinder objects. Later arguments replace earlier material in overlaps,
551
- including random background fluctuations. All arguments are validated
552
- before editing the builder; an empty call is a no-op. Existing voxel
553
- samples are independent snapshots.
593
+ Cylinder objects. Later arguments replace earlier material in overlaps
594
+ and replace a random background inside their masks. Separately configured
595
+ additive fluctuations remain present over every region. All arguments
596
+ are validated before editing the builder; an empty call is a no-op.
597
+ Existing voxel samples are independent snapshots.
554
598
  """
555
599
 
556
600
  if any(not isinstance(structure, (Layer, Sphere, Ellipsoid, Box, Cylinder)) for structure in structures):
@@ -560,9 +604,9 @@ class StructuredMedium(Medium):
560
604
 
561
605
  @property
562
606
  def is_random(self):
563
- """A random background supplies independent composed realizations."""
607
+ """Random backgrounds or additive fluctuations supply independent realizations."""
564
608
 
565
- return self._background is not None
609
+ return self._background is not None or self._fluctuations is not None
566
610
 
567
611
  @property
568
612
  def metadata(self):
@@ -571,8 +615,9 @@ class StructuredMedium(Medium):
571
615
  Region type, absolute refractive index, axis where applicable, and dimensions are
572
616
  recorded. Length keys have the ``_m`` suffix, and vectors are JSON lists.
573
617
  The list order preserves replacement precedence in overlapping regions.
574
- Voxelization returns a manual volume; retain this description separately
575
- when reconstructing a structured sample.
618
+ Configured additive fluctuation statistics are recorded under
619
+ ``fluctuations``. Generated volumes with fluctuations retain a snapshot
620
+ of this metadata and their seed.
576
621
  """
577
622
 
578
623
  length_fields = {"lower", "upper", "radius", "height", "centre", "radii", "size"}
@@ -611,6 +656,9 @@ class StructuredMedium(Medium):
611
656
  if self._background is not None:
612
657
  metadata["background"] = self._background.metadata
613
658
 
659
+ if self._fluctuations is not None:
660
+ metadata["fluctuations"] = self._fluctuations.metadata
661
+
614
662
  return metadata
615
663
 
616
664
  def to_volume(self, *, grid: Grid, seed: int = 0) -> Volume:
@@ -618,8 +666,8 @@ class StructuredMedium(Medium):
618
666
 
619
667
  An explicit background is required. Ordered shapes set absolute refractive
620
668
  indices; overlap follows replace, preserve, or error. A random background
621
- uses the supplied seed; structures replace that background inside their
622
- masks rather than adding fluctuations."""
669
+ uses the supplied seed and is replaced by structures inside their masks.
670
+ Additive fluctuations use the same seed and are applied over all regions."""
623
671
 
624
672
  if self.background_refractive_index is None:
625
673
  raise ValueError("Set a background with add_background before generating a volume.")
@@ -662,10 +710,20 @@ class StructuredMedium(Medium):
662
710
 
663
711
  occupied |= mask
664
712
 
713
+ if self._fluctuations is not None:
714
+ fluctuation_field = self._fluctuations.to_volume(
715
+ grid=grid,
716
+ seed=seed,
717
+ )
718
+
719
+ contrast += fluctuation_field.delta_refractive_index
720
+
665
721
  return Volume(
666
722
  delta_refractive_index=contrast,
667
723
  grid=grid,
668
724
  background_refractive_index=self.background_refractive_index,
725
+ medium=deepcopy(self) if self._fluctuations is not None else None,
726
+ seed=seed if self._fluctuations is not None else None,
669
727
  )
670
728
 
671
729
  @staticmethod