mechdsl-core 0.2.1__tar.gz

mechdsl_core-0.2.1/.gitignore

@@ -0,0 +1,75 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Taichi
+*.tcb
+ti_cache/
+
+# Artifacts
+*.artifact.json
+*.artifact.yaml
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Claude Code
+.claude/settings.local.json
+
+# Claude CoWork
+/MechDsl/
+*.npz
+# Golden-file regression snapshots must be tracked
+!packages/mechdsl-core/tests/golden/*.npz
+.gitnexus
+
+# Local working artifacts (orchestra runtime, plan-edit backups)
+.orchestra/
+**/.orchestra/
+*.original.md
+*.original.[0-9].md
+.claude/worktrees/
+.publisher-worktrees/
+.sesskey
+
+# Public-release staging tree (curated copy pushed to CEmM2/MechDSL)
+/dev/MechDSL/
+
+# MkDocs build output
+/site/
+
+# Generated wiki / code-intelligence index (logic-loom / akms tooling)
+.repo_wiki/
+
+# comment-sweep working tree
+/.comment-review/

mechdsl_core-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shmuel Osovski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mechdsl_core-0.2.1/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: mechdsl-core
+Version: 0.2.1
+Summary: MechDSL core — LaTeX tensor expressions to FEM solver code
+Project-URL: Repository, https://github.com/CEmM2/MechDSL
+Author: Shmuel Osovski
+License-Expression: MIT
+License-File: LICENSE
+Keywords: code-generation,computational-mechanics,dsl,fem,finite-elements,taichi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: <3.14,>=3.11
+Requires-Dist: nrpylatex<2,>=1.4.0
+Requires-Dist: numpy>=2.4.2
+Requires-Dist: opt-einsum>=3.3
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: scipy>=1.17.0
+Requires-Dist: sympy>=1.12
+Provides-Extra: verify
+Requires-Dist: algo2code<0.3,>=0.2.1; extra == 'verify'
+Requires-Dist: taichi>=1.7; extra == 'verify'
+Requires-Dist: ti-runtime<0.3,>=0.2.1; extra == 'verify'
+Description-Content-Type: text/markdown
+
+# mechdsl-core
+
+Core compiler package for MechDSL — LaTeX tensor expressions to FEM solver code.
+
+Handles constitutive equations, element-level physics (Einstein notation), kinematics,
+and Taichi code generation through the Mechanics IR → Element IR → Einsum IR pipeline.
+
+## Documentation
+
+- **User docs:** <https://sosovski.group/MechDSL/mechdsl-core/> — introduction, getting
+  started, the LaTeX directive reference, the constitutive-model catalog, and examples.
+- **Design specs:** `dev/design_docs/` (authoritative source of truth).
+- See the [monorepo root](../../README.md) for the full project overview.

mechdsl_core-0.2.1/README.md

@@ -0,0 +1,13 @@
+# mechdsl-core
+
+Core compiler package for MechDSL — LaTeX tensor expressions to FEM solver code.
+
+Handles constitutive equations, element-level physics (Einstein notation), kinematics,
+and Taichi code generation through the Mechanics IR → Element IR → Einsum IR pipeline.
+
+## Documentation
+
+- **User docs:** <https://sosovski.group/MechDSL/mechdsl-core/> — introduction, getting
+  started, the LaTeX directive reference, the constitutive-model catalog, and examples.
+- **Design specs:** `dev/design_docs/` (authoritative source of truth).
+- See the [monorepo root](../../README.md) for the full project overview.

mechdsl_core-0.2.1/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mechdsl-core"
+version = "0.2.1"
+description = "MechDSL core — LaTeX tensor expressions to FEM solver code"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11,<3.14"
+authors = [
+    { name = "Shmuel Osovski" },
+]
+keywords = ["fem", "finite-elements", "computational-mechanics", "dsl", "taichi", "code-generation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "sympy>=1.12",
+    "numpy>=2.4.2",
+    "opt-einsum>=3.3",
+    "pyyaml>=6.0.3",
+    "scipy>=1.17.0",
+    "nrpylatex>=1.4.0,<2",
+]
+
+[project.optional-dependencies]
+# Taichi is the runtime backend — imported *only* on the verify() / run path
+# (the emit, transpile, capabilities and model_catalog surfaces are proven
+# Taichi-free; see tests/test_integration_surface.py::*taichi_free*). It lives
+# in the `verify` extra so downstream consumers (compmech_reference_pack,
+# akms_learn, the Logic-Loom sidecar) can install mechdsl-core for code
+# emission without pulling Taichi's ~170 MB into their closure. Install
+# `mechdsl-core[verify]` to run verification / solves. opt-einsum stays a base
+# dep — it is a 0.4 MB pure-Python compile-time requirement of the emit path.
+#
+# The generated matrix-free SVK tangent @ti.kernel emits
+# `from ti_runtime import ...` (Tier-1 tensor helpers + hex8 shape gradients +
+# the apply_A injection seam) — the mechdsl-core -> ti-runtime production
+# dependency edge. ti-runtime is Taichi-bearing, so it rides in the `verify`
+# extra alongside taichi; the base install (emit / transpile / capabilities)
+# stays Taichi-free. The generated matrix-free PCG solver is transpiled via
+# `algo2code` in runtime mode and injected through the ti_runtime `set_solver`
+# seam; algo2code is a stdlib-only compile-time tool and rides in the same
+# extra. `verify` is the full install (~1 GB closure via Taichi) — everything
+# needed to run and verify solves, not just emit code.
+# NOTE: the AD oracle uses central finite differences (mechdsl.verify.ad_oracle)
+# — torch was never imported anywhere and is deliberately NOT a dependency.
+verify = ["taichi>=1.7", "ti-runtime>=0.2.1,<0.3", "algo2code>=0.2.1,<0.3"]
+
+[project.scripts]
+mechdsl-lawgen = "mechdsl.lawgen.cli:main"
+
+[tool.uv.sources]
+ti-runtime = { workspace = true }
+algo2code = { workspace = true }
+
+[project.urls]
+Repository = "https://github.com/CEmM2/MechDSL"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mechdsl"]

mechdsl_core-0.2.1/src/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_core-0.2.1/src/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_core-0.2.1/src/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