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 MODUL engine, configured from a props stream (see simcoon.modular for the Python builder).

  • modular (adapter): a legacy name whose dedicated kernel was removed after its equivalence with a MODUL configuration 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 in test_modular.py and Treference_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 _closed suffix (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, Abaqus CMNAME).

  • Python (external): the PYEXT name 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); EPICP_closed runs the dedicated kernel

E, nu, alpha, sigmaY, k, m

The dedicated kernel (EPICP_closed, mechanical and thermomechanical) is the pedagogical reference of the CCP return mapping with the closed-form radial-return tangent, 1.3x faster than the generic assembly of the modular engine; the hardening goes through the modular PowerLawHardening (C1 onset blend below p = 1e-6 for m < 1, exact above), as EPJCK

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); EPCHA_closed runs the dedicated kernel

E, nu, alpha, sigmaY, Q, b, C1, D1, C2, D2

The dedicated kernel (EPCHA_closed) is the pedagogical reference of kinematic hardening in CCP, the modular composition to round-off on a cyclic path (same cutting plane); the modular statev are [T_init, p, EP, a_1, a_2] (20, the back-strains), the back stresses and H_p of the dedicated layout are not stored

EPJCK

Von Mises + Johnson-Cook yield stress (power-law hardening x logarithmic strain-rate factor x thermal softening)

modular (adapter, JohnsonCookHardening block); EPJCK_closed runs the dedicated kernel; the thermomechanical face keeps the dedicated kernel under both names

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 (multiplier_predictor). 9 statev (T_init, p, EP, edot_p), the same layout and meaning under the adapter. Thermomechanical twin with (rho, c_p) prepended, dPhi/dT from the thermal softening (dedicated kernel: the hardening entropy has no modular hook yet). tangent_mode 0 returns the elastic L in the mechanical kernel (explicit integration); the thermomechanical twin promotes it to the continuum operator, as EPICP_T.

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); ZENER_closed runs the dedicated kernel

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\), simcoon.modular.zener_as_maxwell): same response to the round-off of the two inverses; the statev EV is then the Maxwell branch strain, not the Kelvin viscous strain of the dedicated kernel (ZENER_closed, mechanical and thermomechanical)

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); PRONK_closed runs the dedicated kernel

E0, nu0, alpha, N, then per branch: E_i, nu_i, etaB_i, etaS_i

The dedicated kernel (PRONK_closed, mechanical and thermomechanical) is the pedagogical reference; the modular Viscoelasticity mechanism takes the same closed-form step and is identical to it (round-off); the modular statev are [T_init, (v_i, EV_i) x N] (1 + 7N), the total viscous strain of the dedicated layout is not stored

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 simcoon.modular.ModularMaterial

Also available under finite strain (NLGEOM control types 2-6), where the composition is a Hencky hyperelastic law on the logarithmic strain; requires corate_type = 3 (log_R) — any other corate is rejected with a RuntimeError (hyper/hypo consistency). Thermomechanical twin with (rho, c_p) prepended: linear elasticity blocks, every mechanism (Building materials in Python (modular))

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 the HYPER_INVARIANTS block 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, as MODUL; statev is [T_init]. NEOHC_closed and NEOHI_closed keep 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 / HOLZA

    Abaqus *ANISOTROPIC HYPERELASTIC, HOLZAPFEL

    FEBio Holzapfel-Gasser-Ogden

    matrix

    \(c\) (\(\mu\))

    C10 \(= c/2\)

    \(C_{10} = c/2\)

    c

    fibre stiffness

    \(k_1\)

    k1

    \(k_1\)

    k1

    fibre exponent

    \(k_2\)

    k2

    \(k_2\)

    k2

    dispersion

    \(\kappa\) (0 in 2000)

    kappa_d

    \(\kappa\)

    kappa

    fibre 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); props n_fam and the unit directions

    two local directions (*ORIENTATION, LOCAL DIRECTIONS)

    gamma, angle in a plane of the local frame

    bulk 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_d and fibres

    fibre 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 (kappa is the bulk modulus in simcoon)

    fibre angle

    \(\beta\)

    \(\gamma\)

    fibres

    wall thickness (tube)

    \(H\)

    \(H\) (also the letter of the structure tensor)

    not a material parameter

    matadi (holzapfel_gasser_ogden) takes c, k1, k2, kappa and the fibre angle about an axis; axis=2, angle=g is 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 a simcoon.Rotation applied 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 their props hold 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 with n_matrix < 0). The length and the values are checked, so the pre-2.0 layout with its leading nphases and 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, Homogeneous and PeriodicLayers of simcoon.solver.micromechanics build 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_eff of a self-consistent composite of spheres is 7 to 10 times faster (20 times with anderson = 2).

    • rule = 1: half-sphere quadrature, (mp+1)/2 Gauss-Legendre points in cos(theta) and np trapezoidal points in phi (the integrand is centrally symmetric and periodic in phi): half the evaluations of the default Gauss-Legendre rule for the same accuracy or better.

    • anderson = m (MISCN, L_eff only): Anderson acceleration of depth m of the self-consistent fixed point (m = 2 is 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_eff only): relative stopping criterion ||L - L_prev|| <= rtol ||L|| of that fixed point instead of the absolute 1e-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/nstatev from 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 plugins UMABA / UMANS, whose contract belongs to the host code (Cauchy stress, a Jaumann or Green-Naghdi Jacobian). select_umat_M_finite hands 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 (UMEXT is a Kirchhoff box, as PYEXT; 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:

\[\mathbf{S} = \mathbf{T}:\mathbb{P}, \qquad \frac{\mathrm{d}\mathbf{S}}{\mathrm{d}\mathbf{E}} = \mathbb{P}^T:\frac{\partial\mathbf{T}}{\partial\mathbf{H}}:\mathbb{P} + \mathbf{T}:\mathbb{L}, \qquad \mathbb{P} = 2\,\frac{\partial\mathbf{H}}{\partial\mathbf{C}}, \quad \mathbb{L} = 4\,\frac{\partial^2\mathbf{H}}{\partial\mathbf{C}\,\partial\mathbf{C}} .\]

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,

\[\boldsymbol{\tau} = \mathbf{R}\Big[\sum_{a,b}\kappa_{ab}\,\hat T_{ab}\,\mathbf{n}_a\otimes\mathbf{n}_b\Big]\mathbf{R}^T, \qquad \kappa_{ab} = \frac{t_{ab}}{\sinh t_{ab}}, \quad t_{ab} = \ln\frac{\lambda_a}{\lambda_b},\]

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

integrator

the discrete update of the local step

"cutting_plane" (default), "closest_point" (backward Euler)

yes: two different schemes

ncp

how the Kuhn-Tucker conditions are solved inside it

"fischer_burmeister" (default), "min"

no, to the local tolerance (see below)

tangent_mode

the operator handed to the global Newton

"none", "continuum", "algorithmic" (default)

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

\[\Phi \le 0, \qquad \Delta p \ge 0, \qquad \Phi\,\Delta p = 0,\]

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

\[\sqrt{\Phi^2 + \Delta p^{*2}} + \Phi - \Delta p^* = 0 .\]

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

\[\min(\Delta p^*, -\Phi) = 0\]

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.

What ncp="min" does, case by case

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, MODUL with isotropic and Prager hardening

the Fischer-Burmeister return to the local tolerance (EPKCP and MODUL agree to \(10^{-12}\))

MODUL, one yield surface with viscoelastic (Prony) or damage mechanisms

the min step on the yield surface, the other rows untouched; the Fischer-Burmeister return to the local tolerance

MODUL with several yield surfaces (coupled)

no effect: Fischer-Burmeister is kept

MODUL with an Armstrong-Frederick back stress

refused (ValueError) under the cutting plane, see above; taken under the closest point

any other law, any other thermomechanical block, a mean-field model

refused (ValueError); the sub-phases of a mean-field model keep Fischer-Burmeister

integrator="closest_point"

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_modul family) proves the legacy name and the explicit MODUL configuration 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 the Treference_umats gtest, never into libsimcoon, 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.