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,363 @@
1
+ """Statistical size of the representative volume element (RVE).
2
+
3
+ Following Matheron (1971), Kanit et al. (2003) and Lantuéjoul (1991), the ensemble
4
+ variance of the average of a property Z over a volume V scales as
5
+
6
+ D_Z^2(V) = D_Z^2 (A3 / V) (finite integral range A3)
7
+ D_Z^2(V) = K V^(-gamma) (general power law, K = D_Z^2 A3*^gamma)
8
+
9
+ With n realizations of volume V, the relative error on the mean is
10
+ eps_rel = 2 D_Z(V) / (Zbar sqrt(n)), hence the RVE volume
11
+
12
+ V_RVE = (4 K / (eps_rel^2 Zbar^2 n))^(1 / gamma).
13
+
14
+ "Volumes" may equally be lengths or areas (1D/2D samples, e.g. Bironeau et al. 2016), the
15
+ edge of a sample then ``V^(1/d)`` in dimension ``d`` (the side of a square of area ``V``).
16
+
17
+ Shifted tilings (the window method on a periodic image, ``shifts > 1``). The ``T`` tilings
18
+ of the windows of edge ``w`` shifted by the offsets ``k w // shifts`` along each axis are
19
+ translates of the first on the torus: by stationarity the windows of each have the joint
20
+ law of the unshifted ones, and its variance the law of theirs. The mean over all the
21
+ windows of all the tilings is the mean of the tiling means, each the image mean when the
22
+ edges of the image are multiples of ``w``. ``D^2(V)`` is the variance pooled within the
23
+ tilings, ``sum_t sum_(k in t) (Z_k - Zbar_t)^2 / sum_t (n_t - 1)``, with ``n_t = n``
24
+ windows in each the mean of their unbiased variances: of the expectation of the variance
25
+ of one tiling (unbiased under the hypothesis that makes that one unbiased, its windows
26
+ uncorrelated as for ``V >> A3``), of a smaller scatter. Not the variance of the ``T n``
27
+ windows about their mean with ``T n - 1`` degrees of freedom, lower by the factor ``T (n -
28
+ 1) / (T n - 1)``: the windows of different tilings overlap, so that their mean (the image
29
+ mean) is known no better than from one tiling, the deviations of each tiling summing to
30
+ zero. The count behind the uncertainties stays ``n``, the windows of one tiling (the
31
+ independent ones): the shifts leave the mean unchanged, whose standard error stays ``D(V) /
32
+ sqrt(n)``; the relative errors, the Student tests of the components of the tensors and the
33
+ weights ``(n - 1) / 2`` of the fits count ``n`` too, conservatively for the variance, to
34
+ which the overlapping windows add correlated, not independent, samples. The fits and the
35
+ RVE sizes follow from these variances, unchanged.
36
+ """
37
+
38
+ from __future__ import annotations
39
+
40
+ import itertools
41
+ import math
42
+ from dataclasses import asdict, dataclass
43
+
44
+ import numpy as np
45
+ from scipy import stats as _stats
46
+
47
+ from morphogen.analysis.basic import as_array, indicator
48
+
49
+
50
+ def point_variance(fraction: float, z1: float = 1.0, z0: float = 0.0) -> float:
51
+ """D_Z^2 = p (1 - p) (Z1 - Z0)^2 of a two-phase medium (p: fraction of phase 1)."""
52
+ return fraction * (1.0 - fraction) * (z1 - z0) ** 2
53
+
54
+
55
+ def point_variance_multiphase(fractions, values) -> float:
56
+ """D_Z^2 = sum_i P_i (Z_i - Zbar)^2 (Yang et al. 2019, eq. 19)."""
57
+ p = np.asarray(fractions, dtype=float)
58
+ z = np.asarray(values, dtype=float)
59
+ zbar = np.sum(p * z) / np.sum(p)
60
+ return float(np.sum(p * (z - zbar) ** 2) / np.sum(p))
61
+
62
+
63
+ @dataclass(frozen=True)
64
+ class SizeStatistics:
65
+ """Ensemble statistics of a property for several sample sizes.
66
+
67
+ ``dimension``: that of the samples, whose measures the volumes are (3, cubes; 2, the
68
+ squares of a planar image, their areas), their edges ``V^(1/dimension)``
69
+ (:meth:`edges`). ``tilings``: the number of shifted tilings of each size by the window
70
+ method (:func:`window_statistics`), ``n`` then the windows of one tiling and
71
+ ``variance`` their variance pooled within the tilings (see the module); None: one
72
+ tiling, or realizations.
73
+ """
74
+
75
+ volume: np.ndarray
76
+ n: np.ndarray
77
+ mean: np.ndarray
78
+ variance: np.ndarray
79
+ dimension: int = 3
80
+ tilings: np.ndarray | None = None
81
+
82
+ def edges(self) -> np.ndarray:
83
+ """The edges of the samples, ``V^(1/dimension)``: of cubes, of squares."""
84
+ return np.array([float(v) ** (1.0 / self.dimension) for v in self.volume])
85
+
86
+ def relative_error(self) -> np.ndarray:
87
+ """``eps_rel = 2 sqrt(D^2(V) / n) / |Zbar|`` for each size."""
88
+ return 2.0 * np.sqrt(self.variance / self.n) / np.abs(self.mean)
89
+
90
+ def rows(self) -> list[dict]:
91
+ """One row per size: its volume, its count ``n`` (and its tilings when shifted), the
92
+ mean, the variance and the relative error."""
93
+ err = self.relative_error()
94
+ columns = zip(self.volume, self.n, self.mean, self.variance, err, strict=True)
95
+ rows = []
96
+ for i, (v, k, m, s, e) in enumerate(columns):
97
+ row = {"volume": float(v), "n": int(k)}
98
+ if self.tilings is not None:
99
+ row["tilings"] = int(self.tilings[i])
100
+ row.update(mean=float(m), variance=float(s), relative_error=float(e))
101
+ rows.append(row)
102
+ return rows
103
+
104
+
105
+ def ensemble_statistics(volumes, values) -> SizeStatistics:
106
+ """Group values by volume: mean and unbiased variance per size."""
107
+ v = np.asarray(volumes, dtype=float)
108
+ z = np.asarray(values, dtype=float)
109
+ if v.shape != z.shape:
110
+ raise ValueError("volumes and values must have the same length")
111
+ ok = np.isfinite(z)
112
+ v, z = v[ok], z[ok]
113
+ sizes = np.unique(v)
114
+ n = np.array([np.count_nonzero(v == s) for s in sizes])
115
+ mean = np.array([z[v == s].mean() for s in sizes])
116
+ var = np.array(
117
+ [z[v == s].var(ddof=1) if c > 1 else np.nan for s, c in zip(sizes, n, strict=True)]
118
+ )
119
+ return SizeStatistics(sizes, n, mean, var)
120
+
121
+
122
+ @dataclass(frozen=True)
123
+ class ScalingLaw:
124
+ """D_Z^2(V) = K V^(-gamma), fitted in log-log coordinates."""
125
+
126
+ K: float
127
+ gamma: float
128
+ gamma_fixed: bool = False
129
+ r2: float = math.nan
130
+ n_points: int = 0
131
+ volume_min: float = math.nan
132
+ volume_max: float = math.nan
133
+ #: standard errors of gamma (free fits with at least 3 sizes) and of ln K
134
+ gamma_se: float = math.nan
135
+ log_k_se: float = math.nan
136
+
137
+ def _t(self, level: float, n_params: int) -> float:
138
+ dof = self.n_points - n_params
139
+ return float(_stats.t.ppf(0.5 + level / 2.0, dof)) if dof > 0 else math.nan
140
+
141
+ def gamma_interval(self, level: float = 0.95) -> tuple[float, float]:
142
+ """Confidence interval of gamma (Student t, from the scatter about the fit)."""
143
+ if self.gamma_fixed:
144
+ return self.gamma, self.gamma
145
+ half = self._t(level, 2) * self.gamma_se
146
+ return self.gamma - half, self.gamma + half
147
+
148
+ def k_interval(self, level: float = 0.95) -> tuple[float, float]:
149
+ """Confidence interval of K."""
150
+ half = self._t(level, 1 if self.gamma_fixed else 2) * self.log_k_se
151
+ return self.K * math.exp(-half), self.K * math.exp(half)
152
+
153
+ def variance(self, volume) -> np.ndarray:
154
+ return self.K * np.asarray(volume, dtype=float) ** (-self.gamma)
155
+
156
+ def relative_error(self, volume, n, mean) -> np.ndarray:
157
+ return 2.0 * np.sqrt(self.variance(volume) / np.asarray(n, dtype=float)) / abs(mean)
158
+
159
+ def rve_volume(self, eps_rel, mean: float, n=1) -> np.ndarray:
160
+ """Volume for which n realizations give the mean within ``eps_rel`` (relative)."""
161
+ eps = np.asarray(eps_rel, dtype=float)
162
+ n = np.asarray(n, dtype=float)
163
+ return (4.0 * self.K / (eps**2 * mean**2 * n)) ** (1.0 / self.gamma)
164
+
165
+ def realizations(self, volume, eps_rel, mean: float) -> np.ndarray:
166
+ """Number of realizations of the given volume needed for ``eps_rel``."""
167
+ eps = np.asarray(eps_rel, dtype=float)
168
+ return 4.0 * self.variance(volume) / (eps**2 * mean**2)
169
+
170
+ def integral_range(self, point_var: float) -> float:
171
+ """A3* = (K / D_Z^2)^(1/gamma) (the integral range A3 when gamma = 1)."""
172
+ return (self.K / point_var) ** (1.0 / self.gamma)
173
+
174
+ def to_dict(self) -> dict:
175
+ return {
176
+ k: (None if isinstance(v, float) and not math.isfinite(v) else v)
177
+ for k, v in asdict(self).items()
178
+ }
179
+
180
+
181
+ def fit_scaling_law(
182
+ volumes, variances, *, gamma: float | None = None, volume_range=None, weights=None
183
+ ) -> ScalingLaw:
184
+ """Least-squares fit of log D^2 = log K - gamma log V (gamma free or imposed)."""
185
+ v = np.asarray(volumes, dtype=float)
186
+ d2 = np.asarray(variances, dtype=float)
187
+ ok = np.isfinite(v) & np.isfinite(d2) & (v > 0) & (d2 > 0)
188
+ if volume_range is not None:
189
+ lo, hi = volume_range
190
+ ok &= (v >= (lo if lo is not None else -np.inf)) & (v <= (hi if hi is not None else np.inf))
191
+ v, d2 = v[ok], d2[ok]
192
+ w = np.ones_like(v) if weights is None else np.asarray(weights, dtype=float)[ok]
193
+ needed = 1 if gamma is not None else 2
194
+ if len(v) < needed:
195
+ raise ValueError(f"fit_scaling_law: need at least {needed} sizes with a positive variance")
196
+ x, y = np.log(v), np.log(d2)
197
+ m = len(v)
198
+ xm = np.average(x, weights=w)
199
+ sxx = np.sum(w * (x - xm) ** 2)
200
+ if gamma is None:
201
+ ym = np.average(y, weights=w)
202
+ if sxx == 0:
203
+ raise ValueError("fit_scaling_law: need at least two different volumes")
204
+ slope = np.sum(w * (x - xm) * (y - ym)) / sxx
205
+ g, log_k = -slope, ym - slope * xm
206
+ else:
207
+ g = float(gamma)
208
+ log_k = np.average(y + g * x, weights=w)
209
+ pred = log_k - g * x
210
+ ss_res = np.sum(w * (y - pred) ** 2)
211
+ ss_tot = np.sum(w * (y - np.average(y, weights=w)) ** 2)
212
+ r2 = 1.0 - ss_res / ss_tot if ss_tot > 0 else math.nan
213
+ n_params = 1 if gamma is not None else 2
214
+ gamma_se = log_k_se = math.nan
215
+ if m > n_params:
216
+ s2 = ss_res / (m - n_params)
217
+ if gamma is None:
218
+ gamma_se = math.sqrt(s2 / sxx)
219
+ log_k_se = math.sqrt(s2 * (1.0 / np.sum(w) + xm**2 / sxx))
220
+ else:
221
+ log_k_se = math.sqrt(s2 / np.sum(w))
222
+ return ScalingLaw(
223
+ K=float(math.exp(log_k)),
224
+ gamma=float(g),
225
+ gamma_fixed=gamma is not None,
226
+ r2=float(r2),
227
+ n_points=m,
228
+ volume_min=float(v.min()),
229
+ volume_max=float(v.max()),
230
+ gamma_se=float(gamma_se),
231
+ log_k_se=float(log_k_se),
232
+ )
233
+
234
+
235
+ def fit_statistics(stats: SizeStatistics, *, gamma=None, volume_range=None) -> ScalingLaw:
236
+ """The scaling law of the variance with the volume (:func:`fit_scaling_law`) fitted to the
237
+ statistics of a study by size, ``gamma`` given or fitted, within ``volume_range``."""
238
+ return fit_scaling_law(stats.volume, stats.variance, gamma=gamma, volume_range=volume_range)
239
+
240
+
241
+ def rve_volume_classic(point_var, integral_range, eps_rel, mean, n=1) -> float:
242
+ """V_RVE = 4 D_Z^2 A3 / (eps^2 Zbar^2 n) (Kanit et al. 2003)."""
243
+ return 4.0 * point_var * integral_range / (eps_rel**2 * mean**2 * n)
244
+
245
+
246
+ def _shift_count(shifts, periodic: bool) -> int:
247
+ """The number of tilings per axis of the window method: a positive integer, more than
248
+ one only on a periodic image (the shifted tilings wrap around it). The refusals of
249
+ :func:`window_statistics`, :func:`~morphogen.rve.windows.window_tensors` and the RVE
250
+ tool of the interface."""
251
+ if isinstance(shifts, bool) or not isinstance(shifts, (int, np.integer)) or shifts < 1:
252
+ raise ValueError(f"shifts: a positive integer (tilings per axis), got {shifts!r}")
253
+ if shifts > 1 and not periodic:
254
+ raise ValueError("shifts: the shifted tilings wrap around the image, a periodic one")
255
+ return int(shifts)
256
+
257
+
258
+ def _offsets(edge: int, shifts: int, planar: bool) -> np.ndarray:
259
+ """The offsets (voxels, ``(t, 3)``) of the tilings of the windows of ``edge`` voxels
260
+ shifted ``shifts`` times along each axis that they tile (x, y, and z but across a planar
261
+ image): the distinct ``k edge // shifts``, ``k < shifts``, all their combinations, the
262
+ unshifted tiling first."""
263
+ steps = sorted({k * edge // shifts for k in range(shifts)})
264
+ product = itertools.product(steps, steps, [0] if planar else steps)
265
+ return np.array(list(product), dtype=np.int64)
266
+
267
+
268
+ def _pooled_variance(values: np.ndarray, tilings: np.ndarray) -> np.ndarray:
269
+ """The variance of ``values`` (along their first axis) pooled within their ``tilings``
270
+ (the tiling of each value), ``sum_t sum_(k in t) (z_k - zbar_t)^2 / sum_t (n_t - 1)``
271
+ (NaN without a tiling of two values; see the module)."""
272
+ squares = np.zeros(values.shape[1:])
273
+ dof = 0
274
+ for t in np.unique(tilings):
275
+ x = values[tilings == t]
276
+ if len(x) > 1:
277
+ squares = squares + ((x - x.mean(axis=0)) ** 2).sum(axis=0)
278
+ dof += len(x) - 1
279
+ return squares / dof if dof else np.full(values.shape[1:], np.nan)
280
+
281
+
282
+ def _moments(values: np.ndarray, tilings: np.ndarray | None = None) -> tuple:
283
+ """The count, the mean and the unbiased variance of values: of realizations, or of the
284
+ windows of one tiling (``tilings`` None or a single one); of the windows of shifted
285
+ tilings (``tilings`` the tiling of each), the windows of one (their mean count), the
286
+ mean of all and their variance pooled within the tilings (see the module)."""
287
+ groups = 1 if tilings is None else np.unique(tilings).size
288
+ if groups == 1:
289
+ return values.size, values.mean(), values.var(ddof=1) if values.size > 1 else np.nan
290
+ return values.size // groups, values.mean(), float(_pooled_variance(values, tilings))
291
+
292
+
293
+ def window_statistics(
294
+ image, window_sizes, *, phase: int | None = 1, spacing=None, shifts: int = 1, periodic=None
295
+ ):
296
+ """Window method: statistics of the mean over non-overlapping cubic sub-volumes.
297
+
298
+ ``window_sizes`` are window edges in voxels. With ``phase`` the averaged quantity
299
+ is the indicator of that phase (volume fraction); with ``phase=None`` the image
300
+ values themselves (e.g. a local field computed by an FFT or FE solver). Across a
301
+ planar image (``nz = 1``) the windows are squares of ``w`` pixels, whose measure is
302
+ their area (``dimension = 2``, their edges the roots of their areas). ``shifts``: the
303
+ tilings per axis, 1 (by default) the tiling from the origin of the image, the
304
+ remainder left out; ``shifts > 1`` adds the tilings shifted by the offsets ``k w //
305
+ shifts`` voxels (``k < shifts``) along each axis that the windows tile, all their
306
+ combinations (``shifts^3`` tilings of cubes, ``shifts^2`` of squares, fewer for
307
+ windows of fewer voxels), wrapping around the periodic image (``periodic``: None, that
308
+ of a :class:`~morphogen.image.VoxelImage`; an array is not): the mean of all their
309
+ windows, their variance pooled within the tilings, ``n`` the windows of one tiling and
310
+ ``tilings`` their number (see the module). The tensors of the windows:
311
+ :func:`morphogen.rve.windows.window_tensors`.
312
+ """
313
+ data = as_array(image)
314
+ field = data.astype(np.float64) if phase is None else indicator(data, phase)
315
+ if spacing is None:
316
+ spacing = getattr(image, "spacing", (1.0, 1.0, 1.0))
317
+ periodic = getattr(image, "periodic", False) if periodic is None else periodic
318
+ shifts = _shift_count(shifts, periodic)
319
+ planar = field.shape[2] == 1
320
+ pixel = np.broadcast_to(np.asarray(spacing, dtype=float), (3,))[:2]
321
+ voxel_volume = float(np.prod(pixel if planar else spacing))
322
+ volumes, n, mean, var, tilings = [], [], [], [], []
323
+ for w in window_sizes:
324
+ w = int(w)
325
+ across = 1 if planar else w
326
+ counts = [field.shape[0] // w, field.shape[1] // w, field.shape[2] // across]
327
+ if w < 1 or min(counts) < 1:
328
+ raise ValueError(f"window size {w} does not fit in the image {field.shape}")
329
+ nx, ny, nz = counts
330
+ means = []
331
+ for offset in _offsets(w, shifts, planar): # (0, 0, 0) first: the field itself
332
+ shifted = np.roll(field, tuple(-offset), axis=(0, 1, 2)) if offset.any() else field
333
+ block = shifted[: nx * w, : ny * w, : nz * across].reshape(nx, w, ny, w, nz, across)
334
+ means.append(block.mean(axis=(1, 3, 5), dtype=np.float64).ravel())
335
+ labels = np.repeat(np.arange(len(means)), means[0].size)
336
+ count, m, v = _moments(np.concatenate(means), labels)
337
+ volumes.append(w * w * across * voxel_volume)
338
+ n.append(count)
339
+ mean.append(m)
340
+ var.append(v)
341
+ tilings.append(len(means))
342
+ return SizeStatistics(
343
+ np.array(volumes),
344
+ np.array(n),
345
+ np.array(mean),
346
+ np.array(var),
347
+ dimension=2 if planar else 3,
348
+ tilings=np.array(tilings) if shifts > 1 else None,
349
+ )
350
+
351
+
352
+ def rve_table(
353
+ law: ScalingLaw, mean: float, eps_rel=(0.01, 0.05), n=(1, 10), *, dimension: int = 3
354
+ ) -> list[dict]:
355
+ """RVE volume and edge for each pair (eps_rel, n): the edge of a cube, ``V^(1/3)``, or
356
+ of a square of area ``V`` (``dimension = 2``), ``V^(1/2)``."""
357
+ rows = []
358
+ for e in np.atleast_1d(eps_rel):
359
+ for k in np.atleast_1d(n):
360
+ vol = float(law.rve_volume(e, mean, k))
361
+ edge = vol ** (1.0 / dimension)
362
+ rows.append({"eps_rel": float(e), "n": int(k), "volume": vol, "edge": edge})
363
+ return rows