AgentFEM Scientific Function Reference¶

This reference is generated from versioned Scientific Function Cards. It is simultaneously a human manual, a review surface, and the source for the compact machine-readable knowledge/catalog.json.

Function index¶

Stable ID	Title	Kind	Status
`agentfem.load.surface_resultant`	Uniform boundary traction from a requested resultant force	workflow	supported
`agentfem.material.creep_damage_assessment`	Creep damage and modified-theta assessment	material	supported
`agentfem.material.cyclic_cohesive_fatigue`	Cyclic cohesive damage with an independent cycle coordinate	material	experimental
`agentfem.material.finite_strain_plane_stress`	Locally condensed finite-strain plane-stress Neo-Hookean membrane	material	experimental
`agentfem.material.global_implicit_creep`	Global implicit power-law creep	material	supported
`agentfem.material.j2_global_plasticity`	Global small-strain J2 plasticity	material	supported
`agentfem.material.mixed_hybrid_hyperelasticity`	Constant-pressure mixed Neo-Hookean solid	material	supported
`agentfem.material.mixed_mode_cyclic_cohesive`	Proportional and ordered-path mixed-mode cyclic cohesive damage	material	experimental
`agentfem.material.mooney_rivlin_hyperelasticity`	Mooney--Rivlin finite-strain solids and incompressible sheets	material	experimental
`agentfem.operator.system_contracts`	Finite-element operator and system contracts	operator	supported
`agentfem.workflow.abaqus_engineering_regions`	Abaqus node sets and element-face surfaces as FEM regions	workflow	supported
`agentfem.workflow.campaign_learning_pipeline`	Simulation campaign to guarded learning workflow	workflow	supported
`agentfem.workflow.cohesive_state_portability`	Physical-keyed cohesive state across MPI partitions	workflow	experimental
`agentfem.workflow.coordinate_reference_coupling`	Local coordinates and reference-point continuum coupling	workflow	supported
`agentfem.workflow.cyclic_work_energy_ledger`	Transactional generalized work and cycle-block energy ledger	workflow	experimental
`agentfem.workflow.distributed_cohesive_force`	Sparse physical-keyed cohesive force assembly across MPI ranks	workflow	experimental
`agentfem.workflow.dynamic_fracture_v5_evidence`	Publication-data evidence for dynamic cohesive fracture	workflow	experimental
`agentfem.workflow.integration_point_recovery`	Traceable integration-point field recovery	workflow	supported
`agentfem.workflow.observation_grid_learning`	Mesh-independent structured observation grids	workflow	supported
`agentfem.workflow.result_field_sampling`	MPI-safe point and path field sampling	workflow	supported
`agentfem.workflow.scientific_verification`	Scientific trust and verification workflow	workflow	supported
`agentfem.workflow.simplex_mesh_quality`	Collective simplex mesh-quality preflight	workflow	supported
`agentfem.workflow.solution_procedures`	Solution procedure vocabulary	analysis_step	supported
`agentfem.workflow.standard_result_projection`	Projected small-strain fields, reactions, and static equilibrium	workflow	supported
`agentfem.workflow.thermoelastic_analysis`	Sequential thermoelastic analysis	workflow	supported
`agentfem.workflow.transient_checkpoint_portability`	Portable transient checkpoint state	workflow	supported
`agentfem.workflow.vector_cohesive_interface`	Full-vector and mixed-mode cohesive interfaces	workflow	experimental

Benchmark index¶

Stable ID	Title	Physics	Status
`agentfem.benchmark.arrhenius_global_creep`	Nonuniform-temperature global Arrhenius creep patch	three-dimensional small-strain Mises power-law creep with a prescribed nonuniform Arrhenius temperature field	automated_regression
`agentfem.benchmark.c3d10h_periodic_cell`	Imported C3D10H near-incompressible periodic cell	three-dimensional near-incompressible mixed Neo-Hookean periodic homogenization	manual_release_regression
`agentfem.benchmark.cae_reliability_cliffs`	CAE reliability cliffs: orientation, discretization, and reference applicability	cross-cutting finite-element verification	partial_automated_suite
`agentfem.benchmark.campaign_surrogate_pipeline`	Static-elasticity campaign to guarded surrogate pipeline	parameterized small-strain isotropic linear elasticity	executable_integration
`agentfem.benchmark.classical_sub_rayleigh_crack_v3`	Classical sub-Rayleigh cohesive crack guardrail	precracked compressible Neo-Hookean strip with a fixed-path bilinear Mode-I cohesive interface	experimental_v3_guardrail_automated
`agentfem.benchmark.creep_abaqus_constant_stress`	Official Abaqus time-hardening constant-stress creep case	three-dimensional small-strain Mises time-hardening power-law creep	automated_external_verification
`agentfem.benchmark.creep_damage_material_paths`	Creep-damage material paths and curve projection	Mises Kachanov-Rabotnov creep damage, hyperbolic-sine creep, and modified-theta curve projection	automated_regression
`agentfem.benchmark.creep_hot_wall_release`	Sequential hot-wall creep assessment release contract	sequential transient heat conduction, plane-strain thermoelasticity, and local creep-damage assessment	automated_regression
`agentfem.benchmark.cyclic_cohesive_global_lifecycle`	Global cyclic cohesive transaction, cutback, restart and named 3D interfaces	Quasi-static force-controlled fixed-path Mode-I cohesive fatigue	experimental_automated_foundation
`agentfem.benchmark.delamination_structural_family`	DCB, ENF and MMB structural cohesive verification family	Fixed-path delamination under DCB Mode I, ENF Mode II and MMB mixed-mode loading	analytical_oracles_automated_external_curves_pending
`agentfem.benchmark.distributed_cohesive_force`	Two-rank sparse fixed-path cohesive force and portable restart	Two-dimensional normal and mixed-mode bilinear cohesive interfaces in finite-strain assembly and Explicit dynamics	experimental_mpi_sparse_automated
`agentfem.benchmark.dynamic_fracture_energy_v2`	Finite-strain and cohesive dynamic energy closure	Total-Lagrangian Neo-Hookean dynamics with optional Mode-I cohesive separation	experimental_v2_automated
`agentfem.benchmark.elasticity_foundation`	Foundational small-strain elasticity verification	two- and three-dimensional small-strain linear elasticity	automated
`agentfem.benchmark.finite_strain_incremental_waves_v1`	Neo-Hookean small-on-large wave oracle	compressible Neo-Hookean small-on-large elastodynamics	experimental_v1_automated
`agentfem.benchmark.implicit_creep_relaxation`	Three-dimensional implicit power-law creep relaxation and restart	three-dimensional small-strain isotropic Mises power-law creep	automated_regression
`agentfem.benchmark.j2_abaqus_rate_independent`	Published Abaqus rate-independent Mises plasticity uniaxial state	three-dimensional small-strain Mises plasticity with linear isotropic hardening	automated_external_verification
`agentfem.benchmark.j2_global_restart`	Three-dimensional J2 path, physical cutback, cyclic amplitude, energy, and restart equivalence	three-dimensional small-strain Mises plasticity with linear isotropic hardening	automated_regression
`agentfem.benchmark.j2_multielement_patch`	Multi-element global J2 plasticity patch	three-dimensional small-strain rate-independent J2 plasticity with linear isotropic hardening	automated
`agentfem.benchmark.j2_nonuniform_bending`	Nonuniform three-dimensional J2 bending path	three-dimensional small-strain Mises plasticity with linear isotropic hardening under displacement-controlled bending	automated_regression
`agentfem.benchmark.j2_thick_cylinder_mpi`	Public thick-cylinder J2 structural benchmark in serial and MPI	three-dimensional extrusion of a plane-strain quarter cylinder with small-strain Mises plasticity and linear isotropic hardening	automated_external_structural_mpi
`agentfem.benchmark.jmps_weak_interface_convergence_v4`	Two-dimensional weak-interface supershear refinement contract	near-incompressible finite-strain plane-stress Neo-Hookean strip with ten or more cells through the height, homogeneous preload, smooth remote impact, a fixed bilinear Mode-I cohesive interface, and a precrack	experimental_v4_2d_convergence_accepted
`agentfem.benchmark.jmps_weak_interface_transition_v4`	Prestressed weak-interface crack-to-supershear-to-spall mechanism ladder	near-incompressible finite-strain plane-stress Neo-Hookean strip with homogeneous preload, smooth remote impact, a fixed zero-thickness bilinear Mode-I interface, and a precrack	experimental_v4_mechanism_executable
`agentfem.benchmark.linear_static_cantilever`	Two-dimensional linear-static cantilever	small-strain isotropic linear elasticity in plane strain	numerical_regression
`agentfem.benchmark.mixed_mode_bending_external_contract`	Source-identified mixed-mode bending curve comparison	Mixed-mode bending delamination or a mechanically equivalent fixed-path cohesive structure with measured load, displacement, crack length, and Mode-I fraction	contract_ready_external_data_pending
`agentfem.benchmark.mixed_mode_cyclic_cohesive_foundation`	Mixed-mode cyclic cohesive paths, energy lifecycle and portable state	Fixed-path proportional and ordered non-proportional mixed-mode cyclic cohesive degradation	experimental_automated_foundation
`agentfem.benchmark.mooney_rivlin_material_paths`	Mooney--Rivlin material-path and Explicit-consumer contract	incompressible plane-stress Mooney--Rivlin hyperelasticity	experimental_automated_regression
`agentfem.benchmark.neo_hookean_release`	Compressible Neo-Hookean finite-strain release contract	compressible Neo-Hookean hyperelasticity	automated_regression
`agentfem.benchmark.operator_contracts`	Operator role, system, and residual-linearization contracts	backend-facing finite-element operator algebra	automated
`agentfem.benchmark.plane_stress_thin_3d_crosscheck`	Finite-strain plane-stress and thin-three-dimensional patch cross-check	compressible Neo-Hookean finite strain under homogeneous uniaxial stretch with traction-free lateral and thickness directions	experimental_geometry_crosscheck_automated
`agentfem.benchmark.thermoelastic_free_expansion`	Plane-stress isotropic free thermal expansion	small-strain isotropic plane-stress thermoelasticity under uniform temperature change	automated_regression
`agentfem.benchmark.transient_heat_release`	Implicit-Euler transient heat release regression	two-dimensional transient heat conduction with constant isotropic properties	numerical_regression
`agentfem.benchmark.vector_cohesive_interface`	Vector cohesive kinematics, mixed-mode energy and model rank	Two- and three-dimensional fixed-path cohesive interfaces under normal, shear, mixed and compressive separation	experimental_automated_foundation
`agentfem.benchmark.wave_release`	Explicit elastic-wave inclusion release contract	two-dimensional plane-strain linear elastodynamics	automated_regression

Uniform boundary traction from a requested resultant force¶

Stable ID: agentfem.load.surface_resultant
Kind: workflow
Status: supported
Source card: knowledge/cards/surface_resultant_load.json

Converts an engineering total force into a uniform reference-boundary traction while preserving the requested MPI-global resultant.

Public API¶

agentfem.loads.surface_force
agentfem.loads.distributing_coupling
agentfem.models.Model.surface_force
agentfem.models.Model.distributing_coupling
agentfem.results.boundary_resultant

Scientific contract¶

A known continuum-solid end force can be applied without a singular nodal load by distributing it over a named reference boundary.

uniform reference traction

\[ \mathbf{t}_0=\frac{\mathbf{F}_{\mathrm{requested}}}{|\Gamma_0|} \]

The same constant traction is integrated over the selected reference edge or surface.

resultant contract

\[ \int_{\Gamma_0}\mathbf{t}_0\,d\Gamma_0=\mathbf{F}_{\mathrm{requested}} \]

The boundary measure and verification integral are MPI-global.

Inputs¶

Name	Type	Unit role	Meaning
resultant and boundary	finite vector and named BoundaryRegion	force and reference edge length/surface area	The vector dimension must match the mesh geometric dimension.

Outputs¶

Name	Type	Unit role	Meaning
surface resultant load	weak boundary load	traction integrated to force	The load retains requested resultant, measured reference size, and applied traction in its summary.

Assumptions¶

The traction is uniform over the selected reference boundary.
In 2D the resultant is per unit out-of-plane thickness.

Conventions¶

The force vector follows global coordinates.
Amplitude scaling acts on the complete distributed load.
The geometric measure is assembled unless an explicit positive reference_measure is supplied.

Applicability¶

Continuum-solid end loads, verification beams, specimens, and distributing-load workflows.

Limitations¶

surface_force is uniform; use distributing_coupling when a reference-point moment must also be transmitted.
The distributing load preserves resultants but does not yet create kinematic reference-point degrees of freedom or an MPC constraint.

Minimal example¶

loaded = mesh.boundary(domain, right, name='loaded_end')
model.surface_force((0.0, -50000.0), on=loaded)

Verification¶

Tests

tests/test_common_workflows.py
tests/test_engineering_workflows.py

Benchmarks

agentfem.benchmark.elasticity_foundation

Validation rules

Reject non-finite or dimensionally incompatible resultants.
Reject an empty or non-positive reference boundary measure.
Integrate the generated traction and recover the requested vector.
Solve a clamped solid and verify global force balance.

References¶

Abaqus three-dimensional solid distributed loads: https://docs.software.vt.edu/abaqusv2024/English/SIMACAEELMRefMap/simaelm-r-3delem.htm

Creep damage and modified-theta assessment¶

Stable ID: agentfem.material.creep_damage_assessment
Kind: material
Status: supported
Source card: knowledge/cards/creep_damage_assessment.json

Verified material-point Kachanov-Rabotnov and hyperbolic-sine creep relations plus a deterministic modified-theta curve projection, kept distinct from the implemented global isothermal/Arrhenius power-law creep route.

Public API¶

agentfem.constitutive.KachanovRabotnovCreep
agentfem.constitutive.CreepDamageState
agentfem.constitutive.SinhCreep
agentfem.constitutive.ModifiedThetaProjection

Scientific contract¶

K-R couples effective-stress creep flow to a scalar loss-of-integrity variable; the exact constant-stress update supplies a time-subdivision-independent reference, while modified theta represents a measured creep curve rather than a global equilibrium law.

K-R creep rate

\[ \dot{\varepsilon}_{\mathrm{cr}}=A\left(\frac{q}{\sigma_{\mathrm{ref}}}\right)^n(1-\omega)^{-n} \]

Damage accelerates the equivalent creep rate through effective stress.

K-R damage rate

\[ \dot{\omega}=B\left(\frac{q}{\sigma_{\mathrm{ref}}}\right)^m(1-\omega)^{-\phi} \]

The scalar damage state grows from zero toward a declared failure threshold.

modified theta projection

\[ \varepsilon(t)=\varepsilon_0+A_1\left[1-\exp(-\alpha t)\right]+B_1\left[\exp(\alpha t)-1\right] \]

Primary and tertiary terms project a creep strain-time curve.

Inputs¶

Name	Type	Unit role	Meaning
stress and duration	scalar equivalent stress or symmetric 3x3 stress plus time interval	declared reference stress and time system	A piecewise-constant interval for the exact local K-R update.
calibrated parameters	rate coefficients, stress exponents, damage power and failure criterion	normalized by reference stress and reference time	Material- and temperature-specific parameters require provenance.
creep test curve	strictly increasing time and finite strain arrays	consistent time and strain	Data used by the modified-theta projection.

Outputs¶

Name	Type	Unit role	Meaning
creep state	equivalent/tensor creep strain and scalar damage	strain and dimensionless damage	Accepted material-point state and increments.
rupture screening time	scalar	time	Constant-stress time to the declared damage threshold.
projected curve	strain and strain-rate functions	strain and strain per time	Modified-theta fit with recorded RMSE.

Assumptions¶

Small-strain associative Mises creep for tensor increments.
Piecewise-constant stress over each exact K-R material interval.
Scalar isotropic damage and a material-specific declared failure threshold.

Conventions¶

Damage is zero for intact material and approaches but never numerically reaches one.
The first multiaxial implementation drives damage with von Mises stress.
Modified theta is classified as a curve assessment, not an FE constitutive update.

Applicability¶

Material calibration checks and constant-stress creep screening.
Sequential thermoelastic-to-creep hotspot workflows with explicit scope labels.
Reference updates for future global damage and Sinh consumers.

Limitations¶

K-R damage and Sinh flow do not yet enter global equilibrium, adaptive time stepping, or restartable quadrature state; the separate isothermal/Arrhenius power-law model does.
Local softening/damage is not mesh regularized.
No Liu-Murakami multiaxial damage law is claimed in this release.

Minimal example¶

Create KachanovRabotnovCreep with traceable parameters, advance CreepDamageState over stress intervals, and store strain/damage histories in SimulationResult.

Verification¶

Tests

tests/test_constitutive_models.py

Benchmarks

agentfem.benchmark.creep_damage_material_paths

Validation rules

Reject nonfinite parameters, invalid reference scales, and damage outside [0, 1).
Clamp a failed update at the declared failure damage and report failed=True.
Do not promote K-R, Sinh, or modified-theta beyond their declared local/curve maturity merely because power-law creep has a global state consumer.

References¶

Constitutive equations for creep rupture: doi:10.1016/0001-6160(77)90135-3
Damage localization of conventional creep damage models and proposition of a new model: doi:10.1299/jsmea.41.57
Modified theta projection equation for high-temperature creep curves: https://pmc.ncbi.nlm.nih.gov/articles/PMC6838921/

Cyclic cohesive damage with an independent cycle coordinate¶

Stable ID: agentfem.material.cyclic_cohesive_fatigue
Kind: material
Status: experimental
Source card: knowledge/cards/cyclic_cohesive_fatigue.json

Layers a thresholded, irreversible opening-range fatigue state on the exact bilinear Mode-I monotonic limit and advances accepted integer cycle blocks through explicit begin, commit, rollback and restart semantics.

Public API¶

agentfem.fatigue_fracture.ForceCycle
agentfem.fatigue_fracture.CycleJumpPolicy
agentfem.fatigue_fracture.CycleJumpLedger
agentfem.fatigue_fracture.CyclicCohesiveLaw
agentfem.fatigue_fracture.CyclicCohesiveTransaction
agentfem.fatigue_fracture.FieldStateTransaction
agentfem.fatigue_fracture.GlobalCyclicFatigueStep
agentfem.fatigue_fracture.SurfaceCrackTracker
agentfem.fatigue_fracture.ParisEvidence
agentfem.fatigue_fracture.cyclic_cohesive
agentfem.fatigue_fracture.global_cyclic_fatigue_step
agentfem.fatigue_fracture.cyclic_work_energy_ledger
agentfem.fatigue_fracture.observe_surface_crack
agentfem.fatigue_fracture.paris_evidence
agentfem.procedures.cyclic_fatigue
agentfem.fracture.CohesiveForceCollection
agentfem.fracture.FiniteStrainCohesiveEquilibrium
agentfem.fracture.FiniteStrainCohesiveResidual
agentfem.fracture.named_mode_i_cohesive_forces
agentfem.interfaces.split_conforming_named_interfaces

Scientific contract¶

Fatigue cycles are neither transient time increments nor output frames; a replaceable cyclic cohesive law advances irreversible interface state from accepted local opening extrema while preserving the declared monotonic envelope.

local opening load ratio

\[ R_delta=delta_min^+/delta_max^+ \]

The local ratio changes with closure, shielding and crack interaction instead of copying one applied global load ratio to every integration point.

reference fatigue rate

\[ dD_f/dN=C<((Delta delta/delta_f)-threshold)/(1-threshold)>^m(delta_max^+/delta_f)^q(1-D_f)^p \]

A transparent reference law; alternative calibrated laws retain the same state and lifecycle protocol.

combined damage

\[ D=1-(1-D_m)(1-D_f) \]

Monotonic and cyclic degradation remain separately inspectable and combine without healing.

Inputs¶

Name	Type	Unit role	Meaning
monotonic cohesive law	BilinearCohesiveLaw	traction-separation envelope	Defines strength, fracture energy, stiffness, closure and the exact monotonic limit.
cycle extrema	positive opening minimum and maximum per interface point	length	Must come from accepted peak/valley equilibrium states in a global consumer.

Outputs¶

Name	Type	Unit role	Meaning
cyclic cohesive response	traction, tangent, monotonic/fatigue/total damage and energy	interface response	Compression retains closure stiffness without fatigue healing or false fatigue dissipation.
cycle state	physical-facet-keyed quadrature arrays	restart state	Includes opening extrema, accumulated cycles, fatigue damage and fatigue dissipation.
persistent crack components	physical-facet-keyed crack identities and topology events	geometric observation	Tracks per-component area, COD and front geometry while recording birth, death, merge and split ancestry across accepted cycles and restart.
Paris evidence	postprocessed da/dN power-law fit	declared crack-size and driving-force units	Fits accepted simulation observations with an explicit sample mask; it is never consumed as a crack-growth law by the solver.

Assumptions¶

This historical opening-range law is normal Mode-I and fixed path; the separate mixed-mode cyclic card declares its vector energy driver.
The reference evolution is calibrated for the material/interface and load regime being studied.
The global cycle controller re-solves degraded equilibrium and rolls back/cuts back a proposed block when damage, opening-feedback or energy evidence exceeds tolerance.

Conventions¶

Cycle count is an integer independent coordinate.
Local positive opening extrema define the load-ratio effect.
No cycle advancement exactly recovers the wrapped bilinear law.

Applicability¶

Material-point studies, current 2D/3D paired-facet cohesive assemblers and the global peak/valley lifecycle for fixed-path surface-fatigue crack growth.

Limitations¶

The generalized work-energy ledger accepts reference-point, prescribed-motion, MPC, weak and contact channels, but automatic extraction of all such reactions from every native provider remains a separate gate.
This Mode-I card does not claim mixed-mode calibration; free-path growth, cylinder validation and experimental prediction remain separate gates.
Bulk-field durable restart currently requires the same MPI partition; cohesive facet state is physically keyed and portable.

Minimal example¶

cycle = fatigue_fracture.force_cycle(fmin=226, fmax=2262); law = fatigue_fracture.cyclic_cohesive(monotonic=interfaces.bilinear_cohesive(strength=..., fracture_energy=..., initial_stiffness=...), fatigue_coefficient=..., fatigue_exponent=..., range_threshold=...); step = fatigue_fracture.global_cyclic_fatigue_step(cycle=cycle, stop_cycle=..., interfaces=named_interfaces, state=fatigue_fracture.field_state(displacement=u), solve_equilibrium=solve_peak_or_valley); step.run()

Verification¶

Tests

tests/test_fatigue_fracture.py
tests/test_interfaces.py
tests/test_dynamic_fracture.py
tests/test_global_cohesive_residual.py
tests/test_parallel_cohesive.py

Benchmarks

agentfem.benchmark.cyclic_cohesive_global_lifecycle

Validation rules

Below-threshold cycles and static holds do not produce fatigue damage.
No-cycle monotonic paths exactly reproduce the bilinear law.
Rollback leaves all cycle state unchanged and checkpoint restores every field.
Constant-extrema exact cycles and one analytical cycle jump agree.
Global blocks re-solve the degraded peak, cut back excessive feedback, land on requested cycles and preserve restart equivalence.
Several disjoint 3D cohesive surfaces split atomically onto one solver mesh with independent names and state.
Analytical 2D/3D interface tangents match force directional derivatives and assemble with the UFL bulk tangent in serial and two-rank PETSc Newton systems.
A real force-controlled Neo-Hookean split strip completes peak, valley, fatigue update, degraded re-equilibration and closing, and its interrupted restart matches the continuous path.
Same-surface components preserve one-to-one identities, create explicit merge ancestry and recover the same state after restart.
Paris postprocessing recovers a synthetic known power relation without influencing crack evolution.

References¶

Roe and Siegmund, An irreversible cohesive zone model for interface fatigue crack growth simulation: https://doi.org/10.1016/S0013-7944(02)00034-6
Bak et al., A Simulation Method for High-Cycle Fatigue-Driven Delamination using a Cohesive Zone Model: https://doi.org/10.1002/nme.5117
AgentFEM cyclic cohesive fatigue architecture: docs/cyclic_cohesive_fatigue_architecture.md

Locally condensed finite-strain plane-stress Neo-Hookean membrane¶

Stable ID: agentfem.material.finite_strain_plane_stress
Kind: material
Status: experimental
Source card: knowledge/cards/finite_strain_plane_stress.json

Enforces P33=0 through a positive local thickness stretch and uses the same condensed energy, in-plane first-Piola stress, and Schur-complement tangent in static and Explicit finite-strain workflows.

Public API¶

agentfem.constitutive.neo_hookean_plane_stress
agentfem.constitutive.plane_stress_thickness_stretch_value
agentfem.constitutive.plane_stress_first_piola_value
agentfem.fracture.neo_hookean_material_tangent
agentfem.fracture.incremental_wave_speeds
agentfem.fracture.principal_surface_wave_speed
agentfem.models.Model.step

Scientific contract¶

A thin two-dimensional hyperelastic membrane is reduced from the three-dimensional compressible Neo-Hookean energy by solving a positive out-of-plane stretch at each material point such that P33 vanishes.

local plane-stress condition

\[ P_{33}(F_{\alpha\beta},\lambda_3)=\partial\psi/\partial\lambda_3=0,\quad \lambda_3>0 \]

The thickness stretch is an eliminated local variable, not a prescribed Poisson estimate.

condensed membrane tangent

\[ \bar A_{\alpha\beta\gamma\delta}=A_{\alpha\beta\gamma\delta}-A_{\alpha\beta33}A_{3333}^{-1}A_{33\gamma\delta} \]

The same local condition is differentiated for small-on-large acoustic analysis.

Inputs¶

Name	Type	Unit role	Meaning
in-plane deformation gradient and material	positive-J 2x2 tensor and PlaneStressNeoHookeanProperties	dimensionless and stress	The material supplies E, nu, and optional reference density.

Outputs¶

Name	Type	Unit role	Meaning
thickness stretch, condensed energy, P, and tangent	local scalar, scalar density, in-plane tensor, and fourth-order tensor	dimensionless, energy density, and stress	All outputs satisfy the same local P33=0 reduction.

Assumptions¶

A homogeneous through-thickness membrane response with no transverse shear is appropriate.
The three-dimensional parent material is compressible Neo-Hookean with finite bulk modulus.

Conventions¶

The two-dimensional Study must declare assumption='plane_stress'.
J means the complete three-dimensional determinant including the condensed thickness stretch.
Incremental wave speeds use the reference density and a declared reference/current propagation direction.

Applicability¶

Thin hyperelastic sheets, plane-stress parameter studies, and the experimental weak-interface dynamic-fracture route.

Limitations¶

Local plane-stress condensation does not by itself prove freedom from in-plane volumetric locking on arbitrary meshes.
A thin-three-dimensional comparison and general mixed or F-bar Explicit route remain open validation gates.
The surface-wave solver is restricted to a principal, traction-free half-space base state; it deliberately rejects a normally loaded weak interface.

Minimal example¶

study = studies.dynamic_solid(dimension=2, assumption='plane_stress', method='explicit')
material = model.material(constitutive.neo_hookean_plane_stress(young=1000, poisson=0.49, density=1))
step = model.step(target=u, material=material, steps=100)

Verification¶

Tests

tests/test_dynamic_fracture.py
tests/test_dynamic_fracture_benchmarks.py

Benchmarks

agentfem.benchmark.jmps_weak_interface_transition_v4
agentfem.benchmark.jmps_weak_interface_convergence_v4

Validation rules

Require positive thickness stretch and P33 closure.
Compare the Schur-complement tangent with finite differences of the condensed first-Piola response.
Reject a plane-strain material under a plane-stress Study and vice versa.
Keep general near-incompressible locking claims outside this material's evidence scope.

References¶

Wang, Fineberg, and Needleman (2025), transition from crack-type to supershear-type to spall-type dynamics: https://doi.org/10.1016/j.jmps.2025.106213

Global implicit power-law creep¶

Stable ID: agentfem.material.global_implicit_creep
Kind: material
Status: supported
Source card: knowledge/cards/global_implicit_creep.json

Three-dimensional small-strain Mises power-law creep with backward-Euler integration, a shared quadrature transaction, analytical consistent tangent, adaptive physical-time increments, optional scalar or field-driven Arrhenius temperature dependence, atomic rollback, serial restart, and standard creep fields.

Public API¶

agentfem.studies.creep_solid
agentfem.constitutive.isotropic_power_law
agentfem.constitutive.isotropic_arrhenius_power_law
agentfem.constitutive.IsotropicPowerLawCreepMaterial
agentfem.constitutive.CreepQuadratureState
agentfem.models.Model.step

Scientific contract¶

The creep increment is solved locally from the fully implicit Mises power-law equation; its analytical derivative supplies the material tangent for global quasi-static Newton equilibrium, while all history remains trial state until the complete increment is accepted.

power-law flow

\[ \Delta\gamma=\Delta t\,A(t_{n+1})\left(\frac{q_{n+1}}{\sigma_{\mathrm{ref}}}\right)^n \]

Backward Euler evaluates the time-hardening rate and equivalent stress at the increment end.

local scalar corrector

\[ q_{n+1}=q_{\mathrm{trial}}-3G\,\Delta\gamma \]

A safeguarded scalar Newton solve keeps the equivalent stress and creep increment nonnegative.

global equilibrium

\[ \int_{\Omega}\boldsymbol{\sigma}\!\left(\boldsymbol{\varepsilon}(\mathbf{u}_{n+1}),\mathbf{CE}_n,\Delta t\right):\boldsymbol{\varepsilon}(\mathbf{v})\,d\Omega=\mathcal{F}_{\mathrm{ext}}(t_{n+1};\mathbf{v}) \]

The global Newton matrix consumes the analytical algorithmic consistent tangent of the same local update.

Inputs¶

Name	Type	Unit role	Meaning
elastic and creep parameters	E, nu, density, A, n, optional time exponent and reference scales	one declared consistent stress-time system	Use isotropic_power_law to keep instantaneous elasticity and creep flow in one material record.
physical duration and increment controls	positive duration plus fixed or automatic incrementation	time	Normalized increment sizes map to physical time; amplitudes are evaluated in physical time.
temperature	positive scalar or scalar finite-element field	absolute temperature in kelvin	Required for an Arrhenius material and evaluated at the same quadrature identity as creep state.

Outputs¶

Name	Type	Unit role	Meaning
S and MISES	quadrature tensor and scalar fields	stress	Accepted constitutive stress and its von Mises invariant.
CE and CEEQ	committed quadrature state	strain	Creep strain tensor and accumulated equivalent creep strain.
time, Newton, local-update and dissipation histories	structured histories and execution events	time, iterations, strain, and energy	Accepted times, maximum creep increment, local/global iterations, elastic energy, and creep dissipation.
TEMP and temperature evidence	input field plus accepted-increment extrema	kelvin	Records the prescribed temperature field and the integration-point range actually consumed by Arrhenius updates.

Assumptions¶

Small strain, three spatial dimensions, isotropic elasticity, and associative Mises creep; temperature changes the Arrhenius rate but not elastic properties.
Quasi-static equilibrium; inertia is not part of this procedure.
One material covers the current convenience-step domain.

Conventions¶

Ordinary loads and prescribed values are held at full magnitude by default; an explicit amplitude defines any physical-time history.
CE and CEEQ are committed only after local integration, global Newton convergence, and increment-level acceptance all succeed.
maximum_inelastic_increment limits the maximum quadrature-point CEEQ increment and causes rollback/cutback when exceeded.
Checkpoint restore reconstructs stress from accepted strain and CE without advancing a fictitious time increment.

Applicability¶

Isothermal or prescribed-temperature three-dimensional studies governed by a calibrated Mises power-law creep relation.
Stress-relaxation and creep-deformation workflows requiring inspectable state, cutback, and restart evidence.

Limitations¶

The provider and checkpoint are serial-only and do not yet support multiple material regions.
Automatic transfer and time alignment of a transient thermal history, damage, and mesh regularization are not part of this global route.
External component or code-standard validation remains required before application-specific qualification.

Minimal example¶

Create studies.creep_solid(), register constitutive.isotropic_power_law(...) or isotropic_arrhenius_power_law(...), add supports and loads, then call model.step(target=u, material=steel, duration=..., incrementation=steps.automatic(), temperature=T).

Verification¶

Tests

tests/test_p1_platform.py

Benchmarks

agentfem.benchmark.implicit_creep_relaxation
agentfem.benchmark.arrhenius_global_creep

Validation rules

Reject non-3D, multi-rank, nonpositive-duration, or incompatible material use.
Verify the analytical tangent independently against a centered material-point derivative.
Commit shared transaction state only after a globally accepted physical-time increment.
Evaluate and record positive kelvin temperatures at the creep quadrature identity for every attempted increment.
Restore displacement, CE, CEEQ, physical time, next increment, histories, energies, and events from a compatible checkpoint.

References¶

Consistent tangent operators for rate independent elasto-plasticity: https://escholarship.org/uc/item/9cp19009
A consistent formulation for the integration of combined plasticity and creep: doi:10.1002/nme.1620370803

Global small-strain J2 plasticity¶

Stable ID: agentfem.material.j2_global_plasticity
Kind: material
Status: supported
Source card: knowledge/cards/j2_global_plasticity.json

Three-dimensional Mises plasticity with linear isotropic hardening, a shared quadrature transaction, analytical algorithmic tangent, cyclic amplitude paths, physical-increment cutback, cumulative serial restart, standard fields, and work/energy histories verified on homogeneous and nonuniform structural paths.

Public API¶

agentfem.constitutive.J2LinearIsotropicHardening
agentfem.constitutive.J2QuadratureState
agentfem.constitutive.QuadratureTransaction
agentfem.models.Model.step

Scientific contract¶

An elastic trial stress is projected radially onto a linearly hardened Mises surface; the same return map supplies stress, history and its analytical consistent derivative to global Newton equilibrium.

yield function

\[ f_{\mathrm{trial}}=q_{\mathrm{trial}}-(\sigma_{y0}+Hp_n) \]

A nonpositive trial value remains elastic.

plastic multiplier

\[ \Delta\gamma=\frac{f_{\mathrm{trial}}}{3G+H} \]

Closed-form increment for associative J2 flow with linear isotropic hardening.

global equilibrium

\[ \int_{\Omega}\boldsymbol{\sigma}\!\left(\boldsymbol{\varepsilon}(\mathbf{u}),\mathbf{s}_n\right):\boldsymbol{\varepsilon}(\mathbf{v})\,d\Omega=\lambda\,\mathcal{F}_{\mathrm{ext}}(\mathbf{v}) \]

Newton iterations use trial state based on the last committed increment.

Inputs¶

Name	Type	Unit role	Meaning
total strain	symmetric 3x3 tensor at every quadrature point	strain	Small total strain at the current global iterate.
material parameters	E, nu, initial yield stress, hardening modulus	consistent stress system	Finite, physically admissible isotropic parameters.

Outputs¶

Name	Type	Unit role	Meaning
S	quadrature tensor field	stress	Accepted Cauchy stress retained at the constitutive integration points after convergence.
MISES	quadrature scalar field	stress	Pointwise invariant of S; the visualization helper writes a separately identifiable DG0 cell average.
PE and PEEQ	committed quadrature state	strain	Plastic strain tensor and equivalent plastic strain.
DDSDDE	fourth-order quadrature tensor field	stress per strain	Analytical algorithmic consistent tangent.
RF and internal-energy diagnostics	nodal residual field and scalar result quantities	force and energy	Full nodal residual plus elastic, hardening, plastic-dissipation, internal-energy, prescribed-work, and balance histories.

Assumptions¶

Small strain and three spatial dimensions.
Rate independence, associative Mises flow, and linear isotropic hardening.
Natural loads and nonzero engineering Dirichlet targets share one named amplitude; the step coordinate remains monotone while amplitude values may reverse.

Conventions¶

Committed history is immutable during a rejected Newton iterate.
Tensor storage is full symmetric 3x3 form rather than engineering Voigt.
The normalized step coordinate runs from zero to one; load amplitude may be non-monotone.
maximum_inelastic_increment limits the equivalent plastic-strain increment and triggers rollback/cutback after an otherwise converged Newton attempt.

Applicability¶

Monotone or reviewed tabular cyclic small-strain 3D solid loading within the implemented isotropic-hardening law.
Laboratory-scale regression and research workflows requiring inspectable state.
Nonuniform displacement-controlled structures with simultaneous elastic and plastic integration points.

Limitations¶

The first global provider is serial-only and has no plane-stress local constraint, finite-strain plasticity, kinematic hardening, or multi-region driver.
External-work histories are currently available for nonzero strong prescribed displacements; natural, weak, and affine-MPC work require separate verified definitions.
No external NAFEMS benchmark has yet promoted this path to benchmark-verified maturity.

Minimal example¶

Register J2LinearIsotropicHardening in a 3D nonlinear_static Model, add supports and traction, then call model.step(target=u, material=steel, incrementation=steps.automatic()).

Verification¶

Tests

tests/test_constitutive_models.py
tests/test_p1_platform.py

Benchmarks

agentfem.benchmark.j2_global_restart
agentfem.benchmark.j2_multielement_patch
agentfem.benchmark.j2_nonuniform_bending

Validation rules

Reject non-3D and multi-rank global use.
Reject nonphysical material parameters.
Commit shared transaction state only after global and constitutive-increment acceptance.
Restore field, constitutive state, adaptive next-increment state, energy history, accepted/attempt histories, and execution events after restart.

References¶

Abaqus theory: classical metal plasticity: https://docs.software.vt.edu/abaqusv2024/English/SIMACAETHERefMap/simathe-c-isoelastoplast.htm
MOOSE radial return stress update: https://mooseframework.inl.gov/moose/source/materials/RadialReturnStressUpdate.html

Constant-pressure mixed Neo-Hookean solid¶

Stable ID: agentfem.material.mixed_hybrid_hyperelasticity
Kind: material
Status: supported
Source card: knowledge/cards/mixed_hybrid_hyperelasticity.json

Solves finite-strain equilibrium with quadratic displacement and one independent constant pressure unknown per cell, including automatic incrementation, Newton tangent, rollback, and positive-J acceptance.

Public API¶

agentfem.fields.displacement_pressure
agentfem.constitutive.mixed_neo_hookean
agentfem.models.Model.step

Scientific contract¶

The pressure field is a solved scientific unknown rather than metadata inferred from tetra10 geometry; the P2/DG0 pair is AgentFEM's constant-pressure hybrid analogue for C3D10H source meshes.

mixed finite-strain potential

\[ \Pi=\int_{\Omega_0}\left[\psi_{\mathrm{iso}}(\mathbf{F})-p(J-1)-\frac{p^2}{2\kappa}\right]dV-\mathcal{W}_{\mathrm{ext}} \]

Automatic differentiation supplies the coupled residual and consistent Newton tangent.

pressure constraint

\[ p=-\kappa(J-1) \]

Positive pressure denotes compression and DG0 creates one pressure value per cell.

pressure-condensed stored energy

\[ W=\frac{\mu}{2}(J^{-2/3}I_1-3)+\frac{\kappa}{2}(J-1)^2 \]

This is the quasi-incompressible Neo-Hookean form used by the porous-cell workflow; Abaqus polynomial parameters are C10=mu/2 and D1=2/kappa.

Inputs¶

Name	Type	Unit role	Meaning
mixed field and material	P2 displacement/DG0 pressure unknown and MixedNeoHookeanProperties	length, pressure, and energy density	Displacement constraints are applied to the displacement subfield while both fields solve monolithically.

Outputs¶

Name	Type	Unit role	Meaning
U, PRESSURE, and P	mixed finite-element solution with collapsible displacement and pressure fields	length and pressure	U and PRESSURE are primary fields; P is the derived first-Piola tensor. The names remain distinct in one output dataset.

Assumptions¶

Three-dimensional solids and two-dimensional plane strain use total-Lagrangian kinematics.
The volumetric response uses a finite bulk modulus declared directly with mu or derived from E and nu.

Conventions¶

Positive pressure is compressive.
A known imported hybrid element is accepted only by the mixed provider.
Every accepted increment must retain positive quadrature-point J.

Applicability¶

Nearly incompressible Neo-Hookean continuum solids and C3D10H-topology import workflows.

Limitations¶

Distributed mixed affine-periodic MPC, multiple finite-strain material regions, and an external locking benchmark remain release gates.

Minimal example¶

unknown = model.field(fields.displacement_pressure(domain))
material = model.material(constitutive.mixed_neo_hookean(shear_modulus=1.0, bulk_modulus=1.0e4))
model.fix(unknown.displacement, on=support)
step = model.step(target=unknown, material=material)

Verification¶

Tests

tests/test_engineering_workflows.py
tests/test_abaqus_interop.py
tests/test_mesh_formats.py

Benchmarks

agentfem.benchmark.c3d10h_periodic_cell

Validation rules

Require the verified P2/DG0 pair for the constant-pressure provider.
Reject displacement-only consumption of known C3D10H source semantics.
Solve the constrained zero state and recover exactly zero displacement and pressure.
Reject any accepted increment with non-positive quadrature-point J.
Preserve every pressure dof as an independent reduced unknown under serial affine-periodic constraints.
Recover the actual macro deformation gradient from solved reference-point motion whenever a macro component is free.
For three-dimensional uniaxial stress, solve both transverse normal macro components and suppress only the macro shear components.

References¶

Abaqus three-dimensional solid element library: C3D10H constant-pressure hybrid tetrahedron: https://docs.software.vt.edu/abaqusv2024/English/SIMACAEELMRefMap/simaelm-r-3delem.htm
Abaqus hybrid incompressible solid formulation: https://docs.software.vt.edu/abaqusv2024/English/SIMACAETHERefMap/simathe-c-hybridincompress.htm
DOLFINx mixed function-space API: https://docs.fenicsproject.org/dolfinx/main/python/generated/dolfinx.fem.html
Luo et al., nonlinear elastic composites with spherical particles or voids, European Journal of Mechanics A/Solids (2023), 105076: https://doi.org/10.1016/j.euromechsol.2023.105076

Proportional and ordered-path mixed-mode cyclic cohesive damage¶

Stable ID: agentfem.material.mixed_mode_cyclic_cohesive
Kind: material
Status: experimental
Source card: knowledge/cards/mixed_mode_cyclic_cohesive.json

Layers explicit proportional-extrema or ordered within-cycle local cohesive-energy drivers on the mixed-mode bilinear envelope while preserving full jump vectors, BK or power interaction, atomic cycle transactions and physically keyed restart.

Public API¶

agentfem.fatigue_fracture.MixedModeEnergyRange
agentfem.fatigue_fracture.MixedModeEnergyRangeDriver
agentfem.fatigue_fracture.OrderedJumpCyclePath
agentfem.fatigue_fracture.OrderedMixedModeEnergyPathDriver
agentfem.fatigue_fracture.MixedModeCyclicCohesiveLaw
agentfem.fatigue_fracture.MixedModeCyclicCohesiveTransaction
agentfem.fatigue_fracture.mixed_mode_energy_range_driver
agentfem.fatigue_fracture.ordered_jump_cycle
agentfem.fatigue_fracture.ordered_mixed_mode_energy_path_driver
agentfem.fatigue_fracture.cyclic_work_energy_ledger
agentfem.fatigue_fracture.cyclic_cohesive
agentfem.fatigue_fracture.global_cyclic_fatigue_step
agentfem.interfaces.mixed_mode_bilinear_cohesive
agentfem.fracture.cohesive_force

Scientific contract¶

A mixed-mode fatigue update consumes either true accepted valley/peak vectors for a proportional cycle or an ordered closed sequence of within-cycle jump vectors, resolves work-conjugate normal and shear cohesive-energy variations, and advances one replaceable irreversible state through a declared interaction rule.

local cohesive energy channels

\[ G_I^coh=0.5 K_n<delta_n>^2, G_II^coh=0.5 K_t||delta_t||^2 \]

These material-point damage drivers are explicitly distinguished from a structure-level J-integral or VCCT result.

BK range interaction

\[ G_c(beta)=G_Ic+(G_IIc-G_Ic) beta^eta, beta=Delta G_II/(Delta G_I+Delta G_II) \]

A power-law interaction is available through the same explicit driver contract.

reference cyclic evolution

\[ dD_f/dN=C<Delta G_bar>^m(1-D_f)^p \]

The normalized range includes the mixed threshold and critical energy, and constant extrema use exact residual-power integration.

ordered path measure

\[ Phi_path=sum_s I_s <Delta G_s-G_th(beta_s)>_+/(G_c(beta_s)-G_th(beta_s)) \]

Positive variations of each local cohesive energy channel retain their order and segment mode mix; channel unloading does not create a second fictitious fatigue increment, while constant-total-energy mode transfer is preserved.

Inputs¶

Name	Type	Unit role	Meaning
mixed monotonic law	MixedModeBilinearCohesiveLaw	traction-separation envelope	Declares normal/shear strength, stiffness, fracture energies and BK or power interaction.
energy-range driver	MixedModeEnergyRangeDriver	cohesive energy per area	Declares threshold fractions, interaction and admissible proportionality tolerances.
cycle extrema	two local jump-vector arrays	length	Accepted valley and peak vectors in the deterministic local interface basis.
ordered cycle path	OrderedJumpCyclePath	cycle phase and length	A strictly ordered, closed sequence of three or more accepted local jump-vector stations for non-proportional cycles.

Outputs¶

Name	Type	Unit role	Meaning
mixed cyclic response	traction, tangent, damage and energy arrays	interface response	Separates monotonic and fatigue damage and dissipation while preserving compression closure.
cycle evidence fields	material-aware quadrature arrays	jump, cohesive energy and cycle count	Includes jump extrema, GI/GII ranges, critical/threshold energy, normalized range, local ratio and cycles.
portable cycle state	physical-facet-keyed scalar and vector components	restart state	Restores across facet order and MPI rank-count changes independently of DOF numbering.

Assumptions¶

The cohesive crack path is fixed.
A valley/peak pair is used only for proportional or near-proportional cycles; non-proportional cycles declare an ordered closed path.
Fatigue coefficient and exponents require material/interface calibration for predictive work.

Conventions¶

Local jump component zero is normal and the remaining components are tangential.
GI_COH and GII_COH names denote local cohesive-law drivers, not structural energy-release rates.
Non-proportional mode mix and tangential reversal are rejected by the extrema driver and retained station-by-station by the ordered-path driver.
No cycle advancement preserves the wrapped mixed-mode monotonic response.

Applicability¶

Fixed-path two- or three-dimensional cohesive fatigue under proportional or ordered non-proportional Mode-I, Mode-II and mixed-mode cycles.

Limitations¶

The ordered reference driver resolves a supplied closed path but does not infer an unresolved waveform, frictional fatigue dissipation or free-path crack growth.
No external calibrated mixed-mode fatigue structural benchmark has promoted this experimental reference law.
Bulk-field durable restart remains partition-sensitive even though cohesive state is cross-rank-count portable.

Minimal example¶

driver = fatigue_fracture.ordered_mixed_mode_energy_path_driver(mode_i_threshold_fraction=0.05, mode_ii_threshold_fraction=0.05); law = fatigue_fracture.cyclic_cohesive(monotonic=interfaces.mixed_mode_bilinear_cohesive(...), driver=driver, fatigue_coefficient=C, fatigue_exponent=m, residual_exponent=p, range_threshold=0.0); path = fatigue_fracture.ordered_jump_cycle(phases, local_jump_history); state.begin_cycle_path(path, cycles=dN)

Verification¶

Tests

tests/test_fatigue_fracture.py
tests/test_global_cohesive_residual.py
tests/test_parallel_cohesive.py
tests/portable_mixed_cyclic_cohesive_driver.py

Benchmarks

agentfem.benchmark.mixed_mode_cyclic_cohesive_foundation

Validation rules

Pure-mode GI/GII channels and BK interaction match analytical values.
Tangential basis rotation does not change the driving range.
Non-proportional peak/valley paths are rejected by the extrema driver and an ordered closed path retains every resolved station.
Ordered-path exact cycles and one fixed-path cycle jump agree, and rollback/restart preserve path evidence.
Named reference-point, prescribed-motion and MPC work channels participate in the same transactional cycle-block energy ledger.
Exact cycles and one constant-extrema jump agree.
Local, global, serial, MPI and cross-rank-count restart consumers preserve all state fields.

References¶

Dávila, From S-N to Paris Law with a New Mixed-Mode Cohesive Fatigue Model: https://ntrs.nasa.gov/api/citations/20180004395/downloads/20180004395.pdf
Leone et al., Scalability of Cohesive Fatigue Analyses Using Explicit Solvers: https://ntrs.nasa.gov/api/citations/20205010748/downloads/scitech2021_leone_v8.pdf
AgentFEM cyclic cohesive fatigue architecture: docs/cyclic_cohesive_fatigue_architecture.md

Mooney--Rivlin finite-strain solids and incompressible sheets¶

Stable ID: agentfem.material.mooney_rivlin_hyperelasticity
Kind: material
Status: experimental
Source card: knowledge/cards/mooney_rivlin_hyperelasticity.json

Provides a compressible three-dimensional Mooney--Rivlin energy and the exact incompressible plane-stress sheet reduction of Wang--Fineberg--Needleman Eq. (17), consumed by static and finite-strain Explicit workflows.

Public API¶

agentfem.constitutive.mooney_rivlin
agentfem.constitutive.mooney_rivlin_plane_stress
agentfem.fracture.incremental_wave_speeds
agentfem.models.Model.step

Scientific contract¶

The material energy, first-Piola stress, consistent finite-element residual, recoverable energy, numerical material tangent, and prestrained acoustic tensor all derive from one declared Mooney--Rivlin parameterization.

compressible three-dimensional energy

\[ \psi=C_{10}(\bar I_1-3)+C_{01}(\bar I_2-3)+\frac{K}{2}(J-1)^2,\quad \mu=2(C_{10}+C_{01}) \]

A decoupled isochoric/volumetric Mooney--Rivlin form for positive-J three-dimensional solids.

incompressible plane-stress sheet energy

\[ \psi=\frac{\mu}{2}[c(I+J^{-2}-3)+(1-c)(J^2+IJ^{-2}-3)] \]

The reduced Eq. (17) form uses in-plane I=tr(FF^T), J=det(F), and thickness stretch J^-1.

Inputs¶

Name	Type	Unit role	Meaning
shear_modulus and first_invariant_fraction	positive stress and scalar c in [0,1]	stress and dimensionless	C10=muc/2 and C01=mu(1-c)/2.
bulk_modulus	positive stress	stress	Required by the compressible three-dimensional form and absent from the exact incompressible sheet reduction.

Outputs¶

Name	Type	Unit role	Meaning
energy, first-Piola/Cauchy stress, tangent, and wave speeds	scalar, second-order tensors, fourth-order tensor, and scalars	energy density, stress, tangent stress, and length/time	All consumers use the same declared energy and positive-J finite kinematics.

Assumptions¶

The material is isotropic and hyperelastic.
The incompressible plane-stress route represents a thin sheet with thickness stretch equal to the inverse in-plane area ratio.
Density is required for Explicit dynamics and acoustic analysis.

Conventions¶

The three-dimensional factory is not silently used in a two-dimensional Study.
The plane-stress factory must be paired with assumption='plane_stress'.
The Wang--Fineberg--Needleman paper uses Eq. (17) to characterize/convert experimental material response; its reported finite-element calculation is described separately as hypoelastic.

Applicability¶

Finite-strain rubber-like solids, incompressible thin sheets, and parameterized weak-interface dynamic-fracture studies.

Limitations¶

The current compressible form uses a penalty bulk energy rather than a mixed pressure field.
The incompressible sheet route is a two-dimensional reduction, not a general three-dimensional incompressibility algorithm.
Publication-level JMPS reproduction still requires the authors' geometry, cohesive parameters, loading history, and comparison data.

Minimal example¶

material = constitutive.mooney_rivlin_plane_stress(shear_modulus=500.5e3, first_invariant_fraction=0.2829, density=1020.0)
step = model.step(target=u, material=material, dt='auto', steps=100)

Verification¶

Tests

tests/test_dynamic_fracture.py
tests/test_dynamic_fracture_benchmarks.py

Benchmarks

agentfem.benchmark.mooney_rivlin_material_paths

Validation rules

Match the numerical sheet energy to Eq. (17) for a nontrivial deformation gradient.
Compare the material tangent with finite differences of first-Piola stress.
Verify the undeformed shear-wave speed against sqrt(mu/rho).
Run the material through the public finite-strain Explicit provider and the cohesive benchmark injection path.

References¶

Wang, Fineberg, and Needleman (2025), transition from crack-type to supershear-type to spall-type dynamics: https://doi.org/10.1016/j.jmps.2025.106213

Finite-element operator and system contracts¶

Stable ID: agentfem.operator.system_contracts
Kind: operator
Status: supported
Source card: knowledge/cards/operator_system_contracts.json

Names, composes, validates, and records matrix, vector, residual, scalar, and K/M/C/F system structure while delegating symbolic weak-form execution to UFL and DOLFINx.

Public API¶

agentfem.operators.OperatorForm
agentfem.operators.first_order_system
agentfem.operators.second_order_system
agentfem.operators.residual_operator
agentfem.operators.linearize
agentfem.operators.robin_operator
agentfem.operators.rayleigh_damping

Scientific contract¶

The operator layer preserves familiar finite-element systems and the nonlinear residual/tangent relation as inspectable scientific objects, while UFL owns symbolic forms and automatic differentiation.

static system

\[ \mathbf{K}\mathbf{x}=\mathbf{F} \]

A matrix-like stiffness/operator and compatible external vector define the supported static linear structure.

first-order system

\[ \mathbf{C}\dot{\mathbf{x}}+\mathbf{K}\mathbf{x}=\mathbf{F} \]

Capacity/storage and diffusion/conduction operators define heat- and diffusion-like evolution.

second-order system

\[ \mathbf{M}\ddot{\mathbf{u}}+\mathbf{C}\dot{\mathbf{u}}+\mathbf{K}\mathbf{u}=\mathbf{F} \]

Mass, damping, stiffness, and force remain visible independently of the chosen implicit or explicit procedure.

nonlinear tangent

\[ \mathbf{R}(\mathbf{u})=\mathbf{0},\qquad \mathbf{K}_{t}=\frac{\partial\mathbf{R}}{\partial\mathbf{u}} \]

A named weak residual is differentiated by UFL and recorded as the source of its consistent tangent.

Inputs¶

Name	Type	Unit role	Meaning
weak form	UFL form or backend expression	problem dependent	Executable bilinear, linear, residual, or functional expression.
scientific identity	name, role, family, operation, metadata	none	Stable human- and agent-readable meaning layered over the backend expression.

Outputs¶

Name	Type	Unit role	Meaning
OperatorForm	inspectable operator	inherits weak form	Supports composition, validation, assembly, summaries, and serializable scientific metadata.
ValidationReport	addressable issues	none	Checks declared matrix/vector/residual/scalar role against weak-form argument count.

Assumptions¶

UFL form argument count identifies scalar, linear, and bilinear form structure.
Operator compatibility includes role compatibility; complete dimensional/unit algebra is not yet automatic.
System containers describe equations but do not select a solution procedure.

Conventions¶

K, M, C, and F retain conventional finite-element meanings.
A residual has one test argument even when its dependence on the unknown is nonlinear.
Derived sums, scales, and linearizations retain their operand provenance.

Applicability¶

Linear elasticity, heat transfer, structural dynamics, and custom nonlinear weak-form workflows on the FEniCSx backend.

Limitations¶

Automatic physical unit propagation is not implemented.
Block/mixed-space domain and range compatibility is not yet checked.
An opaque backend operator without UFL arguments can be named but its arity cannot be automatically verified.

Minimal example¶

Create C = operators.capacity_operator(T, rho_c), K = operators.conduction_operator(T, k), then system = operators.first_order_system(C, K, Q) and call system.check().

Verification¶

Tests

tests/test_operators.py

Benchmarks

agentfem.benchmark.operator_contracts

Validation rules

Reject unknown operator roles and derived operations without provenance.
Reject matrix/vector/residual/scalar declarations whose UFL argument count is incompatible.
Reject incompatible system component roles before numerical assembly.

References¶

Cast3M presentation and principles of development: https://www-cast3m.cea.fr/html/ManuelCastemEnsta/ManuelCastemEnsta.html
UFL automatic differentiation manual: https://docs.fenicsproject.org/ufl/2026.1.0/manual/form_language.html

Abaqus node sets and element-face surfaces as FEM regions¶

Stable ID: agentfem.workflow.abaqus_engineering_regions
Kind: workflow
Status: supported
Source card: knowledge/cards/abaqus_engineering_regions.json

Promotes source-labelled Abaqus NSET and supported exterior SURFACE definitions into distinct DOLFINx node and facet regions.

Public API¶

agentfem.mesh.read_abaqus_mesh
agentfem.mesh.abaqus.AbaqusMeshImport.node_set
agentfem.mesh.abaqus.AbaqusMeshImport.boundary
agentfem.mesh.abaqus.AbaqusMeshImport.surface_faces

Scientific contract¶

Source labels and official element-face numbering determine engineering regions; coordinate proximity is used only to recover explicit source-to-runtime node or vertex identity within a declared tolerance.

source-to-runtime node identity

\[ \operatorname{selected}(\mathbf{x}_h) \iff \exists!\, n:\; \lVert\mathbf{x}_h-\mathbf{x}_n\rVert \le \mathrm{tol} \]

The coordinate match preserves explicit source-node identity, including high-order nodes; absence or ambiguity is an error rather than a geometric selection rule.

Inputs¶

Name	Type	Unit role	Meaning
Abaqus source and converted solver domain	keyword nodes/elements/sets/surfaces plus one selected topology	geometry length	The conversion fingerprint binds the source, topology choice, and XDMF artifact.

Outputs¶

Name	Type	Unit role	Meaning
NodeRegion or BoundaryRegion	source-node coordinate region or tagged exterior facets	none; boundary measure inherits geometry units	Strong constraints consume node regions; weak loads consume boundary regions through ds(tag).

Assumptions¶

Source node and element labels are unique in the selected import scope.
A reconstructed boundary face is exterior to the selected solver domain.

Conventions¶

NSET does not acquire a surface measure.
High-order source nodes such as C3D10 midside nodes remain addressable by compatible finite-element spaces.
SURFACE face identifiers follow Abaqus solid-element node ordering.
Unknown or ambiguous semantics fail instead of being inferred from a normal or bounding box.

Applicability¶

C3D4/C3D10 and C3D8-family external solid meshes with explicit NSET/ELSET/SURFACE data.

Limitations¶

Assembly/instance-scoped duplicate labels, free-surface generation, internal dS interfaces, and other element families need dedicated adapters.
This is mesh and region interoperability, not full Abaqus solver-deck execution.

Minimal example¶

cell = mesh.read_abaqus_mesh('part.inp', 'part.xdmf'); fixed = cell.node_set('FIXED'); loaded = cell.boundary('LOAD_FACE')

Verification¶

Tests

tests/test_abaqus_interop.py

Benchmarks

None declared.

Validation rules

Recover every requested source node or fail with missing labels.
Match every requested face to one exterior runtime facet.
Reject unsupported element families and face identifiers.
Verify the reconstructed boundary facet count and physical measure.

References¶

Abaqus element-based surface definition: https://docs.software.vt.edu/abaqusv2024/English/SIMACAEMODRefMap/simamod-c-deformablesurf.htm
Abaqus three-dimensional solid node ordering and face numbering: https://docs.software.vt.edu/abaqusv2024/English/SIMACAEELMRefMap/simaelm-r-3delem.htm

Simulation campaign to guarded learning workflow¶

Stable ID: agentfem.workflow.campaign_learning_pipeline
Kind: workflow
Status: supported
Source card: knowledge/cards/campaign_learning_pipeline.json

Turns quality-gated deterministic simulations into scientific datasets, independent surrogate validation, optional PyTorch tensors, applicability decisions, and explicit high-fidelity fallback.

Public API¶

agentfem.campaigns.CampaignReport.require_dataset
agentfem.datasets.ScientificDataset.to_torch
agentfem.surrogates.train
agentfem.surrogates.GuardedSurrogate

Scientific contract¶

Learning begins only after cases, declared quantities, provenance, failures, and an independent validation split are materialized as evidence.

scientific dataset

\[ \mathcal{D}=\{(\mathbf{p}_i,\mathbf{q}_i,\pi_i)\mid i\in\mathcal{I}_{\mathrm{reviewed}}\} \]

Parameters and quantities retain names, bounds, units, shapes, case identity, and evidence.

guarded prediction

\[ \widehat{\mathbf{q}}(\mathbf{p})=\begin{cases}\mathcal{S}(\mathbf{p}), & \mathbf{p}\in\mathcal{A},\\ \mathcal{F}_{\mathrm{FEM}}(\mathbf{p})\;\text{or reject}, & \mathbf{p}\notin\mathcal{A}.\end{cases} \]

A learned model never silently extrapolates beyond its declared domain.

Inputs¶

Name	Type	Unit role	Meaning
campaign	parameter space, sampling, builder, evaluator	declared per parameter and quantity	Defines reproducible simulations and output contracts before execution.
estimator	fit/validate protocol	inherits dataset schema	Transparent baseline, PyTorch adapter, or compatible external trainer.

Outputs¶

Name	Type	Unit role	Meaning
ScientificDataset	manifest plus numeric arrays	preserved per quantity	Successful reviewed cases linked to artifacts and provenance.
SurrogateTrainingRun	model, split, validation report	preserved by named decoding	Keeps training and independent validation evidence together.

Assumptions¶

Each case uses a fresh or safely reset model.
Output names, shapes, and units are declared before execution.
At least three successful samples exist for split training.

Conventions¶

Failed cases block dataset consumption by default.
Named result quality policies can gate every sample before dataset admission.
Categorical parameters use one-hot encoding.
PyTorch remains the optional tensor and training runtime.

Applicability¶

Parameter sweeps, surrogate baselines, reduced-order data, and guarded acceleration of supported FEM workflows.

Limitations¶

Case-level scheduler execution uses deterministic plan shards rather than Python threads.
Residual-scale uncertainty is not calibrated epistemic uncertainty.
Automatic arbitrary-mesh neural-operator training is not implemented.

Minimal example¶

dataset = report.require_dataset(quality='engineering'); training = surrogates.train(dataset); guarded = training.guard(fallback=run_fem).

Verification¶

Tests

tests/test_campaigns.py
tests/test_datasets.py
tests/test_surrogates.py

Benchmarks

agentfem.benchmark.campaign_surrogate_pipeline

Validation rules

Reject missing, non-finite, or wrong-shaped outputs.
Reject partial campaign data by default.
Reject samples that did not pass the requested quality policy.
Reject silent out-of-domain prediction without fallback.

References¶

AgentFEM results and campaigns contract: docs/results_and_campaigns.md

Physical-keyed cohesive state across MPI partitions¶

Stable ID: agentfem.workflow.cohesive_state_portability
Kind: workflow
Status: experimental
Source card: knowledge/cards/cohesive_state_portability.json

Assigns every locally visible cohesive facet one deterministic MPI owner and saves every declared committed quadrature-state field by ordered physical facet key, allowing a changed facet order or MPI rank count to recover the same irreversible monotonic or cyclic state.

Public API¶

agentfem.interfaces.deterministic_facet_ownership
agentfem.interfaces.save_portable_cohesive_state
agentfem.interfaces.load_portable_cohesive_state
agentfem.interfaces.FacetOwnership

Scientific contract¶

Irreversible interface state belongs to an oriented physical facet and quadrature point, not to a transient rank-local degree-of-freedom number.

physical state key

\[ k_f=H(\operatorname{quantize}(\mathbf{X}_{f,1},\mathbf{X}_{f,2};\tau),\mathbf{N}_f,|\Gamma_f|,q) \]

Ordered reference endpoints, normal orientation, length, tolerance, and quadrature contract define the restart identity.

deterministic visible owner

\[ r_f=R_f[H(k_f)\bmod |R_f|] \]

The hash selects one rank from the sorted ranks on which the physical facet is visible.

Inputs¶

Name	Type	Unit role	Meaning
paired physical facets	PairedLineFacets with ordered reference-geometry keys	reference geometry	Every local facet key is unique; ghost overlap across ranks is permitted.
committed cohesive transaction	named quadrature-state arrays per facet and one law contract	opening length	Trial state must not be mistaken for accepted restart state.

Outputs¶

Name	Type	Unit role	Meaning
FacetOwnership	local ownership mask and global key-to-rank map	topology metadata	Provides one owner among the ranks able to assemble a visible facet.
portable cohesive checkpoint	SHA-256 checked JSON manifest and keyed NPZ state	preserves cohesive law units	Schema v2 restores all law-declared local arrays in current facet order after verifying the global physical interface, state layout and law; the reader retains monotonic schema-v1 compatibility.

Assumptions¶

All ranks participate collectively and share the checkpoint filesystem.
Duplicate visibility denotes the same oriented physical facet; incompatible committed owner/ghost values are rejected before writing.
The current interface contains exactly the stored physical key set.

Conventions¶

Facet orientation and quadrature order are identity-bearing.
Execution-local dof and rank numbers are not scientific state identity.
A changed partition may change the owner without changing the state key.

Applicability¶

Fixed-path two-dimensional Mode-I cohesive interfaces and the distributed sparse-payload force assembler using the same physical-key contract.

Limitations¶

Distributed residual assembly uses a sparse physical-node owner schedule; this state card alone is not an extreme-scale performance claim.
The root-gathered NPZ format is laboratory-scale, not an extreme-scale collective checkpoint backend.
State fields must be finite scalar arrays with one value per interface quadrature point.
Reversed facet orientation is intentionally incompatible until quadrature permutation is explicitly implemented.

Minimal example¶

ownership = interfaces.deterministic_facet_ownership(topology, comm=comm); manifest = interfaces.save_portable_cohesive_state('state', topology, transaction, comm=comm); interfaces.load_portable_cohesive_state(manifest, topology, transaction, comm=comm)

Verification¶

Tests

tests/test_interfaces.py
tests/portable_cohesive_checkpoint_driver.py

Benchmarks

None declared.

Validation rules

Reject a changed law, missing/extra physical facet, corrupted archive, nonphysical legacy key, multiple owners, or inconsistent owner/ghost state.
Write with two ranks containing overlapping visible facets, then read with one rank in a different facet order and recover identical state.

References¶

AgentFEM dynamic cohesive fracture architecture: docs/dynamic_cohesive_fracture_architecture.md
DOLFINx parallel checkpointing demo: https://docs.fenicsproject.org/dolfinx/main/python/demos/demo_checkpointing.html

Local coordinates and reference-point continuum coupling¶

Stable ID: agentfem.workflow.coordinate_reference_coupling
Kind: workflow
Status: supported
Source card: knowledge/cards/coordinate_reference_coupling.json

Maps explicit local components to global finite-element loads and applies force/moment or known rigid motion through a named continuum reference point.

Public API¶

agentfem.coordinates.cartesian
agentfem.coordinates.reference_point
agentfem.loads.remote_force
agentfem.constraints.remote_displacement
agentfem.models.Model.remote_force
agentfem.models.Model.remote_displacement

Scientific contract¶

A right-handed orthonormal basis makes component conventions explicit; remote resultants and known rigid motions are then transferred to a continuum boundary without a singular solid-node force.

local-to-global vector

\[ \mathbf{v}_{\mathrm{global}}=\mathbf{Q}^{T}\mathbf{v}_{\mathrm{local}} \]

Rows of Q are local basis vectors expressed in global components.

rigid boundary motion

\[ \mathbf{u}(\mathbf{x})=\mathbf{u}_{\mathrm{RP}}+\boldsymbol{\theta}\times(\mathbf{x}-\mathbf{x}_{\mathrm{RP}}) \]

The prescribed displacement is evaluated on every constrained boundary dof.

remote resultant

\[ \int_{\Gamma}\mathbf{t}\,d\Gamma=\mathbf{F}_{\mathrm{RP}},\qquad \int_{\Gamma}(\mathbf{x}-\mathbf{x}_{\mathrm{RP}})\times\mathbf{t}\,d\Gamma=\mathbf{M}_{\mathrm{RP}} \]

The distributing traction preserves force and moment about the named point.

Inputs¶

Name	Type	Unit role	Meaning
coordinate system and reference point	orthonormal basis, origin, and finite point coordinates	length and dimensionless rotation	Local axes must be right handed and match the model dimension.

Outputs¶

Name	Type	Unit role	Meaning
continuum load or strong rigid-motion constraint	weak boundary load or Dirichlet asset	force/moment or displacement/rotation	Both assets are consumed by ordinary model steps and retain engineering summaries.

Assumptions¶

The selected surface has sufficient geometric extent to transmit a requested moment.
remote_displacement specifies known rigid motion rather than solving for an independent reference-point degree of freedom.

Conventions¶

Coordinate-system axes are stored by row in global components.
Two-dimensional rotation and moment are scalar out-of-plane quantities.
Constant remote displacement follows the normalized nonlinear load path.

Applicability¶

Fixture coordinates, remote loading, driven grips, and continuum-solid coupling surfaces.

Limitations¶

An unknown kinematic reference-point degree of freedom and general MPC coupling are not implemented by this contract.
Local component constraints on an arbitrary oblique direction require a dedicated MPC rather than a component Dirichlet approximation.

Minimal example¶

local = coordinates.cartesian(x=(0,1), y=(-1,0)); rp = coordinates.reference_point((2,0.5), name='RP-1'); model.remote_force((3,4), moment=2, reference_point=rp, system=local, on=end)

Verification¶

Tests

tests/test_coordinates.py
tests/test_engineering_workflows.py

Benchmarks

None declared.

Validation rules

Reject non-orthonormal and left-handed bases.
Reject coordinate, vector, rotation, and target dimension mismatches.
Integrate generated traction and recover transformed force and requested moment.
Verify remote motion follows deterministic load-factor scaling.

References¶

Abaqus distributing coupling constraints: https://docs.software.vt.edu/abaqusv2024/English/SIMACAECSTRefMap/simacst-c-coupling.htm

Transactional generalized work and cycle-block energy ledger¶

Stable ID: agentfem.workflow.cyclic_work_energy_ledger
Kind: workflow
Status: experimental
Source card: knowledge/cards/cyclic_work_energy_ledger.json

Accounts named force-motion and material-energy channels in the same begin/commit/rollback and restart boundary as a global fatigue cycle block.

Public API¶

agentfem.fatigue_fracture.GeneralizedWorkSample
agentfem.fatigue_fracture.CyclicEnergyFrame
agentfem.fatigue_fracture.CyclicWorkEnergyLedger
agentfem.fatigue_fracture.generalized_work_sample
agentfem.fatigue_fracture.reference_point_work_sample
agentfem.fatigue_fracture.cyclic_work_energy_ledger
agentfem.fatigue_fracture.CyclicEquilibriumPoint
agentfem.fatigue_fracture.global_cyclic_fatigue_step

Scientific contract¶

External work is a sum over named work-conjugate generalized forces and motions; recoverable and dissipative energy channels are compared through their committed cycle-block increments.

resolved station work

\[ Delta W_q=0.5(Q_i+Q_(i+1)) dot (q_(i+1)-q_i) \]

Vector force-translation and moment-rotation pairs share the same trapezoidal contract.

cycle-block balance

The acceptance error participates in the global cycle transaction rather than being calculated after irreversible state is committed.

Inputs¶

Name	Type	Unit role	Meaning
generalized work channels	named GeneralizedWorkSample records at every resolved station	force-motion or moment-rotation work	Roles include natural load, reference point, prescribed motion, MPC, weak constraint and contact constraint.
energy channels	named finite total-energy values at every station	energy	Declared at block start and trial end; may include recoverable bulk/interface energy, kinetic energy and monotonic, fatigue, cohesive or numerical dissipation.

Outputs¶

Name	Type	Unit role	Meaning
cyclic energy frame	CyclicEnergyFrame	energy and dimensionless balance error	Separates resolved-cycle work, explicitly estimated skipped-cycle work, per-channel/per-role block work, energy increments and closure error.
restartable ledger	versioned snapshot	accepted evidence	Only accepted frames survive rollback and checkpoint restore.

Assumptions¶

Every station exposes the same uniquely named generalized work and energy channels.
Generalized force signs follow work done on the finite-element model.
For a cycle jump, the solved representative closed-cycle work is multiplied by the accepted cycle count and labelled as an estimate.

Conventions¶

Reference-point force and translation are concatenated with moment and rotation.
Representative closed-cycle work and block endpoint energy increments are distinct; post-damage verification is not multiplied by the cycle jump.
MPC, weak/contact and prescribed-motion work require actual provider reactions; missing reactions are not guessed.
Energy balance rejection rolls back fields, interfaces, cycle identity and energy evidence atomically.

Applicability¶

Quasi-static cyclic fatigue consumers with named load, constraint and material-energy evidence.

Limitations¶

The ledger defines the complete accounting protocol, but not every native solver provider yet extracts every generalized reaction automatically.
Representative-cycle work multiplication is not an error estimator for changing within-block hysteresis; cycle-jump convergence remains required.

Minimal example¶

ledger = fatigue_fracture.cyclic_work_energy_ledger(); point = fatigue_fracture.CyclicEquilibriumPoint(..., generalized_work=(fatigue_fracture.reference_point_work_sample(load, translation=u_rp, rotation=theta_rp),), energy_channels={"recoverable": E, "cohesive_dissipation": D}); step = fatigue_fracture.global_cyclic_fatigue_step(..., energy_ledger=ledger, maximum_energy_balance_error=tol)

Verification¶

Tests

tests/test_fatigue_fracture.py

Benchmarks

agentfem.benchmark.mixed_mode_cyclic_cohesive_foundation

Validation rules

Named reference-point, prescribed-motion and MPC channels integrate to the analytical generalized work.
Cycle-block work and declared energy increments close within the requested tolerance.
An imbalanced block rejects without committing any energy frame.
Interrupted and restored ledgers preserve accepted frame identity.

References¶

Abaqus total energy output and energy balance definitions: https://docs.software.vt.edu/abaqusv2024/English/SIMACAEOUTRefMap/simaout-c-exp-totalenergyoutput.htm
AgentFEM cyclic cohesive fatigue architecture: docs/cyclic_cohesive_fatigue_architecture.md

Sparse physical-keyed cohesive force assembly across MPI ranks¶

Stable ID: agentfem.workflow.distributed_cohesive_force
Kind: workflow
Status: experimental
Source card: knowledge/cards/distributed_cohesive_force.json

Recovers a split two-dimensional interface from declared cell sides, builds one durable input-node owner schedule, exchanges only required remote traces and force contributions, evaluates every physical facet on exactly one balanced deterministic rank, and writes only owned displacement entries.

Public API¶

agentfem.interfaces.create_dolfinx_split_mesh
agentfem.interfaces.split_conforming_cell_interface
agentfem.fracture.cohesive_force
agentfem.fracture.mode_i_cohesive_force
agentfem.fracture.DistributedDofMappedCohesiveForce
agentfem.fracture.FiniteStrainCohesiveResidual

Scientific contract¶

The two sides of a zero-thickness interface may belong to disconnected bulk partitions; interface residuals must therefore follow physical pair identity rather than assuming ordinary cell ghosts expose both displacement traces.

paired interface virtual work

\[ \delta W_{\mathrm{coh}}=\sum_{f\in\Gamma_c}\int_{\Gamma_f} t_n(\llbracket u\rrbracket_n,\kappa_f)\,\llbracket\delta u\rrbracket_n\,\mathrm d\Gamma \]

Every physical facet contributes once; its positive and negative nodal forces are equal and opposite.

balanced deterministic facet owner

\[ r_f=\operatorname{rank}_{\mathrm{sorted}}(k_f)\bmod N_r \]

Sorted physical facet keys distribute work reproducibly and give every rank a facet when the interface has at least as many facets as ranks.

interface-scaled communication payload

\[ N_{\mathrm{payload},r}=d\,|\mathcal N_{\Gamma,r}^{\mathrm{remote}}| \]

Each rank sends displacement traces and force contributions only for remote physical interface nodes required by its owned facets, rather than arrays proportional to all bulk nodes.

Inputs¶

Name	Type	Unit role	Meaning
split interface mesh	SplitInterfaceMesh	reference geometry	Coincident sides retain independent input-node identities and explicit positive/negative facet pairing.
cohesive law and displacement	BilinearCohesiveLaw or MixedModeBilinearCohesiveLaw and blocked P1 vector Function	consistent mechanical units	The same public factory selects serial or MPI execution from the mesh communicator.

Outputs¶

Name	Type	Unit role	Meaning
distributed cohesive residual	owned PETSc vector contributions plus transactional facet state	force and opening length	Bulk and cohesive forces enter one Explicit residual without duplicate ghost accumulation.
portable transient restart	coordinate/input-node-keyed nodal state plus physical-facet-keyed cohesive history	preserves field and law units	A two-rank split-interface Explicit step is continued on one rank and compared with an uninterrupted reference.

Assumptions¶

The current reference routes use two-node line facets in 2D or three-node triangular facets in 3D and a blocked first-order displacement field.
All ranks construct the same audited SplitInterfaceMesh and participate in collective force, energy, snapshot, and restart operations.
The interface contains at least one physical facet per MPI rank.

Conventions¶

Only owned input-node values are published; only owned displacement entries receive the globally reduced force.
The owner/request schedule is built once; accepted and attempted increments reuse numeric MPI_Alltoallv payload layouts.
Each facet owner compacts its local cohesive kernel to the physical interface nodes touched by its facets.
Facet state follows ordered physical geometry and quadrature, never rank-local DOF numbering.
Coincident independent nodal checkpoint keys append durable input-node identity to the quantized coordinate.

Applicability¶

Distributed fixed-path Mode-I finite-strain Explicit dynamics, conforming 2D/3D cell-partition interfaces, Abaqus/Gmsh named-interface lowering, and cross-rank-count restart verification.

Limitations¶

The implementation uses sparse payloads on a communicator-wide Alltoallv schedule; extreme-scale neighborhood-collective performance is not yet benchmarked.
Vector and mixed-mode coupling use the same MPI consumer; quadratic surface interpolation and arbitrary nonconforming interfaces are not yet covered.
MPI execution is experimental and does not promote the V4/V5 scientific benchmark to validated status.

Minimal example¶

split = interfaces.split_conforming_cell_interface(points, cells, positive_cells=upper_cells); domain = interfaces.create_dolfinx_split_mesh(split, comm=MPI.COMM_WORLD); U = fields.displacement(domain); cohesive = fracture.mode_i_cohesive_force(split, U, law, normal_hint=(0, 1)); step = model.finite_strain_explicit_dynamics_step(target=U, material=material, cohesive_force=cohesive, dt=dt, steps=steps)

Verification¶

Tests

tests/test_parallel_cohesive.py
tests/portable_cohesive_dynamics_driver.py
tests/test_global_cohesive_residual.py

Benchmarks

agentfem.benchmark.distributed_cohesive_force

Validation rules

Three physical facets are owned exactly once across two ranks and produce zero net interface force with the exact integrated tensile resultant.
A nonuniform interface spanning compression, elastic loading, and softening matches the serial kernel node by node and in both energy channels.
The execution summary reports sparse remote trace and force payloads bounded by required interface nodes rather than all mesh nodes.
The local assembler node count equals the scheduled interface-node count and is smaller than the split volume-node count in the acceptance mesh.
The public finite-strain Explicit step completes on two ranks with globally identical energy history.
The sparse communication schedule and nonuniform serial equivalence also pass when three facets are assigned across three MPI owners.
A two-rank partial Explicit calculation restarts on one rank and matches uninterrupted displacement and cohesive history.

References¶

AgentFEM dynamic cohesive fracture architecture: docs/dynamic_cohesive_fracture_architecture.md
DOLFINx mesh creation and partitioning API: https://docs.fenicsproject.org/dolfinx/main/python/generated/dolfinx.mesh.html

Publication-data evidence for dynamic cohesive fracture¶

Stable ID: agentfem.workflow.dynamic_fracture_v5_evidence
Kind: workflow
Status: experimental
Source card: knowledge/cards/dynamic_fracture_v5_evidence.json

Pins public fracture observations by version and hash, preserves accepted cohesive-interface traces, estimates fronts from multiple physical observers, and compares curves, Mach angles, and rectilinear fields without turning one fitted case into a validation claim.

Public API¶

agentfem.datasets.science_supershear_dryad_manifest
agentfem.datasets.science_supershear_v5_research_task
agentfem.datasets.read_xlsx_workbook
agentfem.fracture.CohesiveInterfaceTrace
agentfem.fracture.cohesive_front_ensemble
agentfem.fracture.compare_curve
agentfem.fracture.compare_mach_cone
agentfem.fracture.compare_rectilinear_field
agentfem.fracture.compare_rectilinear_observations
agentfem.fracture.DynamicFractureEvidenceBundle
agentfem.surrogates.AffineCoordinateMap
agentfem.datasets.RectilinearObservation
agentfem.results.finite_strain_dynamic_cell_fields

Scientific contract¶

Publication comparison is a versioned transformation from immutable observations and converged simulation observables, with calibration separated from retained prediction conditions.

Mach cone

\[ \theta_M=\sin^{-1}(c_s/v) \]

The observed cone angle is compared with the shear-wave and crack speeds using one declared prestrain and coordinate convention.

normalized field error

\[ \mathrm{NRMSE}=\sqrt{N^{-1}\sum_i(y_i^{\mathrm{FEM}}-y_i^{\mathrm{obs}})^2}/(y_{\max}^{\mathrm{obs}}-y_{\min}^{\mathrm{obs}}) \]

The implementation falls back to observed RMS only when the observed range is numerically zero.

Inputs¶

Name	Type	Unit role	Meaning
external dataset manifest	version, DOI, license, roles, file sizes, and SHA-256 identities	metadata	Binds local observations to one official repository version.
cohesive interface trace	time by facet arrays of opening, traction, damage, and dissipated-energy density	model dependent and explicitly recorded	Retains accepted interface states without conflating density with global integrated energy.
reference and simulation observables	curves, scalar angles, or scalar rectilinear maps	must be harmonized before comparison	Only overlapping coordinates are compared; extrapolated pixels are excluded.
coordinate registration	explicit affine observation-to-model map with units and configuration	coordinate units	Records axis rotation, scale, and origin instead of hiding them in plotting code.

Outputs¶

Name	Type	Unit role	Meaning
ExternalDatasetAudit	missing, size mismatch, digest mismatch, and accepted status	evidence identity	Stops silent use of a different or corrupted public dataset.
CohesiveFrontEnsemble	multiple threshold-interpolated positions and window-fitted speeds	path coordinate and time	Reports observer sensitivity rather than one favorable failed-element velocity.
ScientificComparison	sample count, RMSE, NRMSE, correlation, overlap, and method metadata	same units as compared observable	A common evidence record for curve, Mach-angle, and field-map comparisons.
DynamicFractureEvidenceBundle	sealed manifest plus trace, energy channels, comparisons, and copied artifacts	preserved from every constituent	Provides one self-contained handoff to another researcher or agent; byte integrity is not an automatic validation claim.

Assumptions¶

Workbook units and coordinate conventions are reconstructed and reviewed before numeric comparison.
Calibration conditions and retained prediction conditions are frozen before parameter inference.
Simulation discretization, energy balance, and observer sensitivity are separately converged.

Conventions¶

Interface path coordinates and crack speeds use the declared reference configuration unless metadata says otherwise.
Damage is reduced by the facet quadrature maximum; opening, traction, and dissipated-energy density use facet quadrature means.
Rectilinear simulation fields are bilinearly interpolated to observed grid points only within their common domain.
A masked comparison accepts a point only when every contributing simulation grid point and the observed point are inside their declared domains.

Applicability¶

Science 2023 public supershear observations and future versioned dynamic-fracture datasets with equivalent curve or grid observables.

Limitations¶

The public Science observations are not a complete JMPS 2025 computational input deck.
The dependency-free XLSX reader exposes stored values and cached formula results; it does not execute Excel formulas or infer units.
No universal acceptance tolerance is imposed; the research protocol must justify observable-specific thresholds.
The accepted V4 speed gate covers one fixed-distance two-dimensional numerical mechanism; it is not a publication-curve validation.
Physical-keyed cohesive state, force, energy, sparse interface payloads, cross-rank-count restart, direct named-interface lowering, and linear triangular 3D surfaces are implemented; extreme-scale MPI profiling remains.
The plane-stress/thin-3D cross-check currently covers homogeneous affine deformation, not a full three-dimensional propagating crack.
The implemented publication registration is affine; nonlinear lens correction, segmentation, and coordinate uncertainty remain explicit research preprocessing.

Minimal example¶

manifest = datasets.science_supershear_dryad_manifest(); manifest.audit(data_dir).require(); sample = datasets.fem_observation_sample(SED, grid, coordinate_map=registration); field = datasets.RectilinearObservation.from_field_sample(sample); bundle = fracture.DynamicFractureEvidenceBundle(benchmark_id=case_id, trace=trace, wave_speeds=speeds, energy_history=energy)

Verification¶

Tests

tests/test_external_datasets.py
tests/test_fracture_v5.py
tests/test_dynamic_fracture_benchmarks.py

Benchmarks

agentfem.benchmark.jmps_weak_interface_transition_v4

Validation rules

Reject unrecognized manifests, missing files, wrong sizes, and wrong hashes.
Round-trip cohesive traces without pickle and reject inconsistent array shape or time order.
Recover exact linear curves, Mach angles, and bilinear scalar fields in comparison tests.
Retain a trace from a real finite-strain cohesive Explicit smoke case.
Exclude masked void fill values and reject unit or configuration mismatch.
Round-trip a sealed evidence directory and reject one corrupted artifact.

References¶

Tensile cracks can shatter classical speed limits: https://doi.org/10.1126/science.adg7693
Public data for Tensile cracks can shatter classical speed limits: https://doi.org/10.5061/dryad.7wm37pvz6
Transition from crack-type to supershear-type to spall-type mode of separation under tensile loading: https://doi.org/10.1016/j.jmps.2025.106213

Traceable integration-point field recovery¶

Stable ID: agentfem.workflow.integration_point_recovery
Kind: workflow
Status: supported
Source card: knowledge/cards/integration_point_recovery.json

Converts J2 and creep quadrature evidence to separately named weighted DG0 cell fields without nodal extrapolation, interelement smoothing, or material-boundary averaging.

Public API¶

agentfem.results.FieldRecovery
agentfem.results.cell_average_recovery
agentfem.results.recover_integration_point_field
agentfem.results.write_result_fields

Scientific contract¶

A scientific cell field is the quadrature-weighted mean of one constitutive integration-point field over each element; its processing history is part of the result meaning.

weighted cell recovery

\[ \bar{q}_e=\frac{\sum_p w_p q_{ep}}{\sum_p w_p} \]

Reference-cell quadrature weights form one DG0 value per cell; no neighbor contributes.

Inputs¶

Name	Type	Unit role	Meaning
quadrature field	QuadratureField	field dependent	Point coordinates, weights, constitutive values, value shape, and owning mesh.

Outputs¶

Name	Type	Unit role	Meaning
recovered field	FieldResult carrying a DG0 Function and processing metadata	same as source	A compact cell field suitable for quantitative queries and point/cell visualization.

Assumptions¶

The quadrature rule and stored values describe the same reference-cell point order.
DG0 is a cell-average representation and does not retain within-cell variation.

Conventions¶

Raw integration-point fields keep their original names; recovered variants use an explicit *_CELL suffix in J2 and creep SimulationResult objects.
J2 and creep solve_result(output=...) automatically omit raw quadrature attributes and write the recovered cell fields in the common completed-result dataset.
Material boundaries are preserved because recovery is performed independently within every cell.
A smooth contour is a later presentation product and never overwrites constitutive evidence.

Applicability¶

J2 plasticity and implicit creep field inspection, ParaView cell contours, histories, extrema, and learning-data preparation with explicit processing semantics.

Limitations¶

Direct general quadrature-file export is not yet implemented.
Material-domain nodal extrapolation and smoothing are not yet implemented.
For curved non-affine cells, a physical-Jacobian-weighted recovery will need a distinct reviewed policy.

Minimal example¶

result = step.solve_result(output='inelastic.xdmf')
cell_peeq = result.fields['PEEQ_CELL']

Verification¶

Tests

tests/test_constitutive_models.py
tests/test_p1_platform.py

Benchmarks

agentfem.benchmark.j2_global_restart
agentfem.benchmark.implicit_creep_relaxation
agentfem.benchmark.creep_abaqus_constant_stress

Validation rules

Reject sources without explicit quadrature points and weights.
Reject policies that silently request a non-DG0 or cross-material recovery.
Check weighted values independently and preserve processing metadata in SimulationResult.

References¶

Abaqus integration-point output and extrapolation semantics: https://docs.software.vt.edu/abaqusv2024/English/SIMACAEOUTRefMap/simaout-c-std-elementintegrationpointvariables.htm
Basix quadrature rules: https://docs.fenicsproject.org/basix/main/python/demo/demo_quadrature.py.html

Mesh-independent structured observation grids¶

Stable ID: agentfem.workflow.observation_grid_learning
Kind: workflow
Status: supported
Source card: knowledge/cards/observation_grid_learning.json

Samples serial or distributed FEM fields on stable Cartesian coordinates and exports explicit axes, array layout, units, components, and optional geometry masks for external neural-operator and digital-twin workflows.

Public API¶

agentfem.surrogates.ObservationGrid
agentfem.surrogates.AffineCoordinateMap
agentfem.surrogates.regular_grid
agentfem.datasets.fem_observation_sample
agentfem.datasets.RectilinearObservation
agentfem.surrogates.FieldEncoding
agentfem.surrogates.NeuralOperatorSpec

Scientific contract¶

A fixed physical observation operator separates the mesh used to solve each FEM case from the tensor coordinates consumed by a learned operator or compared with sensors.

observation operator

\[ \mathbf{y}_i=\mathcal{H}_i[\mathbf{u}_h]=\mathbf{u}_h(\mathbf{x}_i) \]

The same ordered physical coordinates are evaluated for every simulation and MPI partition.

coordinate registration

\[ \mathbf{x}_{model}=\mathbf{A}\mathbf{x}_{obs}+\mathbf{b} \]

A reviewed affine map records axis orientation, scale, and origin between observation and model coordinates.

operator-learning map

\[ \mathcal{G}_{\boldsymbol{\theta}}:\;a(\mathbf{x})\mapsto\mathbf{u}(\mathbf{x}) \]

Input and output fields require explicit discretization, coordinate, component, and boundary encodings.

Inputs¶

Name	Type	Unit role	Meaning
observation grid	one to three strictly increasing Cartesian axes	physical coordinate units	Defines shape, order, coordinate system, and stable point identities.
finite-element field	scalar, vector, or tensor DOLFINx Function	field dependent	May be distributed; ownership is resolved collectively.
optional affine coordinate map	invertible one-, two-, or three-dimensional matrix and offset	explicit source and target coordinate units	Maps publication, sensor, or laboratory coordinates to model sampling coordinates.

Outputs¶

Name	Type	Unit role	Meaning
FEMFieldSample	coordinates, structured values, scientific FieldEncoding, metadata, and optional mask	declared field and coordinate units	Portable NPZ or optional PyTorch tensors without prescribing a network architecture.
RectilinearObservation	two physical axes, image-layout scalar values, mask, units, and configuration	declared field and coordinate units	Provides an unambiguous publication/experiment comparison layout and dependency-free NPZ exchange.

Assumptions¶

Every case uses the same declared observation grid when samples are combined.
Coordinates and physical units are consistent across the campaign.
Outside-geometry values use an explicit mask rather than being mistaken for physical zeros.

Conventions¶

Stored values use grid axes followed by field-component axes.
C array order is the default and is recorded.
A true mask entry denotes a point inside the finite-element mesh.
FEMFieldSample stores observation coordinates and, when registered, the distinct model sampling coordinates.

Applicability¶

FNO-style structured-grid datasets, sensor-aligned digital-twin data, field comparison, and mesh-family campaigns.

Limitations¶

Graph and reduced-basis encodings are not yet executable.
No production neural-operator trainer is bundled.
Coordinate registration is currently affine; non-affine optical calibration needs an external reviewed transform.
Online sensor ingestion, assimilation, and uncertainty updating remain external future services.

Minimal example¶

grid = surrogates.regular_grid(bounds=((0,L),(0,H)), shape=(128,64)); registration = surrogates.AffineCoordinateMap(matrix=A, offset=b); sample = datasets.fem_observation_sample(U, grid, unit='m', outside='mask', coordinate_map=registration); image = datasets.RectilinearObservation.from_field_sample(sample)

Verification¶

Tests

tests/test_datasets.py
tests/test_parallel_results.py

Benchmarks

agentfem.benchmark.campaign_surrogate_pipeline

Validation rules

Reject non-monotone axes, inconsistent bounds/shapes, and unknown outside policies.
Compare analytical affine fields on serial and two-rank meshes.
Preserve the same value bytes on every MPI rank.
Round-trip mapped sampling coordinates and explicit rectilinear layout.

References¶

NeuralOperator 2.0 API reference: https://neuraloperator.github.io/dev/modules/api.html
Fourier Neural Operator for Parametric Partial Differential Equations: https://openreview.net/forum?id=c8P9NQVtmnO
NIST human-centered framework to update digital twins: https://tsapps.nist.gov/publication/get_pdf.cfm?pub_id=936651

MPI-safe point and path field sampling¶

Stable ID: agentfem.workflow.result_field_sampling
Kind: workflow
Status: supported
Source card: knowledge/cards/result_field_sampling.json

Evaluates finite-element fields at named physical points and paths with deterministic MPI ownership, including shared accepted-increment probe histories for heat, Standard dynamics, and Explicit dynamics.

Public API¶

agentfem.results.probe
agentfem.results.sample_points
agentfem.results.sample_path
agentfem.results.history
agentfem.results.probe_history
agentfem.results.PathSample.add_to

Scientific contract¶

A finite-element field is evaluated inside a containing owned cell from its basis representation; distributed ownership changes where evaluation occurs, not the returned physical value order.

finite-element point evaluation

\[ \mathbf{u}_h(\mathbf{x}_p)=\sum_a N_a(\mathbf{x}_p)\mathbf{u}_a \]

The containing cell supplies the local basis functions and coefficients for the requested physical point.

path coordinate

\[ s_i=\lVert\mathbf{x}_i-\mathbf{x}_0\rVert_2 \]

Straight-path samples use physical distance as the standard result-history abscissa.

Inputs¶

Name	Type	Unit role	Meaning
field	DOLFINx scalar, vector, or tensor Function	field dependent	The finite-element field whose coefficients and function space define the interpolation.
physical coordinates	point array or path endpoints	length	Coordinates in the mesh geometric dimension, supplied identically on every MPI rank.

Outputs¶

Name	Type	Unit role	Meaning
point values	ordered NumPy scalar/vector/tensor values	same as field	Values are returned in request order and replicated consistently on every rank.
path sample	PathSample coordinates, distance, and values	length and field units	Can be attached directly to SimulationResult as a named distance history.

Assumptions¶

Every MPI rank calls the sampler collectively with identical coordinates.
The requested point lies in the physical mesh unless missing='nan' is selected explicitly.
A one-sided discontinuous value is sampled inside the intended cell rather than exactly on its interface.

Conventions¶

The lowest-rank owned-cell candidate evaluates a point; ties on one rank use the lowest local cell index.
Missing points raise by default instead of silently returning zero.
Path distance is measured from the first endpoint in physical coordinates.
Accepted-frame history requests use physical time or normalized load factor; an unlabelled frame sequence must provide its coordinate explicitly.
Transient requests are evaluated only after accepted increments and are restored through the shared checkpoint history.
One online transient history channel is scalar; vector or tensor sensors use explicit components or separate named channels.

Applicability¶

Final-state quantities of interest, line plots, campaign outputs, sensor comparisons, compact digital-twin observations, and observation data for learned models.

Limitations¶

Straight paths are built in; arbitrary curves should supply explicit coordinates to sample_points.
Interface traces of discontinuous fields require an explicit one-sided sampling location.
Curved paths and one-sided discontinuous traces require explicit coordinates beyond the straight-path helper.
Online transient requests store compact scalar histories, not a replacement for spatial field-output frames.

Minimal example¶

sensor = results.probe_history('tip_U2', at=(L, H/2), component=1, unit='m'); result = step.solve_result(output='results.xdmf', history=(sensor,))

Verification¶

Tests

tests/test_results.py
tests/test_parallel_results.py
tests/test_transient_restart.py
tests/test_parallel_transient.py

Benchmarks

None declared.

Validation rules

Reject negative geometric padding, unknown missing-point policies, and coordinates with the wrong geometric dimension.
Reject rank-inconsistent coordinate requests before field evaluation.
Reject missing points before returning a scientific quantity unless missing='nan' is explicit.
Reject duplicate or conflicting transient history names and non-scalar online channels.
Reject continuation when the accepted-history channel schema differs from the checkpoint evidence.

References¶

DOLFINx geometry and finite-element function evaluation: https://docs.fenicsproject.org/dolfinx/main/python/generated/dolfinx.geometry.html

Scientific trust and verification workflow¶

Stable ID: agentfem.workflow.scientific_verification
Kind: workflow
Status: supported
Source card: knowledge/cards/scientific_verification.json

Separates computed, converged, verified, and validated results while providing exploratory, engineering, and release policies for automatic runtime checks and campaign learning gates.

Public API¶

agentfem.verification.VerificationClaim
agentfem.verification.VerificationReport
agentfem.verification.QualityPolicy
agentfem.verification.assess
agentfem.verification.ConvergenceStudy
agentfem.results.SimulationResult.verify
agentfem.results.SimulationResult.add_verification
agentfem.campaigns.CampaignReport.require_dataset

Scientific contract¶

A numerical result is accepted only through declared evidence; solver completion, discretization adequacy, reference applicability, implementation verification, and physical validation are separate claims.

reference contract

\[ |q_h-q_{\mathrm{ref}}|\le \mathrm{atol}+\mathrm{rtol}\,|q_{\mathrm{ref}}| \]

The reference, tolerance, and validity domain are stored with the decision.

successive refinement

\[ \eta_h=\frac{\lVert q_h-q_{h/2}\rVert}{\max(\lVert q_{h/2}\rVert,\varepsilon_{\mathrm{tiny}})} \]

A first convergence diagnostic; it is not silently presented as a full uncertainty estimate.

Inputs¶

Name	Type	Unit role	Meaning
observable and reference	scalar or fixed-shape numerical values	must be consistent	The actual value, expected value, and source of the expectation.
evidence policy	tolerances, validity domain, refinement sequence, claim kind	declared by each claim	Defines acceptance before a result is promoted.

Outputs¶

Name	Type	Unit role	Meaning
VerificationReport	JSON-safe claim collection and trust level	retains observable metadata	Passed, failed, and inconclusive claims plus the derived trust state.

Assumptions¶

Reference values and tolerances are selected independently of the result under test.
Convergence samples represent the same modeled quantity and are ordered coarse to fine.

Conventions¶

An inapplicable theory is inconclusive, not failed or passed.
A Golden value is a regression contract unless separate convergence evidence is supplied.
Validation claims require physical or experimental evidence and are labeled explicitly.

Applicability¶

Release regression, analytical checks, metamorphic tests, mesh/time convergence, cross-solver comparisons, and simulation-to-learning admission.

Limitations¶

The initial ConvergenceStudy does not yet calculate generalized GCI for arbitrary refinement ratios.
Trust evidence can be wrong if a user supplies an inappropriate reference; deterministic structure does not replace expert review.

Minimal example¶

result.verify('engineering', required_quantities=('response',)).require(); dataset = report.require_dataset(quality='engineering').

Verification¶

Tests

tests/test_verification.py
tests/test_results.py
tests/test_campaigns.py
tests/test_release_goldens.py

Benchmarks

agentfem.benchmark.cae_reliability_cliffs
agentfem.benchmark.creep_hot_wall_release

Validation rules

Reject unknown trust levels and negative tolerances.
Reject unordered or shape-incompatible convergence samples.
Runtime claims cannot promote a result to verified.
Do not admit samples that lack an accepted requested quality policy.

References¶

AgentFEM scientific trust guide: docs/scientific_verification.md

Collective simplex mesh-quality preflight¶

Stable ID: agentfem.workflow.simplex_mesh_quality
Kind: workflow
Status: supported
Source card: knowledge/cards/simplex_mesh_quality.json

Computes normalized triangle/tetrahedron mean-ratio quality and turns a declared threshold into MPI-global preflight evidence.

Public API¶

agentfem.mesh.cell_quality
agentfem.mesh.audit_quality

Scientific contract¶

Simplex mean ratio compares physical area or volume with squared edge lengths and equals one for an equilateral element and zero for a degenerate element.

triangle mean ratio

\[ q=\frac{4\sqrt{3}\,A}{\sum_e l_e^2} \]

The metric is dimensionless and normalized to one.

tetrahedron mean ratio

\[ q=\frac{12(3V)^{2/3}}{\sum_e l_e^2} \]

Six edge lengths and absolute tetrahedron volume define the metric.

Inputs¶

Name	Type	Unit role	Meaning
simplex mesh and threshold	DOLFINx triangle/tetrahedron domain and q_min in [0,1]	dimensionless quality; coordinates share any consistent length unit	Only owned cells contribute to collective counts and statistics.

Outputs¶

Name	Type	Unit role	Meaning
MeshQualityReport	global min/mean/max, poor/invalid counts, and acceptance	dimensionless	Strict mode rejects the mesh when the declared acceptance rule fails.

Assumptions¶

The selected topology is a triangle or tetrahedron solver domain.

Conventions¶

Cells below threshold are poor; zero or non-finite cells are invalid.

Applicability¶

Generated or imported simplex meshes, including C3D10 geometric topology preflight.

Limitations¶

Mean ratio does not replace curved high-order Jacobian sampling or analysis-specific distortion checks.
Quadrilateral/hexahedron quality requires a different Jacobian-based contract and is rejected for now.

Minimal example¶

quality = mesh.audit_quality(domain, threshold=0.1, strict=True)

Verification¶

Tests

tests/test_mesh_quality.py

Benchmarks

None declared.

Validation rules

Recover sqrt(3)/2 for a right isosceles triangle.
Return values within [0,1].
Reduce counts and statistics collectively over owned MPI cells.
Reject unsupported cell types instead of reusing the simplex metric.

References¶

Algebraic mesh quality metrics for unstructured initial meshes: https://doi.org/10.1002/nme.1429

Solution procedure vocabulary¶

Stable ID: agentfem.workflow.solution_procedures
Kind: analysis_step
Status: supported
Source card: knowledge/cards/solution_procedures.json

Separates physical analysis intent from Standard/Explicit selection, equation order, integration algorithm, state policy, and global-solve requirements.

Public API¶

agentfem.procedures.SolutionProcedure
agentfem.procedures.resolve
agentfem.time.newmark
agentfem.time.generalized_alpha
agentfem.problems.LinearSystemProblem.reaction_field
agentfem.diagnostics.SolveEventRecorder
agentfem.diagnostics.mechanical_energy
agentfem.checkpointing.every
agentfem.models.Model.step

Scientific contract¶

A Study identifies the governing problem while a SolutionProcedure identifies how load or time is advanced and which global/local algorithm consumes it.

second-order system

\[ \mathbf{M}\ddot{\mathbf{u}}+\mathbf{C}\dot{\mathbf{u}}+\mathbf{K}\mathbf{u}=\mathbf{F} \]

The same physical system may be solved by implicit Newmark, generalized-alpha, or explicit central difference.

generalized-alpha equilibrium

\[ \mathbf{M}\mathbf{a}_{n+1-\alpha_m}+\mathbf{C}\mathbf{v}_{n+1-\alpha_f}+\mathbf{K}\mathbf{u}_{n+1-\alpha_f}=\mathbf{F}_{n+1-\alpha_f} \]

Algorithmic parameters control stability, accuracy, and high-frequency dissipation.

Inputs¶

Name	Type	Unit role	Meaning
Study	analysis and physics context	none	Defines static/transient order, physics, dimension, and assumptions.
operators and controls	M, C, K, F, dt, increments, solver policy	consistent finite-element system	Visible numerical ingredients consumed by the selected procedure.

Outputs¶

Name	Type	Unit role	Meaning
step summary	structured procedure record	none	Records family, order, algorithm, control, statefulness, and solve requirements.
typed provider request	immutable StepRequest	none	Carries the resolved procedure through capability inspection and executable lowering.
advanced state	field state and convergence evidence	problem dependent	Accepted displacement, velocity, acceleration, temperature, or material state.
reaction and mechanical energy diagnostics	nodal residual field and scalar energy record	force and energy	Strong-constraint reactions and visible M/K quadratic energies for supported systems.
execution trace	ordered JSON-safe SolveEvent records	problem dependent	One source for progress, status files, result histories, failures, and agent monitoring.
scheduled restart state	integrity-checked checkpoint manifest and rank shards	time	Written after accepted increments at one shared cadence across explicit, implicit-dynamics, and heat routes, with optional partition-independent nodal state.

Assumptions¶

Newmark and generalized-alpha are currently linear structural dynamics routes.
Implicit heat transfer currently uses backward Euler.
Central difference uses a lumped mass operator.

Conventions¶

Standard means a global implicit/assembled solution route, not an Abaqus compatibility claim.
Explicit means no global linear solve at each time increment.
Step, increment, iteration, attempt, and output frame remain distinct.
An explicit procedure object takes precedence over the Study preference and cannot conflict with method= or equation order.
Display cadence never removes an accepted or failed event from the execution trace.
Automatic checkpoints are written only after state, history, and the accepted-increment event are committed.

Applicability¶

Selecting and inspecting current linear static, nonlinear static, heat-transfer, and structural-dynamics routes.

Limitations¶

Nonlinear implicit structural dynamics is not implemented.
Moving-support kinematics for implicit dynamics are not implemented.
Checkpoint retention is implemented for shared transient routes; portable cross-partition restart currently covers nodal state but not quadrature/internal-variable state.

Minimal example¶

study = studies.dynamic_solid(dimension=2, assumption='plane_stress', method='newmark')
step = model.step(target=u, procedure=procedures.generalized_alpha(), dt=..., steps=...)

Verification¶

Tests

tests/test_p1_platform.py
tests/test_transient_restart.py
tests/test_parallel_transient.py

Benchmarks

None declared.

Validation rules

Reject unknown procedure families, method names, equation orders, controls, or incompatible explicit/global-solve combinations.
Require capability inspection and provider lowering to consume the same resolved SolutionProcedure.
Reject invalid generalized-alpha spectral radius and integration parameters.

References¶

Chung and Hulbert generalized-alpha method: https://deepblue.lib.umich.edu/bitstream/handle/2027.42/50422/1640100803_ftp.pdf?isAllowed=y&sequence=1

Projected small-strain fields, reactions, and static equilibrium¶

Stable ID: agentfem.workflow.standard_result_projection
Kind: workflow
Status: supported
Source card: knowledge/cards/standard_result_projection.json

Produces engineering-default S, E, and MISES plus opt-in SENER as traceable cell-average fields, extracts MPI-global resultants, and records assembled external-force versus strong-reaction equilibrium.

Public API¶

agentfem.results.project
agentfem.results.project_piecewise
agentfem.results.small_strain_cell_fields
agentfem.results.small_strain_partition_fields
agentfem.results.field_extrema
agentfem.results.region_measure
agentfem.results.reaction_resultant
agentfem.results.external_force_resultant
agentfem.results.static_force_balance
agentfem.results.static_work_balance
agentfem.mesh.tagged_boundary_region
agentfem.diagnostics.linear_static_energy

Scientific contract¶

A projected result field is defined by an L2 variational problem, while a strong-constraint reaction is the unconstrained assembled residual retained on prescribed degrees of freedom.

L2 projection

\[ \int_{\Omega}q_h:v_h\,dx=\int_{\Omega}q:v_h\,dx\qquad\forall v_h \]

DG0 projection returns the cell average of a scalar, vector, or tensor expression.

strong-constraint reaction

\[ \mathbf{R}=\mathbf{K}\mathbf{u}-\mathbf{F} \]

At converged free degrees of freedom R is zero to solver tolerance; prescribed degrees retain reaction entries.

global static force balance

\[ \mathbf{r}_{\mathrm{balance}}=\sum\mathbf{R}_{\mathrm{strong}}+\sum\mathbf{F}_{\mathrm{assembled}} \]

The relative error is the residual norm divided by the larger external or reaction resultant norm.

proportional linear work

\[ W_{\mathrm{ext}}=\tfrac{1}{2}\mathbf{u}^{T}\mathbf{F}+\tfrac{1}{2}\mathbf{R}_{c}^{T}\bar{\mathbf{u}},\qquad U=\tfrac{1}{2}\mathbf{u}^{T}\mathbf{K}\mathbf{u} \]

Natural loads and strong prescribed values are ramped proportionally from zero; the constrained residual supplies the conjugate prescribed-motion work.

Inputs¶

Name	Type	Unit role	Meaning
displacement and material	finite-element displacement field, elastic properties, and Study	consistent mechanics system	Defines infinitesimal strain, Cauchy stress, equivalent stress, and strain-energy density.
converged problem	linear or nonlinear problem exposing reaction_field	force or conjugate residual	Supplies the assembled residual for the strong-constraint resultant.

Outputs¶

Name	Type	Unit role	Meaning
standard fields	DG projected Functions named S, E, MISES, and optionally SENER	stress, strain, and energy density	Serial solve_result(output=...) stores these cell fields with nodal U on one Uniform Grid.
resultants, force balance, and energy closure	MPI-global scalar/vector, StaticForceBalance, and LinearStaticEnergy	force and energy	Compact engineering histories or verification quantities.

Assumptions¶

Small-strain standard fields use the selected linear-elastic constitutive relation.
Plane-strain isotropic Mises stress includes the constitutively implied out-of-plane stress.
Reaction resultant semantics are limited to strong Dirichlet constraints.

Conventions¶

DG0 is the default output space and represents a cell average.
DG0 result fields are discontinuous and are not extrapolated or averaged across neighboring cells or material boundaries.
The engineering default is U/S/E/MISES; SENER is an explicit diagnostic request.
E means infinitesimal strain in a small-strain context.
Non-zero strong prescribed-displacement work is recorded separately from natural-load work and included in total external work.
Imported physical boundaries use their facet tag for both strong topological dof location and weak integration; an optional marker is audit evidence.
field_extrema(location=True) identifies its finite-element-dof sampling, coordinate, rank, global dof, and DG0 cell where applicable.
Model-generated linear static solids attach assembled external force, strong reaction, balance residual, and relative error to SimulationResult.

Applicability¶

Linear small-strain solid mechanics, field visualization, reaction checks, and proportional load energy verification.

Limitations¶

Nodal smoothing and superconvergent stress recovery are not implemented.
Affine MPC, weak, and contact reactions need dedicated dual definitions; the strong-Dirichlet work formula is rejected for those assets.
Thermoelastic output requires temperature-aware field construction in a later extension.

Minimal example¶

support = mesh.tagged_boundary_region(domain, facet_tags, tag=101, name='support')
result = step.solve_result(output='solid.xdmf')
RF_x = results.reaction_resultant(step.problem, on=support, component=0)
balance = results.static_force_balance(step.problem)
peak = results.field_extrema(result.fields['MISES'], location=True)

Verification¶

Tests

tests/test_results.py
tests/test_p1_platform.py

Benchmarks

agentfem.benchmark.linear_static_cantilever
agentfem.benchmark.elasticity_foundation

Validation rules

Reject unknown field variables and negative projection degrees.
Compare affine displacement projection with its analytical constant strain.
Check named-boundary reaction equilibrium and proportional static energy closure.
Check the automatically attached assembled-force, strong-reaction, and relative global balance evidence.
Verify a regional two-material series bar through one piecewise projection.

References¶

DOLFINx finite-element functions and variational assembly: https://docs.fenicsproject.org/dolfinx/main/python/generated/dolfinx.fem.html
Abaqus field and history output requests: https://docs.software.vt.edu/abaqusv2024/English/SIMACAEOUTRefMap/simaout-c-output.htm
Abaqus contour extrapolation and averaging: https://docs.software.vt.edu/abaqusv2024/English/SIMACAECAERefMap/simacae-c-conconceptlimits.htm
COMSOL Gauss-point evaluation: https://doc.comsol.com/6.4/doc/com.comsol.help.sme/sme_ug_modeling.05.224.html

Sequential thermoelastic analysis¶

Stable ID: agentfem.workflow.thermoelastic_analysis
Kind: workflow
Status: supported
Source card: knowledge/cards/thermoelastic_analysis.json

One isotropic material record supplies heat capacity, conductivity, elasticity, reference temperature, and thermal expansion to an implicit heat step followed by a thermal-stress solve.

Public API¶

agentfem.constitutive.thermoelastic
agentfem.operators.thermal_expansion_vector
agentfem.constitutive.ArrheniusPowerLawCreep
agentfem.models.Model.step

Scientific contract¶

Temperature is solved first when mechanical response does not materially feed back into heat transfer, then thermal eigenstrain enters equilibrium as an equivalent load.

heat equation

\[ \rho c_p\dot{T}-\nabla\!\cdot(k\nabla T)=Q \]

Backward Euler advances the first-order thermal state.

thermal strain

\[ \boldsymbol{\varepsilon}_{\mathrm{th}}=\alpha(T-T_{\mathrm{ref}})\mathbf{I} \]

The reference temperature and dimensional reduction are explicit material/Study inputs.

sequential stress equilibrium

\[ \mathbf{K}\mathbf{u}=\mathbf{F}_{\mathrm{ext}}+\int_{\Omega}(\mathbb{C}:\boldsymbol{\varepsilon}_{\mathrm{th}}):\boldsymbol{\varepsilon}(\mathbf{v})\,d\Omega \]

The thermal contribution remains a named inspectable vector operator.

normalized Arrhenius factor

\[ A(T)=A_{\mathrm{ref}}\exp\!\left[-\frac{Q}{R}\left(\frac{1}{T}-\frac{1}{T_{\mathrm{ref}}}\right)\right] \]

The local creep coefficient retains its fitted meaning at the declared reference temperature.

Inputs¶

Name	Type	Unit role	Meaning
thermomechanical properties	E, nu, rho, alpha, k, c_p, T_ref	consistent absolute-temperature system	One immutable material record shared by thermal and mechanical models.
temperature field	scalar finite-element field	absolute temperature	Solved or prescribed temperature consumed by thermal expansion.

Outputs¶

Name	Type	Unit role	Meaning
Temperature	transient scalar field	absolute temperature	Implicit-Euler heat-transfer result.
F_thermal	finite-element vector operator	force	Equivalent load from constrained thermal expansion.
Displacement	vector finite-element field	length	Sequential mechanical response.

Assumptions¶

Small-strain isotropic thermoelasticity.
Sequential coupling: temperature affects mechanics but mechanical dissipation and deformation do not feed back into heat transfer.
Material constants are temperature independent in the current global operators.

Conventions¶

All Arrhenius temperatures are kelvin.
Plane strain retains the constrained out-of-plane thermal strain.
Plane stress uses the reduced in-plane constitutive law.

Applicability¶

Thermal gradients and thermal stress in laboratory and power-plant component models when one-way coupling is adequate.
Preparing temperature fields for global Arrhenius creep integration.

Limitations¶

No monolithic fully coupled temperature-displacement solve.
No convection/radiation convenience boundary in this card.
Global Arrhenius creep accepts a prescribed scalar or finite-element temperature; automatic transient-history transfer is not yet provided.

Minimal example¶

Solve a heat-transfer Model with the shared material, then pass its Temperature field to mechanics.thermal_expansion(u, temperature) in a solid-mechanics Model.

Verification¶

Tests

tests/test_p1_platform.py

Benchmarks

agentfem.benchmark.thermoelastic_free_expansion

Validation rules

Reject nonpositive conductivity, specific heat, density, or absolute reference temperature.
Require an explicit 2D solid assumption for thermoelastic stress.

References¶

Abaqus fully coupled thermal-stress analysis: https://docs.software.vt.edu/abaqusv2024/English/SIMACAEANLRefMap/simaanl-c-couptempdisp.htm
Abaqus heat transfer procedures: https://docs.software.vt.edu/abaqusv2024/English/SIMACAEANLRefMap/simaanl-c-heatproc.htm

Portable transient checkpoint state¶

Stable ID: agentfem.workflow.transient_checkpoint_portability
Kind: workflow
Status: supported
Source card: knowledge/cards/transient_checkpoint_portability.json

Adds an opt-in physical-node-keyed state beside fast MPI rank shards so a supported transient analysis can restart with a different MPI partition or rank count, including split interfaces with coincident independent nodes.

Public API¶

agentfem.checkpointing.every
agentfem.checkpointing.save_transient_checkpoint
agentfem.checkpointing.load_transient_checkpoint
agentfem.checkpointing.mesh_portable_identity
agentfem.checkpointing.function_portable_identity

Scientific contract¶

A restart state must identify physical degrees of freedom independently of rank-local numbering before it can be called portable across MPI partitions.

portable degree-of-freedom key

\[ k_i=\left(\operatorname{quantize}(\mathbf{x}_i;\,\mathbf{b},\tau),\,c_i[,\,n_i]\right) \]

Physical coordinates and block component define the usual deterministic key. When independent nodes share a coordinate, the durable source input-node identity n_i disambiguates them; quantization absorbs mesh-construction roundoff without changing the field value.

Inputs¶

Name	Type	Unit role	Meaning
accepted transient state	named finite-element Functions plus time, history, and solver metadata	problem dependent	Only committed increments are eligible for checkpointing.

Outputs¶

Name	Type	Unit role	Meaning
portable checkpoint	manifest, fast rank shards, and optional coordinate-keyed NPZ state	problem dependent	The same-partition path remains fast; a different partition consumes the verified portable state.

Assumptions¶

The restart mesh represents the same physical nodal discretization within the recorded coordinate tolerance.
Every participating rank calls checkpoint save and load collectively in the same field order.

Conventions¶

Portable state is opt-in through checkpointing.every(..., portable=True) or save_checkpoint(..., portable=True).
File size and SHA-256 are checked before state restoration.
The manifest records both rank-local and partition-independent identities.
Coincident split-interface nodes are keyed by durable source input-node identity rather than being merged by coordinate.

Applicability¶

Explicit structural dynamics, implicit structural dynamics, and first-order transient heat state composed of nodal finite-element Functions.

Limitations¶

The present root-gathered NPZ representation is intended for laboratory-scale restart evidence, not extreme-scale parallel checkpoint bandwidth.
Quadrature and constitutive internal-variable portability requires a cell/integration-point identity contract and is not implied by nodal portability.
Changes to mesh geometry, function-space family, degree, value shape, or field schema remain incompatible.

Minimal example¶

policy = checkpointing.every(10, directory='checkpoints', portable=True)

Verification¶

Tests

tests/test_transient_restart.py
tests/test_parallel_transient.py
tests/portable_checkpoint_driver.py
tests/portable_cohesive_dynamics_driver.py

Benchmarks

None declared.

Validation rules

Reject a changed field schema or physical mesh identity.
Reject missing, truncated, or checksum-mismatched state files.
Verify a two-rank write followed by a one-rank continuation against an uninterrupted one-rank solution.
Verify the same two-rank-to-one-rank continuation for a split-interface Explicit step with coincident independent nodes and physical-facet cohesive history.

References¶

DOLFINx parallel checkpointing demo: https://docs.fenicsproject.org/dolfinx/main/python/demos/demo_checkpointing.html

Full-vector and mixed-mode cohesive interfaces¶

Stable ID: agentfem.workflow.vector_cohesive_interface
Kind: workflow
Status: experimental
Source card: knowledge/cards/vector_cohesive_interface.json

Adds explicit vector jump and traction kinematics, intact and damage-compatible tangential transfer, mixed-mode bilinear damage, compression contact, standard fields, rigid-mode and Mode-I audits, serial/MPI restart, and spherical arc-length continuation to one reusable fixed-path interface contract.

Public API¶

agentfem.interfaces.mixed_mode_bilinear_cohesive
agentfem.interfaces.audit_split_interface_rigid_modes
agentfem.interfaces.audit_mode_i_kinematics
agentfem.fracture.cohesive_force
agentfem.fracture.cohesive_forces
agentfem.fracture.mode_i_cohesive_force
agentfem.fracture.FiniteStrainCohesiveArcLength

Scientific contract¶

A split cohesive interface must constrain and damage the complete displacement jump declared by its physical law; normal-only traction is a special slip model rather than the default meaning of a three-dimensional cohesive surface.

interface kinematics

\[ \delta_n=\llbracket u\rrbracket\cdot n,\quad \boldsymbol\delta_t=\llbracket u\rrbracket-\delta_n n \]

The same decomposition drives line and triangular-surface facets.

quadratic damage initiation

\[ (\langle t_n\rangle/T_n)^2+(\|t_t\|/T_t)^2=1 \]

Compression does not initiate cohesive damage.

BK mixed fracture energy

\[ G_c=G_{Ic}+(G_{IIc}-G_{Ic})(G_s/(G_n+G_s))^\eta \]

Power-law energy interaction is an alternative explicit option.

spherical continuation

\[ \|\Delta u\|^2+(\alpha\Delta\lambda)^2=\Delta s^2 \]

Post-peak path following adds one load unknown to the existing cohesive residual.

Inputs¶

Name	Type	Unit role	Meaning
split interface	SplitInterfaceMesh or NamedSplitInterfaceMesh	reference geometry	Coincident sides with independent displacement identities.
cohesive law	BilinearCohesiveLaw or MixedModeBilinearCohesiveLaw	consistent force-length system	Strength, stiffness, fracture energies and optional contact/friction parameters.
kinematic mode	free, tie, degraded or mixed	dimensionless choice	Declares the physical tangential behavior rather than hiding it in a case script.

Outputs¶

Name	Type	Unit role	Meaning
standard interface fields	quadrature arrays	jump length, traction, damage	JUMP_N/JUMP_T/TRACTION_N/TRACTION_T/DAMAGE/MODE_MIXITY.
well-posedness evidence	InterfaceRigidModeAudit and ModeIKinematicsAudit	rank and dimensionless ratio	Pre-solve body-mode rank and accepted-state tangential deviation.
continuation evidence	ArcLengthSolveInfo	declared load and displacement scales	Residual, arc constraint, iterations and accepted load increment.

Assumptions¶

The crack path is fixed and represented by paired two-node lines or three-node triangular surfaces.
The first mixed-mode damage law is intended for proportional or mildly changing mode mix.
Regularized friction acts only in compression and is not a replacement for a general contact solver.

Conventions¶

Positive normal traction and jump denote opening.
The local interface frame is deterministic and right-handed; normal is component zero.
Strict tie does not degrade and must be selected deliberately.
The recommended scalar Mode-I factory uses a strict tangential penalty tie because the scalar law declares no Mode-II failure data.
State and output identity follow physical facet keys and quadrature, not MPI-local dofs.

Applicability¶

Fixed-path monotonic and dynamic cohesive problems requiring explicit shear integrity, mixed-mode separation, model-rank screening, or post-peak continuation.

Limitations¶

No free-path fracture or cohesive-junction topology; the separate experimental cyclic consumer accepts proportional extrema or an explicitly supplied ordered closed non-proportional path.
Normal-damage-driven tangential integrity does not yet add an independent cyclic shear-dissipation state; substantial shear requires the mixed-mode law.
No external mixed-mode structural benchmark has promoted the experimental law.
Arc length currently targets quasi-static native cohesive equilibrium, not Explicit dynamics.

Minimal example¶

law = interfaces.mixed_mode_bilinear_cohesive(normal_strength=Tn, shear_strength=Ts, normal_fracture_energy=GIc, shear_fracture_energy=GIIc, normal_stiffness=Kn, tangential_stiffness=Kt, interaction='bk'); cohesive = fracture.cohesive_force(split, U, law, normal_hint=(0, 0, 1))

Verification¶

Tests

tests/test_interfaces.py
tests/test_global_cohesive_residual.py
tests/test_parallel_cohesive.py

Benchmarks

agentfem.benchmark.vector_cohesive_interface

Validation rules

Pure-mode envelope areas equal declared fracture energies.
Analytical point and facet tangents match centered force derivatives.
A free middle body is detected before solving and a shear-carrying intact interface closes the rank.
Mixed-mode vector resultants and state fields pass serial and two-rank consumers.
A native finite-strain cohesive arc-length increment satisfies equilibrium and the spherical constraint.

References¶

Abaqus cohesive behavior: https://docs.software.vt.edu/abaqusv2025/English/SIMACAEITNRefMap/simaitn-c-cohesivebehavior.htm
Abaqus damage evolution and mixed-mode criteria: https://docs.software.vt.edu/abaqusv2024/English/SIMACAECAERefMap/simacae-t-prpmechanicaldamageevolution.htm
PETSc rigid-body null space: https://petsc.org/release/manualpages/Mat/MatNullSpaceCreateRigidBody/
AgentFEM dynamic cohesive fracture architecture: docs/dynamic_cohesive_fracture_architecture.md