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,507 @@
1
+ """Bloch waves in periodic cells: the dispersion of elastic, acoustic and electromagnetic
2
+ waves and the band gaps of architected materials (phononic, sonic and photonic crystals).
3
+
4
+ A Bloch wave ``u(x) = û(x) exp(i k·x)``, ``û`` periodic, is a free vibration of the
5
+ periodic medium at the wave vector ``k``. On a cell meshed by tetrahedra (the finite
6
+ elements of :mod:`morphogen.homogenization.fe`, 4 or 10 nodes),
7
+ ``u(x + n∘L) = u(x) exp(i k·(n∘L))`` ties each node of the upper faces to its image on
8
+ the lower ones: ``w = T(k) w_masters``, the periodic map of the fluctuations, each of
9
+ its weights times the phase of the period between the node and that master. The angular
10
+ frequencies ``ω`` are those of the Hermitian problem ``T^H K T φ = ω² T^H M T φ`` (the
11
+ stiffness ``K`` and the consistent mass ``M`` of the cell), the lowest found by
12
+ shift-invert Lanczos on its real form of twice the size (each frequency twice). Along
13
+ the edges of the irreducible Brillouin zone (Γ–X–M–Γ–R for a cubic cell) the bands give
14
+ the dispersion; a range between two bands free of waves along the path is a band gap
15
+ (complete if the path holds the extrema of the bands, as for most cells of cubic
16
+ symmetry).
17
+
18
+ **Scalar waves.** A field ``u`` that obeys ``div(a grad u) + ω² b u = 0`` has the same
19
+ Bloch problem with one unknown per node, the "stiffness" of the coefficient ``a`` and the
20
+ "mass" of ``b`` (:func:`scalar_band_structure`). :data:`SCALAR_WAVES` names those of the
21
+ materials (:func:`wave_coefficients`):
22
+
23
+ ============== ======================= ================ ================
24
+ waves field ``u`` ``a`` ``b``
25
+ ============== ======================= ================ ================
26
+ ``acoustic`` pressure of a fluid ``1 / rho`` ``1 / K``
27
+ ``shear`` antiplane displacement ``mu`` ``rho``
28
+ ``tm`` electric field ``E_z`` ``1 / mu_m`` ``epsilon``
29
+ ``te`` magnetic field ``H_z`` ``1 / epsilon`` ``mu_m``
30
+ ============== ======================= ================ ================
31
+
32
+ (``rho``: density, ``K``: bulk modulus, ``mu``: shear modulus, ``epsilon``: permittivity,
33
+ ``mu_m``: magnetic permeability). The antiplane shear waves and the two polarizations of
34
+ the electromagnetic waves are those of a medium invariant along the third axis (a cell
35
+ one voxel thick) for wave vectors in its plane: the photonic crystals of rods and of
36
+ holes. In three dimensions the shear waves are those of the elastic solid (``"elastic"``)
37
+ and the electromagnetic waves are vector waves, ``curl(curl H / epsilon) = ω² mu_m H``,
38
+ solved by plane waves on the voxels of an image (``"electromagnetic"``,
39
+ :mod:`morphogen.homogenization.photonic`): the photonic crystals of spheres, of rods
40
+ stacked across each other, of any morphology, and the waves that leave the plane of a
41
+ crystal of rods. A phase whose coefficient ``a`` is zero is left out, its boundary free of
42
+ flux: the rigid scatterers of a sonic crystal (``1 / rho = 0``), the perfect conductors of
43
+ ``te`` waves. At long wavelengths the first band is that of the homogenized medium, ``ω² =
44
+ k . a* . k / <b>`` (:func:`long_wavelength_speeds`: Wood's law for the sound of mixtures,
45
+ the effective index of a photonic crystal).
46
+ """
47
+
48
+ from __future__ import annotations
49
+
50
+ import math
51
+ from dataclasses import dataclass
52
+ from itertools import product
53
+
54
+ import numpy as np
55
+ import scipy.sparse as sp
56
+ from scipy.sparse.linalg import LinearOperator, eigsh, splu
57
+
58
+ from morphogen.homogenization.fe import FEElasticProblem, FEThermalProblem, periodic_map
59
+ from morphogen.homogenization.materials import Material
60
+ from morphogen.image import VoxelImage
61
+ from morphogen.mesh.tetra import TET_EDGES, TetMesh
62
+
63
+ #: Corners of the Brillouin zone of an orthorhombic cell, in units of ``pi / L`` per axis.
64
+ POINTS = {
65
+ "G": (0.0, 0.0, 0.0),
66
+ "X": (1.0, 0.0, 0.0),
67
+ "Y": (0.0, 1.0, 0.0),
68
+ "Z": (0.0, 0.0, 1.0),
69
+ "M": (1.0, 1.0, 0.0),
70
+ "R": (1.0, 1.0, 1.0),
71
+ }
72
+
73
+
74
+ #: The scalar waves of the materials: the field, and the coefficients ``a`` and ``b`` of
75
+ #: ``div(a grad u) + ω² b u = 0`` (see :func:`wave_coefficients`)
76
+ SCALAR_WAVES = {
77
+ "acoustic": ("pressure", "1 / density", "1 / bulk modulus"),
78
+ "shear": ("antiplane displacement", "shear modulus", "density"),
79
+ "tm": ("electric field along the axis", "1 / permeability", "permittivity"),
80
+ "te": ("magnetic field along the axis", "1 / permittivity", "permeability"),
81
+ }
82
+
83
+ #: The scalar waves of a medium invariant along the third axis, for wave vectors in its
84
+ #: plane; in three dimensions: ``"elastic"`` and ``"electromagnetic"``
85
+ PLANE_WAVES = ("shear", "tm", "te")
86
+
87
+ #: The waves of :func:`band_structure`
88
+ WAVES = ("elastic", *SCALAR_WAVES, "electromagnetic")
89
+
90
+
91
+ def _monomial_integral(exponents) -> float:
92
+ """``∫ λ0^a λ1^b λ2^c λ3^d dV / V`` over a tetrahedron (barycentric coordinates)."""
93
+ num = 6.0 * math.prod(math.factorial(int(a)) for a in exponents)
94
+ return num / math.factorial(int(sum(exponents)) + 3)
95
+
96
+
97
+ def _p2_mass() -> np.ndarray:
98
+ """Consistent mass matrix of the 10-node tetrahedron over its volume (corners, then
99
+ the mid-edge nodes in ``TET_EDGES`` order)."""
100
+ shapes = []
101
+ for i in range(4): # λi (2 λi - 1)
102
+ two = [0, 0, 0, 0]
103
+ two[i] = 2
104
+ one = [0, 0, 0, 0]
105
+ one[i] = 1
106
+ shapes.append({tuple(two): 2.0, tuple(one): -1.0})
107
+ for a, b in TET_EDGES: # 4 λa λb
108
+ e = [0, 0, 0, 0]
109
+ e[a] += 1
110
+ e[b] += 1
111
+ shapes.append({tuple(e): 4.0})
112
+ m = np.zeros((10, 10))
113
+ for i, j in product(range(10), range(10)):
114
+ m[i, j] = sum(
115
+ ci * cj * _monomial_integral(np.add(ei, ej))
116
+ for ei, ci in shapes[i].items()
117
+ for ej, cj in shapes[j].items()
118
+ )
119
+ return m
120
+
121
+
122
+ #: Consistent mass matrices of the 4- and 10-node tetrahedra over their volume.
123
+ MASS = {1: (np.ones((4, 4)) + np.eye(4)) / 20.0, 2: _p2_mass()}
124
+
125
+
126
+ def mass_matrix(mesh: TetMesh, density) -> sp.csr_matrix:
127
+ """Consistent mass matrix (nodes x nodes) of a tetrahedral mesh, ``density`` the
128
+ density of each element."""
129
+ ref = MASS[mesh.order]
130
+ e = mesh.elements
131
+ m = e.shape[1]
132
+ rows = np.repeat(e, m, axis=1).ravel()
133
+ cols = np.tile(e, (1, m)).ravel()
134
+ vals = (np.asarray(density, dtype=float) * np.abs(mesh.volumes()))[:, None] * ref.ravel()
135
+ return sp.csr_matrix((vals.ravel(), (rows, cols)), shape=(mesh.n_nodes, mesh.n_nodes))
136
+
137
+
138
+ def voxel_tet_mesh(image: VoxelImage, phases=None) -> TetMesh:
139
+ """Six tetrahedra per voxel of an image (the Kuhn triangulation of its grid, whose
140
+ opposite faces match), each with the phase of its voxel; ``phases``: those kept (the
141
+ solid of a lattice, say)."""
142
+ from morphogen.mesh.conforming import background_mesh
143
+
144
+ lower = np.asarray(image.origin, dtype=float)
145
+ upper = lower + image.size
146
+ nodes, tets, _, _ = background_mesh(image.shape, lower, upper)
147
+ phase = np.tile(np.asarray(image.data).ravel(), 6) # six blocks of all the cubes
148
+ mesh = TetMesh(nodes, tets, phase, lower, upper, periodic=bool(image.periodic))
149
+ return mesh.subset(phases) if phases is not None else mesh
150
+
151
+
152
+ def brillouin_path(size, path=("G", "X", "M", "G", "R"), points: int = 12):
153
+ """Wave vectors along the segments between the corners ``path`` (names of
154
+ :data:`POINTS` or points in units of ``pi / L``) of the Brillouin zone of a cell of
155
+ edges ``size``, ``points`` per segment: the wave vectors (n x 3), their distance along
156
+ the path and the positions and names of the corners."""
157
+ size = np.asarray(size, dtype=float)
158
+ names = [("Γ" if p == "G" else p) if isinstance(p, str) else str(tuple(p)) for p in path]
159
+ corners = [
160
+ np.asarray(POINTS[p] if isinstance(p, str) else p, dtype=float) * np.pi / size for p in path
161
+ ]
162
+ ks, dist = [corners[0]], [0.0]
163
+ labels = [(0.0, names[0])]
164
+ for a, b, name in zip(corners[:-1], corners[1:], names[1:], strict=True):
165
+ start, length = dist[-1], float(np.linalg.norm(b - a))
166
+ for t in np.linspace(0.0, 1.0, int(points) + 1)[1:]:
167
+ ks.append(a + t * (b - a))
168
+ dist.append(start + t * length)
169
+ labels.append((dist[-1], name))
170
+ return np.array(ks), np.array(dist), labels
171
+
172
+
173
+ @dataclass
174
+ class BandStructure:
175
+ """The angular frequencies (``frequencies``: wave vectors x bands, increasing) of
176
+ the Bloch waves at the ``wavevectors``, their ``distance`` along the path and the
177
+ positions and names of its corners (``labels``)."""
178
+
179
+ wavevectors: np.ndarray
180
+ distance: np.ndarray
181
+ frequencies: np.ndarray
182
+ labels: list
183
+
184
+ def gaps(self, relative: float = 1e-3) -> list[tuple[int, float, float]]:
185
+ """The band gaps along the path: ``(n, low, high)`` between the bands ``n`` and
186
+ ``n + 1`` (counted from 1), wider than ``relative`` times their mid-frequency."""
187
+ out = []
188
+ for n in range(self.frequencies.shape[1] - 1):
189
+ low, high = float(self.frequencies[:, n].max()), float(self.frequencies[:, n + 1].min())
190
+ if high - low > relative * 0.5 * (high + low):
191
+ out.append((n + 1, low, high))
192
+ return out
193
+
194
+ def normalized(self, length: float, speed: float) -> np.ndarray:
195
+ """The frequencies in units of ``2 pi speed / length`` (``ω L / 2π c``)."""
196
+ return self.frequencies * length / (2.0 * np.pi * speed)
197
+
198
+ def plot(self, ax=None, *, scale: float = 1.0, ylabel: str = "ω"):
199
+ """Draw the bands (times ``scale``) along the path with its corners and the band
200
+ gaps shaded (matplotlib, without pyplot); returns the axes (``ax.figure.savefig``)."""
201
+ if ax is None:
202
+ from morphogen.viz.figures import _figure
203
+
204
+ ax = _figure(5.0, 4.0).subplots()
205
+ for _, low, high in self.gaps():
206
+ ax.axhspan(low * scale, high * scale, color="0.88", lw=0)
207
+ for position, _ in self.labels:
208
+ ax.axvline(position, color="0.6", lw=0.6)
209
+ ax.plot(self.distance, self.frequencies * scale, color="C0", lw=1.2)
210
+ if self.labels:
211
+ ax.set_xticks([d for d, _ in self.labels], [n for _, n in self.labels])
212
+ ax.set_xlim(self.distance[0], self.distance[-1])
213
+ ax.set_ylim(bottom=0.0)
214
+ ax.set_ylabel(ylabel)
215
+ return ax
216
+
217
+
218
+ def _scalar(value, name: str, phase) -> float:
219
+ """An isotropic coefficient of a material for the scalar waves."""
220
+ if value is None:
221
+ raise ValueError(f"waves: give the {name} of phase {phase}")
222
+ if isinstance(value, tuple):
223
+ raise ValueError(f"waves: an isotropic {name} (phase {phase})")
224
+ return float(value)
225
+
226
+
227
+ def wave_coefficients(waves: str, materials: dict[int, Material]) -> tuple[dict, dict]:
228
+ """The coefficients ``a`` and ``b`` of each phase for the scalar ``waves`` of
229
+ :data:`SCALAR_WAVES`, from the materials: their ``density`` and elastic moduli
230
+ (``acoustic``: the pressure waves of fluids, of bulk modulus ``K``; ``shear``:
231
+ antiplane shear waves), or their ``permittivity`` and ``permeability`` (``tm``,
232
+ ``te``; a permeability left out is that of the units, 1). Voids are left out; give
233
+ the coefficients themselves to :func:`scalar_band_structure` for the phases that the
234
+ materials do not describe (a fluid has no shear modulus)."""
235
+ if waves not in SCALAR_WAVES:
236
+ raise ValueError(f"waves: one of {WAVES}, got {waves!r}")
237
+ a, b = {}, {}
238
+ for phase, m in materials.items():
239
+ if m.void:
240
+ a[phase] = b[phase] = 0.0
241
+ continue
242
+ if waves in ("acoustic", "shear"):
243
+ density = _scalar(m.density, "density", phase)
244
+ if m.young is None:
245
+ raise ValueError(f"waves: isotropic elastic moduli (phase {phase})")
246
+ lam, mu = m.lame
247
+ if waves == "acoustic":
248
+ a[phase], b[phase] = 1.0 / density, 1.0 / (lam + 2.0 * mu / 3.0)
249
+ else:
250
+ a[phase], b[phase] = mu, density
251
+ else:
252
+ eps = _scalar(m.permittivity, "permittivity", phase)
253
+ mu = 1.0 if m.permeability is None else _scalar(m.permeability, "permeability", phase)
254
+ if not (eps > 0.0 and mu > 0.0):
255
+ raise ValueError(f"waves: positive permittivity and permeability (phase {phase})")
256
+ a[phase], b[phase] = (1.0 / mu, eps) if waves == "tm" else (1.0 / eps, mu)
257
+ return a, b
258
+
259
+
260
+ def electromagnetic_coefficients(materials: dict[int, Material]) -> tuple[dict, dict]:
261
+ """The permittivity and the permeability of each phase for the electromagnetic waves
262
+ (numbers, or 3 x 3 tensors in the axes of the cell), from the materials: their
263
+ ``permittivity`` and ``permeability`` (left out: that of the units, 1). A void holds
264
+ no wave in the scalar problems; here every phase carries the field: give the vacuum
265
+ its permittivity."""
266
+ eps, mu = {}, {}
267
+ for phase, m in materials.items():
268
+ if m.void or m.permittivity is None:
269
+ raise ValueError(
270
+ f"waves: give the permittivity of phase {phase} (1 for the vacuum: every phase "
271
+ "carries the electromagnetic field)"
272
+ )
273
+ eps[phase] = (
274
+ np.array(m.permittivity) if isinstance(m.permittivity, tuple) else m.permittivity
275
+ )
276
+ value = 1.0 if m.permeability is None else m.permeability
277
+ mu[phase] = np.array(value) if isinstance(value, tuple) else value
278
+ return eps, mu
279
+
280
+
281
+ def _default_path(sample, path):
282
+ """The path of a cell when none is given: Γ–X–M–Γ in the plane of a cell one voxel
283
+ thick, Γ–X–M–Γ–R otherwise."""
284
+ if path is not None:
285
+ return path
286
+ planar = isinstance(sample, VoxelImage) and sample.shape[2] == 1
287
+ return ("G", "X", "M", "G") if planar else ("G", "X", "M", "G", "R")
288
+
289
+
290
+ def _check_plane(sample, path, points: int, waves: str) -> None:
291
+ """The waves of a medium invariant along the third axis: a cell that does not vary
292
+ along it, and wave vectors in its plane."""
293
+ other = "'elastic'" if waves == "shear" else "'electromagnetic'"
294
+ if isinstance(sample, VoxelImage) and sample.shape[2] > 1:
295
+ data = np.asarray(sample.data)
296
+ if np.any(data != data[:, :, :1]):
297
+ raise ValueError(
298
+ f"waves {waves!r}: those of a cell invariant along z (one voxel thick); the "
299
+ f"waves of a three-dimensional cell: {other}"
300
+ )
301
+ if isinstance(path, np.ndarray) and path.ndim == 2:
302
+ ks = np.asarray(path, dtype=float)
303
+ else:
304
+ ks, _, _ = brillouin_path(sample.size, path, points)
305
+ if np.any(np.abs(ks[:, 2]) > 1e-12 * max(float(np.abs(ks).max()), 1e-300)):
306
+ raise ValueError(
307
+ f"waves {waves!r}: wave vectors in the plane x-y of the cell (a path such as G X M "
308
+ f"G); the waves that leave it: {other}"
309
+ )
310
+
311
+
312
+ def _wave_mesh(sample, order: int, phases) -> TetMesh:
313
+ mesh = voxel_tet_mesh(sample, phases) if isinstance(sample, VoxelImage) else sample
314
+ if int(order) == 2:
315
+ return mesh.quadratic().straight() # the mass matrices are those of straight edges
316
+ if int(order) == 1:
317
+ return mesh.linear()
318
+ raise ValueError("order: 1 or 2")
319
+
320
+
321
+ def _path(mesh: TetMesh, path, points: int):
322
+ if isinstance(path, np.ndarray) and path.ndim == 2:
323
+ ks = np.asarray(path, dtype=float)
324
+ dist = np.concatenate([[0.0], np.cumsum(np.linalg.norm(np.diff(ks, axis=0), axis=1))])
325
+ return ks, dist, []
326
+ return brillouin_path(mesh.size, path, points)
327
+
328
+
329
+ def _bands(stiffness, mass, mesh: TetMesh, nd: int, ks, bands: int) -> np.ndarray:
330
+ """The lowest Bloch frequencies of the matrices of a cell (``nd`` unknowns per node)
331
+ at the wave vectors ``ks``."""
332
+ t, masters, _ = periodic_map(mesh)
333
+ t = t.tocsr()
334
+ # the periods between each node and each of its masters (interpolated ones included)
335
+ rows = np.repeat(np.arange(t.shape[0]), np.diff(t.indptr))
336
+ delta = mesh.nodes[rows] - mesh.nodes[masters[t.indices]]
337
+ periods = np.rint(delta / mesh.size) * mesh.size
338
+ scale = float(np.median(stiffness.diagonal()) / np.median(mass.diagonal()))
339
+ sigma = -1e-6 * scale
340
+ n = int(bands)
341
+ if not 0 < n < t.shape[1] * nd:
342
+ raise ValueError(
343
+ f"band_structure: between 1 and {t.shape[1] * nd - 1} bands (the unknowns of the "
344
+ f"cell, less one), got {n}"
345
+ )
346
+ freqs = np.zeros((len(ks), n))
347
+ for i, k in enumerate(ks):
348
+ tk = sp.csr_matrix(
349
+ (t.data * np.exp(1j * (periods @ k)), t.indices, t.indptr), shape=t.shape
350
+ )
351
+ tn = sp.kron(tk, sp.identity(nd), format="csr") if nd > 1 else tk
352
+ kr = _real(tn.getH() @ stiffness @ tn)
353
+ mr = _real(tn.getH() @ mass @ tn)
354
+ # minimum degree on A + A^T: a quarter of the fill of SuperLU's default ordering
355
+ lu = splu((kr - sigma * mr).tocsc(), permc_spec="MMD_AT_PLUS_A")
356
+ inverse = LinearOperator(kr.shape, matvec=lu.solve, dtype=float)
357
+ values = eigsh(kr, 2 * n, mr, sigma=sigma, OPinv=inverse, return_eigenvectors=False)
358
+ values = np.sort(values)
359
+ freqs[i] = np.sqrt(np.clip(0.5 * (values[0::2] + values[1::2]), 0.0, None))
360
+ return freqs
361
+
362
+
363
+ def scalar_band_structure(
364
+ sample,
365
+ stiffness: dict[int, float],
366
+ mass: dict[int, float],
367
+ path=("G", "X", "M", "G", "R"),
368
+ *,
369
+ bands: int = 8,
370
+ points: int = 12,
371
+ order: int = 2,
372
+ phases=None,
373
+ ) -> BandStructure:
374
+ """The lowest ``bands`` Bloch frequencies of the scalar waves ``div(a grad u) + ω² b
375
+ u = 0`` of a periodic cell (mesh or voxel image, as :func:`band_structure`): ``a``
376
+ the ``stiffness`` coefficient of each phase and ``b`` its ``mass`` coefficient (the
377
+ table of the module: acoustic, antiplane shear and electromagnetic waves). The phases
378
+ whose ``a`` is zero are left out (rigid scatterers), their boundaries free of flux."""
379
+ mesh = _wave_mesh(sample, order, phases)
380
+ present = sorted({int(p) for p in mesh.phase})
381
+ missing = [p for p in present if p not in stiffness or p not in mass]
382
+ if missing:
383
+ raise ValueError(f"scalar_band_structure: no coefficients for phase(s) {missing}")
384
+ bad = [p for p in present if stiffness[p] < 0.0 or (stiffness[p] > 0.0 and not mass[p] > 0.0)]
385
+ if bad:
386
+ raise ValueError(
387
+ f"scalar_band_structure: positive coefficients (a >= 0, b > 0) for phase(s) {bad}"
388
+ )
389
+ mats = {
390
+ p: Material(conductivity=float(stiffness[p])) if stiffness[p] > 0.0 else Material(void=True)
391
+ for p in present
392
+ }
393
+ problem = FEThermalProblem(mesh, mats, bc="periodic")
394
+ if problem.empty:
395
+ raise ValueError("scalar_band_structure: no phase carries the waves")
396
+ mesh = problem.mesh
397
+ weight = np.array([mass[int(p)] for p in mesh.phase], dtype=float)
398
+ ks, dist, labels = _path(mesh, path, points)
399
+ matrix = problem._stiffness().tocsr()
400
+ freqs = _bands(matrix, mass_matrix(mesh, weight), mesh, 1, ks, bands)
401
+ return BandStructure(ks, dist, freqs, labels)
402
+
403
+
404
+ def long_wavelength_speeds(
405
+ sample, stiffness: dict[int, float], mass: dict[int, float], **options
406
+ ) -> dict:
407
+ """The speeds of the scalar waves of a periodic cell at long wavelengths, those of the
408
+ homogenized medium: ``c_i = sqrt(a*_ii / <b>)`` along each axis, with the effective
409
+ tensor ``a*`` of the coefficient ``a`` (a conduction problem: the FFT solver of a
410
+ voxel image, finite elements on a mesh) and the mean of ``b`` (over the whole cell,
411
+ the phases left out included: they hold no wave). Returns ``"tensor"`` (``a*``, 3 x
412
+ 3), ``"mass"`` (``<b>``) and ``"speeds"`` (3,). For the sound of a mixture of fluids
413
+ this is Wood's law (``1 / K* = <1 / K>``) with the effective density ``(a*)^-1``; for
414
+ light, ``c / n*``. ``options``: those of :func:`~morphogen.homogenization.apparent.
415
+ make_problem`."""
416
+ from morphogen.analysis import phase_fractions
417
+ from morphogen.homogenization.apparent import conductivity_tensor, make_problem
418
+
419
+ mats = {
420
+ p: Material(conductivity=float(a)) if a > 0.0 else Material(void=True)
421
+ for p, a in stiffness.items()
422
+ }
423
+ problem = make_problem(sample, mats, "thermal", "periodic", **options)
424
+ tensor, _ = conductivity_tensor(problem)
425
+ if isinstance(sample, VoxelImage):
426
+ fractions = phase_fractions(sample)
427
+ else:
428
+ volumes = np.abs(sample.volumes())
429
+ fractions = {
430
+ int(p): float(volumes[sample.phase == p].sum() / np.prod(sample.size))
431
+ for p in np.unique(sample.phase)
432
+ }
433
+ mean = float(sum(f * mass[p] for p, f in fractions.items() if stiffness.get(p, 0.0) > 0.0))
434
+ return {"tensor": tensor, "mass": mean, "speeds": np.sqrt(np.diag(tensor) / mean)}
435
+
436
+
437
+ def band_structure(
438
+ sample,
439
+ materials: dict[int, Material],
440
+ path=None,
441
+ *,
442
+ bands: int = 12,
443
+ points: int = 12,
444
+ order: int = 2,
445
+ phases=None,
446
+ waves: str = "elastic",
447
+ coarsen: int = 1,
448
+ ) -> BandStructure:
449
+ """The lowest ``bands`` Bloch frequencies of a periodic cell (a
450
+ :class:`~morphogen.mesh.tetra.TetMesh`, or a :class:`~morphogen.image.VoxelImage`
451
+ cut into six tetrahedra per voxel, keeping ``phases``) along ``path`` (corners of the
452
+ Brillouin zone, ``points`` per segment; or an array of wave vectors; by default
453
+ Γ–X–M–Γ–R, Γ–X–M–Γ in the plane of an image one voxel thick), with elements of
454
+ ``order`` 1 or 2. The materials need a ``density``; void phases are left out, as the
455
+ clusters of elements that touch no face of the box. ``waves``: ``"elastic"`` (the
456
+ vector waves of the solid); the scalar waves of :data:`SCALAR_WAVES` (``"acoustic"``,
457
+ and ``"shear"``, ``"tm"``, ``"te"`` in the plane of a cell invariant along z) with
458
+ the coefficients of the materials (:func:`wave_coefficients`,
459
+ :func:`scalar_band_structure`); or ``"electromagnetic"``, the vector waves of light in
460
+ a voxel image of any morphology, by plane waves on its voxels or on a grid
461
+ ``coarsen`` times coarser (:func:`~morphogen.homogenization.photonic.
462
+ electromagnetic_band_structure`; ``order`` and ``phases`` do not apply)."""
463
+ if waves not in WAVES:
464
+ raise ValueError(f"waves: one of {WAVES}, got {waves!r}")
465
+ path = _default_path(sample, path)
466
+ if waves == "electromagnetic":
467
+ from morphogen.homogenization.photonic import electromagnetic_band_structure
468
+
469
+ eps, mu = electromagnetic_coefficients(materials)
470
+ return electromagnetic_band_structure(
471
+ sample, eps, path, permeability=mu, bands=bands, points=points, coarsen=coarsen
472
+ )
473
+ if waves != "elastic":
474
+ a, b = wave_coefficients(waves, materials)
475
+ if waves in PLANE_WAVES:
476
+ _check_plane(sample, path, points, waves)
477
+ return scalar_band_structure(
478
+ sample, a, b, path, bands=bands, points=points, order=order, phases=phases
479
+ )
480
+ mesh = voxel_tet_mesh(sample, phases) if isinstance(sample, VoxelImage) else sample
481
+ if int(order) == 2:
482
+ mesh = mesh.quadratic().straight() # the mass matrices are those of straight edges
483
+ elif int(order) == 1:
484
+ mesh = mesh.linear()
485
+ else:
486
+ raise ValueError("order: 1 or 2")
487
+ problem = FEElasticProblem(mesh, materials, bc="periodic")
488
+ if problem.empty:
489
+ raise ValueError("band_structure: no material in the cell")
490
+ mesh = problem.mesh
491
+ missing = sorted({int(p) for p in mesh.phase if materials[int(p)].density is None})
492
+ if missing:
493
+ raise ValueError(f"band_structure: give the density of phase(s) {missing}")
494
+ density = np.array([materials[int(p)].density for p in mesh.phase], dtype=float)
495
+ stiffness = problem._stiffness().tocsr()
496
+ mass = sp.kron(mass_matrix(mesh, density), sp.identity(3), format="csr")
497
+ ks, dist, labels = _path(mesh, path, points)
498
+ freqs = _bands(stiffness, mass, mesh, 3, ks, bands)
499
+ return BandStructure(ks, dist, freqs, labels)
500
+
501
+
502
+ def _real(h: sp.spmatrix) -> sp.csc_matrix:
503
+ """The real symmetric matrix ``[[A, -B], [B, A]]`` of a Hermitian ``A + iB``: each
504
+ eigenvalue twice, so that the symmetric Lanczos of ARPACK applies (the complex
505
+ Hermitian one is that of nonsymmetric matrices)."""
506
+ h = 0.5 * (h + h.getH())
507
+ return sp.bmat([[h.real, -h.imag], [h.imag, h.real]], format="csc")