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,595 @@
1
+ """Force-biased packing of fibres, chains of spherocylinders (Altendorf & Jeulin 2011).
2
+
3
+ The fibres are chains of nodes in a periodic box ``[0, box)`` (unwrapped coordinates:
4
+ consecutive nodes of a chain are joined by a segment, the axis of a spherocylinder of the
5
+ radius of its fibre). At every step, three displacements ("forces", Altendorf & Jeulin
6
+ 2011, sec. II B) are computed from the current configuration and applied together:
7
+
8
+ * repulsion: two segments whose axes are closer than the sum of their radii plus ``gap``
9
+ (nearest periodic images) by ``δ`` are each pushed apart by ``δ/2`` along the line of
10
+ their closest points (Ericson 2005, sec. 5.1.9; the middle of the common span for
11
+ parallel segments), the push shared by the two nodes of a segment in proportion to the
12
+ barycentric weights of its closest point; segments of a fibre at most ``related``
13
+ steps apart along it are exempt (they touch at the joints);
14
+ * springs: a segment whose length departs from its rest length ``D0`` by ``ΔD`` moves
15
+ each of its nodes by ``f(|ΔD| / D0) ΔD`` along it, ``f`` the friction ramp of the paper,
16
+ 0 below 5 %, 1 above 10 % and a half cosine between;
17
+ * open angular springs: a joint more bent than at rest (its angle ``α`` below its rest
18
+ angle ``α0``) moves its node towards the chord of its two neighbours by
19
+ ``f(α0 - α) (z - z0)``, ``z`` its distance to the chord and ``z0`` the distance at which
20
+ the angle would be ``α0`` (ramp from 0.1 to 0.2 rad), or, folded beyond the chord (the
21
+ foot of the node outside it), by ``f`` times its distance to the middle of the chord;
22
+ straightened joints are free.
23
+
24
+ The total displacement of a node is the repulsion plus ``recovery`` (the paper's ε)
25
+ times the springs and angles, capped to ``max_move``. Segments are found in linked cells
26
+ at least as large as their reach, ``2 r_max + gap`` plus the longest segment.
27
+
28
+ The contact packing of Keilmann, Redenbach & Willot (2026) adds contact forces
29
+ (:func:`contact_pulls`): shortlisted pairs of segments of different fibres (found by
30
+ :func:`near_pairs`) farther apart than in contact are drawn together, the complement of
31
+ the repulsions (:func:`pack_contacts`).
32
+
33
+ Before the packing, the chains may be placed one after another where they overlap the
34
+ chains already placed the least (:func:`place`), the initial placement of Altendorf,
35
+ Jeulin & Willot (2014, sec. 2.3), which shortens the packing.
36
+ """
37
+
38
+ from __future__ import annotations
39
+
40
+ import math
41
+
42
+ import numpy as np
43
+ from numba import njit
44
+
45
+ #: Friction ramps of the recovery forces (Altendorf & Jeulin 2011): relative change of
46
+ #: length of a segment, deviation of the angle of a joint (radians), from no force to all
47
+ SPRING_RAMP = (0.05, 0.10)
48
+ ANGLE_RAMP = (0.1, 0.2)
49
+
50
+
51
+ @njit(cache=True, inline="always")
52
+ def _clamp(x):
53
+ return 0.0 if x < 0.0 else (1.0 if x > 1.0 else x)
54
+
55
+
56
+ @njit(cache=True, inline="always")
57
+ def _ramp(x, lo, hi):
58
+ """The friction factor: 0 below ``lo``, 1 above ``hi``, a half cosine between."""
59
+ if x <= lo:
60
+ return 0.0
61
+ if x >= hi:
62
+ return 1.0
63
+ return 0.5 - 0.5 * math.cos(math.pi * (x - lo) / (hi - lo))
64
+
65
+
66
+ @njit(cache=True, inline="always")
67
+ def _closest(rx, ry, rz, ax, ay, az, bx, by, bz):
68
+ """Parameters ``(s, t)`` in [0, 1] of the closest points of the segments ``p + s a``
69
+ and ``q + t b``, ``r = p - q`` (Ericson 2005, sec. 5.1.9); for (nearly) parallel
70
+ segments, the middle of the span of ``a`` facing ``b``."""
71
+ A = ax * ax + ay * ay + az * az
72
+ E = bx * bx + by * by + bz * bz
73
+ F = bx * rx + by * ry + bz * rz
74
+ if A <= 1e-300 and E <= 1e-300:
75
+ return 0.0, 0.0
76
+ if A <= 1e-300:
77
+ return 0.0, _clamp(F / E)
78
+ C = ax * rx + ay * ry + az * rz
79
+ if E <= 1e-300:
80
+ return _clamp(-C / A), 0.0
81
+ B = ax * bx + ay * by + az * bz
82
+ den = A * E - B * B
83
+ if den > 1e-9 * A * E:
84
+ s = _clamp((B * F - C * E) / den)
85
+ else:
86
+ s = 0.5 * (_clamp(-C / A) + _clamp((B - C) / A))
87
+ t = (B * s + F) / E
88
+ if t < 0.0:
89
+ t, s = 0.0, _clamp(-C / A)
90
+ elif t > 1.0:
91
+ t, s = 1.0, _clamp((B - C) / A)
92
+ return s, t
93
+
94
+
95
+ @njit(cache=True, inline="always")
96
+ def _share(push, node, g, wx, wy, wz):
97
+ push[node, 0] += g * wx
98
+ push[node, 1] += g * wy
99
+ push[node, 2] += g * wz
100
+
101
+
102
+ @njit(cache=True)
103
+ def _reach(x, seg_node, radius, gap):
104
+ """Largest radius and largest length of a segment, and the size of the cells."""
105
+ longest = 0.0
106
+ for s in range(seg_node.shape[0]):
107
+ a = seg_node[s]
108
+ d2 = 0.0
109
+ for k in range(3):
110
+ d = x[a + 1, k] - x[a, k]
111
+ d2 += d * d
112
+ longest = max(longest, math.sqrt(d2))
113
+ return 2.0 * radius.max() + gap + longest
114
+
115
+
116
+ @njit(cache=True)
117
+ def _cells(x, seg_node, box, size):
118
+ """Linked cells at least ``size`` wide over the segments: their numbers along the
119
+ axes, the heads and links of their lists, and the vectors, wrapped midpoints, half
120
+ lengths and cells of the segments."""
121
+ n_seg = seg_node.shape[0]
122
+ cell_n = np.empty(3, np.int64)
123
+ cell_h = np.empty(3)
124
+ for k in range(3):
125
+ cell_n[k] = max(1, int(box[k] / size))
126
+ cell_h[k] = box[k] / cell_n[k]
127
+ head = np.full(cell_n[0] * cell_n[1] * cell_n[2], -1, np.int64)
128
+ nxt = np.empty(n_seg, np.int64)
129
+ mid = np.empty((n_seg, 3))
130
+ vec = np.empty((n_seg, 3))
131
+ half = np.empty(n_seg)
132
+ cell = np.empty((n_seg, 3), np.int64)
133
+ for s in range(n_seg):
134
+ a = seg_node[s]
135
+ d2 = 0.0
136
+ for k in range(3):
137
+ d = x[a + 1, k] - x[a, k]
138
+ vec[s, k] = d
139
+ d2 += d * d
140
+ m = x[a, k] + 0.5 * d
141
+ m -= box[k] * math.floor(m / box[k])
142
+ mid[s, k] = m
143
+ cell[s, k] = min(int(m / cell_h[k]), cell_n[k] - 1)
144
+ half[s] = 0.5 * math.sqrt(d2)
145
+ c = (cell[s, 0] * cell_n[1] + cell[s, 1]) * cell_n[2] + cell[s, 2]
146
+ nxt[s] = head[c]
147
+ head[c] = s
148
+ return cell_n, head, nxt, mid, vec, half, cell
149
+
150
+
151
+ @njit(cache=True)
152
+ def overlaps(x, seg_node, seg_fibre, seg_index, radius, related, box, gap, push, worst):
153
+ """One pass over the pairs of segments closer than ``r_a + r_b + gap`` (nearest
154
+ periodic images; same-fibre pairs at most ``related[fibre]`` steps apart skipped):
155
+ their repulsions added to ``push`` (nodes x 3; none if it has no rows) and the
156
+ largest such ``δ`` of each fibre kept in ``worst``. Returns the largest ``δ`` (0
157
+ without overlaps) and the number of overlapping pairs."""
158
+ n_seg = seg_node.shape[0]
159
+ size = _reach(x, seg_node, radius, gap)
160
+ cell_n, head, nxt, mid, vec, half, cell = _cells(x, seg_node, box, size)
161
+ ni, nj, nk = min(3, cell_n[0]), min(3, cell_n[1]), min(3, cell_n[2])
162
+ forces = push.shape[0] > 0
163
+ largest = 0.0
164
+ count = 0
165
+ for s in range(n_seg):
166
+ a = seg_node[s]
167
+ fs = seg_fibre[s]
168
+ rs = radius[fs]
169
+ ax, ay, az = vec[s, 0], vec[s, 1], vec[s, 2]
170
+ for di in range(ni):
171
+ ii = (cell[s, 0] + di - 1) % cell_n[0] if ni == 3 else di
172
+ for dj in range(nj):
173
+ jj = (cell[s, 1] + dj - 1) % cell_n[1] if nj == 3 else dj
174
+ for dk in range(nk):
175
+ kk = (cell[s, 2] + dk - 1) % cell_n[2] if nk == 3 else dk
176
+ t = head[(ii * cell_n[1] + jj) * cell_n[2] + kk]
177
+ while t >= 0:
178
+ if t > s:
179
+ ft = seg_fibre[t]
180
+ near = ft == fs and abs(seg_index[t] - seg_index[s]) <= related[fs]
181
+ lim = rs + radius[ft] + gap
182
+ mx = mid[t, 0] - mid[s, 0]
183
+ my = mid[t, 1] - mid[s, 1]
184
+ mz = mid[t, 2] - mid[s, 2]
185
+ mx -= box[0] * math.floor(mx / box[0] + 0.5)
186
+ my -= box[1] * math.floor(my / box[1] + 0.5)
187
+ mz -= box[2] * math.floor(mz / box[2] + 0.5)
188
+ reach = lim + half[s] + half[t]
189
+ if not near and mx * mx + my * my + mz * mz < reach * reach:
190
+ bx, by, bz = vec[t, 0], vec[t, 1], vec[t, 2]
191
+ # r = p - q, p and q the starts of s and of the image of t
192
+ rx = -mx - 0.5 * ax + 0.5 * bx
193
+ ry = -my - 0.5 * ay + 0.5 * by
194
+ rz = -mz - 0.5 * az + 0.5 * bz
195
+ u, v = _closest(rx, ry, rz, ax, ay, az, bx, by, bz)
196
+ wx = rx + u * ax - v * bx
197
+ wy = ry + u * ay - v * by
198
+ wz = rz + u * az - v * bz
199
+ d = math.sqrt(wx * wx + wy * wy + wz * wz)
200
+ if d < lim:
201
+ delta = lim - d
202
+ count += 1
203
+ largest = max(largest, delta)
204
+ worst[fs] = max(worst[fs], delta)
205
+ worst[ft] = max(worst[ft], delta)
206
+ if forces:
207
+ if d <= 1e-12 * lim: # crossing axes
208
+ wx = ay * bz - az * by
209
+ wy = az * bx - ax * bz
210
+ wz = ax * by - ay * bx
211
+ d = math.sqrt(wx * wx + wy * wy + wz * wz)
212
+ if d <= 1e-300: # parallel too
213
+ wx, wy, wz = -ay - az, ax - az, ax + ay
214
+ d = math.sqrt(wx * wx + wy * wy + wz * wz)
215
+ g = 0.5 * delta / d
216
+ b = seg_node[t]
217
+ _share(push, a, (1.0 - u) * g, wx, wy, wz)
218
+ _share(push, a + 1, u * g, wx, wy, wz)
219
+ _share(push, b, (v - 1.0) * g, wx, wy, wz)
220
+ _share(push, b + 1, -v * g, wx, wy, wz)
221
+ t = nxt[t]
222
+ return largest, count
223
+
224
+
225
+ @njit(cache=True)
226
+ def near_pairs(x, seg_node, seg_fibre, radius, box, gap):
227
+ """The pairs of segments of different fibres whose axes are closer than ``r_a + r_b +
228
+ gap`` (nearest periodic images): the indices ``s < t`` and the distances."""
229
+ n_seg = seg_node.shape[0]
230
+ size = _reach(x, seg_node, radius, gap)
231
+ cell_n, head, nxt, mid, vec, half, cell = _cells(x, seg_node, box, size)
232
+ ni, nj, nk = min(3, cell_n[0]), min(3, cell_n[1]), min(3, cell_n[2])
233
+ found_s = np.empty(64, np.int64)
234
+ found_t = np.empty(64, np.int64)
235
+ found_d = np.empty(64)
236
+ count = 0
237
+ for s in range(n_seg):
238
+ fs = seg_fibre[s]
239
+ ax, ay, az = vec[s, 0], vec[s, 1], vec[s, 2]
240
+ for di in range(ni):
241
+ ii = (cell[s, 0] + di - 1) % cell_n[0] if ni == 3 else di
242
+ for dj in range(nj):
243
+ jj = (cell[s, 1] + dj - 1) % cell_n[1] if nj == 3 else dj
244
+ for dk in range(nk):
245
+ kk = (cell[s, 2] + dk - 1) % cell_n[2] if nk == 3 else dk
246
+ t = head[(ii * cell_n[1] + jj) * cell_n[2] + kk]
247
+ while t >= 0:
248
+ if t > s and seg_fibre[t] != fs:
249
+ lim = radius[fs] + radius[seg_fibre[t]] + gap
250
+ mx = mid[t, 0] - mid[s, 0]
251
+ my = mid[t, 1] - mid[s, 1]
252
+ mz = mid[t, 2] - mid[s, 2]
253
+ mx -= box[0] * math.floor(mx / box[0] + 0.5)
254
+ my -= box[1] * math.floor(my / box[1] + 0.5)
255
+ mz -= box[2] * math.floor(mz / box[2] + 0.5)
256
+ reach = lim + half[s] + half[t]
257
+ if mx * mx + my * my + mz * mz < reach * reach:
258
+ bx, by, bz = vec[t, 0], vec[t, 1], vec[t, 2]
259
+ rx = -mx - 0.5 * ax + 0.5 * bx
260
+ ry = -my - 0.5 * ay + 0.5 * by
261
+ rz = -mz - 0.5 * az + 0.5 * bz
262
+ u, v = _closest(rx, ry, rz, ax, ay, az, bx, by, bz)
263
+ wx = rx + u * ax - v * bx
264
+ wy = ry + u * ay - v * by
265
+ wz = rz + u * az - v * bz
266
+ d = math.sqrt(wx * wx + wy * wy + wz * wz)
267
+ if d < lim:
268
+ if count == found_s.shape[0]: # grown by doubling
269
+ found_s = np.concatenate((found_s, np.empty_like(found_s)))
270
+ found_t = np.concatenate((found_t, np.empty_like(found_t)))
271
+ found_d = np.concatenate((found_d, np.empty_like(found_d)))
272
+ found_s[count], found_t[count], found_d[count] = s, t, d
273
+ count += 1
274
+ t = nxt[t]
275
+ return found_s[:count].copy(), found_t[:count].copy(), found_d[:count].copy()
276
+
277
+
278
+ @njit(cache=True)
279
+ def place(x, first, radius, box, gap, shifts):
280
+ """The initial placement of least overlap: the chains ``x`` (each from its first node,
281
+ moved in place) translated one after another by the best of their candidate
282
+ ``shifts`` (fibres x trials x 3), the one whose segments overlap those of the chains
283
+ already placed the least (the sum of the depths ``δ`` of the pairs closer than ``r_a +
284
+ r_b + gap``, nearest periodic images; a trial stopped once it exceeds the best, the
285
+ first without overlap taken at once). Returns the sum of the depths of the overlaps
286
+ left, each pair counted once."""
287
+ n = first.shape[0] - 1
288
+ n_seg = x.shape[0] - n
289
+ longest = 0.0
290
+ for f in range(n):
291
+ for a in range(first[f], first[f + 1] - 1):
292
+ d2 = 0.0
293
+ for k in range(3):
294
+ d = x[a + 1, k] - x[a, k]
295
+ d2 += d * d
296
+ longest = max(longest, math.sqrt(d2))
297
+ size = 2.0 * radius.max() + gap + longest
298
+ cell_n = np.empty(3, np.int64)
299
+ cell_h = np.empty(3)
300
+ for k in range(3):
301
+ cell_n[k] = max(1, int(box[k] / size))
302
+ cell_h[k] = box[k] / cell_n[k]
303
+ ni, nj, nk = min(3, cell_n[0]), min(3, cell_n[1]), min(3, cell_n[2])
304
+ head = np.full(cell_n[0] * cell_n[1] * cell_n[2], -1, np.int64)
305
+ nxt = np.empty(n_seg, np.int64)
306
+ mid = np.empty((n_seg, 3))
307
+ vec = np.empty((n_seg, 3))
308
+ half = np.empty(n_seg)
309
+ fibre = np.empty(n_seg, np.int64)
310
+ m = np.empty(3)
311
+ c = np.empty(3, np.int64)
312
+ placed = 0
313
+ total = 0.0
314
+ for f in range(n):
315
+ lo, hi = first[f], first[f + 1]
316
+ best, best_t = np.inf, 0
317
+ for t in range(shifts.shape[1]):
318
+ score = 0.0
319
+ for a in range(lo, hi - 1):
320
+ ax, ay, az = x[a + 1, 0] - x[a, 0], x[a + 1, 1] - x[a, 1], x[a + 1, 2] - x[a, 2]
321
+ hs = 0.5 * math.sqrt(ax * ax + ay * ay + az * az)
322
+ m[0] = x[a, 0] + 0.5 * ax + shifts[f, t, 0]
323
+ m[1] = x[a, 1] + 0.5 * ay + shifts[f, t, 1]
324
+ m[2] = x[a, 2] + 0.5 * az + shifts[f, t, 2]
325
+ for k in range(3):
326
+ m[k] -= box[k] * math.floor(m[k] / box[k])
327
+ c[k] = min(int(m[k] / cell_h[k]), cell_n[k] - 1)
328
+ for di in range(ni):
329
+ ii = (c[0] + di - 1) % cell_n[0] if ni == 3 else di
330
+ for dj in range(nj):
331
+ jj = (c[1] + dj - 1) % cell_n[1] if nj == 3 else dj
332
+ for dk in range(nk):
333
+ kk = (c[2] + dk - 1) % cell_n[2] if nk == 3 else dk
334
+ q = head[(ii * cell_n[1] + jj) * cell_n[2] + kk]
335
+ while q >= 0:
336
+ lim = radius[f] + radius[fibre[q]] + gap
337
+ mx = mid[q, 0] - m[0]
338
+ my = mid[q, 1] - m[1]
339
+ mz = mid[q, 2] - m[2]
340
+ mx -= box[0] * math.floor(mx / box[0] + 0.5)
341
+ my -= box[1] * math.floor(my / box[1] + 0.5)
342
+ mz -= box[2] * math.floor(mz / box[2] + 0.5)
343
+ reach = lim + hs + half[q]
344
+ if mx * mx + my * my + mz * mz < reach * reach:
345
+ bx, by, bz = vec[q, 0], vec[q, 1], vec[q, 2]
346
+ rx = -mx - 0.5 * ax + 0.5 * bx
347
+ ry = -my - 0.5 * ay + 0.5 * by
348
+ rz = -mz - 0.5 * az + 0.5 * bz
349
+ u, v = _closest(rx, ry, rz, ax, ay, az, bx, by, bz)
350
+ wx = rx + u * ax - v * bx
351
+ wy = ry + u * ay - v * by
352
+ wz = rz + u * az - v * bz
353
+ d = math.sqrt(wx * wx + wy * wy + wz * wz)
354
+ if d < lim:
355
+ score += lim - d
356
+ q = nxt[q]
357
+ if score >= best:
358
+ break
359
+ if score < best:
360
+ best, best_t = score, t
361
+ if best <= 0.0:
362
+ break
363
+ total += best
364
+ for a in range(lo, hi): # moved to the best position, its segments then listed
365
+ for k in range(3):
366
+ x[a, k] += shifts[f, best_t, k]
367
+ for a in range(lo, hi - 1):
368
+ d2 = 0.0
369
+ for k in range(3):
370
+ d = x[a + 1, k] - x[a, k]
371
+ vec[placed, k] = d
372
+ d2 += d * d
373
+ mk = x[a, k] + 0.5 * d
374
+ mk -= box[k] * math.floor(mk / box[k])
375
+ mid[placed, k] = mk
376
+ c[k] = min(int(mk / cell_h[k]), cell_n[k] - 1)
377
+ half[placed] = 0.5 * math.sqrt(d2)
378
+ fibre[placed] = f
379
+ cell = (c[0] * cell_n[1] + c[1]) * cell_n[2] + c[2]
380
+ nxt[placed] = head[cell]
381
+ head[cell] = placed
382
+ placed += 1
383
+ return total
384
+
385
+
386
+ @njit(cache=True)
387
+ def contact_pulls(x, seg_node, pair_s, pair_t, active, lim, box, smooth, weight, pull):
388
+ """The contact forces of Keilmann et al. (2026, eqs. 20-22) on the active pairs of
389
+ segments, added to ``pull``: two segments farther apart than ``lim`` (that pair's
390
+ ``r_a + r_b + gap + epsilon``) by ``e > 0`` are each drawn ``weight f(e) e / 2`` towards
391
+ the other along the line of their closest points (nearest periodic images), ``f`` the
392
+ friction ramp from 0 at ``e = 0`` to 1 at ``smooth`` (1 if 0), the pull shared by the
393
+ nodes of a segment as the repulsions are."""
394
+ for p in range(pair_s.shape[0]):
395
+ if not active[p]:
396
+ continue
397
+ a, b = seg_node[pair_s[p]], seg_node[pair_t[p]]
398
+ ax, ay, az = x[a + 1, 0] - x[a, 0], x[a + 1, 1] - x[a, 1], x[a + 1, 2] - x[a, 2]
399
+ bx, by, bz = x[b + 1, 0] - x[b, 0], x[b + 1, 1] - x[b, 1], x[b + 1, 2] - x[b, 2]
400
+ mx = x[b, 0] + 0.5 * bx - x[a, 0] - 0.5 * ax
401
+ my = x[b, 1] + 0.5 * by - x[a, 1] - 0.5 * ay
402
+ mz = x[b, 2] + 0.5 * bz - x[a, 2] - 0.5 * az
403
+ mx -= box[0] * math.floor(mx / box[0] + 0.5)
404
+ my -= box[1] * math.floor(my / box[1] + 0.5)
405
+ mz -= box[2] * math.floor(mz / box[2] + 0.5)
406
+ rx = -mx - 0.5 * ax + 0.5 * bx
407
+ ry = -my - 0.5 * ay + 0.5 * by
408
+ rz = -mz - 0.5 * az + 0.5 * bz
409
+ u, v = _closest(rx, ry, rz, ax, ay, az, bx, by, bz)
410
+ wx = rx + u * ax - v * bx # from the closest point of b to that of a
411
+ wy = ry + u * ay - v * by
412
+ wz = rz + u * az - v * bz
413
+ d = math.sqrt(wx * wx + wy * wy + wz * wz)
414
+ e = d - lim[p]
415
+ if e <= 0.0:
416
+ continue
417
+ g = 0.5 * weight * e / d * (_ramp(e, 0.0, smooth) if smooth > 0.0 else 1.0)
418
+ _share(pull, a, -(1.0 - u) * g, wx, wy, wz)
419
+ _share(pull, a + 1, -u * g, wx, wy, wz)
420
+ _share(pull, b, (1.0 - v) * g, wx, wy, wz)
421
+ _share(pull, b + 1, v * g, wx, wy, wz)
422
+
423
+
424
+ @njit(cache=True, inline="always")
425
+ def _rest_distance(h1, h2, angle):
426
+ """Distance ``z0`` of a node to the chord of its neighbours (whose foot is at the
427
+ distances ``h1`` and ``h2`` from them) at which the angle of the joint is ``angle``:
428
+ the positive root of ``z² - (h1 + h2) cot(angle) z - h1 h2 = 0`` (0 for a straight
429
+ rest angle)."""
430
+ if angle >= math.pi - 1e-12:
431
+ return 0.0
432
+ b = (h1 + h2) * math.cos(angle) / math.sin(angle)
433
+ disc = math.sqrt(b * b + 4.0 * h1 * h2)
434
+ return 0.5 * (b + disc) if b >= 0.0 else 2.0 * h1 * h2 / (disc - b)
435
+
436
+
437
+ @njit(cache=True)
438
+ def recoveries(x, first, rest, rest_angle, out):
439
+ """The spring and open angular spring displacements of the nodes, added to ``out``."""
440
+ d_lo, d_hi = SPRING_RAMP
441
+ a_lo, a_hi = ANGLE_RAMP
442
+ for f in range(first.shape[0] - 1):
443
+ lo, hi = first[f], first[f + 1]
444
+ for a in range(lo, hi - 1):
445
+ s = a - f # the segments of fibre f follow those of the previous fibres
446
+ vx, vy, vz = x[a, 0] - x[a + 1, 0], x[a, 1] - x[a + 1, 1], x[a, 2] - x[a + 1, 2]
447
+ length = math.sqrt(vx * vx + vy * vy + vz * vz)
448
+ change = rest[s] - length
449
+ g = _ramp(abs(change) / rest[s], d_lo, d_hi)
450
+ if g > 0.0 and length > 0.0:
451
+ g *= change / length
452
+ out[a, 0] += g * vx
453
+ out[a, 1] += g * vy
454
+ out[a, 2] += g * vz
455
+ out[a + 1, 0] -= g * vx
456
+ out[a + 1, 1] -= g * vy
457
+ out[a + 1, 2] -= g * vz
458
+ for p in range(lo + 1, hi - 1):
459
+ e1x, e1y, e1z = x[p - 1, 0] - x[p, 0], x[p - 1, 1] - x[p, 1], x[p - 1, 2] - x[p, 2]
460
+ e2x, e2y, e2z = x[p + 1, 0] - x[p, 0], x[p + 1, 1] - x[p, 1], x[p + 1, 2] - x[p, 2]
461
+ n1 = math.sqrt(e1x * e1x + e1y * e1y + e1z * e1z)
462
+ n2 = math.sqrt(e2x * e2x + e2y * e2y + e2z * e2z)
463
+ if n1 <= 0.0 or n2 <= 0.0:
464
+ continue
465
+ cos = (e1x * e2x + e1y * e2y + e1z * e2z) / (n1 * n2)
466
+ deviation = rest_angle[p] - math.acos(max(-1.0, min(1.0, cos)))
467
+ if deviation <= a_lo:
468
+ continue
469
+ cx, cy, cz = e2x - e1x, e2y - e1y, e2z - e1z # the chord q1 -> q2
470
+ lc = math.sqrt(cx * cx + cy * cy + cz * cz)
471
+ if lc <= 0.0:
472
+ continue
473
+ cx, cy, cz = cx / lc, cy / lc, cz / lc
474
+ h1 = -(e1x * cx + e1y * cy + e1z * cz) # foot of the node: q1 + h1 c
475
+ h2 = lc - h1
476
+ g = _ramp(deviation, a_lo, a_hi)
477
+ if h1 <= 0.0 or h2 <= 0.0: # folded beyond the chord: towards its middle
478
+ out[p, 0] += 0.5 * g * (e1x + e2x)
479
+ out[p, 1] += 0.5 * g * (e1y + e2y)
480
+ out[p, 2] += 0.5 * g * (e1z + e2z)
481
+ continue
482
+ wx, wy, wz = e1x + h1 * cx, e1y + h1 * cy, e1z + h1 * cz # node -> foot
483
+ z = math.sqrt(wx * wx + wy * wy + wz * wz)
484
+ z0 = _rest_distance(h1, h2, rest_angle[p])
485
+ if z > z0 and z > 1e-14 * lc:
486
+ g *= (z - z0) / z
487
+ out[p, 0] += g * wx
488
+ out[p, 1] += g * wy
489
+ out[p, 2] += g * wz
490
+
491
+
492
+ @njit(cache=True)
493
+ def _step(x, push, seg_node, rest, max_move):
494
+ """Moves the nodes by their displacements capped to ``max_move``, then shortens to
495
+ its rest length about its middle a segment stretched beyond twice that length."""
496
+ for i in range(x.shape[0]):
497
+ norm = math.sqrt(push[i, 0] ** 2 + push[i, 1] ** 2 + push[i, 2] ** 2)
498
+ scale = max_move / norm if norm > max_move else 1.0
499
+ for k in range(3):
500
+ x[i, k] += scale * push[i, k]
501
+ for s in range(seg_node.shape[0]):
502
+ a = seg_node[s]
503
+ dx, dy, dz = x[a + 1, 0] - x[a, 0], x[a + 1, 1] - x[a, 1], x[a + 1, 2] - x[a, 2]
504
+ d = math.sqrt(dx * dx + dy * dy + dz * dz)
505
+ if d > 2.0 * rest[s]:
506
+ g = 0.5 - rest[s] / d
507
+ x[a, 0] += g * dx
508
+ x[a, 1] += g * dy
509
+ x[a, 2] += g * dz
510
+ x[a + 1, 0] -= g * dx
511
+ x[a + 1, 1] -= g * dy
512
+ x[a + 1, 2] -= g * dz
513
+
514
+
515
+ @njit(cache=True)
516
+ def pack(x, first, seg_node, seg_fibre, seg_index, radius, related, rest, rest_angle, box,
517
+ gap, recovery, max_move, force_tol, overlap_tol, max_steps, repulsion_only): # fmt: skip
518
+ """Force-biased steps on the nodes ``x`` (moved in place) until the largest overlap
519
+ falls to ``overlap_tol`` and the total force (the sum of the lengths of the
520
+ displacements before capping) to ``force_tol``, or, with ``repulsion_only`` (the end
521
+ step: repulsions alone), the overlap alone; at most ``max_steps`` steps. A segment
522
+ stretched beyond twice its rest length after a step is shortened to it about its
523
+ middle (a fraction out of reach tears the fibres apart, which would swell the cells).
524
+ Returns the number of steps, the total force and the largest overlap ``δ`` of the last
525
+ configuration."""
526
+ n = x.shape[0]
527
+ push = np.zeros((n, 3))
528
+ back = np.zeros((n, 3))
529
+ worst = np.zeros(radius.shape[0])
530
+ steps = 0
531
+ while True:
532
+ push[:] = 0.0
533
+ largest, _ = overlaps(
534
+ x, seg_node, seg_fibre, seg_index, radius, related, box, gap, push, worst
535
+ )
536
+ if not repulsion_only:
537
+ back[:] = 0.0
538
+ recoveries(x, first, rest, rest_angle, back)
539
+ total = 0.0
540
+ for i in range(n):
541
+ fx = push[i, 0] + recovery * back[i, 0]
542
+ fy = push[i, 1] + recovery * back[i, 1]
543
+ fz = push[i, 2] + recovery * back[i, 2]
544
+ norm = math.sqrt(fx * fx + fy * fy + fz * fz)
545
+ total += norm
546
+ push[i, 0], push[i, 1], push[i, 2] = fx, fy, fz
547
+ done = largest <= overlap_tol and (repulsion_only or total <= force_tol)
548
+ if done or steps >= max_steps:
549
+ return steps, total, largest
550
+ _step(x, push, seg_node, rest, max_move)
551
+ steps += 1
552
+
553
+
554
+ @njit(cache=True)
555
+ def pack_contacts(x, first, seg_node, seg_fibre, seg_index, radius, related, rest, rest_angle,
556
+ box, gap, recovery, max_move, pair_s, pair_t, active, lim, smooth, weight,
557
+ rel_tol, max_steps, force): # fmt: skip
558
+ """The contact packing of Keilmann et al. (2026, eq. 23, Algorithm 1): force-biased
559
+ steps whose displacements are the repulsions, ``recovery`` times the springs and
560
+ angles and the contact pulls of the active pairs (weighted by ``weight`` in
561
+ :func:`contact_pulls`), until the total force changes over a step by less than
562
+ ``rel_tol`` of itself (the paper's 0.001 %) or vanishes, at most ``max_steps`` steps.
563
+ ``force`` receives the length of the displacement of each node in the last
564
+ configuration. Returns the number of steps, the total force and the largest
565
+ overlap."""
566
+ n = x.shape[0]
567
+ push = np.zeros((n, 3))
568
+ back = np.zeros((n, 3))
569
+ pull = np.zeros((n, 3))
570
+ worst = np.zeros(radius.shape[0])
571
+ steps = 0
572
+ previous = np.inf
573
+ while True:
574
+ push[:] = 0.0
575
+ largest, _ = overlaps(
576
+ x, seg_node, seg_fibre, seg_index, radius, related, box, gap, push, worst
577
+ )
578
+ back[:] = 0.0
579
+ recoveries(x, first, rest, rest_angle, back)
580
+ pull[:] = 0.0
581
+ contact_pulls(x, seg_node, pair_s, pair_t, active, lim, box, smooth, weight, pull)
582
+ total = 0.0
583
+ for i in range(n):
584
+ fx = push[i, 0] + recovery * back[i, 0] + pull[i, 0]
585
+ fy = push[i, 1] + recovery * back[i, 1] + pull[i, 1]
586
+ fz = push[i, 2] + recovery * back[i, 2] + pull[i, 2]
587
+ force[i] = math.sqrt(fx * fx + fy * fy + fz * fz)
588
+ total += force[i]
589
+ push[i, 0], push[i, 1], push[i, 2] = fx, fy, fz
590
+ stalled = abs(previous - total) < rel_tol * previous
591
+ if steps >= max_steps or stalled or total <= 1e-12 * max_move * n:
592
+ return steps, total, largest
593
+ previous = total
594
+ _step(x, push, seg_node, rest, max_move)
595
+ steps += 1