morphogen 1.0.0__py3-none-any.whl

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 (381) hide show
  1. morphogen/__init__.py +60 -0
  2. morphogen/__main__.py +7 -0
  3. morphogen/_platform.py +55 -0
  4. morphogen/_public.py +153 -0
  5. morphogen/_utils.py +80 -0
  6. morphogen/_version.py +1 -0
  7. morphogen/analysis/__init__.py +174 -0
  8. morphogen/analysis/anisotropy.py +135 -0
  9. morphogen/analysis/basic.py +38 -0
  10. morphogen/analysis/cells.py +54 -0
  11. morphogen/analysis/connectivity.py +156 -0
  12. morphogen/analysis/correlation.py +195 -0
  13. morphogen/analysis/covariance.py +80 -0
  14. morphogen/analysis/fractal.py +54 -0
  15. morphogen/analysis/measures.py +188 -0
  16. morphogen/analysis/morphology.py +265 -0
  17. morphogen/analysis/particles.py +160 -0
  18. morphogen/analysis/percolation.py +2034 -0
  19. morphogen/analysis/power_laws.py +143 -0
  20. morphogen/analysis/random_sets.py +351 -0
  21. morphogen/analysis/stereology.py +289 -0
  22. morphogen/analysis/surface.py +107 -0
  23. morphogen/analysis/topology.py +92 -0
  24. morphogen/automata/__init__.py +74 -0
  25. morphogen/automata/engine.py +211 -0
  26. morphogen/automata/growth.py +686 -0
  27. morphogen/automata/lattice.py +143 -0
  28. morphogen/automata/reaction.py +255 -0
  29. morphogen/automata/rules.py +353 -0
  30. morphogen/automata/tilings.py +1715 -0
  31. morphogen/cli.py +3526 -0
  32. morphogen/config.py +2167 -0
  33. morphogen/contact/__init__.py +113 -0
  34. morphogen/contact/experiments.py +368 -0
  35. morphogen/contact/hertz.py +104 -0
  36. morphogen/contact/kernels.py +827 -0
  37. morphogen/contact/periodic.py +278 -0
  38. morphogen/contact/problem.py +578 -0
  39. morphogen/contact/surfaces.py +310 -0
  40. morphogen/coupling/__init__.py +43 -0
  41. morphogen/coupling/ageing.py +143 -0
  42. morphogen/coupling/diffusion.py +226 -0
  43. morphogen/coupling/fenicsx.py +484 -0
  44. morphogen/coupling/oxidation.py +447 -0
  45. morphogen/coupling/plates.py +247 -0
  46. morphogen/design/__init__.py +51 -0
  47. morphogen/design/csp.py +616 -0
  48. morphogen/design/frames.py +277 -0
  49. morphogen/design/search.py +287 -0
  50. morphogen/design/tiles.py +336 -0
  51. morphogen/distributions.py +312 -0
  52. morphogen/domain.py +203 -0
  53. morphogen/dynamics/__init__.py +179 -0
  54. morphogen/dynamics/model.py +638 -0
  55. morphogen/dynamics/openradioss.py +643 -0
  56. morphogen/dynamics/results.py +515 -0
  57. morphogen/fracture/__init__.py +170 -0
  58. morphogen/fracture/bulk.py +349 -0
  59. morphogen/fracture/cohesive.py +1614 -0
  60. morphogen/fracture/ductile.py +557 -0
  61. morphogen/fracture/lefm.py +1168 -0
  62. morphogen/fracture/mixed.py +1178 -0
  63. morphogen/fracture/periodic.py +733 -0
  64. morphogen/fracture/phasefield.py +714 -0
  65. morphogen/fracture/phasefield_finite.py +368 -0
  66. morphogen/fracture/surface.py +572 -0
  67. morphogen/fracture/toughness.py +566 -0
  68. morphogen/gpu.py +108 -0
  69. morphogen/gui/__init__.py +8 -0
  70. morphogen/gui/api.py +1927 -0
  71. morphogen/gui/desktop.py +387 -0
  72. morphogen/gui/icon.png +0 -0
  73. morphogen/gui/index.html +1909 -0
  74. morphogen/gui/server.py +229 -0
  75. morphogen/gui/tools/__init__.py +629 -0
  76. morphogen/gui/tools/compare.py +149 -0
  77. morphogen/gui/tools/contact.py +391 -0
  78. morphogen/gui/tools/couplings.py +1085 -0
  79. morphogen/gui/tools/crackfront.py +245 -0
  80. morphogen/gui/tools/design.py +224 -0
  81. morphogen/gui/tools/dynamics.py +824 -0
  82. morphogen/gui/tools/fracture.py +2586 -0
  83. morphogen/gui/tools/interop.py +1654 -0
  84. morphogen/gui/tools/learning.py +595 -0
  85. morphogen/gui/tools/mechanics.py +3881 -0
  86. morphogen/gui/tools/nonlocal_damage.py +1321 -0
  87. morphogen/gui/tools/phasefield.py +215 -0
  88. morphogen/gui/tools/physics.py +597 -0
  89. morphogen/gui/tools/stability.py +1756 -0
  90. morphogen/gui/tools/statistics.py +1408 -0
  91. morphogen/gui/viewer.js +1100 -0
  92. morphogen/homogenization/__init__.py +210 -0
  93. morphogen/homogenization/acoustics.py +566 -0
  94. morphogen/homogenization/amg.py +1005 -0
  95. morphogen/homogenization/apparent.py +1046 -0
  96. morphogen/homogenization/behaviours.cu +2285 -0
  97. morphogen/homogenization/behaviours.py +944 -0
  98. morphogen/homogenization/beremin.py +263 -0
  99. morphogen/homogenization/bifurcation.py +1085 -0
  100. morphogen/homogenization/bloch.py +507 -0
  101. morphogen/homogenization/bounds.py +226 -0
  102. morphogen/homogenization/core.py +458 -0
  103. morphogen/homogenization/coupled.py +1135 -0
  104. morphogen/homogenization/crystal.py +2967 -0
  105. morphogen/homogenization/dilatation.py +454 -0
  106. morphogen/homogenization/elements.py +157 -0
  107. morphogen/homogenization/fatigue.py +768 -0
  108. morphogen/homogenization/fe.py +1739 -0
  109. morphogen/homogenization/fenicsx.py +307 -0
  110. morphogen/homogenization/fft.py +499 -0
  111. morphogen/homogenization/fft_nonlinear.py +391 -0
  112. morphogen/homogenization/finite.py +613 -0
  113. morphogen/homogenization/flow.py +361 -0
  114. morphogen/homogenization/frames.py +1125 -0
  115. morphogen/homogenization/gpu.py +1241 -0
  116. morphogen/homogenization/harmonic.py +427 -0
  117. morphogen/homogenization/identification.py +579 -0
  118. morphogen/homogenization/kernels.py +760 -0
  119. morphogen/homogenization/laws.py +2061 -0
  120. morphogen/homogenization/materials.py +1080 -0
  121. morphogen/homogenization/mfront.py +589 -0
  122. morphogen/homogenization/networks.py +880 -0
  123. morphogen/homogenization/nonlinear.py +2612 -0
  124. morphogen/homogenization/ntfa.py +577 -0
  125. morphogen/homogenization/paths.py +476 -0
  126. morphogen/homogenization/photonic.py +467 -0
  127. morphogen/homogenization/poroelastic.py +212 -0
  128. morphogen/homogenization/porous.py +1120 -0
  129. morphogen/homogenization/postprocess.py +290 -0
  130. morphogen/homogenization/solvers.py +1140 -0
  131. morphogen/homogenization/tensors.py +240 -0
  132. morphogen/homogenization/voxel_fe.py +457 -0
  133. morphogen/homogenization/xfem.py +1016 -0
  134. morphogen/homogenization/zmat.py +1258 -0
  135. morphogen/iga/__init__.py +48 -0
  136. morphogen/iga/analysis.py +508 -0
  137. morphogen/iga/basis.py +214 -0
  138. morphogen/iga/geometry.py +501 -0
  139. morphogen/iga/homogenization.py +219 -0
  140. morphogen/iga/optimization.py +700 -0
  141. morphogen/iga/shapes.py +331 -0
  142. morphogen/image.py +128 -0
  143. morphogen/io/__init__.py +246 -0
  144. morphogen/io/amitex.py +741 -0
  145. morphogen/io/ebsd.py +881 -0
  146. morphogen/io/export.py +196 -0
  147. morphogen/io/geometry.py +158 -0
  148. morphogen/io/medit.py +147 -0
  149. morphogen/io/meshes.py +844 -0
  150. morphogen/io/metaimage.py +97 -0
  151. morphogen/io/mfront.py +1104 -0
  152. morphogen/io/native.py +57 -0
  153. morphogen/io/radioss.py +764 -0
  154. morphogen/io/solvers.py +371 -0
  155. morphogen/io/tables.py +278 -0
  156. morphogen/io/tiff.py +66 -0
  157. morphogen/io/vtk.py +701 -0
  158. morphogen/io/xdmf.py +200 -0
  159. morphogen/kernels/__init__.py +5 -0
  160. morphogen/kernels/annealing.py +192 -0
  161. morphogen/kernels/cells.py +69 -0
  162. morphogen/kernels/collective.py +87 -0
  163. morphogen/kernels/force_biased.py +595 -0
  164. morphogen/kernels/implicit.py +145 -0
  165. morphogen/kernels/leaves.py +132 -0
  166. morphogen/kernels/packing.py +304 -0
  167. morphogen/kernels/raster.py +279 -0
  168. morphogen/kernels/rsa.py +371 -0
  169. morphogen/kernels/union.py +135 -0
  170. morphogen/kernels/watershed.py +190 -0
  171. morphogen/laser/__init__.py +234 -0
  172. morphogen/laser/architectures.py +375 -0
  173. morphogen/laser/bending.py +216 -0
  174. morphogen/laser/cells.py +1694 -0
  175. morphogen/laser/design.py +940 -0
  176. morphogen/laser/figures.py +227 -0
  177. morphogen/laser/heat.py +804 -0
  178. morphogen/laser/materials.py +691 -0
  179. morphogen/laser/mechanics.py +1670 -0
  180. morphogen/laser/metallurgy.py +615 -0
  181. morphogen/laser/patterns.py +828 -0
  182. morphogen/laser/periodic.py +392 -0
  183. morphogen/laser/process.py +362 -0
  184. morphogen/laser/run.py +534 -0
  185. morphogen/laser/solid.py +216 -0
  186. morphogen/laser/specimen.py +200 -0
  187. morphogen/laser/structures.py +708 -0
  188. morphogen/learning/__init__.py +81 -0
  189. morphogen/learning/behaviour.py +398 -0
  190. morphogen/learning/data.py +328 -0
  191. morphogen/learning/learned.cpp +668 -0
  192. morphogen/learning/logarithmic.py +202 -0
  193. morphogen/learning/mfront.py +409 -0
  194. morphogen/learning/networks.py +767 -0
  195. morphogen/learning/run.py +212 -0
  196. morphogen/learning/standard.py +814 -0
  197. morphogen/learning/training.py +235 -0
  198. morphogen/mesh/__init__.py +29 -0
  199. morphogen/mesh/conforming.py +1423 -0
  200. morphogen/mesh/curved.py +600 -0
  201. morphogen/mesh/exact.py +1717 -0
  202. morphogen/mesh/octree.py +350 -0
  203. morphogen/mesh/polycrystal.py +1041 -0
  204. morphogen/mesh/polyhedra.py +677 -0
  205. morphogen/mesh/regularize.py +570 -0
  206. morphogen/mesh/surface.py +97 -0
  207. morphogen/mesh/tetra.py +512 -0
  208. morphogen/mesh/voxel.py +124 -0
  209. morphogen/micromorphic/__init__.py +31 -0
  210. morphogen/micromorphic/damage.py +359 -0
  211. morphogen/micromorphic/ductile.py +534 -0
  212. morphogen/micromorphic/finite.py +220 -0
  213. morphogen/micromorphic/microfoam.py +787 -0
  214. morphogen/micromorphic/space.py +341 -0
  215. morphogen/models/__init__.py +195 -0
  216. morphogen/models/affine.py +384 -0
  217. morphogen/models/automata.py +592 -0
  218. morphogen/models/base.py +500 -0
  219. morphogen/models/boolean.py +310 -0
  220. morphogen/models/bouligand.py +331 -0
  221. morphogen/models/branching.py +241 -0
  222. morphogen/models/combination.py +430 -0
  223. morphogen/models/deadleaves.py +766 -0
  224. morphogen/models/design.py +289 -0
  225. morphogen/models/ebsd.py +206 -0
  226. morphogen/models/fibers.py +1476 -0
  227. morphogen/models/foam.py +594 -0
  228. morphogen/models/gaussian.py +314 -0
  229. morphogen/models/growth.py +459 -0
  230. morphogen/models/hardcore.py +317 -0
  231. morphogen/models/hierarchical.py +269 -0
  232. morphogen/models/honeycomb.py +749 -0
  233. morphogen/models/implicit.py +177 -0
  234. morphogen/models/laminate.py +470 -0
  235. morphogen/models/lattice.py +351 -0
  236. morphogen/models/lattice_field.py +345 -0
  237. morphogen/models/levelset_foam.py +563 -0
  238. morphogen/models/nacre.py +411 -0
  239. morphogen/models/nested.py +924 -0
  240. morphogen/models/osteons.py +374 -0
  241. morphogen/models/pieces.py +167 -0
  242. morphogen/models/planar.py +126 -0
  243. morphogen/models/reconstruction.py +203 -0
  244. morphogen/models/scale_rich.py +1409 -0
  245. morphogen/models/scale_rich_3d.py +1616 -0
  246. morphogen/models/tessellation.py +735 -0
  247. morphogen/models/tiling_field.py +302 -0
  248. morphogen/models/tpms.py +197 -0
  249. morphogen/models/transparent.py +406 -0
  250. morphogen/models/union.py +141 -0
  251. morphogen/optimization/__init__.py +43 -0
  252. morphogen/optimization/cell.py +295 -0
  253. morphogen/optimization/filters.py +115 -0
  254. morphogen/optimization/mma.py +226 -0
  255. morphogen/optimization/run.py +219 -0
  256. morphogen/optimization/topology.py +632 -0
  257. morphogen/orientations.py +568 -0
  258. morphogen/parallel.py +599 -0
  259. morphogen/pipeline.py +978 -0
  260. morphogen/primitives.py +188 -0
  261. morphogen/results.py +564 -0
  262. morphogen/rve/__init__.py +73 -0
  263. morphogen/rve/report.py +627 -0
  264. morphogen/rve/scaling.py +363 -0
  265. morphogen/rve/study.py +1054 -0
  266. morphogen/rve/windows.py +345 -0
  267. morphogen/seeding.py +51 -0
  268. morphogen/settings.py +118 -0
  269. morphogen/stopping.py +48 -0
  270. morphogen/symmetry.py +384 -0
  271. morphogen/templates/activator_inhibitor.yaml +22 -0
  272. morphogen/templates/aggregation.yaml +23 -0
  273. morphogen/templates/boolean_cylinders.yaml +20 -0
  274. morphogen/templates/boolean_spheres.yaml +22 -0
  275. morphogen/templates/bouligand.yaml +28 -0
  276. morphogen/templates/cellular_automaton.yaml +25 -0
  277. morphogen/templates/coated_spheres.yaml +26 -0
  278. morphogen/templates/contact_fibers.yaml +27 -0
  279. morphogen/templates/cox_nanocomposite.yaml +22 -0
  280. morphogen/templates/cross_linked_fibers.yaml +26 -0
  281. morphogen/templates/curved_arcs.yaml +28 -0
  282. morphogen/templates/curved_fibers.yaml +24 -0
  283. morphogen/templates/dead_leaves.yaml +22 -0
  284. morphogen/templates/delaunay_network.yaml +22 -0
  285. morphogen/templates/dense_packing.yaml +22 -0
  286. morphogen/templates/diffusion.yaml +33 -0
  287. morphogen/templates/ebsd.yaml +34 -0
  288. morphogen/templates/ebsd_map.ctf +3087 -0
  289. morphogen/templates/fracture_composite.yaml +42 -0
  290. morphogen/templates/fracture_rubber.yaml +47 -0
  291. morphogen/templates/gaussian_excursion.yaml +17 -0
  292. morphogen/templates/graded_lattice.yaml +24 -0
  293. morphogen/templates/hardcore_fibers.yaml +22 -0
  294. morphogen/templates/hardcore_spheres.yaml +22 -0
  295. morphogen/templates/hierarchical_lattice.yaml +22 -0
  296. morphogen/templates/homogenization_acoustic_foam.yaml +36 -0
  297. morphogen/templates/homogenization_beremin.yaml +50 -0
  298. morphogen/templates/homogenization_cleavage.yaml +51 -0
  299. morphogen/templates/homogenization_cleavage_band.yaml +55 -0
  300. morphogen/templates/homogenization_contact.yaml +43 -0
  301. morphogen/templates/homogenization_crack_closure.yaml +49 -0
  302. morphogen/templates/homogenization_crystal_plasticity.yaml +50 -0
  303. morphogen/templates/homogenization_crystal_plasticity_fft.yaml +52 -0
  304. morphogen/templates/homogenization_crystallization.yaml +30 -0
  305. morphogen/templates/homogenization_debonding.yaml +43 -0
  306. morphogen/templates/homogenization_detwinning.yaml +58 -0
  307. morphogen/templates/homogenization_ductile_damage.yaml +47 -0
  308. morphogen/templates/homogenization_fatigue.yaml +40 -0
  309. morphogen/templates/homogenization_grain_fracture.yaml +56 -0
  310. morphogen/templates/homogenization_gyroid.yaml +30 -0
  311. morphogen/templates/homogenization_intergranular.yaml +43 -0
  312. morphogen/templates/homogenization_interphase.yaml +42 -0
  313. morphogen/templates/homogenization_mixed_loading.yaml +33 -0
  314. morphogen/templates/homogenization_ntfa.yaml +56 -0
  315. morphogen/templates/homogenization_piezoelectric.yaml +27 -0
  316. morphogen/templates/homogenization_polycrystal.yaml +30 -0
  317. morphogen/templates/homogenization_polycrystal_inclusions.yaml +30 -0
  318. morphogen/templates/homogenization_poroelastic.yaml +26 -0
  319. morphogen/templates/homogenization_rubber.yaml +40 -0
  320. morphogen/templates/homogenization_slip_cleavage.yaml +50 -0
  321. morphogen/templates/homogenization_spheres.yaml +31 -0
  322. morphogen/templates/homogenization_transport.yaml +29 -0
  323. morphogen/templates/homogenization_twinning.yaml +54 -0
  324. morphogen/templates/homogenization_viscoelastic.yaml +34 -0
  325. morphogen/templates/homogenization_viscoplastic.yaml +42 -0
  326. morphogen/templates/homogenization_voronoi.yaml +26 -0
  327. morphogen/templates/homogenization_xfem.yaml +23 -0
  328. morphogen/templates/hyperuniform_cells.yaml +24 -0
  329. morphogen/templates/laguerre.yaml +18 -0
  330. morphogen/templates/laser_bending.yaml +35 -0
  331. morphogen/templates/laser_cells.yaml +38 -0
  332. morphogen/templates/laser_corrugated.yaml +36 -0
  333. morphogen/templates/level_set_foam.yaml +29 -0
  334. morphogen/templates/menger_sponge.yaml +17 -0
  335. morphogen/templates/nacre.yaml +25 -0
  336. morphogen/templates/nucleation_growth.yaml +25 -0
  337. morphogen/templates/optimize_auxetic.yaml +29 -0
  338. morphogen/templates/optimize_auxetic_3d.yaml +27 -0
  339. morphogen/templates/optimize_bulk.yaml +23 -0
  340. morphogen/templates/optimize_conductivity.yaml +20 -0
  341. morphogen/templates/osteons.yaml +28 -0
  342. morphogen/templates/penetrable_spheres.yaml +21 -0
  343. morphogen/templates/poisson_fibers.yaml +21 -0
  344. morphogen/templates/random_laminate.yaml +26 -0
  345. morphogen/templates/random_lattice.yaml +27 -0
  346. morphogen/templates/random_walk_fibers.yaml +26 -0
  347. morphogen/templates/reaction_diffusion.yaml +22 -0
  348. morphogen/templates/reconstruction.yaml +22 -0
  349. morphogen/templates/rve_cellular_automaton.yaml +23 -0
  350. morphogen/templates/rve_crystal_plasticity_fft.yaml +51 -0
  351. morphogen/templates/rve_multiphysics.yaml +43 -0
  352. morphogen/templates/rve_poisson_fibers.yaml +22 -0
  353. morphogen/templates/rve_poisson_fibers_fe.yaml +33 -0
  354. morphogen/templates/rve_voronoi_windows.yaml +20 -0
  355. morphogen/templates/scale_rich_network.yaml +29 -0
  356. morphogen/templates/scale_rich_plates.yaml +30 -0
  357. morphogen/templates/sequential_dead_leaves.yaml +25 -0
  358. morphogen/templates/strut_lattice.yaml +21 -0
  359. morphogen/templates/tile_assembly.yaml +28 -0
  360. morphogen/templates/tpms.yaml +19 -0
  361. morphogen/templates/trabecular_bone.yaml +29 -0
  362. morphogen/templates/transparent_dead_leaves.yaml +23 -0
  363. morphogen/templates/vascular_tree.yaml +23 -0
  364. morphogen/templates/voronoi.yaml +20 -0
  365. morphogen/templates/wood.yaml +34 -0
  366. morphogen/templates/workflow.yaml +56 -0
  367. morphogen/texture.py +665 -0
  368. morphogen/theory.py +162 -0
  369. morphogen/viz/__init__.py +12 -0
  370. morphogen/viz/export.py +244 -0
  371. morphogen/viz/figures.py +707 -0
  372. morphogen/viz/png.py +148 -0
  373. morphogen/viz/sections.py +696 -0
  374. morphogen/viz/surfaces.py +1352 -0
  375. morphogen/viz/video.py +904 -0
  376. morphogen/viz/workflow.py +488 -0
  377. morphogen-1.0.0.dist-info/METADATA +2316 -0
  378. morphogen-1.0.0.dist-info/RECORD +381 -0
  379. morphogen-1.0.0.dist-info/WHEEL +4 -0
  380. morphogen-1.0.0.dist-info/entry_points.txt +5 -0
  381. morphogen-1.0.0.dist-info/licenses/LICENSE +674 -0
@@ -0,0 +1,241 @@
1
+ """Branching networks grown by space colonization: vascular trees, roots, corals.
2
+
3
+ Blood vessels, the airways of lungs, the roots and crowns of plants grow toward the
4
+ tissue or the space they serve. The space colonization algorithm (Runions, Lane and
5
+ Prusinkiewicz 2007) grows a tree toward attraction points scattered in the volume (the
6
+ cells that call for vessels, the light the crown seeks): at each step, every point
7
+ pulls the node of the tree nearest to it within the influence distance ``d_i``; each
8
+ pulled node grows a branch of length ``D`` toward the mean direction of its points, and
9
+ the points closer to the tree than the kill distance ``d_k`` are reached and removed.
10
+ The growth stops when no point is left within reach of the tree.
11
+
12
+ The radii follow Murray's law (1926): the radius of a vessel to the power ``n`` is the
13
+ sum of those of its branches, from tips of radius ``r_t``: ``n = 3`` minimizes the work
14
+ of a laminar flow and the volume of blood (Murray), ``n = 2`` keeps the cross-section
15
+ area (the pipe model of trees, da Vinci's rule). A root then has the radius ``r_t
16
+ N^(1/n)`` for the ``N`` tips it feeds. In a periodic box the tree grows on the torus.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ from dataclasses import dataclass
22
+ from typing import ClassVar
23
+
24
+ import numpy as np
25
+ from scipy.spatial import cKDTree
26
+
27
+ from morphogen._utils import check_positive
28
+ from morphogen.domain import Domain
29
+ from morphogen.models.base import Model, param, register
30
+ from morphogen.models.union import PrimitiveUnion
31
+ from morphogen.orientations import uniform_unit_vectors
32
+ from morphogen.primitives import Segments
33
+ from morphogen.seeding import SeedLike, make_rng
34
+
35
+ ROOT_POSITIONS = ("face", "center", "random")
36
+
37
+
38
+ def murray_radii(parents: np.ndarray, tip: float, exponent: float) -> np.ndarray:
39
+ """Radius of the segment ending at each node: ``tip`` for the tips, and Murray's law
40
+ ``r^n = sum of r_child^n`` above (the parents come before their children)."""
41
+ n = len(parents)
42
+ flow = np.zeros(n)
43
+ has_child = np.zeros(n, dtype=bool)
44
+ has_child[parents[parents >= 0]] = True
45
+ flow[~has_child] = tip**exponent
46
+ for i in range(n - 1, -1, -1):
47
+ if parents[i] >= 0:
48
+ flow[parents[i]] += flow[i]
49
+ return flow ** (1.0 / exponent)
50
+
51
+
52
+ @dataclass
53
+ class _Tree:
54
+ positions: np.ndarray # nodes (unwrapped), in order of growth
55
+ parents: np.ndarray # -1 for the roots
56
+ reached: int # attraction points reached
57
+ steps: int
58
+
59
+
60
+ @register
61
+ @dataclass(frozen=True)
62
+ class BranchingNetwork(Model):
63
+ """Branching network grown toward ``n_attractors`` random points by space
64
+ colonization (segments of ``step``), with Murray's law for the radii."""
65
+
66
+ name = "branching"
67
+ phases: ClassVar[dict[int, str]] = {0: "tissue", 1: "vessels"}
68
+ count_label = "segments"
69
+
70
+ n_attractors: int = param(2000, doc="Attraction points in the domain", kind="int")
71
+ step: float = param(0.02, doc="Length of the branch segments", unit="length")
72
+ influence: float | None = param(
73
+ None, doc="Distance within which a point pulls the tree (default: 8 steps)", unit="length"
74
+ )
75
+ kill: float | None = param(
76
+ None, doc="Distance at which the tree reaches a point (default: 2 steps)", unit="length"
77
+ )
78
+ roots: int = param(1, doc="Number of trees", kind="int")
79
+ root_position: str = param(
80
+ "face", doc="face (on the lower face along the axis), center (one tree) or random",
81
+ kind="str",
82
+ ) # fmt: skip
83
+ tip_radius: float = param(0.004, doc="Radius of the tips", unit="length")
84
+ murray_exponent: float = param(3.0, doc="Exponent n of Murray's law (3: vessels, 2: trees)")
85
+ max_steps: int = param(2000, doc="Largest number of growth steps", kind="int")
86
+ axis: int = param(2, doc="Axis of the face of the roots (0: x, 1: y, 2: z)", kind="int")
87
+
88
+ def _validate(self) -> None:
89
+ if self.n_attractors < 1:
90
+ raise ValueError("n_attractors: at least one point")
91
+ d = check_positive(self.step, "step")
92
+ if not self.kill_distance < self.influence_distance:
93
+ raise ValueError("kill: closer than the influence distance")
94
+ if self.kill_distance < 0.5 * d:
95
+ raise ValueError("kill: at least half a step (or the tree misses points)")
96
+ if self.roots < 1:
97
+ raise ValueError("roots: at least one tree")
98
+ if self.root_position not in ROOT_POSITIONS:
99
+ raise ValueError(f"root_position: one of {list(ROOT_POSITIONS)}")
100
+ if self.root_position == "center" and self.roots != 1:
101
+ raise ValueError("root_position: center grows one tree")
102
+ check_positive(self.tip_radius, "tip_radius")
103
+ if not 1.0 <= self.murray_exponent <= 4.0:
104
+ raise ValueError("murray_exponent: from 1 to 4")
105
+ if self.max_steps < 1:
106
+ raise ValueError("max_steps: at least one step")
107
+ if self.axis not in (0, 1, 2):
108
+ raise ValueError("axis: 0, 1 or 2")
109
+
110
+ @property
111
+ def influence_distance(self) -> float:
112
+ return 8.0 * self.step if self.influence is None else float(self.influence)
113
+
114
+ @property
115
+ def kill_distance(self) -> float:
116
+ return 2.0 * self.step if self.kill is None else float(self.kill)
117
+
118
+ # -- growth --------------------------------------------------------------------------
119
+
120
+ def _roots(self, rng, size: np.ndarray) -> np.ndarray:
121
+ if self.root_position == "center":
122
+ return 0.5 * size[None, :]
123
+ roots = rng.random((self.roots, 3)) * size
124
+ if self.root_position == "face":
125
+ roots[:, self.axis] = 0.0
126
+ return roots
127
+
128
+ def grow(self, rng, size: np.ndarray, periodic: bool) -> _Tree:
129
+ """Grow the trees in the box ``[0, size)`` (on the torus if ``periodic``)."""
130
+ box = size if periodic else None
131
+
132
+ def wrap(p):
133
+ if not periodic:
134
+ return p
135
+ w = np.mod(p, size)
136
+ w[w >= size] = 0.0
137
+ return w
138
+
139
+ def towards(points, nodes):
140
+ v = points - nodes
141
+ if periodic:
142
+ v -= size * np.round(v / size)
143
+ return v
144
+
145
+ points = rng.random((self.n_attractors, 3)) * size
146
+ positions = [self._roots(rng, size)]
147
+ parents = [np.full(len(positions[0]), -1, dtype=np.int64)]
148
+ n_nodes = len(positions[0])
149
+ alive = np.ones(len(points), dtype=bool)
150
+ d, di, dk = self.step, self.influence_distance, self.kill_distance
151
+
152
+ def reach(new): # the points close to new nodes are reached
153
+ idx = np.flatnonzero(alive)
154
+ if idx.size:
155
+ dist, _ = cKDTree(wrap(new), boxsize=box).query(
156
+ points[idx], k=1, distance_upper_bound=dk
157
+ )
158
+ alive[idx[np.isfinite(dist)]] = False
159
+
160
+ reach(positions[0])
161
+ steps = 0
162
+ for steps in range(1, self.max_steps + 1): # noqa: B007 (the count is returned)
163
+ idx = np.flatnonzero(alive)
164
+ if not idx.size:
165
+ break
166
+ pos = np.concatenate(positions)
167
+ tree = cKDTree(wrap(pos), boxsize=box)
168
+ dist, near = tree.query(points[idx], k=1, distance_upper_bound=di)
169
+ pulled = np.isfinite(dist)
170
+ if not pulled.any():
171
+ break
172
+ near = near[pulled]
173
+ v = towards(points[idx[pulled]], wrap(pos)[near])
174
+ v /= np.maximum(np.linalg.norm(v, axis=1), 1e-300)[:, None]
175
+ nodes = np.unique(near)
176
+ pull = np.zeros((len(pos), 3))
177
+ np.add.at(pull, near, v)
178
+ pull = pull[nodes]
179
+ norm = np.linalg.norm(pull, axis=1)
180
+ balanced = norm < 1e-9 # opposite pulls: a random direction
181
+ if balanced.any():
182
+ pull[balanced] = uniform_unit_vectors(rng, int(balanced.sum()))
183
+ norm[balanced] = 1.0
184
+ new = pos[nodes] + d * pull / norm[:, None]
185
+ # no node on top of another (a node pulled the same way twice)
186
+ gap, _ = tree.query(wrap(new), k=1)
187
+ fresh = gap > 0.25 * d
188
+ if not fresh.any():
189
+ break
190
+ new, nodes = new[fresh], nodes[fresh]
191
+ positions.append(new)
192
+ parents.append(nodes)
193
+ n_nodes += len(new)
194
+ reach(new)
195
+ return _Tree(
196
+ np.concatenate(positions),
197
+ np.concatenate(parents),
198
+ int((~alive).sum()),
199
+ steps,
200
+ )
201
+
202
+ def generate(self, domain: Domain, seed: SeedLike = None) -> PrimitiveUnion:
203
+ rng, seed_info = make_rng(seed)
204
+ size = domain.lengths
205
+ tree = self.grow(rng, size, domain.periodic)
206
+ radii = murray_radii(tree.parents, self.tip_radius, self.murray_exponent)
207
+ child = np.flatnonzero(tree.parents >= 0)
208
+ start = tree.positions[tree.parents[child]]
209
+ end = tree.positions[child]
210
+ if domain.periodic: # each segment from its end inside the box
211
+ offset = np.floor(start / size) * size
212
+ start, end = start - offset, end - offset
213
+ segments = Segments(start + domain.lower, end + domain.lower, radii[child], round_caps=True)
214
+ has_child = np.zeros(len(tree.parents), dtype=bool)
215
+ has_child[tree.parents[tree.parents >= 0]] = True
216
+ roots = np.flatnonzero(tree.parents < 0)
217
+ counts = np.bincount(tree.parents[child], minlength=len(tree.parents))
218
+ summary = {
219
+ "n_tips": int((~has_child).sum()),
220
+ "n_branchings": int((counts >= 2).sum()),
221
+ "total_length": float(np.linalg.norm(end - start, axis=1).sum()),
222
+ "root_radius": float(radii[roots].max()),
223
+ "reached_fraction": tree.reached / self.n_attractors,
224
+ "growth_steps": tree.steps,
225
+ }
226
+ return PrimitiveUnion(
227
+ domain, segments=segments, model=self, seed=seed_info, metadata={"summary": summary}
228
+ )
229
+
230
+ def expected_count(self, domain: Domain) -> float | None:
231
+ return None
232
+
233
+ def theory(self, domain: Domain | None = None) -> dict[str, float]:
234
+ """The radius of a root feeding ``N`` tips is ``r_t N^(1/n)``: the exponent of
235
+ Murray's law and the area ratio of a symmetric branching, ``2^(1 - 2/n)``."""
236
+ n = self.murray_exponent
237
+ return {
238
+ "murray_exponent": n,
239
+ "symmetric_area_ratio": 2.0 ** (1.0 - 2.0 / n),
240
+ "symmetric_radius_ratio": 2.0 ** (-1.0 / n),
241
+ }
@@ -0,0 +1,430 @@
1
+ """Combinations of models: union, intersection, difference and complement of their
2
+ phase 1, and inclusions overlaid on a matrix (a polycrystal, or any structure).
3
+
4
+ The components are independent realizations of their models in the same domain, with
5
+ seeds derived from the seed of the combination. The phase 1 of a union is the union of
6
+ the phases 1 of the components, and so on; their level sets combine by minimum, maximum
7
+ and negation, so that combinations of models with level sets are meshed conformingly.
8
+ Inclusions keep the phases of the first component (the matrix: a polycrystal keeps its
9
+ cells, their labels and orientations) and give the phase 1 of each further component a
10
+ phase of its own, the next free index by default; later components cover earlier ones.
11
+
12
+ For independent stationary random sets ``A`` and ``B`` of volume fractions ``p`` and
13
+ specific surfaces ``S`` (Matheron 1975):
14
+
15
+ * union: ``p = 1 - (1 - pA) (1 - pB)``, ``S = SA (1 - pB) + SB (1 - pA)``;
16
+ * intersection: ``p = pA pB``, ``S = SA pB + SB pA``;
17
+ * complement: ``p = 1 - pA``, ``S = SA``.
18
+
19
+ A union of a Boolean model with another is the Boolean model of both grains; the
20
+ intersection of fine inclusions with a coarse random set gives clustered (Cox-like,
21
+ multiscale) inclusions, cut by the boundary of the set (``cox_spheres`` keeps them
22
+ whole). A nested combination fills the phase 1 of each model with the next one, whose
23
+ other phases are kept: hierarchical structures (a gyroid of octet trusses...), its phase
24
+ 1 being the intersection.
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ import math
30
+ from dataclasses import dataclass
31
+ from typing import ClassVar
32
+
33
+ import numpy as np
34
+
35
+ from morphogen.domain import Domain, Grid
36
+ from morphogen.image import VoxelImage
37
+ from morphogen.models.base import Microstructure, Model, param, register, register_kind
38
+ from morphogen.seeding import SeedLike, make_rng, seed_from_description
39
+
40
+ OPERATIONS = ("union", "intersection", "difference", "complement", "inclusions", "nested")
41
+
42
+
43
+ def _set_operation(operation: str, parts: list[np.ndarray]) -> np.ndarray:
44
+ """Phase 1 of a set operation on the phase-1 indicators of the components."""
45
+ if operation == "union":
46
+ return np.logical_or.reduce(parts)
47
+ if operation in ("intersection", "nested"):
48
+ return np.logical_and.reduce(parts)
49
+ if operation == "difference":
50
+ return parts[0] & ~np.logical_or.reduce(parts[1:])
51
+ return ~parts[0] # complement
52
+
53
+
54
+ @register_kind
55
+ class Combined(Microstructure):
56
+ """Realization of a combination: its components and how they combine."""
57
+
58
+ kind = "combination"
59
+
60
+ def __init__(
61
+ self,
62
+ domain: Domain,
63
+ operation: str,
64
+ parts,
65
+ inclusion_phases=None,
66
+ **kwargs,
67
+ ) -> None:
68
+ super().__init__(domain, **kwargs)
69
+ if operation not in OPERATIONS:
70
+ raise ValueError(f"operation: one of {', '.join(OPERATIONS)}")
71
+ self.operation = operation
72
+ self.parts = list(parts)
73
+ self.inclusion_phases = (
74
+ None if inclusion_phases is None else [int(p) for p in inclusion_phases]
75
+ )
76
+
77
+ @property
78
+ def matrix(self) -> Microstructure:
79
+ return self.parts[0]
80
+
81
+ # -- discretization ------------------------------------------------------------------
82
+
83
+ def _phases_on(self, grid: Grid) -> np.ndarray:
84
+ images = [p.voxelize(grid=grid).data for p in self.parts]
85
+ if self.operation == "nested": # each structure fills the phase 1 of the previous
86
+ out = images[0].astype(np.uint8, copy=True)
87
+ for img in images[1:]:
88
+ inside = out == 1
89
+ out[inside] = img[inside]
90
+ return out
91
+ if self.operation != "inclusions":
92
+ return _set_operation(self.operation, [img == 1 for img in images]).astype(np.uint8)
93
+ out = images[0].astype(np.uint8, copy=True)
94
+ for img, phase in zip(images[1:], self.inclusion_phases, strict=True):
95
+ out[img == 1] = phase
96
+ return out
97
+
98
+ def voxelize(self, shape=None, *, voxel_size=None, grid: Grid | None = None, supersampling=1):
99
+ grid = self.grid(shape, voxel_size=voxel_size, grid=grid)
100
+ ss = int(supersampling)
101
+ if ss == 1:
102
+ data = self._phases_on(grid)
103
+ return VoxelImage.from_grid(data, grid, name="phase", metadata=self.image_metadata())
104
+ if not 1 <= ss <= 6:
105
+ raise ValueError("supersampling must be an integer between 1 and 6")
106
+ fine = Grid(grid.domain, tuple(n * ss for n in grid.shape))
107
+ ph = (self._phases_on(fine) == 1).astype(np.float32)
108
+ nx, ny, nz = grid.shape
109
+ data = ph.reshape(nx, ss, ny, ss, nz, ss).mean(axis=(1, 3, 5), dtype=np.float32)
110
+ return VoxelImage.from_grid(data, grid, name="fraction", metadata=self.image_metadata())
111
+
112
+ def level_set(self, shape=None, *, voxel_size=None, grid: Grid | None = None) -> VoxelImage:
113
+ """Minimum (union), maximum (intersection) or negation (complement) of the level
114
+ sets of the components."""
115
+ if self.operation == "inclusions":
116
+ return super().level_set(shape, voxel_size=voxel_size, grid=grid)
117
+ grid = self.grid(shape, voxel_size=voxel_size, grid=grid)
118
+ fields = [p.level_set(grid=grid).data.astype(np.float32) for p in self.parts]
119
+ if self.operation == "union":
120
+ data = np.minimum.reduce(fields)
121
+ elif self.operation in ("intersection", "nested"):
122
+ data = np.maximum.reduce(fields)
123
+ elif self.operation == "difference":
124
+ data = np.maximum(fields[0], -np.minimum.reduce(fields[1:]))
125
+ else:
126
+ data = -fields[0]
127
+ return VoxelImage.from_grid(data, grid, name="level_set", metadata=self.image_metadata())
128
+
129
+ def implicit_phases(self) -> list[int]:
130
+ if self.operation == "inclusions":
131
+ return sorted({*self.matrix.implicit_phases(), *self.inclusion_phases})
132
+ if self.operation == "nested": # the phases of each structure, in the phase 1 of the last
133
+ phases = set(self.parts[-1].implicit_phases())
134
+ for part in self.parts[:-1]:
135
+ phases |= set(part.implicit_phases()) - {1}
136
+ return sorted(phases)
137
+ return [0, 1]
138
+
139
+ def phase_level_set(
140
+ self, phase: int, shape=None, *, voxel_size=None, grid: Grid | None = None
141
+ ) -> VoxelImage:
142
+ """The implicit function of a phase (see :meth:`Microstructure.phase_level_set`).
143
+ Inclusions: a phase is what the matrix has of it outside all the inclusions,
144
+ and each inclusion of that phase outside the later ones, which cover it. Nested
145
+ structures: a phase is what each structure has of it inside the phase 1 of all
146
+ the previous ones."""
147
+ phase = int(phase)
148
+ if self.operation not in ("inclusions", "nested"):
149
+ return super().phase_level_set(phase, shape, voxel_size=voxel_size, grid=grid)
150
+ if phase not in self.implicit_phases():
151
+ raise ValueError(f"phase {phase}: the phases are {self.implicit_phases()}")
152
+ grid = self.grid(shape, voxel_size=voxel_size, grid=grid)
153
+
154
+ def of(part, k):
155
+ if k not in part.implicit_phases():
156
+ return None
157
+ return np.asarray(part.phase_level_set(k, grid=grid).data, dtype=np.float32)
158
+
159
+ data = None
160
+
161
+ def add(field):
162
+ nonlocal data
163
+ if field is not None:
164
+ data = field if data is None else np.minimum(data, field)
165
+
166
+ if self.operation == "inclusions":
167
+ covers = [of(part, 1) for part in self.parts[1:]]
168
+ later = None # the smallest function of the inclusions that cover the current one
169
+ for cover, k in zip(covers[::-1], self.inclusion_phases[::-1], strict=True):
170
+ if k == phase:
171
+ add(cover if later is None else np.maximum(cover, -later))
172
+ later = cover if later is None else np.minimum(later, cover)
173
+ field = of(self.matrix, phase)
174
+ if field is not None:
175
+ add(field if later is None else np.maximum(field, -later))
176
+ else:
177
+ inside = None # the largest function of the phases 1 of the previous structures
178
+ for i, part in enumerate(self.parts):
179
+ last = i == len(self.parts) - 1
180
+ if phase != 1 or last:
181
+ field = of(part, phase)
182
+ if field is not None:
183
+ add(field if inside is None else np.maximum(field, inside))
184
+ if not last:
185
+ one = of(part, 1)
186
+ inside = one if inside is None else np.maximum(inside, one)
187
+ return VoxelImage.from_grid(data, grid, name="level_set", metadata=self.image_metadata())
188
+
189
+ @property
190
+ def lipschitz(self) -> float:
191
+ return max(float(getattr(p, "lipschitz", 1.0)) for p in self.parts)
192
+
193
+ def phase_level_sets_at(self, points, reach: float = np.inf) -> dict[int, np.ndarray]:
194
+ """The functions of :meth:`phase_level_set` at the points, from those of the
195
+ components (:meth:`~morphogen.models.base.Microstructure.phase_level_sets_at`).
196
+ Inclusions: the visible parts of the inclusions of a phase (each minus the later
197
+ ones, ``max(psi_i, -min_{j > i} psi_j)``) and the phase of the matrix where no
198
+ inclusion covers it; nested structures: a phase of each structure inside the
199
+ phase 1 of all the previous ones; the others (two phases): that of
200
+ :meth:`level_set_at`. A component without point-wise functions (a polycrystal
201
+ matrix of one phase) leaves the combination without them."""
202
+ if self.operation not in ("inclusions", "nested"):
203
+ return super().phase_level_sets_at(points, reach)
204
+ pts = np.asarray(points, dtype=float).reshape(-1, 3)
205
+ values = [p.phase_level_sets_at(pts, reach) for p in self.parts]
206
+ out: dict[int, np.ndarray] = {}
207
+
208
+ def add(phase, field):
209
+ if field is not None:
210
+ out[phase] = field if phase not in out else np.minimum(out[phase], field)
211
+
212
+ if self.operation == "inclusions":
213
+ later = None # the smallest function of the inclusions after the current one
214
+ covers = [v[1] for v in values[1:]]
215
+ for cover, k in zip(covers[::-1], self.inclusion_phases[::-1], strict=True):
216
+ add(k, cover if later is None else np.maximum(cover, -later))
217
+ later = cover if later is None else np.minimum(later, cover)
218
+ for k, field in values[0].items(): # the matrix where no inclusion covers it
219
+ add(k, field if later is None else np.maximum(field, -later))
220
+ else:
221
+ inside = None # the largest function of the phases 1 of the previous structures
222
+ for i, part in enumerate(values):
223
+ last = i == len(values) - 1
224
+ for k, field in part.items():
225
+ if k != 1 or last:
226
+ add(k, field if inside is None else np.maximum(field, inside))
227
+ if not last:
228
+ inside = part[1] if inside is None else np.maximum(inside, part[1])
229
+ return {k: out[k] for k in self.implicit_phases() if k in out}
230
+
231
+ def level_set_at(self, points, reach: float = np.inf) -> np.ndarray:
232
+ """The level sets of the components at the points, combined as :meth:`level_set`
233
+ (inclusions: the function of phase 1, see :meth:`phase_level_sets_at`)."""
234
+ if self.operation == "inclusions":
235
+ if 1 in self.implicit_phases():
236
+ return self.phase_level_sets_at(points, reach)[1]
237
+ return super().level_set_at(points, reach)
238
+ fields = [p.level_set_at(points, reach) for p in self.parts]
239
+ if self.operation == "union":
240
+ return np.minimum.reduce(fields)
241
+ if self.operation in ("intersection", "nested"):
242
+ return np.maximum.reduce(fields)
243
+ if self.operation == "difference":
244
+ return np.maximum(fields[0], -np.minimum.reduce(fields[1:]))
245
+ return -fields[0]
246
+
247
+ def contains(self, points) -> np.ndarray:
248
+ inside = [p.contains(points) for p in self.parts]
249
+ if self.operation != "inclusions":
250
+ return _set_operation(self.operation, inside)
251
+ out = inside[0].copy() # phase 1 of the matrix, unless covered by an inclusion
252
+ for covered, phase in zip(inside[1:], self.inclusion_phases, strict=True):
253
+ out[covered] = phase == 1
254
+ return out
255
+
256
+ # -- grains of a polycrystal matrix ----------------------------------------------------
257
+
258
+ @property
259
+ def has_labels(self) -> bool:
260
+ return self.operation == "inclusions" and self.matrix.has_labels
261
+
262
+ def labels(self, shape=None, *, voxel_size=None, grid: Grid | None = None) -> VoxelImage:
263
+ """Cell labels of the matrix (the inclusions keep the label of their cell)."""
264
+ if not self.has_labels:
265
+ raise NotImplementedError("only inclusions in a tessellation have cell labels")
266
+ return self.matrix.labels(shape, voxel_size=voxel_size, grid=grid)
267
+
268
+ @property
269
+ def orientations(self):
270
+ return getattr(self.matrix, "orientations", None) if self.has_labels else None
271
+
272
+ # -- description ------------------------------------------------------------------------
273
+
274
+ def summary(self) -> dict:
275
+ out: dict = {}
276
+ for k, part in enumerate(self.parts):
277
+ out.update({f"c{k}_{key}": value for key, value in part.summary().items()})
278
+ return out
279
+
280
+ def _geometry(self) -> dict:
281
+ geo = {"operation": self.operation, "parts": [p.to_dict() for p in self.parts]}
282
+ if self.inclusion_phases is not None:
283
+ geo["inclusion_phases"] = self.inclusion_phases
284
+ return geo
285
+
286
+ @classmethod
287
+ def _from_geometry(cls, domain, geometry, **kwargs):
288
+ parts = [Microstructure.from_dict(d) for d in geometry["parts"]]
289
+ return cls(domain, geometry["operation"], parts, geometry.get("inclusion_phases"), **kwargs)
290
+
291
+
292
+ @register
293
+ @dataclass(frozen=True)
294
+ class Combination(Model):
295
+ """Union, intersection, difference or complement of models, or inclusions in a matrix."""
296
+
297
+ name = "combination"
298
+ phases: ClassVar[dict[int, str]] = {0: "outside", 1: "combined phase 1"}
299
+
300
+ operation: str = param(
301
+ "union",
302
+ doc="union, intersection, difference (the first minus the others), complement "
303
+ "(of a single model), inclusions (the phase 1 of the others over the first) or "
304
+ "nested (each model fills the phase 1 of the previous one, with its phases)",
305
+ kind="str",
306
+ )
307
+ models: tuple = param(
308
+ (), doc="Models combined: mappings with a 'type' key and their parameters", kind="models"
309
+ )
310
+ inclusion_phases: tuple[int, ...] | None = param(
311
+ None,
312
+ doc="Inclusions: phase of each model after the first (default: the next free phases)",
313
+ kind="ints",
314
+ )
315
+
316
+ def _validate(self) -> None:
317
+ if self.operation not in OPERATIONS:
318
+ raise ValueError(f"operation: one of {', '.join(OPERATIONS)}")
319
+ if self.operation == "complement":
320
+ if len(self.models) != 1:
321
+ raise ValueError("models: the complement of exactly one model")
322
+ elif len(self.models) < 2:
323
+ raise ValueError(f"models: at least two models for the {self.operation}")
324
+ if self.inclusion_phases is not None:
325
+ if self.operation != "inclusions":
326
+ raise ValueError("inclusion_phases: only for the 'inclusions' operation")
327
+ if len(self.inclusion_phases) != len(self.models) - 1:
328
+ raise ValueError("inclusion_phases: one phase per model after the first")
329
+ if not all(0 <= p <= 255 for p in self.inclusion_phases):
330
+ raise ValueError("inclusion_phases: phase indices from 0 to 255")
331
+
332
+ # -- properties that depend on the components -------------------------------------------
333
+
334
+ @property
335
+ def supports_periodic(self) -> bool:
336
+ return all(m.supports_periodic for m in self.models)
337
+
338
+ @property
339
+ def has_level_set(self) -> bool:
340
+ return self.operation != "inclusions" and all(m.has_level_set for m in self.models)
341
+
342
+ @property
343
+ def phases_of_inclusions(self) -> list[int]:
344
+ """Phase of each inclusion model (the next free indices by default)."""
345
+ if self.operation != "inclusions":
346
+ return []
347
+ if self.inclusion_phases is not None:
348
+ return list(self.inclusion_phases)
349
+ start = max(self.models[0].active_phases()) + 1
350
+ return list(range(start, start + len(self.models) - 1))
351
+
352
+ def active_phases(self) -> dict[int, str]:
353
+ if self.operation == "nested":
354
+ out = {0: "outside", 1: "phase 1 of every model"}
355
+ for model in self.models[1:]:
356
+ for phase, name in model.active_phases().items():
357
+ out.setdefault(phase, f"{name} ({model.name})")
358
+ return out
359
+ if self.operation != "inclusions":
360
+ return dict(self.phases)
361
+ out = self.models[0].active_phases()
362
+ for model, phase in zip(self.models[1:], self.phases_of_inclusions, strict=True):
363
+ out[phase] = f"inclusions ({model.name})"
364
+ return out
365
+
366
+ # -- realizations -----------------------------------------------------------------------
367
+
368
+ def generate(self, domain: Domain, seed: SeedLike = None) -> Combined:
369
+ self._check_domain(domain)
370
+ rng, seed_info = make_rng(seed)
371
+ if seed_info is not None: # children of the seed sequence: reproducible
372
+ seeds = list(seed_from_description(seed_info).spawn(len(self.models)))
373
+ else:
374
+ seeds = list(rng.spawn(len(self.models)))
375
+ parts = [m.generate(domain, s) for m, s in zip(self.models, seeds, strict=True)]
376
+ phases = self.phases_of_inclusions if self.operation == "inclusions" else None
377
+ if phases is not None and max(phases) > 255:
378
+ raise ValueError("inclusion_phases: phase indices from 0 to 255")
379
+ return Combined(domain, self.operation, parts, phases, model=self, seed=seed_info)
380
+
381
+ def theory(self, domain: Domain | None = None) -> dict[str, float]:
382
+ """Volume fraction and specific surface of set operations on independent
383
+ components, when theirs are known."""
384
+ if self.operation == "inclusions":
385
+ return {}
386
+ values = []
387
+ for m in self.models:
388
+ try:
389
+ t = m.theory(domain)
390
+ except (ValueError, NotImplementedError):
391
+ return {}
392
+ values.append(t)
393
+ out = {}
394
+ if all("volume_fraction" in t for t in values):
395
+ p = [t["volume_fraction"] for t in values]
396
+ out["volume_fraction"] = _fraction(self.operation, p)
397
+ if all("specific_surface" in t for t in values):
398
+ s = [t["specific_surface"] for t in values]
399
+ out["specific_surface"] = _surface(self.operation, p, s)
400
+ return out
401
+
402
+
403
+ def _fraction(operation: str, p: list[float]) -> float:
404
+ if operation == "union":
405
+ return 1.0 - math.prod(1.0 - x for x in p)
406
+ if operation in ("intersection", "nested"):
407
+ return math.prod(p)
408
+ if operation == "difference":
409
+ return p[0] * math.prod(1.0 - x for x in p[1:])
410
+ return 1.0 - p[0]
411
+
412
+
413
+ def _surface(operation: str, p: list[float], s: list[float]) -> float:
414
+ """Surface of the boundary of a set operation on independent sets: the boundary of
415
+ each set where the others leave it on the boundary of the result."""
416
+ if operation == "complement":
417
+ return s[0]
418
+ total = 0.0
419
+ for i, si in enumerate(s):
420
+ others = [x for j, x in enumerate(p) if j != i]
421
+ if operation == "union":
422
+ total += si * math.prod(1.0 - x for x in others)
423
+ elif operation in ("intersection", "nested"):
424
+ total += si * math.prod(others)
425
+ elif i == 0: # difference: boundary of A outside the others
426
+ total += si * math.prod(1.0 - x for x in others)
427
+ else: # boundary of another set inside A and outside the rest
428
+ rest = [x for j, x in enumerate(p[1:], start=1) if j != i]
429
+ total += si * p[0] * math.prod(1.0 - x for x in rest)
430
+ return total