simcardemsx 0.1.0__py3-none-any.whl

simcardemsx/__init__.py

@@ -0,0 +1,18 @@
+from importlib.metadata import metadata
+
+meta = metadata("simcardemsx")
+__version__ = meta.get("Version")
+__author__ = meta.get("Author-email")
+__license__ = meta.get("license-expression")
+__email__ = meta.get("Author-email")
+__program_name__ = meta.get("Name")
+
+from . import backends, controller, interpolation, ode_model, utils
+
+__all__ = [
+    "backends",
+    "controller",
+    "ode_model",
+    "utils",
+    "interpolation",
+]

simcardemsx/averaging.py

@@ -0,0 +1,112 @@
+"""Averaging a discontinuous field into a continuous or cellwise-constant target.
+
+Values sent from the mechanics mesh back to the EP mesh (fibre stretch λ, active
+tension, ...) are discontinuous across cells -- there is no single "the" value at a
+shared vertex. Point interpolation of such a field into a continuous (P1) space picks
+up whichever neighbouring cell's value the interpolation happens to visit last, so the
+result silently depends on cell numbering. :func:`make_averager` instead builds a
+proper average: a mass-lumped nodal average for a P1 target, an exact cell average for
+a DG0 target.
+
+Both source and target are assumed to live on the same mesh -- this module averages
+*within* a mesh; :mod:`simcardemsx.interpolation` moves values *between* meshes.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+import dolfinx
+import ufl
+
+
+def family_name(element) -> str:
+    """The element's family name, normalizing a discontinuous element to ``"DG"``.
+
+    dolfinx reports a discontinuous Lagrange element's own ``family_name`` as
+    ``"P"`` (with ``discontinuous=True``); callers building a label like
+    ``"DG0"`` need ``"DG"`` instead.
+    """
+    return "DG" if element.discontinuous else element.family_name
+
+
+def make_averager(
+    source: dolfinx.fem.Function,
+    target: dolfinx.fem.Function,
+) -> Callable[[], None]:
+    """Build a callable that refreshes ``target`` in place with an average of ``source``.
+
+    Compiles the assembly forms once, here, rather than on every call. The returned
+    closure re-assembles the numerator against the current ``source`` values each time
+    it is called (the denominator -- cell volumes / patch measures -- does not depend on
+    ``source`` and is assembled once, up front).
+
+    Supported ``target`` spaces:
+
+    - continuous Lagrange degree 1 (P1): the lumped nodal average
+      ``target_i = (∫ source φ_i dx) / (∫ φ_i dx)``. Because a nodal basis function
+      φ_i vanishes outside the cells touching node i, this is exactly the volume-weighted
+      average of ``source`` over the cells sharing that node.
+    - discontinuous Lagrange degree 0 (DG0): the exact cell average
+      ``target_K = (∫_K source dx) / |K|``. DG0 basis functions do not overlap between
+      cells, so the same numerator/denominator machinery reduces to a per-cell average
+      with no approximation.
+
+    Any other ``target`` space raises :class:`NotImplementedError`.
+
+    When ``source`` lives on a quadrature space, the measure is given
+    ``metadata={"quadrature_degree": source's degree}`` so FFCx reuses the same
+    quadrature rule the values were stored at, instead of picking its own (which would
+    not line up with the stored point values at all).
+
+    Parameters
+    ----------
+    source : dolfinx.fem.Function
+        The (generally discontinuous, possibly quadrature) function to average.
+    target : dolfinx.fem.Function
+        The function refreshed, in place, by the returned callable. Its function space
+        determines which averaging scheme is used.
+
+    Returns
+    -------
+    Callable[[], None]
+        Call it with no arguments to refresh ``target`` from the current ``source``.
+    """
+    V_target = target.function_space
+    target_element = V_target.ufl_element()
+    family = family_name(target_element)
+    degree = target_element.degree
+
+    is_p1 = family == "P" and degree == 1
+    is_dg0 = family == "DG" and degree == 0
+    if not (is_p1 or is_dg0):
+        raise NotImplementedError(
+            "make_averager only supports a continuous P1 or a DG0 target, got "
+            f"family={family!r}, degree={degree}",
+        )
+
+    mesh = V_target.mesh
+    source_element = source.function_space.ufl_element()
+    metadata = None
+    if source_element.family_name == "quadrature":
+        metadata = {"quadrature_degree": source_element.degree}
+    dx = ufl.dx(domain=mesh, metadata=metadata)
+
+    v = ufl.TestFunction(V_target)
+    numerator_form = dolfinx.fem.form(source * v * dx)
+    denominator_form = dolfinx.fem.form(v * dx)
+
+    # The denominator (cell volumes for DG0, nodal patch measures for P1) depends only
+    # on the mesh and V_target, both fixed -- assemble it once.
+    denominator = dolfinx.fem.assemble_vector(denominator_form)
+    denominator.scatter_reverse(dolfinx.la.InsertMode.add)
+    denominator.scatter_forward()
+
+    def refresh() -> None:
+        numerator = dolfinx.fem.assemble_vector(numerator_form)
+        numerator.scatter_reverse(dolfinx.la.InsertMode.add)
+        numerator.scatter_forward()
+        target.x.array[:] = numerator.array / denominator.array
+        target.x.scatter_forward()
+
+    return refresh

simcardemsx/backends/__init__.py

@@ -0,0 +1,37 @@
+"""Activation backends.
+
+Each backend generates active tension and hands it to the mechanics solve, but
+they differ in where the EP/mechanics split is cut and in how force generation
+is coupled to mechanics. See :mod:`simcardemsx.backends.base` for the
+``CoupledBackend`` protocol and why the differences matter.
+
+The controller drives a backend through :class:`CoupledBackend`;
+:class:`GeneratedActivation` and :class:`CrossbridgeSegregated` are two. What crosses
+between EP and activation is derived from the EP module and the backend's
+``missing``/``provides`` by :func:`simcardemsx.transfer_plan.resolve` and moved by
+:class:`simcardemsx.transfer_plan.TransferPlan`. :class:`ZetaSplitUFL` is driven
+directly against ``pulse`` and declares its crossings with :class:`Transfer`.
+
+- :class:`GeneratedActivation`: any split of an ``.ode`` file, coupled monolithically in
+  Newton (the default), stabilized-segregated, or naive segregated (``scheme``).
+- :class:`CrossbridgeSegregated`: a crossbridge model on the Ca_i split,
+  stabilized-segregated (R&Q), or naive segregated (``stabilized=False``).
+- :class:`ZetaSplitUFL` (deprecated): the hand-ported Land model of the zeta split.
+
+An external-operator crossbridge backend, coupling monolithically without
+symbolic differentiation, is planned; it would implement :class:`CoupledBackend`.
+"""
+
+from .base import CoupledBackend, Transfer
+from .generated import GeneratedActivation
+from .segregated import CrossbridgeSegregated
+from .zeta_split import Scheme, ZetaSplitUFL
+
+__all__ = [
+    "CoupledBackend",
+    "Transfer",
+    "GeneratedActivation",
+    "ZetaSplitUFL",
+    "CrossbridgeSegregated",
+    "Scheme",
+]

simcardemsx/backends/base.py

@@ -0,0 +1,120 @@
+"""The activation-backend interface.
+
+An *activation backend* owns everything about how active tension is generated
+and how it reaches the mechanics solve. Different backends make genuinely
+different numerical choices -- where the EP/mechanics split is cut, and whether
+the force-generation model is coupled monolithically or in a segregated way.
+
+The controller drives a backend through the :class:`CoupledBackend` protocol below;
+what crosses between EP and activation is derived from the EP module and the backend's
+``missing``/``provides`` by :func:`simcardemsx.transfer_plan.resolve` and moved by
+:class:`simcardemsx.transfer_plan.TransferPlan`. :class:`~simcardemsx.backends.generated.
+GeneratedActivation` and :class:`~simcardemsx.backends.segregated.CrossbridgeSegregated`
+are two; ``CrossbridgeSegregated`` also documents the units of its crossings with
+:class:`Transfer` records. :class:`ZetaSplitUFL` is driven directly against ``pulse``,
+and declares its crossings with :class:`Transfer` instead.
+
+That matters more than usual here, because the choices are not equivalent.
+A segregated coupling of force generation to mechanics is unstable, and in
+fact not convergent, once active stiffness exceeds passive stiffness
+(Regazzoni & Quarteroni 2021); a monolithic one is stable but expensive. Having
+the alternatives behind one interface is what makes them comparable on the same
+mesh, in the same process, from the same configuration, rather than by
+comparing published numbers.
+
+A backend is also a ``pulse.ActiveModel``: it supplies ``S``/``P`` and is handed
+straight to ``pulse.CardiacModel``. Note that ``S`` is the primary contract, not
+``strain_energy``. Only a segregated backend has a clean potential to
+differentiate; for the zeta split ``Ta`` depends on the stretch through
+``zeta_s(lambda_dot)``, so no closed-form potential exists, and for an
+external-operator backend ``Ta`` is opaque by construction. This is fine:
+``pulse.StaticProblem`` assembles ``model.S(C)`` and never touches
+``strain_energy``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Mapping, Protocol, runtime_checkable
+
+import dolfinx
+
+
+@dataclass(frozen=True)
+class Transfer:
+    """One variable crossing between the EP and mechanics subsystems.
+
+    A bare name is not enough to drive a transfer. The direction is carried by
+    which backend method returns the ``Transfer`` (``wants_from_ep`` or
+    ``gives_to_ep``); the rest is here.
+
+    Attributes
+    ----------
+    name:
+        The variable's name in the generated ODE module, e.g. ``"cai"`` or
+        ``"XS"``. Used to look up its index via ``state_index``/``monitor_index``.
+    unit:
+        The unit *as the producing side emits it*, e.g. ``"mM"`` for ToR-ORd's
+        ``cai``. The consumer may want something else -- crossbridge wants
+        micromolar -- and carrying the unit here is what lets the coupler
+        convert explicitly instead of relying on a lookup table keyed
+        invisibly by name.
+    kind:
+        Whether ``name`` is an ODE state or a monitored (derived) expression.
+        They need different index lookups in the generated module.
+    """
+
+    name: str
+    unit: str = "dimensionless"
+    kind: Literal["state", "monitor"] = "state"
+
+
+@runtime_checkable
+class CoupledBackend(Protocol):
+    """What :class:`~simcardemsx.controller.SimulationController` requires of a backend.
+
+    Once per mechanics time step the controller calls, in this order::
+
+        backend.begin_step(t_n, dt)   # t_n is the old time, dt the mechanics step (ms)
+        mechanics.advance(t_n, dt)    # the Newton solve
+        backend.post_solve()          # accept the step
+        # then TransferPlan.backward() reads ``outputs``
+
+    Nothing is accepted before ``post_solve``: until then the backend's stored states,
+    ``outputs`` and ``active_tension`` are those of the last accepted step, so a step
+    whose solve fails leaves them untouched. ``begin_step`` only prepares the step.
+
+    What crosses between EP and the backend is derived by
+    :func:`simcardemsx.transfer_plan.resolve` from ``missing`` and ``provides``, the
+    name -> index dicts of the generated activation module, and moved through
+    ``inputs`` (EP -> backend, filled before ``begin_step``) and ``outputs``
+    (backend -> EP, read after ``post_solve``), all on ``space``.
+    """
+
+    @property
+    def missing(self) -> Mapping[str, int]:
+        """What the activation module needs from EP, name -> index."""
+        ...
+
+    @property
+    def provides(self) -> Mapping[str, int]:
+        """What the activation module hands to EP, name -> index."""
+        ...
+
+    @property
+    def quadrature_degree(self) -> int | None:
+        """The degree of the quadrature space the states live on, if they live on one."""
+        ...
+
+    inputs: dict[str, dolfinx.fem.Function]
+    outputs: dict[str, dolfinx.fem.Function]
+    space: dolfinx.fem.FunctionSpace
+    active_tension: dolfinx.fem.Function
+
+    def begin_step(self, t_n: float, dt: float) -> None:
+        """Prepare the step from ``t_n`` to ``t_n + dt`` (ms)."""
+        ...
+
+    def post_solve(self) -> None:
+        """Accept the converged step."""
+        ...