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,2316 @@
1
+ Metadata-Version: 2.5
2
+ Name: morphogen
3
+ Version: 1.0.0
4
+ Summary: Morphological modelling and generation of virtual microstructures for RVE studies
5
+ Project-URL: Repository, https://github.com/jdirr/morphoGen
6
+ Author: Justin Dirrenberger
7
+ License-Expression: GPL-3.0-or-later
8
+ License-File: LICENSE
9
+ Keywords: Boolean model,FFT,TPMS,Voronoi,cellular automata,finite elements,homogenization,mathematical morphology,metamaterials,microstructure,random media,representative volume element,topology optimization
10
+ Classifier: Development Status :: 5 - Production/Stable
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: Operating System :: MacOS
13
+ Classifier: Operating System :: Microsoft :: Windows
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Scientific/Engineering :: Physics
20
+ Requires-Python: >=3.12
21
+ Requires-Dist: numba>=0.60
22
+ Requires-Dist: numpy>=1.26
23
+ Requires-Dist: pyyaml>=6.0
24
+ Requires-Dist: scipy>=1.12
25
+ Provides-Extra: all
26
+ Requires-Dist: matplotlib>=3.8; extra == 'all'
27
+ Requires-Dist: meshio>=5.3; extra == 'all'
28
+ Requires-Dist: pymmg>=1.0; (platform_machine != 'aarch64') and extra == 'all'
29
+ Requires-Dist: scikit-image>=0.22; extra == 'all'
30
+ Requires-Dist: tifffile>=2024.1; extra == 'all'
31
+ Provides-Extra: desktop
32
+ Requires-Dist: pywebview>=5.0; extra == 'desktop'
33
+ Requires-Dist: pywebview[qt]>=5.0; (sys_platform == 'linux') and extra == 'desktop'
34
+ Provides-Extra: dev
35
+ Requires-Dist: furo>=2024.8; extra == 'dev'
36
+ Requires-Dist: matplotlib>=3.8; extra == 'dev'
37
+ Requires-Dist: meshio>=5.3; extra == 'dev'
38
+ Requires-Dist: myst-parser>=4.0; extra == 'dev'
39
+ Requires-Dist: pymmg>=1.0; (platform_machine != 'aarch64') and extra == 'dev'
40
+ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
41
+ Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
42
+ Requires-Dist: pytest>=8.0; extra == 'dev'
43
+ Requires-Dist: ruff>=0.6; extra == 'dev'
44
+ Requires-Dist: scikit-fem>=10; extra == 'dev'
45
+ Requires-Dist: scikit-image>=0.22; extra == 'dev'
46
+ Requires-Dist: sphinx>=8.1; extra == 'dev'
47
+ Requires-Dist: tifffile>=2024.1; extra == 'dev'
48
+ Provides-Extra: docs
49
+ Requires-Dist: furo>=2024.8; extra == 'docs'
50
+ Requires-Dist: matplotlib>=3.8; extra == 'docs'
51
+ Requires-Dist: meshio>=5.3; extra == 'docs'
52
+ Requires-Dist: myst-parser>=4.0; extra == 'docs'
53
+ Requires-Dist: pymmg>=1.0; (platform_machine != 'aarch64') and extra == 'docs'
54
+ Requires-Dist: scikit-image>=0.22; extra == 'docs'
55
+ Requires-Dist: sphinx>=8.1; extra == 'docs'
56
+ Requires-Dist: tifffile>=2024.1; extra == 'docs'
57
+ Provides-Extra: gpu
58
+ Requires-Dist: cuda-toolkit[cudart,cufft,nvrtc]==13.*; extra == 'gpu'
59
+ Requires-Dist: cupy-cuda13x>=14; extra == 'gpu'
60
+ Provides-Extra: io
61
+ Requires-Dist: meshio>=5.3; extra == 'io'
62
+ Requires-Dist: tifffile>=2024.1; extra == 'io'
63
+ Provides-Extra: mesh
64
+ Requires-Dist: pymmg>=1.0; (platform_machine != 'aarch64') and extra == 'mesh'
65
+ Provides-Extra: plot
66
+ Requires-Dist: matplotlib>=3.8; extra == 'plot'
67
+ Provides-Extra: surface
68
+ Requires-Dist: scikit-image>=0.22; extra == 'surface'
69
+ Provides-Extra: test
70
+ Requires-Dist: pytest-xdist>=3.6; extra == 'test'
71
+ Requires-Dist: pytest>=8.0; extra == 'test'
72
+ Requires-Dist: scikit-fem>=10; extra == 'test'
73
+ Provides-Extra: video
74
+ Requires-Dist: imageio-ffmpeg>=0.4; extra == 'video'
75
+ Requires-Dist: vtk>=9.3; extra == 'video'
76
+ Description-Content-Type: text/markdown
77
+
78
+ # morphoGen
79
+ <!-- section: introduction -->
80
+
81
+ Morphological modelling and generation of virtual microstructures — stochastic or
82
+ deterministic — for the study of representative volume elements (RVE).
83
+
84
+ morphoGen does ten things:
85
+
86
+ * It generates random media from models of mathematical morphology and stochastic
87
+ geometry, and architected materials (TPMS, strut lattices, scale-rich networks),
88
+ periodic or not.
89
+ * It grows microstructures with cellular automata and lattice processes: annealing and
90
+ Turing patterns, reaction–diffusion, nucleation and growth of grains (Avrami
91
+ kinetics), grain coarsening, fractal aggregates.
92
+ * It designs architected materials: compatible assemblies of building blocks
93
+ (combinatorial metamaterials), strut lattices with defects and their rigidity, and
94
+ periodic cells optimized for their homogenized properties (topology optimization).
95
+ * It nests models — particles clustered in aggregates (Cox models of nanocomposites),
96
+ coatings and hollow members, hierarchical lattices of frames of tubes, fractal
97
+ sponges — and draws on biology: nacre, Bouligand plywoods, honeycombs and wood,
98
+ Haversian and trabecular bone, open-cell foams, vascular trees grown by space
99
+ colonization.
100
+ * It gives their morphological characteristics, both theoretical and measured.
101
+ * It exports them as vector, implicit or voxel geometry, as conforming tetrahedral
102
+ meshes or voxel meshes for finite elements, and as volumes for FFT solvers. The
103
+ conforming meshes of two phases need no voxels nor background grid (by default,
104
+ `mesh: {method: auto}`): tessellations from their exact cells, faceted morphologies
105
+ from their exact convex pieces, the others from their exact level set, refined where
106
+ the interface needs it, its nodes on the exact surface.
107
+ * It computes their apparent properties — elastic, thermal, electrical, dielectric,
108
+ magnetic and diffusive, with their weak and strong couplings (thermal expansion,
109
+ swelling, poroelasticity, piezoelectricity...), harmonic regimes, Bloch waves, the
110
+ flow through the pores and the sound that a porous layer absorbs: finite elements on
111
+ conforming meshes that follow the interfaces or the grains of polycrystals (kinematic,
112
+ mixed, periodic and static boundary conditions), an FFT solver on voxel images, on
113
+ the CPU or an NVIDIA GPU, or extended finite elements on a grid that the interfaces
114
+ cut; phases are isotropic or anisotropic crystals turned by the orientations of the
115
+ grains.
116
+ Loadings mix macroscopic strains and stresses (the periodic element of Z-set), with
117
+ thermal expansion; the results are post-processed into engineering constants and
118
+ normalized values, kept in a database of every configuration tested, and shown on
119
+ normalized Ashby charts ([docs/physics.md](docs/physics.md) is the guide to these
120
+ problems and their solvers).
121
+ * It follows nonlinear behaviours in time, up to fracture: phases that yield (von Mises
122
+ or Hill elasto-viscoplasticity with isotropic and kinematic hardening), polycrystals
123
+ that slip on the systems of their lattices (crystal plasticity of Méric and
124
+ Cailletaud), viscoelastic and hyperelastic phases (rubbers, soft tissues, foams),
125
+ ductile and quasi-brittle damage, along loading paths (tension at a strain rate,
126
+ creep, relaxation, cycles, thermal histories), in small or finite strains, with the
127
+ macroscopic strain components as degrees of freedom (the periodic element): by finite
128
+ elements on conforming meshes, by the FFT solver on voxel images, or by extended
129
+ finite elements. Cracks grow in meshes (stress intensity factors, cohesive zones) or
130
+ nucleate and merge in voxel images (the phase field, in small or finite strains).
131
+ Surfaces touch and rub (contact, self-contact and Coulomb's friction): the walls of the
132
+ pores of a cell that densifies, a sample between platens or under an indenter. The
133
+ interfaces of the phases of a cell debond along a path (cohesive zones on its torus).
134
+ The stresses of a cycle are judged by criteria of multiaxial fatigue (Crossland, Sines,
135
+ Dang Van, Findley, Matake): where a cell would start to crack, and its factor of safety.
136
+ Behaviours written in MFront can take the place of its own (through MGIS).
137
+ * It runs RVE-size studies with the statistical method of Kanit et al. (2003) and
138
+ Dirrenberger et al. (2014): generalized scaling law D²(V) = K V^-γ, RVE sizes with
139
+ confidence intervals, discrepancy between boundary conditions, isotropy. Realizations
140
+ run in parallel on a workstation and as job arrays on clusters.
141
+ * It architectures metal sheets by localized laser treatment (`morphogen.laser`): the
142
+ thermal cycles of laser tracks on one face or both, the martensite, tempering,
143
+ carburizing, nitriding or alloying they leave, the tensile test of the specimen by
144
+ finite elements with large rotations, and the optimization of the laser path for a
145
+ strength–ductility objective ([docs/laser.md](docs/laser.md)).
146
+
147
+ It comes with figures, animations and a graphical interface in the web browser. The
148
+ [tutorials](docs/tutorials.md) walk through whole studies — the first from the
149
+ installation to a behaviour learned from the responses of a microstructure —, the
150
+ [recipes](docs/howto.md) answer "how do I..." in a snippet each, and the
151
+ [gallery of examples](docs/gallery.md) shows every template with its image, its
152
+ configuration and the commands that reproduce it.
153
+
154
+ > **Status: 1.0, released on 18 November 2026**, the first public release, whose
155
+ > public interface is stable ([docs/stability.md](docs/stability.md)): the work of
156
+ > November 2026 (multiphysics, fracture and contact, explicit dynamics with OpenRadioss
157
+ > and the stand-alone application, crystallographic textures and orientation maps,
158
+ > scale-rich networks and exact meshes, laser-architectured sheets), phase 3b (the FFT
159
+ > solvers on NVIDIA GPUs; hard-core and curved fibres, rotated and graded lattices;
160
+ > AMITEX_FFTP workflows; MFront behaviours through MGIS; 3D views), phases 2a
161
+ > (homogenization and statistical analysis), 3a (cellular automata, combinatorial
162
+ > design, topology optimization, visualization), 2b (polycrystals in finite elements,
163
+ > anisotropic crystals, parallel and cluster runs, exports) and 2c (whole periodic
164
+ > grains, the periodic element with mixed macroscopic loadings, thermo-elasticity,
165
+ > nonlinear behaviours along loading paths, post-processing, database of results and
166
+ > Ashby charts, nested and bio-inspired models). The specification
167
+ > ([docs/specification.md](docs/specification.md)) was validated on 2026-10-21 (1.1);
168
+ > its later versions describe the later phases. morphoGen is free software under the GNU
169
+ > GPL v3 or later; its repository is public since 18 November 2026.
170
+
171
+ <!-- section: features -->
172
+ ## Features
173
+
174
+ | Models | Type |
175
+ |---|---|
176
+ | `boolean_spheres` | Boolean model of spheres, constant or random radii (porous and granular media) |
177
+ | `boolean_cylinders` | Boolean model of finite fibres (cylinders or spherocylinders) of any law of the axes, with its exact covariance along any direction (Peyrega et al. 2009) and integral range |
178
+ | `poisson_fibers` | infinite fibres on Poisson lines (Dirrenberger et al. 2014), isotropic or of any law of directions, with their exact covariance along any direction |
179
+ | `curved_fibers` | Curved fibres: worm-like chains whose tangents decorrelate along the contour (nonwovens, entangled networks), circular arcs of distributed radii of curvature (as in PuMA) or helices (crimp); a Boolean model or fibres without overlap; hollow (lumens) |
180
+ | `hardcore_spheres` | non-overlapping spheres by random sequential addition, or dense random packings grown by the Lubachevsky–Stillinger algorithm (up to about 0.64) |
181
+ | `penetrable_spheres` | penetrable spheres with impenetrable cores: Torquato's cherry-pit model, between the Boolean model and hard spheres |
182
+ | `hardcore_fibers` | non-overlapping fibres (spherocylinders) by random sequential addition, isotropic, aligned or planar, with a minimal gap |
183
+ | `random_walk_fibers` | bending fibres without overlap at high volume fractions (Altendorf & Jeulin 2011): random walks whose steps follow a von Mises–Fisher law between the main direction of their fibre (isotropic, aligned, planar, Schladitz's beta law, or mixtures of laws, as the orthotropic glass fibres of the 2014 paper) and the previous step, packed by repulsions against springs on the segments and the joints after an initial placement of least overlap (Altendorf, Jeulin & Willot 2014), then drawn into contact by the contact forces of Keilmann, Redenbach & Willot (2026) |
184
+ | `cross_linked_fibers` | entangled cross-linked fibres (Mezeix et al. 2009; Chatti et al. 2018, 2020): straight fibres, infinite on Poisson lines or finite, isotropic or in the Gaussian girdle of moulded fibres, bonded by cross-links (phase 2) at a fraction of their contacts, with the exact mean spacing of the contacts and cross-links |
185
+ | `delaunay_network` | fibre networks on the edges of the periodic Delaunay triangulation of Poisson or hard-core points (Ban et al. 2016), in space or in a plane, cross-linked at every node (15.5 fibres per node in space, 6 in a plane), with the stiffness of their frame of beams |
186
+ | `voronoi`, `laguerre` | Poisson–Voronoi and Laguerre tessellations (Poisson germs, germs of sphere packings, or stealthy hyperuniform germs: disordered but regular cells): polycrystals with random orientations, multiphase mosaics, grain-boundary phases |
187
+ | `ebsd` | measured polycrystals: windows of an orientation map (EBSD: `.ang` and `.ctf` files), its grains found from the disorientations of its points, each with its mean orientation |
188
+ | `gaussian_excursion` | excursions of Gaussian random fields (bicontinuous porous media) |
189
+ | `tpms` | gyroid, Schwarz P, Schwarz D and Neovius, sheet or network |
190
+ | `strut_lattice` | cubic, BCC, FCC, octet, Kelvin, diamond and pyrochlore lattices, with solid or hollow struts; rotated and functionally graded lattices (non-periodic samples) |
191
+ | `cellular_automaton` | two-phase structures grown by a cellular automaton from noise: annealing (bicontinuous), majority, conserved volume fraction, any `B/S` rule; on squares or cubes, triangles, hexagons, Penrose rhombi, Ammann–Beenker tiles, prisms, BCC or FCC cells, golden rhombohedra (quasi-periodic tilings in periodic boxes: their periodic approximants) |
192
+ | `activator_inhibitor` | Turing patterns of Young's activator–inhibitor automaton (spots, stripes, labyrinths) |
193
+ | `reaction_diffusion` | Gray–Scott reaction–diffusion patterns (spots, worms, labyrinths, holes), on the grid or the cells of any tiling |
194
+ | `nucleation_growth` | nucleation and growth of grains (JMAK kinetics): Voronoi or Johnson–Mehl polycrystals, partially crystallized structures, faceted grains, Potts coarsening |
195
+ | `aggregation` | diffusion-limited, Eden and ballistic aggregates: fractal clusters and deposits |
196
+ | `tile_assembly` | compatible assemblies of building blocks: polarized blocks (combinatorial metamaterials), pipe networks |
197
+ | `random_lattice` | strut lattices with missing struts and displaced nodes, with their rigidity (Maxwell–Calladine) |
198
+ | `random_laminate` | layers of random thicknesses with holes through the thin layers (nanolayered films, Bironeau et al. 2016) |
199
+ | `dead_leaves` | dead leaves of spheres or spheroids: mosaics of non-convex grains, families of leaves of their own sizes, finite coverage over a background, with their exact covariances (Jeulin 1997) |
200
+ | `transparent_dead_leaves` | excursions of the random function of transparent leaves (Jeulin 1997), with its exact covariance |
201
+ | `reconstruction` | stochastic reconstruction (Yeong & Torquato 1998): a lattice annealed to the two-point probability and lineal-path function of a Debye medium, a model or an image |
202
+ | `combination` | union, intersection, difference and complement of models; inclusions in a matrix, e.g. a polycrystal; nested models (each fills the phase 1 of the previous one) |
203
+ | `cox_spheres` | spheres clustered in the phase 1 of another model: Cox models of nanocomposites (particles in aggregates), hard-core or not |
204
+ | `coating` | a coating (interphase) around the phase 1 of any model, or a shell inside it: hollow spheres, fibres and struts, core–shell particles |
205
+ | `hierarchical_lattice` | hierarchical lattices of (hollow) tubes: frames of generation G of regular octahedra (Rayneau-Kirkhope, Mao & Farr 2012) |
206
+ | `fractal_sponge` | Menger sponge, Vicsek fractal, Cantor dust and any iterated function system on a cubic grid |
207
+ | `nacre` | brick-and-mortar stacks of mineral tablets, polygonal or staggered bricks |
208
+ | `bouligand` | twisted plywoods of fibres (arthropod cuticles, fish scales), periodic fibre families |
209
+ | `honeycomb` | prismatic cells: hexagonal, square or random honeycombs; softwood with radial files, growth rings and rays |
210
+ | `osteons` | Haversian bone: osteons with canals and cement lines, remodelled one after another (dead leaves) |
211
+ | `open_foam` | open-cell foams and trabecular bone: struts on the edges of relaxed, elongated Voronoi cells, at a given relative density, with their framework and the stiffness of its frame of beams |
212
+ | `level_set_foam` | open- or closed-cell foams as level sets of the distance fields of packed aligned ellipsoids: Plateau-border struts of controlled curvature thickening towards the nodes, at a given thickness or solid fraction (Degdeg & Dirrenberger); `calibrate_seeds` fits the seeds to measured section radii |
213
+ | `branching` | vascular trees, roots and corals grown by space colonization, radii by Murray's law |
214
+ | `scale_rich_network` | scale-rich networks (Both et al. 2026): ligaments of thicknesses `lambda_0 t^-alpha` grown one after another from points of the voids until they meet, extruded prisms; their thicknesses, lengths and degrees span orders of magnitude (power-law tails `1 + 1/alpha`, 3 and 3); the relative density in closed form (mean field) or solved on each realization, the jamming threshold; uniform, aligned or polarized ligaments, gradients of nucleation, a frame for periodic cells; in 3D (`dimension: 3`), plates that split convex voids into closed cells (areas and degrees of tails 5/2, the density and the jamming threshold in closed form) or beams grown until they touch (open cells, a mean-field density) |
215
+
216
+ Point processes, tessellations, Gaussian fields, dead leaves, growths and lattices take the
217
+ same field `anisotropy: {stretch: [1, 1, 2], euler: [0, 0, 0]}` (or `[1, 1, 2]`): the
218
+ realization of the isotropic model mapped by stretches along turned principal axes,
219
+ preserving volumes (aligned ellipsoids, elongated cells and grains, anisotropic
220
+ covariances); periodic boxes take principal axes along their axes, the Gaussian field any.
221
+
222
+ * **Representations.**
223
+ * Each realization is first an explicit description: centres and radii, fibre axes,
224
+ germs and weights, Fourier modes, surface equations. It is saved to JSON and
225
+ regenerated exactly.
226
+ * It is voxelized at any resolution, with optional partial-volume voxels; volumes
227
+ larger than memory are written slab by slab (`io.voxelize_to_file`).
228
+ * Every phase of every model has an implicit function (`phase_level_set`: negative
229
+ in the phase, zero on its boundary): signed distances for unions of grains, minima
230
+ and maxima for combinations, coatings and inclusions, distances to the spheres of
231
+ the leaves, to the faces of the cells of tessellations and tilings, to the cubes of
232
+ a sponge. The exports of the geometry — conforming meshes, surfaces, sections — are
233
+ cut from them, not from voxels ([docs/theory.md](docs/theory.md) §75).
234
+ * **Theory.** Each model knows its closed-form characteristics when they exist: volume
235
+ fraction, specific surface, covariance, integral range, variance exponent, cell
236
+ statistics. See [docs/theory.md](docs/theory.md).
237
+ * **Measurements.** Volume fraction, specific surface (Cauchy–Crofton, 13 directions),
238
+ covariance, connected components and percolation (labels, or a forest fire and its chemical
239
+ distance), percolation thresholds of families
240
+ of microstructures and their finite-size scaling to the infinite medium, in 2D and 3D, the
241
+ anisotropy of percolation (along any direction across a core of the box, the thresholds
242
+ of a family along directions, their ratio and threshold tensor), the rigidity threshold
243
+ where the elastic moduli of the voxels vanish, and the critical exponents
244
+ of the conductivity and of the elastic moduli at the threshold (t and f, by the
245
+ finite-size scaling of the FFT solutions, or of the voxels assembled and factorized near
246
+ the rigidity threshold, with their errors), cell volumes and neighbours,
247
+ fractal dimension (box counting), chord lengths, granulometry by openings, local
248
+ thickness and pore sizes, Euler characteristic and Minkowski densities, geometric
249
+ tortuosity; Torquato's descriptors: lineal-path, two-point cluster and pore-size
250
+ functions, radial distribution function and structure factor (hyperuniformity) of
251
+ point patterns; mathematical morphology: Choquet capacities of balls, segments, pairs
252
+ and cubes, dilations, erosions, openings, closings and contact distributions, the
253
+ morphological covariance of grey-level images, the four Minkowski functionals (with
254
+ the integral of mean curvature) and their curves for excursion sets, Betti numbers;
255
+ the mean intercept length and its fabric tensor (degree of anisotropy), the first
256
+ minima of the covariance (hole effect); stereology: section sizes and Saltykov's
257
+ unfolding of the size distribution of spheres or oriented ellipsoids; the particles of
258
+ a phase measured one by one in the volume (`analysis.particle_sizes`: touching
259
+ particles split by a watershed of their distance map, their sizes and number per unit
260
+ volume, with the frame correction of images that are not periodic).
261
+ * **Cellular automata and growth** (`morphogen.automata`).
262
+ * Von Neumann, Moore, edge and Euclidean neighbourhoods in 2D and 3D; Life-like
263
+ `B/S` rules, majority, Vichniac's annealing rule, majority at constant volume
264
+ fraction, probabilistic rules, activator–inhibitor rules; synchronous,
265
+ asynchronous and sequential updates.
266
+ * Gray–Scott reaction–diffusion, on the grid or on any tiling (finite-volume
267
+ Laplacians).
268
+ * Automata on other lattices than the square grid: triangles, hexagons, Penrose
269
+ rhombi (de Bruijn's pentagrid; quasi-periodic), Ammann–Beenker squares and rhombi
270
+ (octagonal, quasi-periodic), the prisms stacking them in 3D, truncated octahedra
271
+ (BCC), rhombic dodecahedra (FCC) and the golden rhombohedra of the icosahedral
272
+ quasi-periodic tiling, rasterized to images cell by cell (`lattice: hexagonal`);
273
+ the periodic approximants of the quasi-periodic tilings for periodic boxes (the same
274
+ tiles in a rectangle or a cube: `approximant: 4`; the cubic approximants 1/1, 2/1,
275
+ 3/2... of the icosahedral tiling).
276
+ * Nucleation and growth by an event-driven automaton with exact (or faceted,
277
+ oriented) growth fronts, checked against the Avrami law; normal grain growth by
278
+ the Monte Carlo Potts model; diffusion-limited, Eden and ballistic aggregation.
279
+ * Lattice structures are exact on their lattice and smooth elsewhere (a level set
280
+ for conforming meshes); non-periodic domains are cut from larger periodic
281
+ simulations, so that their structures do not wrap around. Their formation can be
282
+ watched step by step.
283
+ * **Combinatorial design** (`morphogen.design`).
284
+ * Tile sets with labelled faces; compatible assemblies by wave function collapse
285
+ with backtracking; exact counts and exact uniform sampling by transfer matrices;
286
+ polarized blocks after Coulais et al. (2016), with their exact counts.
287
+ * Periodic pin-jointed frameworks: random dilution and perturbation, rigidity
288
+ (mechanisms, states of self-stress, floppy macroscopic strains).
289
+ * Simulated annealing, genetic algorithm, and the inverse design of automaton rules
290
+ that reproduce the morphology of an image (`morphogen fit-rule`).
291
+ * **Topology optimization** (`morphogen.optimization`). Periodic cells of maximal bulk
292
+ or shear modulus or conductivity, of negative Poisson's ratio, or of a target
293
+ stiffness tensor, by inverse homogenization with the FFT solver and exact
294
+ sensitivities: SIMP, density filter, Heaviside projection, cubic or orthotropic
295
+ symmetry; optimality criteria, method of moving asymptotes, BESO and the hybrid
296
+ cellular automaton. Designs are microstructures like any other (meshing, finite
297
+ element validation, exports).
298
+ * **Isogeometric analysis and shape optimization** (`morphogen.iga`). NURBS patches
299
+ and their assemblies — exact circles and ellipses —, refined without changing the
300
+ geometry; linear elasticity (plane strain, plane stress, solids) and conduction with
301
+ the functions of the geometry; the effective tensors of periodic cells, boxes or
302
+ cells of any lattice (hexagonal arrays, patterns cut along no straight line); shape
303
+ optimization whose variables are control points, linked by the symmetries of the
304
+ pattern, with analytical sensitivities (the energy-momentum tensor) and SLSQP or the
305
+ moving asymptotes: the hole of largest bulk modulus of a cell reaches the bound of
306
+ Hashin and Shtrikman, and a sheet with alternating holes is brought to a Poisson's
307
+ ratio of -0.8 at a given stiffness ([tutorial](docs/tutorial_iga.md)).
308
+ * **Laser-architectured sheets** (`morphogen.laser`, [docs/laser.md](docs/laser.md)).
309
+ After Wang's thesis (PIMM 2022) and the project SCOLASTIC: moving Gaussian or top-hat
310
+ beams on a plate, on one face or on both at once (Rosenthal's limits, images through
311
+ the thickness, losses; transient finite volumes of a blank); austenite, martensite and
312
+ tempering of C–Mn steels (lever rule, Andrews, Koistinen–Marburger, Maynier,
313
+ Hollomon–Jaffe), the peak-temperature hardening of AISI 430, melt-pool carburizing,
314
+ nitriding and alloying; flow laws fitted to `R_p`, `R_m` and `A_g` by Considère; laser
315
+ paths (straight, corrugated, Fourier, crossed, honeycomb; G-code); a layered membrane
316
+ in plane stress with large rotations for the tensile test of dog-bone specimens; the
317
+ optimization of the path (grid, Nelder–Mead, differential evolution, genetic, Bayesian)
318
+ under constraints of strength and process (`morphogen laser`). Corrugated martensite
319
+ in an annealed 0.23 C steel trades yield strength for uniform elongation as measured;
320
+ a nonlocal fracture of the martensite gives the failure strains of the six samples of
321
+ Wang et al. (2023) within 0.006; the strength contrast of the reinforcement, from the
322
+ matrix to the martensite, decides whether a corrugation pays (the maps of 1450 designs
323
+ within the limits of the process); morphoGen's 2D morphologies treated at the scale of
324
+ the spot (1 mm²) on whole sheets, the sheets they make, the steering of a ductile crack
325
+ by soft corridors, the materials and the stiffness; the geometric work hardening of
326
+ corrugated tracks over a whole sheet (the strength contrast, not the stiffness, unbends
327
+ them) and where it works (along the axis of the tracks in uniaxial tension, the tracks
328
+ lying on lines that the deformation first shortens; every architecture lowers
329
+ the forming limit on the stretching side), and the architecture this rule selects: two
330
+ families of straight tracks crossed about the load, a scissor network that locks at
331
+ the necking of the matrix (an angle in closed form), raising the uniform elongation and
332
+ the forming limit near uniaxial tension. Cellular design (the loop of SCOLASTIC): phases on a
333
+ grid of cells, sensitivities by replays of the deformation history, BESO and
334
+ neighbour-exchange automata tested by finite elements, HCA and MMA, the tracks that
335
+ draw a design. Structures beyond the tensile test: a compact tension specimen (hard
336
+ bands that shield a crack, softened bands around it in hard sheets) and an L-shaped
337
+ plate, the growth of its crack (bridged by hard tracks); the plastic anisotropy of
338
+ treated sheets on the periodic cell of the sheet (Lankford, Hill 1948, Yld2000-2d),
339
+ the anisotropy set by an architecture, a rolling texture compensated by tracks along
340
+ the rolling direction; 22MnB5 and AA6082-T6 (softened by the laser). The periodic
341
+ cell of a treated sheet in its volume (`case_volume`: voxels of graded elastoplastic
342
+ phases with free faces) for the solvers of three-dimensional fields, within 1 to 3 %
343
+ of the membrane in tension.
344
+ * **NTFA.** Reduced models of nonlinear voxel microstructures (nonuniform transformation
345
+ field analysis, Michel & Suquet): modes from full-field snapshots, then loading paths
346
+ in milliseconds, within a few percent of the full fields; also from configurations
347
+ (`homogenization: ntfa`).
348
+ * **Bloch waves.** Band structures of the elastic waves of periodic cells (meshes or
349
+ voxel images) along the edges of the Brillouin zone, their band gaps and figures
350
+ (`homogenization.band_structure`); the scalar waves of sonic and photonic crystals
351
+ (`waves="acoustic"`, `"shear"`, `"tm"`, `"te"`: the pressure of fluids, antiplane
352
+ shear, the two polarizations of light in planar crystals), rigid scatterers, and the
353
+ speeds of the homogenized medium at long wavelengths (Wood's law); light in
354
+ three-dimensional photonic crystals (`waves="electromagnetic"`: the vector waves of
355
+ Maxwell's equations by plane waves on the voxels, dielectric, anisotropic or magnetic
356
+ phases, interfaces averaged within the cells; the band gap of the diamond lattice).
357
+ * **Post-bifurcated patterns.** The patterns that a periodic architectured material (a
358
+ frame of beams, a tetrahedral mesh or a voxel image) may adopt after buckling, from
359
+ the symmetry of its cell (group theory and the equivariant
360
+ branching lemma, after Azulay & Combescure), with the first bifurcation of a loading by
361
+ linear buckling, and the cell they need from a Bloch-wave stability analysis (cells of
362
+ several primitive cells split by their translations and the little groups of their wave
363
+ vectors, the patterns that double the period); periodic
364
+ frames of Euler-Bernoulli beams in the plane (honeycomb, triangular, square, kagome)
365
+ and in space (`SpaceFrame`: cubic, body-centred cubic, octet, Kelvin, diamond and
366
+ pyrochlore lattices of struts, their apparent stiffness and relative density),
367
+ patterns drawn and animated
368
+ in 3D (`homogenization.post_bifurcation`, `morphogen.symmetry`); along nonlinear
369
+ loading paths in finite strains with nonlinear behaviours (Hencky elasticity, von Mises
370
+ elasto-(visco)plasticity, crystals, MFront laws), the tangent of each step block by
371
+ block, the first bifurcation, its patterns and the bifurcated branch
372
+ (`homogenization.path_bifurcation`).
373
+ * **Fibre networks as frames of beams.** The effective stiffness of random periodic
374
+ frameworks (Delaunay fibre networks, Voronoi open foams, random lattices) as frames of
375
+ Euler-Bernoulli beams of circular sections with rigid joints, or of exact Timoshenko
376
+ beams (`shear_coefficient`: a coefficient per beam, or Cowper's), by a sparse periodic
377
+ problem: the Voigt stiffness, its split into stretching, bending, torsion and shear,
378
+ the affine estimate and the non-affinity of the deformation (slender Delaunay
379
+ networks at 0.82 of the affine estimate, open foams at E = 1.27 E_s phi^2); the
380
+ softening of networks of non-identical beams of Ban et al. (2016), exact to second
381
+ order in the coefficient of variation and against replicas; with the axial stiffness
382
+ lowered, Timoshenko beams whose shear stiffness follows the area of their general
383
+ sections reproduce their Voronoi case (s = 0.46) and come within a factor 1.4 of
384
+ their Delaunay case. Against the FFT solver on the voxels of the same realizations,
385
+ the frames are 2 to 30 % softer than the continuum, the struts merging in its joints;
386
+ Timoshenko beams rigid over a third of their radius at the joints (`rigid_joints`)
387
+ follow it within 4 % for open foams from 6 to 15 % (7 % at 2 %) and a Delaunay network
388
+ at 12 % (`homogenization.networks`; in the summaries of the network models with
389
+ `frame_stiffness: true`; for any realization of them, with every option, by
390
+ `morphogen frame-stiffness` and the tool Stiffness of the frame of beams of the
391
+ interface). Both run Ban's replicas of the stiffness of the beams (normal, lognormal or
392
+ bimodal, several coefficients of variation) against the exact `1 - s CV^2` and
393
+ `v CV^2`, with their table and figure; the axial force and the energy of each beam
394
+ under a uniaxial stress (`beam_forces`) draw the force chains and the beams that bend
395
+ (`viz.figures.frame_figure`, in the tool).
396
+ * **FEniCSx.** `solver: fenicsx` assembles and solves the finite element problems of
397
+ tetrahedral meshes with FEniCSx (dolfinx, dolfinx_mpc, PETSc; Linux or WSL), with the
398
+ same results as morphoGen's own solver.
399
+ * **Couplings.** Transient diffusion in microstructures (moisture, oxygen, solvents),
400
+ thermal oxidation of polymers (closed-loop scheme, diffusion-limited profiles of a
401
+ plate, and in the volume of a microstructure around its fibres or fillers),
402
+ properties that evolve with an ageing tracer mapped to graded phases, hydrolysis of
403
+ cellulose, hygromorph multilayers bending as moisture diffuses (orthotropic layers,
404
+ their properties homogenized from microstructures); diffusion from
405
+ configurations (`diffusion` section); with FEniCSx, the diffusion and free swelling of
406
+ meshed samples (hygromorph strips bending in time) and the stresses of oxidized ones.
407
+ * **Physics.** One homogenization module for the mechanical, thermal, electrical,
408
+ electromagnetic, chemical, diffusive, optical and acoustic problems of heterogeneous
409
+ materials, static and dynamic, with their couplings; [docs/physics.md](docs/physics.md)
410
+ is the guide to them for researchers (which problem, which solver, which name).
411
+ * Transport of a scalar potential: thermal and electrical conduction, dielectrics,
412
+ magnetostatics and diffusion share the solvers, the bounds and the RVE studies
413
+ (`conductivity`, `electrical_conductivity`, `permittivity`, `permeability`,
414
+ `diffusivity`, scalars and tensors; isotropic or crystalline phases, inert phases).
415
+ * Weak couplings: thermal expansion, hygroscopic and chemical swelling (`swelling`),
416
+ the poroelasticity of Biot (`poroelastic`: drained stiffness, tensor and modulus of
417
+ Biot of any solid, undrained response of Gassmann and Skempton); transient diffusion,
418
+ oxidation and ageing (`morphogen.coupling`).
419
+ * Strong couplings, their fields solved together on voxel images: piezoelectric,
420
+ piezomagnetic, magneto-electro-elastic (product properties), magnetoelectric and
421
+ thermoelectric composites, with the constants of their effective laws (`d33`, `k_t`,
422
+ `ZT`...).
423
+ * Harmonic regimes: storage and loss moduli of viscoelastic composites
424
+ (`dynamic_stiffness`), complex conductivity and permittivity of leaky dielectrics
425
+ (`complex_conductivity`: Maxwell–Wagner polarization), effective complex refractive
426
+ index (`refractive_index`).
427
+ * Behaviours in closed form for every solver: viscoelasticity (Prony series, WLF),
428
+ hyperelasticity (neo-Hookean, the polynomial of Rivlin with Mooney–Rivlin and Yeoh,
429
+ Arruda–Boyce and the eight chains, Gent, van der Waals, Fung, Ogden, the fibres of
430
+ Holzapfel–Gasser–Ogden, the foams of Blatz–Ko and Ogden–Hill; the softening of
431
+ Mullins, finite viscoelasticity; `fit_hyperelasticity` fits them to the uniaxial,
432
+ equibiaxial, planar and shear tests of a rubber) and isotropic damage
433
+ (crack band, viscous regularization, the unilateral effect of cracks that close),
434
+ Mazars' damage of concrete, and the damage coupled to plasticity (Lemaitre's ductile
435
+ damage, the creep damage of Kachanov and Rabotnov: `damage: {law: lemaitre, S: ...}`
436
+ beside `plasticity`), beside plasticity, crystal plasticity and porous plasticity.
437
+ * Fracture: the phase field of brittle fracture on voxel images
438
+ (`homogenize(..., fracture=...)`: AT1 and AT2, a toughness per phase; in finite
439
+ strains with `nonlinear: {kinematics: finite}`, for hyperelastic phases), beside the
440
+ cracks, cohesive zones and ductile damage of `morphogen.fracture`.
441
+ * Extended finite elements (`method: xfem`, `LevelSetSample`): a regular grid cut by
442
+ the interfaces of the morphology, without a mesher and without the stairs of the
443
+ voxels; elasticity, transport and loading paths.
444
+ * Flow and sound in porous media: the permeability of Darcy's law by a Stokes flow
445
+ through the pores (`hydraulic_permeability`, a lattice Boltzmann method on the
446
+ voxels), the parameters of the equivalent fluid of a rigid frame (`acoustic`:
447
+ tortuosity, viscous and thermal characteristic lengths, thermal permeability) and the
448
+ sound absorption of a layer (`homogenization.absorption`, the model of Johnson,
449
+ Champoux, Allard and Lafarge).
450
+ * **Explicit dynamics with OpenRadioss** (`morphogen.dynamics`). The crushing, tension,
451
+ shear and impact of a morphology at the rates of crashes, shocks and drops, simulated
452
+ by [OpenRadioss](https://github.com/OpenRadioss/OpenRadioss), the open-source explicit
453
+ finite element solver (AGPL-3.0; run as a separate program, installed from its
454
+ releases by `morphogen radioss install`): its voxels as stabilized 8-node bricks or a
455
+ conforming mesh of its level set as tetrahedra, its phases elastic, von Mises
456
+ elastoplastic (the linear, Voce and Norton hardenings of morphoGen tabulated in LAW36)
457
+ or Johnson–Cook (LAW2), with failure by element deletion, the self contact of its
458
+ folding struts and closing cells (TYPE24), its faces held and driven after a smooth
459
+ start, or the whole thrown against a rigid wall; its nominal stress–strain curves at
460
+ both faces (their gap telling a quasi-static test from a dynamic one), energies, peak
461
+ and plateau stresses, densification strain, absorbed energy per volume and mass, and
462
+ its fields over time (`morphogen radioss export|run|read`, the tab Explicit
463
+ dynamics). The inputs are the Radioss Block Format of the reference guide, written
464
+ with their manifest so that a run made elsewhere (a cluster) is read back.
465
+ * **Homogenization.**
466
+ * Conforming tetrahedral meshes of every model, made with MMG from the implicit
467
+ functions of its phases: the interfaces are followed within a Hausdorff distance,
468
+ and opposite faces match for periodic media. Porous media are meshed without their
469
+ pores; structures of several phases (coated inclusions, inclusions in a polycrystal,
470
+ osteons, leaves of several phases) are cut phase by phase, conforming to all their
471
+ interfaces.
472
+ * Polycrystals (Voronoi and Laguerre tessellations) are meshed grain by grain from
473
+ their exact cells, after removing features smaller than a chosen length: conforming
474
+ grain boundaries, one element set and orientation per grain, matching periodic
475
+ faces.
476
+ * Crystals: cubic, hexagonal or any stiffness and conductivity, turned by the
477
+ orientation of each grain, in both solvers; the bulk modulus of cubic polycrystals
478
+ comes out exact, and the shear modulus within the Hashin–Shtrikman bounds.
479
+ * Textures and orientation maps (`morphogen.texture`, `morphogen.io.ebsd`): the
480
+ symmetries of the eleven Laue classes, disorientations (against Mackenzie's
481
+ distribution for cubic crystals), mean orientations, pole figures in multiples of a
482
+ random texture, inverse pole figures and their colours; EBSD maps read and written
483
+ (`.ang`, `.ctf`, with the axes of each acquisition system), their grains, and the
484
+ polycrystal of a map for every solver (the model `ebsd`); the texture of a map given
485
+ to the cells of a tessellation of space (`texture: {type: measured, file: map.ctf}`);
486
+ `morphogen texture` for the numbers, the tables and the figures of a map. Along a
487
+ loading path in finite strains, the lattices that slip turns (`PathResult.texture`,
488
+ the `orientation` of a material point), checked against Schmid and Boas in single
489
+ slip and against the fibres of Taylor's polycrystal.
490
+ * Finite elements (4-node tetrahedra, or 10-node isoparametric ones whose curved edges
491
+ follow the interfaces, and the sharp edges where spheres, fibres or their coatings
492
+ overlap: the elements of the analyses of a configuration, by default):
493
+ KUBC, mixed (MBC), periodic (PBC) and
494
+ static (SUBC) conditions; bulk and shear moduli, conductivity, stiffness and
495
+ conductivity tensors; energy estimates, per-phase field statistics, isotropy
496
+ criteria, local fields for ParaView. Algebraic multigrid solvers (no compiled
497
+ dependency), about 10⁵–10⁶ unknowns on a laptop.
498
+ * FFT solver of voxel images (periodic), for tessellations and any image, linear or
499
+ nonlinear: loading paths are solved by Newton–Krylov iterations (conjugate gradients
500
+ preconditioned in Fourier space, the tangent applied without assembly) on voxels
501
+ that do not lock under plastic flow (B-bar, F-bar). With CuPy, the FFT solvers run on
502
+ an NVIDIA GPU (`device: gpu`, `--device gpu`), the loading paths with their
503
+ integration points: on a laptop, 5 to 7 times faster for linear problems, 1.6 to 2.8
504
+ times along crystal plasticity paths and 2.4 to 3.5 along porous ones.
505
+ * Periodic polycrystals meshed from their whole grains (periodized at the design):
506
+ node-to-node periodic links, no cell cut by the faces of the box.
507
+ * The periodic element: loadings that prescribe any mix of macroscopic strain and
508
+ stress components (uniaxial stress, plane strain...), solved exactly by
509
+ condensation of the macroscopic unknowns, for every boundary condition and both
510
+ solvers; thermal expansion of the phases, thermal stresses and the apparent thermal
511
+ expansion tensor (Levin's relation and bounds).
512
+ * Nonlinear behaviours along loading paths: von Mises elasto-viscoplasticity (Norton
513
+ flow, linear and Voce isotropic hardening, Prager and Armstrong–Frederick
514
+ kinematic hardening) or rate-independent plasticity, integrated implicitly with
515
+ the consistent tangent, or with Hill's anisotropic criterion (Z-set's coefficients
516
+ `h11` … `h31` by component; the closest point projection by Newton's method); paths that prescribe each component as a strain or a
517
+ stress in time, with a change of temperature; Newton iterations whose unknowns
518
+ include the macroscopic strain components (periodic and kinematic conditions on
519
+ meshes, periodic on voxels), with line search and step division; macroscopic curves,
520
+ phase averages and fields of plastic strain; a material point simulator.
521
+ * Crystal plasticity of Méric and Cailletaud for polycrystals: octahedral, cube and
522
+ body-centred cubic slip families, Norton flow, isotropic hardening coupled by an
523
+ interaction matrix (Franciosi's six interactions), kinematic hardening per system,
524
+ slip systems turned by the orientation of each grain; robust implicit integration
525
+ with its consistent tangent.
526
+ * Finite strains for every nonlinear behaviour: total Lagrangian finite elements,
527
+ Hencky elasticity and von Mises plasticity in the logarithmic strain space,
528
+ multiplicative crystal plasticity with lattice rotations; nominal and true (Cauchy)
529
+ stresses, logarithmic strains.
530
+ * Behaviours written in MFront (TFEL), integrated by MGIS (optional, from conda-forge):
531
+ standard behaviours in small or finite strains in place of morphoGen's own, by
532
+ finite elements, on voxels (CPU or GPU) and at a material point, crystals turned by
533
+ the orientation of each grain; `.mfront` sources compiled on first use and cached;
534
+ validated against MFront twins of morphoGen's behaviours.
535
+ * Behaviours learned from data (`morphogen.learning`, `morphogen learn`; NumPy and
536
+ Numba only): random strain paths at a material point or on a microstructure, a
537
+ perceptron, a learned convex potential (hyperelastic: a symmetric positive tangent),
538
+ a recurrent network over the increments (plasticity) or a learned generalized
539
+ standard material (a convex free energy and dissipation potential of learned
540
+ internal variables, the state of a step the minimizer of the incremental potential:
541
+ a nonnegative dissipation and a symmetric positive tangent by construction, trained
542
+ through the minimizations by implicit differentiation), every model in finite
543
+ strains of the logarithmic strain (by default, as the Hencky points: its stress
544
+ conjugate to `½ ln C`, objective) or of the Green-Lagrange strain, trained with their
545
+ gradients written out, then integrated in place of a behaviour (`learned` in a
546
+ material) at a material point, by finite elements and on voxels; a law learned in
547
+ the axes of a crystal (its paths turned by the rotations of the cube) turned grain
548
+ by grain in polycrystals, the stress-free thermal strain of its material taken out;
549
+ a tool of the interface that learns a behaviour in the background and keeps its law;
550
+ every learned law exported as an MFront behaviour (its trained parameters and a C++
551
+ port of its model, in small or finite strains, its state as state variables), for
552
+ Abaqus, Cast3M, Code_Aster and AMITEX_FFTP, checked against morphoGen's own
553
+ integration to round-off.
554
+ * Post-processing: the compliance S = C⁻¹ beside every stiffness C, in tables, JSON
555
+ and the text of the commands (morphoGen's Voigt order 11, 22, 33, 23, 31, 12 with
556
+ engineering shears, stated with each, TFEL and Abaqus ordering their shears 12, 13,
557
+ 23), engineering constants, anisotropy indices (universal index, Zener
558
+ ratio, distance to isotropy), macroscopic values of porous media
559
+ (Σ = φ⟨σ⟩_solid), relative, normalized and specific properties.
560
+ * Voigt, Reuss and Hashin–Shtrikman bounds, also for polycrystals of cubic crystals.
561
+ * **Results database and Ashby charts** (`morphogen.results`). Every run can be
562
+ recorded in a database (one SQLite file): its configuration and the results of each
563
+ realization, filtered by conditions on any key (`model.type == gyroid`,
564
+ `solid_fraction < 0.3`). Normalized Ashby charts (relative property against relative
565
+ density, scaling laws of cellular solids) from Python, `morphogen ashby` and the
566
+ graphical interface.
567
+ * **RVE.**
568
+ * ensemble method (realizations at several sizes) and window method (sub-volumes of
569
+ one large sample, or of any scalar field; the stiffness and conductivity tensors of
570
+ the windows of one periodic realization, their mean mutual energies by FFT; tilings
571
+ shifted around a periodic sample, their variances pooled within the tilings);
572
+ * per property and boundary condition: means and intervals, relative errors, fit of
573
+ K and γ (free or imposed), RVE sizes and the number of objects (fibres, grains)
574
+ they contain, bootstrap confidence intervals, discrepancy between conditions;
575
+ * for every physical quantity: the scalar properties and tensors of each physics, the
576
+ named results of the couplings and of the harmonic properties (`piezoelectric.e33`,
577
+ `dynamic_stiffness.shear_loss_1`, `poroelastic.biot_coefficient`), and the quantities
578
+ of nonlinear loading paths (a stress at a time, the strength, the work of fracture);
579
+ * reports in Markdown, LaTeX and JSON, with figures;
580
+ * fit of external tables, e.g. apparent moduli computed with another FE/FFT code.
581
+ * **Exports.**
582
+ * Volumes: VTK (`.vti`, legacy `.vtk` for FFT codes), XDMF, MetaImage, NumPy, TIFF.
583
+ * Conforming tetrahedral meshes and hexahedral voxel meshes, with phase, grain and
584
+ face sets: Abaqus/CalculiX `.inp` (with orientations, sections and the materials of
585
+ the phases: elastic, the nonlinear ones as MFront laws), Gmsh `.msh`,
586
+ `.vtu`, Medit `.mesh`, FEniCSx XDMF with tags, and more through meshio; periodic
587
+ node pairs and periodic constraint equations (`*EQUATION`).
588
+ * Polycrystals for other codes: DAMASK grids and material files, Neper seeds,
589
+ weights and orientations.
590
+ * Runs of AMITEX_FFTP (the FFT solver of the CEA, MPI-parallel): material and zone
591
+ fields, material file (isotropic phases, voids and crystals with the orientation of
592
+ each grain; the nonlinear materials as MFront laws), loading files (the six unit
593
+ strains of the stiffness, mixed loadings, loading paths, in small or finite
594
+ strains), algorithm file and the MPI script; their results read back (averages of the cell, materials and zones,
595
+ apparent stiffness and moduli) for RVE studies (`morphogen amitex export|read`,
596
+ `outputs.amitex`).
597
+ * MFront sources of the nonlinear materials (von Mises or Hill plasticity, porous
598
+ plasticity, crystal plasticity and the learned laws, in small and finite strains,
599
+ with their thermal expansion from 293.15 K,
600
+ where the Abaqus inputs then start their nodes), for AMITEX_FFTP, Cast3M, Abaqus or
601
+ Code_Aster (`morphogen mfront`), checked against morphoGen's own kernels; the user's
602
+ own MFront laws go to AMITEX and Abaqus inputs too, in small or finite strains
603
+ (every phase an MFront law then, Hencky's elasticity for the elastic ones).
604
+ * Watertight STL surfaces for additive manufacturing.
605
+ * Gmsh OpenCASCADE scripts.
606
+ * Raw data and figures: tables as `.csv`, `.txt` and `.xlsx` (no dependency),
607
+ figures as `.png`, `.tif`, `.svg`, `.pdf` and TikZ (pgfplots code for LaTeX);
608
+ `morphogen.export(obj, path)` picks the writer from the object and the suffix.
609
+ * **Visualization.** Sections, periodic tilings, 3D surfaces, histories, Avrami
610
+ kinetics and animated GIFs of the formation of structures (`morphogen view`).
611
+ Videos (`.mp4` through ffmpeg, `.gif`), played once, in a loop or back and forth:
612
+ sections sweeping through a volume and the three orthogonal sections (as in
613
+ Avizo), turntables of phases and meshes, cross-sections sweeping through a mesh,
614
+ fields and modes animated with a magnified displacement, matplotlib colormaps
615
+ (3D views rendered off screen by VTK).
616
+ * **Interfaces.** Python API, command line, YAML/JSON/TOML configurations and a
617
+ graphical interface, in the web browser (`morphogen gui`) or as a stand-alone
618
+ application in a window of its own (`morphogen desktop`, `morphogen-desktop`; a
619
+ bundle that needs no Python from `packaging/desktop`), with the dialogs of the system
620
+ for its folders and files.
621
+ * **Parallel and cluster runs.** Realizations run in parallel processes (`-j`), in
622
+ job arrays written and submitted for SLURM, PBS Pro, Torque, SGE, OAR and LSF
623
+ (`morphogen submit`), or under MPI; each one leaves a record, so that runs can be
624
+ resumed, checked (`morphogen status`) and merged, with results independent of the
625
+ splitting.
626
+
627
+ <!-- section: installation -->
628
+ ## Installation
629
+
630
+ morphoGen needs Python 3.12 or newer on Windows, macOS (Apple Silicon) or Linux. All
631
+ dependencies are installed from binary wheels; no compiler is needed.
632
+
633
+ **With uv** (recommended, it can also install Python itself):
634
+
635
+ ```bash
636
+ git clone https://github.com/jdirr/morphoGen.git
637
+ cd morphoGen
638
+ uv venv --python 3.13
639
+ uv pip install -e ".[all]" # [all] = scikit-image, tifffile, meshio, matplotlib, pymmg
640
+ ```
641
+
642
+ Activate the environment with `.venv\Scripts\activate` (Windows) or
643
+ `source .venv/bin/activate` (macOS, Linux).
644
+
645
+ **With pip and venv:**
646
+
647
+ ```bash
648
+ python -m venv .venv
649
+ .venv\Scripts\activate # Windows
650
+ source .venv/bin/activate # macOS, Linux
651
+ python -m pip install -e ".[all]"
652
+ ```
653
+
654
+ **With conda** (Miniforge or Anaconda):
655
+
656
+ ```bash
657
+ conda create -n morphogen python=3.13
658
+ conda activate morphogen
659
+ python -m pip install -e ".[all]"
660
+ ```
661
+
662
+ The core needs only NumPy, SciPy, Numba and PyYAML; the graphical interface needs
663
+ nothing else. The optional extras are `surface` (STL surfaces), `io` (TIFF and other
664
+ mesh formats), `plot` (figures and animations, with matplotlib) and `mesh` (the MMG
665
+ mesher, from the `pymmg` wheels: conforming meshes for the finite element solver). Where pymmg has no wheel (e.g. Linux on ARM), build `mmg3d` from
666
+ <https://github.com/MmgTools/mmg> and set `MORPHOGEN_MMG3D` to its path;
667
+ `morphogen info` shows the mesher found.
668
+
669
+ **GPU (optional).** On a machine with an NVIDIA GPU, `python -m pip install -e ".[gpu]"`
670
+ adds CuPy and the CUDA libraries it loads (the runtime, NVRTC and cuFFT, about 270 MB;
671
+ neither the CUDA toolkit nor a compiler is needed, only a driver of CUDA 13). With a
672
+ driver of CUDA 12, install
673
+ `python -m pip install cupy-cuda12x "cuda-toolkit[cudart,nvrtc,cufft]==12.*"` instead.
674
+ The FFT solvers then run on the GPU with `device: gpu` (or `auto`: the GPU when there is
675
+ one); `morphogen info` shows the GPU found, or why none is usable. These libraries are
676
+ proprietary (NVIDIA's licence, free of charge), and morphoGen never requires them.
677
+
678
+ **Stand-alone application (optional).** `python -m pip install -e ".[desktop]"` adds
679
+ pywebview, which shows the interface in a window of the web engine of the system
680
+ (WebView2 on Windows, WebKit on macOS; on Linux, Qt WebEngine from its wheels, with the
681
+ system's EGL and X libraries, e.g. `apt install libegl1 libxkbcommon-x11-0
682
+ libxcb-cursor0`); `morphogen desktop` (or the program `morphogen-desktop`) opens it.
683
+ A folder that runs without Python (`morphoGen.exe` on Windows, `morphoGen.app` on macOS)
684
+ is built with PyInstaller by the recipe of `packaging/desktop`.
685
+
686
+ **OpenRadioss (optional).** The explicit dynamic simulations run OpenRadioss, a
687
+ separate program: `morphogen radioss install` downloads its latest release from GitHub
688
+ (Linux x86-64 and ARM, Windows) into `~/morphogen/openradioss`, where morphoGen finds it
689
+ (or set `OPENRADIOSS_PATH` to the folder of an installation, e.g. one built from its
690
+ sources on macOS); `morphogen radioss info` shows the installation found. Without it,
691
+ morphoGen writes the inputs and the scripts that run them elsewhere.
692
+
693
+ **MFront behaviours (optional).** MGIS and MFront are not on PyPI: install them from
694
+ conda-forge in morphoGen's environment, with a C++ compiler for the behaviours:
695
+
696
+ ```bash
697
+ conda install -c conda-forge mgis mfront cxx-compiler
698
+ ```
699
+
700
+ On Windows, MFront needs the C++ compiler of Visual Studio (its Build Tools); WSL with
701
+ Ubuntu and Miniforge is simpler, and is where morphoGen's MFront tests run.
702
+ `morphogen info` shows MGIS and the version of MFront found.
703
+
704
+ Check the installation:
705
+
706
+ ```bash
707
+ morphogen info
708
+ python -m pip install -e ".[dev]" && python -m pytest
709
+ ```
710
+
711
+ The first call of each kernel compiles it (a few seconds); compiled code is cached.
712
+
713
+ <!-- section: quick start -->
714
+ ## Quick start
715
+
716
+ The [tutorial](docs/tutorial.md) follows a whole study step by step; the
717
+ [gallery](docs/gallery.md) starts from any of the templates.
718
+
719
+ ### Python
720
+
721
+ ```python
722
+ import morphogen as mg
723
+
724
+ model = mg.models.BooleanSpheres(radius=1.0, volume_fraction=0.3)
725
+ micro = model.generate(mg.Domain.cube(20.0, periodic=True), seed=42) # explicit geometry
726
+ image = micro.voxelize(shape=128) # phase image
727
+
728
+ print(mg.analysis.volume_fraction(image), model.theory()["volume_fraction"])
729
+ print(mg.analysis.specific_surface(image), model.theory()["specific_surface"])
730
+
731
+ mg.io.save_image(image, "spheres.vti") # ParaView, FFT codes
732
+ mg.io.save_mesh(mg.mesh.voxel_mesh(image, phases=[1]), "spheres.inp")
733
+ mg.io.save_microstructure(micro, "spheres.json") # regenerates it exactly
734
+ ```
735
+
736
+ ### Apparent properties
737
+
738
+ ```python
739
+ from morphogen.homogenization import VOID, Material, homogenize
740
+
741
+ mesh = mg.mesh.conforming_mesh(micro, size=0.5) # tetrahedra following the spheres
742
+ materials = {0: Material(young=1.0, poisson=0.3, conductivity=1.0),
743
+ 1: Material(young=20.0, poisson=0.3, conductivity=10.0)}
744
+ results = homogenize(mesh, materials, bcs=["kubc", "mixed", "periodic"],
745
+ properties=["bulk_modulus", "shear_modulus", "conductivity"])
746
+ print(results["bulk_modulus.kubc"].value)
747
+
748
+ # porous media: mesh only the solid (phases="solid"), and give the pores a VOID
749
+ # voxel images (e.g. tessellations) are solved by FFT, under periodic conditions:
750
+ results = homogenize(image, materials, properties=["stiffness"])
751
+ stiffness = results["stiffness.periodic"]
752
+ print(stiffness["tensor"]) # C: Voigt 11 22 33 23 31 12, engineering shears
753
+ print(stiffness["compliance"]) # S = C^-1 in the same notation: S44 = 1/G23, S66 = 1/G12
754
+ print(stiffness["E1"], stiffness["nu12"], stiffness["G23"]) # its engineering constants
755
+ ```
756
+
757
+ Every output of a stiffness gives its compliance beside it, in the same notation:
758
+ `results.csv` has the columns `stiffness.<bc>.C11` ... `C66` and `stiffness.<bc>.S11`
759
+ ... `S66` (upper triangles) and `run.json` states their notation; `morphogen homogenize`,
760
+ `frame-stiffness`, `amitex read` and `optimize` print both (their JSON has `compliance`
761
+ and `notation` beside the stiffness), and the tools of the interface show both as tables
762
+ with their .csv. TFEL (MFront) and Abaqus order their shears 12, 13, 23: morphoGen's
763
+ `C44` (plane 23) is their `C66`.
764
+
765
+ A cell symmetric about its mid-planes can be meshed in its irreducible part and
766
+ mirrored: the mesh then has its symmetries exactly (and matching opposite faces), as the
767
+ analyses by group theory need; any level-set function makes a microstructure:
768
+
769
+ ```python
770
+ from morphogen.mesh import ImplicitBody, mirrored_mesh
771
+
772
+ def holes(points): # negative in the solid: a square array of holes
773
+ d = points[:, :2] % 1.0 - 0.5
774
+ return 0.4348 - np.hypot(d[:, 0], d[:, 1])
775
+
776
+ body = ImplicitBody(mg.Domain(size=(1.0, 1.0, 0.13), periodic=True), holes)
777
+ mesh = mirrored_mesh(body, size=0.065, cells=(2, 2, 1), order=2, phases="solid")
778
+ # with the diagonal mirrors of the square (4/mmm), or of the cube: ((0, 1), (1, 2))
779
+ square = mirrored_mesh(body, size=0.065, diagonals=((0, 1),), cells=(2, 2, 1), phases="solid")
780
+ ```
781
+
782
+ ### Polycrystals
783
+
784
+ ```python
785
+ from morphogen.homogenization import Material, homogenize
786
+
787
+ # a copper polycrystal: 50 grains with random orientations, meshed grain by grain
788
+ grains = mg.models.Voronoi(n_cells=50, crystal_orientations=True).generate(
789
+ mg.Domain.cube(1.0, periodic=True), seed=1)
790
+ mesh = mg.mesh.conforming_mesh(grains, size=0.08, min_feature=0.02)
791
+ copper = Material.cubic(168.4, 121.4, 75.4)
792
+ results = homogenize(mesh, {1: copper}, bcs=["kubc", "periodic", "subc"],
793
+ properties=["bulk_modulus", "shear_modulus"])
794
+ print(results["bulk_modulus.subc"].value) # (C11 + 2 C12) / 3 = 137.07, exactly
795
+
796
+ mg.io.save_mesh(mesh, "grains.inp") # element sets and orientations per grain
797
+ mg.io.write_periodic_equations("grains_equations.inp", mesh)
798
+ mg.io.save_mesh(mesh, "grains.xdmf") # FEniCSx, with phase, grain and face tags
799
+ mg.io.write_damask("grains", grains.labels(shape=64), grains.orientations,
800
+ materials={1: copper}) # DAMASK grid and material.yaml
801
+
802
+ # combinations: alumina inclusions and an amorphous boundary phase in the polycrystal
803
+ model = mg.models.Combination(operation="inclusions", models=(
804
+ mg.models.Voronoi(n_cells=50, crystal_orientations=True, boundary_thickness=0.01),
805
+ mg.models.HardcoreSpheres(radius=0.05, volume_fraction=0.05)))
806
+ print(model.active_phases()) # {1: 'cells', 0: 'grain boundaries', 2: 'inclusions ...'}
807
+ ```
808
+
809
+ Features smaller than `min_feature` (short cell edges, thin caps of cells on the faces
810
+ of the box) are removed before meshing; `min_feature=0` meshes the exact cells. Without
811
+ MMG, or for voxel workflows, the same polycrystals are homogenized by FFT on their
812
+ images with the grain labels (`homogenize(image, materials, grains=labels,
813
+ orientations=grains.orientations)`).
814
+
815
+ More examples are in [`examples/`](https://github.com/jdirr/morphoGen/tree/main/examples): `minimal.py`, `rve_study.py` (Voronoi
816
+ mosaic, integral range recovered), `homogenization.py` (finite elements and FFT),
817
+ `multiphysics.py` (one microstructure homogenized for its elastic, thermal, dielectric
818
+ and diffusive properties, its expansions, its poroelastic and piezoelectric laws, its
819
+ dynamic moduli, and cut by extended finite elements), `acoustic_foam.py` (from an
820
+ open-cell foam to the parameters of its equivalent fluid and the sound absorption of
821
+ layers of it),
822
+ `polycrystal.py` (meshes of grains, crystals, exports, a parallel batch),
823
+ `ebsd_map.py` (an orientation map from end to end: its grains, its texture, the
824
+ stiffness of its polycrystal, windows of it as the realizations of a study),
825
+ `automata_and_design.py` (automata, growth, aggregation, tile assemblies, rigidity,
826
+ inverse design of rules), `topology_optimization.py` (bulk modulus and auxetic cells),
827
+ `architectures_ashby.py` (lattices, foams, trabecular bone, honeycombs and fractal
828
+ sponges homogenized, recorded in a database and placed on a normalized Ashby chart),
829
+ `fracture.py` (cohesive zones of a double cantilever beam against the corrected beam
830
+ theory, an edge crack by XFEM against the handbook), `microfoam.py` (the hole size effect
831
+ of nickel foams with the microfoam model, a crack as a band of micromorphic damage on two
832
+ meshes, the densification of the foam compressed to half its height in finite strains, a
833
+ ductile crack by micromorphic ductile damage on two meshes), `hill_of_a_laminate.py`
834
+ (Hill's law of a laminate identified on its responses, written for Z-set),
835
+ `gurson_of_pores.py` (Gurson's q1 and q2 of spherical pores in a von Mises matrix, from a
836
+ tension and a confined one), `benchmark.py`, `gpu_benchmark.py` and
837
+ `behaviour_benchmark.py` (the cost of each behaviour of the integration points).
838
+
839
+ ### Cellular automata and growth
840
+
841
+ ```python
842
+ import numpy as np
843
+ from morphogen import automata
844
+ from morphogen.models import CellularAutomatonModel, NucleationGrowthModel
845
+
846
+ # an automaton on its own: Vichniac's annealing rule coarsens noise into a
847
+ # bicontinuous structure
848
+ rng = np.random.default_rng(1)
849
+ run = automata.CellularAutomaton("anneal", neighbourhood="moore").run(
850
+ automata.random_state((64, 64, 64), 0.5, rng), steps=30, rng=rng)
851
+ print(run.history["interface"][-1]) # interface density
852
+
853
+ # as a model: any domain, periodic or not, smooth interfaces off the lattice
854
+ micro = CellularAutomatonModel(rule="anneal", steps=30, cell_size=0.5).generate(
855
+ mg.Domain.cube(20.0), seed=1)
856
+
857
+ # a partially crystallized structure, and its kinetics against the Avrami law
858
+ model = NucleationGrowthModel(nucleation="continuous", nucleation_rate=1e-3, time=6.0)
859
+ grains = model.generate(mg.Domain.cube(40.0), seed=2)
860
+ print(grains.voxelize().data.mean(), model.theory()["transformed_fraction"])
861
+ frames = model.evolution(mg.Domain.cube(40.0), seed=2, frames=20) # formation
862
+ ```
863
+
864
+ ### Combinatorial design
865
+
866
+ ```python
867
+ from morphogen import design
868
+ from morphogen.models import RandomLattice, TileAssembly
869
+
870
+ design.count_polarized_blocks((4, 4, 4)) # 145 456 074 compatible assemblies
871
+ blocks = design.polarized_blocks()
872
+ assembly = design.wave_function_collapse(blocks, (8, 8, 8), rng)
873
+ metamaterial = TileAssembly(tiles="polarized").generate(mg.Domain.cube(8.0), seed=3)
874
+
875
+ # an octet lattice diluted to a mean coordination of 5: below Maxwell's 6, it is floppy
876
+ lattice = RandomLattice(cell="octet", coordination=5.0).generate(mg.Domain.cube(4.0), seed=4)
877
+ print(lattice.summary()["floppy_strains"])
878
+ ```
879
+
880
+ ### Topology optimization
881
+
882
+ ```python
883
+ from morphogen.optimization import CellOptimization
884
+
885
+ # planar cell (one voxel through the thickness) with a negative Poisson's ratio
886
+ opt = CellOptimization((64, 64, 1), 0.35, objective="poisson_ratio", method="mma",
887
+ filter_radius=3.0, projection=8.0, iterations=300)
888
+ cell = opt.run()
889
+ print(cell.properties()) # moduli of the black-and-white design
890
+ print(cell.refined_properties(2), cell.hinges) # checks: finer grid, hinges
891
+ micro = cell.to_microstructure() # smooth level set: mesh it, homogenize it
892
+ ```
893
+
894
+ The same from a configuration file: `morphogen template optimize_auxetic -o
895
+ auxetic.yaml`, then `morphogen optimize auxetic.yaml`; in three dimensions, the template
896
+ `optimize_auxetic_3d` (a cell auxetic along its three axes, on 24³ voxels).
897
+
898
+ ### Laser-architectured sheets
899
+
900
+ ```python
901
+ from morphogen.laser import Beam, SheetCase, Specimen, optimize
902
+
903
+ # corrugated martensite in an annealed 0.23 C steel, a fibre laser above and a diode below
904
+ case = SheetCase(
905
+ material="annealed_ms1500",
906
+ specimen=Specimen(kind="dogbone", length=30.0, width=5.0, thickness=1.0),
907
+ beam=Beam(150.0, speed=10.0, radius=0.5, absorptivity=0.55),
908
+ bottom=Beam(100.0, speed=10.0, radius=0.6, absorptivity=0.55, profile="tophat"),
909
+ pattern={"kind": "corrugated", "count": 1, "amplitude": 1.0, "period": 15.0},
910
+ )
911
+ print(case.evaluate().measures) # Rp, Rm, Ag, energy, treated fraction, path...
912
+ best = optimize(case, {"pattern.amplitude": [0.0, 2.5], "pattern.period": [6.0, 30.0]},
913
+ constraints={"yield_strength": [400.0, None]}, evaluations=30)
914
+ print(best.values, best.result.path.to_gcode()[:200])
915
+ ```
916
+
917
+ The same from a configuration file: `morphogen template laser_corrugated -o
918
+ laser.yaml`, then `morphogen laser laser.yaml` (curves, maps, history, G-code).
919
+
920
+ ### Nested and bio-inspired models
921
+
922
+ ```python
923
+ # carbon black in rubber: particles in aggregates (a Cox model), with a bound-rubber phase
924
+ nano = mg.models.CoxSpheres(
925
+ aggregates={"type": "boolean_spheres", "radius": 0.1, "volume_fraction": 0.25},
926
+ radius=0.012, local_fraction=0.35, hardcore=True, aggregate_phase=2)
927
+ # hollow spheres, and a hierarchical lattice of hollow tubes (Rayneau-Kirkhope et al.)
928
+ shells = mg.models.Coating(model={"type": "hardcore_spheres", "radius": 0.1,
929
+ "volume_fraction": 0.2}, thickness=0.02, side="inside")
930
+ frames = mg.models.HierarchicalLattice(generations=1, cells=3, tube_radius=0.012,
931
+ wall_thickness=0.004)
932
+ menger = mg.models.FractalSponge(pattern="menger", level=3)
933
+ # from biology
934
+ nacre = mg.models.Nacre(arrangement="brick", tablet_size=1.0, tablet_thickness=0.2,
935
+ mortar_thickness=0.05)
936
+ plywood = mg.models.Bouligand(fiber_radius=0.03, fiber_spacing=0.08, pitch_angle=15.0)
937
+ wood = mg.models.Honeycomb(arrangement="wood", cell_size=0.4, wall_thickness=0.04,
938
+ ring_width=4.0, ray_fraction=0.08) # rays: 3D
939
+ bone = mg.models.OpenFoam(n_cells=64, volume_fraction=0.15, relaxation=10, anisotropy=1.6)
940
+ cortical = mg.models.Osteons(radius=100.0, coverage=0.65, cement_thickness=4.0)
941
+ tree = mg.models.BranchingNetwork(n_attractors=3000, step=0.02, murray_exponent=3.0)
942
+ print(cortical.theory()) # exact fractions of the four phases (dead leaves)
943
+ ```
944
+
945
+ ### Scale-rich networks
946
+
947
+ ```python
948
+ from morphogen.homogenization.postprocess import directional_modulus
949
+
950
+ # Both et al. (2026): 500 ligaments of thicknesses lambda_0 t^-0.6 at 40 % relative density
951
+ model = mg.models.ScaleRichNetwork(n_ligaments=500, decay=0.6, volume_fraction=0.4)
952
+ plane = mg.Domain(size=(1.0, 1.0, 1 / 512), periodic=False) # one voxel thick
953
+ net = model.generate(plane, seed=1)
954
+ print(model.theory(plane)) # lambda_0 of the density, the jamming threshold...
955
+ print(net.metadata["summary"]) # ligaments, density, degrees, geometric anisotropy
956
+ print({k: v.exponent for k, v in net.statistics().items()}) # power-law tails
957
+ # aligned, polarized (tangential for the first 20 %), graded nucleation; a frame for a
958
+ # periodic cell (FFT, Bloch waves)
959
+ aligned = mg.models.ScaleRichNetwork(volume_fraction=0.4, angles=[0, 90])
960
+ swirl = mg.models.ScaleRichNetwork(volume_fraction=0.4, pole=[0.5, 0.5], pole_angle=90,
961
+ polarized_fraction=0.2)
962
+ cell = mg.models.ScaleRichNetwork(volume_fraction=0.4, frame=0.006).generate(plane, seed=1)
963
+ # the elastic anisotropy E_min / E_max of a stiffness tensor C, in plane strain
964
+ # eta = directional_modulus(C, np.linspace(0, np.pi, 361)).min() / ....max()
965
+ ```
966
+
967
+ In 3D, the plates or the beams of Fig. 6a of the paper fill the box:
968
+
969
+ ```python
970
+ cube = mg.Domain(size=(1.0, 1.0, 1.0), periodic=False)
971
+ plates = mg.models.ScaleRichNetwork(dimension=3, n_ligaments=2000, decay=0.5,
972
+ volume_fraction=0.3) # closed cells
973
+ cells = plates.generate(cube, seed=1)
974
+ print(plates.theory(cube)) # first plate area, lambda_0, jamming, tails 5/2...
975
+ print(cells.volume_fraction, cells.areas[:5], cells.degrees().mean())
976
+ beams = mg.models.ScaleRichNetwork(dimension=3, element="beams", n_ligaments=500,
977
+ decay=0.3, volume_fraction=0.15) # open cells, struts
978
+ struts = beams.generate(cube, seed=1)
979
+ segments = struts.segments() # the beams as capsules (meshing, STL)
980
+ # layers, vertical walls, shells about a pole, a gradient along z
981
+ layers = mg.models.ScaleRichNetwork(dimension=3, volume_fraction=0.3,
982
+ orientation={"type": "aligned", "direction": [0, 0, 1]})
983
+ shells = mg.models.ScaleRichNetwork(dimension=3, volume_fraction=0.3, pole=[0.5, 0.5, 0.5],
984
+ pole_angle=90, nucleation_gradient=[1, 4], gradient_axis=2)
985
+ image = cells.voxelize(shape=128)
986
+ # the elastic anisotropy E_min / E_max of a 3D stiffness C (homogenization.postprocess):
987
+ # e = spatial_modulus(C, sphere_directions()); eta = e.min() / e.max()
988
+ ```
989
+
990
+ `examples/scale_rich_networks.py` reproduces the laws of the paper and the anisotropy of
991
+ its networks, `examples/scale_rich_networks_3d.py` those of plates and beams.
992
+
993
+ ### Macroscopic loadings and thermal expansion
994
+
995
+ ```python
996
+ from morphogen.homogenization import Loading, homogenize
997
+
998
+ materials = {0: Material(young=2800.0, poisson=0.39, expansion=95e-6), # epoxy
999
+ 1: Material(young=89000.0, poisson=0.3, expansion=5.5e-6)} # glass
1000
+ results = homogenize(image, materials, properties=["stiffness", "thermal_expansion"],
1001
+ loadings={"tension": {"stress": {"33": 100.0}}, # the rest free
1002
+ "plane": Loading.parse("E11=0.001 E33=0"),
1003
+ "heating": {"temperature": 100.0}})
1004
+ print(results["thermal_expansion.periodic"]["tensor"])
1005
+ print(results["tension.periodic"].components()) # E11 ... E12, S11 ... S12, energy
1006
+ ```
1007
+
1008
+ ### Multiphysics: transport, couplings, harmonic regimes
1009
+
1010
+ Every transport phenomenon of a scalar potential has its coefficient and its properties;
1011
+ couplings and harmonic regimes are properties too ([docs/physics.md](docs/physics.md)
1012
+ goes through all of them, with fracture and the choice of a solver):
1013
+
1014
+ ```python
1015
+ import dataclasses
1016
+
1017
+ phases = {0: Material(conductivity=0.2, electrical_conductivity=1e-12, permittivity=3.0),
1018
+ 1: Material(conductivity=30.0, electrical_conductivity=1e4, permittivity=10.0)}
1019
+ results = homogenize(image, phases, properties=["conductivity", "electrical_conductivity",
1020
+ "permittivity_tensor"])
1021
+
1022
+ # a piezoelectric composite: the fields solved together, the constants of the law
1023
+ ceramic = dataclasses.replace(Material.hexagonal(166e9, 77e9, 78e9, 162e9, 43e9),
1024
+ permittivity=(11.2e-9, 11.2e-9, 12.6e-9),
1025
+ coupling={"piezoelectric": {"e31": -4.4, "e33": 18.6, "e15": 11.6}})
1026
+ polymer = Material(young=4e9, poisson=0.35, permittivity=3.7e-11)
1027
+ law = homogenize(image, {0: polymer, 1: ceramic}, properties=["piezoelectric"])
1028
+ print(law["piezoelectric.periodic"]["d33"], law["piezoelectric.periodic"]["k_t"])
1029
+
1030
+ # storage and loss moduli of a viscoelastic matrix at three angular frequencies
1031
+ resin = Material(young=3e9, poisson=0.35,
1032
+ viscoelasticity={"shear": [[0.5, 1e-2], [0.3, 1.0]], "bulk": [[0.2, 0.1]]})
1033
+ dma = homogenize(image, {0: resin, 1: Material(young=70e9, poisson=0.22)},
1034
+ properties=["dynamic_stiffness"], frequencies=[0.1, 10.0, 1000.0])
1035
+ print(dma["dynamic_stiffness.periodic"]["shear_tan_delta_2"])
1036
+
1037
+ # a porous rock: Biot's tensor and modulus, Skempton's coefficient with water in the pores
1038
+ rock = homogenize(image, {0: Material(young=20e9, poisson=0.2), 1: VOID},
1039
+ properties=["poroelastic"], fluid_bulk_modulus=2.2e9)
1040
+ print(rock["poroelastic.periodic"]["biot_coefficient"])
1041
+ ```
1042
+
1043
+ ### Nonlinear behaviours along loading paths
1044
+
1045
+ ```python
1046
+ from morphogen.homogenization import LoadingPath, Material, homogenize, simulate_point
1047
+
1048
+ matrix = Material(young=70e3, poisson=0.33, plasticity={ # aluminium alloy (MPa, s)
1049
+ "yield": 100, "isotropic": [{"Q": 80, "b": 20}], "kinematic": [{"C": 1e4, "D": 100}],
1050
+ "norton": {"K": 50, "n": 5}})
1051
+ particles = Material(young=400e3, poisson=0.2) # SiC
1052
+ # tension at 1e-3 /s to 2 %, relaxation for 100 s, unloading; lateral stresses free
1053
+ path = LoadingPath.parse("t=0,20,120,130 n=10,10,5 E11=0,0.02,0.02,0.017")
1054
+ out = homogenize(mesh, {0: matrix, 1: particles}, properties=[], paths={"tension": path})
1055
+ curve = out["tension.periodic"] # times, strain, stress, plastic, phases, fields
1056
+ print(curve.stress[:, 0], curve.phases[0]["plastic"])
1057
+ print(simulate_point(matrix, path).stress[-1]) # the matrix alone
1058
+ ```
1059
+
1060
+ Crystal plasticity (Méric–Cailletaud) in the grains of a polycrystal mesh, in finite
1061
+ strains:
1062
+
1063
+ ```python
1064
+ from morphogen.homogenization import CrystalPlasticity, Material, NonlinearFEProblem
1065
+
1066
+ nickel = Material.from_config({
1067
+ "cubic": [250e3, 160e3, 120e3], # MPa
1068
+ "crystal_plasticity": {
1069
+ "families": ["octahedral"], # also cube, bcc110, bcc112
1070
+ "tau0": 80, "Q": 20, "b": 10, # r = tau0 + Q sum h (1 - e^-bv)
1071
+ "C": 2e4, "D": 300, # x = C alpha
1072
+ "K": 25, "n": 10, # <(|tau - x| - r) / K>^n
1073
+ "interaction": [1, 1, 0.6, 12.3, 1.6, 1.3]}}) # Franciosi
1074
+ problem = NonlinearFEProblem(poly_mesh, {1: nickel}, "periodic", kinematics="finite")
1075
+ curve = problem.run({"times": [0, 100], "increments": 40, "strain": {"11": 0.1}},
1076
+ fields=True)
1077
+ print(curve.stress[:, 0], curve.cauchy[:, 0], curve.log_strain[:, 0]) # S, TS, LE
1078
+ print(curve.fields[100.0]["orientation"][:5]) # current lattice orientations (Bunge)
1079
+ ```
1080
+
1081
+ Crystals also twin and cleave ([docs/theory.md](docs/theory.md) §86–87). Hexagonal
1082
+ crystals have their slip families (`basal`, `prismatic`, `pyramidal_a`, `pyramidal_ca`,
1083
+ `pyramidal2_ca`, with the ratio `c_over_a`); twins shear in one sense until the crystal
1084
+ has twinned; cleavage planes open at a normal stress and soften, with the fracture
1085
+ energy of a crack band:
1086
+
1087
+ ```python
1088
+ magnesium = Material.from_config({
1089
+ "hexagonal": [59400, 25600, 21400, 61600, 16400], # c11, c12, c13, c33, c44
1090
+ "crystal_plasticity": {
1091
+ "c_over_a": 1.624, "K": 5, "n": 10,
1092
+ "families": {"basal": {"tau0": 10}, "prismatic": {"tau0": 60},
1093
+ "pyramidal2_ca": {"tau0": 100}},
1094
+ "twins": {"twin1012": {"tau0": 25}}}}) # {10-12}: lengthens c
1095
+ iron = Material.from_config({
1096
+ "cubic": [230e3, 135e3, 117e3],
1097
+ "crystal_plasticity": {
1098
+ "K": 10, "n": 10, "families": {"bcc110": {"tau0": 300}},
1099
+ "cleavage": {"planes": "cube", "strength": 500, # {100}: opens at 500 MPa
1100
+ "energy": 0.05, "length": 0.008, # G_c, in elements of 8 µm
1101
+ "K": 50, "n": 1}}})
1102
+ curve = simulate_point(magnesium, {"times": [0, 1], "increments": 20, "strain": {"33": 0.03}})
1103
+ curve.series["twin_fraction"] # of a crystal pulled along c; cleavage_damage for iron
1104
+ ```
1105
+
1106
+ A textured magnesium flows at half the stress in the sense that twins it (the template
1107
+ `homogenization_twinning`); a polycrystal of iron breaks through its grains from
1108
+ cleavage plane to cleavage plane (`homogenization_cleavage`), or between them when its
1109
+ boundaries are cohesive and weaker (`interfaces: {faces: grains}`, the template
1110
+ `homogenization_grain_fracture`). The fields map the `twin_fraction`, the
1111
+ `cleavage_opening` and the `cleavage_damage`. Under a stress that is reversed the twins
1112
+ shear back and the cleavage planes close ([docs/theory.md](docs/theory.md) §89): a
1113
+ closed crack carries the pressure as the sound crystal, its lips rubbing with
1114
+ `friction` (the template `homogenization_crack_closure`); and with `twin_reorientation`
1115
+ the lattice of a point becomes that of its predominant twin at a threshold of its
1116
+ twinned fraction, slips and twins as the twin does, and twins back (the field
1117
+ `twin_misorientation`; the template `homogenization_detwinning`) — point by point, or
1118
+ grain by grain (`{threshold, growth}`: the turned volume of a grain, `twin_reoriented`,
1119
+ then follows its twinned volume). `twin_detwinning` and `closure` also take the share of
1120
+ their resistance at which the twins shear back and the planes close. And the slip can
1121
+ nucleate the cleavage ([docs/theory.md](docs/theory.md) §90): with `cleavage: {coupling:
1122
+ Θ}` the strength of the planes falls as `exp(−Θ γ)` of the cumulated slip of the
1123
+ crystal, and their damage eases its slip.
1124
+
1125
+ How likely is cleavage to start? The local approach of Beremin
1126
+ ([docs/theory.md](docs/theory.md) §88) reads it from the fields of a path: the Weibull
1127
+ stress of the points that have yielded, and the probability that the weakest link has
1128
+ failed.
1129
+
1130
+ ```python
1131
+ from morphogen.homogenization import Beremin, path_beremin
1132
+
1133
+ law = Beremin(modulus=22, scale=2600.0, volume=1.25e-4, # m, sigma_u (MPa), V0 (mm³)
1134
+ planes="cube", plastic=1e-4) # the {100} planes of the grains
1135
+ found = path_beremin(curve, law, orientations=euler_of_each_voxel) # fields="steps"
1136
+ found.weibull, found.probability # at each step; found.driving: the stress of each point
1137
+ ```
1138
+
1139
+ In a configuration, `homogenization: {beremin: {modulus: 22, scale: 1550, volume:
1140
+ 1.25e-10, planes: cube, plastic: 1e-4}}` adds the curves `beremin_weibull` and
1141
+ `beremin_probability` to those of the path (the template `homogenization_beremin`); in
1142
+ the graphical interface, the box *Cleavage* of the tool *Loading path of a morphology*.
1143
+
1144
+ In finite strains the macroscopic gradient is upper triangular: `E11 ... E12` are its
1145
+ components (nominal strains, and simple shears for `E23, E31, E12`), `S11 ... S12` the
1146
+ same components of the nominal (first Piola–Kirchhoff) stress; free components leave
1147
+ the faces free of tractions, so that a tension is a uniaxial Cauchy stress.
1148
+
1149
+ The same paths are followed on voxel images by the FFT solver, with the grains and
1150
+ orientations of a tessellation:
1151
+
1152
+ ```python
1153
+ from morphogen.homogenization import NonlinearFFTProblem
1154
+
1155
+ image = poly.voxelize(shape=32) # a Voronoi realization, 32³ voxels
1156
+ problem = NonlinearFFTProblem(image, {1: nickel}, grains=poly.labels(grid=image.grid()),
1157
+ orientations=poly.orientations, kinematics="finite")
1158
+ curve = problem.run({"times": [0, 50], "increments": 25, "strain": {"11": 0.05}})
1159
+ ```
1160
+
1161
+ Each voxel is a trilinear element with 8 Gauss points; the volumetric part of the strain
1162
+ is averaged over the voxel (`integration="bbar"`: B-bar, and F-bar in finite strains),
1163
+ without which the voxels lock under plastic flow (the flow stress of elastic cubes in a
1164
+ plastic matrix is twice too high on 10³ voxels with `integration="full"`). The memory
1165
+ is that of the integration points: about 8 kB per voxel for a crystal with 12 slip
1166
+ systems in small strains (2 GB for 64³ voxels).
1167
+
1168
+ Behaviours written in MFront take the place of morphoGen's, with MGIS and MFront
1169
+ installed (the source is compiled on first use and cached):
1170
+
1171
+ ```python
1172
+ from morphogen.homogenization.mfront import MFrontBehaviour
1173
+
1174
+ alloy = Material(young=70e3, poisson=0.33, # the linear problems, the FFT reference
1175
+ mfront=MFrontBehaviour(source="tests/mfront/VonMisesTwin.mfront"))
1176
+ print(simulate_point(alloy, path).stress[-1]) # its own elasticity and viscoplasticity
1177
+ out = homogenize(mesh, {0: alloy, 1: particles}, properties=[], paths={"tension": path})
1178
+ ```
1179
+
1180
+ In configurations and materials files, `mfront` is the path of the source (relative to
1181
+ the file) or a mapping: `source`, or `library` and `behaviour`; `material_properties`,
1182
+ `parameters` and `external_state_variables` (constants); `temperature` (the reference, in
1183
+ K, to which the paths add their change of temperature); `plastic_strain` (the internal
1184
+ variable of the cumulated plastic strain of the outputs).
1185
+
1186
+ ### Identification of a macroscopic law
1187
+
1188
+ The parameters of a behaviour are identified on reference responses, as Zopt does for
1189
+ Zsim: the curves of `homogenize` (`PathResult`: `curve.path`, `curve.times`,
1190
+ `curve.stress`) of a morphology under several paths give it a macroscopic law, material
1191
+ points or the points of a test calibrate a law; each reference counts by its weight
1192
+ whatever its number of points. Gurson's q1 and q2 under two triaxialities, written back
1193
+ for Z-set:
1194
+
1195
+ ```python
1196
+ from morphogen.homogenization import Material, simulate_point
1197
+ from morphogen.homogenization.identification import Reference, identify_references
1198
+ from morphogen.homogenization.zmat import write_zmat
1199
+
1200
+ tension = {"times": [0, 1], "increments": 12, "strain": {"11": [0, 0.05]}} # triaxiality 1/3
1201
+ confined = {**tension, "strain": {"11": [0, 0.05], "22": [0, 0], "33": [0, 0]}} # held laterally
1202
+ voids = {"criterion": "gurson", "yield": 100, "hardening": 1000, "porosity": 0.07}
1203
+ law = Material.from_config({"young": 70e3, "poisson": 0.33,
1204
+ "porous_plasticity": {**voids, "q1": 1.5, "q2": 1.0}})
1205
+ refs = [Reference(r.path, r.times, r.stress, components) for r, components in (
1206
+ (simulate_point(law, tension), [0]), (simulate_point(law, confined), [0, 1, 2]))]
1207
+ start = {"young": 70e3, "poisson": 0.33, "porous_plasticity": {**voids, "q1": 1.0, "q2": 1.3}}
1208
+ fit = identify_references(start, refs, ["q1", "q2"])
1209
+ print(fit.values, fit.gaps) # q1 1.5, q2 1.0; the gap to each response
1210
+ write_zmat(fit.material, "gurson.mat", digits=6) # porous_plastic, for Z-set
1211
+ ```
1212
+
1213
+ In the interface, "Identification of a behaviour" (tab Mechanics) takes the runs of the
1214
+ workspace, each under its own path, and "Z-set file of a behaviour" (Solvers & formats)
1215
+ writes the behaviour found.
1216
+
1217
+ An anisotropic morphology calls for an anisotropic law: Hill's criterion
1218
+ (`hill: {11: …, 22: …, 33: …, 12: …, 23: …, 31: …}`, Z-set's form, 1 where not given),
1219
+ whose coefficients `hill11` … `hill31` the identification fits from von Mises's. Two
1220
+ plastic phases in layers normal to z (`examples/hill_of_a_laminate.py`, a few seconds)
1221
+ yield alike in tension along x and z, but their shear across the layers (31, the layers in
1222
+ series) saturates at 0.63 where the shear in their plane (12, in parallel) reaches 0.89:
1223
+ von Mises misses the first by 38 %, Hill's law found (`h31 ≈ 2`, `h12 ≈ h33 ≈ 1`) follows
1224
+ all four responses within 4 %, and `write_zmat` writes it as a `gen_evp` with
1225
+ `*criterion hill` for Z-set. `macroscopic_law(respond)` does it in one go: it runs the
1226
+ tensions and shears chosen through `respond(path)` (the response of the morphology),
1227
+ estimates a starting law on them (elasticity of the first increment, yield stress,
1228
+ hardening; with `cycle=True` the loadings reverse and the law takes a kinematic
1229
+ hardening, the Bauschinger effect of the morphology) and identifies the von Mises or Hill
1230
+ law on them together; in the interface,
1231
+ "Macroscopic law of a morphology" (tab Mechanics) does the same on its voxels and writes
1232
+ the law for Z-set. `law="gurson"` gives a porous morphology Gurson's law: the matrix
1233
+ of its phase, its voids as the porosity, q1 and q2 identified on loadings of several
1234
+ triaxialities (`loadings=["11", "confined11"]`: a tension, then one whose lateral
1235
+ strains are held), as on unit cells.
1236
+
1237
+ ### Database of results and Ashby charts
1238
+
1239
+ ```bash
1240
+ morphogen run gyroid.yaml --db study.db # or outputs.database in the file
1241
+ morphogen db list --db study.db
1242
+ morphogen db export --db study.db --where "model.type == tpms" -o gyroids.csv
1243
+ morphogen ashby --db study.db -o ashby.svg # relative modulus vs relative density
1244
+ ```
1245
+
1246
+ ### Command line
1247
+
1248
+ ```bash
1249
+ morphogen models # list the models
1250
+ morphogen models poisson_fibers # parameters of a model
1251
+ morphogen template # list the example configurations
1252
+ morphogen template tpms -o gyroid.yaml # start from an example
1253
+ morphogen run gyroid.yaml # generate, measure, export
1254
+ morphogen analyze out/tpms/gyroid_0000.vti --measure volume_fraction specific_surface
1255
+ morphogen texture map.ctf -o texture/ # grains, pole figures, disorientations of an EBSD map
1256
+ morphogen texture out/polycrystal_0000_tension_periodic_4.vti -o texture/ # lattices of a path
1257
+ morphogen percolation spheres.yaml --lower 0.15 --upper 0.45 # percolation threshold
1258
+ morphogen percolation fibres.yaml --lower 0.02 --upper 0.6 --directions lattice # anisotropy
1259
+ morphogen percolation spheres.yaml --lower 0.1 --upper 0.4 --sizes 24,32,48,64 \
1260
+ --exponent thermal --realizations 49 # the exponent t of the conductivity at p_c
1261
+ morphogen percolation discs.yaml --lower 0.4 --upper 0.8 --sizes 32,48,64 \
1262
+ --exponent elastic --contrast 0 # f at the threshold of the moduli (--rigidity)
1263
+ morphogen frame-stiffness foam.yaml --beams timoshenko --rigid-joints 0.33 \
1264
+ --softening modulus # a network as a frame of beams: stiffness, energy split
1265
+ morphogen frame-stiffness foam.yaml --softening bending --replicas 40 --cv 0.1 0.2 0.3 \
1266
+ --table replicas.csv --figure replicas.png # Ban's replicas against s CV^2 and v CV^2
1267
+ morphogen view out/tpms/gyroid_0000.vti --surface # 3D figure (matplotlib)
1268
+ morphogen homogenize cell.json --voxels 64 --material 0=void 1=young:1,poisson:0.3 \
1269
+ --property stiffness --loading "tension: S11=1" "E11=0.01 S22=0"
1270
+ morphogen homogenize foam.vti --material 0=void 1=young:1,poisson:0.3 \
1271
+ --property hydraulic_permeability acoustic # Darcy's permeability, acoustic parameters
1272
+ morphogen bands rods.vti --material 0=permittivity:1 1=permittivity:8.9 --waves tm \
1273
+ --path G X M G --figure bands.png # band structure and gaps of a photonic crystal
1274
+ morphogen bands diamond.vti --material 0=permittivity:1 1=permittivity:11.56 \
1275
+ --waves electromagnetic --coarsen 4 # light in a three-dimensional crystal
1276
+ morphogen gui # graphical interface in the browser
1277
+ morphogen template workflow -o chain.yaml # the whole chain: model, mesh, fields, videos
1278
+ morphogen laser laser.yaml # a laser-architectured sheet and its laser path
1279
+ morphogen export fields.vtu stress.mp4 --field von_mises --displacement displacement \
1280
+ --wave sine --mode loop # files of a run to other formats and videos
1281
+ ```
1282
+
1283
+ A configuration file describes the model, the domain, the voxels, the outputs and the
1284
+ measurements:
1285
+
1286
+ ```yaml
1287
+ model:
1288
+ type: poisson_fibers
1289
+ radius: 1.0
1290
+ volume_fraction: 0.16
1291
+ domain:
1292
+ size: 30.0
1293
+ periodic: false # infinite fibres cannot be periodic
1294
+ seed: 2014
1295
+ voxels:
1296
+ voxel_size: 0.25
1297
+ outputs:
1298
+ directory: out/poisson_fibers
1299
+ geometry: [json, geo] # geo: Gmsh script
1300
+ image: [vtk] # legacy VTK for FFT solvers
1301
+ mesh: {formats: [msh], phases: [1]}
1302
+ analysis: [volume_fraction, specific_surface, connectivity]
1303
+ ```
1304
+
1305
+ ### The whole chain in a configuration
1306
+
1307
+ A `visualization` section draws figures and videos of the first realizations: their
1308
+ voxel image, conforming mesh and the fields of the homogenization, on the deformed mesh
1309
+ (finite elements) or the voxels (FFT); `outputs.tables` adds `.txt` and `.xlsx` copies
1310
+ of the tables. The template `workflow` follows the whole chain:
1311
+
1312
+ ```yaml
1313
+ outputs:
1314
+ tables: [txt, xlsx]
1315
+ visualization:
1316
+ cmap: viridis
1317
+ figures:
1318
+ - {of: image, formats: [png, svg, tex]} # three sections, TikZ for LaTeX
1319
+ - {of: mesh} # 3D view coloured by phase
1320
+ - {of: shear_modulus.periodic, color: von_mises, section: {axis: 2, fraction: 0.5}}
1321
+ - {of: tension.periodic, formats: [pdf]} # curves of a loading path
1322
+ videos:
1323
+ - {of: image, kind: orthoslices, mode: bounce} # as in Avizo
1324
+ - {of: mesh, kind: sweep, axis: 0} # a cross-section sweeping
1325
+ - {of: shear_modulus.periodic, wave: sine, mode: loop, part: fluctuation}
1326
+ - {of: tension.periodic, color: p, frames: 60} # the steps of the path
1327
+ ```
1328
+
1329
+ Views: `image` (sections, orthoslices, the surface of a phase), `labels`, `mesh`
1330
+ (view, turntable, sweep) and the results `<property>.<bc>`, `<loading>.<bc>`,
1331
+ `<path>.<bc>` coloured by a field (`von_mises`, `stress_12`, `p`, `displacement`,
1332
+ `flux`...; of a path, also `interface_damage` and `interface_opening` where interfaces
1333
+ debond, `fatigue_utilization` and `fatigue_amplitude` where a cycle is judged),
1334
+ magnified (`magnification`, automatic by default), cut by a plane, with
1335
+ the colormap and range of your choice; formats `png`, `tif`, `jpg`, `svg`, `pdf`,
1336
+ `tex` (TikZ) for figures and `mp4`, `gif`, `frames` for videos, played `once`, in a
1337
+ `loop` or back and forth (`bounce`). The 3D views need VTK and the mp4 videos ffmpeg
1338
+ (`pip install 'morphogen[video]'`); a run checks them before it starts.
1339
+
1340
+ ### Cohesive zones: interfaces and fracture
1341
+
1342
+ `morphogen.fracture` opens the interfaces of a tetrahedral mesh (between phases, or
1343
+ along chosen faces) and gives them cohesive zone elements, in small or finite strains:
1344
+
1345
+ ```python
1346
+ from morphogen.fracture import Bilinear, CohesiveProblem, insert_interfaces
1347
+
1348
+ opened, interfaces = insert_interfaces(mesh, "phases") # debonding of the particles
1349
+ law = Bilinear(stiffness=1e5, normal_strength=30.0, shear_strength=40.0,
1350
+ mode_I=0.3, mode_II=0.6, eta=2.0) # Benzeggagh-Kenane mixity
1351
+ problem = CohesiveProblem(opened, interfaces, materials, law, kinematics="finite")
1352
+ result = problem.run([(bottom, [0, 1, 2], 0.0), (top, 2, 1.0)], load=0.05,
1353
+ steps=50, viscosity=1e-4, fields=True)
1354
+ problem.write("debonding", result) # the bulk and the interfaces (damage), VTU
1355
+ ```
1356
+
1357
+ Laws: bilinear mixed-mode and the exponential law of Ortiz & Pandolfi; helpers: the
1358
+ length of the cohesive zone, the strength of coarse meshes (Turon et al.), the double
1359
+ cantilever beam (`dcb_specimen`) and its corrected beam theory (`dcb_beam_theory`).
1360
+
1361
+ Cracks (`morphogen.fracture.lefm`): planar cracks by level sets, their energy release
1362
+ rate on conforming meshes remeshed at each step (MMG, as Z-cracks) or by XFEM (jump and
1363
+ branch enrichments of linear tetrahedra), and their growth by Paris' law or Griffith:
1364
+
1365
+ ```python
1366
+ from morphogen.fracture import Crack, propagate, xfem_work
1367
+
1368
+ crack = Crack("penny", centre, normal=(0, 0, 1), size=2.0)
1369
+ growth = propagate(xfem_work(mesh, material, forces, supports), crack, young=E,
1370
+ poisson=nu, increment=0.5, steps=10, paris=(C, m))
1371
+ ```
1372
+
1373
+ Mixed modes, in small or finite strains (`morphogen.fracture.mixed`): the energy release
1374
+ rate along the front by the G-θ method (exact for the neo-Hookean body of finite strains),
1375
+ the factors of modes I, II and III by interaction integrals, the frictionless contact of
1376
+ the lips, and kinked cracks remeshed by MMG at each step, growing in the direction of
1377
+ Erdogan & Sih:
1378
+
1379
+ ```python
1380
+ from morphogen.fracture import KinkedCrack, crack_mesh, propagate_kinked, solve_crack
1381
+
1382
+ solution = solve_crack(mesh, crack, material, supports, forces=loads,
1383
+ kinematics="finite", contact=True)
1384
+ modes = solution.modes(stations=5) # K_I, K_II, K_III, G, G_I, G_II, G_III along the front
1385
+ crack = KinkedCrack(((0.0, 16.0, 0.0), (4.5, 16.0, 0.0))) # mouth to front, front along z
1386
+ growth = propagate_kinked(lambda c: crack_mesh(lower, upper, c, size=0.5), crack,
1387
+ material, supports, forces=loads, increment=1.5, steps=10,
1388
+ paris=(C, m))
1389
+ ```
1390
+
1391
+ Cracks of any surface and front (`morphogen.fracture.surface`): the surface swept by the
1392
+ successive positions of a front, closed (a crack inside the body) or open (through, edge
1393
+ and surface cracks), each point of which advances by its own amount and kinks by its own
1394
+ angle; the mesh is refined around the front alone:
1395
+
1396
+ ```python
1397
+ from morphogen.fracture import SurfaceCrack, crack_mesh, propagate_front
1398
+
1399
+ crack = SurfaceCrack.ellipse(centre, normal=(0.5, 0, 0.87), a=1.0, b=0.6) # inclined
1400
+ mesh_of = lambda c: crack_mesh(lower, upper, c, size=0.6, front_size=0.08)
1401
+ growth = propagate_front(mesh_of, crack, material, supports, forces=loads,
1402
+ increment=0.3, steps=5, stations=12, paris=(C, m))
1403
+ growth.rows() # per step: area, K_I, K_II, K_III along the front, kink angles, cycles
1404
+ growth.cracks[-1].points # rows x stations x 3: the surface, its last row the front
1405
+ ```
1406
+
1407
+ Inelastic solids (`morphogen.fracture.bulk`): the crack solvers take the behaviours of
1408
+ morphoGen's points as their bulk (von Mises elasto-viscoplasticity, with Hencky's
1409
+ logarithmic strains in finite strains; crystal plasticity with the orientations of the
1410
+ grains; MFront laws) and give the driving forces of dissipative solids:
1411
+
1412
+ ```python
1413
+ steel = Material(young=210e3, poisson=0.3, plasticity={
1414
+ "yield": 300.0, "hardening": 1e3, "norton": {"K": 50.0, "n": 5.0}})
1415
+ solution = solve_crack(mesh, crack, steel, grips, kinematics="finite", steps=20)
1416
+ solution.release_rate(energy="work") # the J of the deformation theory (Begley-Landes)
1417
+ solution.release_rate(energy="tip") # the driving force at the tip (configurational forces)
1418
+ opened, boundaries = insert_interfaces(polycrystal, faces=lambda c: c[:, 0] > -1e9,
1419
+ sides=polycrystal.cell) # the grain boundaries
1420
+ problem = CohesiveProblem(opened, boundaries, {0: crystal}, law, kinematics="finite")
1421
+ result = problem.run(grips, 0.02, steps=40, duration=1.0) # result.work: loads, bulk, interfaces
1422
+ ```
1423
+
1424
+ Ductile growth on meshes rebuilt at each advance (`morphogen.fracture.ductile`): the state
1425
+ of the points (internal variables, dissipated energy, stresses) and the displacement move
1426
+ from mesh to mesh, the lips apart, the body is brought back to equilibrium, and the crack
1427
+ advances when its driving force at the tip reaches a toughness, or the porosity of its GTN
1428
+ points a critical value; the far J at each advance draws the resistance curve:
1429
+
1430
+ ```python
1431
+ from morphogen.fracture import KinkedCrack, crack_mesh, propagate_ductile, solve_crack
1432
+
1433
+ growth = propagate_ductile(lambda c: crack_mesh(lower, upper, c, size=1.0), crack, steel,
1434
+ grips, load_step=0.25, increment=1.5, steps=5, toughness=30.0,
1435
+ kinematics="finite", transfer="nearest")
1436
+ advance, resistance = growth.resistance() # the R-curve (far J against the advance)
1437
+ moved = solve_crack(new_mesh, longer_crack, steel, grips, 1.2, initial=solution) # one transfer
1438
+ ```
1439
+
1440
+ A polycrystal grows its crack through its grains: the crack meshes carry the grains of a
1441
+ tessellation and their orientations, and the state of each grain moves within the grain
1442
+ from one mesh to the next:
1443
+
1444
+ ```python
1445
+ mesh_of = lambda c: crack_mesh(lower, upper, c, size=0.4, grains=tessellation)
1446
+ growth = propagate_ductile(mesh_of, KinkedCrack(((0, 4, 0), (2.5, 4, 0))), crystal, grips,
1447
+ load_step=1e-3, increment=1.0, steps=3, toughness=0.6)
1448
+ ```
1449
+
1450
+ Any morphology can be cracked: the crack meshes carry its phases (the materials, in
1451
+ `mesh.phase`) and the sides of the crack apart (`mesh.side`), as staircases or conforming
1452
+ to the level set of a two-phase morphology (MMG cuts the grid along it once, then each
1453
+ crack cuts that mesh and remeshes it), its void phases left out. Stiff inclusions deflect
1454
+ the crack, soft ones and pores attract it, and a front reaching a pore runs through it;
1455
+ the state of inelastic points moves material by material:
1456
+
1457
+ ```python
1458
+ from morphogen.fracture import phase_mesh
1459
+
1460
+ phases = phase_mesh(micro, lower, upper, 0.5) # cut along its level set, once
1461
+ mesh_of = lambda c: crack_mesh(lower, upper, c, size=0.5, morphology=phases, voids=[1])
1462
+ growth = propagate_kinked(mesh_of, crack, {0: matrix, 1: Material(void=True)}, held,
1463
+ forces=tension, increment=0.75, steps=4)
1464
+ ```
1465
+
1466
+ The phases and their interfaces have toughnesses of their own: each advance is the
1467
+ candidate of the largest `G(θ)/Γ(θ)`, the kink of the bulk or a path along an interface
1468
+ met within an increment (the first-order kinked factors of Cotterell & Rice), so that a
1469
+ crack turns along interfaces weaker than about a quarter of the phases (He & Hutchinson),
1470
+ climbs a staircase through the weak boundaries of a brick-and-mortar structure, and
1471
+ needs a higher load to enter a tough phase:
1472
+
1473
+ ```python
1474
+ from morphogen.fracture import Toughness
1475
+
1476
+ growth = propagate_kinked(mesh_of, crack, {0: mortar, 1: tablets}, held, forces=tension,
1477
+ increment=0.5, steps=6,
1478
+ toughness=Toughness({0: 1.0, 1: 4.0}, interfaces=0.2))
1479
+ growth.rows() # each advance: path (bulk or interface), G / toughness, critical load
1480
+ ```
1481
+
1482
+ ### Contact, self-contact and friction
1483
+
1484
+ `morphogen.contact` keeps the surfaces of a mesh out of each other, out of themselves and
1485
+ out of rigid obstacles, with Coulomb's friction, in small or finite strains
1486
+ ([docs/theory.md](docs/theory.md) §82): the integration points of the faces against the
1487
+ nearest point of the surface that they face, a penalty or the augmented Lagrangian;
1488
+ with `points="nodes"`, the nodes of the faces instead, for bodies that meet by their
1489
+ corners and edges.
1490
+
1491
+ ```python
1492
+ from morphogen.contact import ContactProblem, Obstacle, Pair, Surface
1493
+
1494
+ skin = Surface.of(mesh) # the free faces of the mesh
1495
+ walls = Pair(skin, friction=0.3) # a surface against itself
1496
+ punch = Obstacle.sphere(skin, centre, radius, motion=(0, 0, -0.1))
1497
+ problem = ContactProblem(mesh, materials, [walls], [punch])
1498
+ result = problem.run(prescribed, steps=20) # forces, areas, pressures, works
1499
+ ```
1500
+
1501
+ The walls of the pores of a periodic cell close on themselves, and on their images
1502
+ through the faces of the cell, along a loading path (`ContactCell`; in a configuration,
1503
+ `homogenization: {nonlinear: {contact: {friction: 0.3}}}`; the template
1504
+ `homogenization_contact`). Two tests come ready-made — a sample between two platens, and
1505
+ under an indenter, whose force reads its modulus:
1506
+
1507
+ ```python
1508
+ from morphogen.contact import compression, indentation
1509
+
1510
+ crush = compression(mesh, materials, -0.2, friction=0.1) # stress against strain
1511
+ crush.modulus, crush.tangent(), crush.self_area # stiffer as the walls close
1512
+ dent = indentation(mesh, materials, 0.05, indenter="sphere", radius=10.0, unload=True)
1513
+ dent.modulus, dent.layer_modulus(poisson=0.3), dent.hardness # Hertz; with the base
1514
+ ```
1515
+
1516
+ ```bash
1517
+ morphogen compress foam.json --size 0.2 --material 0=void 1=young:1000,poisson:0.3 \
1518
+ --strain -0.3 --friction 0.1 --fields crushed
1519
+ morphogen indent block.vtu --material 0=young:1000,poisson:0.3 --depth 0.05 --radius 10 \
1520
+ --unload --poisson 0.3
1521
+ ```
1522
+
1523
+ ### Interfaces that debond
1524
+
1525
+ The interfaces of the phases of a periodic cell — or the boundaries of its grains — open,
1526
+ break, close again and rub along a loading path ([docs/theory.md](docs/theory.md) §84):
1527
+ cohesive interface elements inserted on the torus of the cell, so that an interface that
1528
+ crosses a face goes on in the next cell.
1529
+
1530
+ ```python
1531
+ from morphogen.fracture import Bilinear, CohesiveCell
1532
+
1533
+ law = Bilinear(stiffness=1e7, normal_strength=30.0, shear_strength=30.0,
1534
+ mode_I=0.05, mode_II=0.05, friction=0.3)
1535
+ cell = CohesiveCell(mesh, materials, law, viscosity=0.02) # faces="phases", "grains", pairs
1536
+ res = cell.run({"times": [0, 1, 2], "increments": [24, 8], "strain": {"11": [0, 0.03, 0]}})
1537
+ res.stress, res.series["debonded_area"], res.series["interface_opening"]
1538
+ ```
1539
+
1540
+ In a configuration, `homogenization: {nonlinear: {interfaces: {normal_strength: 30,
1541
+ mode_I: 0.05, friction: 0.3, viscosity: 0.02}}}` (the template
1542
+ `homogenization_debonding`: glass beads that debond from their matrix, soft in tension
1543
+ and nearly whole again in compression); on the command line, `morphogen homogenize ...
1544
+ --interfaces normal_strength:30,mode_I:0.05,friction:0.3,viscosity:0.02`. A bead lets go
1545
+ at once: the `viscosity` (a time of the path) slows the damage and lets the steps
1546
+ through. Each pair of phases may have its law (`{(0, 1): law, (0, 2): other}`; `laws: {0-1:
1547
+ {...}}`), and `faces: grains` makes the grain boundaries of a polycrystal cohesive (the
1548
+ template `homogenization_intergranular`: a crack crosses the cell from boundary to
1549
+ boundary, and the work that broke it is the fracture energy times the area of the
1550
+ crack). The fields of the path map the damage and the opening of the interfaces. In the
1551
+ graphical interface, the box *Interfaces* of the tool *Loading path of a morphology*.
1552
+
1553
+ ### High-cycle fatigue
1554
+
1555
+ In the high-cycle regime a cell stays elastic, and whether a point lasts is read from
1556
+ the cycle of its stress ([docs/theory.md](docs/theory.md) §85): the amplitude of its
1557
+ deviator — the radius of the smallest hypersphere that holds its path — and a normal or
1558
+ hydrostatic stress, in a criterion calibrated on two fatigue limits of the phase.
1559
+
1560
+ ```python
1561
+ from morphogen.homogenization import DangVan, homogenize, path_fatigue
1562
+
1563
+ cycle = {"times": [0, 1, 2, 3], "increments": [1, 2, 2], "stress": {"11": [0, 40, -40, 40]}}
1564
+ out = homogenize(mesh, materials, properties=[], paths={"cycle": cycle}, fields="steps")
1565
+ alloy = DangVan.from_limits(bending=110.0, torsion=80.0) # or Crossland, Sines, Findley, Matake
1566
+ res = path_fatigue(out["cycle.periodic"], {0: alloy}, cycle=(1, 3)) # a criterion per phase
1567
+ res.utilization # of each point: its equivalent stress over its limit
1568
+ res.largest, res.safety, res.fraction() # of the cell; the share of its volume beyond the limit
1569
+ ```
1570
+
1571
+ In a configuration, `homogenization: {fatigue: {criterion: dang_van, bending: 110,
1572
+ torsion: 80, cycle: [1, 3]}}` writes the map of the utilization beside the curve of the
1573
+ path and adds `fatigue_utilization`, `fatigue_safety` and `fatigue_beyond` to the
1574
+ results (the template `homogenization_fatigue`: pores in a cast alloy; a spherical pore
1575
+ doubles the stress at its equator, where the utilization is the largest). In the
1576
+ graphical interface, the box *Fatigue* of the tool *Loading path of a morphology*.
1577
+
1578
+ ### Micromorphic continua: microfoam and nonlocal damage
1579
+
1580
+ `morphogen.micromorphic` solves micromorphic media on tetrahedral meshes (quadratic
1581
+ displacements, linear generalized degrees of freedom), in small or finite strains: the
1582
+ microfoam model of nickel foams (Dillard, Forest & Ienny 2006: anisotropic compressible
1583
+ plasticity in a micromorphic continuum, whose length removes the strain concentration of
1584
+ holes as small as the cells; in finite strains the plasticity of the logarithmic strains
1585
+ and the objective measures `χ⁻¹ F` and `χ⁻¹ Grad χ` of Forest & Sievert), a micromorphic
1586
+ damage model (the implicit gradient model of Peerlings et al.) and micromorphic ductile
1587
+ damage (von Mises elasto-(visco)plasticity whose damage follows the micromorphic
1588
+ cumulated plastic strain), whose cracks are bands of damage independent of the mesh:
1589
+
1590
+ ```python
1591
+ from morphogen.micromorphic import (CHI, DamageProblem, DuctileProblem, Microfoam,
1592
+ MicrofoamProblem, MicromorphicDamage, MicromorphicDuctile)
1593
+
1594
+ foam = Microfoam.nickel_foam(length=0.1) # the article's Tables 2 and 3 (MPa, mm)
1595
+ problem = MicrofoamProblem(mesh, foam) # u (P2) and the microdeformation (P1)
1596
+ result = problem.run([(bottom, 1, 0.0), (held, CHI["chi12"], 0.0), (top, 1, 0.1)], steps=10)
1597
+ fields = problem.fields(result.values, result.state) # strain, stress, p, chi
1598
+ crushed = MicrofoamProblem(mesh, foam, kinematics="finite") # fields: log strain, Cauchy, J
1599
+
1600
+ damage = MicromorphicDamage(young=1000.0, poisson=0.2, threshold=1e-3, length=0.08)
1601
+ cracked = DamageProblem(mesh, damage, kinematics="finite").run(supports, steps=40)
1602
+
1603
+ steel = MicromorphicDuctile(young=200e3, poisson=0.3, yield_stress=400.0, hardening=1e3,
1604
+ voce=((200.0, 20.0),), length=0.1, onset=0.02, critical=0.1,
1605
+ triaxiality="rice_tracey") # or johnson_cook, lemaitre, none
1606
+ ductile = DuctileProblem(mesh, steel, kinematics="finite")
1607
+ result = ductile.run(supports, steps=40) # a predictor by the last tangent
1608
+ ductile.damage(result.state), ductile.plastic_strain(result.state)
1609
+ ```
1610
+
1611
+ ### Z-mat material files
1612
+
1613
+ The material files of Z-mat (Z-set) run as they are: a `gen_evp` behaviour of von Mises
1614
+ or Hill elasto-(visco)plasticity on morphoGen's own kernels, the others (hyperbolic or
1615
+ double Norton flows, power-law hardening, several potentials...) as MFront behaviours
1616
+ (MFront's brick StandardElastoViscoPlasticity):
1617
+
1618
+ ```yaml
1619
+ homogenization:
1620
+ materials:
1621
+ 0: {zmat: alloy.mat} # ***behavior gen_evp ... ***return
1622
+ 1: {young: 400000, poisson: 0.2}
1623
+ ```
1624
+
1625
+ `morphogen zmat alloy.mat` shows the translation, `morphogen zmat --coverage` what of
1626
+ Z-mat's library morphoGen covers (docs/zmat.md). The other way, `write_zmat` writes an
1627
+ elastic, von Mises, Hill or porous material of morphoGen (a behaviour identified on the response
1628
+ of a morphology: its Gurson model) as a material file of Z-mat, read back as the same:
1629
+
1630
+ ```python
1631
+ from morphogen.homogenization.zmat import write_zmat
1632
+
1633
+ write_zmat({"young": 200000, "poisson": 0.3, "plasticity": {
1634
+ "yield": 130, "kinematic": [{"C": 15000, "D": 300}], "norton": {"K": 400, "n": 7}}},
1635
+ "alloy.mat")
1636
+ ```
1637
+
1638
+ Porous plasticity (`porous_plastic` files of Z-mat, or a material of its own): the ductile
1639
+ damage of Gurson-Tvergaard-Needleman (coalescence, Chu and Needleman's nucleation) and of
1640
+ Rousselier, and the compaction of powders and foams by the elliptic criterion of Abouaf,
1641
+ with the Armstrong-Frederick backstresses of the matrix for GTN and the elliptic criterion
1642
+ (`kinematic: [{C: 30000, D: 200}]`: the potential of σ - X), in small and finite strains,
1643
+ on morphoGen's kernels (CPU); the curves give the porosity `f`:
1644
+
1645
+ ```yaml
1646
+ homogenization:
1647
+ materials:
1648
+ 0:
1649
+ young: 200000
1650
+ poisson: 0.3
1651
+ porous_plasticity: {criterion: gurson, yield: 300, porosity: 0.01, q1: 1.5, q2: 1.0,
1652
+ fc: 0.05, fF: 0.2, hardening: 1000}
1653
+ 1: {zmat: {file: powder.mat, porosity: 0.4}} # ***behavior porous_plastic ...
1654
+ ```
1655
+
1656
+ ### Graphical interface and figures
1657
+
1658
+ `morphogen gui` starts a local web server (standard library only, address
1659
+ `127.0.0.1`) and opens the interface in the browser; `morphogen desktop` (or the program
1660
+ `morphogen-desktop`, `pip install ".[desktop]"`) opens the same interface as a
1661
+ stand-alone application, in a window of its own whose server is private to it (a free
1662
+ port of the local machine): its menu holds the workspace (Open…, Save…), the folder of
1663
+ the session and the help; the folders of the workspaces and the paths that the forms
1664
+ take (**Browse…**) are chosen in the dialogs of the system, the files of the results are
1665
+ saved where one chooses or opened by their applications, the folder of a result is
1666
+ shown in the file manager (**Show its folder**), and closing the window asks first when
1667
+ the workspace holds items not saved. The forms of every model open
1668
+ filled with its example configuration (its template: parameters and domain), so that
1669
+ any model runs as it opens. Its menus follow the work in four sections, each with its
1670
+ tabs: **Create** (Generate, Topology optimization, Inverse design, Tile assemblies),
1671
+ **Characterize** (Statistics), **Simulate** (Linear homogenization, Mechanics, Learning,
1672
+ Fracture, Contact, Nonlocal damage, Stability, Physics, Couplings, Explicit
1673
+ dynamics) and **Export & compare**
1674
+ (Export, Solvers & formats, Comparisons, Ashby charts). A tab lists its tools in a menu
1675
+ on its left, under the headings of what they do — Mechanics: *Loading paths* (of a
1676
+ morphology, its macroscopic law, the NTFA), *Behaviours of materials* (material point,
1677
+ identification), *Linear elasticity* (tensors, frames of beams); Statistics:
1678
+ *Morphology*, *Representative volume*, *Reconstruction*; Fracture: *Cracks*, *Cohesive
1679
+ zones*, *Phase field*; Solvers & formats: *AMITEX_FFTP*, *Abaqus and meshes*,
1680
+ *Behaviours of materials* — and Generate lists its models by family, with a filter. The
1681
+ **search** of the header (`/`) finds a tool, a model or an option of their forms (a
1682
+ behaviour, a strain energy, a file format) and opens it with the option set: "arruda"
1683
+ opens the loading path of a morphology with the energy of Arruda and Boyce chosen,
1684
+ "finite strains" its kinematics, "stl" the surfaces of Export. The address of the page
1685
+ names what is shown (`#mechanics/path`, `#generate/voronoi`): a link to keep or to
1686
+ give. **?** opens the map of the interface (every tab and every tool, as links),
1687
+ `Ctrl + Enter` runs the form shown (its button stays in sight under the long forms), and
1688
+ the colours follow the system or are set light or dark. Each morphology, simulation and optimized design is
1689
+ kept in the **workspace** of the session (a strip of its items under the menus), from
1690
+ which any tab takes its input, before or after another as needed: an item is sent on by
1691
+ the buttons of its usual next steps or the menu of the other tools (by section), which
1692
+ set the forms to take it (e.g. a morphology as the specimen of a crack), and the item
1693
+ stays when another tool of the tab is chosen; a click on an item shows it, sends it on,
1694
+ renames or removes it. Each run of a tool joins the workspace too (R), so that a run with other
1695
+ parameters keeps the first: shown again, its form filled with its parameters, to change
1696
+ them and run again. The long forms stand in boxes (specimen, material, loading, solver,
1697
+ output; the details seldom changed folded until opened). A long computation is stopped
1698
+ by **Stop** beside its progress, at its next step (an iteration of its solver, a
1699
+ realization, a step it reports): a tool or a simulation then keeps nothing, an
1700
+ optimization keeps the design of its last iteration. The behaviour of a material
1701
+ defined at a material point (calibrated on the points of a test), identified, learned
1702
+ from data or imported from a
1703
+ Z-set file joins the workspace too (B), with its own elasticity: the loading paths of
1704
+ morphologies, the NTFA, the bulk of a cracked plate or one phase of a cracked
1705
+ morphology, the inputs of AMITEX_FFTP and Abaqus and the MFront sources take it, so
1706
+ that it is given once. A tool runs on several items one after another (**Run on several
1707
+ items** below its form: the same parameters for each morphology or behaviour checked),
1708
+ and the curves of these runs are then compared in one click.
1709
+
1710
+ * **Generate**: any model, chosen in a menu by family (random sets and particles, fibres
1711
+ and layers, tessellations and foams, lattices and TPMS, bio-inspired, growth and
1712
+ patterns, assemblies), with a form built from its parameters; sections of its
1713
+ level set (anti-aliased boundaries; of the implicit functions of its phases when it
1714
+ has several: coatings, inclusions, dead leaves, osteons, cells with phases), computed
1715
+ at up to 2048 pixels per edge without
1716
+ a voxel image of the volume, measures of its level set against theory; for the
1717
+ models grown by a process (automata, reaction–diffusion, nucleation and growth,
1718
+ aggregation), the animation of their formation with the share of the cells changed
1719
+ at each step; for the network models with `frame_stiffness`, the stiffness of their
1720
+ frame of beams in a table of its own and in the card of the morphology;
1721
+ * **Statistics**: the size of the representative volume element of the model of a
1722
+ morphology, by the ensemble or the window method (its windows also shifted around a
1723
+ periodic realization), for its volume fraction or apparent moduli (the variance fitted
1724
+ as `K V^-γ`, the integral range, the volumes for chosen errors and numbers of
1725
+ realizations, the tables and figures of the report); its morphological measures
1726
+ against the theory of its model; its correlation functions and
1727
+ distributions (covariance, lineal path, chords, granulometry, pore sizes, Choquet
1728
+ capacities) with the closed forms of its model; its stereology (Saltykov's unfolding);
1729
+ the RVE fit of a pasted table of results of any origin; a morphology reconstructed
1730
+ from its two-point function (Yeong & Torquato); the percolation threshold of its model
1731
+ against a parameter (the volume fraction), with the curve of the probabilities against
1732
+ the fraction, the threshold of its elastic moduli (its rigidity), and the critical
1733
+ exponent of the conductivity or of the elastic moduli at the threshold;
1734
+ * **Simulate**: a morphology of the workspace, its conforming mesh of its level set
1735
+ (finite elements) or its voxels (FFT, on an NVIDIA GPU when there is one), the
1736
+ materials of its phases, the apparent shear or bulk modulus with its fields;
1737
+ * **Mechanics**: loading paths of a morphology (elastic, von Mises elasto-viscoplastic,
1738
+ Méric–Cailletaud crystal plasticity, GTN, Rousselier and elliptic porous plasticity,
1739
+ viscoelasticity by Prony series, hyperelastic energies, isotropic damage with a
1740
+ fracture energy, Z-set files, MFront laws; small or finite strains; FFT, on the CPU or an NVIDIA GPU,
1741
+ or finite elements; strains, stresses or both over time) with their curves, fields
1742
+ and videos; the NTFA reduced
1743
+ model trained on paths and compared with the full field; a material point under a
1744
+ path, with the points of a test, its behaviour kept in the workspace for the other
1745
+ tools; the identification of a von Mises, Hill or porous behaviour (yield stress,
1746
+ hardenings, viscosity, elastic constants, Hill's coefficients; Gurson's q1, q2, the
1747
+ initial porosity...) on the curves of
1748
+ runs followed together — the macroscopic law of a morphology, a tension and a cycle in
1749
+ shear to tell its isotropic hardening from its kinematic one, the Gurson model of a
1750
+ porous morphology under several triaxialities — or on the points of a test, as Zopt
1751
+ does, from the values of the form or a behaviour of the workspace, with the stiffness
1752
+ and compliance of the elasticity identified; the linear tensors (stiffness with its
1753
+ compliance, thermal expansion,
1754
+ conductivity) with their bounds, by FFT, by finite elements on a conforming mesh or
1755
+ by extended finite elements (XFEM) on a grid cut by the level set; the stiffness of a fibre network, an open foam or a
1756
+ random lattice of the workspace as the frame of beams of its framework (Euler–Bernoulli
1757
+ or Timoshenko beams, rigid joints, the modulus and Poisson's ratio of the fibres): its
1758
+ stiffness and compliance, engineering constants and directional Young's modulus, the energy of
1759
+ uniaxial stresses split into stretching, bending, torsion and shear, its ratio to the
1760
+ affine estimate, the non-affinity, a drawing of its beams coloured by their axial
1761
+ forces (the force chains) or their stretching or bending energy under a uniaxial
1762
+ stress, and Ban et al.'s softening of non-identical beams, with replicas of the
1763
+ stiffness of the beams against it (their table and figure, in the background with
1764
+ their progress);
1765
+ * **Learning**: a behaviour learned from data — the responses of a behaviour at a
1766
+ material point (those of Mechanics, a material of the configurations, a behaviour of
1767
+ the workspace) or the homogenized responses of a morphology (FFT on its voxels) along
1768
+ random strain paths, a perceptron, a learned convex potential, a recurrent network or
1769
+ a generalized standard material (its internal variables, a viscous dissipation; the
1770
+ strain that every model sees in finite strains) trained on them in the background (the losses of each epoch reported, **Stop**
1771
+ between two of them), with the fields of the paths, the model and the training of
1772
+ `morphogen learn`; its learning curves, its errors on the validation paths, its tangent at the
1773
+ natural state (stiffness and compliance) against the elasticity of the reference, and its law
1774
+ along a validation path against the reference (turned by an orientation for a crystal
1775
+ learned in its axes); the model saved (`learned.npz`, with its data and the
1776
+ configuration that learns it again) and the learned law kept in the workspace (B),
1777
+ which the loading paths of morphologies give to a phase;
1778
+ * **Fracture**: the stress intensity factors of a crack (edge, through or penny; K_I,
1779
+ K_II, K_III by interaction integrals, G by G-θ, J) in a plate or a morphology, in small
1780
+ or finite strains; its growth in a plate or through a morphology of the workspace (E
1781
+ and ν or void for each phase, conforming interfaces; kinking, toughness, ductile by
1782
+ J_tip or the porosity of GTN points, the R-curve, the phase at each tip, the path over
1783
+ the phases, a video; the toughness of each phase and of their interfaces, the
1784
+ deflections along weak interfaces marked); cohesive zones (a ligament, the interfaces of a
1785
+ double cantilever beam); the growth of a crack through a polycrystal; the phase-field
1786
+ fracture of a morphology, in small or finite strains, whose cracks start and merge in its phases along a loading
1787
+ path (the curve, the strength, the work of fracture, the damage field); the growth of a
1788
+ crack front in 3D (an elliptical crack inclined to the tension inside a block: K_I,
1789
+ K_II, K_III along its curved front against Irwin and Kassir & Sih, each point of the
1790
+ front advancing and kinking on its own);
1791
+ * **Stability**: the post-bifurcated patterns of a lattice frame (honeycomb,
1792
+ triangular, square, kagome; cubic, bcc, octet, Kelvin, diamond and pyrochlore space
1793
+ frames) or of a
1794
+ morphology (its mirrored conforming mesh when its cell is symmetric, else its voxels)
1795
+ under a macroscopic strain, with their irreps, critical loads, wave vectors and the
1796
+ Bloch-wave stability that tells the cell needed; the bifurcation along a nonlinear
1797
+ path in finite strains (the pattern transformation of a square array of holes) and the
1798
+ post-bifurcated branch; the Bloch-wave band structure of a morphology and its gaps;
1799
+ * **Nonlocal damage**: the microfoam model of metallic foams (Dillard, Forest & Ienny),
1800
+ micromorphic ductile damage with the stress triaxiality (Rice & Tracey, Johnson &
1801
+ Cook, Lemaitre) and micromorphic damage of quasi-brittle solids, on notched plates,
1802
+ bars or morphologies of the workspace: force–displacement curves, the bands and their
1803
+ width set by the internal length, videos of the damage;
1804
+ * **Physics**: the other physics of a morphology of the workspace, on its voxels — its
1805
+ transport properties (thermal and electrical conductivities, permittivity, permeability,
1806
+ diffusivity) and their tensor between the bounds of Wiener and of Hashin and Shtrikman;
1807
+ the flow through its pores (Darcy's permeability), the acoustic parameters of the rigid
1808
+ frame and the absorption curve of a layer of it on a rigid wall; the storage and loss
1809
+ moduli and the loss factor of a composite with a viscoelastic phase over a range of
1810
+ frequencies;
1811
+ * **Couplings**: transient diffusion into a morphology (uptake curve, fields, the
1812
+ effective diffusivity), the thermal oxidation of an epoxy plate (Ernault et al.) and
1813
+ of a morphology in its volume (the oxidized layer around impermeable phases), and
1814
+ hygromorph multilayers bending and twisting as moisture enters them, their layers
1815
+ homogenized from morphologies of the workspace;
1816
+ * **Explicit dynamics**: the crushing, tension, shear or impact of a morphology run by
1817
+ OpenRadioss (its voxels or a conforming mesh; its phases elastic, von Mises
1818
+ elastoplastic or Johnson–Cook, with failure; the self contact of its outer surface;
1819
+ engineering units: MPa, kg/m³, m/s, 1/s, ms), its nominal stress–strain curves at both
1820
+ faces, energies, peak and plateau stresses, densification strain and absorbed energy,
1821
+ its fields over time in 3D and a video; without OpenRadioss here, its inputs and the
1822
+ scripts to run them elsewhere; the results of a run made elsewhere read back; the
1823
+ installation found, or a release installed from GitHub. Its curves go to Comparisons
1824
+ with the loading paths (E33 and S33 for a compression along z);
1825
+ * **Export**: the files of an item of the workspace with an archive of them all — of a
1826
+ morphology, its geometry, sections, voxel images of its level set and phases (up to
1827
+ 2048 voxels per edge, memory permitting), its surface (STL) and conforming mesh (for
1828
+ a morphology of several phases: the implicit function and the surface of each phase,
1829
+ `level_set_phase1.vti`, `surface_phase1.stl`..., and the mesh conforming to all their
1830
+ interfaces) and a
1831
+ video (sections of its level set sweeping it, orthoslices, a turntable); of a
1832
+ simulation, a view of its fields (field, colormap, magnification, cut, range) and a
1833
+ video (the field on the deformed mesh under a growing or oscillating load, the
1834
+ colours following the load; a turntable, a sweep), its tables, fields, mesh and
1835
+ configuration (to rerun it with `morphogen run`), drawn without solving again;
1836
+ * **Design**: the rule of a cellular automaton whose structures match a morphology of
1837
+ the workspace (a genetic search over its birth and survival sets), and the rigidity of
1838
+ strut lattices as their struts are removed (the mechanisms, states of self-stress and
1839
+ floppy strains of Maxwell and Calladine: stretching- or bending-dominated);
1840
+ * **Optimize**: topology optimization, drawn live, from a void ball, noise, or a
1841
+ morphology or simulation of the workspace (its densities, its solid material); the
1842
+ design joins the workspace as a morphology (its level set: the densities about 1/2),
1843
+ to simulate on a conforming mesh or to export;
1844
+ * **Solvers & formats**: the inputs of AMITEX_FFTP (and the reading of its results) and
1845
+ of Abaqus (materials, orientations, MFront laws, periodic equations, loading steps) of
1846
+ a morphology; its meshes and images in the formats of other codes (Gmsh, Medit,
1847
+ FEniCSx, Neper, DAMASK, TIFF, MetaImage; the level set as an image of floats, one per
1848
+ phase when it has several); the MFront sources of morphoGen's laws; the
1849
+ import of a Z-set material file, and the behaviours of the workspace written as such
1850
+ files (a behaviour identified on a morphology, for Z-set);
1851
+ * **Comparisons**: the curves of several runs of the workspace on one figure (loading
1852
+ paths of morphologies, material points; a strain component or the time against a
1853
+ stress, the plastic strain or the porosity, true measures in finite strains), with the
1854
+ points of a test and the gap of each run to them, their final and extreme values;
1855
+ * **Tile assemblies**: exact number of the compatible assemblies of a tile set in a box
1856
+ (combinatorial metamaterials), and one assembly drawn by wave function collapse;
1857
+ * **Ashby chart**: the records of a database, filtered, as a normalized chart with a
1858
+ table view (light and dark themes).
1859
+
1860
+ The workspace is saved to a folder and opened again in another session (**Save…** and
1861
+ **Open…** beside it): the morphologies, simulations and results with their files.
1862
+
1863
+ Every item of the workspace is also drawn in 3D in the page (**View in 3D** in the menu
1864
+ of its chip, and below the results of Generate and Linear homogenization), with WebGL
1865
+ and no library, so that the page works offline: turned by dragging, moved by
1866
+ shift-dragging, zoomed by the wheel, cut by a section plane along x, y or z, the box and
1867
+ each phase shown or hidden. A morphology is drawn by the interfaces of its phases (the
1868
+ marching cubes of its level set, the exact facets of polycrystals, the faces of the
1869
+ voxels of cells and grains), a simulation by the faces of its mesh or voxels coloured by
1870
+ a field (colour map and scale), on the mesh deformed by its magnified displacement; the
1871
+ faces of the box and the section show the phases or the field inside, as the sections
1872
+ do. The surfaces (`morphogen.viz.surfaces`, `GET /api/surface`) hold at most 300 000
1873
+ triangles: coarser grids, or simplified meshes, keep them within.
1874
+
1875
+ The tabs of tools are built from a registry (`morphogen.gui.tools`): each tool declares
1876
+ its form (typed fields, fields shown on conditions, items of the workspace, the
1877
+ materials of their phases) and runs as a job whose progress the page follows; its
1878
+ values, tables, figures, videos and files come back with an archive, and the
1879
+ morphologies it makes join the workspace. A module of tools added to the package
1880
+ appears in the interface by itself.
1881
+
1882
+ `morphogen view` draws the same figures from the command line: sections, `--tile 3`
1883
+ (periodic tiling), `--surface` (3D view), `--labels` (grains), `--history`,
1884
+ `--kinetics` (Avrami), and `--animate formation.gif` for the formation of a structure
1885
+ described by a configuration.
1886
+
1887
+ `morphogen fit-rule image.vti -o rule.yaml` finds the automaton rule, and the density
1888
+ of its initial noise, whose structures match the volume fraction, interface density and
1889
+ correlation function of a two-phase image, and writes the configuration that generates
1890
+ them; `--tiling hexagonal` (or any other lattice: `triangular`, `penrose`,
1891
+ `ammann_beenker`, `bcc`, `fcc`, `icosahedral`) searches the rules of the automaton on
1892
+ the cells of that tiling.
1893
+
1894
+ ### Explicit dynamics with OpenRadioss
1895
+
1896
+ ```python
1897
+ import morphogen as mg
1898
+ from morphogen import dynamics
1899
+
1900
+ lattice = mg.model_from_config({"type": "tpms", "surface": "gyroid", "volume_fraction": 0.2,
1901
+ "cell_size": 5.0}) # an aluminium gyroid, its lengths in mm
1902
+ micro = lattice.generate(mg.Domain.cube(10.0), seed=1)
1903
+ materials = {0: "void", 1: {"young": 70e3, "poisson": 0.33, "density": 2.7e-9, # MPa, Mg/mm³
1904
+ "plasticity": {"yield": 150.0, "hardening": 600.0},
1905
+ "failure_strain": 0.4}}
1906
+ test = dynamics.explicit_test(micro, materials,
1907
+ {"kind": "compression", "strain": 0.6, "strain_rate": 500.0},
1908
+ "gyroid_crush", resolution=32) # units: Mg, mm, s by default
1909
+ values = dynamics.summary(test.result) # peak and plateau stresses (MPa), densification...
1910
+ ```
1911
+
1912
+ The loadings are `compression`, `tension` and `shear` (the lower face held, the upper
1913
+ one driven at the nominal strain rate after a smooth start, laterally `fixed` or
1914
+ `free`) and `impact` (the morphology thrown at a `velocity` against a rigid wall), with
1915
+ the self contact of the outer surface by default. The values are in the consistent unit
1916
+ system of `units` (`dynamics.UnitSystem`: Mg, mm, s by default, i.e. MPa, Mg/mm³, mm/s, N,
1917
+ mJ; `length_scale` converts the lengths of the morphology). The time step of an explicit
1918
+ run is that of the smallest element (`dynamics.critical_time_step`; the manifest of the
1919
+ inputs gives the number of cycles before the run): a coarser mesh, a higher rate or a
1920
+ minimum time step (`time_step`, mass scaling) shortens it. The command line does the
1921
+ same from a geometry or an image, and reads back a run made elsewhere:
1922
+
1923
+ ```bash
1924
+ morphogen radioss install # the latest release, from GitHub
1925
+ morphogen radioss export gyroid.json --materials aluminium.yaml --voxels 32 \
1926
+ --loading compression --strain 0.6 --rate 500 -o crush
1927
+ morphogen radioss run crush --threads 8 # Starter, Engine, conversions, summary
1928
+ morphogen radioss read crush --frames-vtu # curves.csv, energies.csv, frames/*.vtu
1929
+ ```
1930
+
1931
+ The inputs follow the fields of the Radioss Reference Guide for the input version 2022
1932
+ (`/BEGIN`, `/NODE`, `/BRICK`, `/TETRA4`, `/TETRA10`, `/PART`, `/PROP/SOLID`, `/MAT/LAW1`,
1933
+ `/MAT/LAW2`, `/MAT/LAW36`, `/FUNCT`, `/GRNOD`, `/BCS`, `/IMPVEL`, `/INIVEL`, `/RWALL`,
1934
+ `/SURF/PART/EXT`, `/INTER/TYPE24`, `/TH/NODE`, `/TH/PART`, `/TH/RWALL`; `/RUN`, `/TFILE`,
1935
+ `/ANIM`, `/DT/NODA/CST`); the forces of the faces come from the reactions of their nodes
1936
+ in the time history (`th_to_csv`) or in the animations (`anim_to_vtk`), the forces on a
1937
+ rigid wall from the change of the momentum.
1938
+
1939
+ ### Homogenization in a configuration
1940
+
1941
+ A `mesh` section describes the conforming meshes, and a `homogenization` section the
1942
+ materials, boundary conditions and properties:
1943
+
1944
+ ```yaml
1945
+ mesh:
1946
+ size: 0.5 # largest element edge; the interfaces are refined
1947
+ order: 2 # 10-node tetrahedra (the default of an analysis); 1: 4-node
1948
+ homogenization:
1949
+ materials:
1950
+ 0: void # pores (not meshed)
1951
+ 1: {young: 210000.0, poisson: 0.3, conductivity: 100.0}
1952
+ boundary_conditions: [kubc, mixed]
1953
+ properties: [bulk_modulus, shear_modulus, conductivity]
1954
+ ```
1955
+
1956
+ `method: fft` (with a `voxels` section and `boundary_conditions: [periodic]`) uses the
1957
+ FFT solver instead, on an NVIDIA GPU with `device: gpu`. Crystals are given as `{cubic: [C11, C12, C44]}`,
1958
+ `{hexagonal: [C11, C12, C13, C33, C44]}` or `{stiffness: <6 x 6>}`; tessellations with
1959
+ `crystal_orientations: true` are meshed grain by grain (`mesh: {size: 0.08,
1960
+ min_feature: 0.02}`) and their crystals turned by the orientations of the grains.
1961
+ Templates: `homogenization_spheres` (the four conditions on a composite),
1962
+ `homogenization_gyroid` (stiffness tensor of a lattice, local fields),
1963
+ `homogenization_voronoi` (FFT), `homogenization_polycrystal` (copper, finite elements
1964
+ on grains), `homogenization_polycrystal_inclusions` (crystals, grain boundaries and
1965
+ inclusions, FFT), `homogenization_mixed_loading` (thermo-elastic loadings mixing strains
1966
+ and stresses), `homogenization_viscoplastic` (tension, relaxation and unloading of a
1967
+ particle-reinforced viscoplastic alloy), `homogenization_crystal_plasticity` (tension of
1968
+ a polycrystal to 10 % in finite strains, Méric–Cailletaud crystal plasticity),
1969
+ `homogenization_crystal_plasticity_fft` (the same on 24³ voxels of 20 grains, to 5 %,
1970
+ FFT), `homogenization_twinning` (the twins of a textured magnesium, pulled and
1971
+ compressed), `homogenization_detwinning` (the same pulled and brought back: twins that
1972
+ shear back, lattices that turn), `homogenization_cleavage` (a polycrystal of iron that
1973
+ cleaves through its grains), `homogenization_crack_closure` (the same pushed back: its
1974
+ crack closes), `homogenization_slip_cleavage` (a polycrystal that yields first: the slip
1975
+ of its grains nucleates their cleavage), `homogenization_cleavage_band` (planes regularized
1976
+ by their microdamage: a crack across a band of a given width, whatever the grid), `homogenization_grain_fracture` (cohesive grain boundaries and cleavage planes:
1977
+ cracks between the grains or through them), `homogenization_beremin` (the probability of
1978
+ cleavage of a ferritic steel, by the Weibull stress of Beremin), `rve_poisson_fibers_fe` (RVE study of the 2014 paper), `rve_crystal_plasticity_fft`
1979
+ (RVE sizes of the elastic and viscoplastic responses of polycrystals). The other physics:
1980
+ `homogenization_transport` (thermal and electrical conductivities, permittivity and
1981
+ diffusivity on the same voxels), `homogenization_piezoelectric` (a strong coupling),
1982
+ `homogenization_viscoelastic` (storage and loss moduli at `frequencies`, relaxation in
1983
+ time), `homogenization_poroelastic` (Biot's law, `fluid_bulk_modulus`),
1984
+ `homogenization_xfem` (`method: xfem`: the level set of the model cuts the grid of the
1985
+ `voxels` section), `homogenization_acoustic_foam` (Darcy's permeability and the acoustic
1986
+ parameters of an open-cell foam) and `rve_multiphysics` (the RVE sizes of several physics
1987
+ at once);
1988
+ `homogenization.fracture` (`{toughness: ..., length: ...}`) makes the loading paths break
1989
+ the voxels by the phase-field method. Nested and
1990
+ bio-inspired templates: `cox_nanocomposite`, `coated_spheres`, `hierarchical_lattice`,
1991
+ `menger_sponge`, `nacre`, `bouligand`, `wood`, `osteons`, `trabecular_bone`,
1992
+ `vascular_tree`. Fibres and lattices: `hardcore_fibers`, `curved_fibers`,
1993
+ `random_walk_fibers` (bending fibres packed by forces to 0.35), `contact_fibers`
1994
+ (the same drawn into contact, Keilmann et al. 2026), `cross_linked_fibers`
1995
+ (entangled carbon fibres bonded by epoxy, Chatti et al.), `delaunay_network` (a
1996
+ fibre network on the edges of a Delaunay triangulation, Ban et al.), `graded_lattice`
1997
+ (an octet lattice graded and turned, with its STL surface for additive manufacturing).
1998
+ Dead leaves and Torquato: `sequential_dead_leaves`, `transparent_dead_leaves`,
1999
+ `dense_packing`, `penetrable_spheres`, `reconstruction`, `hyperuniform_cells`.
2000
+
2001
+ From the command line, for one sample (a geometry `.json`, a mesh `.vtu`/`.mesh`, or an
2002
+ image for the FFT solver):
2003
+
2004
+ ```bash
2005
+ morphogen homogenize spheres.json --size 0.5 --material 0=void 1=young:210e3,poisson:0.3 \
2006
+ --bc kubc mixed --property bulk_modulus shear_modulus --fields fields/
2007
+ # a loading path with the plasticity of the materials (YAML), curves in curves/
2008
+ morphogen homogenize composite.vtu --materials alloy.yaml --property stiffness \
2009
+ --path "tension: t=0,20,120 n=10,10 E11=0,0.02,0.02" --curves curves/
2010
+ # the same in finite strains: the curves add the true strains LE and stresses TS
2011
+ morphogen homogenize polycrystal.vtu --materials nickel.yaml --periodic --finite \
2012
+ --path "tension: t=0,100 n=40 E11=0.1" --curves curves/ --fields fields/
2013
+ # on a voxel image: the FFT solver (fields as .vti)
2014
+ morphogen homogenize composite.vti --materials alloy.yaml \
2015
+ --path "tension: t=0,20 n=10 E11=0,0.02" --curves curves/ --fields fields/
2016
+ # the same on an NVIDIA GPU (CuPy, the extra [gpu])
2017
+ morphogen homogenize composite.vti --materials alloy.yaml --device gpu \
2018
+ --path "tension: t=0,20 n=10 E11=0,0.02" --curves curves/
2019
+ # the same image for AMITEX_FFTP: its inputs and the MPI script, then its results
2020
+ morphogen amitex export composite.vti --materials alloy.yaml -o amitex/ \
2021
+ --path "tension: t=0,20 n=10 E11=0,0.02" # the plastic phases as MFront laws
2022
+ sh amitex/composite_run.sh # where AMITEX_FFTP and MFront are installed (Linux)
2023
+ morphogen amitex read amitex/ --json # the curves of the runs
2024
+ # the elasticity of the phases only: the apparent stiffness and moduli (a CSV row)
2025
+ morphogen amitex export composite.vti --materials alloy.yaml --elastic-only -o elastic/
2026
+ sh elastic/composite_run.sh && morphogen amitex read elastic/ -o stiffness.csv
2027
+ # the MFront sources of the plastic phases, for another code (umat: Cast3M, abaqus...)
2028
+ morphogen mfront --materials alloy.yaml -o laws/
2029
+ cd laws && mfront --obuild --interface=abaqus alloyPhase0.mfront
2030
+ ```
2031
+
2032
+ ### RVE study
2033
+
2034
+ ```bash
2035
+ morphogen template rve_poisson_fibers_fe -o study.yaml # or rve_poisson_fibers (morphology)
2036
+ morphogen run study.yaml
2037
+ ```
2038
+
2039
+ The run writes:
2040
+
2041
+ * `results.csv`: one row per realization (measures and apparent properties);
2042
+ * `homogenization.csv`: one row per realization, property and boundary condition;
2043
+ * `rve_report.md`, `rve_report.tex` and `rve_report.json`: for each property and
2044
+ condition, the statistics per size, K, γ (free and imposed), R², the RVE sizes for
2045
+ each (ε_rel, n) with confidence intervals, the discrepancy between conditions, the
2046
+ isotropy criteria and the bounds;
2047
+ * when the homogenization computes the `stiffness`, for each condition and size the mean
2048
+ stiffness C̄_ij and its compliance S_ij = C̄⁻¹ (the inverse of the mean C, not the mean
2049
+ of the inverses), each component ± 2 standard deviations, and the RVE size of each
2050
+ component (Voigt order 11 22 33 23 31 12, engineering shears): in the report, in
2051
+ `rve_stiffness.csv` (one row per condition and size: `C11` ... `C66`, `S11` ... `S66`,
2052
+ `C11_std` ...) and in `rve_stiffness_<bc>.png`;
2053
+ * figures per property.
2054
+
2055
+ To analyse apparent properties computed elsewhere (CSV with a `volume` column, one
2056
+ row per realization; `--group-by` splits the rows by boundary condition):
2057
+
2058
+ ```bash
2059
+ morphogen fit fe_results.csv --property k_app mu_app --group-by bc --gamma 0.6667 \
2060
+ --eps 0.01 0.05 --n 1 10 -o report/
2061
+ ```
2062
+
2063
+ Nonlinear responses are analysed in the same way: `rve.properties` may name quantities
2064
+ of the curves of the loading paths, `<path>.<quantity>` at the end of the path or
2065
+ `<path>.<quantity>@<time>` at the end of one of its steps (`tension.S11@3`: the stress
2066
+ of the path `tension` at the time 3; also `TS11` in finite strains, `p`, or the mean of
2067
+ a phase, `S11_1`), followed by a boundary condition to keep only that one
2068
+ (`tension.S11@3.periodic`). The template `rve_crystal_plasticity_fft`, after Yang et al.
2069
+ (2019), compares the RVE sizes of the elastic moduli of a polycrystal with those of its
2070
+ stress at 0.1, 0.3 and 1 % of a tension (crystal plasticity, nonlinear FFT solver):
2071
+
2072
+ ```bash
2073
+ morphogen template rve_crystal_plasticity_fft -o study.yaml && morphogen run study.yaml
2074
+ morphogen fit out/rve_crystal_plasticity_fft --property tension.S11@3 # again, from the files
2075
+ ```
2076
+
2077
+ ### Parallel and cluster runs
2078
+
2079
+ Realizations are independent, and the seed of each one depends only on its place in
2080
+ the study: results do not depend on how a run is split.
2081
+
2082
+ ```bash
2083
+ morphogen run study.yaml -j 8 # 8 realizations at a time on this machine
2084
+ morphogen submit study.yaml --scheduler slurm --tasks 32 -j 4 --time 02:00:00 \
2085
+ --memory 16G --setup "module load python" --submit
2086
+ morphogen status out/study # realizations done and missing
2087
+ morphogen merge out/study # done by the merging job of 'submit'
2088
+ mpirun -n 64 morphogen run study.yaml --mpi # or one task per MPI rank (mpi4py)
2089
+ ```
2090
+
2091
+ `submit` writes a job array and a merging job for SLURM, PBS Pro, Torque, SGE, OAR or
2092
+ LSF, and with `--submit` submits both, the merging job waiting for the array. Each task
2093
+ runs `morphogen run --task-id auto` (the index of the array, read from the scheduler)
2094
+ with `--resume`: a task resubmitted after a time limit only runs the realizations
2095
+ without a record. A script that runs realizations in processes (`jobs > 1` in Python)
2096
+ must guard its entry point with `if __name__ == "__main__":`.
2097
+
2098
+ <!-- section: performance -->
2099
+ ## Performance
2100
+
2101
+ Generation and voxelization at 256³ voxels (16.8 M voxels), 4-core container,
2102
+ `python examples/benchmark.py 256`:
2103
+
2104
+ | Model | Setting | Voxelization |
2105
+ |---|---|---|
2106
+ | boolean_spheres | 5 452 spheres | 0.18 s |
2107
+ | boolean_cylinders | 1 657 fibres | 0.18 s |
2108
+ | poisson_fibers | 322 fibres | 0.13 s |
2109
+ | hardcore_spheres | 1 934 spheres, p = 0.3 | 0.14 s |
2110
+ | strut_lattice | octet, 3 300 struts | 0.18 s |
2111
+ | tpms | sheet gyroid, 125 cells | 0.39 s |
2112
+ | gaussian_excursion | 59 756 Fourier modes | 1.9 s |
2113
+ | voronoi / laguerre | 5 000 cells | 5.0 s / 6.3 s |
2114
+
2115
+ Memory goes mostly into the outputs: 1 byte per voxel for phase images (512³ = 134 MB),
2116
+ 4 bytes for labels and fields.
2117
+
2118
+ Lattice models, simulated on 128³ cells and voxelized at 256³ (same command):
2119
+
2120
+ | Model | Setting | Generation | Voxelization |
2121
+ |---|---|---|---|
2122
+ | cellular_automaton | annealing rule, 30 steps | 4.2 s | 0.8 s |
2123
+ | activator_inhibitor | 15 steps (FFT neighbourhood sums) | 1.1 s | 0.4 s |
2124
+ | reaction_diffusion | labyrinth, 4 000 steps | 14 s | 0.5 s |
2125
+ | nucleation_growth | site saturation, 4 850 grains, 20 Potts sweeps | 3.4 s | 0.5 s |
2126
+ | nucleation_growth | continuous nucleation, 1 157 grains | 1.8 s | 0.6 s |
2127
+ | aggregation | DLA, 20 clusters, 105 k particles | 16 s | 0.5 s |
2128
+ | tile_assembly | 16³ polarized blocks (wave function collapse) | 0.01 s | 0.4 s |
2129
+
2130
+ Polycrystal meshes (Voronoi, periodic; regularization at a quarter of the element size;
2131
+ MMG):
2132
+
2133
+ | Grains | Element size | Elements | Time | Quality (mean / 0.1 % quantile) |
2134
+ |---|---|---|---|---|
2135
+ | 30 | 0.08 | 27 500 | 2.6 s | 0.72 / 0.10 |
2136
+ | 100 | 0.05 | 108 000 | 9.5 s | 0.74 / 0.10 |
2137
+ | 300 | 0.04 | 212 000 | 20 s | 0.74 / 0.11 |
2138
+
2139
+ Topology optimization (`python examples/topology_optimization.py` and the templates):
2140
+ 48² planar cells in 10–20 s (150–300 iterations), 64² in about a minute, 24³ cells in
2141
+ about a minute (130 iterations).
2142
+
2143
+ Homogenization (`python examples/homogenization.py`, same container):
2144
+
2145
+ | Sample | Discretization | Meshing | Solve (per loading) |
2146
+ |---|---|---|---|
2147
+ | Boolean spheres, 6³, both phases | 96 k tetrahedra (P1), 43–56 k unknowns | 19 s | 0.7–3.3 s, 31–66 iterations |
2148
+ | sheet gyroid cell, solid only | 62 k tetrahedra (P2), 305 k unknowns | 72 s | 15–25 s, 50–80 iterations |
2149
+ | Voronoi mosaic, contrast 20 | 64³ voxels (FFT) | — | 3–3.5 s, 37–38 iterations |
2150
+
2151
+ The gyroid's stiffness comes out cubic to 0.01 % (normal–shear couplings below
2152
+ 10⁻⁴ C11), with its solid fraction within 0.6 % of the target.
2153
+
2154
+ FFT solvers on the GPU (`python examples/gpu_benchmark.py`; a laptop with an Intel
2155
+ i9-13900H, 20 threads, and an NVIDIA RTX 3000 Ada laptop GPU, 8 GB):
2156
+
2157
+ | Problem | Voxels | CPU | GPU |
2158
+ |---|---|---|---|
2159
+ | bulk modulus, Boolean spheres (30 %, contrast 10) | 64³ / 128³ / 192³ / 256³ | 1.4 / 11.1 / 38.6 / 103 s | 0.23 / 2.0 / 5.5 / 29 s |
2160
+ | crystal plasticity, 12 grains, 1 % in 10 steps | 24³ / 32³ / 48³ | 8.9 / 22 / 125 s | 5.6 / 10 / 44 s |
2161
+ | stiff spheres in a GTN matrix, tension to 1 % in 10 steps (`--porous`) | 32³ / 48³ / 64³ | 11.5 / 51 / 161 s | 4.8 / 15 / 46 s |
2162
+
2163
+ The linear solves are 5 to 7 times faster up to 192³ voxels (3.5 times at 256³); the
2164
+ loading paths of the polycrystal 1.6 to 2.8 times and those of the porous composite 2.4
2165
+ to 3.5 times, the integration of the behaviours on the GPU being bound by the double
2166
+ precision of this laptop GPU ([docs/theory.md](docs/theory.md), §35).
2167
+
2168
+ The behaviours of the integration points on the CPU
2169
+ (`python examples/behaviour_benchmark.py`, the same laptop, 20 threads): an increment
2170
+ in the middle of a loading, per point:
2171
+
2172
+ | Behaviour | Small strains | Finite strains |
2173
+ |---|---|---|
2174
+ | elasticity | 10 ns | 254 ns |
2175
+ | von Mises (Voce and Armstrong-Frederick hardenings) | 88 ns | 302 ns |
2176
+ | Hill's criterion (the same hardenings) | 345 ns | 542 ns |
2177
+ | Gurson-Tvergaard-Needleman, with a nucleation | 522 ns | 701 ns |
2178
+ | crystal plasticity, fcc (12 slip systems) | 1.4 µs | 2.6 µs |
2179
+
2180
+ An update of the points of 128³ voxels (2.1 M points) thus takes 0.2 s in a von Mises
2181
+ matrix and 1.1 s in a porous one; finite strains add the logarithmic strain and its
2182
+ tangent, about a quarter of a microsecond per point.
2183
+
2184
+ The study of the template `rve_poisson_fibers_fe` (25 realizations, KUBC and MBC, three
2185
+ properties) takes about 7 minutes in one process. Realizations are independent: run
2186
+ them in processes (`-j`) or in cluster job arrays (`morphogen submit`).
2187
+
2188
+ <!-- section: documentation -->
2189
+ ## Documentation
2190
+
2191
+ * [docs/tutorials.md](docs/tutorials.md): nine tutorials, the first eight in snippets
2192
+ that run in seconds to a minute and that the tests run —
2193
+ [a whole study](docs/tutorial.md) (generation, characterization, apparent properties
2194
+ and RVE size, a loading path, exports, a learned behaviour),
2195
+ [how large is a representative volume?](docs/tutorial_rve.md) (the statistics of the
2196
+ RVE on spheres and on Poisson fibres, windows, a study from a configuration),
2197
+ [a rubber, from its tests to its tearing](docs/tutorial_rubber.md) (finite strains),
2198
+ [exact geometry, from implicit functions to meshes](docs/tutorial_geometry.md),
2199
+ [isogeometric analysis, from a patch to an auxetic sheet](docs/tutorial_iga.md),
2200
+ [contact and damage](docs/tutorial_contact.md) (a block crushed and indented, the
2201
+ damage laws, a composite whose matrix fails),
2202
+ [how a microstructure breaks](docs/tutorial_fracture.md) (interfaces that debond, the
2203
+ fatigue of a pore, twins, cleavage and its probability),
2204
+ [from an orientation map to a textured polycrystal](docs/tutorial_texture.md) (an
2205
+ EBSD map, its grains and its texture, the lattices that a tension turns) and
2206
+ [a study in the graphical interface](docs/tutorial_interface.md); their figures are
2207
+ written by `docs/tutorials/make_figures.py` (which runs the snippets) and
2208
+ `docs/tutorials/make_screenshots.py` (which drives the interface).
2209
+ * [docs/howto.md](docs/howto.md): recipes, short answers to "how do I..." in snippets
2210
+ run by the tests; [docs/faq.md](docs/faq.md): questions and troubles (installing,
2211
+ units and phases, the messages of the solvers, the files of a run);
2212
+ [docs/glossary.md](docs/glossary.md): the words that have a precise meaning here.
2213
+ * [docs/gallery.md](docs/gallery.md): the gallery of examples, a card per template
2214
+ (written with its images by `docs/gallery/make_gallery.py`).
2215
+ * [docs/physics.md](docs/physics.md): a guide to the physics for researchers in the
2216
+ mechanics and physics of materials — every problem of the homogenization module
2217
+ (elasticity, transport, weak and strong couplings, harmonic regimes and waves,
2218
+ nonlinear behaviours, fracture), the solver for each, the dependence on the mesh and
2219
+ the size of the representative volume, in snippets run by the tests.
2220
+ * [docs/specification.md](docs/specification.md): specification (cahier des charges) —
2221
+ objectives, requirements, technical choices, roadmap, decisions.
2222
+ * [docs/architecture.md](docs/architecture.md): modules, data model, conventions,
2223
+ configuration schema, file formats, tests.
2224
+ * [docs/theory.md](docs/theory.md): formulas implemented and validated.
2225
+ * [docs/laser.md](docs/laser.md): architectured sheets by localized laser treatment —
2226
+ the choices of a study, the chain of models, its checks and first results.
2227
+ * [docs/stability.md](docs/stability.md): the public interface and its versioning;
2228
+ [docs/release.md](docs/release.md): the steps of a release; [CITATION.cff](CITATION.cff)
2229
+ and [docs/citing.md](docs/citing.md): how to cite morphoGen.
2230
+ * [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md).
2231
+ * The documentation site gathers these pages, this README and the API reference written
2232
+ from the docstrings, behind a landing page: `python -m pip install ".[docs]"`, then
2233
+ `python -m sphinx -b html docs site` (open `site/index.html`). Its pages copy their
2234
+ code blocks at a click, and its gallery filters its cards by words. The continuous
2235
+ integration builds it too and keeps it as the artifact `site` of each run.
2236
+
2237
+ <!-- section: development -->
2238
+ ## Development
2239
+
2240
+ ```bash
2241
+ python -m pip install -e ".[dev]"
2242
+ python -m pip install vtk gmsh # optional: independent readers of the exported files
2243
+ python -m pytest -n auto # 1900+ tests in parallel (pytest-xdist): about 25 minutes
2244
+ # on 4 cores
2245
+ python -m pytest -n auto -m "not slow" # the fast tier: about 10 minutes on 4 cores
2246
+ python tests/test_public_api.py # the list of the public interface written again,
2247
+ # after a change of it made on purpose
2248
+ ruff check src tests examples docs && ruff format --check src tests examples docs
2249
+ python -m sphinx -b html -W docs site # the documentation site, without warnings
2250
+ tools/ci_local.sh # the CI jobs of this machine's system, locally
2251
+ CI_LOCAL_PACKAGES="vtk gmsh" tools/ci_local.sh # the same with the VTK and Gmsh checks
2252
+ ```
2253
+
2254
+ The statistical tests compare every model with its theory, using fixed seeds and
2255
+ tolerances derived from that theory. The homogenization tests check exact solutions
2256
+ (homogeneous media, laminates, the bulk modulus of cubic polycrystals), the ordering of
2257
+ the boundary conditions and the agreement with scikit-fem. The phase-3 tests check automata against known patterns
2258
+ (gliders, blinkers), growth against the Avrami law and exact distances, exact counts
2259
+ against brute force, rigidity against Maxwell–Calladine, sensitivities against finite
2260
+ differences and optimized cells against the Hashin–Shtrikman bounds. Optional checks
2261
+ with VTK and Gmsh (their Python packages: VTK reads the `.vti` files, Gmsh the `.msh`
2262
+ meshes and meshes the `.geo` scripts) run when those packages are installed; the GitHub
2263
+ workflow does not install them. The GPU tests compare the solutions of both devices
2264
+ where CuPy finds a GPU, and the MFront tests morphoGen's behaviours with their MFront
2265
+ twins where MGIS and MFront are installed (in WSL on the development machine).
2266
+ Continuous integration runs the tests on Linux, Windows and macOS
2267
+ (`.github/workflows/ci.yml`); `tools/ci_local.sh` runs the jobs of the development
2268
+ machine's system (an environment per Python version, the tests against the built wheel,
2269
+ the command-line smoke test, the documentation site), for when GitHub Actions is not
2270
+ available. The Python versions run at once, each on its share of the cores
2271
+ (`CI_LOCAL_WORKERS` test processes per version); the slowest tests (marker `slow`,
2272
+ two thirds of the time) run under the last version only (`CI_LOCAL_SLOW`), which gets
2273
+ three times the cores of each other version, and the GitHub workflow runs them in its
2274
+ job Ubuntu with Python 3.14. An environment is kept from one run to the next while
2275
+ `pyproject.toml` does not change (`CI_LOCAL_FRESH=1` makes new ones). It runs in Git
2276
+ Bash on Windows. With uv it finds or installs
2277
+ Python 3.12 and 3.14; without uv it uses venv and pip, and takes the versions
2278
+ (`pythonX.Y` on the PATH or `py -X.Y`) or the paths of the interpreters:
2279
+ `tools/ci_local.sh /path/to/python3.12 /path/to/python3.14`. Changes go through pull
2280
+ requests to `main`.
2281
+
2282
+ <!-- section: references -->
2283
+ ## References
2284
+
2285
+ * Kanit, T., Forest, S., Galliet, I., Mounoury, V., Jeulin, D. (2003). *Int. J. Solids
2286
+ Struct.* 40, 3647–3679.
2287
+ * Dirrenberger, J., Forest, S., Jeulin, D. (2014). Towards gigantic RVE sizes for 3D
2288
+ stochastic fibrous networks. *Int. J. Solids Struct.* 51, 359–376.
2289
+ * Yang, S., Dirrenberger, J., Monteiro, E., Ranc, N. (2019). *Int. J. Solids Struct.*
2290
+ 158, 210–219.
2291
+ * Bironeau, A., Dirrenberger, J., Sollogoub, C., Miquelard-Garnier, G., Roland, S.
2292
+ (2016). *J. Microscopy* 264, 48–58.
2293
+ * Coulais, C., Teomy, E., de Reus, K., Shokef, Y., van Hecke, M. (2016). Combinatorial
2294
+ design of textured mechanical metamaterials. *Nature* 535, 529–532.
2295
+ * Hashin, Z., Shtrikman, S. (1962). A variational approach to the theory of the elastic
2296
+ behaviour of polycrystals. *J. Mech. Phys. Solids* 10, 343–352.
2297
+ * Jeulin, D. (1997). Dead leaves models: from space tessellation to random functions.
2298
+ In *Advances in Theory and Applications of Random Sets*, World Scientific, 137–156.
2299
+ * Sigmund, O. (1994). Materials with prescribed constitutive parameters: an inverse
2300
+ homogenization problem. *Int. J. Solids Struct.* 31, 2313–2329.
2301
+ * Tovar, A., Patel, N. M., Niebur, G. L., Sen, M., Renaud, J. E. (2006). Topology
2302
+ optimization using a hybrid cellular automaton method with local control rules.
2303
+ *J. Mech. Des.* 128, 1205–1216.
2304
+
2305
+ The formulas and the other references are in [docs/theory.md](docs/theory.md).
2306
+
2307
+ <!-- section: licence -->
2308
+ ## Licence
2309
+
2310
+ Copyright © 2026 Justin Dirrenberger.
2311
+
2312
+ morphoGen is free software: you can redistribute it and/or modify it under the terms of
2313
+ the GNU General Public License as published by the Free Software Foundation, either
2314
+ version 3 of the License, or (at your option) any later version. It is distributed in
2315
+ the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
2316
+ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See [LICENSE](https://github.com/jdirr/morphoGen/blob/main/LICENSE).