pyfieldml 1.0.0

A modern pure-Python implementation of FieldML 0.5 with evaluation engine and biomechanics model zoo.

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 will do (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()
• Docs site with jupyter-lite in-browser runnable notebooks
• JOSS paper submitted alongside v1.0

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

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.