mechdsl-core 0.2.1__py3-none-any.whl

mechdsl/__init__.py

@@ -0,0 +1,263 @@
+"""MechDSL core — LaTeX tensor expressions to FEM solver code (Taichi).
+
+The canonical MVP-stable entry point is :func:`compile_latex`, which accepts
+a LaTeX source string and produces an :class:`~mechdsl.codegen.artifact.ArtifactBundle`.
+The lower-level :func:`compile` is preserved as a programmatic API that
+takes a pre-built :class:`~mechdsl.ir.mechanics_ir.ProblemIR`.
+
+See ``README.md`` Support tiers and
+``dev/plans/recovery_plan_latex_contract.md`` Phase 2 (R1) for the recovery
+context.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mechdsl import integration as integration
+from mechdsl.codegen import compile
+
+if TYPE_CHECKING:
+    from os import PathLike
+
+    from mechdsl.codegen.artifact import ArtifactBundle
+
+__version__ = "0.2.1"
+
+# Allowed values for the `profile` argument of :func:`compile_latex`. Module-
+# level so callers can introspect the supported set instead of guessing from
+# the docstring. Add new profiles by extending this set explicitly — never
+# silently relax the gate.
+ALLOWED_PROFILES: frozenset[str] = frozenset({"mvp"})
+
+__all__ = ["ALLOWED_PROFILES", "compile", "compile_latex", "integration"]
+
+# Authored-invariant markers that select a non-default constitutive derivation
+# path. Principal stretches (lbar1/2/3) belong to the spectral (Ogden) engine;
+# the fiber pseudo-invariant (Ibar4) belongs to the anisotropic (HGO) engine.
+_SPECTRAL_STRETCH = ("lbar1", "lbar2", "lbar3")
+_FIBER_INVARIANT = "Ibar4"
+
+
+def _derive_constitutive_energy(energy_source: str):
+    """Derive the constitutive model, routing by the authored invariants.
+
+    The free symbols of the parsed energy decide the path (robust to comments,
+    unlike a raw substring scan): a fiber pseudo-invariant ``Ibar4`` -> the
+    anisotropic (HGO) engine; principal stretches ``lbar1/2/3`` -> the spectral
+    (Ogden) engine; otherwise the named-invariant engine. Each engine
+    re-validates and rejects symbols outside its own contract.
+    """
+    from mechdsl.symbolic.energy import parse_energy_scalar_sympy
+
+    psi, _ = parse_energy_scalar_sympy(energy_source)
+    names = {s.name for s in psi.free_symbols}
+    if _FIBER_INVARIANT in names:
+        from mechdsl.symbolic.anisotropic_energy import derive_from_anisotropic_energy
+
+        return derive_from_anisotropic_energy(energy_source)
+    if any(s in names for s in _SPECTRAL_STRETCH):
+        from mechdsl.symbolic.spectral_energy import derive_from_spectral_energy
+
+        return derive_from_spectral_energy(energy_source)
+    from mechdsl.symbolic.energy import derive_from_energy
+
+    return derive_from_energy(energy_source)
+
+
+def compile_latex(
+    source: str,
+    profile: str = "mvp",
+    *,
+    energy_source: str | None = None,
+    energy_file: str | PathLike[str] | None = None,
+) -> ArtifactBundle:
+    """Compile a LaTeX-source mechanics problem to an artifact bundle.
+
+    This is the canonical MVP-stable entry point. The function:
+
+    1. Parses ``source`` through
+       :func:`mechdsl.frontend.parse_compile_context`, the math-aware
+       frontend entry point that preserves directive-only behaviour while
+       rejecting unsupported math-bearing sources before IR construction.
+    2. Adapts the resulting context dict to a :class:`ProblemIR` via
+       :meth:`ProblemIR.from_latex_semantics` (fgram P6-1). This is the
+       LaTeX-semantic constructor: its MVP-stable *core* (dim, formulation,
+       element type, material, boundaries) is identical to
+       :meth:`ProblemIR.from_context`, so the emitted Taichi code is
+       byte-for-byte unchanged. The constructor additionally attaches a
+       serializable :class:`~mechdsl.ir.mechanics_ir.LatexSemantics` record
+       to the IR (declared fields, directive-tagged constitutive
+       ``(symbol, role)`` pairs, the weak-form label, and any ``$...$``
+       equation roles). That record rides into the artifact bundle's
+       ``problem_ir_dict["latex_semantics"]`` so emitted code sections are
+       traceable back to their source equation roles for review and golden
+       diffing — the codegen contract itself stays the typed IR fields
+       (``material`` / ``residual_contract``), not the advisory record.
+    3. Forwards to :func:`compile` (the existing programmatic façade)
+       to run localisation, einsum planning, and Taichi emission.
+
+    **Backend stability:** Taichi is the only MVP-stable backend on the
+    canonical LaTeX compile path.  All code produced by this function
+    targets the Taichi runtime.  MFEM and MOOSE are experimental backends
+    preserved in the tree (``mechdsl.codegen.mfem_printer`` and
+    ``mechdsl.codegen.moose_printer``) but they are not reachable through
+    this façade and are not part of the stable contract.  Reaching those
+    surfaces requires calling the experimental printers directly; see
+    ``README.md`` Support tiers and
+    ``dev/plans/recovery_plan_latex_contract.md`` Phase 5 (R4).
+
+    Parameters
+    ----------
+    source:
+        LaTeX source text containing ``% mechanics`` directives.
+    profile:
+        Compile profile selector. Only ``"mvp"`` is currently accepted;
+        other profiles (e.g. extended LaTeX math grammar via NRPyLaTeX,
+        non-canonical backends) are deferred to later recovery phases.
+    energy_source:
+        Optional self-contained nrpylatex strain-energy block (``% declare``
+        metric + ``EDD`` strain, then the scalar energy assignment). When
+        provided, it is run
+        through :func:`mechdsl.symbolic.energy.derive_from_energy` and the
+        resulting symbolic PK2 stress + material tangent are attached to the
+        :class:`ProblemIR` as ``derived_energy``. The generated solver then
+        emits its constitutive law and consistent tangent from the derived
+        energy (parameterised on the energy's own material-parameter names),
+        instead of the named-model ``(lam, mu)`` dispatch. The problem
+        ``source``'s ``MaterialSpec`` params must supply a value for every
+        parameter the energy uses.
+    energy_file:
+        Path to a ``.tex`` file holding the same energy block as
+        ``energy_source``. Mutually exclusive with ``energy_source``; the file
+        is read as UTF-8.
+
+    Boundary conditions
+    -------------------
+    LaTeX ``% mechanics boundary`` directives populate
+    :class:`mechdsl.ir.mechanics_ir.BoundaryCondition` slots on the
+    resulting :class:`ProblemIR`. Two boundary kinds are supported:
+
+    - **Dirichlet** — fixed displacement components, applied at solve
+      time by the runtime adapter.
+    - **Neumann** — surface tractions. When the directive carries a
+      numeric traction triple, post_recovery_plan P1-5 emits an
+      ``f_ext`` initialisation kernel (see ``f_ext_kernel`` in
+      *Returns* below) and the bundle is self-contained for that BC.
+      Neumann BCs with a symbolic-string traction leave the kernel
+      slot empty.
+
+    Numeric ``f_ext`` provisioning is the **caller's responsibility**
+    when no kernel is emitted (Dirichlet-only problems or
+    symbolic-traction Neumann): the caller supplies the global
+    external-force vector to the solver. When ``f_ext_kernel`` is
+    present, the emitted kernel overrides any manual ``f_ext``
+    provisioning for the directive-driven contribution; the caller
+    is still responsible for compositing it with any additional body
+    forces. ``BoundaryCondition`` objects therefore document intent
+    at the IR level, while the artifact bundle decides whether the
+    contract is satisfied entirely by emitted code or jointly by
+    caller-provided ``f_ext``.
+
+    Returns
+    -------
+    ArtifactBundle
+        The same bundle :func:`compile` produces, ready for golden-file
+        comparison or Taichi emission. When the parsed problem contains
+        one or more Neumann BCs with numeric traction (post_recovery_plan
+        P1-5), the bundle's optional ``f_ext_kernel`` field carries the
+        emitted ``init_f_ext_from_neumann_<bc>`` kernel source. The kernel
+        signature is parametric in ``f_factor`` (= face_area /
+        n_face_nodes) so the runtime mesh adapter supplies the per-node
+        weighting at call time. Pure Dirichlet problems and Neumann BCs
+        with symbolic-string traction leave ``f_ext_kernel`` at ``None``;
+        existing residual / tangent fields and ``emitted_source`` shape
+        are unchanged.
+
+    Raises
+    ------
+    ValueError
+        When ``profile`` is anything other than ``"mvp"``.
+    mechdsl.frontend.parser.ParseError
+        When the LaTeX source has a malformed ``% mechanics`` directive.
+    mechdsl.frontend.FrontendSemanticError
+        When a math-bearing LaTeX source cannot produce supported frontend
+        math semantics before IR construction.
+    mechdsl.symbolic.convected.UnsupportedError
+        When the parsed context falls outside the MVP-supported subset.
+
+    """
+    if profile not in ALLOWED_PROFILES:
+        raise ValueError(
+            f"compile_latex profile={profile!r} is not supported. "
+            f"Allowed profiles: {sorted(ALLOWED_PROFILES)}. "
+            "Broader profile support is planned for later recovery-plan "
+            "phases (see dev/plans/recovery_plan_latex_contract.md)."
+        )
+
+    if energy_source is not None and energy_file is not None:
+        raise ValueError(
+            "compile_latex accepts at most one of energy_source / energy_file, not both."
+        )
+    if energy_file is not None:
+        from pathlib import Path
+
+        energy_source = Path(energy_file).read_text(encoding="utf-8")
+
+    from mechdsl.frontend import parse_compile_context
+
+    ctx = parse_compile_context(source)
+
+    import dataclasses
+
+    from mechdsl.codegen.taichi_printer import (
+        EmissionContext,
+        emit_neumann_f_ext_kernel_for_ir,
+    )
+    from mechdsl.ir.mechanics_ir import BCType, ProblemIR
+
+    # Build the IR through the LaTeX-semantic constructor so the emitted
+    # bundle carries the source-role metadata (latex_semantics) that links
+    # generated code sections back to source equation roles. The MVP-stable
+    # core is identical to from_context, so emitted Taichi is unchanged;
+    # only the additive latex_semantics record is new.
+    problem_ir = ProblemIR.from_latex_semantics(ctx)
+    # When a strain-energy block was supplied, derive its symbolic stress and
+    # attach it to the IR. The codegen layer then emits the constitutive law and
+    # consistent tangent from the derived energy (taichi_printer + the matching
+    # emitter), parameterised on the energy's own material-parameter names rather
+    # than the named-model (lam, mu) dispatch. The derivation path is selected
+    # from the authored invariants: principal stretches (Ogden) -> spectral,
+    # a fiber pseudo-invariant (HGO) -> anisotropic, else the named-invariant path.
+    if energy_source is not None:
+        problem_ir = dataclasses.replace(
+            problem_ir, derived_energy=_derive_constitutive_energy(energy_source)
+        )
+    # Enforce the MVP-stable contract at the canonical compile-path
+    # boundary so users hitting an experimental combination or a missing
+    # required-param see a clean IR-level rejection instead of a deep
+    # codegen / runtime failure.
+    problem_ir.assert_mvp_stable()
+    bundle = compile(problem_ir)
+
+    # Surface a Neumann ``f_ext`` initialisation kernel for every Neumann
+    # BC carrying numeric traction. Symbolic (string) traction stays
+    # handled by the legacy imported numeric injection path so existing
+    # callers keep working unchanged. Pure Dirichlet problems leave
+    # ``f_ext_kernel`` at ``None``.
+    neumann_bcs = [
+        bc
+        for bc in problem_ir.boundaries
+        if bc.bc_type == BCType.NEUMANN and isinstance(bc.traction, tuple)
+    ]
+    if not neumann_bcs:
+        return bundle
+    em_ctx = EmissionContext()
+    for bc in neumann_bcs:
+        emit_neumann_f_ext_kernel_for_ir(
+            em_ctx,
+            bc_name=bc.name,
+            surface_tag=bc.effective_surface_tag,
+            traction=bc.traction,  # type: ignore[arg-type]
+        )
+    return dataclasses.replace(bundle, f_ext_kernel=em_ctx.get_source())

mechdsl/codegen/__init__.py

@@ -0,0 +1,90 @@
+"""Einsum optimizer, Taichi code generation, boundary condition codegen.
+
+Backend support tiers
+---------------------
+The MVP-stable canonical backend is :mod:`mechdsl.codegen.taichi_printer`.
+:mod:`mechdsl.codegen.mfem_printer` and :mod:`mechdsl.codegen.moose_printer`
+are preserved in-tree as **experimental** surfaces (see
+``dev/plans/recovery_plan_latex_contract.md`` Phase 5 (R4)).
+
+The ``__experimental__`` convention
+-----------------------------------
+Every experimental printer module exposes a module-level constant::
+
+    __experimental__: bool = True
+
+so callers and tests can detect experimental status programmatically::
+
+    from mechdsl.codegen import mfem_printer
+    assert mfem_printer.__experimental__ is True
+
+Stable backends do **not** set this flag.  On the first call to its public
+``emit`` function, each experimental printer additionally raises a single
+:class:`mechdsl.codegen._experimental.ExperimentalBackendWarning` that can
+be filtered with the standard :mod:`warnings` machinery.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mechdsl.codegen._experimental import ExperimentalBackendWarning
+from mechdsl.codegen.taichi_printer import TaichiCodegenFacade
+
+if TYPE_CHECKING:
+    from mechdsl.codegen.artifact import ArtifactBundle
+    from mechdsl.ir.mechanics_ir import ProblemIR
+
+__all__ = ["ExperimentalBackendWarning", "TaichiCodegenFacade", "compile"]
+
+
+def compile(problem_ir: ProblemIR) -> ArtifactBundle:
+    """Compile a ProblemIR into a self-contained Taichi solver.
+
+    Runs the full pipeline: localise → optimise → emit.
+
+    **Backend stability:** Taichi is the only MVP-stable backend on the
+    canonical LaTeX compile path.  MFEM and MOOSE printers exist in the
+    tree as experimental surfaces (see ``mechdsl.codegen.mfem_printer``
+    and ``mechdsl.codegen.moose_printer``) but they are not part of the
+    stable contract and may not be supported in future recovery phases
+    without explicit roadmap work (Plan B §B8).
+
+    Parameters
+    ----------
+    problem_ir : ProblemIR
+        The semantic problem specification.
+
+    Returns
+    -------
+    ArtifactBundle
+        Bundle with ``emitted_source`` populated. Contains all
+        intermediate products (IRs, contraction plans).
+
+    Raises
+    ------
+    ValueError
+        Propagated when the IR contains an unsupported formulation,
+        element type, or material model for the MVP pipeline.
+    BudgetExceededError
+        Propagated when einsum optimisation exceeds the absolute JIT
+        budget ceiling.
+    """
+    from mechdsl.codegen.artifact import ArtifactBundle as _AB
+    from mechdsl.codegen.taichi_printer import emit
+    from mechdsl.lowering.fe_localise import localise_and_optimize
+
+    loc_result, plans = localise_and_optimize(problem_ir)
+    bundle = _AB.from_pipeline(problem_ir, loc_result, plans)
+    source = emit(bundle)
+
+    return _AB(
+        problem_ir_dict=bundle.problem_ir_dict,
+        element_ir_summary=bundle.element_ir_summary,
+        contraction_plans=bundle.contraction_plans,
+        emitted_source=source,
+        metadata=bundle.metadata,
+        # Preserve the derived-energy Python-object channel through the
+        # bundle rebuild so a LaTeX-derived constitutive law reaches codegen.
+        derived_energy=bundle.derived_energy,
+    )

mechdsl/codegen/_experimental.py

@@ -0,0 +1,71 @@
+"""Experimental-backend infrastructure for mechdsl.codegen.
+
+Defines the shared :class:`ExperimentalBackendWarning` that each non-stable
+printer emits on first use, and documents the ``__experimental__`` flag
+convention used across the codegen package.
+
+Convention
+----------
+Every experimental backend module exposes a module-level constant::
+
+    __experimental__: bool = True
+
+This allows tooling and tests to detect experimental status
+programmatically (e.g. ``import mechdsl.codegen.mfem_printer as m;
+assert m.__experimental__``) rather than parsing docstrings.  Stable
+backends (currently only :mod:`mechdsl.codegen.taichi_printer`) do **not**
+set this flag.
+
+At runtime, each experimental printer emits one
+:class:`ExperimentalBackendWarning` per Python session on the first call to
+its public ``emit`` function.  The warning is filterable with the standard
+:mod:`warnings` machinery::
+
+    import warnings
+    warnings.filterwarnings("ignore", category=ExperimentalBackendWarning)
+"""
+
+from __future__ import annotations
+
+import warnings
+
+__all__ = ["ExperimentalBackendWarning", "warn_experimental_backend_once"]
+
+
+class ExperimentalBackendWarning(UserWarning):
+    """Warning raised on the first call to an experimental codegen backend.
+
+    Experimental backends (MFEM, MOOSE) are preserved in-tree but are not
+    part of the MVP stable contract.  This warning signals that the caller
+    is using a surface outside the stable Taichi compile path.
+
+    Filter with::
+
+        import warnings
+        warnings.filterwarnings("ignore", category=ExperimentalBackendWarning)
+    """
+
+
+def warn_experimental_backend_once(state: dict, backend_name: str) -> None:
+    """Emit an ExperimentalBackendWarning the first time this is called for the given state.
+
+    Idempotent: subsequent calls with the same state dict are no-ops.
+
+    Parameters
+    ----------
+    state : dict
+        Module-level dict tracking warning state. Caller passes a single shared
+        dict (e.g. ``_warn_state``); this function flips ``state["warned"]`` to True.
+    backend_name : str
+        Human-readable backend name (e.g. "MFEM", "MOOSE") for the warning message.
+    """
+    if state.get("warned"):
+        return
+    warnings.warn(
+        f"{backend_name} backend is experimental — its API may change without "
+        f"deprecation notice. Suppress with "
+        f"warnings.filterwarnings('ignore', category=ExperimentalBackendWarning).",
+        ExperimentalBackendWarning,
+        stacklevel=3,
+    )
+    state["warned"] = True

mechdsl/codegen/anisotropic_emitter.py

@@ -0,0 +1,233 @@
+"""Emit a Taichi constitutive ``@ti.func`` from a LaTeX-derived *anisotropic*
+(fiber-reinforced, HGO) energy.
+
+The straight-line emitter in :mod:`mechdsl.codegen.energy_emitter` prints one
+unconditional assignment per stress component. The Holzapfel-Gasser-Ogden (HGO)
+family needs two things it structurally cannot do (see :issue:`288`):
+
+1. a **data-dependent branch** — the fiber term is gated to tension by the
+   Macaulay bracket ``<Ibar4 - 1>`` (active only when ``Ibar4 > 1``); and
+2. a **per-element fiber-direction gather** — the fiber stress depends on a
+   direction ``a`` that is per-element field data (P5-1
+   ``ProblemIR.fiber_field`` -> ``ElementIR.fiber_field``), not authored in the
+   LaTeX, so the constitutive function gains a fiber-direction argument that the
+   call site reads from the gathered field.
+
+This module supplies :func:`emit_anisotropic_constitutive_func`, which emits a
+``constitutive_update(F, a, *params)`` that:
+
+* computes the always-on isotropic + volumetric stress ``S_iso(E)`` (identical
+  in form to the proven neo-Hookean emission);
+* normalises the fiber direction ``a`` (as the oracle does), computes the fiber
+  pseudo-invariant ``Ibar4(E, a)``; and
+* adds the active-branch fiber stress ``S_fib(E, a)`` only when ``Ibar4 > 1``.
+
+It reproduces :meth:`AnisotropicEnergyModel.pk2_stress` for a single fiber family
+(the ``fiber_dispersion = 0`` perfectly-aligned case), so the emitted Taichi and
+the NumPy oracle agree to FP noise.
+
+Conventions (07-CONVENTIONS.md): tension-positive stress; float64. Material
+parameters keep their sanitised LaTeX names as ``ti.f64`` arguments, matching
+:mod:`mechdsl.codegen.energy_emitter`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sympy import Symbol, pycode
+
+from mechdsl.codegen.energy_emitter import _to_numpy_math, _to_taichi_math
+
+if TYPE_CHECKING:
+    from mechdsl.symbolic.anisotropic_energy import AnisotropicEnergyModel
+
+__all__ = [
+    "ANISOTROPIC_PK2_NUMPY_NAME",
+    "anisotropic_param_names",
+    "emit_anisotropic_constitutive_func",
+    "emit_anisotropic_pk2_numpy_source",
+    "emit_anisotropic_tangent_matvec_body",
+]
+
+_STRAIN = "EDD"
+
+# Name of the emitted host-NumPy PK2 helper the FD tangent calls.
+ANISOTROPIC_PK2_NUMPY_NAME = "_pk2_anisotropic"
+
+
+def anisotropic_param_names(model: AnisotropicEnergyModel) -> list[str]:
+    """Sorted union of isotropic and fiber material-parameter names.
+
+    These name the ``ti.f64`` arguments of the emitted ``constitutive_update``
+    (in the same sorted order the body forwards them), mirroring
+    :func:`mechdsl.codegen.energy_emitter.derived_param_names`. The union (not
+    just the isotropic params) guarantees a fiber-only parameter (e.g. ``k1`` /
+    ``k2``) is still plumbed into the signature.
+    """
+    names = {s.name for s in model.iso_param_symbols}
+    names |= {s.name for s in model.fiber_param_symbols}
+    return sorted(names)
+
+
+def emit_anisotropic_constitutive_func(
+    model: AnisotropicEnergyModel,
+    *,
+    func_name: str = "constitutive_update",
+    param_names: list[str] | None = None,
+    fiber_arg: str = "a",
+) -> str:
+    """Return a Taichi ``@ti.func`` computing PK2 stress ``S(F, a)`` from a
+    derived *anisotropic* (HGO) energy model.
+
+    The emitted function takes the deformation gradient ``F``, a per-element
+    fiber-direction vector ``a`` (``ti.Vector(3)``, gathered from the fiber
+    field at the call site), and one ``ti.f64`` argument per material parameter.
+    It builds the Green-Lagrange strain, assigns the always-on isotropic stress,
+    then conditionally adds the fiber stress when the tension gate
+    ``Ibar4(E, a) > 1`` is open.
+
+    ``param_names`` overrides the argument list (default:
+    :func:`anisotropic_param_names`); pass an explicit list to keep the
+    signature aligned with the unified solver parameter vocabulary, as
+    :mod:`mechdsl.codegen.energy_emitter` does. ``fiber_arg`` names the fiber
+    vector argument (default ``a``, matching the ``a0``/``a1``/``a2`` symbols the
+    derivation uses).
+    """
+    # Strain symbols EDDij -> the per-component locals Eij the body declares.
+    strain_subs = {
+        model.strain_symbols[i][j]: Symbol(f"E{i}{j}") for i in range(3) for j in range(3)
+    }
+
+    args = param_names if param_names is not None else anisotropic_param_names(model)
+    # @ti.func arguments are untyped: Taichi infers their types from the call site.
+    arglist = ", ".join(["F", fiber_arg, *args])
+    head = [
+        "@ti.func",
+        f"def {func_name}({arglist}):",
+    ]
+    body = [
+        '"""PK2 stress from a fiber-reinforced (HGO) strain energy; fiber term'
+        ' tension-gated by the Macaulay bracket <Ibar4 - 1>."""',
+        "C = F.transpose() @ F",
+        "I3 = ti.Matrix.identity(ti.f64, 3)",
+        "E = 0.5 * (C - I3)",
+    ]
+    for i in range(3):
+        for j in range(3):
+            body.append(f"E{i}{j} = E[{i}, {j}]")
+    # Normalise the gathered fiber direction (the oracle normalises before
+    # evaluating). The derivation's a0/a1/a2 symbols bind to these locals, so
+    # pycode references resolve directly.
+    body.append(
+        f"_anorm = ti.sqrt({fiber_arg}[0] * {fiber_arg}[0] + {fiber_arg}[1] * {fiber_arg}[1]"
+        f" + {fiber_arg}[2] * {fiber_arg}[2])"
+    )
+    for k in range(3):
+        body.append(f"a{k} = {fiber_arg}[{k}] / _anorm")
+    # Always-on isotropic + volumetric stress.
+    body.append("S = ti.Matrix.zero(ti.f64, 3, 3)")
+    for i in range(3):
+        for j in range(3):
+            expr = model.iso_pk2[i, j].xreplace(strain_subs)
+            body.append(f"S[{i}, {j}] = {_to_taichi_math(pycode(expr))}")
+    # Fiber gate: the Macaulay bracket makes the fiber term active in tension
+    # only (Ibar4 > 1) -- the data-dependent branch the straight-line emitter
+    # structurally lacks.
+    ibar4_expr = model.fiber_ibar4.xreplace(strain_subs)
+    body.append(f"ibar4 = {_to_taichi_math(pycode(ibar4_expr))}")
+    body.append("if ibar4 > 1.0:")
+    for i in range(3):
+        for j in range(3):
+            expr = model.fiber_pk2[i, j].xreplace(strain_subs)
+            if expr == 0:
+                continue
+            body.append(f"    S[{i}, {j}] += {_to_taichi_math(pycode(expr))}")
+    body.append("return 0.5 * (S + S.transpose())")
+
+    indent = "    "
+    return "\n".join(head + [indent + line for line in body]) + "\n"
+
+
+def emit_anisotropic_pk2_numpy_source(
+    model: AnisotropicEnergyModel,
+    *,
+    func_name: str = ANISOTROPIC_PK2_NUMPY_NAME,
+    param_names: list[str] | None = None,
+    fiber_arg: str = "a",
+) -> str:
+    """Return a host-NumPy ``def`` computing PK2 stress ``S(E, a)`` for the HGO
+    energy, used as the central-difference reference of the FD tangent.
+
+    The internal force is computed by the device ``@ti.func``
+    (:func:`emit_anisotropic_constitutive_func`); the matrix-free
+    ``tangent_matvec`` is host NumPy and needs a host stress to finite-difference.
+    This emits exactly :meth:`AnisotropicEnergyModel.pk2_stress` for a single
+    fiber family: the always-on isotropic stress plus the tension-gated fiber
+    stress (``Ibar4 > 1``), with the fiber direction normalised, so the device
+    and host stresses stay numerically identical.
+    """
+    strain_subs = {
+        model.strain_symbols[i][j]: Symbol(f"E{i}{j}") for i in range(3) for j in range(3)
+    }
+    args = param_names if param_names is not None else anisotropic_param_names(model)
+    arglist = ", ".join(["E", fiber_arg, *args])
+    head = [f"def {func_name}({arglist}):"]
+    body = [
+        '"""Host-NumPy PK2 stress for the HGO energy (FD-tangent reference)."""',
+    ]
+    for i in range(3):
+        for j in range(3):
+            body.append(f"E{i}{j} = E[{i}, {j}]")
+    body.append(
+        f"_anorm = np.sqrt({fiber_arg}[0] ** 2 + {fiber_arg}[1] ** 2 + {fiber_arg}[2] ** 2)"
+    )
+    for k in range(3):
+        body.append(f"a{k} = {fiber_arg}[{k}] / _anorm")
+    body.append("S = np.zeros((3, 3), dtype=np.float64)")
+    for i in range(3):
+        for j in range(3):
+            expr = model.iso_pk2[i, j].xreplace(strain_subs)
+            body.append(f"S[{i}, {j}] = {_to_numpy_math(pycode(expr))}")
+    ibar4_expr = model.fiber_ibar4.xreplace(strain_subs)
+    body.append(f"ibar4 = {_to_numpy_math(pycode(ibar4_expr))}")
+    body.append("if ibar4 > 1.0:")
+    for i in range(3):
+        for j in range(3):
+            expr = model.fiber_pk2[i, j].xreplace(strain_subs)
+            if expr == 0:
+                continue
+            body.append(f"    S[{i}, {j}] += {_to_numpy_math(pycode(expr))}")
+    body.append("return 0.5 * (S + S.T)")
+
+    indent = "    "
+    return "\n".join(head + [indent + line for line in body]) + "\n"
+
+
+def emit_anisotropic_tangent_matvec_body(
+    model: AnisotropicEnergyModel,
+    *,
+    pk2_name: str = ANISOTROPIC_PK2_NUMPY_NAME,
+    param_names: list[str] | None = None,
+    fiber_local: str = "a_fiber",
+) -> list[str]:
+    """Host-NumPy lines for the HGO material term inside ``tangent_matvec``.
+
+    Returns statements (no leading indent) that, given the Green-Lagrange strain
+    ``E``, the linearised strain ``dE`` (both ``(3, 3)`` ``np.ndarray``), the
+    fiber direction ``fiber_local`` (a 3-vector in scope), and the material
+    parameters already in scope, assign ``S`` (derived PK2 stress) and ``dS``
+    (``C : dE`` via the directional central difference). FD is the correct method
+    across the non-smooth Macaulay gate (it matches
+    :meth:`AnisotropicEnergyModel.material_tangent_4th`).
+    """
+    args = param_names if param_names is not None else anisotropic_param_names(model)
+    fwd = ", ".join(args)
+    return [
+        "# Derived HGO constitutive law: PK2 stress + central-difference FD tangent.",
+        f"S = {pk2_name}(E, {fiber_local}, {fwd})",
+        "_fd_eps = 1e-6",
+        f"_S_plus = {pk2_name}(E + _fd_eps * dE, {fiber_local}, {fwd})",
+        f"_S_minus = {pk2_name}(E - _fd_eps * dE, {fiber_local}, {fwd})",
+        "dS = (_S_plus - _S_minus) / (2.0 * _fd_eps)",
+    ]