hyper-surrogate

Define hyperelastic materials in Python, deploy them in your finite element solver.

hyper-surrogate turns a hyperelastic material defined in Python into a self-contained Fortran 90 user subroutine (UMAT) that links directly to commercial and research finite element solvers. A material can be defined in three ways:

• Path A — built-in symbolic SEF. Pick from ten classical isotropic and anisotropic models and emit a UMAT in one line.
• Path B — custom symbolic SEF. Subclass Material with a sef property in SymPy and the framework derives stress and consistent tangent for you. See the custom materials tutorial.
• Path C — data-driven surrogate. Train an MLP, ICNN, or polyconvex ICNN on energy and stress samples from any ground-truth source and emit a hybrid UMAT whose energy is the trained network and whose mechanics is computed analytically in Fortran.

All three paths produce the same artefact — a .f90 file with Cauchy stress, the analytical consistent tangent, and stress-freedom at the reference enforced exactly at emission time.

Where to start

• Installation — pip install hyper-surrogate or uv sync --extra ml.
• Getting started — your first material, in five minutes.
• Custom materials — write your own SEF and get a UMAT.
• Fortran export — when to pick each of the three emitters.
• Examples — runnable scripts for every path.

Runnable examples for each path

Path	Example	What it does
A	examples/analytical_umat.py	Built-in NeoHooke → analytical Fortran UMAT in one line
B	examples/custom_sef.py	Custom Ogden-like SEF → analytical Fortran UMAT
C	examples/export_hybrid_umat.py	Train an MLP and emit a hybrid UMAT (NN energy + analytical mechanics)