pyfieldml

A modern, pure-Python implementation of FieldML 0.5 with a full evaluation engine, interop bridges (meshio, PyVista, XDMF, scikit-fem, OpenSim-adjacent), and a curated biomechanics model zoo.

FieldML is the Physiome Project's declarative markup language for representing mathematical fields over discrete meshes — used across computational physiology (cardiac, musculoskeletal, respiratory modeling). The original C++ FieldML-API has been effectively unmaintained since 2015. pyfieldml is an independent reimplementation that brings FieldML into the modern scientific-Python ecosystem.

Status: v1.0 — feature-complete for Phase-1 through Phase-5 scope. See the design spec and CHANGELOG for what's in and what's deferred to later minor releases.

What it does (v1.0)

• Full FieldML 0.5 read + write, round-trip validated against the C++ reference test suite
• Legacy read of FieldML 0.3 and 0.4 (auto up-conversion to 0.5)
• Evaluation engine with Lagrange (orders 1–2) and cubic Hermite-with-scaling bases
• Field.evaluate(element, xi), vectorized Field.sample(points), Jacobians
• High-level builders: add_lagrange_mesh, add_fiber_field, add_material_field, add_landmark_set, …
• Interop: meshio (two-way), PyVista (doc.plot(), doc.explore()), XDMF, scikit-fem, OpenSim-compatible asset export
• CLI: pyfieldml inspect | validate | convert | plot | lint | diff
• Curated model zoo: pyfieldml.datasets.load_femur(), load_rectus_femoris(), load_myocardium()
• JOSS paper in preparation

License

Apache 2.0. See LICENSE and NOTICE.

Install

pip install pyfieldml

Development:

git clone https://github.com/kchemorion/pyfieldml
cd pyfieldml
uv sync --extra dev
uv run pytest

Try it in your browser

The tutorial notebooks run in-browser via JupyterLite (Pyodide kernel, no install required). The site is built by .github/workflows/jupyterlite.yml and a hosted URL will be added once GitHub Pages is enabled — see docs/jupyterlite/README.md to build it locally.

Notebooks (in docs/notebooks/):

• 01_quickstart.ipynb — five-minute install / load / evaluate / export tour
• 02_evaluator_graph.ipynb — anatomy of the FieldML evaluator hierarchy
• 03_hermite_bending.ipynb — cubic-Hermite beam: derivative DOFs + basis plots
• 04_muscle_fibers.ipynb — rectus_femoris fiber-direction field + VTK glyphs
• 05_meshio_roundtrip.ipynb — FieldML → VTU → FieldML round-trip via meshio
• 06_scikit_fem_poisson.ipynb — solve Poisson on a FieldML mesh with scikit-fem
• 07_real_anatomy.ipynb — tour of the bundled Stanford Bunny + BodyParts3D femur
• 08_conformance.ipynb — self-conformance smoke test over every bundled dataset

Quickstart

import pyfieldml as fml
from pyfieldml import datasets

# Load a bundled synthetic dataset
doc = datasets.load_rectus_femoris()

# Inspect the evaluator graph
for name, ev in doc.evaluators.items():
    print(f"{name:30s}  {type(ev).__name__}")

# Evaluate the coordinate field at an element centroid
coords = doc.field("coordinates")
print("centroid of element 1:", coords.evaluate(element=1, xi=(0.25, 0.25, 0.25)))

# Export to VTK for ParaView
m = doc.to_meshio()

Cite this work

If you use pyfieldml in academic work, please cite it — see CITATION.cff for the canonical metadata, and docs/cite.md for BibTeX snippets.

Acknowledgments

pyfieldml is an independent Python reimplementation inspired by and validated against the C++ FieldML-API. Credit to its original authors — Caton Little, Alan Wu, Richard Christie, Andrew Miller, and Auckland Uniservices Ltd / the Auckland Bioengineering Institute — and to the Physiome Project community that maintains the FieldML specification.