Constitutive model (UMAT) catalog
Every constitutive law is selected by its umat_name (five letters, or the _closed
name of a kept dedicated kernel). The names live in one table, the registry of
umat_registry.cpp (umat_registry(), one row per name): the kernel that serves the name on
each face of the dispatch (small-strain mechanical, finite-strain mechanical, thermomechanical),
its finite-strain conventions and its capabilities (condensed stress states of sim.umat, the
elastic stiffness of the mean-field schemes). Every route reads it: the solver, sim.umat /
sim.umat_T, the Abaqus and Ansys bridges, the micromechanics. Since the
modular UMAT framework, four kinds of implementation coexist behind those
names — the calling convention is identical for all of them (same
umat_name, same props, same solver/FEA usage):
modular (native): the composable
MODULengine, configured from a props stream (seesimcoon.modularfor the Python builder).modular (adapter): a legacy name whose dedicated kernel was removed after its equivalence with a
MODULconfiguration was proven against the retained reference kernels — bit-identical for the elastic, power-law and Hill families and, since the modular engine runs the same cutting plane, for the Voce/Chaboche families as well (tests intest_modular.pyandTreference_umats); a translator maps the legacy props to the modular configuration at each call.legacy (kept): a dedicated, self-contained implementation kept because no modular equivalent exists.
modular (adapter); ``NAME_closed`` runs the dedicated kernel: the name runs the modular engine; the dedicated closed-form kernel stays reachable under the
_closedsuffix (benchmarks, comparisons, the readable single-file reference of the CCP return mapping), on every route the plain name takes (solver,sim.umat/sim.umat_T, AbaqusCMNAME).Python (external): the
PYEXTname serves a law written in Python (simcoon.PythonUMAT) through a registered callback; see Constitutive laws in Python (PYEXT).
Small-strain mechanical models
Name |
Physics |
Engine |
Props (in order) |
Notes |
|---|---|---|---|---|
ELISO |
Isotropic elasticity |
modular (adapter) |
E, nu, alpha |
|
ELIST |
Transversely isotropic elasticity |
modular (adapter) |
axis, EL, ET, nuTL, nuTT, GLT, alpha_L, alpha_T |
|
ELORT |
Orthotropic elasticity |
modular (adapter) |
E1, E2, E3, nu12, nu13, nu23, G12, G13, G23, alpha1, alpha2, alpha3 |
|
EPICP |
Von Mises + power-law isotropic hardening |
modular (adapter); |
E, nu, alpha, sigmaY, k, m |
The dedicated kernel ( |
EPKCP |
Von Mises + power-law isotropic + Prager kinematic |
modular (adapter) |
E, nu, alpha, sigmaY, k, m, kX |
The legacy kernel writes \(X = k_X a\), the modular twin \(X = \tfrac{2}{3} C a\), i.e. \(C = 1.5 k_X\) (handled by the adapter) |
EPCHA |
Von Mises + Voce + 2x Armstrong-Frederick |
modular (adapter); |
E, nu, alpha, sigmaY, Q, b, C1, D1, C2, D2 |
The dedicated kernel ( |
EPJCK |
Von Mises + Johnson-Cook yield stress (power-law hardening x logarithmic strain-rate factor x thermal softening) |
modular (adapter, |
E, nu, alpha, A, B, n, C, edot0, m, T_ref, T_melt |
Rate-dependent: the plastic strain rate is Dp/Dt, fully implicit in the
return mapping; the rate factor is clamped at 1 below edot0 and the cutting
plane starts at the kink ( |
EPHIL / EPTRI |
Hill yield + power-law isotropic hardening |
modular (adapter) |
E, nu, alpha, sigmaY, k, m, F, G, H, L, M, N |
Bit-identical to the modular twin (machine precision) |
EPHAC |
Cubic elasticity + Hill + Voce + 2x AF |
modular (adapter) |
E, nu, G, alpha, sigmaY, Q, b, C1, D1, C2, D2, F, G, H, L, M, N |
statev columns beyond the modular layout are unused (see below) |
EPANI |
Cubic elasticity + 9-parameter anisotropic yield + Voce + 2x AF |
modular (adapter) |
E, nu, G, alpha, sigmaY, Q, b, C1, D1, C2, D2, P11, P22, P33, P12, P13, P23, P44, P55, P66 |
P must be an admissible (convex) quadratic form: symmetric with zero row sums on the normal block; an indefinite P yields sqrt(<0) = NaN |
EPDFA |
Cubic elasticity + Deshpande-Fleck-Ashby yield + Voce + 2x AF |
modular (adapter) |
E, nu, G, alpha, sigmaY, Q, b, C1, D1, C2, D2, F, G, H, L, M, N, K |
|
EPCHG |
Cubic elasticity + selectable yield + N-term “Voce” + N-term Chaboche |
modular (adapter) |
E, nu, G, alpha, sigmaY, N_iso, N_kin, criteria(0=Mises, 1=Hill, 2=DFA, 3=anisotropic), (Q_i, b_i) x N_iso, (C_i, D_i) x N_kin, criterion parameters |
The legacy N-term isotropic hardening couples all terms through a single Hp (dHp/dp = sum b_i (Q_i - Hp)): mathematically ONE effective Voce with b_eff = sum(b_i), Q_eff = sum(b_i Q_i)/sum(b_i) — not the standard combined-Voce sum. The adapter maps accordingly. |
EPHIN |
N Hill yield surfaces, each with power-law isotropic hardening |
modular (adapter) |
E, nu, alpha, N, then per surface: sigmaY, k, m, F, G, H, L, M, N |
The removed legacy kernel was defective for N >= 2 (NaN even for identical or inactive second surfaces); the modular engine handles multiple surfaces correctly, so N >= 2 is now functional. |
ZENER |
Standard linear solid, Poynting-Thomson (Kelvin) form: spring in series with one Kelvin-Voigt unit |
modular (adapter); |
E0, nu0, alpha, E1, nu1, etaB1, etaS1 |
The adapter runs the one-branch Maxwell composition with the Kelvin unit
mapped per isotropic mode (\(X_M = X_0^2/(X_0 + X_1)\),
\(\eta_M = \eta_K X_0^2/(X_0 + X_1)^2\), |
ZENNK |
Generalized KELVIN chain, N branches |
legacy (kept) |
E0, nu0, alpha, N, then per branch: E_i, nu_i, etaB_i, etaS_i |
Kelvin units in series: NOT equivalent to PRONK despite the identical props layout (measured 86% response difference); the Kelvin-to-Maxwell map of ZENER has no closed form for N >= 2 |
PRONK |
Generalized Maxwell (Prony series), N branches |
modular (adapter); |
E0, nu0, alpha, N, then per branch: E_i, nu_i, etaB_i, etaS_i |
The dedicated kernel ( |
LLDM0 |
Ladevèze-Le Dantec damage of the unidirectional ply (d22, d12), plasticity in effective stress |
legacy (kept) |
see header (18 props, 10 statev) |
Modular equivalence not yet established (audit pending) |
MODUL |
Composable modular UMAT (elasticity + N mechanisms) |
modular (native) |
self-describing stream — build it with
|
Also available under finite strain (NLGEOM control types 2-6), where
the composition is a Hencky hyperelastic law on the logarithmic
strain; requires |
Shape memory alloys, finite strain, multiscale, plugins
Unchanged dedicated implementations (out of the modular scope):
SMA: SMADI/SMADC/SMAAI/SMAAC (unified), SMRDI/SMRDC/SMRAI/SMRAC (unified with reorientation), SMAMO/SMAMC (monocrystal).
Finite strain: HYPOO (hypoelastic orthotropic), SNTVE (Saint-Venant), OGDEN (isochoric principal stretches, props =
N, kappa, mu_1, alpha_1, ...) are kernels built on \(\mathbf{F}\). The invariant-based hyperelastic names NEOHI/NEOHC (Neo-Hookean), MOORI, YEOHH, ISHAH, GETHH, SWANH and HOLZA run theHYPER_INVARIANTSblock of the modular engine through a props adapter (the same potential, the same props): a potential of the logarithmic strain, served under corate 3 (log_R) and the total formulation only, asMODUL;statevis[T_init].NEOHC_closedandNEOHI_closedkeep the kernels built on \(\mathbf{F}\), which serve every corate and the native material tangent (comparisons,test_finite_tangents). The compressible potentials take one optional trailing prop selecting the volumetric term \(U(J)\): absent or 0 for \(\kappa (J \ln J - J + 1)\), 1 for \(\frac{\kappa}{2} (J - 1)^2\) (NEOHI is the Neo-Hookean potential with the latter form, \(\mu = E/2(1+\nu)\), \(\kappa = E/3(1-2\nu)\), i.e. \(C_{10} = \mu/2\), \(1/D_1 = \kappa/2\)).HOLZA is the Gasser-Ogden-Holzapfel model, the only anisotropic one of the set: an isotropic neo-Hookean matrix reinforced by \(n\) families of dispersed fibres,
\[W = C_{10} \left(\bar{I}_1 - 3\right) + \sum_i \frac{k_1}{2 k_2} \left[ \exp\left(k_2 \left(\bar{I}^{*}_{4,i} - 1\right)^2\right) - 1 \right] + U(J),\]with \(\bar{I}^{*}_{4,i} = \kappa_d \bar{I}_1 + (1 - 3 \kappa_d) \bar{I}_{4,i}\) and \(\bar{I}_{4,i} = \mathbf{a}_{0,i} \cdot \bar{\mathbf{C}} \, \mathbf{a}_{0,i}\). The dispersion \(\kappa_d \in [0, 1/3]\) interpolates between perfectly aligned fibres (\(\kappa_d = 0\), the Holzapfel-Gasser-Ogden 2000 model) and an isotropic distribution (\(\kappa_d = 1/3\)). The fibre term is inactive wherever \(\bar{I}^{*}_{4,i} < 1\), which is the switch of the original Gasser-Ogden-Holzapfel formulation. Note it is a condition on the generalized invariant, not on fibre compression: once \(\kappa_d > 0\) the term picks up a \(\kappa_d \bar{I}_1\) contribution, so a fibre with \(\bar{I}_{4,i} < 1\) can still be active (at \(\kappa_d = 0.2\) a fibre shortened to 0.39 of its length gives \(\bar{I}^{*}_4 = 1.12\)).
Parameters in the papers and in other codes. The matrix coefficient is \(C_{10}\) here and in Abaqus, the shear modulus \(c = 2 C_{10}\) (written \(\mu\) in 2000) in the papers, FEBio and matadi. The volumetric terms differ, but all are fixed by the same ground-state bulk modulus \(K = U''(1)\); the papers treat the material as incompressible.
quantity
Gasser et al. 2006 (Holzapfel et al. 2000)
simcoon
HolzapfelElasticity/HOLZAAbaqus
*ANISOTROPIC HYPERELASTIC, HOLZAPFELFEBio
Holzapfel-Gasser-Ogdenmatrix
\(c\) (\(\mu\))
C10\(= c/2\)\(C_{10} = c/2\)
cfibre stiffness
\(k_1\)
k1\(k_1\)
k1fibre exponent
\(k_2\)
k2\(k_2\)
k2dispersion
\(\kappa\) (0 in 2000)
kappa_d\(\kappa\)
kappafibre families
two, at \(\pm\gamma\) (\(\pm\beta\) in 2000) from the circumferential direction, in the tangent plane
fibres: one rotation of \(\mathbf{e}_1\) per family in the local frame,Rotation.from_euler("zxz", [[0, 0, g], [0, 0, -g]], degrees=True); propsn_famand the unit directionstwo local directions (
*ORIENTATION,LOCAL DIRECTIONS)gamma, angle in a plane of the local framebulk modulus
incompressible
kappa\(= K\);volumetric="log": \(K (J \ln J - J + 1)\),"quadratic": \(K (J-1)^2/2\)\(D = 2/K\), \(U = \frac{1}{D}\left(\frac{J^2 - 1}{2} - \ln J\right)\)
k(FEBio’s own \(U(J)\), see its manual)The 2006 paper rewrites the 2000 model around a generalized structure tensor; the notations map as follows (the 2006 model with \(\kappa = 0\) is the 2000 one).
Holzapfel, Gasser, Ogden 2000
Gasser, Ogden, Holzapfel 2006
simcoon
structure tensor
\(\mathbf{A}_i = \mathbf{a}_{0i} \otimes \mathbf{a}_{0i}\)
\(\mathbf{H}_i = \kappa \mathbf{I} + (1 - 3\kappa)\,\mathbf{a}_{0i} \otimes \mathbf{a}_{0i}\)
built from
kappa_dandfibresfibre strain
\(\bar{I}_4 - 1\), \(\bar{I}_6 - 1\) (\(\bar{I}_{4,6} = \bar{\mathbf{C}} : \mathbf{A}_{1,2}\))
\(\bar{E}_i = \mathbf{H}_i : \bar{\mathbf{C}} - 1 = \kappa (\bar{I}_1 - 3) + (1 - 3\kappa)(\bar{I}_{4,i} - 1)\)
the same quantity, written \(\bar{I}^{*}_{4,i} - 1\) (\(\bar{I}^{*}_{4,i} = \kappa_d \bar{I}_1 + (1 - 3\kappa_d) \bar{I}_{4,i} = \mathbf{H}_i : \bar{\mathbf{C}}\))
fibre energy
\(\frac{k_1}{2 k_2} \sum_{i = 4, 6} \left[ e^{k_2 (\bar{I}_i - 1)^2} - 1 \right]\)
\(\bar{\Psi}_{f i} = \frac{k_1}{2 k_2} \left[ e^{k_2 \bar{E}_i^2} - 1 \right]\)
same, summed over the families
dispersion
none (aligned fibres)
\(\kappa = \frac{1}{4} \int_0^\pi \rho(\Theta) \sin^3\Theta \, d\Theta\), with \(\rho\) a von Mises density of concentration \(b\)
kappa_d(kappais the bulk modulus in simcoon)fibre angle
\(\beta\)
\(\gamma\)
fibreswall thickness (tube)
\(H\)
\(H\) (also the letter of the structure tensor)
not a material parameter
matadi (
holzapfel_gasser_ogden) takesc,k1,k2,kappaand the fibreangleabout anaxis;axis=2, angle=gis the plane and the convention of the rotation above (checked to 1.6e-14 on the stress against simcoon, quadratic \(U(J)\)). The example Anisotropic hyperelasticity - inflation of an arterial layer (HOLZA) reproduces figure 7 of Gasser et al. (2006) with the parameters of the iliac adventitia, \(c = 7.64\) kPa, \(k_1 = 996.6\) kPa, \(k_2 = 524.6\), \(\gamma = 49.98^\circ\), \(\kappa = 0.226\).props =
C10, k1, k2, kappa_d, n_fam, a0x_1, a0y_1, a0z_1, ..., kappa, where each \(\mathbf{a}_{0,i}\) is a unit direction in the local material frame (the solver’s material orientation places it globally, as for ELIST/ELORT). From Python the directions are given as asimcoon.Rotationapplied to \(\mathbf{e}_1\), one entry per family, which keeps Euler angles and their gimbal lock off the path to the kernel:sim.modular.HolzapfelElasticity( C10=0.0354, k1=0.0107, k2=7.48, kappa_d=0.0, fibres=sim.Rotation.from_euler('zxz', [[0, 0, 40], [0, 0, -40]], degrees=True), kappa=1000.)
The same potential is available as a MODUL elasticity block, and may be composed with any mechanism. Composed with damage – anisotropic tissue with softening – the kinematics are exact: damage subtracts no inelastic strain (it scales the stiffness instead), so the elastic stretch is the total one and the fibres follow it. Its driving force is the thermodynamic force \(Y = -\partial\Psi/\partial D = \Psi_0\), the undamaged energy, evaluated as \(\tfrac12\,\boldsymbol{\tau}_{eff} : \mathbf{M}_t : \boldsymbol{\tau}_{eff}\) on the effective stress \(\boldsymbol{\tau}/(1-D)\): exact for a linear block, an approximation of \(\Psi_0\) through the tangent compliance for this nonlinear potential.
Warning
Composed with a mechanism that does subtract an inelastic strain (plasticity, viscoelasticity), the fibre convection is approximate. The block carries \(\mathbf{a}_{0,i}\) from the reference configuration and pushes it forward with the elastic stretch, so the inelastic strain does not reorient the fibres. The composition is well posed and converges – the return mapping is handed the anisotropic tangent and its consistency condition holds exactly – but the response is only as good as that assumption: exact while the inelastic strain is small or leaves the fibre directions fixed, degrading as it reorients them. Representing the convection exactly would require the convected directions as state variables, which the additive corotational kinematics of the modular UMAT cannot express (there is no plastic deformation gradient to convect with).
A second, separate caveat applies to viscoelasticity only: every Prony branch is built as an isotropic \(\mathbf{L}_i(E_i, \nu_i)\), so the viscous response carries none of the fibre anisotropy while the equilibrium response does. That is a property of the viscoelastic mechanism’s \((E_i, \nu_i)\) parameterization rather than of HOLZA – a Prony branch cannot follow an ELORT or ELIST block’s symmetry either.
Neither is rejected at run time; both are modelling choices left to the user.
A single scalar damage variable, finally, degrades matrix and fibres at the same rate. The Holzapfel damage literature instead carries separate variables – one on the isotropic term and one per fibre family – since collagen and ground substance damage very differently. simcoon’s damage mechanism is a single scalar, so the composition models uniform softening, not anisotropic damage.
Multiscale: MIHEN, MIMTN, MISCN, MIPLN. Their sub-phases are passed in memory (
phases=, see In-memory Python solver) and theirpropshold only the scheme’s settings:[mp, np]for MIHEN,[mp, np, n_matrix]for MIMTN,[mp, np, n_matrix]or[mp, np, n_matrix, start]for MISCN, nothing for MIPLN (mp,np: integration points of the Eshelby integrals;n_matrix: index of the matrix phase in the list;start: first guess of the self-consistent iteration, 1 Mori-Tanaka (default) or 0 homogeneous strain withn_matrix < 0). The length and the values are checked, so the pre-2.0 layout with its leadingnphasesand file-number slots is refused rather than misread.Optional trailing slots set numerical options; all default to 0, the historical behaviour (giving a slot gives the ones before it). The same settings by name:
MoriTanaka,SelfConsistent,HomogeneousandPeriodicLayersofsimcoon.solver.micromechanicsbuild these lists (see In-memory Python solver):[mp, np, n_matrix, closed_form, rule]for MIMTN and[mp, np, n_matrix, start, closed_form, rule, anderson, rtol]for MISCN.closed_form = 1: the Eshelby tensor is taken in closed form (sphere, prolate or oblate spheroid of axis 1) when the reference medium is isotropic, and integrated otherwise. Exact, and no integration:L_effof a self-consistent composite of spheres is 7 to 10 times faster (20 times withanderson = 2).rule = 1: half-sphere quadrature,(mp+1)/2Gauss-Legendre points incos(theta)andnptrapezoidal points inphi(the integrand is centrally symmetric and periodic inphi): half the evaluations of the default Gauss-Legendre rule for the same accuracy or better.anderson = m(MISCN,L_effonly): Anderson acceleration of depthmof the self-consistent fixed point (m = 2is a good choice: 65 iterations become about 11 at a 50 % concentration). The solver does one self-consistent sweep per localization iteration and ignores it.rtol > 0(MISCN,L_effonly): relative stopping criterion||L - L_prev|| <= rtol ||L||of that fixed point instead of the absolute1e-6(in the stiffness unit), so the iteration count no longer depends on the unit.
Plugins: UMEXT (external dylib), UMABA (Abaqus wrapper).
Python: PYEXT (registered Python law;
props/nstatevfrom the object).
State variable (statev) layout for adapter-served names
The modular engine claims the FIRST required_nstatev slots of the caller’s
statev array — always within the legacy allocation, so array sizes never
change. For ELISO/ELIST/ELORT (T_init) and EPHIL/EPTRI
(T_init, p, EP(6)) the column meaning is identical to the removed kernels.
For the Chaboche-family names and EPKCP the columns re-mean: the layout is
T_init | p, EP(6) | back-strains a_i(6) ... in mechanism registration
order; trailing legacy slots are left untouched. Code that read specific
legacy statev columns (e.g. the stored X_i of EPHAC) must be updated to the
modular layout.
Stress measure and tangent rate
Every native simcoon kernel is Kirchhoff-native. In the logarithmic framework an isotropic stored energy per reference volume gives \(\boldsymbol{\tau} = \partial W / \partial \ln \mathbf{V}\) (for an anisotropic one the identity needs \(\boldsymbol{\tau}\) coaxial with \(\mathbf{V}\)), so \(\boldsymbol{\tau}\) is the route stress, and the Cauchy stress is the derived output \(\boldsymbol{\sigma} = \boldsymbol{\tau}/J\), formed only at the boundaries – the solver’s output sinks and the Python wrapper. Nothing on the route carries Cauchy.
The stress measure a kernel writes into sigma is declared, one entry per kernel, in
the registry (umat_entry::convention, umat_registry.cpp; read through
output_convention_of). A name without a finite-strain kernel is rejected by the finite
route rather than given a default – a missing declaration is an error of exactly
\(J\), and invisible near \(J = 1\):
kirchhoff– every native kernel.cauchy– only the host pluginsUMABA/UMANS, whose contract belongs to the host code (Cauchy stress, a Jaumann or Green-Naghdi Jacobian).select_umat_M_finitehands them \(\boldsymbol{\sigma}_n = \boldsymbol{\tau}_n / J_n\), converts their stress to \(\boldsymbol{\tau}\) on the way out and their Jacobian to the box of the solver’s corate (UMEXTis a Kirchhoff box, asPYEXT; see External).
HYPOO is native too: it integrates the corotational Kirchhoff rate,
\(\boldsymbol{\tau}_{n+1} = \boldsymbol{\tau}_n + \mathbf{L} : \Delta\boldsymbol{\varepsilon}^{el}\),
and is the rate counterpart of ELORT (total form
\(\boldsymbol{\tau} = \mathbf{L} : \boldsymbol{\varepsilon}^{el}\)). With the same
\(\mathbf{L}\), isotropic or anisotropic, the two are identical on any path for corates
0 to 3: with the material axes following the body, the transported strain and stress satisfy
the same recursion (a ~74 % orthotropic shear gap measured before 2.1 came from lab-fixed
axes, not from the rate form). They differ under corate 4 even for an isotropic
\(\mathbf{L}\): ELORT is then the total Almansi law
\(\boldsymbol{\tau} = \lambda\,\mathrm{tr}(\mathbf{e}_A)\mathbf{I} + 2\mu\,\mathbf{e}_A\), HYPOO
integrates the Oldroyd rate of \(\boldsymbol{\tau}\), whose isochoric solution is
\(\boldsymbol{\tau} = \mu(\mathbf{b} - \mathbf{I})\). In simple shear both give
\(\tau_{12} = \mu\gamma\); the normal stresses differ, \(\tau_{11} = \mu\gamma^2\),
\(\tau_{22} = \tau_{33} = 0\) for HYPOO against \(\tau_{11} = \tau_{33} = -\lambda\gamma^2/2\),
\(\tau_{22} = -(\lambda/2 + \mu)\gamma^2\) for ELORT. Under corate 5 they differ for an
anisotropic \(\mathbf{L}\) only (about 6 % measured in orthotropic shear): the similarity
transport by a rotation-free stretch does not commute with it. For an
anisotropic \(\mathbf{L}\) the common law \(\boldsymbol{\tau} = \mathbf{L}_R :
\ln\mathbf{V}\) is Cauchy-elastic, not hyperelastic.
Material frame. On the finite route the kernels fed the logarithmic strain (ELISO, ELIST,
ELORT, HYPOO, the plasticity names, MODUL, PYEXT) run in a frame that follows the
material: the accumulated corate rotation for corates 0 to 3, the polar rotation of
\(\mathbf{F}\) for 4 and 5. Their anisotropy axes (orthotropic and transversely isotropic
stiffness, Hill-type criteria, HOLZA fibres, in MODUL and through the hyperelastic names)
therefore rotate with the body, as with Abaqus *ORIENTATION under NLGEOM, and their tensorial
Statev are material-frame components. The kernels built from \(\mathbf{F}\) (SNTVE,
NEOHC_closed, NEOHI_closed, OGDEN) are objective by construction and keep the lab frame.
The tangent rate is not declared, it is deduced from the solver’s ``corate_type``. Every
kernel receives the solver’s corate_type and must return \(\mathbf{L}_t\) expressed in
it. A kernel that builds its tangent from \(\mathbf{F}\) – the finite hyperelastic family –
converts the spatial (Lie/Oldroyd) closed form of the potential in one step, with
Dtau_LieDD_2_DtauDe_corate; a kernel handed the solver’s already-corotated strain
increment is in that rate for free. Per corate: 0 Jaumann and 1 Green-Naghdi are spin/rate
corrections, 2 (XBM) and 3 (log_R) share the exact spectral map, and 4 (Truesdell) is the
convected box, which is the spatial (Lie) tangent – an identity: the Kirchhoff stress is
transported upper-convected and the strain lower-convected, so the strain is the Almansi strain
\(\mathbf{e}_A = \tfrac12(\mathbf{I} - \mathbf{b}^{-1})\) (the Strain output; see
Read the results). Logarithmic control (control type 3) still prescribes \(\ln\mathbf{V}\)
under corate 4: the solver rebuilds it from the stored strain,
\(\ln\mathbf{V} = -\tfrac12\ln(\mathbf{I} - 2\mathbf{e}_A)\).
5 (log_F) is the chain rule through its own increment \(\mathbf{D}_e = \mathbb{A}^F :
\mathbf{D}\,\Delta t\), \(\mathbb{C}^J : (\mathbb{A}^F)^{-1}\), equal to the log box for
isotropic laws (both finite-difference verified).
Note
The solver transports the total strain, the start stress and the tensorial internal
variables with the variance each corate requires: rotation for 0-3 (in the material frame the
frame-relative increment is the identity, so a kernel is called with
\(\Delta\mathbf{R} = \mathbf{I}\)); for 4, lower-convected strain-like and upper-convected
stress-like quantities; for 5, similarity. For 4 and 5 the dispatcher applies it to the
internal variables each kernel declares in the registry (umat_registry.cpp: EPICP,
EPJCK, EPCHA, the elastic and hyperelastic kernels); a kernel that has not declared them (the
plasticity names served by the modular engine, PYEXT) is refused under corates 4 and 5,
and MODUL under any corate but 3 (it runs under the total formulation). Under the total formulation nothing is transported
(see the total formulation below). EPCHA is also refused under corate 4: it stores
\(\mathbf{X}_i = \tfrac23 C_i\,\mathbf{a}_i\), and the Truesdell rate convects the
back-strain and the back-stress differently.
Mechanical work. Wm is the work per reference volume,
\(\int \mathbf{P} : \mathrm{d}\mathbf{F}\). A kernel accumulates
\(\tfrac12(\hat{\boldsymbol{\tau}}_n + \boldsymbol{\tau}_{n+1}) : \Delta\mathbf{e}\) on the strain
increment it is handed, \(\hat{\boldsymbol{\tau}}_n\) being the start stress transported to the
end configuration. Per corate:
0, 1 (Jaumann, Green-Naghdi): \(\Delta\mathbf{e} = \mathbf{D}\,\Delta t\), the kernel work converges to the true work at second order.
2 (XBM): the rate is conjugate, \(\mathbf{D} = (\ln\mathbf{V})^{\circ\log}\), so there is no continuum gap.
3, 5 (log_R, log_F): \(\boldsymbol{\tau} : \dot{\mathbf{e}} \neq \boldsymbol{\tau} : \mathbf{D}\) as soon as \(\boldsymbol{\tau}\) is not coaxial with \(\mathbf{V}\) (anisotropy, plasticity).
4 (Truesdell): the kernel work is exactly the trapezoid \(\tfrac12(\mathbf{S}_n + \mathbf{S}_{n+1}) : \Delta\mathbf{E}\).
Under 2, 3 and 5 the solver replaces the kernel work by the midpoint stress power with both
stresses in the lab frame, \(\tfrac12(\boldsymbol{\tau}_n + \boldsymbol{\tau}_{n+1}) :
\mathrm{sym}\big(2(\mathbf{F}_1 - \mathbf{F}_0)(\mathbf{F}_1 + \mathbf{F}_0)^{-1}\big)\), which is the
trapezoid of \(\mathbf{P} : \mathrm{d}\mathbf{F}\) itself and zero under a rigid rotation (Delta_work_conjugacy).
The difference is added to \(W_m\) and \(W_m^r\), so \(W_m^r\) then holds the stored
energy plus the work the rate does not conjugate: under 3 and 5, in non-coaxial states, it is not
a state function. simcoon.umat() does the same when it is given
\(\mathbf{F}_0, \mathbf{F}_1\), recovering the lab start stress from the one it is passed
(transported by the caller) as \(\mathrm{sym}(\Delta\mathbf{R}^{-1}\hat{\boldsymbol{\tau}}_n\Delta\mathbf{R})\).
Note
Under the rate formulation MODUL passes corate 3 unconditionally rather than the solver’s value, because it
evaluates its potential at \(\mathbf{V}^{el}\) in the corotated frame
(\(\mathbf{R} = \mathbf{I}\)), where the log box with respect to
\(\ln \mathbf{V}^{el}\) is
\(\partial \boldsymbol{\tau} / \partial \boldsymbol{\varepsilon}^{el}\). Any other
corate is already refused upstream under NLGEOM, so passing one down would not be more
general – it would be wrong. Under the total formulation the block is told so
(KinematicForm::total) and returns \(\mathbf{T}\) and
\(\partial\mathbf{T}/\partial\mathbf{H}^{el}\) instead.
The total formulation (strain space, kinematic_form="total" ). Under the rate
formulation a law works on \(\ln\mathbf{V}\) (with the logarithmic rates) and the Kirchhoff stress
\(\boldsymbol{\tau}\); under the total formulation it works on \(\ln\mathbf{U}\) and the
stress \(\mathbf{T}\) dual to it. It is not an objective rate: no rate and no spin are
involved, and corate must be left unset. This is the total-Lagrangian
framework of Miehe, Apel and Lambrecht (Comput. Methods Appl. Mech. Engrg. 191, 2002,
5383-5425). A log-strain box is fed the material Hencky strain
\(\mathbf{H} = \tfrac12\ln\mathbf{C} = \ln\mathbf{U}\), a state function of
\(\mathbf{F}\) in reference components; the frame increment is the identity and the internal
variables are never transported. Its output is the stress \(\mathbf{T}\) conjugate to
\(\mathbf{H}\) per reference volume,
\(\mathbf{T}:\dot{\mathbf{H}} = \mathbf{S}:\dot{\mathbf{E}} = \boldsymbol{\tau}:\mathbf{D}\), and
the geometry is applied once, after the box:
This is the one exception to “the kernel’s sigma is \(\boldsymbol{\tau}\)”: under the total
formulation the sigma of a box kernel is \(\mathbf{T}\). No kernel changes; the dispatcher converts at entry
(Kirchoff2LogStressU) and at exit (LogStressU2Kirchoff), and \(\boldsymbol{\tau}\) stays the only
stress on the route. In the eigenbasis of \(\mathbf{C}\), with \(\lambda_a\) the principal
stretches,
which in Voigt form is \((\mathbf{A}^R)^T\) applied to \(\mathbf{R}\,\mathbf{T}\,\mathbf{R}^T\).
Relation to the rate formulation under corate 3. Under log_R a box kernel already runs in the rotated frame, on \(\mathbf{R}^T(\ln\mathbf{V})\mathbf{R} = \mathbf{H}\): the two formulations share the box, its strain and its internal variables. They differ in two ways.
The strain increment is the closed form \(\mathbf{H}(\mathbf{F}_1) - \mathbf{H}(\mathbf{F}_0)\) here, against the integral of \(\mathbf{A}^R:\mathbf{D}\) there, whose residue is first order in the step. An elastic law is therefore exact in a single increment.
The box output is read as \(\mathbf{T}\) here and as \(\mathbf{R}^T\boldsymbol{\tau}\,\mathbf{R}\) there. Since \(\kappa_{aa} = 1\) and \(\kappa_{ab} \le 1\), the two readings are identical when the stress is coaxial with \(\mathbf{U}\) (isotropic elasticity, proportional plasticity), and differ otherwise. These are two constitutive statements, not two accuracies of one. A yield criterion holds on \(\mathbf{T}\) here and on \(\boldsymbol{\tau}\) there: in simple shear to \(\gamma = 1\) with \(\sigma_Y = 250\) MPa, the Cauchy shear and normal stresses are 140.9 and -15.7 MPa here against 144.4 and -8.4 MPa under log_R, and the difference does not vanish with the step. An anisotropic elastic law \(\mathbf{T} = \mathbf{L}:\mathbf{H}\) derives from a stored energy with its axes on the reference frame, so a closed path stores no net work; read as \(\boldsymbol{\tau} = \mathbf{R}(\mathbf{L}:\mathbf{H})\mathbf{R}^T\) it is only Cauchy-elastic.
Reading one run in the measures of the other. \(\ln\mathbf{V} = \mathbf{R}\,\mathbf{H}\,\mathbf{R}^T\)
and \(\boldsymbol{\tau} \leftrightarrow \mathbf{T}\) are changes of measure, valid for any state:
sim.stress_convert has the keys "Kirchoff2LogStressU" and "LogStressU2Kirchoff", and the solver
results offer LogStrainU, LogStrainV and LogStressU whenever the strain of the run is
a state function of \(\mathbf{F}\) (see Read the results). On a path of prescribed
\(\mathbf{F}\), and for a log-strain box kernel, a run under corate 3 and a run under the
total formulation then compare as follows: the box output is the same, \(\mathbf{R}^T\boldsymbol{\tau}_{\text{rate}}\mathbf{R} =
\mathbf{T}_{\text{total}}\), and the two Kirchhoff stresses differ by the map above,
\(\boldsymbol{\tau}_{\text{total}} = (\mathbf{A}^R)^T\boldsymbol{\tau}_{\text{rate}}\), up to the
first-order quadrature of the log_R strain. Under the other rates the box does not see
\(\mathbf{H}\) in the polar frame and this comparison has no meaning.
Scope. Log-strain box kernels (ELISO, ELIST, ELORT, EPICP, EPJCK, EPCHA,
the plasticity and hyperelastic names served by the modular engine, and PYEXT, whose Python
law then receives \(\ln\mathbf{U}\) and must return \(\mathbf{T}\)), and the kernels built on
\(\mathbf{F}\) (NEOHI_closed, NEOHC_closed, OGDEN, SNTVE). The latter return the
true \(\boldsymbol{\tau}\) in both
formulations, so their stress does not depend on it; the dispatcher forms their work on the dual
pair, \(\tfrac12(\mathbf{T}_n + \mathbf{T}_{n+1}):\Delta\mathbf{H}\) with
\(\mathbf{T}\) computed from \(\boldsymbol{\tau}\), and their box is
\(\partial\mathbf{T}/\partial\mathbf{H}\). The rate law HYPOO integrates from its start
stress and is refused. MODUL is a log-strain box and is served: its mechanisms work on
\(\mathbf{H}\) and \(\mathbf{T}\) as those of EPICP do, and its hyperelastic block
returns \(\mathbf{T} = \partial\Psi/\partial\mathbf{H}^{el}\) with
\(\partial\mathbf{T}/\partial\mathbf{H}^{el}\). A fibre block (Holzapfel) is then the law built
on \(\mathbf{F}\) at any step, where under corate 3 it converges to it at first order.
"logarithmic" control is refused too (the stored strain is \(\ln\mathbf{U}\)). The work of
a box kernel is its own \(\tfrac12(\mathbf{T}_n + \mathbf{T}_{n+1}):\Delta\mathbf{H}\): the
trapezoidal rule on a conjugate pair, second order in the step, with no correction to apply. Through simcoon.umat() the caller passes
kinematic_form="total", \(\mathbf{H}(\mathbf{F}_0)\),
\(\mathbf{H}(\mathbf{F}_1) - \mathbf{H}(\mathbf{F}_0)\),
\(\Delta\mathbf{R} = \mathbf{I}\), and both deformation gradients; the stress stays Cauchy in
and out, tangent_output="box" is \(\partial\mathbf{T}/\partial\mathbf{H}\) and its
Lt_convert key to \(\mathrm{d}\mathbf{S}/\mathrm{d}\mathbf{E}\) is DTDH_2_DSDE.
The Python contract. sim.umat returns Cauchy stress and the Kirchhoff box
tangent \(\partial \hat{\boldsymbol{\tau}} / \partial \mathbf{D}_e\) with no \(J\),
and, under the rate formulation, takes the objective rate as kinematic_form= (corate=, its
former name; default 3, log_R)
selecting the rate that tangent is expressed in. The default is contract-preserving: corates 2 and 3 resolve to the same exact map, so it
returns precisely the box the finite kernels used to produce unconditionally. Rescaling that
tangent by \(1/J\) at the boundary would break Lt_convert by exactly \(J\).
Integrator and tangent operator
A run makes three numerical choices for the laws with a return mapping, given to solve
and sim.umat by name:
Option |
Chooses |
Values |
Changes the converged answer |
|---|---|---|---|
|
the discrete update of the local step |
|
yes: two different schemes |
|
how the Kuhn-Tucker conditions are solved inside it |
|
no, to the local tolerance (see below) |
|
the operator handed to the global Newton |
|
no: global convergence only |
"algorithmic" is the consistent operator of the integrator that ran: Simo-Hughes after the
cutting plane, the exact operator of the closest-point map after the closest point. The closest
point is offered with that operator only (integrator="closest_point" with "none" or
"continuum" raises ValueError). tangent_mode = 3 ("closest_point"), the former way
to ask for the closest point, is no longer accepted: it raises ValueError, pointing to
integrator="closest_point". Inside, the kernels still read one code (kernel_tangent_mode,
parameter.hpp): 0 = none (Lt = elastic L, explicit integration), 1 = continuum,
2 = algorithmic/Simo-Hughes (default), 3 = the closest-point integrator with its exact
operator. Code 3 reaches only the laws that implement it (check_integrator_serves; closest-point
coverage below), so a
Python law (PYEXT) receives 0, 1 or 2. Pre-2.0 numbering was 0 = continuum,
1 = algorithmic — see Use the solver for the migration note. The
finite-strain hyperelastic models ignore the mode (their tangent is always
the exact one of the hyperelastic law). So do the linear viscoelastic models (ZENER,
ZENNK, PRONK and their thermomechanical versions) except for mode 0: their
backward-Euler step is solved in closed form, so the tangent, and for the thermomechanical
versions dSdT and the heat-source derivatives drdE, drdT, are the exact
derivatives of the discrete update. For plasticity, the algorithmic operator is exact with a
von Mises criterion and isotropic hardening only; with kinematic hardening or a Hill, DFA,
Drucker or Tresca criterion the cutting-plane update is path dependent and the operator is
approximate (see the note on the scope of the algorithmic tangent in Use the solver).
Closest-point coverage (2.2). The closest-point integrator with its exact operator runs for
MODUL rows whose criterion has a flow Hessian (von Mises, Hill, DFA, Ani; with every
hardening law and a hyperelastic block) and for the legacy names the modular engine serves,
for the dedicated kernels EPICP_closed, EPCHA_closed (EPICP_closed / EPKCP_closed
thermomechanical), and for the SMA kernels SMADI / SMADC /
SMAAI / SMAAC and SMRDI / SMRDC / SMRAI / SMRAC (analytic total
derivatives through the mean transformation strain and the reorientation back-strain; about
2x the cost of mode 2 per increment on a superelastic loop, 3x with the reorientation row,
up to 5x on a non-proportional path, for an operator exact to \(10^{-8}\)). For
EPJCK (and the adapter-served von Mises + isotropic names) mode 3 is identical to mode
2 by construction: with a radial flow the cutting-plane update already is the closest-point
projection and the algorithmic operator is the exact Jacobian of the discrete map, including
the rate term. Any other law, the thermomechanical SMA kernel and SMA_mono included, refuses
integrator="closest_point" with ValueError rather than running its cutting plane
silently; inside MODUL, a Tresca or Drucker row keeps the cutting plane and its mode-2
operator. A condensed stress state (plane stress, beam,
truss) keeps mode 3: the law runs 3D and the state is solved around it.
Numerical options of the local Newton
These options change how the local return mapping is solved, not the constitutive law. They
are settings of the run, not material parameters: they are given to solve or sim.umat
by name, and the props stay those of the law.
ncp: a faster local solve for simple plasticity
solve(..., ncp="min") or sim.umat(..., ncp="min") switches the complementarity function
of the cutting plane from Fischer-Burmeister (ncp="fischer_burmeister", the default, the
historical results bit for bit) to the min function, the classic cutting-plane step. The modular
engine (MODUL and the legacy names it serves, mechanical and thermomechanical) and
EPICP_closed read it, in their cutting plane and in their closest point (the step of the
reduced Newton). Any other law or a mean-field model raises ValueError for ncp="min".
Use it for a single yield surface with isotropic or linear (Prager) kinematic hardening.
The return is the same to the local tolerance, and the local iterations drop from about 6 to 3.
In MODUL this includes a yield surface composed with viscoelastic (Prony) or damage
mechanisms: their rows are always satisfied and uncoupled, so the min step applies to the yield
surface next to them. With several coupled yield surfaces the option has no effect:
Fischer-Burmeister is kept.
If the min step makes the error grow, the solver switches back to Fischer-Burmeister for the
rest of the increment.
Do not use it with Armstrong-Frederick (Chaboche) back stresses. MODUL refuses the
combination, and the Chaboche kernels do not take the option. Those back stresses are integrated
along the cutting-plane iterates, so the full min steps land on a different answer, without
any growth in the residual that the fallback could detect. On coarse increments of the
Chaboche identification programmes, this answer is up to 46 % off the closest-point update,
where Fischer-Burmeister stays within 4 %. For an accurate Chaboche return, use
integrator="closest_point".
How the two functions work
At each increment the law seeks the plastic multiplier \(\Delta p\) of each yield surface that satisfies the Kuhn-Tucker conditions
with \(\Phi\) the yield function (for EPICP, \(\Phi = \sigma_{Mises} - R(p) - \sigma_Y\)): either the point stays elastic (\(\Delta p = 0\), \(\Phi \le 0\)) or it lies on the surface (\(\Phi = 0\), \(\Delta p > 0\)). The cutting plane solves them by Newton on \(\Delta p\), with the linearisation \(\Phi(\Delta p + \delta p) \approx \Phi + B\,\delta p\), \(B = \partial\Phi/\partial\Delta p\) (for von Mises with isotropic hardening \(B \approx -(3G + H)\), \(H\) the hardening slope). A complementarity function turns the three conditions into one equation. Both variants use the normalised multiplier \(\Delta p^* = |B|\,\Delta p\), a stress like \(\Phi\).
Fischer-Burmeister (ncp="fischer_burmeister") solves
The equation is smooth away from \((0, 0)\) and decides by itself whether the surface is
active: Newton never chooses a branch. It extends as is to a coupled system of several surfaces
(multi-mechanism MODUL, the SMA kernels). Its first step is short: from
\(\Delta p = 0\) on a violated surface (\(\Phi > 0\)), the residual is \(2\Phi\)
and its derivative \(2B - |B| = 3B\), so the step is \(-2\Phi/(3B)\), two thirds of the
full cutting-plane step \(-\Phi/B\). The return then needs about 6 local iterations. The
stopping criterion is the residual divided by \(\sigma_Y\), summed over the surfaces.
Min (ncp="min") solves
by semi-smooth Newton (primal-dual active set, Hintermueller, Ito and Kunisch 2002), which picks a branch at each iteration:
active surface (\(\Phi > 0\) or \(-\Phi < \Delta p^*\)): it solves \(\Phi + B\,\delta p = 0\), the full step \(\delta p = -\Phi/B\) of the classic cutting plane (Ortiz and Simo 1986);
inactive surface: the multiplier goes back to zero, \(\delta p = -\Delta p\).
With linear hardening \(\Phi\) is affine in \(\Delta p\), so the first step is the exact return, and one more iteration confirms it. With a nonlinear hardening (power law) the return takes about 3 iterations instead of 6. The stopping criterion is twice the residual of the chosen branch over \(\sigma_Y\): on the first step this equals the Fischer-Burmeister residual, and near the solution it is at least as strict.
Fallback. Within an increment, the min step switches to Fischer-Burmeister for the rest of the local solve as soon as its error grows from one iteration to the next (the full step overshoots, or the branch choice oscillates) or \(B\) vanishes. Coupled surfaces stay on Fischer-Burmeister from the start, because the plain semi-smooth Newton can cycle there, the set of active surfaces changing from one iteration to the next without converging.
Active set (ncp="active_set", 2.5) is the min step on every row: the active surfaces
solve their linearised constraints together,
\(\Phi_A + B_{AA}\,\delta p_A + B_{AI}\,\delta p_I = 0\), the inactive multipliers going
back to zero (\(\delta p_I = -\Delta p_I\)): the primal-dual active set of Hintermueller,
Ito and Kunisch on the coupled system, with the fallback of the min step as its combinatorial
safeguard. On a single surface it is the min step; on coupled surfaces it is a different
iteration path for the cutting plane (the state differs from the Fischer-Burmeister one by the
path dependence of that integrator, \(4 \times 10^{-4}\) on the two-surface composition
below) and the same root under the closest point.
Penalized Fischer-Burmeister (ncp="penalized_fischer_burmeister", 2.5) solves
\(\phi_\lambda(a, b) = \lambda\,\phi_{FB}(a, b) + (1 - \lambda)\, a_+ b_+ = 0\),
\(a = -\Phi\), \(b = \Delta p^*\), \(\lambda = 0.95\) (Chen, Chen and Kanzow
2000): the product term keeps the iterate off the kink of the Fischer-Burmeister function. No
fallback, served for every composition under both integrators, including an
Armstrong-Frederick back stress under the cutting plane (it is not a full step).
Measured (2.5), tension, shear at held tension, unloading (10 increments per step, one thread, min of three runs; the stress of each function against Fischer-Burmeister under the same integrator):
Composition |
Integrator |
FB (ms) |
min |
active set |
penalized FB |
|---|---|---|---|---|---|
MODUL J2, power law |
cutting plane |
0.3 |
\(10^{-14}\), 0.2 ms |
\(10^{-14}\), 0.3 ms |
\(10^{-15}\), 0.5 ms |
MODUL J2, power law |
closest point |
0.5 |
\(3 \times 10^{-10}\), 0.4 ms |
\(3 \times 10^{-10}\), 0.5 ms |
\(10^{-15}\), 0.7 ms |
MODUL Prager |
cutting plane |
0.4 |
\(10^{-14}\), 0.3 ms |
\(10^{-14}\), 0.5 ms |
\(10^{-15}\), 0.7 ms |
MODUL Armstrong-Frederick |
cutting plane |
0.5 |
refused |
refused |
\(10^{-14}\), 0.9 ms |
MODUL Armstrong-Frederick |
closest point |
0.8 |
\(2 \times 10^{-10}\), 0.7 ms |
\(2 \times 10^{-10}\), 0.8 ms |
\(10^{-15}\), 1.0 ms |
MODUL two surfaces (coupled) |
cutting plane |
0.4 |
= FB (falls back), 0.5 ms |
\(4 \times 10^{-4}\), 0.7 ms |
\(10^{-14}\), 1.0 ms |
MODUL two surfaces (coupled) |
closest point |
0.8 |
= FB, 0.8 ms |
\(2 \times 10^{-10}\), 0.8 ms |
\(10^{-13}\), 1.2 ms |
EPICP_closed |
cutting plane |
1.5 |
\(4 \times 10^{-12}\), 1.2 ms |
\(4 \times 10^{-12}\), 2.1 ms |
\(10^{-15}\), 12.3 ms |
The min step stays the fastest local solve; the active set brings nothing on a single surface
(its system is built per iteration) and only changes the path on coupled ones; the penalized
function converges to the same root everywhere but needs more iterations near it. They are
kept as options for comparison; "min" remains the one to use.
Which rows count. The min step applies row by row when the local Jacobian \(B\) is
diagonal, i.e. when the rows are independent scalar problems. That is the case of a single yield
surface, and of a yield surface next to the rows of the viscoelastic and damage mechanisms of
MODUL: those are integrated outside the Newton (the Prony branches in closed form, the damage
by a fixed point), so their rows are always satisfied (\(\Phi = -Y^{crit}\)), carry no
multiplier and no cross term, and stay at zero. Two yield surfaces share the stress, so their
rows are coupled (off-diagonal terms of \(B\)) and keep Fischer-Burmeister.
Case |
Result |
|---|---|
EPICP, linear isotropic hardening |
one exact step and one check; the Fischer-Burmeister return to \(10^{-10}\) |
EPICP, power-law isotropic hardening |
about 3 iterations instead of 6; the Fischer-Burmeister return to \(10^{-7}\) |
EPKCP, |
the Fischer-Burmeister return to the local tolerance (EPKCP and |
|
the min step on the yield surface, the other rows untouched; the Fischer-Burmeister return to the local tolerance |
|
no effect: Fischer-Burmeister is kept |
|
refused ( |
any other law, any other thermomechanical block, a mean-field model |
refused ( |
|
the min step on the reduced Newton system of the closest point, every composition (Armstrong-Frederick included): one backward-Euler system, the same root as Fischer-Burmeister (measured 1e-10 to 4e-10 on a coarse non-proportional path, the local tolerance), where the cutting plane with Fischer-Burmeister sits 1 to 4 % away for an Armstrong-Frederick back stress |
On a batch of \(10^4\) EPICP points (sim.umat, one thread), one increment takes 20 ms
with Fischer-Burmeister and 14 ms with ncp="min". On a cyclic uniaxial MODUL solve
(150 increments) the whole run drops by 17 % with one Prony branch next to the yield surface,
29 % with three, 23 % with a damage mechanism.
EPICP consistent tangent
With tangent_mode = 2, EPICP builds the consistent tangent of the radial return in closed
form (Simo and Taylor 1985),
\(3K\,\mathbb{I}_{vol} + 2G\theta\,\mathbb{I}_{dev} - 2G\bar\theta\,\mathbf{N}\otimes\mathbf{N}\).
It is the operator of the generic assembly to round-off at the converged return, without its
6x6 inverse.
Choosing the tangent and the integrator for EPCHA (0D uniaxial)
tangent_mode = 1(continuum) gives the same iterates as the default mode 2 (to \(10^{-14}\) on the Chaboche identification programmes) for about 27 % less time.integrator="closest_point"is a different update, backward Euler: 1 to 2 % off the cutting plane there, at about 2.3 times the cost.
Global Newton tolerance
The global Newton has its own option, solve(..., precision_rel=...)
(solver_params::precision_rel). The residual tolerance becomes
\(\max(\mathrm{precision}, \mathrm{precision\_rel}\,|\boldsymbol\tau|)\), see
In-memory Python solver.
Validation and performance
Each adapter-served name is validated at two levels:
Translator correctness: a pytest equivalence test (
simcoon-python-builder/test/test_core/test_modular.py, the*_matches_modulfamily) proves the legacy name and the explicitMODULconfiguration are bit-identical through the solver.Independent physics: the removed legacy kernels are retained VERBATIM as test-only reference oracles under
test/Libraries/Umat/reference_kernels/(compiled only into theTreference_umatsgtest, never intolibsimcoon, not dispatchable by name). Every adapter is driven side by side with its reference kernel on a cyclic strain path each test run — machine precision for every family (the Chaboche row of the gtest keeps a 2e-3 tolerance, measured at 4e-15).
A benchmark row per family lives in benchmark/bench_legacy_vs_modular.py:
results show no measurable adapter overhead, and the modular
engine runs at 0.8-1.2x the speed of the removed kernels on all families.