Source code for morphogen.coupling.fenicsx

"""Diffusion and swelling of tetrahedral meshes with FEniCSx (dolfinx): moisture or a
solvent enters a sample through its exposed faces, and the sample swells and bends as
it does (Mou, Dirrenberger & Le Duigou 2025 model pine cone scales and 4D-printed
hygromorphs this way with FEniCS).

The activity ``u`` of the species is continuous across interfaces, each phase holds
``c = S u`` and lets it through with the permeability ``D S`` (as in
:mod:`morphogen.coupling.diffusion`): ``S du/dt = div(D S grad u)``, Lagrange elements of
the order of the mesh, the exposed faces held at the activity (a number or a function of
time), the other faces impermeable, implicit Euler steps. At each output time the
sample, free of tractions, deforms elastically under the swelling strains ``beta c I``
(small strains; isotropic phases), held only by 3-2-1 supports at three corners: its
displacement field, and the curvature of a strip fitted to the deflection of its
mid-plane (:func:`strip_curvature`). FEniCSx runs on Linux (or WSL).
"""

from __future__ import annotations

import dataclasses
from collections.abc import Callable

import numpy as np
from scipy.spatial import cKDTree

from morphogen.homogenization.fenicsx import _modules
from morphogen.mesh.tetra import TetMesh

FACES = ("x-", "x+", "y-", "y+", "z-", "z+")


[docs] @dataclasses.dataclass class SwellingResult: """At the output ``times``: the mean concentration over the meshed volume (``uptake``; ``saturation`` at the activity of the last time), the concentration of the nodes (that of the phase of an element around each node, ``S u``) and their displacement (morphoGen's order of the nodes).""" times: np.ndarray uptake: np.ndarray saturation: float concentration: list displacement: list mesh: TetMesh = dataclasses.field(repr=False) @property def relative_uptake(self) -> np.ndarray: return self.uptake / self.saturation
def _dolfinx_mesh(mesh: TetMesh): basix, dolfinx, _, ufl, MPI, _ = _modules() corners = mesh.elements[:, :4] used = np.unique(corners) index = np.full(mesh.n_nodes, -1, dtype=np.int64) index[used] = np.arange(len(used)) coord = basix.ufl.element("Lagrange", "tetrahedron", 1, shape=(3,)) msh = dolfinx.mesh.create_mesh(MPI.COMM_SELF, index[corners], ufl.Mesh(coord), mesh.nodes[used]) original = msh.topology.original_cell_index if isinstance(original, list): original = original[0] return msh, np.asarray(original) def _node_map(space, mesh: TetMesh) -> np.ndarray: dist, block = cKDTree(space.tabulate_dof_coordinates()).query(mesh.nodes) if dist.max() > 1e-9 * float(np.max(mesh.upper - mesh.lower)): raise ValueError("the nodes of the mesh are not those of dolfinx's elements") return block def _cellwise(dolfinx, msh, values): space = dolfinx.fem.functionspace(msh, ("DG", 0)) f = dolfinx.fem.Function(space) f.x.array[space.dofmap.list[:, 0]] = values return f
[docs] def swelling( mesh: TetMesh, phases: dict, times, *, exposed=("z-",), activity: float | Callable[[float], float] = 1.0, initial: float = 0.0, steps: int = 20, kinematics: str = "small", ) -> SwellingResult: """Diffusion into ``mesh`` from its ``exposed`` faces and the free swelling of the sample at the output ``times``. ``phases``: phase -> mapping with ``diffusivity``, ``solubility`` (default 1), ``swelling`` (the strain per unit concentration, default 0), ``young`` and ``poisson``. Each output interval takes ``steps`` implicit Euler steps (the first one geometrically growing, for the sqrt(t) start). ``kinematics``: ``"small"`` (linear elasticity under the swelling strains) or ``"finite"`` (large rotations and strains: ``F = F_e F_s`` with the swelling stretch ``F_s = (1 + beta c) I``, Saint Venant-Kirchhoff's law of ``F_e`` per unit volume of the swollen state, so that ``P = (1 + beta c) F S_e``; Newton's method, each output reached by continuation of the concentration field, halved when it fails).""" if kinematics not in ("small", "finite"): raise ValueError('kinematics: "small" or "finite"') _, dolfinx, _, ufl, _, PETSc = _modules() for face in exposed: if face not in FACES: raise ValueError(f"exposed: faces among {', '.join(FACES)}") msh, original = _dolfinx_mesh(mesh) phase = np.asarray(mesh.phase)[original] missing = sorted(set(np.unique(phase).tolist()) - set(phases)) if missing: raise ValueError(f"phases: no properties for {missing}") def prop(name, default=None): out = [] for p in phase: v = phases[int(p)].get(name, default) if v is None: raise ValueError(f"phases: give '{name}' for phase {int(p)}") out.append(float(v)) return _cellwise(dolfinx, msh, np.array(out)) sol = prop("solubility", 1.0) perm = _cellwise( dolfinx, msh, np.asarray(prop("diffusivity").x.array) * np.asarray(sol.x.array) ) beta = prop("swelling", 0.0) young, poisson = prop("young"), prop("poisson") lam = young * poisson / ((1 + poisson) * (1 - 2 * poisson)) mu = young / (2 * (1 + poisson)) order = mesh.order v_space = dolfinx.fem.functionspace(msh, ("Lagrange", order)) w_space = dolfinx.fem.functionspace(msh, ("Lagrange", order, (3,))) node_s = _node_map(v_space, mesh) node_w = _node_map(w_space, mesh) # the exposed faces lo, hi, tol = mesh.lower, mesh.upper, mesh.tolerance() def on_faces(x): out = np.zeros(x.shape[1], dtype=bool) for face in exposed: axis, side = "xyz".index(face[0]), face[1] out |= np.abs(x[axis] - (lo[axis] if side == "-" else hi[axis])) <= tol return out facets = dolfinx.mesh.locate_entities_boundary(msh, 2, on_faces) exposed_dofs = dolfinx.fem.locate_dofs_topological(v_space, 2, facets) level = dolfinx.fem.Constant(msh, 0.0) bc = dolfinx.fem.dirichletbc(level, exposed_dofs, v_space) # diffusion: (S/dt) u + div(-D S grad u) = (S/dt) u_n u, v = ufl.TrialFunction(v_space), ufl.TestFunction(v_space) u_n = dolfinx.fem.Function(v_space) u_n.x.array[:] = initial inv_dt = dolfinx.fem.Constant(msh, 1.0) a_d = dolfinx.fem.form( (inv_dt * sol * u * v + perm * ufl.inner(ufl.grad(u), ufl.grad(v))) * ufl.dx ) l_d = dolfinx.fem.form(inv_dt * sol * u_n * v * ufl.dx) u_h = dolfinx.fem.Function(v_space) # mechanics: free swelling, 3-2-1 supports d, e = ufl.TrialFunction(w_space), ufl.TestFunction(w_space) def eps(z): return ufl.sym(ufl.grad(z)) def sigma(z): return 2.0 * mu * eps(z) + lam * ufl.tr(eps(z)) * ufl.Identity(3) a_m = dolfinx.fem.form(ufl.inner(sigma(d), eps(e)) * ufl.dx) l_m = dolfinx.fem.form((3.0 * lam + 2.0 * mu) * beta * sol * u_h * ufl.div(e) * ufl.dx) tree = cKDTree(mesh.nodes) corners = [lo, np.array([hi[0], lo[1], lo[2]]), np.array([lo[0], hi[1], lo[2]])] supports = [int(tree.query(c)[1]) for c in corners] held = {0: [supports[0]], 1: [supports[0], supports[1]], 2: supports} bcs_m = [] for c in range(3): sub, parent = w_space.sub(c).collapse() inverse = np.full(3 * len(node_w), -1, dtype=np.int64) inverse[np.asarray(parent)] = np.arange(len(parent)) dofs = np.array(sorted({3 * int(node_w[n]) + c for n in held[c]}), dtype=np.int32) bcs_m.append( dolfinx.fem.dirichletbc( dolfinx.fem.Function(sub), [dofs, inverse[dofs].astype(np.int32)], w_space.sub(c) ) ) a_mech = dolfinx.fem.petsc.assemble_matrix(a_m, bcs=bcs_m) a_mech.assemble() ksp_m = PETSc.KSP().create(msh.comm) ksp_m.setOperators(a_mech) ksp_m.setType("preonly") ksp_m.getPC().setType("lu") ksp_m.getPC().setFactorSolverType("mumps") disp = dolfinx.fem.Function(w_space) if kinematics == "finite": u_load = dolfinx.fem.Function(v_space) # the activity along the continuation identity = ufl.Identity(3) def_grad = identity + ufl.grad(disp) stretch = 1.0 + beta * sol * u_load fe = def_grad / stretch ee = 0.5 * (fe.T * fe - identity) se = lam * ufl.tr(ee) * identity + 2.0 * mu * ee residual = ufl.inner(stretch * def_grad * se, ufl.grad(e)) * ufl.dx newton = dolfinx.fem.petsc.NonlinearProblem( residual, disp, petsc_options_prefix="morphogen_swelling_", bcs=bcs_m, petsc_options={ "snes_type": "newtonls", "snes_linesearch_type": "bt", "snes_rtol": 1e-10, "snes_atol": 1e-12, "snes_max_it": 15, "ksp_type": "preonly", "pc_type": "lu", "pc_factor_mat_solver_type": "mumps", }, ) u_prev = np.full(u_h.x.array.shape, float(initial)) def finite_solve(): target = np.asarray(u_h.x.array).copy() done, step = 0.0, 0.25 saved = disp.x.array.copy() while done < 1.0 - 1e-12: s = min(1.0, done + step) u_load.x.array[:] = u_prev + s * (target - u_prev) newton.solve() if newton.solver.getConvergedReason() > 0: done, saved = s, disp.x.array.copy() step = min(1.5 * step, 1.0 - done) if done < 1.0 else step else: disp.x.array[:] = saved step *= 0.5 if step < 1e-4: raise RuntimeError("swelling: Newton's method failed in finite strains") u_prev[:] = target value = activity if callable(activity) else (lambda t, a=float(activity): a) volume = float(np.abs(mesh.volumes()).sum()) solvers: dict[float, object] = {} def diffusion_step(dt, t): key = float(dt) if key not in solvers: inv_dt.value = 1.0 / dt mat = dolfinx.fem.petsc.assemble_matrix(a_d, bcs=[bc]) mat.assemble() ksp = PETSc.KSP().create(msh.comm) ksp.setOperators(mat) ksp.setType("preonly") ksp.getPC().setType("lu") ksp.getPC().setFactorSolverType("mumps") solvers.clear() solvers[key] = ksp inv_dt.value = 1.0 / dt level.value = value(t) b = dolfinx.fem.petsc.assemble_vector(l_d) dolfinx.fem.petsc.apply_lifting(b, [a_d], bcs=[[bc]]) b.ghostUpdate(addv=PETSc.InsertMode.ADD, mode=PETSc.ScatterMode.REVERSE) dolfinx.fem.petsc.set_bc(b, [bc]) solvers[key].solve(b, u_h.x.petsc_vec) u_h.x.scatter_forward() u_n.x.array[:] = u_h.x.array b.destroy() times = np.asarray(times, dtype=float) if np.any(np.diff(times) <= 0) or times[0] <= 0: raise ValueError("times: positive and increasing") uptake, conc, displacement = [], [], [] mean_c = dolfinx.fem.form(sol * u_h * ufl.dx) # the solubility of an element around each node, for the nodal concentrations element_sol = np.array([float(phases[int(p)].get("solubility", 1.0)) for p in mesh.phase]) node_sol = np.zeros(mesh.n_nodes) node_sol[mesh.elements.ravel()] = np.repeat(element_sol, mesh.elements.shape[1]) t = 0.0 u_h.x.array[:] = initial for t_out in times: span = t_out - t if t == 0.0: r = 1.25 first = span * (r - 1.0) / (r**steps - 1.0) dts = first * r ** np.arange(steps) else: dts = np.full(steps, span / steps) for dt in dts: t += dt diffusion_step(dt, t) t = float(t_out) uptake.append(float(dolfinx.fem.assemble_scalar(mean_c)) / volume) conc.append(node_sol * np.asarray(u_h.x.array)[node_s]) if kinematics == "finite": finite_solve() else: b = dolfinx.fem.petsc.assemble_vector(l_m) dolfinx.fem.petsc.apply_lifting(b, [a_m], bcs=[bcs_m]) b.ghostUpdate(addv=PETSc.InsertMode.ADD, mode=PETSc.ScatterMode.REVERSE) dolfinx.fem.petsc.set_bc(b, bcs_m) ksp_m.solve(b, disp.x.petsc_vec) disp.x.scatter_forward() b.destroy() displacement.append(np.asarray(disp.x.array).reshape(-1, 3)[node_w].copy()) s_mean = float(dolfinx.fem.assemble_scalar(dolfinx.fem.form(sol * ufl.dx))) / volume return SwellingResult( times, np.asarray(uptake), s_mean * float(value(times[-1])), conc, displacement, mesh )
[docs] def strip_curvature(mesh: TetMesh, displacement, *, axis: int = 0, normal: int = 2) -> float: """Curvature of a strip along ``axis`` bending in the plane of ``normal``: minus the second derivative of the deflection of the nodes of its mid-plane (least squares, ``w = -k x^2 / 2 + a x + b + c y``), so that it is positive when the strip bends towards its lower face (``-normal``), as :func:`~morphogen.coupling.timoshenko_curvature` and :class:`~morphogen.coupling.Multilayer`.""" d = np.asarray(displacement) mid = 0.5 * (mesh.lower[normal] + mesh.upper[normal]) z = mesh.nodes[:, normal] close = ( np.abs(z - mid) <= 0.5 * np.min(np.abs(np.unique(z) - mid)[np.unique(z) != mid], initial=np.inf) + mesh.tolerance() ) if not close.any(): close = np.abs(z - mid) == np.abs(z - mid).min() x = mesh.nodes[close, axis] other = 3 - axis - normal y = mesh.nodes[close, other] w = d[close, normal] basis = np.column_stack([0.5 * x**2, x, np.ones_like(x), y]) coef, *_ = np.linalg.lstsq(basis, w, rcond=None) return -float(coef[0])
[docs] def arc_curvature(mesh: TetMesh, displacement, *, axis: int = 0, normal: int = 2) -> float: """Curvature of a strip that bends into an arc (large rotations): the circle fitted (least squares, Kasa) to the deformed nodes of its mid-plane in the plane of ``axis`` and ``normal``; positive when the strip bends towards its lower face.""" d = np.asarray(displacement) mid = 0.5 * (mesh.lower[normal] + mesh.upper[normal]) z0 = mesh.nodes[:, normal] close = np.abs(z0 - mid) == np.abs(z0 - mid).min() x = mesh.nodes[close, axis] + d[close, axis] z = z0[close] + d[close, normal] basis = np.column_stack([x, z, np.ones_like(x)]) coef, *_ = np.linalg.lstsq(basis, -(x * x + z * z), rcond=None) cx, cz = -0.5 * coef[0], -0.5 * coef[1] radius = float(np.sqrt(cx * cx + cz * cz - coef[2])) return (1.0 if cz < z.mean() else -1.0) / radius
[docs] @dataclasses.dataclass class OxidationResult: """At the ``times``: the oxidation tracer (amide concentration, mol/l) of each element, their stresses (Voigt order 11 22 33 23 31 12) and the displacement of the nodes.""" times: np.ndarray tracer: list stress: list displacement: list mesh: TetMesh = dataclasses.field(repr=False)
[docs] def oxidation_stresses( mesh: TetMesh, law, times, *, oxidation=None, exposed=("z-", "z+"), poisson: float = 0.37, nodes: int = 81, ) -> OxidationResult: """Stresses of a sample oxidized through its ``exposed`` faces (Ernault et al. 2019): the amide profile of the diffusion-limited oxidation (:class:`~morphogen.coupling.ClosedLoopOxidation`, default: their DGEBA/IPDA at 110 °C) at the depth of each element below the nearest exposed face, Young's modulus and the shrinkage (``expansion``, a strain) of ``law`` (:class:`~morphogen.coupling.PropertyLaw` of the amide concentration), and the linear elastic response of the free sample (3-2-1 supports) to these eigenstrains (Poisson's ratio ``poisson``, 0.37 as theirs).""" from morphogen.coupling.oxidation import ClosedLoopOxidation _, dolfinx, _, ufl, _, PETSc = _modules() oxidation = oxidation or ClosedLoopOxidation() for face in exposed: if face not in FACES: raise ValueError(f"exposed: faces among {', '.join(FACES)}") times = np.asarray(times, dtype=float) centroids = mesh.nodes[mesh.elements[:, :4]].mean(axis=1) depth = np.full(len(centroids), np.inf) for face in exposed: axis = "xyz".index(face[0]) plane = mesh.lower[axis] if face[1] == "-" else mesh.upper[axis] depth = np.minimum(depth, np.abs(centroids[:, axis] - plane)) profile = oxidation.profile(2.0 * float(depth.max()) * 1.02, times, nodes=nodes) surface = oxidation.thin_film(times)["PO"] msh, original = _dolfinx_mesh(mesh) w_space = dolfinx.fem.functionspace(msh, ("Lagrange", mesh.order, (3,))) node_w = _node_map(w_space, mesh) young = _cellwise(dolfinx, msh, np.ones(len(original))) shrink = _cellwise(dolfinx, msh, np.zeros(len(original))) lam = young * poisson / ((1.0 + poisson) * (1.0 - 2.0 * poisson)) mu = young / (2.0 * (1.0 + poisson)) d, e = ufl.TrialFunction(w_space), ufl.TestFunction(w_space) def eps(z): return ufl.sym(ufl.grad(z)) identity = ufl.Identity(3) a_form = dolfinx.fem.form( ufl.inner(2.0 * mu * eps(d) + lam * ufl.tr(eps(d)) * identity, eps(e)) * ufl.dx ) l_form = dolfinx.fem.form((3.0 * lam + 2.0 * mu) * shrink * ufl.div(e) * ufl.dx) tree = cKDTree(mesh.nodes) lo, hi = mesh.lower, mesh.upper corners = [lo, np.array([hi[0], lo[1], lo[2]]), np.array([lo[0], hi[1], lo[2]])] supports = [int(tree.query(c)[1]) for c in corners] held = {0: [supports[0]], 1: [supports[0], supports[1]], 2: supports} bcs = [] for c in range(3): sub, parent = w_space.sub(c).collapse() inverse = np.full(3 * len(node_w), -1, dtype=np.int64) inverse[np.asarray(parent)] = np.arange(len(parent)) dofs = np.array(sorted({3 * int(node_w[n]) + c for n in held[c]}), dtype=np.int32) bcs.append( dolfinx.fem.dirichletbc( dolfinx.fem.Function(sub), [dofs, inverse[dofs].astype(np.int32)], w_space.sub(c) ) ) disp = dolfinx.fem.Function(w_space) strain = eps(disp) sigma = ( 2.0 * mu * (strain - shrink * identity) + lam * ufl.tr(strain - shrink * identity) * identity ) t_space = dolfinx.fem.functionspace(msh, ("DG", 0, (3, 3))) points = t_space.element.interpolation_points points = points() if callable(points) else points sigma_expr = dolfinx.fem.Expression(sigma, points) stress_fn = dolfinx.fem.Function(t_space) cells = t_space.dofmap.list[:, 0] order = np.empty(len(original), dtype=np.int64) order[original] = np.arange(len(original)) # morphoGen element -> dolfinx cell depths = np.concatenate([[0.0], profile["depth"]]) tracers, stresses, displacements = [], [], [] for k in range(len(times)): amide = np.concatenate([[surface[k]], profile["PO"][k]]) tracer = np.interp(depth, depths, amide) props = law(tracer) young.x.array[young.function_space.dofmap.list[:, 0]] = props["young"][original] shrink.x.array[shrink.function_space.dofmap.list[:, 0]] = props.get( "expansion", np.zeros_like(tracer) )[original] mat = dolfinx.fem.petsc.assemble_matrix(a_form, bcs=bcs) mat.assemble() ksp = PETSc.KSP().create(msh.comm) ksp.setOperators(mat) ksp.setType("preonly") ksp.getPC().setType("lu") ksp.getPC().setFactorSolverType("mumps") b = dolfinx.fem.petsc.assemble_vector(l_form) dolfinx.fem.petsc.apply_lifting(b, [a_form], bcs=[bcs]) b.ghostUpdate(addv=PETSc.InsertMode.ADD, mode=PETSc.ScatterMode.REVERSE) dolfinx.fem.petsc.set_bc(b, bcs) ksp.solve(b, disp.x.petsc_vec) disp.x.scatter_forward() stress_fn.interpolate(sigma_expr) tensors = np.asarray(stress_fn.x.array).reshape(-1, 9)[cells][order].reshape(-1, 3, 3) voigt = np.stack( [ tensors[:, 0, 0], tensors[:, 1, 1], tensors[:, 2, 2], tensors[:, 1, 2], tensors[:, 2, 0], tensors[:, 0, 1], ], axis=1, ) tracers.append(tracer) stresses.append(voigt) displacements.append(np.asarray(disp.x.array).reshape(-1, 3)[node_w].copy()) b.destroy() ksp.destroy() mat.destroy() return OxidationResult(times, tracers, stresses, displacements, mesh)