BornSim 0.5.7__tar.gz → 0.5.8__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.
Files changed (139) hide show
  1. {bornsim-0.5.7 → bornsim-0.5.8}/.zenodo.json +1 -1
  2. {bornsim-0.5.7 → bornsim-0.5.8/BornSim.egg-info}/PKG-INFO +1 -1
  3. {bornsim-0.5.7 → bornsim-0.5.8}/BornSim.egg-info/SOURCES.txt +14 -0
  4. {bornsim-0.5.7 → bornsim-0.5.8}/CITATION.cff +1 -1
  5. {bornsim-0.5.7/BornSim.egg-info → bornsim-0.5.8}/PKG-INFO +1 -1
  6. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/__init__.py +6 -0
  7. bornsim-0.5.8/bornsim/_version.py +1 -0
  8. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/geometry.py +7 -306
  9. bornsim-0.5.8/bornsim/medium/__init__.py +24 -0
  10. bornsim-0.5.8/bornsim/medium/particles/__init__.py +8 -0
  11. bornsim-0.5.8/bornsim/medium/particles/core_shell.py +78 -0
  12. bornsim-0.5.8/bornsim/medium/particles/cylinder.py +78 -0
  13. bornsim-0.5.8/bornsim/medium/particles/ellipsoid.py +71 -0
  14. bornsim-0.5.7/bornsim/medium/random_spheres.py → bornsim-0.5.8/bornsim/medium/particles/spheres.py +5 -5
  15. bornsim-0.5.8/bornsim/medium/random/__init__.py +5 -0
  16. bornsim-0.5.7/bornsim/medium/random_medium.py → bornsim-0.5.8/bornsim/medium/random/fields.py +5 -5
  17. bornsim-0.5.8/bornsim/medium/random_medium.py +5 -0
  18. bornsim-0.5.8/bornsim/medium/random_spheres.py +5 -0
  19. bornsim-0.5.8/bornsim/medium/structured/__init__.py +6 -0
  20. bornsim-0.5.8/bornsim/medium/structured/composite.py +315 -0
  21. bornsim-0.5.8/bornsim/medium/structured/periodic.py +103 -0
  22. {bornsim-0.5.7 → bornsim-0.5.8}/conda.recipe/meta.yaml +1 -1
  23. bornsim-0.5.8/docs/examples/structured_media/README.rst +9 -0
  24. bornsim-0.5.8/docs/examples/structured_media/antenna_rods.py +104 -0
  25. bornsim-0.5.8/docs/examples/structured_media/particle_families.py +123 -0
  26. bornsim-0.5.8/docs/examples/structured_media/periodic_array.py +130 -0
  27. bornsim-0.5.8/docs/source/_static/favicon.png +0 -0
  28. bornsim-0.5.8/docs/source/_static/favicon.svg +8 -0
  29. bornsim-0.5.8/docs/source/_static/logo.png +0 -0
  30. bornsim-0.5.8/docs/source/_static/logo.svg +11 -0
  31. {bornsim-0.5.7 → bornsim-0.5.8}/docs/source/api.rst +30 -0
  32. {bornsim-0.5.7 → bornsim-0.5.8}/docs/source/examples.rst +16 -0
  33. bornsim-0.5.8/docs/source/overview.rst +14 -0
  34. {bornsim-0.5.7 → bornsim-0.5.8}/pyproject.toml +1 -1
  35. bornsim-0.5.8/tests/numerical/test_medium_families.py +113 -0
  36. bornsim-0.5.7/bornsim/_version.py +0 -1
  37. bornsim-0.5.7/bornsim/medium/__init__.py +0 -7
  38. bornsim-0.5.7/docs/examples/structured_media/README.rst +0 -5
  39. bornsim-0.5.7/docs/source/_static/favicon.png +0 -0
  40. bornsim-0.5.7/docs/source/_static/favicon.svg +0 -1
  41. bornsim-0.5.7/docs/source/_static/logo.png +0 -0
  42. bornsim-0.5.7/docs/source/_static/logo.svg +0 -1
  43. bornsim-0.5.7/docs/source/overview.rst +0 -2
  44. {bornsim-0.5.7 → bornsim-0.5.8}/.coveragerc +0 -0
  45. {bornsim-0.5.7 → bornsim-0.5.8}/.pre-commit-config.yaml +0 -0
  46. {bornsim-0.5.7 → bornsim-0.5.8}/BornSim.egg-info/dependency_links.txt +0 -0
  47. {bornsim-0.5.7 → bornsim-0.5.8}/BornSim.egg-info/requires.txt +0 -0
  48. {bornsim-0.5.7 → bornsim-0.5.8}/BornSim.egg-info/top_level.txt +0 -0
  49. {bornsim-0.5.7 → bornsim-0.5.8}/CONTRIBUTING.md +0 -0
  50. {bornsim-0.5.7 → bornsim-0.5.8}/LICENSE +0 -0
  51. {bornsim-0.5.7 → bornsim-0.5.8}/MANIFEST.in +0 -0
  52. {bornsim-0.5.7 → bornsim-0.5.8}/README.rst +0 -0
  53. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/angular_data.py +0 -0
  54. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/api.py +0 -0
  55. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/directions.py +0 -0
  56. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/ensemble.py +0 -0
  57. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/ensemble_sampling.py +0 -0
  58. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/green.py +0 -0
  59. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/grid.py +0 -0
  60. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/material.py +0 -0
  61. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/medium/base.py +0 -0
  62. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/results.py +0 -0
  63. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/rotation.py +0 -0
  64. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/sampling.py +0 -0
  65. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/series.py +0 -0
  66. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/solver.py +0 -0
  67. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/source.py +0 -0
  68. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/units.py +0 -0
  69. {bornsim-0.5.7 → bornsim-0.5.8}/bornsim/volume.py +0 -0
  70. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/README.rst +0 -0
  71. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/born_orders/README.rst +0 -0
  72. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/born_orders/born_interference.py +0 -0
  73. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/born_orders/compare_orders.py +0 -0
  74. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/random_media/README.rst +0 -0
  75. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/random_media/covariance_models.py +0 -0
  76. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/random_media/phase_function.py +0 -0
  77. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/random_media/random_medium.py +0 -0
  78. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/random_media/random_spheres.py +0 -0
  79. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/random_media/theory_random_fields.py +0 -0
  80. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/random_media/wavelength_dependence.py +0 -0
  81. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/results/README.rst +0 -0
  82. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/results/result_plots.py +0 -0
  83. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/results/save_load_results.py +0 -0
  84. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/structured_media/dielectric_sphere.py +0 -0
  85. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/structured_media/structured_media.py +0 -0
  86. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/structured_media/theory_directional_interference.py +0 -0
  87. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/validation/README.rst +0 -0
  88. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/validation/angular_convergence.py +0 -0
  89. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/validation/ensemble_sampling.py +0 -0
  90. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/validation/finite_size_comparison.py +0 -0
  91. {bornsim-0.5.7 → bornsim-0.5.8}/docs/examples/validation/grid_refinement.py +0 -0
  92. {bornsim-0.5.7 → bornsim-0.5.8}/docs/images/bornsim_medium_opacity_3d.png +0 -0
  93. {bornsim-0.5.7 → bornsim-0.5.8}/docs/images/bornsim_spf_surface_3d.png +0 -0
  94. {bornsim-0.5.7 → bornsim-0.5.8}/docs/images/branding-prompts.rst +0 -0
  95. {bornsim-0.5.7 → bornsim-0.5.8}/docs/source/_static/phase_function.svg +0 -0
  96. {bornsim-0.5.7 → bornsim-0.5.8}/docs/source/conf.py +0 -0
  97. {bornsim-0.5.7 → bornsim-0.5.8}/docs/source/development.rst +0 -0
  98. {bornsim-0.5.7 → bornsim-0.5.8}/docs/source/gallery_config.py +0 -0
  99. {bornsim-0.5.7 → bornsim-0.5.8}/docs/source/getting_started.rst +0 -0
  100. {bornsim-0.5.7 → bornsim-0.5.8}/docs/source/guide.rst +0 -0
  101. {bornsim-0.5.7 → bornsim-0.5.8}/docs/source/index.rst +0 -0
  102. {bornsim-0.5.7 → bornsim-0.5.8}/docs/source/medium_visualization.rst +0 -0
  103. {bornsim-0.5.7 → bornsim-0.5.8}/docs/source/research.rst +0 -0
  104. {bornsim-0.5.7 → bornsim-0.5.8}/docs/source/resources.rst +0 -0
  105. {bornsim-0.5.7 → bornsim-0.5.8}/docs/source/theory.rst +0 -0
  106. {bornsim-0.5.7 → bornsim-0.5.8}/makefile +0 -0
  107. {bornsim-0.5.7 → bornsim-0.5.8}/pytest.ini +0 -0
  108. {bornsim-0.5.7 → bornsim-0.5.8}/setup.cfg +0 -0
  109. {bornsim-0.5.7 → bornsim-0.5.8}/tests/analytical/reference.py +0 -0
  110. {bornsim-0.5.7 → bornsim-0.5.8}/tests/analytical/test_model.py +0 -0
  111. {bornsim-0.5.7 → bornsim-0.5.8}/tests/analytical/test_numerical_reference.py +0 -0
  112. {bornsim-0.5.7 → bornsim-0.5.8}/tests/conftest.py +0 -0
  113. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_api.py +0 -0
  114. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_api_keywords.py +0 -0
  115. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_api_ownership.py +0 -0
  116. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_api_scope.py +0 -0
  117. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_configuration.py +0 -0
  118. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_directional_api.py +0 -0
  119. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_directions.py +0 -0
  120. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_engine.py +0 -0
  121. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_explicit_physics.py +0 -0
  122. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_geometry.py +0 -0
  123. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_media.py +0 -0
  124. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_medium_composition.py +0 -0
  125. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_medium_metadata.py +0 -0
  126. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_plot_contract.py +0 -0
  127. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_random_spheres.py +0 -0
  128. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_result.py +0 -0
  129. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_result_contract.py +0 -0
  130. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_rotation.py +0 -0
  131. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_series.py +0 -0
  132. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_unit_contract.py +0 -0
  133. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_units.py +0 -0
  134. {bornsim-0.5.7 → bornsim-0.5.8}/tests/numerical/test_volume_plotting.py +0 -0
  135. {bornsim-0.5.7 → bornsim-0.5.8}/tests/packaging/test_release_tools.py +0 -0
  136. {bornsim-0.5.7 → bornsim-0.5.8}/tools/check_release.py +0 -0
  137. {bornsim-0.5.7 → bornsim-0.5.8}/tools/check_wheel.py +0 -0
  138. {bornsim-0.5.7 → bornsim-0.5.8}/tools/next_release_version.py +0 -0
  139. {bornsim-0.5.7 → bornsim-0.5.8}/tools/release_tag.py +0 -0
@@ -8,7 +8,7 @@
8
8
  }
9
9
  ],
10
10
  "license": "mit",
11
- "version": "0.5.7",
11
+ "version": "0.5.8",
12
12
  "keywords": [
13
13
  "Born approximation",
14
14
  "light scattering",
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: BornSim
3
- Version: 0.5.7
3
+ Version: 0.5.8
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
@@ -37,6 +37,16 @@ bornsim/medium/__init__.py
37
37
  bornsim/medium/base.py
38
38
  bornsim/medium/random_medium.py
39
39
  bornsim/medium/random_spheres.py
40
+ bornsim/medium/particles/__init__.py
41
+ bornsim/medium/particles/core_shell.py
42
+ bornsim/medium/particles/cylinder.py
43
+ bornsim/medium/particles/ellipsoid.py
44
+ bornsim/medium/particles/spheres.py
45
+ bornsim/medium/random/__init__.py
46
+ bornsim/medium/random/fields.py
47
+ bornsim/medium/structured/__init__.py
48
+ bornsim/medium/structured/composite.py
49
+ bornsim/medium/structured/periodic.py
40
50
  conda.recipe/meta.yaml
41
51
  docs/examples/README.rst
42
52
  docs/examples/born_orders/README.rst
@@ -53,7 +63,10 @@ docs/examples/results/README.rst
53
63
  docs/examples/results/result_plots.py
54
64
  docs/examples/results/save_load_results.py
55
65
  docs/examples/structured_media/README.rst
66
+ docs/examples/structured_media/antenna_rods.py
56
67
  docs/examples/structured_media/dielectric_sphere.py
68
+ docs/examples/structured_media/particle_families.py
69
+ docs/examples/structured_media/periodic_array.py
57
70
  docs/examples/structured_media/structured_media.py
58
71
  docs/examples/structured_media/theory_directional_interference.py
59
72
  docs/examples/validation/README.rst
@@ -98,6 +111,7 @@ tests/numerical/test_explicit_physics.py
98
111
  tests/numerical/test_geometry.py
99
112
  tests/numerical/test_media.py
100
113
  tests/numerical/test_medium_composition.py
114
+ tests/numerical/test_medium_families.py
101
115
  tests/numerical/test_medium_metadata.py
102
116
  tests/numerical/test_plot_contract.py
103
117
  tests/numerical/test_random_spheres.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.5.7"
5
+ version: "0.5.8"
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.5.7
3
+ Version: 0.5.8
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
@@ -15,8 +15,14 @@ from .results import Result
15
15
  from .angular_data import AngularData
16
16
  from .material import Material
17
17
  from .ensemble_sampling import EnsembleSampling
18
+ from .medium.structured import PeriodicMedium
19
+ from .medium.particles import CoreShellMedium, EllipsoidMedium, CylinderMedium
18
20
 
19
21
  __all__ = [
22
+ "PeriodicMedium",
23
+ "CoreShellMedium",
24
+ "EllipsoidMedium",
25
+ "CylinderMedium",
20
26
  "Directions",
21
27
  "Material",
22
28
  "EnsembleSampling",
@@ -0,0 +1 @@
1
+ __version__ = version = "0.5.8"
@@ -5,19 +5,13 @@ not dielectric contrast; Volume retains the solver's linearized constitutive
5
5
  law. Interfaces are sampled at cell centres without subvoxel averaging.
6
6
  """
7
7
 
8
- from dataclasses import asdict, dataclass, field, replace
9
- from copy import deepcopy
8
+ from dataclasses import dataclass, field, replace
10
9
  import numpy as np
11
10
  from numpy.typing import NDArray
12
11
  from typing import Any
13
12
  from .units import _refractive_index_values, Quantity, validate_units, ureg
14
- from .medium import Medium
15
- from .medium.random_medium import RandomFieldMedium
16
- from .volume import Volume
17
- from .grid import Grid
18
13
  from .rotation import Rotation, RotationInput, RotationMatrix
19
14
  from .material import Material
20
- import warnings
21
15
 
22
16
 
23
17
  def _refractive_index(*, value: float) -> float:
@@ -455,304 +449,11 @@ class Cylinder(_RotatableTransformable):
455
449
  )
456
450
 
457
451
 
458
- @dataclass(kw_only=True)
459
- class StructuredMedium(Medium):
460
- """Compose ordered material regions in a uniform background.
461
-
462
- Parameters
463
- ----------
464
- regions : sequence of Layer, Sphere, Ellipsoid, Box, or Cylinder
465
- Regions set absolute refractive index. Overlap precedence follows the
466
- overlap policy; indices are not added. Default is empty.
467
- background_refractive_index : float
468
- Explicit positive uniform background refractive index. It fills uncovered
469
- voxels and extends outside the finite voxel box.
470
-
471
- overlap : {"replace", "preserve", "error"}
472
- Later regions win, earlier regions win, or reject shared voxel centres.
473
- warn_on_clipping : bool
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.
477
-
478
- Notes
479
- -----
480
- Configure this mutable builder with ``add_background``, ``add_structures``,
481
- and optionally ``add_fluctuations``.
482
- An empty builder has no background; voxelization requires an explicit one.
483
- Medium remains abstract; random statistics and geometry shapes remain frozen.
484
- Calls update the builder and return None. Previously generated volumes do
485
- not change. Constructor regions are still accepted for existing callers.
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
489
- ``delta_refractive_index**2`` even at higher Born orders. Strong refractive index differences
490
- can invalidate this constitutive approximation or Born iteration.
491
- Regions crossing the box are clipped. Layers therefore have finite lateral
492
- extent; this is not a transfer-matrix or layered-background Green solver.
493
- """
494
-
495
- regions: tuple = ()
496
- background_refractive_index: float | None = None
497
- overlap: str = "replace"
498
- warn_on_clipping: bool = False
499
- _background: RandomFieldMedium | None = field(default=None, init=False, repr=False)
500
- _fluctuations: RandomFieldMedium | None = field(default=None, init=False, repr=False)
501
-
502
- def __post_init__(self) -> None:
503
- regions = tuple(self.regions)
504
-
505
- if any(not isinstance(region, (Layer, Sphere, Ellipsoid, Box, Cylinder)) for region in regions):
506
- raise TypeError("regions must contain Layer, Sphere, Ellipsoid, Box, or Cylinder objects.")
507
-
508
- if self.overlap not in ("replace", "preserve", "error"):
509
- raise ValueError("overlap must be replace, preserve, or error.")
510
-
511
- if not isinstance(self.warn_on_clipping, bool):
512
- raise ValueError("warn_on_clipping must be a bool.")
513
-
514
- self.regions = regions
515
-
516
- if self.background_refractive_index is not None:
517
- self.background_refractive_index = _refractive_index(value=self.background_refractive_index)
518
-
519
- def add_background(self, *, refractive_index=None, medium=None, material=None):
520
- """Set the background in place, retaining all existing structures.
521
-
522
- Supply exactly one of ``refractive_index`` (a positive uniform refractive index)
523
- or ``medium`` (RandomFieldMedium statistics). A random background is sampled
524
- with to_volume(seed=...) and fills only voxels outside structures.
525
- The exterior scattering background remains uniform at background_refractive_index.
526
- Replacing a background changes the reference n0, not structures'
527
- absolute refractive indices. Validation precedes any state change.
528
- Returns None. Random statistics are copied when added.
529
- """
530
-
531
- if material is not None:
532
- resolved = Material._resolve(material=material, refractive_index=refractive_index)
533
-
534
- refractive_index = resolved.refractive_index
535
-
536
- if (refractive_index is None) == (medium is None):
537
- raise ValueError("Supply exactly one of refractive_index or medium.")
538
-
539
- if medium is not None:
540
- if not isinstance(medium, RandomFieldMedium):
541
- raise TypeError("medium must be a RandomFieldMedium.")
542
-
543
- background = replace(medium)
544
-
545
- background_refractive_index = background.background_refractive_index
546
- else:
547
- background = None
548
-
549
- background_refractive_index = _refractive_index(value=refractive_index)
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
-
560
- self.background_refractive_index = background_refractive_index
561
-
562
- self._background = background
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
-
589
- def add_structures(self, *structures):
590
- """Append material regions in argument order; return None.
591
-
592
- Accepts any number of positional Layer, Sphere, Ellipsoid, Box, or
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.
598
- """
599
-
600
- if any(not isinstance(structure, (Layer, Sphere, Ellipsoid, Box, Cylinder)) for structure in structures):
601
- raise TypeError("structures must be Layer, Sphere, Ellipsoid, Box, or Cylinder objects.")
602
-
603
- self.regions = (*self.regions, *structures)
604
-
605
- @property
606
- def is_random(self):
607
- """Random backgrounds or additive fluctuations supply independent realizations."""
608
-
609
- return self._background is not None or self._fluctuations is not None
610
-
611
- @property
612
- def metadata(self):
613
- """Return independent SI geometry descriptions in application order.
614
-
615
- Region type, absolute refractive index, axis where applicable, and dimensions are
616
- recorded. Length keys have the ``_m`` suffix, and vectors are JSON lists.
617
- The list order preserves replacement precedence in overlapping regions.
618
- Configured additive fluctuation statistics are recorded under
619
- ``fluctuations``. Generated volumes with fluctuations retain a snapshot
620
- of this metadata and their seed.
621
- """
622
-
623
- length_fields = {"lower", "upper", "radius", "height", "centre", "radii", "size"}
624
-
625
- regions = []
626
-
627
- for region in self.regions:
628
- description: dict[str, object] = {"type": type(region).__name__}
629
-
630
- for name, value in asdict(region).items():
631
- if name == "material":
632
- continue
633
-
634
- if name == "rotation" and np.array_equal(value, np.eye(3)):
635
- continue
636
-
637
- if isinstance(region, Layer) and name == "centre" and np.all(value == 0):
638
- continue
639
-
640
- if name in length_fields:
641
- magnitude = value.to("meter").magnitude
642
-
643
- value = np.asarray(magnitude).tolist()
644
-
645
- key = f"{name}_m" if name in length_fields else name
646
-
647
- description[key] = list(value) if isinstance(value, tuple) else value
648
-
649
- regions.append(description)
650
-
651
- metadata: dict[str, object] = {**super().metadata, "regions": regions}
652
-
653
- if self.overlap != "replace":
654
- metadata["overlap"] = self.overlap
655
-
656
- if self._background is not None:
657
- metadata["background"] = self._background.metadata
658
-
659
- if self._fluctuations is not None:
660
- metadata["fluctuations"] = self._fluctuations.metadata
661
-
662
- return metadata
663
-
664
- def to_volume(self, *, grid: Grid, seed: int = 0) -> Volume:
665
- """Voxelize this medium on an explicit Grid.
666
-
667
- An explicit background is required. Ordered shapes set absolute refractive
668
- indices; overlap follows replace, preserve, or error. A random background
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."""
671
-
672
- if self.background_refractive_index is None:
673
- raise ValueError("Set a background with add_background before generating a volume.")
674
-
675
- grid = Grid._resolve(grid=grid)
676
-
677
- if self.overlap not in ("replace", "preserve", "error"):
678
- raise ValueError("overlap must be replace, preserve, or error.")
679
-
680
- positions = grid.positions
681
-
682
- if self._background is None:
683
- contrast = np.zeros(grid.shape)
684
- else:
685
- background = self._background.to_volume(
686
- grid=grid,
687
- seed=seed,
688
- )
689
-
690
- contrast = background.delta_refractive_index.copy()
691
-
692
- occupied = np.zeros(grid.shape, dtype=bool)
693
-
694
- for region_index, region in enumerate(self.regions):
695
- if self.warn_on_clipping and self._is_clipped(region=region, grid=grid):
696
- warnings.warn(
697
- f"Region {region_index} ({type(region).__name__}) crosses the voxel box and is clipped.",
698
- UserWarning,
699
- stacklevel=2,
700
- )
701
-
702
- mask = region.mask(positions=positions)
703
-
704
- if self.overlap == "error" and np.any(mask & occupied):
705
- raise ValueError(f"Region {region_index} overlaps existing structures at voxel centres.")
706
-
707
- selected = mask & ~occupied if self.overlap == "preserve" else mask
708
-
709
- contrast[selected] = region.refractive_index - self.background_refractive_index
710
-
711
- occupied |= mask
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
-
721
- return Volume(
722
- delta_refractive_index=contrast,
723
- grid=grid,
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,
727
- )
728
-
729
- @staticmethod
730
- def _is_clipped(*, region, grid):
731
- half_box = np.asarray(grid.shape) * grid.spacing / 2
732
-
733
- centre = region.centre
734
-
735
- if isinstance(region, Sphere):
736
- half_extent = np.ones(3) * region.radius
737
- else:
738
- matrix = np.asarray(region.rotation)
739
-
740
- if isinstance(region, Layer):
741
- normal = matrix[:, region.axis]
742
-
743
- reach = np.sum(np.abs(normal) * half_box)
744
-
745
- shift = np.dot(centre, normal)
746
-
747
- return region.lower + shift < -reach or region.upper + shift > reach
748
-
749
- if isinstance(region, Box):
750
- half_extent = np.abs(matrix) @ (region.size / 2)
751
- elif isinstance(region, Ellipsoid):
752
- half_extent = np.sqrt(matrix**2 @ region.radii**2)
753
- else:
754
- normal = matrix[:, region.axis]
452
+ def __getattr__(name):
453
+ """Preserve the historical StructuredMedium import."""
454
+ if name == "StructuredMedium":
455
+ from .medium.structured.composite import StructuredMedium
755
456
 
756
- half_extent = np.abs(normal) * region.height / 2 + region.radius * np.sqrt(np.maximum(0, 1 - normal**2))
457
+ return StructuredMedium
757
458
 
758
- return bool(np.any(np.abs(centre) + half_extent > half_box * (1 + 1e-12)))
459
+ raise AttributeError(name)
@@ -0,0 +1,24 @@
1
+ """Finite media for numerical Born calculations."""
2
+
3
+ from .random_spheres import RandomSphereMedium
4
+ from .base import Medium
5
+ from .random_medium import GaussianMedium, ExponentialMedium, WhittleMaternMedium
6
+
7
+ __all__ = ["Medium", "GaussianMedium", "ExponentialMedium", "WhittleMaternMedium", "RandomSphereMedium"]
8
+
9
+ __all__ += ["StructuredMedium", "PeriodicMedium", "CoreShellMedium", "EllipsoidMedium", "CylinderMedium"]
10
+
11
+
12
+ def __getattr__(name):
13
+ """Resolve composed media after geometry initialization."""
14
+ if name in ("StructuredMedium", "PeriodicMedium"):
15
+ from . import structured
16
+
17
+ return getattr(structured, name)
18
+
19
+ if name in ("CoreShellMedium", "EllipsoidMedium", "CylinderMedium"):
20
+ from . import particles
21
+
22
+ return getattr(particles, name)
23
+
24
+ raise AttributeError(name)
@@ -0,0 +1,8 @@
1
+ """Finite particle collections."""
2
+
3
+ from .spheres import RandomSphereMedium
4
+ from .core_shell import CoreShellMedium
5
+ from .ellipsoid import EllipsoidMedium
6
+ from .cylinder import CylinderMedium
7
+
8
+ __all__ = ["RandomSphereMedium", "CoreShellMedium", "EllipsoidMedium", "CylinderMedium"]
@@ -0,0 +1,78 @@
1
+ """Finite concentric core–shell spheres."""
2
+
3
+ from dataclasses import dataclass
4
+ from ..base import Medium
5
+ from ...geometry import Sphere
6
+ from ...units import Quantity
7
+
8
+
9
+ @dataclass(frozen=True, kw_only=True)
10
+ class CoreShellMedium(Medium):
11
+ """A concentric spherical core and shell in a uniform background.
12
+
13
+ Parameters
14
+ ----------
15
+ background_refractive_index, core_refractive_index, shell_refractive_index : float
16
+ Absolute real refractive indices.
17
+ core_radius, outer_radius : Quantity
18
+ Positive length scalars with core_radius strictly below outer_radius.
19
+ centre : Quantity
20
+ Three-component particle position. Interfaces use voxel-centre sampling.
21
+ """
22
+
23
+ background_refractive_index: float
24
+ core_refractive_index: float
25
+ shell_refractive_index: float
26
+ core_radius: Quantity
27
+ outer_radius: Quantity
28
+ centre: Quantity
29
+
30
+ def __post_init__(self):
31
+ self._composite()
32
+
33
+ if self.core_radius >= self.outer_radius:
34
+ raise ValueError("core_radius must be smaller than outer_radius.")
35
+
36
+ def _composite(self):
37
+ from ..structured.composite import StructuredMedium
38
+
39
+ shell = Sphere(
40
+ radius=self.outer_radius,
41
+ refractive_index=self.shell_refractive_index,
42
+ centre=self.centre,
43
+ )
44
+
45
+ core = Sphere(
46
+ radius=self.core_radius,
47
+ refractive_index=self.core_refractive_index,
48
+ centre=self.centre,
49
+ )
50
+
51
+ medium = StructuredMedium()
52
+
53
+ medium.add_background(refractive_index=self.background_refractive_index)
54
+
55
+ medium.add_structures(shell, core)
56
+
57
+ return medium
58
+
59
+ @property
60
+ def metadata(self):
61
+ """Return ordered shell and core geometry in SI units."""
62
+ return {**self._composite().metadata, "model": "core_shell"}
63
+
64
+ def to_volume(self, *, grid, seed=0):
65
+ """Sample the shell first and replace its interior with the core."""
66
+ from ...volume import Volume
67
+
68
+ medium = self._composite()
69
+
70
+ volume = medium.to_volume(grid=grid, seed=seed)
71
+
72
+ return Volume(
73
+ delta_refractive_index=volume.delta_refractive_index,
74
+ background_refractive_index=self.background_refractive_index,
75
+ grid=grid,
76
+ medium=self,
77
+ seed=seed,
78
+ )
@@ -0,0 +1,78 @@
1
+ """Finite cylindrical particles for rods and antenna-like scatterers."""
2
+
3
+ from dataclasses import dataclass
4
+ from ..base import Medium
5
+ from ...units import Quantity
6
+
7
+
8
+ @dataclass(frozen=True, kw_only=True)
9
+ class CylinderMedium(Medium):
10
+ """A finite homogeneous cylinder in a uniform background.
11
+
12
+ Parameters
13
+ ----------
14
+ background_refractive_index, particle_refractive_index : float
15
+ Absolute real refractive indices.
16
+ radius, height : Quantity
17
+ Radius and full axial length of the cylinder.
18
+ centre : Quantity
19
+ Three-component particle position.
20
+ axis : int
21
+ Local cylinder axis: 0, 1, or 2 for x, y, or z.
22
+ rotation : Rotation or array
23
+ Rotation mapping local cylinder coordinates into global coordinates.
24
+
25
+ Notes
26
+ -----
27
+ This is a finite dielectric rod. It can approximate an antenna-like
28
+ scatterer when the refractive-index model is appropriate. It does not
29
+ include conducting boundary conditions, complex permittivity, or currents.
30
+ """
31
+
32
+ background_refractive_index: float
33
+ particle_refractive_index: float
34
+ radius: Quantity
35
+ height: Quantity
36
+ centre: Quantity
37
+ axis: int = 2
38
+ rotation: object = ((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))
39
+
40
+ def _composite(self):
41
+ from ...geometry import Cylinder
42
+ from ..structured.composite import StructuredMedium
43
+
44
+ particle = Cylinder(
45
+ radius=self.radius,
46
+ height=self.height,
47
+ centre=self.centre,
48
+ axis=self.axis,
49
+ rotation=self.rotation,
50
+ refractive_index=self.particle_refractive_index,
51
+ )
52
+
53
+ medium = StructuredMedium()
54
+
55
+ medium.add_background(refractive_index=self.background_refractive_index)
56
+
57
+ medium.add_structures(particle)
58
+
59
+ return medium
60
+
61
+ @property
62
+ def metadata(self):
63
+ """Return cylinder geometry in SI units."""
64
+ return {**self._composite().metadata, "model": "cylinder"}
65
+
66
+ def to_volume(self, *, grid, seed=0):
67
+ """Voxelize the finite cylinder on the supplied grid."""
68
+ from ...volume import Volume
69
+
70
+ volume = self._composite().to_volume(grid=grid, seed=seed)
71
+
72
+ return Volume(
73
+ delta_refractive_index=volume.delta_refractive_index,
74
+ background_refractive_index=self.background_refractive_index,
75
+ grid=grid,
76
+ medium=self,
77
+ seed=seed,
78
+ )