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 agentfem/knowledge/catalog.json.

Function index¶

Stable ID	Title	Kind	Status
`agentfem.constraint.exact_rectangular_mpc`	Exact rectangular periodic multi-point constraint	constraint	supported
`agentfem.formulation.axisymmetric_solid`	Axisymmetric solid formulation	workflow	supported
`agentfem.load.surface_resultant`	Uniform boundary traction from a requested resultant force	workflow	supported
`agentfem.material.chaboche_global_plasticity`	Global Chaboche combined-hardening plasticity	material	experimental
`agentfem.material.composite_ply_failure`	Material-axis composite ply failure assessment	material	experimental
`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.fabric_surface_constitutive`	Non-orthogonal woven-fabric surface response	material	experimental
`agentfem.material.finite_strain_j2_logarithmic`	Finite-strain logarithmic J2 plasticity	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.linear_viscoelastic_dynamics`	Generalized-Maxwell linear viscoelastic material	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.material.solver_neutral_user_material_contract`	Solver-neutral finite-strain user-material contract	material	contract_only
`agentfem.operator.biharmonic_split`	Biharmonic split operators and boundary closure	operator	supported
`agentfem.operator.elastic_foundation_reaction`	Linear elastic foundation reaction and energy ownership	operator	supported
`agentfem.operator.fibrous_shell_curvature_reconstruction`	Neighbor-reconstructed fibre curvature	operator	experimental
`agentfem.operator.incompressible_flow`	Mixed incompressible-flow fields and operators	operator	supported
`agentfem.operator.scalar_transport_reaction`	Scalar transport and reaction operators	operator	supported
`agentfem.operator.system_contracts`	Finite-element operator and system contracts	operator	supported
`agentfem.verification.discrete_inf_sup_evidence`	Norm-aware discrete inf-sup evidence	operator	experimental
`agentfem.workflow.abaqus_engineering_regions`	Abaqus node, element, and element-face sets as FEM regions	workflow	supported
`agentfem.workflow.abaqus_reviewed_migration`	Reviewed Abaqus model and user-material migration	workflow	experimental
`agentfem.workflow.campaign_learning_pipeline`	Simulation campaign to guarded learning workflow	workflow	supported
`agentfem.workflow.cell_neighborhood_topology`	Partition-aware cell neighborhood topology	workflow	experimental
`agentfem.workflow.cohesive_state_portability`	Physical-keyed cohesive state across MPI partitions	workflow	experimental
`agentfem.workflow.composite_orientation_and_laminate`	Composite material frames and laminate sections	workflow	experimental
`agentfem.workflow.coordinate_reference_coupling`	Local coordinates and reference-point continuum coupling	workflow	supported
`agentfem.workflow.creep_fatigue_assessment`	Engineering creep-fatigue assessment	workflow	supported
`agentfem.workflow.cyclic_work_energy_ledger`	Transactional generalized work and cycle-block energy ledger	workflow	experimental
`agentfem.workflow.discretization_preflight`	Mesh, element, and Study discretization preflight	workflow	supported
`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.lefm_interaction_integral`	Solver-neutral LEFM stress-intensity extraction	workflow	experimental
`agentfem.workflow.observation_grid_learning`	Mesh-independent structured observation grids	workflow	supported
`agentfem.workflow.periodic_cell_homogenization`	Finite-strain periodic-cell homogenization evidence	workflow	experimental
`agentfem.workflow.physical_field_statistics`	Physical-measure statistics for quadrature fields	workflow	supported
`agentfem.workflow.result_field_sampling`	MPI-safe point and path field sampling	workflow	supported
`agentfem.workflow.scalable_campaign_evidence`	Spawned campaign ensembles and convergence certificates	workflow	supported
`agentfem.workflow.scientific_response_experiments`	Campaign-backed scientific response experiments	workflow	supported
`agentfem.workflow.scientific_verification`	Scientific trust and verification workflow	workflow	supported
`agentfem.workflow.simplex_mesh_quality`	Collective 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.abaqus_viscoelastic_rod`	Viscoelastic rod under suddenly applied constant axial traction	Three-dimensional small-strain isotropic linear viscoelastic creep under prescribed traction	automated_external_structural_verification
`agentfem.benchmark.arrhenius_global_creep`	Transient heat to global Arrhenius creep contract	three-dimensional small-strain Mises power-law creep with prescribed or time-varying Arrhenius temperature fields	automated_regression
`agentfem.benchmark.axisymmetric_lame_cylinder`	Axisymmetric Lamé thick-cylinder elasticity	small-strain isotropic axisymmetric elasticity for a long pressurized thick cylinder	release_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.chaboche_combined_hardening`	Abaqus OFHC copper and 316-steel cyclic material paths	three-dimensional and axisymmetric small-strain J2 plasticity with isotropic and Armstrong--Frederick kinematic hardening under strain, stress, or mixed control	automated_external_material_point_comparison
`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_fatigue_assessment`	Source-identified engineering creep-fatigue assessment	Postprocessed creep time-fraction and stress-life fatigue damage	automated_postprocessor
`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.creep_nafems_r0027_test7`	NAFEMS R0027 Test 7 pressurized-cylinder secondary creep	Plane-strain thick cylinder under constant internal pressure with Mises secondary power-law creep	automated_external_structural_verification
`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	assembled_dcb_enf_mmb_mechanism_regressions_passed
`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.fibrous_shell_foundation`	Multilayer membrane and hybrid fibrous-shell foundation	finite-kinematics woven-reinforcement membrane and local fibre-specific shell response	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.finite_strain_j2_lewandowski_2023_beam`	Lewandowski et al. finite-strain J2 self-weight beam	Three-dimensional slender beam under a ramped gravity-like body force, with a left clamp, right-end axial symmetry constraint, finite rotations, isotropic J2 plasticity and linear isotropic hardening.	external_reference_reexecuted_candidate_promotion_incomplete
`agentfem.benchmark.finite_strain_j2_material_paths`	Finite-strain logarithmic J2 material and global paths	three-dimensional rate-independent finite-strain J2 plasticity with quadratic Hencky elasticity and linear isotropic hardening	experimental_automated_global_mpi_restart
`agentfem.benchmark.finite_strain_j2_periodic_multi_void`	Finite-strain J2 periodic cell with a deterministic multi-void realization	Three-dimensional finite-strain logarithmic J2 plasticity in a unit periodic cube containing four non-overlapping geometric spherical voids under isochoric macroscopic tension.	automated_fixed_stack_regression_with_refinement_path_mpi_restart
`agentfem.benchmark.finite_strain_j2_periodic_void`	Finite-strain J2 periodic cell with a true spherical void	Three-dimensional finite-strain logarithmic J2 plasticity in a unit periodic cube containing a geometric spherical void under isochoric macroscopic tension.	automated_fixed_stack_regression_experimental_science
`agentfem.benchmark.finite_strain_j2_zhang_2021_table5`	Zhang--Feng--Khandelwal finite-strain periodic composite, Table 5	Plane-strain periodic composite with two stiff circular inclusions, one circular void, logarithmic finite-strain J2 matrix plasticity, elastic inclusions, and macroscopic simple shear.	experimental_external_fixture_not_promoted
`agentfem.benchmark.global_viscoelastic_harmonic_bar`	Three-dimensional generalized-Maxwell harmonic bar	Three-dimensional small-strain isotropic linear viscoelasticity	automated_analytical_verification
`agentfem.benchmark.global_viscoelastic_relaxation`	Three-dimensional generalized-Maxwell relaxation patch	Three-dimensional small-strain isotropic linear viscoelasticity	automated_analytical_verification
`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	native axisymmetric and three-dimensional plane-strain thick cylinders 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.lefm_center_crack_mode_i`	Mode-I center-crack LEFM extraction	two-dimensional plane-stress isotropic linear elasticity with a traction-free straight center crack under remote tension	experimental_automated_foundation
`agentfem.benchmark.linear_cantilever_modal`	Clamped rectangular cantilever first bending mode	Two-dimensional plane-stress linear-elastic cantilever free vibration	automated_analytical_verification
`agentfem.benchmark.linear_static_cantilever`	Two-dimensional linear-static cantilever	small-strain isotropic linear elasticity in plane strain	numerical_regression
`agentfem.benchmark.linear_viscoelastic_spectrum`	Generalized-Maxwell relaxation and dynamic spectrum	Small-strain thermorheologically simple linear viscoelastic relaxation	automated_analytical_verification
`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	external_curve_pinned_solver_reproduction_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.nafems_le10_3d_elasticity`	NAFEMS LE10 three-dimensional thick elliptical plate	three-dimensional small-strain isotropic linear elasticity under transverse pressure	external_release_regression
`agentfem.benchmark.nafems_r0016_test5h_forced_vibration`	NAFEMS R0016 Test 5H forced vibration of a simply supported beam	Three-dimensional small-strain isotropic linear elasticity with inertia, Rayleigh damping and sinusoidal transverse pressure	automated_external_single_mesh_comparison
`agentfem.benchmark.nafems_r0016_test5h_spatial_refinement`	NAFEMS R0016 Test 5H spatial-refinement stability	Three-dimensional small-strain isotropic linear elasticity with inertia, Rayleigh damping and sinusoidal transverse pressure	opt_in_automated_peak_observable_spatial_refinement_stability
`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.pdeagent_bench_eleven_family`	PDEAgent-Bench eleven-family fixed-adapter milestone	Poisson, heat, linear elasticity, Helmholtz, convection--diffusion, reaction--diffusion, scalar wave, Burgers, Stokes, Navier--Stokes, and biharmonic equations	external_runner_development_snapshot
`agentfem.benchmark.pdeagent_bench_scalar_seven_family`	PDEAgent-Bench seven-family fixed-adapter snapshot	Poisson, heat, linear elasticity, Helmholtz, convection--diffusion, reaction--diffusion, and scalar wave equations	external_runner_development_snapshot
`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.simulia_316_ratcheting_structure`	SIMULIA 316-steel shouldered axisymmetric ratcheting specimen	axisymmetric small-strain 316-steel combined-hardening plasticity under asymmetric cyclic end pressure	external_structure_comparison_not_yet_promoted
`agentfem.benchmark.thermo_creep_shared_material`	Shared temperature-dependent heat-to-creep material contract	Sequential three-dimensional transient heat transfer and small-strain thermoelastic Arrhenius power-law creep	automated_integration
`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

Exact rectangular periodic multi-point constraint¶

Stable ID: agentfem.constraint.exact_rectangular_mpc
Kind: constraint
Status: supported
Source card: src/agentfem/knowledge/cards/exact_rectangular_mpc.json

Constructs a checked rectangular periodic relation and lowers it through the ordinary linear structural and heat-transfer Step lifecycle in serial or MPI.

Public API¶

agentfem.constraints.rectangular_periodic_mpc
agentfem.constraints.RectangularPeriodicMPC
agentfem.solvers.prepare_mpc_linear_problem

Scientific contract¶

An exact periodic constraint changes the admissible discrete space by eliminating slave degrees of freedom in favor of geometrically matched masters; it is not a post-solve projection.

periodic field relation

\[ \mathbf{u}(\mathbf{x}^{+})=\mathbf{u}(\mathbf{x}^{-}) \]

Opposite rectangular faces share one field value for every selected periodic axis.

multi-point elimination

\[ u_s=\sum_{j\in\mathcal{M}(s)}c_{sj}u_j \]

Each owned slave is lowered to one checked unit-coefficient master relation in the current provider.

Inputs¶

Name	Type	Unit role	Meaning
target and periodic axes	finite-element FunctionSpace or field plus axis indices	field dependent	The mesh bounding box defines opposite minimum and maximum faces; optional strong conditions must be declared during MPC construction.

Outputs¶

Name	Type	Unit role	Meaning
exact MPC provider	RectangularPeriodicMPC	dimensionless relation	Carries the assembled backend, construction diagnostics, selected axes and geometric tolerance into model.step lowering and result evidence.
constraint dual	ConstraintDualEvidence plus nodal reaction field	force/flux and conjugate field unit	Contains the MPI-global physical resultant, homogeneous-constraint virtual work, multiplier/gap norms, and provider-owned nodal distribution after convergence.

Assumptions¶

The periodic domain is rectangular in the selected coordinate axes.
Opposite-face finite-element degrees of freedom have a one-to-one coordinate match within tolerance.
Any strong boundary conditions that remove selected slaves are supplied when the MPC is constructed.

Conventions¶

Maximum-coordinate faces are slaves and minimum-coordinate faces are masters.
Corners map directly to the opposite corner instead of forming chained slave relations.
The current public relation is homogeneous; finite-strain affine macroscopic loading uses AbaqusPeriodicConstraint instead.

Applicability¶

Linear-static solids, steady linear heat transfer, and constant-property implicit transient heat transfer on rectangular cells.
Serial and distributed meshes with a dolfinx_mpc build compatible with the active DOLFINx runtime.

Limitations¶

Arbitrary master/slave geometry, nonlinear structural Steps, and implicit structural dynamics require separate reviewed providers.
The rectangular provider recovers a physical reaction/flux distribution only after a converged linear solve. Construction diagnostics alone do not constitute dual evidence.
Its current homogeneous periodic relation performs zero constraint work. Nonzero affine macroscopic work belongs to the affine-periodic path provider rather than this endpoint contract.
Only one exact-MPC provider may own a linear system.

Minimal example¶

periodicity = constraints.rectangular_periodic_mpc(u); result = model.step(target=u, constraints=periodicity).solve_result()

Verification¶

Tests

tests/test_parallel_affine.py
tests/test_common_workflows.py

Benchmarks

None declared.

Validation rules

Reject unmatched, multiply matched, non-unit, or overlapping strong/MPC slave relations before solve.
Reproduce analytical constant scalar and vector fields through ordinary model.step calls.
Reuse one prepared linear lifecycle across accepted transient increments.
Match serial and two-rank solutions and retain provider diagnostics in SimulationResult.
Recover a deliberately nonzero slave multiplier, scatter equal-and-opposite nodal reactions across ranks, and require near-zero resultant, constraint gap, and homogeneous-constraint virtual work.
Reject unsupported analyses, missing provider backends, and multiple exact providers before assembly.
Keep global reaction and work evidence unavailable for every provider that has not supplied its own physical dual.

References¶

DOLFINx_MPC documentation: https://jsdokken.com/dolfinx_mpc/
DOLFINx_MPC source repository: https://github.com/jorgensd/dolfinx_mpc

Axisymmetric solid formulation¶

Stable ID: agentfem.formulation.axisymmetric_solid
Kind: workflow
Status: supported
Source card: src/agentfem/knowledge/cards/axisymmetric_solid.json

Small-strain axisymmetric solids on an (r,z) meridian with full three-dimensional strain and stress, full-revolution integration, engineering loads, standard fields, elastic statics, J2 plasticity, and implicit Mises creep.

Public API¶

agentfem.studies.static_solid
agentfem.studies.nonlinear_static
agentfem.studies.creep_solid
agentfem.constraints.axisymmetric_plane_strain
agentfem.constraints.axisymmetric_axis
agentfem.models.Model.surface_force
agentfem.models.Model.step
agentfem.results.region_integral
agentfem.results.region_average
agentfem.results.region_measure
agentfem.results.boundary_resultant

Scientific contract¶

The public declaration Study(dimension=2, assumption='axisymmetric') is lowered once to meridian kinematics and the cylindrical Jacobian; constitutive tensors remain full three-dimensional objects ordered (r, theta, z).

axisymmetric strain

\[ \boldsymbol{\varepsilon}=\begin{bmatrix}u_{r,r}&0&\tfrac12(u_{r,z}+u_{z,r})\\0&u_r/r&0\\\tfrac12(u_{r,z}+u_{z,r})&0&u_{z,z}\end{bmatrix} \]

The meridian displacement is ordered (u_r,u_z), while tensors are ordered (r,theta,z).

full-revolution virtual work

\[ \delta W_{\mathrm{int}}=2\pi\int_{\Omega_{rz}}\boldsymbol{\sigma}:\boldsymbol{\varepsilon}(\mathbf v)\,r\,dr\,dz \]

The same 2 pi r measure is used by stiffness, body force, traction, energy, projection, and physical result integrals.

Inputs¶

Name	Type	Unit role	Meaning
meridian mesh	two-dimensional mesh in coordinates (r,z)	length	The radial coordinate must be nonnegative. If the domain touches r=0, radial regularity requires u_r=0 on the axis.
Study	solid_mechanics, dimension=2, assumption=axisymmetric	semantic formulation	The Study controls provider selection, weak-form lowering, result recovery, and validation.

Outputs¶

Name	Type	Unit role	Meaning
U	two-component meridian displacement	length	Components are U_r and U_z.
S and E	full 3x3 tensors	stress and strain	The hoop component is retained rather than collapsed into a planar three-component tensor.
physical integrals	full-revolution scalar or meridional component result	area, volume, force, or energy	Pass study=study to public region and boundary integration helpers.

Assumptions¶

Geometry, material assignment, loading, and solution are invariant about the z axis.
Small strain; finite-strain axisymmetric kinematics are not implied by this formulation.
Isotropic elasticity is supported; planar anisotropic stiffness matrices do not define the missing hoop coupling and are rejected.

Conventions¶

Coordinates and displacement use (r,z); embedded tensors use (r,theta,z).
The 2 pi factor is retained so loads, reactions, energies, and measures describe the complete revolved body.
constraints.axisymmetric_plane_strain fixes U_z throughout a long-cylinder meridian and is a benchmark specialization, not a general axisymmetry requirement.
An integrated radial meridian traction is a circumferential integral of radial magnitude, not a Cartesian vector resultant, which cancels by symmetry.

Applicability¶

Axisymmetric linear elasticity and thermoelasticity.
Axisymmetric small-strain J2 plasticity with linear isotropic hardening.
Axisymmetric small-strain Mises power-law creep in the supported serial global route.

Limitations¶

Finite-strain, contact, reference-point moment coupling, and general anisotropic axisymmetric materials are not yet supported.
Axisymmetric implicit creep retains the same serial public-provider maturity boundary as the three-dimensional route.
A meridian mesh is not a planar unit-thickness model; direct low-level integrations that omit the Study retain planar semantics.

Minimal example¶

study = studies.static_solid(dimension=2, assumption='axisymmetric')
model = models.create(study=study, mesh=meridian)
u = model.field(fields.displacement(meridian, degree=2))
model.material(constitutive.isotropic_elastic(young=E, poisson=nu))
model.pressure(p, on=inner_wall)
result = model.step(target=u).solve_result()

Verification¶

Tests

tests/test_common_workflows.py
tests/test_external_inelastic_benchmark.py
tests/axisymmetric_mpi_driver.py

Benchmarks

agentfem.benchmark.axisymmetric_lame_cylinder
agentfem.benchmark.j2_thick_cylinder_mpi
agentfem.benchmark.creep_nafems_r0027_test7

Validation rules

Reject non-isotropic planar stiffness in an axisymmetric Study.
Require regular radial kinematics when the meridian touches the symmetry axis.
Verify the Lamé displacement field and full-revolution total-force conversion.
Verify nonlinear quadrature state against public thick-cylinder J2 and NAFEMS creep references.

References¶

Abaqus axisymmetric solid elements: https://docs.software.vt.edu/abaqusv2025/English/SIMACAEELMRefMap/simaelm-r-axisymelem.htm
NAFEMS R0027 Test 7 reproduced in the Abaqus benchmark guide: https://docs.software.vt.edu/abaqusv2025/English/SIMACAEBMKRefMap/simabmk-c-creeptest7.htm

Uniform boundary traction from a requested resultant force¶

Stable ID: agentfem.load.surface_resultant
Kind: workflow
Status: supported
Source card: src/agentfem/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 planar 2D the resultant is per unit out-of-plane thickness; in an axisymmetric Study, model.surface_force uses the complete revolved boundary area.

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.
Direct loads.surface_force calls require study=study to select axisymmetric rather than planar measure semantics.

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.
Axisymmetric distributing_coupling and remote_force are rejected until ring/reference kinematics and moment semantics are implemented.

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

Global Chaboche combined-hardening plasticity¶

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

A three-dimensional small-strain J2 route with exponential isotropic hardening, multiple Armstrong--Frederick backstresses, committed quadrature state, a fully discrete tangent, cyclic amplitudes, cutback, standard fields and restart through the ordinary model.step workflow.

Public API¶

agentfem.constitutive.chaboche
agentfem.constitutive.ChabocheCombinedHardening
agentfem.constitutive.ChabocheQuadratureState
agentfem.constitutive.material_strain_path
agentfem.constitutive.PlasticMaterialHistoryStep
agentfem.models.Model.step
agentfem.benchmarks.simulia_316_shouldered_ratcheting_benchmark
agentfem.benchmarks.certify_simulia_316_shouldered_ratcheting_accuracy
agentfem.benchmarks.certify_simulia_316_shouldered_ratcheting_convergence

Scientific contract¶

The yield surface translates through several Armstrong--Frederick backstresses while its radius evolves toward an exponential saturation value; one backward-Euler consistency solve supplies trial stress and state to global Newton.

yield function

\[ f=\sqrt{\frac{3}{2}(\mathbf{s}-\boldsymbol{\alpha}):(\mathbf{s}-\boldsymbol{\alpha})}-[\sigma_{y0}+Q(1-e^{-b p})] \]

The total backstress is the sum of all declared components.

backstress evolution

\[ \dot{\boldsymbol{\alpha}}_i=\frac{2}{3}C_i\dot{\boldsymbol{\varepsilon}}^p-\gamma_i\boldsymbol{\alpha}_i\dot p \]

Dynamic recovery bounds each kinematic-hardening component under repeated loading.

isotropic radius

\[ R(p)=Q(1-e^{-bp}) \]

Q and b are both zero or both positive in the public material contract.

Inputs¶

Name	Type	Unit role	Meaning
elastic and initial-yield data	E, nu and initial yield stress	consistent stress system	Small-strain isotropic elastic predictor and initial Mises radius.
combined-hardening data	Q, b and one or more (C_i, gamma_i) pairs	stress and inverse strain	Saturation and dynamic-recovery parameters supplied by a reviewed calibration.

Outputs¶

Name	Type	Unit role	Meaning
S, PE and PEEQ	quadrature fields	stress and strain	Accepted Cauchy stress, plastic strain and accumulated equivalent plastic strain.
ALPHA	quadrature tensor field	stress	Sum of all committed backstress components.
DDSDDE	fourth-order quadrature tensor field	stress per strain	Analytical consistent linearization of the fully discrete backward-Euler return map consumed by global Newton.
material history result	SimulationResult histories	declared material unit system	Stress, strain, PE, PEEQ, individual and total backstress, yield residual, path identity, recoverable hardening storage, reference-yield dissipation, dynamic-recovery dissipation and a separately identified backward-Euler contribution; response-only histories omit DDSDDE.

Assumptions¶

Small strain and associative three-dimensional or axisymmetric Mises plasticity.
Material parameters are calibrated in one consistent unit system.
The public cyclic path is a sequence of equilibrium states, not an implicit dynamic history.

Conventions¶

Every rejected increment rolls back PE, PEEQ and every backstress component atomically.
The normalized Step coordinate stays monotone while the declared amplitude may reverse.
ALPHA is the total backstress; individual components remain in the restartable constitutive state.
Signed plastic work, recoverable hardening storage, reference-yield dissipation, dynamic-recovery dissipation and backward-Euler numerical dissipation remain separately named.
The accepted discrete plastic-work ledger closes without presenting the backward-Euler contribution as material heat.

Applicability¶

Research and laboratory-scale three-dimensional or axisymmetric cyclic plasticity with reviewed Chaboche calibration.
Stress-, strain-, or mixed-control monotone and reversed paths requiring inspectable quadrature state.

Limitations¶

Plane stress, finite-strain plasticity and temperature-dependent cyclic plasticity are not implemented.
The external shouldered-specimen comparison is digitized from a public raster figure and retains an explicit uncertainty and convergence obligation.
The five-cycle structure evidence has passed independent adaptive-path and spatial-mesh gates, and one complete 100-cycle response passes the predeclared raster-data error and equilibrium gates; a clean release rerun remains required before maturity promotion.
The discrete constitutive ledger is closed, but a calibrated thermomechanical heat-conversion model is not inferred from it.

Minimal example¶

Create constitutive.chaboche(...). For a material test, pass a tensor-valued constitutive.material_strain_path(...) to material.history(path).solve_result(). For a global model, register it in studies.static_solid(dimension=3, nonlinear=True) or an axisymmetric nonlinear-static Study, declare a tabular cyclic amplitude, and call model.step(target=u, material=steel, amplitude=history).

Verification¶

Tests

tests/test_constitutive_models.py
tests/test_p1_platform.py
tests/test_ratcheting_structure.py

Benchmarks

agentfem.benchmark.chaboche_combined_hardening
agentfem.benchmark.simulia_316_ratcheting_structure

Validation rules

Reject missing or mismatched backstress parameter pairs.
Reject a restart whose material, mesh, quadrature state or amplitude identity differs.
Commit all hardening variables only after global increment acceptance.
Require response-only and consistent-linearization material histories to produce identical accepted stresses and states.
Preserve every declared reversal and hold knot while automatic cutback limits the maximum accepted equivalent-plastic-strain increment.
Keep digitized experimental values, raster uncertainty, AgentFEM acceptance tolerance and official-input SHA-256 distinct in structure evidence.
Require independent mesh and adaptive path-integration convergence before promoting the shouldered specimen result.
Require accepted plastic work to equal hardening-storage change plus reference-yield, dynamic-recovery and separately identified backward-Euler dissipation.

References¶

Abaqus theory: models for metals subjected to cyclic loading: https://docs.software.vt.edu/abaqusv2024/English/SIMACAETHERefMap/simathe-c-combinedhardening.htm
Abaqus verification: import of combined-hardening material state: https://docs.software.vt.edu/abaqusv2024/English/SIMACAEVERRefMap/simaver-c-import-plast.htm
SIMULIA example: uniaxial ratcheting under tension and compression: https://docs.software.vt.edu/abaqusv2025/English/SIMACAEEXARefMap/simaexa-c-ratchetting.htm
NEML documentation: Chaboche nonassociative hardening: https://neml.readthedocs.io/en/stable/hardening/non/chaboche.html
Chaboche and Cailletaud: Integration methods for complex plastic constitutive equations: https://doi.org/10.1016/0045-7825(95)00957-4
Doghri and Ouaar: tangent operators, cyclic plasticity and numerical algorithms: https://doi.org/10.1016/S0020-7683(03)00013-1
MOOSE radial-return material substepping: https://mooseframework.inl.gov/source/materials/RadialReturnStressUpdate.html

Material-axis composite ply failure assessment¶

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

Evaluates sign-aware maximum-stress, plane-stress Hashin, or explicitly parameterized Tsai--Wu initiation indices in ply material axes, computes the proportional first-failure load factor, and applies the same replaceable assessment to every stable laminate section point without evolving damage.

Public API¶

agentfem.constitutive.CompositeStrengths2D
agentfem.constitutive.PlyFailureCriterion
agentfem.constitutive.MaximumStress2D
agentfem.constitutive.Hashin2D
agentfem.constitutive.TsaiWu2D
agentfem.constitutive.PlyFailureAssessment
agentfem.constitutive.LaminateFailureAssessment
agentfem.constitutive.composite_strengths_2d
agentfem.constitutive.assess_ply_failure
agentfem.constitutive.assess_laminate_failure

Scientific contract¶

Strength allowables and initiation criteria are independent assessment assets that consume material-axis ply stress; they do not alter elastic stiffness or constitute a progressive-damage law.

Hashin fibre modes

\[ F_{ft}=(\sigma_{11}/X_t)^2+(\tau_{12}/S_{12})^2,\qquad F_{fc}=(\sigma_{11}/X_c)^2 \]

The tensile or compressive fibre branch is selected by the sign of sigma_11.

Hashin matrix modes

\[ F_{mt}=(\sigma_{22}/Y_t)^2+(\tau_{12}/S_{12})^2,\qquad F_{mc}=(\sigma_{22}/(2S_{12}))^2+[(Y_c/(2S_{12}))^2-1](\sigma_{22}/Y_c)+(\tau_{12}/S_{12})^2 \]

The tensile or compressive matrix branch is selected by the sign of sigma_22.

Tsai--Wu interaction

\[ F=F_1\sigma_{11}+F_2\sigma_{22}+F_{11}\sigma_{11}^2+F_{22}\sigma_{22}^2+2F_{12}\sigma_{11}\sigma_{22}+F_{66}\tau_{12}^2 \]

F12 is supplied through an explicit normalized interaction coefficient; no empirical default is inferred.

Inputs¶

Name	Type	Unit role	Meaning
material-axis ply stress	(sigma_11, sigma_22, tau_12)	stress	Global or section-axis stress is rotated before assessment; the function never guesses a coordinate frame.
five plane-stress strengths	positive Xt, Xc, Yt, Yc and S12	stress	Tension and compression allowables remain distinct.

Outputs¶

Name	Type	Unit role	Meaning
ply or laminate failure assessment	per-mode indices, governing mode/location, accepted flag and proportional first-failure factor	dimensionless	Laminate output retains every stable ply section-point identity and its material-axis stress.

Assumptions¶

The built-in criteria use a plane-stress unidirectional-ply idealization.
The reported load factor assumes proportional scaling of the supplied stress state.

Conventions¶

Material direction 1 is longitudinal/fibre, direction 2 is transverse, and tau_12 is tensor shear stress.
Initiation occurs when the governing index reaches one.

Applicability¶

First-ply screening of recovered lamina or classical-laminate section-point stresses.

Limitations¶

The assessment does not degrade stiffness, redistribute stress, advance damage, or predict final laminate failure.
Interlaminar normal/shear failure, three-dimensional criteria, Puck, LaRC and fracture-energy regularization are separate capabilities.
Cell- or section-point averaging must not be interpreted as an unresolved local maximum.

Minimal example¶

strengths = constitutive.composite_strengths_2d(xt=1500e6, xc=1000e6, yt=50e6, yc=200e6, s12=100e6); assessment = constitutive.assess_ply_failure((750e6, 25e6, 50e6), strengths, criterion='hashin_2d')

Verification¶

Tests

tests/test_composite_failure.py

Benchmarks

None declared.

Validation rules

Reject nonpositive strengths, malformed stresses, unknown built-in criteria and incomplete laminate strength mappings.
Verify distinct tension/compression branches, pure and combined Hashin modes, and the nonlinear matrix-compression proportional root.
Verify Tsai--Wu tensile/compressive intercepts, convex interaction bounds, and its proportional first-failure root without assuming an interaction coefficient.
Verify that every laminate section point is rotated from section axes into its named ply material axes before assessment.
Keep initiation screening distinct from progressive damage and structural failure prediction.

References¶

Hashin (1980), Failure Criteria for Unidirectional Fiber Composites: https://doi.org/10.1115/1.3153664
Tsai and Wu (1971), A General Theory of Strength for Anisotropic Materials: https://doi.org/10.1177/002199837100500106

Creep damage and modified-theta assessment¶

Stable ID: agentfem.material.creep_damage_assessment
Kind: material
Status: supported
Source card: src/agentfem/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: src/agentfem/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}=\frac{\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

\[ \frac{\mathrm{d}D_f}{\mathrm{d}N}=C\left\langle\frac{\Delta\delta/\delta_f-\eta_{\mathrm{th}}}{1-\eta_{\mathrm{th}}}\right\rangle_{+}^{m}\left(\frac{\delta_{\max}^{+}}{\delta_f}\right)^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 through the shared provider-owned dual protocol, but each native enforcement backend must still implement and verify its own extraction.
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

Non-orthogonal woven-fabric surface response¶

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

Defines independent woven-surface tension, trellising-shear, and bending channels; retains varying orientations in named multilayer stacks; separates objective in-plane and normal fibre curvature; supplies exact first- and second-variation actions for a neighbour-reconstructed displacement bending energy; and verifies an internal assembled-local plus matrix-free Newton composition while keeping a public shell Step and forming as explicit later gates.

Public API¶

agentfem.materials.FiberFrame
agentfem.constitutive.SurfaceConstitutive
agentfem.constitutive.TabulatedResponse
agentfem.constitutive.DecoupledFabricSurface
agentfem.constitutive.decoupled_fabric_surface
agentfem.constitutive.DecoupledFibrousShell
agentfem.constitutive.FibrousShellExpressions
agentfem.constitutive.decoupled_fibrous_shell
agentfem.constitutive.FabricLayer
agentfem.constitutive.FabricStack
agentfem.constitutive.fabric_layer
agentfem.constitutive.fabric_stack
agentfem.constitutive.FabricFormingLimits
agentfem.constitutive.fabric_forming_limits
agentfem.studies.static_membrane
agentfem.mechanics.director_shell_kinematics
agentfem.mechanics.fiber_curve_kinematics
agentfem.mechanics.fibrous_shell_kinematics_ufl
agentfem.mechanics.fibrous_shell_compatibility_ufl
agentfem.mechanics.surface_deformation_gradient
agentfem.operators.FiberDirectionBendingOperator
agentfem.operators.FiberDirectionBendingResponse
agentfem.operators.FiberDirectionBendingIncrement
agentfem.operators.fiber_direction_bending
agentfem.operators.ConvectedCellFiberOperator
agentfem.operators.ConvectedCellFiberKinematics
agentfem.operators.ConvectedCellFiberIncrement
agentfem.operators.convected_cell_fiber
agentfem.operators.DisplacementFiberBendingOperator
agentfem.operators.displacement_fiber_bending
agentfem.operators.NonlinearOperatorContribution
agentfem.results.fabric_membrane_cell_fields
agentfem.results.fabric_stack_membrane_cell_fields
agentfem.results.fabric_stack_result_manifest
agentfem.models.Model.step

Scientific contract¶

Warp and weft are independent structural directions that convect with the surface deformation, while yarn tension, trellising shear, and bending are calibrated and accumulated as distinct constitutive energy channels.

fiber stretches and trellising angle

\[ \lambda_{i}=\lVert\mathbf{F}_{s}\mathbf{a}_{i}\rVert,\qquad \gamma=\Theta_{0}-\arccos(\widehat{\mathbf{F}_{s}\mathbf{a}_{1}}\cdot\widehat{\mathbf{F}_{s}\mathbf{a}_{2}}) \]

The two directions need not remain orthogonal, unlike a conventional material frame.

decoupled surface energy

\[ \Psi_{s}=\Psi_{1}(\lambda_{1}-1)+\Psi_{2}(\lambda_{2}-1)+\Psi_{\gamma}(\gamma)+\tfrac{1}{2}\boldsymbol{\kappa}^{T}\mathbf{D}_{b}\boldsymbol{\kappa} \]

Independent tension, in-plane shear, and bending data remain independently identifiable.

fibre-curve bending split

\[ \boldsymbol{\kappa}_{f}=\mathrm d\mathbf{t}/\mathrm ds,\qquad \kappa_{g}=\boldsymbol{\kappa}_{f}\cdot(\mathbf{n}\times\mathbf{t}),\qquad \kappa_{n}=\boldsymbol{\kappa}_{f}\cdot\mathbf{n} \]

In-plane/geodesic and normal bending are separate objective measures and require an explicit unit-fibre direction gradient.

Inputs¶

Name	Type	Unit role	Meaning
surface deformation, fiber frame, response curves, and curvature	2D surface deformation gradient, two independent reference directions, piecewise-linear channels, and three generalized curvatures	dimensionless, radians, force per reference length, inverse length, and bending stiffness	Curve extrapolation and yarn compression behavior are explicit choices.
named computational layers and physical-layer identities	ordered FabricLayer entries with explicit physical_layer_ids for any same-orientation grouping	identity and integer multiplicity	No scalar weight silently represents omitted plies; every grouped physical layer remains addressable evidence.

Outputs¶

Name	Type	Unit role	Meaning
surface constitutive response	fiber kinematics, membrane resultants, bending moments, 6x6 local tangent, and stored energy	dimensionless, force per length, moment per length, and energy per area in a consistent unit system	The local response includes bending; the current global membrane Step consumes only tension and trellising shear.
global membrane result fields	Displacement plus DG cell fields FABRIC_GENERALIZED_STRAIN, FABRIC_GENERALIZED_RESULTANT, FABRIC_WARP_DIRECTION, FABRIC_WEFT_DIRECTION, and SENER	length, dimensionless/radians, force per reference length, unit directions, and energy per reference area	The generalized strain and resultant vectors use the fixed warp, weft, trellising component order.
multilayer local response and forming assessment	stable per-layer kinematics/resultants/energy plus dimensionless utilization against declared strain, trellising, and curvature limits	per-layer constitutive units and dimensionless utilization	Only compatible energy scalars are aggregated; resultants retain their layer frames, and limit assessment is screening rather than a wrinkle prediction.
multilayer membrane result fields	stable per-layer DG fields expanded from generic fabric requests plus aggregate SENER and a layer-to-field manifest	the same per-layer units as the single-surface fields	Layer order and a readable slug form collision-free field prefixes; same-orientation groups aggregate only their explicitly listed physical layers, and unlike generalized resultants are never silently summed.
local fibrous-shell response	independent membrane, transverse-shear, in-plane-bending, and normal-bending resultants, energy channels, and a 9x9 block tangent	generalized shell forces, moments, energy per reference area, and their conjugate tangents	The constitutive contract is element-neutral and rejects overlapping legacy bending ownership.
symbolic fibrous-shell constitutive potential	nine generalized UFL measures, one stored-energy expression, four named energy channels, and nine conjugate resultants	the same generalized shell units as the local response	A future operator constructs compatible measures; UFL differentiates this single potential into a consistent residual and Jacobian.
independent-direction bending response	owned-cell in-plane/normal curvature, energy, exact local-plus-ghost direction residual, exact direct surface-tangent dual, and exact matrix-free response linearization	curvature, energy, and virtual work in a consistent unit system	The direction is normalized before one cached neighbor reconstruction; the response and its linearization differentiate both direction and current-tangent paths, while tangent_action remains the fixed-tangent direction-only convenience.
displacement-derived cell-fibre kinematics	current 3x2 tangents, fibre stretch, unit direction, exact directional derivative, exact displacement-space adjoint, and exact adjoint linearization	surface deformation and work-conjugate virtual quantities	Reference tangent coordinates are convected by the cell-average gradient of a three-component displacement on a two-dimensional parameter mesh; no independent physical direction field is exposed to the user.
displacement-derived fibre-bending contribution	one inspectable energy, exact displacement residual, and matrix-free consistent tangent action	energy and virtual work in the declared consistent unit system	The composition reuses the convected-fibre kinematics and neighbour-bending response without merging their ownership or claiming a complete shell element.

Assumptions¶

The current foundation uses decoupled, rate-independent elastic channels.
Tabulated data are expressed in one consistent unit system.

Conventions¶

Positive trellising shear is the reduction of the included warp/weft angle.
The shear response is odd and yarn compression is suppressed when tension_only is enabled.
Generalized bending order is warp, weft, then twist.

Applicability¶

Material calibration, constitutive screening, local varying-orientation multilayer response, and finite-kinematics in-plane single-surface or shared-kinematics multilayer woven-membrane equilibrium.

Limitations¶

The global membrane Step rejects nonzero bending because no shell element consumes that channel yet.
The independent-direction bending operator supplies exact direction and direct surface-tangent first derivatives plus their exact admissible response linearization, but it does not include compatibility-constraint blocks.
The displacement-derived fibre transfer and bending response compose into the complete first variation and matrix-free consistent tangent of the bending energy, but boundary moments, complete shell assembly, and a public shell Step remain promotion gates.
The internal hybrid Newton runtime verifies total derivatives, strong constraints, retained reactions, rollback, serial/two-rank equivalence, the ordinary nonlinear load/result lifecycle, and separate true-operator/preconditioner ownership, but does not yet expose a public shell Procedure.
A displacement-only boundary is not a complete clamp for the rotation-free curvature operator; an inspectable edge contract now distinguishes displacement/effective-force and normal-rotation/bending-moment pairs, but provider lowering remains unavailable.
Under MPI, conservative neighbour energies require a partition-complete stencil; wider-than-halo reconstructions are rejected.
FabricStack membrane lowering shares one surface displacement across layers; transverse slippage, independent material normals, and shell equilibrium remain promotion gates.
Contact, friction, inter-ply slip, locking control, and forming procedures are not implemented.
Rate effects, hysteresis, irreversible locking, yarn slippage, and damage need additional stateful laws.
Material-point tests do not establish a forming simulation or wrinkle prediction capability.

Minimal example¶

study = studies.static_membrane(); model = models.create(study=study, mesh=domain); u = model.field(fields.displacement(domain)); fabric = constitutive.decoupled_fabric_surface(frame=materials.fiber_frame((1,0),(0,1)), warp_tension=tension, weft_tension=tension, shear=shear, bending_stiffness=((0,0,0),(0,0,0),(0,0,0))); model.material(fabric); result = model.step(target=u).solve_result()

Verification¶

Tests

tests/test_composite_materials.py
tests/test_fiber_bending_operator.py
tests/test_convected_cell_fiber.py
tests/test_additive_tangent_matrix.py
tests/test_hybrid_nonlinear.py
tests/test_parallel_mesh_semantics.py

Benchmarks

agentfem.benchmark.fibrous_shell_foundation

Validation rules

Require independent non-collinear reference fiber directions and non-collapsed convected directions.
Require an odd trellising response and a symmetric positive-semidefinite bending stiffness.
Verify zero reference response, tension-only compression behavior, stored-energy consistency, and separation of tension, shear, and bending channels.
Verify objective director kinematics and a nonzero global membrane patch with positive deformation Jacobian and energy.
Verify objective fibre-curve in-plane/normal curvature separation, stable multilayer identity, energy-only stack aggregation, fail-closed curvature assessment, and global per-layer field preservation.
Verify that same-orientation grouping scales energy, resultants and tangents by the explicit physical-layer ID count and rejects duplicate IDs across groups.
Verify that the three-dimensional surface deformation lift maps both reference tangents and the reference normal and is objective under superposed rotation.
Verify pure local fibrous-shell modes, block-tangent symmetry, energy-channel additivity, and rejection of double-counted bending stiffness.
Verify that UFL differentiation of the nine-component symbolic shell potential exactly recovers every declared generalized resultant.
Verify that operator-side symbolic shell measures reproduce the local objective measures and remain invariant under a superposed rigid rotation.
Verify that the no-slip mixed-field contract vanishes for an exactly convected layer and detects director normalization and fibre-convection violations without redundant multiplier equations.
Verify that neighbour-reconstructed fibre bending matches finite-difference energy and residual derivatives, has a symmetric Hessian action, is invariant to pointwise direction scaling, and transforms objectively under a superposed three-dimensional rotation in serial and two-rank execution.
Verify that displacement-derived current tangents, fibre stretch, and unit direction reproduce a rigid rotation, match finite-difference directional derivatives, and satisfy the global derivative/adjoint work identity in serial and under two MPI ranks.
Verify that the composed displacement-derived bending residual includes both direction and direct surface-tangent paths and closes the global energy--virtual-work identity in serial and under two MPI ranks.
Verify that exact response and kinematic-adjoint linearizations compose into a displacement-space tangent that matches residual differences in serial and under two MPI ranks.
Verify that the composed displacement bending energy is objective, its residual and tangent are covariant under three-dimensional rigid rotation, and its Hessian action is symmetric.
Verify that the assembled-local plus matrix-free PETSc operator converges with a separate local preconditioner and handles strong constraints once.
Verify that the total residual is the total-energy derivative and the additive tangent is the total-residual derivative.
Verify matching displacement, bending-energy, maximum-response, constrained-reaction, free-residual, and Newton-iteration observables in serial and under two MPI ranks.
Verify that a failed nonlinear attempt restores the pre-attempt primary field.
Verify fixed increments, automatic cutback, progress events, snapshots, and SimulationResult through the shared nonlinear Procedure lifecycle.
Verify that an independent assembled preconditioner does not alter the true local-plus-nonlocal tangent action.
Reject conservative MPI neighbour energies when the requested reconstruction rings exceed the available cell halo.
Keep shell, contact, and forming claims unavailable until their independent patch tests and benchmarks pass.

References¶

Boisse et al. (2022), bias-extension characterization review: https://doi.org/10.1007/s12289-022-01682-8
Liang, Colmars, and Boisse (2017), fibrous-reinforcement shell formulation: https://doi.org/10.1016/j.compositesa.2017.04.024
Peng and Cao (2005), non-orthogonal woven-fabric constitutive model: https://doi.org/10.1016/j.compositesa.2004.08.008
Bai et al. (2020), specific 3D shell for textile reinforcement: https://doi.org/10.1016/j.compositesa.2020.106135
Bai et al. (2025), multilayer shell with varying fibre orientations: https://doi.org/10.1016/j.compstruct.2025.119593
Zheng et al. (2026), virtual-fibre prediction of in-plane bending: https://doi.org/10.1016/j.compositesb.2026.113771
Boisse et al. (2018), bending and wrinkling review: https://doi.org/10.1016/j.compositesb.2017.12.061
Duong, Itskov, and Sauer (2022), rotation-free shells with in-plane fibre bending: https://doi.org/10.1002/nme.6937
Steer et al. (2021), rotation-free in-plane bending of fibrous reinforcements: https://doi.org/10.1016/j.ijsolstr.2021.03.001

Finite-strain logarithmic J2 plasticity¶

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

Multiplicative finite-strain J2 plasticity with quadratic Hencky elasticity, associated isochoric flow, linear isotropic hardening, a spectral analytical algorithmic tangent with an independent numerical oracle, and public strong-boundary, displacement-only affine/MPC, 3D P2/DG0 mixed affine, and 2D plane-strain Q2/DPC1 mixed affine model.step routes sharing provider-owned quadrature evidence.

Public API¶

agentfem.constitutive.FiniteStrainJ2Logarithmic
agentfem.constitutive.MaterialPointBatchResult
agentfem.constitutive.finite_strain_j2_logarithmic
agentfem.constitutive.update_material_points
agentfem.fields.displacement_pressure
agentfem.models.Model.step
agentfem.mechanics.FiniteStrainJ2StateTransaction
agentfem.mechanics.FiniteStrainJ2StandardProblem
agentfem.mechanics.finite_strain_j2_standard_problem
agentfem.mechanics.finite_strain_j2_affine_problem
agentfem.mechanics.finite_strain_j2_mixed_affine_problem
agentfem.results.MixedJ2ElasticEnergyDiagnostics
agentfem.results.mixed_j2_elastic_energy_diagnostics
agentfem.results.HomogenizedAlgorithmicTangent
agentfem.results.homogenized_algorithmic_tangent
agentfem.constraints.AffineMacroGradientLift

Scientific contract¶

The total deformation gradient is split multiplicatively; a quadratic Hencky elastic potential supplies Kirchhoff stress, and an associative pressure-insensitive radial return updates an isochoric plastic deformation gradient and accumulated equivalent plastic strain.

multiplicative kinematics

\[ \mathbf F=\mathbf F_e\mathbf F_p,\qquad \det\mathbf F_p=1 \]

The identity initial plastic state and pressure-insensitive flow preserve plastic volume in the discrete update.

elastic potential

\[ \psi_e=\mu\lVert\operatorname{dev}(\log\mathbf V_e)\rVert^2+\frac{K}{2}[\operatorname{tr}(\log\mathbf V_e)]^2 \]

A quadratic logarithmic elastic potential is part of the model identity and is not interchangeable with a Neo-Hookean potential.

yield function

\[ f=q-(\sigma_{y0}+H\bar\varepsilon_p),\qquad q=\sqrt{\frac{3}{2}\,\operatorname{dev}\boldsymbol\tau:\operatorname{dev}\boldsymbol\tau} \]

The current isotropic yield radius grows linearly with accumulated equivalent plastic strain.

radial return

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

A positive trial yield value produces the associated principal logarithmic-strain corrector.

algorithmic first-Piola tangent

\[ \mathbb A=\frac{\partial \mathbf P_{n+1}}{\partial \mathbf F_{n+1}}\bigg|_{\mathbf F_{p,n},\bar\varepsilon_{p,n}} \]

The production tangent differentiates the complete elastic or plastic spectral return at fixed committed state, including the first-Piola geometric term. A centered derivative of the same discrete return remains an explicit verification oracle.

displacement-only recoverable stored energy

\[ \mathrm{SENER}=\mathrm{ELENER}+\mathrm{HARDENER}=\psi_e+\frac{1}{2}H\bar\varepsilon_p^2 \]

For displacement-only J2, the two provider-owned components separate primal Hencky elastic free energy from isotropic-hardening storage. The mixed provider retains the same algebraic SENER=ELENER+HARDENER identity but gives ELENER the condensed semantics declared below. PDENER is an irrecoverable cumulative energy per reference volume and is not part of SENER.

irrecoverable plastic dissipation

\[ \mathrm{PDENER}_{n+1}=\mathrm{PDENER}_n+\sigma_{y0}\Delta\bar\varepsilon_p \]

For the declared rate-independent associative J2 law, hardening energy is stored separately and the remaining initial-yield work is accumulated as nonnegative plastic dissipation.

mixed volumetric equation

\[ p=\tfrac13\operatorname{tr}\boldsymbol\tau,\qquad \ln J-p/\kappa=0 \]

The experimental mixed route solves a cellwise mean Kirchhoff stress that is positive in tension; it is not the positive-compression Cauchy pressure of the mixed Neo-Hookean provider.

mixed Newton system

\[ \begin{bmatrix}K_{uu}&K_{up}\\K_{pu}&K_{pp}\end{bmatrix}\begin{bmatrix}\Delta u\\\Delta p\end{bmatrix}=-\begin{bmatrix}R_u\\R_p\end{bmatrix} \]

Displacement and pressure-like degrees of freedom remain independent and all four tangent blocks are assembled monolithically.

mixed condensed elastic-energy representation

\[ \mathrm{ELENER}=\psi_{e,\mathrm{dev}}+\frac{p^2}{2\kappa} \]

The nonnegative condensed mixed-energy channel is distinct from MIXED_POTENTIAL, which retains the saddle variational density. Its volumetric point value equals the primal storage only where p=kappa ln(J), and integration does not make it the primal physical-energy observable. The explicit mixed-energy diagnostic reports primal and condensed energies, their signed gap, signed pressure orthogonality, nonnegative pressure-constraint defect, and decomposition residual. An external primal-energy oracle must consume the primal channel, never mixed ELENER.

Inputs¶

Name	Type	Unit role	Meaning
deformation gradients	old and new finite 3x3 tensors with positive determinant	dimensionless kinematics	The local update consumes the new gradient and a committed multiplicative state; the old gradient remains in the neutral provider contract.
material parameters	E, nu, initial yield stress, linear hardening modulus	consistent stress system	The public factory owns these reviewed values; duplicated point properties may not silently override them.
optional mixed affine field	3D P2/DG0 or 2D plane-strain Q2/DPC1 displacement and mean Kirchhoff stress with one exact affine-periodic constraint	length and stress	The experimental mixed lowering retains the constitutive J2 state but replaces its global volumetric response by an independently solved scalar field.

Outputs¶

Name	Type	Unit role	Meaning
Cauchy stress	symmetric 3x3 tensor per integration point	stress	The current-configuration stress is returned by the neutral material contract.
FP and PEEQ	committed/trial quadrature state	dimensionless	The full plastic deformation gradient and accumulated equivalent plastic strain have a versioned portable schema.
PDENER	committed/trial cumulative quadrature state and accepted response	energy per reference volume	Cumulative irrecoverable plastic dissipation is nonnegative, is committed only with an accepted increment, and is neither a dimensionless history variable nor part of recoverable SENER.
F, P, S, MISES, SENER, ELENER, HARDENER and PDENER	accepted provider-owned quadrature response	F is dimensionless; P, S and MISES are stress; SENER, ELENER, HARDENER and PDENER are energy per reference volume	All public equilibrium lowerings retain accepted constitutive fields without reconstructing them from a history-free material law; explicitly named DG0 cell averages are separate visualization products.
mixed J2 elastic-energy diagnostics	volume-normalized primal and condensed energies with decomposition evidence	energy per complete reference-cell volume	Aligned accepted F, mean-Kirchhoff-stress, inverse-bulk-modulus and condensed ELENER fields produce the primal energy, condensed energy, signed primal-minus-condensed gap, signed pressure-orthogonality term, nonnegative pressure-constraint-defect term, decomposition residual, and pressure-residual extrema. Decomposition verification is not solver convergence or benchmark promotion.
consistent tangent	9 by 9 derivative of first Piola stress with respect to deformation gradient	stress	The default implementation uses the spectral analytical derivative of the complete discrete radial return with fixed old state. The selectable central-difference implementation remains an independent oracle and is not required by the production global solve.
homogenized current-state algorithmic tangent	4 by 4 or 9 by 9 derivative of homogenized first-Piola stress with respect to the prescribed macroscopic deformation gradient	stress	The serial affine-periodic recovery condenses the converged full Jacobian through the exact provider-owned macro-gradient lift. It uses the final accepted increment only while a state-owned linearization token proves the tangent came from that increment, and records one PETSc solve plus reduced-equilibrium evidence per column; it does not rerun or finite-difference the load path. A checkpoint restoration that did not persist the macro tangent fails closed.
MEAN_KIRCHHOFF_STRESS, MEAN_KIRCHHOFF_STRESS_CELL and MIXED_POTENTIAL	exact mixed primary field, recovered visualization field, and provider-owned quadrature diagnostic	stress, stress, and energy per reference volume	MEAN_KIRCHHOFF_STRESS is the exact DG0 or DPC primary field, positive in tension, retained in SimulationResult and the transaction-owned portable checkpoint. For DPC1, XDMF writes the explicitly recovered DG0 cell-average MEAN_KIRCHHOFF_STRESS_CELL and does not silently serialize multiple DPC moments as one cell value. MIXED_POTENTIAL is a saddle variational density and cannot replace condensed ELENER, SENER, or the explicit primal-energy diagnostic.

Assumptions¶

Three-dimensional isothermal rate-independent isotropic material response.
Quadratic Hencky elasticity, associated J2 flow and linear isotropic hardening.
Plastic spin follows the elastic polar update used by the discrete logarithmic formulation.
The mixed routes use a three-dimensional P2/DG0 tetrahedral formulation or a two-dimensional plane-strain Q2/DPC1 quadrilateral formulation with F33=1 under exact affine-periodic kinematics.

Conventions¶

State order and output aliases are declared by MaterialStateSchema rather than inferred from arrays.
Global iterations read committed state and write trial state; only an accepted increment may commit.
The tangent is the row-major first-Piola/deformation-gradient reference derivative.
The ordinary route validates prescribed-value, natural-load, amplitude, solver, nodal, quadrature, mesh, material and increment-control identity; the affine route additionally validates the periodic-equation identity before restore.
Mixed portable checkpoints split live and accepted mixed functions into standalone U and exact MEAN_KIRCHHOFF_STRESS fields; only the owning state transaction reassembles them after identity validation. SimulationResult likewise retains the exact primary field independently of visualization recovery.
The assembled pressure-block residual is equilibrium evidence. The reported pointwise pressure defect is max_q |ln(J_q)-p_h(q)/kappa| at constitutive quadrature points; for DPC1, p_h varies within each cell, so this diagnostic is not DG0 and is not the assembled discrete residual.
The mixed interpolation is intended to mitigate volumetric locking; it is neither certified locking-free nor currently supported by a locking-convergence claim. Such claims require formulation and mesh-convergence evidence for the problem being reported.

Applicability¶

Material-point studies and three-dimensional solids with ordinary strong boundaries, proportional prescribed motion and reference dead loads through model.step.
Three-dimensional affine-periodic cells with one or more explicitly partitioned compatible material regions under prescribed macroscopic deformation through model.step.
Serial three-dimensional P2/DG0 or two-dimensional plane-strain Q2/DPC1 mixed affine-periodic cells that use an independent mean Kirchhoff stress and are intended to mitigate volumetric locking.

Limitations¶

The ordinary provider accepts strong Dirichlet or remote-displacement constraints, a shared normalized amplitude, and reference-configuration dead loads; absolute TimeDependentDirichlet histories, follower loads, weak boundary models, contact and MPC constraints require separate consistent lowering.
The affine provider requires exactly one AbaqusPeriodicConstraint and no body-force or natural-load power; all regional materials must share one declared state schema, tangent convention, and stored-energy component contract.
The mixed provider requires 3D tetrahedral P2/DG0 or 2D plane-strain quadrilateral Q2/DPC1, one exact affine-periodic constraint, serial sparse reduction, and bulk/shear no greater than the temporary 1e4 implementation ceiling; a plastic simple-shear direction test guards tangent accuracy at that ceiling, but the value is not a material-model validity range, a general accuracy range, or evidence of locking-free response. Distributed mixed MPC, ordinary strong-boundary mixed lowering, and body/natural-load power are not implemented.
The default tangent is the spectral analytical derivative of the elastic/plastic discrete return and first-Piola transformation; a selectable centered-difference path remains the independent oracle. Rank-local point updates remain vectorized. The mixed transformation still obtains its fixed-pressure deviatoric block by subtracting the analytical Hencky volumetric contribution, which becomes ill-conditioned as K/mu grows, so the explicit 1e4 guard and residual, pressure-defect, energy, and mesh/formulation-convergence evidence remain necessary.
The homogenized current-state algorithmic tangent is presently a serial exact-affine recovery for providers declaring purely kinematic macro-gradient dependence. Its analytical homogeneous Q2/DPC1 and P2/DG0 checks establish the Schur-condensation convention, not Zhang benchmark agreement or distributed mixed-MPC support. A restart that reconstructs point response without persisting the accepted-increment macro tangent intentionally makes that tangent unavailable.
No independent external finite-strain plasticity structure benchmark has yet passed.
The exact Zhang--Feng--Khandelwal two-inclusion/one-void geometry now has a 2D Q2/DPC1 diagnostic execution with explicit primal/condensed energy decomposition, but no complete or content-bound Table 5 evidence has passed; the thin-3D P2/DG0 diagnostic remains a distinct formulation.
Plane stress, kinematic hardening, thermal coupling, damage and deletion are outside this first provider.
SENER separates algebraically into ELENER and HARDENER fields. Displacement-only ELENER is primal Hencky elastic energy; mixed ELENER is a condensed representation and is not automatically primal. PDENER is cumulative irrecoverable energy per reference volume and is excluded from SENER; MIXED_POTENTIAL is not physical storage. Complete external-work closure for follower, weak and contact loading remains provider-owned.
For a DPC mixed primary field, MEAN_KIRCHHOFF_STRESS remains exact in SimulationResult and portable checkpoints; XDMF contains the separately named DG0 recovery MEAN_KIRCHHOFF_STRESS_CELL rather than silently discarding higher cell moments.

Minimal example¶

material = constitutive.finite_strain_j2_logarithmic(young=210e3, poisson=0.3, yield_stress=250.0, hardening_modulus=1e3)

Verification¶

Tests

tests/test_finite_strain_plasticity.py
tests/test_finite_strain_j2_standard.py
tests/finite_strain_j2_mpi_driver.py
tests/portable_finite_strain_j2_driver.py
tests/test_finite_strain_j2_periodic.py
tests/test_finite_strain_j2_material_map.py
tests/test_affine_j2_automatic_restart.py
tests/portable_affine_j2_periodic_driver.py
tests/test_periodic_void_fixture.py
tests/parallel_periodic_void_j2_driver.py
tests/test_periodic_multi_void_fixture.py
tests/test_multi_void_rve_golden.py
tests/multi_void_rve_golden_driver.py
tests/multi_void_rve_restart_driver.py
tests/test_finite_strain_j2_mixed.py
tests/test_mixed_j2_energy_diagnostics.py
tests/test_zhang_2021_periodic_composite.py
tests/zhang_2021_plane_strain_driver.py
tests/test_lewandowski_2023_self_weight_beam.py
tests/lewandowski_2023_self_weight_beam_driver.py

Benchmarks

agentfem.benchmark.finite_strain_j2_material_paths
agentfem.benchmark.finite_strain_j2_periodic_void
agentfem.benchmark.finite_strain_j2_periodic_multi_void
agentfem.benchmark.finite_strain_j2_zhang_2021_table5
agentfem.benchmark.finite_strain_j2_lewandowski_2023_beam

Validation rules

Reject inverted total or plastic deformation gradients and non-isochoric committed plastic state.
Rigid rotation produces zero stress and a superposed rotation preserves the scalar history while rotating stress objectively.
Plastic paths preserve det(Fp)=1 and satisfy the updated yield surface.
Elastic unloading preserves history while a sufficiently large reverse path accumulates additional equivalent plastic strain.
Independent fixed-old-state perturbations accept the discrete tangent in elastic and plastic regimes.
The analytical spectral tangent and central-difference oracle agree after non-proportional plastic history; repeated principal stretches use the invariant spectral limit rather than an eigenvector-dependent quotient.
Batch failure restores every trial quadrature field and accepted batches commit atomically; scalar and vectorized native J2 updates agree in elastic, plastic and path-dependent states.
Serial one- and multi-element total-Lagrangian patches assemble P and dP/dF, reach a prescribed finite deformation, and reject/cut back an excessive PEEQ increment.
A two-rank global patch preserves shared assembly and uniform quadrature state.
Portable full-Step checkpoints resume equivalently after changing from two ranks to one and from one rank to two.
The public ordinary provider consumes nonlinear tabular amplitudes, remote displacement and reference body force, reports reaction balance and accepted integration-point fields, performs real cutback, and rolls back atomically when accepted-state finalization fails.
Unsupported nested periodic/MPC constraints, follower loads and weak boundary models fail closed instead of being discarded during strong-boundary lowering.
The public model.step affine-periodic cube matches the same accepted material-point path and records provider-owned F/P/S/MISES/SENER/ELENER/HARDENER/PDENER/FP/PEEQ fields plus Hill--Mandel evidence.
Material-point and public output tests verify SENER = ELENER + HARDENER and nonnegative monotone PDENER under plastic loading and rollback/restart.
An accepted public affine checkpoint restores displacement, quadrature state, accepted and attempted increment histories, the next adaptive increment, and execution evidence before continuing.
A mutated periodic-equation identity is rejected before any restored state is accepted.
Regional material dispatch shares one atomic trial/commit/rollback transaction and preserves scientific identity across one-to-two and two-to-one-rank portable restart.
A true spherical-void periodic RVE satisfies geometric pairing, positive-J, Hill--Mandel, public-lifecycle and two-rank execution contracts; its fixed-stack Golden and opt-in successive-refinement stability certificate remain separate evidence and do not constitute formal mesh convergence or GCI.
A deterministic four-void periodic RVE preserves realization, portable mesh and constraint identities; separates its h/L=0.16 Golden from three-level spatial-refinement and fixed-mesh 2/4/8-increment path certificates; and passes serial/two-rank and midpoint-restart equivalence without representing a stochastic porous-material ensemble.
The serial mixed P2/DG0 route assembles Kuu, Kup, Kpu and Kpp, passes homogeneous and heterogeneous affine cells, independently checks displacement and pressure residual-Jacobian directions, preserves non-affine fluctuations, distinguishes condensed mixed-energy output from MIXED_POTENTIAL, and restores split primary fields through a portable checkpoint.
A serial plane-strain Q2/DPC1 affine patch embeds F33=1, retains three pressure modes per quadrilateral, follows the same mixed transaction, reports max_q |ln(J_q)-p_h(q)/kappa| without reducing DPC1 to DG0, preserves the exact primary field in SimulationResult/checkpoint, writes only the explicit *_CELL recovery to XDMF, and fails closed for unsupported interpolation, dimension, conditioning, and parallel execution.
Aligned mixed J2 quadrature fields reproduce the primal-minus-condensed energy identity and report the signed gap, pressure-orthogonality, nonnegative pressure-constraint-defect, and decomposition-residual channels without treating decomposition as solver convergence.
The Zhang--Feng--Khandelwal Table 5 fixture remains fail-closed. One unarchived thin-3D P2/DG0 diagnostic passed the first-Piola vector-L2 threshold but failed the P11 and P22 componentwise checks; its condensed ELENER is not the published primal-energy observable, so that energy gate remained incomplete. The exact Q9/DPC1 driver now computes the effective tangent rather than accepting a missing placeholder, but no content-bound evidence archive exists and load-path, mesh/formulation, Table 5 comparison, cell-replication, MPI, and restart gates remain open.
The content-bound Lewandowski et al. self-weight beam candidate passes the independently reexecuted curve, observer reconciliation, mesh convergence, serial/MPI equivalence and full-state restart equivalence. Its 15-to-45-to-90 increment RMS passes and decreases, but the final-pair maximum is 0.6784 percent versus the fixed 0.5 percent contract, so the structure-level promotion remains fail-closed.

References¶

A model for finite strain elasto-plasticity based on logarithmic strains: Computational issues: https://doi.org/10.1016/0045-7825(92)90156-E
Algorithms for static and dynamic multiplicative plasticity that preserve the classical return mapping schemes of the infinitesimal theory: https://doi.org/10.1016/0045-7825(92)90123-2
MOOSE ComputeSimoHughesJ2PlasticityStress reference: https://mooseframework.inl.gov/source/materials/lagrangian/ComputeSimoHughesJ2PlasticityStress.html
Elastic properties of reinforced solids: Some theoretical principles: https://doi.org/10.1016/0022-5096(63)90036-X
Discrete averaging relations for micro to macro transition: https://doi.org/10.1115/1.4033552
A computational framework for homogenization and multiscale stability analyses of nonlinear periodic materials: https://doi.org/10.1002/nme.6802
Basix create_element and discontinuous DPC variant: https://docs.fenicsproject.org/basix/main/python/_autosummary/basix.finite_element.html

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

Stable ID: agentfem.material.finite_strain_plane_stress
Kind: material
Status: experimental
Source card: src/agentfem/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: src/agentfem/knowledge/cards/global_implicit_creep.json

Three-dimensional and two-dimensional axisymmetric small-strain Mises power-law creep with backward-Euler integration, a shared quadrature transaction, analytical consistent tangent, endpoint creep-rate error control, adaptive physical-time increments, shared temperature-dependent thermoelastic properties, scalar, field, or physical-time-history temperature input, atomic rollback, portable restart, work-energy evidence, regional materials, 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.histories.FieldHistory
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.

time-integration error indicator

\[ e_{cr}=\max_q\left|\dot{\bar\varepsilon}^{cr}_{q,n+1}-\dot{\bar\varepsilon}^{cr}_{q,n}\right|\Delta t \]

A declared creep_strain_error_tolerance may reject an otherwise converged increment independently of the equilibrium residual.

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 with constants or elastic=... to share E(T), nu(T), alpha(T), density and the 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. A procedure-specific endpoint creep-rate tolerance may control integration accuracy.
temperature	positive scalar, scalar finite-element field, or physical-time FieldHistory	absolute temperature in kelvin	Required for an Arrhenius material, sampled at attempted physical time, 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, integration-error, work and energy histories	structured histories and execution events	time, iterations, strain, and energy	Accepted times, maximum creep increment, endpoint creep-rate error estimate, local/global iterations, elastic energy, creep dissipation, natural-load work, prescribed-motion work, internal energy and mechanical residual.
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, either three spatial dimensions or a two-dimensional axisymmetric meridian, isotropic thermoelasticity, and associative Mises creep; a shared property asset may make the Arrhenius rate, E, nu and alpha temperature dependent.
Quasi-static equilibrium; inertia is not part of this procedure.
Each integration point resolves exactly one declared regional material.

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.
creep_strain_error_tolerance limits the endpoint creep-rate change times the physical increment and causes the same atomic rollback/cutback when exceeded.
Checkpoint restore reconstructs stress from accepted strain and CE without advancing a fictitious time increment.
A failed attempt restores the temperature history to the accepted increment start time together with displacement and quadrature state.
Result histories inherit the model's declared consistent time unit; without a unit declaration they remain explicitly unitless rather than being mislabeled as seconds.
Thermal-expansion tables are interpreted as mean/secant coefficients relative to the declared reference temperature.
The mechanical residual excludes prescribed thermal/material energy transfer and is not a full thermo-mechanical conservation error.

Applicability¶

Isothermal or prescribed-temperature three-dimensional or axisymmetric 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 MPI global Newton route has regional patch, rollback, and cross-rank-count restart evidence; the external NAFEMS R0027 structure benchmark currently exercises the native serial axisymmetric route rather than an independent distributed component model.
Portable nodal histories are root-gathered; global damage and mesh regularization are not part of this 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
tests/test_histories.py
tests/portable_field_history_driver.py

Benchmarks

agentfem.benchmark.implicit_creep_relaxation
agentfem.benchmark.arrhenius_global_creep
agentfem.benchmark.thermo_creep_shared_material
agentfem.benchmark.creep_nafems_r0027_test7

Validation rules

Reject unsupported dimensional assumptions, nonpositive duration, uncovered regional quadrature points, 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.
Keep equilibrium convergence and creep time-integration accuracy as separate acceptance decisions.
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
Abaqus VISCO procedure and CETOL definition: https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKEYRefMap/simakey-r-visco.htm

Global small-strain J2 plasticity¶

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

Three-dimensional and two-dimensional axisymmetric Mises plasticity with linear isotropic hardening, a shared quadrature transaction, analytical algorithmic tangent, cyclic amplitude paths, physical-increment cutback, portable restart, standard fields, and work/energy histories verified on homogeneous, nonuniform, and public thick-cylinder 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, either three spatial dimensions or a two-dimensional axisymmetric meridian.
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 or axisymmetric 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¶

There is no plane-stress local constraint, finite-strain plasticity, or kinematic hardening.
External-work histories are currently available for nonzero strong prescribed displacements; natural, weak, and affine-MPC work require separate verified definitions.
The public thick-cylinder route verifies first yield; cyclic hardening still requires an external structure-level benchmark.

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
agentfem.benchmark.j2_thick_cylinder_mpi

Validation rules

Reject unsupported dimensional assumptions and nonphysical material parameters.
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

Generalized-Maxwell linear viscoelastic material¶

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

Defines generalized-Maxwell/Prony constitutive response, exact material-point history, temperature shifting, and committed quadrature state for the engineering three-dimensional transient equilibrium route. Modal and direct harmonic solution procedures are owned separately by the solution-procedure contract.

Public API¶

agentfem.constitutive.GeneralizedMaxwell
agentfem.constitutive.IsotropicGeneralizedMaxwell
agentfem.constitutive.IsotropicHarmonicModuli
agentfem.constitutive.standard_linear_solid
agentfem.constitutive.WLFShift
agentfem.constitutive.ArrheniusShift
agentfem.constitutive.fit_relaxation_prony

Scientific contract¶

A generalized-Maxwell material owns the causal constitutive map and its branch history; a solution procedure owns modal or frequency-domain lowering. The material may supply storage and loss moduli to a harmonic procedure without owning that procedure.

relaxation modulus

\[ E(t)=E_{\infty}+\sum_{i=1}^{N}E_i\exp\!\left(-t/\tau_i\right) \]

The equilibrium modulus and positive relaxing branches define the instantaneous and long-time limits.

complex modulus

\[ E^{*}(\omega)=E_{\infty}+\sum_{i=1}^{N}E_i\frac{\mathrm{i}\omega\tau_i}{1+\mathrm{i}\omega\tau_i} \]

The constitutive spectrum supplies storage and loss moduli at angular frequency; frequency-domain equilibrium remains a separate procedure.

exact branch update

\[ q_i^{n+1}=\exp\!\left(-\Delta t/\tau_i\right)q_i^n+E_i\frac{\tau_i}{\Delta t}\left(1-\exp\!\left(-\Delta t/\tau_i\right)\right)\Delta\varepsilon \]

A linear strain path over one increment has an exact branch update and algorithmic modulus.

Inputs¶

Name	Type	Unit role	Meaning
relaxation spectrum	positive equilibrium modulus, branch moduli and relaxation times	stress and time	A Prony factory accepts instantaneous modulus and normalized relaxing ratios.
strain and temperature history	small-strain increments, accepted time path and optional shift-law temperature	strain, time and temperature	The material transaction evaluates trial branch state without mutating the last accepted state.

Outputs¶

Name	Type	Unit role	Meaning
constitutive response	relaxation modulus, storage/loss modulus, stress, algorithmic tangent and branch state	stress and time	Material-point response and committed branch state share one declared Prony spectrum and shift law.
global transient material state	quadrature stress, branch history, stored energy and viscous dissipation	stress and energy density	The engineering three-dimensional viscoelastic Step records accepted and rejected increments, rollback, restart, standard fields and a constitutive work--storage--dissipation ledger.
harmonic material coefficients	complex bulk and shear moduli	stress	These coefficients are constitutive inputs consumed by the separate direct harmonic procedure; their availability does not promote the material-specific global harmonic provider.

Assumptions¶

The generalized-Maxwell law is small-strain and thermorheologically simple when one shift law is supplied.
The global transient material route is currently three-dimensional and quasi-static.
Each accepted increment follows the declared linear strain interpolation used by the exact branch update.

Conventions¶

Storage and loss moduli consume angular frequency, not cyclic frequency.
Positive Prony ratios are fractions of the instantaneous modulus and must sum to less than one.
A nonzero initial strain declares either an instantaneous loading state or a fully equilibrated state; the material history never invents that past implicitly.
A trial material-point update does not modify accepted state until explicitly committed.
Constitutive work, stored energy and viscous dissipation are retained as distinct channels.

Applicability¶

Material-point relaxation, storage/loss spectra and temperature-shift studies for small-strain linear viscoelasticity.
Three-dimensional small-strain quasi-static generalized-Maxwell loading and relaxation on prescribed or automatically controlled physical-time paths.
Supplying isotropic storage and loss coefficients to a separately selected frequency-domain procedure.

Limitations¶

The engineering time-domain global provider supports 3D solids, strong constraints, prescribed or adaptive physical-time paths and physical-keyed portable restart.
The generalized-Maxwell global harmonic provider remains experimental; the engineering maturity of the generic direct harmonic procedure and its elastic NAFEMS Test 5H comparison do not validate this material coupling.
The current material-specific harmonic route is limited to one 3D isotropic material, uniform temperature, homogeneous strong constraints and one common load phase.
Nonlinear viscoelasticity, finite strain and physical aging are not implemented.
Fixed-spectrum fitting does not automatically choose relaxation times or replace calibration/validation separation.

Minimal example¶

material = constitutive.IsotropicGeneralizedMaxwell.from_prony(...); model.material(material); result = model.step(target=u, duration=..., time_points=(...)).solve_result()

Verification¶

Tests

tests/test_viscoelasticity.py
tests/test_parallel_viscoelasticity.py
tests/portable_viscoelastic_step_driver.py

Benchmarks

agentfem.benchmark.linear_viscoelastic_spectrum
agentfem.benchmark.global_viscoelastic_relaxation
agentfem.benchmark.global_viscoelastic_harmonic_bar
agentfem.benchmark.abaqus_viscoelastic_rod

Validation rules

Require positive moduli and relaxation times, and Prony ratios summing to less than one.
Recover the closed-form relaxation modulus from an instantaneous initial state under constant strain.
Reject singular or non-finite time-temperature shift factors before updating material state.
Separate trial and committed branch state and preserve rollback equivalence.
Require restarted material histories to match the accepted initial strain and branch layout, and close independently integrated work against stored energy plus dissipation.
Require the global 3D ramp--hold patch to match the exact generalized-Maxwell stress after both the ramp and hold.
Require split and uninterrupted global paths to preserve displacement, stress, committed branch state and energy history.
Estimate adaptive physical-time error by comparing one full increment with two half increments in displacement and quadrature stress, and accept only the finer state.
Reject an increment whose estimated time error exceeds the declared tolerance, restore displacement and all quadrature history atomically, and retry from the same accepted time with a smaller increment.
Require generalized-Maxwell displacement, committed branch state, stress and energy history to remain equivalent across one-to-two and two-to-one-rank portable restart.
Require a nonuniform-grid, traction-controlled three-dimensional rod to match the published Abaqus short- and long-time axial strains and effective Poisson ratio.
Require the material-specific harmonic bar to recover analytical complex compliance and positive cycle loss while retaining experimental global-provider maturity.

References¶

Abaqus time-domain viscoelastic rod benchmark: https://docs.software.vt.edu/abaqusv2025/English/SIMACAEBMKRefMap/simabmk-c-viscorod.htm
Abaqus frequency-domain viscoelasticity: https://docs.software.vt.edu/abaqusv2025/English/SIMACAETHERefMap/simathe-c-freqdomainvisco.htm
Van Houten et al. (2023), closed-form one-dimensional viscoelastic wave boundary-value problem: https://doi.org/10.1002/cnm.3741

Constant-pressure mixed Neo-Hookean solid¶

Stable ID: agentfem.material.mixed_hybrid_hyperelasticity
Kind: material
Status: supported
Source card: src/agentfem/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: src/agentfem/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_{\mathrm{I}}^{\mathrm{coh}}=\frac{1}{2}K_n\langle\delta_n\rangle_{+}^{2},\qquad G_{\mathrm{II}}^{\mathrm{coh}}=\frac{1}{2}K_t\lVert\boldsymbol{\delta}_t\rVert^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_{\mathrm{I}c}+(G_{\mathrm{II}c}-G_{\mathrm{I}c})\beta^{\eta},\qquad \beta=\frac{\Delta G_{\mathrm{II}}}{\Delta G_{\mathrm{I}}+\Delta G_{\mathrm{II}}} \]

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

reference cyclic evolution

\[ \frac{\mathrm{d}D_f}{\mathrm{d}N}=C\left\langle\overline{\Delta G}\right\rangle_{+}^{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_{\mathrm{path}}=\sum_s I_s\frac{\left\langle\Delta G_s-G_{\mathrm{th}}(\beta_s)\right\rangle_{+}}{G_c(\beta_s)-G_{\mathrm{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: src/agentfem/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

Solver-neutral finite-strain user-material contract¶

Stable ID: agentfem.material.solver_neutral_user_material_contract
Kind: material
Status: contract_only
Source card: src/agentfem/knowledge/cards/solver_neutral_user_material_contract.json

Defines versioned named internal variables and explicit stress/kinematic tangent conventions shared by native materials and future industrial adapters, with a fail-closed validated update boundary before global Newton integration.

Public API¶

agentfem.constitutive.MaterialPointInput
agentfem.constitutive.MaterialPointOutput
agentfem.constitutive.MaterialQuadratureState
agentfem.constitutive.MaterialStateVariable
agentfem.constitutive.MaterialStateSchema
agentfem.constitutive.MaterialTangentConvention
agentfem.constitutive.MaterialTangentCheck
agentfem.constitutive.UserMaterial
agentfem.constitutive.check_material_tangent
agentfem.constitutive.validated_material_update

Scientific contract¶

A constitutive Jacobian is usable by a nonlinear finite-element driver only when its stress measure, conjugate kinematic perturbation, configuration, storage, component order, shear convention and objective-rate convention are explicit and its internal state has a stable versioned identity.

total-Lagrangian tangent

\[ \mathbb A=\partial\mathbf P/\partial\mathbf F \]

A native first-Piola/deformation-gradient provider declares all nine components in the reference configuration.

Abaqus UMAT spatial Jacobian

\[ \mathbf C=\frac{1}{J}\frac{\partial\,\Delta(J\boldsymbol\sigma)}{\partial\,\Delta\boldsymbol\epsilon} \]

This adapter convention includes Abaqus component, engineering-shear, rotating-basis and objective-update semantics and is not relabeled as a total-Lagrangian tangent.

Inputs¶

Name	Type	Unit role	Meaning
MaterialPointInput	old/new deformation gradients, time, properties, typed old state and optional thermal/field data	provider-declared consistent units	Both deformation gradients must be finite with positive determinant.
UserMaterial declarations	name, MaterialStateSchema and MaterialTangentConvention	metadata and state units	The declarations are stable properties of the provider rather than values inferred from returned array shapes; tensor states may declare a full physical initial value such as an identity tensor.

Outputs¶

Name	Type	Unit role	Meaning
MaterialPointOutput	Cauchy stress, declared consistent tangent, typed new state, optional energy and suggested time scale	stress, tangent, state and energy density	Global-Newton eligibility is explicit and false for undeclared legacy outputs.
MaterialQuadratureState	schema-lowered committed/trial integration-point fields	per-variable declared units	Scalar and tensor state initialization, aliases and full schema identity remain attached to portable checkpoint storage.
MaterialTangentCheck	fixed-old-state numerical differentiation evidence	dimensionless relative error and tangent units for absolute error	Compares a declared first-Piola/deformation-gradient Jacobian against perturbations of all nine new-deformation-gradient components.

Assumptions¶

One adapter is responsible for mapping its source convention into the declared neutral contract.
The global finite-element consumer uses the same declared tangent convention or performs a separately verified transformation.

Conventions¶

State schema identity combines a stable name and version.
First-Piola/deformation-gradient and second-Piola/Green--Lagrange tangents are reference-configuration conventions.
Cauchy or Kirchhoff rate tangents are current-configuration conventions and must declare an objective rate.

Applicability¶

Native or adapted three-dimensional finite-strain material-point providers entering a future quadrature/global-Newton driver.

Limitations¶

The contract does not itself compile or execute arbitrary UMAT or UHYPER source.
MaterialQuadratureState owns storage and atomic lifecycle, not a constitutive integration algorithm or global residual.
Direct numerical tangent checking currently applies to first-Piola/deformation-gradient 9x9 tangents; spatial UMAT tangents require a verified transformation.
No finite-strain inelastic material is promoted until material paths, tangent checks, global cutback/restart, MPI identity and an external benchmark pass.

Minimal example¶

response = constitutive.validated_material_update(material, point)

Verification¶

Tests

tests/test_user_material.py
tests/test_user_material_inspection.py

Benchmarks

None declared.

Validation rules

Reject invalid deformation gradients, nonfinite state and mismatched state size.
Reject tensor initial values whose shape differs from the declared state variable shape.
Reject spatial rate tangents without an objective-rate declaration.
Reject array shapes inconsistent with the declared tangent storage.
Reject state-schema or tangent-convention drift across one material update.
Reject incompatible material schemas during portable checkpoint restore.
Exercise schema-driven state in the existing two-rank-write to one-rank-read acceptance driver.
Reject an incorrect first-Piola tangent and retain the numerical relative-error evidence.
Keep undeclared legacy outputs ineligible for global Newton consumption.

References¶

Abaqus 2025 UMAT reference: https://docs.software.vt.edu/abaqusv2025/English/SIMACAESUBRefMap/simasub-c-umat.htm
Numerical computation of algorithmic consistent tangent moduli in large-strain computational inelasticity: https://doi.org/10.1016/0045-7825(96)01019-5

Biharmonic split operators and boundary closure¶

Stable ID: agentfem.operator.biharmonic_split
Kind: operator
Status: supported
Source card: src/agentfem/knowledge/cards/biharmonic_split_operators.json

Represents a fourth-order scalar equation through two inspectable second-order Laplacian blocks and keeps the auxiliary boundary closure explicit.

Public API¶

agentfem.operators.split_laplacian_operator
agentfem.operators.auxiliary_laplacian_boundary

Scientific contract¶

A mixed second-order split avoids silently requiring a high-continuity primary element, but it does not remove the need to declare a second boundary condition.

biharmonic equation

\[ \Delta^2u=f \]

The scalar fourth-order balance.

two-field split

\[ w=-\Delta u,\qquad-\Delta w=f \]

Each block uses the public scalar Laplacian weak form.

derived public boundary closure

\[ u=g,\qquad w=-\Delta g\quad\text{on }\partial\Omega \]

This closure is valid only when the supplied expression g defines the intended spatial extension; it is recorded rather than inferred from reference data.

Inputs¶

Name	Type	Unit role	Meaning
primary and auxiliary scalar fields	Lagrange unknowns	split state	The auxiliary field carries minus the primary Laplacian.
auxiliary boundary condition	declared or derived scalar expression	second boundary condition	Completes the fourth-order boundary-value problem.

Outputs¶

Name	Type	Unit role	Meaning
split Laplacian block	OperatorForm	second-order weak operator	Reusable matrix contribution for either primary or auxiliary solve.

Assumptions¶

The chosen two-field closure represents the intended fourth-order boundary conditions.
The supplied primary boundary expression is differentiable when its Laplacian is used.
A spatially constant primary boundary has zero auxiliary Laplacian.

Conventions¶

The auxiliary variable is w equals minus Laplacian u.
Boundary closure is attached to solver evidence.
Hidden manufactured solutions are never valid sources of auxiliary data.

Applicability¶

Scalar biharmonic verification problems and reusable mixed second-order prototypes with explicitly reviewed boundary semantics.

Limitations¶

This operator card does not define every clamped, simply supported, free, or plate-theory boundary pair.
The current benchmark consumer performs sequential Poisson solves rather than a monolithic block solve.

Minimal example¶

Define w = -laplacian(u); solve split_laplacian_operator(w, q) = f*q and then split_laplacian_operator(u, v) = w*v with an explicit auxiliary boundary condition.

Verification¶

Tests

tests/test_operators.py
tests/test_pdeagent_bench.py

Benchmarks

agentfem.benchmark.pdeagent_bench_eleven_family

Validation rules

Reject a split benchmark case without one public primary boundary expression.
Record the auxiliary boundary closure in solver_info.
Test both spatially varying and constant public boundary expressions.

References¶

UFL form language manual: https://docs.fenicsproject.org/ufl/main/manual/form_language.html
PDEAgent-Bench public repository: https://github.com/YusanX/pde-agent-bench

Linear elastic foundation reaction and energy ownership¶

Stable ID: agentfem.operator.elastic_foundation_reaction
Kind: operator
Status: supported
Source card: src/agentfem/knowledge/cards/elastic_foundation_reaction.json

Adds an isotropic, normal, or conservative matrix spring-to-ground boundary operator and publishes its distributed reaction without double-counting stored energy.

Public API¶

agentfem.boundary_models.elastic_foundation
agentfem.boundary_models.ElasticFoundation
agentfem.models.Model.elastic_foundation

Scientific contract¶

A linear elastic foundation is a conservative weak boundary operator whose force on the solid opposes displacement; its reaction closes global force balance while its recoverable energy remains part of the assembled system strain energy.

isotropic foundation traction

\[ \mathbf{t}_{f}=-k\mathbf{u} \]

The foundation force per reference boundary measure opposes every displacement component.

normal foundation traction

\[ \mathbf{t}_{f}=-k(\mathbf{u}\cdot\mathbf{n})\mathbf{n} \]

Normal mode retains only the displacement along the declared reference-boundary normal.

matrix foundation traction

\[ \mathbf{t}_{f}=-\mathbf{K}\mathbf{u},\qquad \mathbf{K}=\mathbf{K}^{T}\succeq 0 \]

Matrix mode permits directional coupling while symmetry and positive semidefiniteness retain a conservative nonnegative energy.

weak stiffness and stored energy

\[ a_f(\mathbf{u},\mathbf{v})=\int_{\Gamma_f}k\mathbf{u}\cdot\mathbf{v}\,d\Gamma,\qquad U_f=\tfrac{1}{2}a_f(\mathbf{u},\mathbf{u}) \]

The same reviewed operator supplies tangent stiffness, nodal reaction recovery, and conservative stored energy.

Inputs¶

Name	Type	Unit role	Meaning
foundation boundary, stiffness, and mode	BoundaryRegion, nonnegative scalar or symmetric positive-semidefinite matrix, and isotropic/normal/matrix selector	force per boundary measure per displacement	The boundary measure determines whether stiffness is interpreted per unit length or area in the selected consistent unit system.

Outputs¶

Name	Type	Unit role	Meaning
foundation operator and dual evidence	OperatorForm, ConstraintDualEvidence, and nodal reaction field	stiffness, force, and energy	The result carries the MPI-global resultant, nodal support reaction, and foundation stored energy ownership.

Assumptions¶

The current provider is linear, conservative, and attached to fixed ground.
The reaction/energy evidence route is verified for linear-static vector solid fields.
Normal mode uses the reference-boundary normal supplied by the mesh or caller.
Matrix mode is expressed in model coordinates and must match the displacement dimension.

Conventions¶

Positive stiffness enters the left-hand-side operator; the reported support reaction on the solid is its negative action.
Foundation stored energy is included in total system strain energy and contributes no separate prescribed-motion work.
The full nodal reaction remains a field artifact while JSON retains compact resultant, norm, energy, and provenance evidence.

Applicability¶

Small-strain linear-static solids with isotropic or reference-normal spring support in serial or MPI.

Limitations¶

Nonlinear force-displacement laws, predeformation, moving normals, damping, finite-strain foundations, and pair/contact layers require separate providers.
Spatially rotating local matrix coordinates require a separate oriented-boundary provider.

Minimal example¶

support = mesh.boundary(domain, left, name='support')
model.elastic_foundation(on=support, stiffness=5.0e6, mode='isotropic')
result = model.step(target=displacement).solve_result(output='foundation.xdmf')

Verification¶

Tests

tests/test_engineering_workflows.py
tests/test_parallel_affine.py
tests/test_results.py

Benchmarks

agentfem.benchmark.elasticity_foundation

Validation rules

Reject negative stiffness and missing boundary regions.
Reject non-square, dimension-mismatched, asymmetric, or indefinite numerical matrix stiffness.
Recover the applied boundary resultant from the distributed foundation reaction.
Require serial and two-rank force balance at numerical tolerance.
Require proportional linear work closure without adding foundation energy twice.
Retain the provider-owned nodal reaction distribution in SimulationResult.
Write the nodal reaction beside displacement and stress in the ordinary single-grid XDMF/HDF5 result.

References¶

Abaqus Element Foundations: https://docs.software.vt.edu/abaqusv2025/English/SIMACAEMODRefMap/simamod-c-foundation.htm
COMSOL Elastic Energy: https://doc.comsol.com/6.4/doc/com.comsol.help.sme/sme_ug_theory.06.125.html
COMSOL Spring Foundation and Thin Elastic Layer: https://doc.comsol.com/6.4/doc/com.comsol.help.sme/sme_ug_theory.06.068.html

Neighbor-reconstructed fibre curvature¶

Stable ID: agentfem.operator.fibrous_shell_curvature_reconstruction
Kind: operator
Status: experimental
Source card: src/agentfem/knowledge/cards/fibrous_shell_curvature_reconstruction.json

Reconstructs a three-dimensional unit-fibre direction gradient on a two-dimensional parameter mesh, then separates signed in-plane and normal fibre curvature with rank, conditioning, objectivity and mesh-convergence evidence.

Public API¶

agentfem.mechanics.ReconstructedFiberCurvature
agentfem.mechanics.reconstruct_fiber_curvature

Scientific contract¶

The material directional derivative of a unit fibre is reconstructed from a ghost-complete cell neighborhood and decomposed along the in-surface normal-to-fibre direction and the surface normal; it is a discrete kinematic input, not yet shell equilibrium.

fibre curvature components

\[ \kappa_g=(\nabla_s\mathbf{a})\mathbf{a}\cdot(\mathbf{n}\times\mathbf{a}),\qquad \kappa_n=(\nabla_s\mathbf{a})\mathbf{a}\cdot\mathbf{n} \]

The derivative component parallel to the unit fibre is removed before the signed decomposition.

Inputs¶

Name	Type	Unit role	Meaning
cell fibre directions and surface tangents	one 3-vector and one 3x2 tangent matrix per local/ghost cell	dimensionless direction and current surface geometry	The first adapter consumes a two-dimensional parameter mesh and requires synchronized ghost values.

Outputs¶

Name	Type	Unit role	Meaning
reconstructed fibre curvature	owned-cell direction gradients, in-plane curvature, normal curvature and reconstruction evidence	inverse length	Neighbor count, rank and condition number remain attached to the reported kinematics.

Assumptions¶

The current fibre direction is nonzero, unit-normalizable and tangent to the supplied current surface.
The local cell-neighbor stencil spans the two-dimensional parameter domain with acceptable conditioning.

Conventions¶

Positive in-plane curvature is along surface-normal cross fibre; positive normal curvature is along the surface normal.
The first adapter is defined on a 2D parameter mesh with 3D physical fibre and tangent data.

Applicability¶

Rotation-free fibrous-shell patch studies and future neighboring-element forming operators.

Limitations¶

No bending energy, virtual work, boundary moment, nonlinear equilibrium or shell Step is provided yet.
Direct reconstruction on arbitrary two-manifolds embedded as three-dimensional mesh coordinates remains a separate gate.
Cell-center reconstruction must be converged for the field and mesh family used by a scientific claim.

Minimal example¶

curvature = mechanics.reconstruct_fiber_curvature(domain, cell_directions, cell_tangents)

Verification¶

Tests

tests/test_fibrous_shell_reconstruction.py
tests/test_mesh_neighborhood.py
tests/test_parallel_mesh_semantics.py

Benchmarks

None declared.

Validation rules

Preserve in-plane and normal curvature under an arbitrary superposed three-dimensional rigid rotation.
Keep normal curvature at zero for an in-plane rotating fibre field.
For the smooth field a=(cos(0.8x), sin(0.8x), 0), reduce relative in-plane-curvature error from approximately 1.50e-2 to 3.86e-3 to 9.75e-4 on 4x4, 8x8 and 16x16 quadrilateral meshes.
On two MPI ranks, retain ghost-complete reconstruction of a nonlinear rotating fibre field across the partition interface.
Reject unsupported mesh-coordinate contracts and rank-deficient or ill-conditioned reconstruction stencils.

References¶

Bai et al. (2024), Influence of in-plane bending behaviour on textile composite reinforcement forming: https://doi.org/10.1016/j.ijmecsci.2024.109206
Steer et al. (2021), Modeling and analysis of in-plane bending in fibrous reinforcements with rotation-free shell finite elements: https://doi.org/10.1016/j.ijsolstr.2021.03.001

Mixed incompressible-flow fields and operators¶

Stable ID: agentfem.operator.incompressible_flow
Kind: operator
Status: supported
Source card: src/agentfem/knowledge/cards/incompressible_flow_operators.json

Provides an explicit Taylor--Hood velocity/pressure unknown and composable viscous, pressure, incompressibility, and momentum-convection operators for Stokes and Navier--Stokes workflows.

Public API¶

agentfem.fields.velocity_pressure
agentfem.spaces.velocity_pressure_space
agentfem.operators.viscous_flow_operator
agentfem.operators.pressure_coupling_operator
agentfem.operators.incompressibility_operator
agentfem.operators.convective_momentum_operator

Scientific contract¶

Velocity/pressure stability, pressure reference semantics, and momentum terms remain explicit scientific choices rather than consequences of the mesh or solver backend.

steady incompressible momentum

\[ -\nu\Delta\boldsymbol{u}+(\boldsymbol{u}\cdot\nabla)\boldsymbol{u}+\nabla p=\boldsymbol{f} \]

Removing the convective term gives the Stokes momentum balance.

incompressibility

\[ \nabla\cdot\boldsymbol{u}=0 \]

The pressure test field enforces the divergence constraint in the mixed weak form.

Inputs¶

Name	Type	Unit role	Meaning
velocity and pressure degrees	integer pair	discretization	Taylor--Hood requires the conforming velocity degree to exceed the pressure degree.
viscosity	positive scalar or coefficient	kinematic viscosity in the normalized benchmark form	Weights the viscous gradient term.

Outputs¶

Name	Type	Unit role	Meaning
velocity_pressure unknown	VelocityPressureUnknown	mixed primary state	Owns one mixed function and inspectable velocity and pressure subfields.
flow operators	OperatorForm	weak momentum and continuity contributions	Composable terms suitable for linear Stokes systems or differentiated nonlinear residuals.

Assumptions¶

The public mixed space is a conforming Taylor--Hood pair.
A fully velocity-Dirichlet problem needs a pressure reference or equivalent nullspace treatment.
The current operators express constant-density incompressible flow.

Conventions¶

Pressure enters momentum as minus p times div(v).
The continuity block uses minus q times div(u), yielding a symmetric Stokes saddle-point sign convention.
Momentum convection is represented as the advecting velocity dotted with the gradient of the transported velocity.

Applicability¶

Steady Stokes and steady incompressible Navier--Stokes formulations with explicit boundary and pressure-reference policies.

Limitations¶

No general turbulent closure, transient flow procedure, equal-order stabilization, or automatic pressure-nullspace object is claimed.
The PDEAgent-Bench adapter currently uses a direct mixed solve and a Stokes-initialized Newton route; these are consumers, not the only possible solvers.

Minimal example¶

Create vp = fields.velocity_pressure(domain); compose viscous_flow_operator, pressure_coupling_operator, and incompressibility_operator; add convective_momentum_operator to a Navier--Stokes residual.

Verification¶

Tests

tests/test_operators.py
tests/test_pdeagent_bench.py

Benchmarks

agentfem.benchmark.pdeagent_bench_eleven_family

Validation rules

Reject Taylor--Hood degree pairs whose velocity order does not exceed pressure order.
Keep pressure reference or natural-pressure semantics in solver evidence.
Never initialize from a withheld manufactured solution or case-identity table.

References¶

DOLFINx mixed Poisson demo and mixed-space conventions: https://docs.fenicsproject.org/dolfinx/main/python/demos/demo_mixed-poisson.html
UFL form language manual: https://docs.fenicsproject.org/ufl/main/manual/form_language.html

Scalar transport and reaction operators¶

Stable ID: agentfem.operator.scalar_transport_reaction
Kind: operator
Status: supported
Source card: src/agentfem/knowledge/cards/scalar_transport_reaction.json

Provides inspectable advection, scalar Burgers convection, streamline-upwind stabilization, and named scalar reaction laws for reusable transport and reaction--diffusion workflows.

Public API¶

agentfem.operators.advection_operator
agentfem.operators.burgers_convection_operator
agentfem.operators.streamline_upwind_operator
agentfem.operators.intrinsic_time_scale
agentfem.operators.reaction_expression

Scientific contract¶

Transport and reaction semantics remain named public operators while UFL supplies the executable weak form and differentiation.

multidimensional scalar Burgers transport

\[ ∂_t u+u\,\boldsymbol{1}\cdot\nabla u-\nu\Delta u=f \]

The default public direction differentiates the transported scalar along every spatial axis; a caller may supply an explicit direction for a reduced model.

advection--diffusion--reaction

\[ \partial_t u-\nabla\cdot(\varepsilon\nabla u)+\boldsymbol{\beta}\cdot\nabla u+r(u)=f \]

Diffusion, directed transport, and local reaction remain independently inspectable contributions.

streamline-upwind contribution

\[ \int_{\Omega}\tau R(u)\,\boldsymbol{\beta}\cdot\nabla w\,\mathrm{d}\Omega \]

SUPG weights the strong residual in the streamline test direction.

advective intrinsic scale

\[ \tau=\frac{h}{2\lVert\boldsymbol{\beta}\rVert} \]

The first public policy uses the cellwise advective scale and rejects zero velocity.

Inputs¶

Name	Type	Unit role	Meaning
velocity	numeric vector or UFL vector	length/time	Advection direction and magnitude.
reaction law	named mapping	field/time	Linear, cubic, Allen--Cahn, or logistic local reaction parameters.
strong residual	UFL scalar expression	balance residual	Complete equation residual supplied to streamline stabilization.

Outputs¶

Name	Type	Unit role	Meaning
transport operator	OperatorForm	weak balance	Composable UFL form with family, method, and velocity metadata.
reaction expression	UFL scalar expression	field/time	Local nonlinear term suitable for residual construction and automatic differentiation.

Assumptions¶

The current intrinsic scale is the advective cell scale, not a universal transient or diffusion-aware stabilization policy.
Named reaction parameters use a unit-consistent model chosen by the caller.
SUPG requires the caller to provide the complete strong residual appropriate to the time discretization.

Conventions¶

Reaction laws enter the balance with a positive residual sign.
Allen--Cahn is represented as lambda times (u cubed minus u).
Logistic reaction is represented as rho times u times (1 minus u).

Applicability¶

Steady and transient scalar advection--diffusion, reaction--diffusion, phase-like scalar kinetics, and externally defined transport workflows.

Limitations¶

No discontinuity-capturing or shock limiter is included.
The scalar operators do not define mixed flow, species coupling, or automatic stabilization selection.
Symbolic velocity metadata are recorded as an inspectable expression string rather than reconstructed as numeric components.

Minimal example¶

Create A = operators.advection_operator(u, v, beta); add operators.streamline_upwind_operator(R, v, beta, domain=domain) when the declared transport policy requires SUPG.

Verification¶

Tests

tests/test_operators.py
tests/test_pdeagent_bench.py

Benchmarks

agentfem.benchmark.pdeagent_bench_scalar_seven_family
agentfem.benchmark.pdeagent_bench_eleven_family

Validation rules

Reject a zero numeric advection velocity when constructing the advective intrinsic time scale.
Reject unknown named reaction laws.
Keep official benchmark oracle data outside the adapter and regression tests.

References¶

Streamline upwind/Petrov-Galerkin formulations for convection dominated flows: https://doi.org/10.1016/0045-7825(82)90071-8
UFL form language manual: https://docs.fenicsproject.org/ufl/main/manual/form_language.html

Finite-element operator and system contracts¶

Stable ID: agentfem.operator.system_contracts
Kind: operator
Status: supported
Source card: src/agentfem/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

Norm-aware discrete inf-sup evidence¶

Stable ID: agentfem.verification.discrete_inf_sup_evidence
Kind: operator
Status: experimental
Source card: src/agentfem/knowledge/cards/discrete_inf_sup_evidence.json

Computes a basis-invariant normalized singular spectrum for one mixed constraint operator and audits a declared coarse-to-fine sequence without relabeling isolated full-rank matrices as mesh-independent stability.

Public API¶

agentfem.diagnostics.DiscreteInfSupEvidence
agentfem.diagnostics.DiscreteInfSupSample
agentfem.diagnostics.DiscreteInfSupStudy
agentfem.diagnostics.discrete_inf_sup

Scientific contract¶

A mixed coupling matrix must be measured in declared primal and multiplier norms; raw singular values depend on bases and units and cannot establish the discrete Babuška--Brezzi condition.

normalized discrete inf-sup value

\[ \beta_h=\sigma_{min}(\mathbf{L}_{\lambda}^{-1}\mathbf{B}\mathbf{L}_{u}^{-T}),\qquad \mathbf{M}_{u}=\mathbf{L}_{u}\mathbf{L}_{u}^{T},\quad \mathbf{M}_{\lambda}=\mathbf{L}_{\lambda}\mathbf{L}_{\lambda}^{T} \]

The Cholesky factors encode the declared discrete norms and make the spectrum invariant to consistent nonsingular basis changes.

Inputs¶

Name	Type	Unit role	Meaning
coupling and norm matrices	finite B, symmetric positive-definite M_u and M_lambda	operator and matching primal/multiplier norms	Rows are multiplier equations and columns are primal unknowns after the caller's essential-boundary and nullspace policy.

Outputs¶

Name	Type	Unit role	Meaning
discrete inf-sup evidence	normalized singular values, beta, numerical rank, full-row-rank flag and condition number	dimensionless when compatible norms are supplied	A study additionally records at least three coarse-to-fine samples, minimum beta, beta range ratio, endpoint decay order and a caller-declared verification claim.

Assumptions¶

The supplied norm matrices are symmetric positive definite on the tested discrete spaces.
Essential constraints and physical nullspaces have been treated consistently before matrix extraction.

Conventions¶

constraint_matrix has multiplier equations by primal unknowns.
Rank tolerance defaults to the standard matrix-size-scaled floating-point SVD threshold.

Applicability¶

Mixed shell, hybrid solid, incompressible flow, multiplier constraint and other saddle-point discretization studies.

Limitations¶

The first implementation consumes dense serial arrays; PETSc/MPI extraction and scalable extremal singular solvers are future adapters.
A finite sequence satisfying a declared lower bound is evidence for that tested family and range; it is not a universal proof or evidence of absence of locking.
An inappropriate norm or untreated nullspace can make a numerically correct spectrum scientifically irrelevant.

Minimal example¶

sample = diagnostics.DiscreteInfSupSample(h, diagnostics.discrete_inf_sup(B, primal_norm=M_u, multiplier_norm=M_lambda)); study = diagnostics.DiscreteInfSupStudy('mixed family', (coarse, medium, fine))

Verification¶

Tests

tests/test_mixed_stability.py

Benchmarks

None declared.

Validation rules

Verify the reported beta, rank and condition number against a diagonal analytical spectrum.
Verify spectrum invariance under arbitrary nonsingular primal and multiplier basis transformations with consistently transformed norms.
Return beta zero for a rank-deficient multiplier space and reject non-SPD norm matrices.
Require at least three strictly coarse-to-fine samples and distinguish a bounded sequence from a beta value that decays as a positive power of mesh size.

References¶

Bathe et al. (2000), An inf-sup test for shell finite elements: https://doi.org/10.1016/S0045-7949(99)00213-8
Pinsky and Jasti (1991), Lagrange multiplier compatible modes for mixed shell finite elements: https://doi.org/10.1016/0045-7825(91)90131-O

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

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

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

Public API¶

agentfem.mesh.read_abaqus_mesh
agentfem.mesh.abaqus.AbaqusMeshImport.node_set
agentfem.mesh.abaqus.AbaqusMeshImport.element_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, CellRegion, or BoundaryRegion	source-node coordinate region, tagged cells, 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.
ELSET becomes a material-ready cell region only when its converted tag owns every source element in the set.
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'); steel = cell.element_set('STEEL'); loaded = cell.boundary('LOAD_FACE')

Verification¶

Tests

tests/test_abaqus_interop.py
tests/test_abaqus_migration.py

Benchmarks

None declared.

Validation rules

Recover every requested source node or fail with missing labels.
Reject a converted ELSET tag that owns fewer cells than the preserved source set.
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

Reviewed Abaqus model and user-material migration¶

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

Preserves an Abaqus source graph, assesses a deliberately bounded native subset, records reviewer and unit decisions, lowers an equivalent final linear-static state, and inventories UMAT/UHYPER sources without claiming arbitrary solver compatibility.

Public API¶

agentfem.mesh.plan_abaqus_migration
agentfem.mesh.assess_abaqus_native_lowering
agentfem.mesh.lower_abaqus_migration_project
agentfem.constitutive.user_material.inspect_abaqus_user_material

Scientific contract¶

A migrated model is executable only when every consumed Abaqus declaration has an explicit AgentFEM meaning. For a single geometrically linear static Step, the final equilibrium state depends on the end magnitudes of prescribed data, so a supported relative tabular amplitude may be evaluated at Step end while its complete source history remains evidence.

final linear-static amplitude lowering

\[ \mathbf{K}\mathbf{u}_{\mathrm{end}}=a(t_{\mathrm{end}})\mathbf{f}_{\mathrm{ref}} \]

Only the final linear equilibrium state is lowered; intermediate Abaqus increments are not reproduced by this route.

Inputs¶

Name	Type	Unit role	Meaning
Abaqus source graph	include-resolved input deck plus optional Fortran user-material source	reviewer-declared consistent unit system	Every copied source file and separately inspected user-material file retains a content fingerprint.

Outputs¶

Name	Type	Unit role	Meaning
Reviewed native draft and decision evidence	case.native.py, lowering.json, derived orphan mesh, and optional user-material inspection JSON	same consistent source units	Reference values, amplitude history, final multipliers, material assignments, source locations, reviewer, and limitations remain inspectable.

Assumptions¶

The native route contains exactly one geometrically linear static Step.
Supported amplitudes are named relative tabular histories in Step time or total time.
The final state is a linear equilibrium problem, so the supported amplitude path has no history-dependent constitutive effect.

Conventions¶

Migration planning, reviewed native lowering, and user-material execution are separate gates.
An adapter-candidate UMAT/UHYPER inspection is never reported as executable.
Unsupported or ambiguous declarations produce stable findings instead of inferred behavior.

Applicability¶

Selected Abaqus solid models within the documented native linear-static subset.
Fortran UMAT/UHYPER source inventory before restricted adapter development.

Limitations¶

No arbitrary Abaqus deck execution or solver-equivalence claim.
No nonlinear, history-dependent, multi-Step, absolute, or non-tabular amplitude lowering.
User-material inspection does not compile, link, or execute Fortran code.

Minimal example¶

agentfem inspect-abaqus model.inp --json; agentfem migrate-abaqus model.inp migrated --json; agentfem lower-abaqus migrated --reviewed-by REVIEWER --unit-system SI --json; agentfem inspect-user-material material.for --json

Verification¶

Tests

tests/test_abaqus_migration.py
tests/test_user_material_inspection.py
tests/test_project_cli.py

Benchmarks

None declared.

Validation rules

Reject source mutation after migration planning.
Reject missing, duplicate, non-relative, non-tabular, nonfinite, or nonmonotone amplitude definitions.
Retain reference and final magnitudes plus the complete amplitude table in lowering evidence.
Reject user-material sources with an ambiguous entry point or unresolved Abaqus utility calls from the automatic adapter-candidate route.

References¶

Abaqus amplitude commands and time spans: https://docs.software.vt.edu/abaqusv2025/English/SIMACAEKERRefMap/simaker-m-AmpPyc-sb.htm
Abaqus UMAT interface and conventions: https://docs.software.vt.edu/abaqusv2025/English/SIMACAESUBRefMap/simasub-c-umat.htm

Simulation campaign to guarded learning workflow¶

Stable ID: agentfem.workflow.campaign_learning_pipeline
Kind: workflow
Status: supported
Source card: src/agentfem/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.campaigns.CampaignReport.require_field_dataset
agentfem.datasets.FieldDatasetAssembler
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.
ScientificFieldDataset	field manifest plus numeric arrays	preserved per declared field encoding	Accepted complete fields, coordinates, parameters, case evidence, and artifact links assembled through an explicit extractor.
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.
Field extraction remains problem-owned; AgentFEM does not guess scientific fields from result filenames.
Automatic arbitrary-mesh neural-operator training is not implemented in core.

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_campaign_field_datasets.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

Partition-aware cell neighborhood topology¶

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

Builds owned-facet evidence and ghost-complete local stencils, then supplies affine-exact pair differences plus rank-audited least-squares gradients and their exact transpose action for neighboring-element, DG, estimator and fracture algorithms.

Public API¶

agentfem.assembly.assemble_cell_residual
agentfem.mesh.CellNeighborhood
agentfem.mesh.CellNeighborhoodGeometry
agentfem.mesh.CellPairDifference
agentfem.mesh.CellGradientOperator
agentfem.mesh.CellGradientReconstruction
agentfem.mesh.CellGradientStencil
agentfem.mesh.CellStencilNeighborhood
agentfem.mesh.InteriorFacetGeometry
agentfem.mesh.InteriorFacetPair
agentfem.mesh.cell_neighborhood
agentfem.mesh.cell_neighborhood_geometry
agentfem.mesh.cell_gradient_operator
agentfem.mesh.cell_pair_directional_difference
agentfem.mesh.cell_stencil_neighborhood
agentfem.mesh.owned_cell_measures
agentfem.mesh.reconstruct_cell_gradient
agentfem.operators.CellGradientEnergyOperator
agentfem.operators.cell_gradient_energy
agentfem.operators.CellAverageGradientOperator
agentfem.operators.cell_average_gradient

Scientific contract¶

An interior facet is an operator stencil joining exactly two manifold cells; a partition interface must retain that two-cell meaning through ghost adjacency and must never be silently reclassified as an exterior boundary.

manifold interior-facet adjacency

\[ |\mathcal{C}(f)|=2\quad\text{for every interior facet }f \]

The two-cell stencil must remain complete when one adjacent cell is a ghost on the current MPI rank.

Inputs¶

Name	Type	Unit role	Meaning
domain	DOLFINx mesh or AgentFEM FEMMesh	topology	The mesh supplies facet-to-cell and cell-to-facet connectivity, including ghost cells at partition interfaces.

Outputs¶

Name	Type	Unit role	Meaning
cell neighborhood	owned interior-facet pairs and partition evidence	runtime topology	Each pair records runtime local/global facet and cell indices plus the local facet number in both adjacent cells; optional geometry adds centroids, facet midpoint, center vector, distance and direction in embedding coordinates.
pair directional difference	scalar or vector cell-value differences per center distance	input value per length	The discrete operator is exact for affine cell-center data and remains explicitly distinct from a reconstructed full gradient or shell curvature.
cell gradient reconstruction	owned-cell scalar or vector gradient plus stencil evidence	input value per length	Weighted least squares uses a local SVD tangent basis and reports neighbor count, rank and condition number for every owned cell; compact neighbor weights can be cached and reapplied to many fields, and the same operator exposes its exact transpose for residual and energy-gradient construction.
cell gradient energy operator	matrix-free energy, residual and tangent action	declared cell weight and stiffness contract	One cached G evaluates 0.5 sum(w k \|Gv\|^2), its exact residual G^T w k Gv and the matching tangent action for scalar or vector cell fields without forming a dense global matrix.
owned cell measures	one positive physical integration measure per owned cell	length to the mesh topological dimension	A DG0 test integral provides cell-aligned weights and excludes ghost cells so rank-local energies count every global cell once.
assembled DG0 cell residual	ghosted PETSc vector on a scalar or blocked DG0 space	the supplied cell virtual-work contribution	Local and ghost cell contributions are mapped by explicit cell identity, reverse-scattered with addition to owners, and forward-scattered for a consistent distributed vector.
FEM-to-cell average gradient transfer	reusable sparse forward matrix and exact mass-inverse-weighted transpose	source field per length and its work-conjugate dual	A UFL gradient coupling maps scalar or vector FEM fields to physical DG0 cell averages; local-plus-ghost gradient duals reverse-scatter before the exact transpose returns a source-space PETSc residual.

Assumptions¶

The domain is a manifold mesh with one cell at an exterior facet and two cells at an interior facet.
Distributed meshes include the ghost-cell adjacency required by the consuming operator.

Conventions¶

Only owned facets are emitted, so each global interior facet is represented once across MPI ranks.
Cell pairs are ordered by runtime global cell index for deterministic local execution.

Applicability¶

Rotation-free neighboring-element shells, discontinuous Galerkin operators, local error estimation and crack-neighborhood algorithms.

Limitations¶

Runtime global indices depend on the mesh partition and are not scientific model identity or restart identity.
The contract does not define a shell curvature, bending virtual work, or forming solver; reconstructed gradients must still pass field-specific patch and convergence tests.
Callers must synchronize ghost cell values before evaluating a distributed pair difference or gradient reconstruction.
The transpose returns local and ghost-cell contributions; distributed residual assembly must reverse-scatter ghost contributions to their owning ranks.

Minimal example¶

gradient = mesh.cell_gradient_operator(domain, rings=2); energy = operators.cell_gradient_energy(gradient, cell_weights=weights, stiffness=k); residual = energy.residual(cell_values)

Verification¶

Tests

tests/test_mesh_neighborhood.py
tests/test_parallel_mesh_semantics.py

Benchmarks

None declared.

Validation rules

Recover exact interior and exterior facet counts on triangle and quadrilateral meshes.
Retain both local-facet positions and deterministic cell ordering.
Recover translation-invariant center vectors, distances and directions from embedding coordinates.
Recover the exact directional derivative of affine scalar and vector cell-center fields.
Recover affine-exact scalar and vector full gradients on triangle and quadrilateral meshes while rejecting rank-deficient or ill-conditioned stencils.
Reuse one geometry-cached compact operator across fields and annihilate arbitrary constant offsets exactly.
Satisfy the scalar and vector inner-product identity between the cached gradient action and its exact transpose, including rank-local ghost contributions under two MPI ranks.
Match finite-difference energy derivatives with the exact residual, retain a symmetric positive-semidefinite tangent, and preserve constant fields as an exact zero-energy mode.
Recover the exact rectangle area on triangular and quadrilateral meshes and count the unit-square area exactly once across two MPI ranks.
Assemble scalar and vector DG0 cell contributions by cell identity and recover global energy-directional-derivative work after ghost reverse scatter under two MPI ranks.
Recover affine-exact scalar and three-component FEM gradients and satisfy the global forward/adjoint work identity with rank-dependent ghost contributions under two MPI ranks.
Under two MPI ranks, count every global interior facet exactly once and retain a ghost adjacent cell across partition interfaces.

References¶

Bai et al. (2024), Influence of in-plane bending behaviour on textile composite reinforcement forming: https://doi.org/10.1016/j.ijmecsci.2024.109206
Steer et al. (2021), rotation-free in-plane bending of fibrous reinforcements: https://doi.org/10.1016/j.ijsolstr.2021.03.001

Physical-keyed cohesive state across MPI partitions¶

Stable ID: agentfem.workflow.cohesive_state_portability
Kind: workflow
Status: experimental
Source card: src/agentfem/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

Composite material frames and laminate sections¶

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

Keeps elastic behavior, material orientation, and ordered ply placement as separate reusable assets, with oriented 2D/3D solid response, classical laminate resultants, stable section-point recovery, and reviewed Abaqus composite-section lowering.

Public API¶

agentfem.materials.MaterialFrame
agentfem.materials.oriented
agentfem.materials.Ply
agentfem.materials.LaminateSection
agentfem.materials.laminate_from_abaqus_section
agentfem.constitutive.orthotropic_plane_stress_2d
agentfem.constitutive.orthotropic_elastic_3d
agentfem.results.small_strain_cell_fields

Scientific contract¶

A constitutive stiffness is written in an orthonormal material frame, rotated into the model frame at assignment, and integrated through an ordered laminate thickness only when a section response is requested.

oriented elasticity

\[ \boldsymbol{\sigma}=\mathbf{R}\,\mathbb{C}^{m}:[\mathbf{R}^{T}\boldsymbol{\varepsilon}\mathbf{R}]\,\mathbf{R}^{T} \]

The material constants and their placement orientation remain independent assets.

laminate constitutive resultants

\[ \begin{bmatrix}\mathbf{N}\\\mathbf{M}\end{bmatrix}=\begin{bmatrix}\mathbf{A}&\mathbf{B}\\\mathbf{B}&\mathbf{D}\end{bmatrix}\begin{bmatrix}\boldsymbol{\varepsilon}^{0}\\\boldsymbol{\kappa}\end{bmatrix} \]

Ordered plies define membrane, coupling, and bending stiffness about the declared reference surface.

Inputs¶

Name	Type	Unit role	Meaning
elastic material and material frame	2D reduced or 3D engineering-Voigt stiffness plus right-handed orthonormal basis	stress and dimensionless direction cosines	The frame is attached to a material assignment rather than duplicated in material constants.
ordered plies	material, thickness, angle, name, and section-point count per ply	stress, length, and degrees	Stable ply and section-point identities preserve provenance and recovery location.

Outputs¶

Name	Type	Unit role	Meaning
oriented solid fields and laminate response	global/material stress and strain, A/B/D matrices, generalized resultants, and per-ply section-point fields	stress, force per length, force, and consistent section units	S_MATERIAL and E_MATERIAL make the reporting coordinate system explicit.

Assumptions¶

The oriented solid response is small-strain linear elasticity with one constant frame per assignment.
LaminateSection uses classical laminate kinematics and plane-stress lamina stiffness.

Conventions¶

2D and 3D engineering shear strains use gamma_12 and gamma_23/gamma_13/gamma_12 respectively.
Ply angles are degrees measured counter-clockwise from the section reference axis.
A reviewed Abaqus section is lowered only after material references and row semantics are explicit.

Applicability¶

Oriented linear-elastic solid analysis, laminate section studies, composite migration review, and future shell-provider inputs.

Limitations¶

LaminateSection is a local section asset and is not yet a shell finite element.
Spatial orientation fields, finite-strain anisotropy, anisotropic thermal expansion, progressive ply damage, and delamination are separate capabilities.
Abaqus lowering covers reviewed common composite solid/continuum and shell rows rather than arbitrary keyword execution.

Minimal example¶

lamina = constitutive.orthotropic_plane_stress_2d(ex=135e9, ey=10e9, nuxy=0.3, gxy=5e9, density=1600); frame = materials.MaterialFrame.from_angle(45); assigned = model.material(lamina, orientation=frame); section = materials.laminate([materials.ply(lamina, 1.25e-4, angle=0, name='ply_0'), materials.ply(lamina, 1.25e-4, angle=90, name='ply_90')])

Verification¶

Tests

tests/test_composite_materials.py

Benchmarks

None declared.

Validation rules

Reject non-orthonormal, left-handed, dimensionally incompatible, or orientation-reversing material frames.
Recover the isotropic limit of 3D engineering-constant orthotropy.
Preserve elastic energy under frame rotation and require the coupling matrix of a symmetric laminate to vanish.
Retain unique ply and section-point identities and fail closed on unreviewed or ambiguous imported sections.

References¶

Abaqus 2025 documentation, Defining composite plies: https://docs.software.vt.edu/abaqusv2025/English/SIMACAECAERefMap/simacae-t-prpcompositesshellcontinuumplies.htm

Local coordinates and reference-point continuum coupling¶

Stable ID: agentfem.workflow.coordinate_reference_coupling
Kind: workflow
Status: supported
Source card: src/agentfem/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

Engineering creep-fatigue assessment¶

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

A standard-neutral postprocessing contract for source-identified creep time fractions, declared dwell extraction from named stress/temperature histories, existing stress-life fatigue assessments, explicit interaction diagrams, and structured result evidence.

Public API¶

agentfem.assessments.CreepDamageBlock
agentfem.assessments.DwellInterval
agentfem.assessments.creep_blocks_from_result
agentfem.assessments.creep_time_fraction
agentfem.assessments.interaction_diagram
agentfem.assessments.creep_fatigue
agentfem.assessments.creep_fatigue_from_result

Scientific contract¶

Creep and fatigue damage are computed by separately reviewable consumers, then compared with one explicitly sourced interaction boundary; this engineering assessment is not a coupled constitutive evolution law.

creep time fraction

\[ D_{c}=\sum_i n_i\,t_i/t_{r,i} \]

Each dwell duration and rupture time remains attached to its label and source.

interaction decision

\[ D_f\leq D_{f,\mathrm{allow}}(D_c) \]

The allowable boundary is a declared piecewise-linear scientific input.

Inputs¶

Name	Type	Unit role	Meaning
creep blocks	duration, rupture time, repetitions, label and source	duration and rupture time use the same time unit	Rupture times come from reviewed material data or a declared assessment relation.
named result histories and dwells	scalar stress/temperature HistoryResult names and DwellInterval records	history time, stress and absolute temperature	The V1 extractor interpolates dwell endpoints, applies declared reducers and calls a source-identified project rupture relation.
fatigue assessment	FatigueAssessment	dimensionless cumulative damage	Usually produced from a verified scalar history, cycle counting, mean-stress policy and S-N curve.
interaction diagram	ordered creep-damage and allowable-fatigue-damage points	dimensionless damage coordinates	Normative, company or research data stay outside the core and retain their source.

Outputs¶

Name	Type	Unit role	Meaning
damage and margin	creep damage, fatigue damage, allowable fatigue damage and signed margin	dimensionless	Positive margin is inside the declared boundary.
assessment record	JSON-safe source-preserving structure	scientific evidence	May be attached to a SimulationResult without changing the FEM solution.

Assumptions¶

The selected time-fraction rule, fatigue model and interaction curve are applicable to the assessed material, temperature and loading history.
Creep and fatigue damage are evaluated independently before interaction.

Conventions¶

Creep damage is horizontal and allowable fatigue damage is vertical in an interaction diagram.
AgentFEM provides a transparent linear reference but no design-code or material-specific curve.
An assessment is a postprocessor and does not weaken stiffness or advance constitutive state.
A declared dwell outside either result history fails instead of silently clamping or extrapolating.

Applicability¶

Exploratory and engineering life assessments with reviewed rupture, fatigue and interaction inputs.
Traceable comparison of alternative project procedures without changing the FEM model.

Limitations¶

It does not implement cyclic viscoplasticity, dwell stress relaxation or coupled continuum damage.
Qualification against a design standard requires licensed/current normative data and engineering review.

Minimal example¶

For existing result histories, declare DwellInterval records and call assessments.creep_fatigue_from_result(...) with named stress/temperature histories, a fatigue curve, and a source-identified rupture callable; direct CreepDamageBlock composition remains available.

Verification¶

Tests

tests/test_assessments.py

Benchmarks

agentfem.benchmark.creep_fatigue_assessment

Validation rules

Reject missing rupture and interaction sources.
Reject malformed or nonmonotone interaction boundaries.
Reject missing, non-scalar, or out-of-range result histories and nonphysical rupture times.
Keep the complete fatigue, creep and interaction records with the decision.

References¶

ASTM E1049 cycle counting in fatigue analysis: https://store.astm.org/standards/e1049
ASME high-temperature structural design technology report: https://www.asme.org/getmedia/4e4e3227-b157-4614-8172-572ade1c7e1d/20533.pdf

Transactional generalized work and cycle-block energy ledger¶

Stable ID: agentfem.workflow.cyclic_work_energy_ledger
Kind: workflow
Status: experimental
Source card: src/agentfem/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=\frac{1}{2}(\mathbf{Q}_i+\mathbf{Q}_{i+1})\cdot(\mathbf{q}_{i+1}-\mathbf{q}_i) \]

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

cycle-block balance

\[ \varepsilon_E=\frac{\left|W_{\mathrm{ext}}-\Delta E_{\mathrm{accounted}}\right|}{\max\left(\left|W_{\mathrm{ext}}\right|,\left|\Delta E_{\mathrm{accounted}}\right|,\varepsilon\right)} \]

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

Mesh, element, and Study discretization preflight¶

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

Reports runtime mesh topology, actual UFL/Basix element identities, Study value-shape compatibility, and optional MPI-global mesh-quality evidence without inferring formulation from connectivity.

Public API¶

agentfem.elements.describe_element
agentfem.elements.describe_field
agentfem.elements.audit
agentfem.mesh.describe_geometry
agentfem.mesh.describe_topology_compatibility

Scientific contract¶

Mesh connectivity, coordinate geometry, finite-element interpolation, and numerical formulation are separate identities and must be checked without silently substituting one for another.

discretization identity separation

\[ I_{source} \neq I_{topology} \neq I_{space} \neq I_{formulation} \]

Each identity is recorded independently; equality is established only by an explicit adapter or provider contract.

high-order simplex quality

\[ q = \min(q_{corner}, \min_{\xi \in S} J_s(\xi)) \]

Corner mean-ratio quality is limited by the minimum sampled scaled Jacobian of the real coordinate map.

Inputs¶

Name	Type	Unit role	Meaning
Model and quality policy	registered mesh, fields, Study, optional q_min	element identity plus dimensionless quality	Metadata inspection is cheap; cell-quality evaluation is an explicit collective option.

Outputs¶

Name	Type	Unit role	Meaning
DiscretizationAudit	topology capabilities, coordinate element, field elements, structured validation, optional MeshQualityReport	mixed metadata and dimensionless quality	Stable issue codes identify repairable mesh, element, shape, and quality failures.

Assumptions¶

Registered finite-element fields expose a DOLFINx function space and UFL element.

Conventions¶

Runtime topology maturity is independent of source-element formulation.
Coordinate-element identity is independent of solution-field interpolation.
Invalid cells are errors; a positive poor-cell threshold is explicit project policy.
Ordinary Model validation does not perform a cell-level quality traversal.

Applicability¶

Generated and imported AgentFEM meshes with scalar, vector, tensor, blocked, or mixed finite-element fields.

Limitations¶

The preflight does not prove inf-sup stability, locking freedom, reduced-integration equivalence, or vendor element equivalence.
Analysis-specific formulation maturity remains the Step provider's responsibility.

Minimal example¶

report = elements.audit(model, check_quality=True, quality_threshold=0.1)

Verification¶

Tests

tests/test_element_contracts.py
tests/test_mesh_quality.py
tests/test_mixed_cell_topologies.py
tests/test_validation.py

Benchmarks

None declared.

Validation rules

Preserve scalar, vector, blocked, and mixed element identities.
Reject a solid displacement whose value shape differs from the Study dimension.
Separate verified runtime topology from conditional source import maturity.
Identify quadratic coordinate bases and continuously detect positive near-singular curved simplex maps.
Reproduce affine gradients and assemble conforming P1 forms on prism and pyramid cells.
Warn or fail on poor cells according to the explicit policy while always rejecting invalid cells.

References¶

UFL finite-element language: https://docs.fenicsproject.org/ufl/main/
Basix finite-element definitions: https://docs.fenicsproject.org/basix/main/
DOLFINx finite-element functionality: https://docs.fenicsproject.org/dolfinx/main/python/generated/dolfinx.fem.html

Sparse physical-keyed cohesive force assembly across MPI ranks¶

Stable ID: agentfem.workflow.distributed_cohesive_force
Kind: workflow
Status: experimental
Source card: src/agentfem/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.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: src/agentfem/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: src/agentfem/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

Solver-neutral LEFM stress-intensity extraction¶

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

Defines stable straight-crack and crack-tip identities, exact mixed-mode Williams auxiliary fields, a solver-neutral interaction-domain integral, DOLFINx field lowering, path-sensitivity evidence, and analytical reference verification for stationary two-dimensional LEFM cracks.

Public API¶

agentfem.fracture.crack_set
agentfem.fracture.segment
agentfem.fracture.linear_elastic_fracture_material
agentfem.fracture.WilliamsField2D
agentfem.fracture.interaction_integral_report
agentfem.fracture.dolfinx_interaction_integral_report
agentfem.fracture.infinite_plate_stress_intensity
agentfem.fracture.verify_stress_intensity
agentfem.benchmarks.center_crack_mode_i_benchmark

Scientific contract¶

Stress-intensity extraction is a declared transformation from displacement-gradient and stress fields to per-tip mixed-mode evidence, with multiple integration domains retained instead of reporting one favorable scalar.

interaction domain integral

\[ I^{(1,2)}=\int_A\left(\sigma_{ij}^{(1)}u_{i,1}^{(2)}+\sigma_{ij}^{(2)}u_{i,1}^{(1)}-\sigma_{ik}^{(1)}\varepsilon_{ik}^{(2)}\delta_{1j}\right)q_{,j}\,\mathrm{d}A \]

Actual and auxiliary fields are expressed in one right-handed local crack-tip frame; q decays linearly across the declared annulus.

stress-intensity normalization

\[ K_m=E'I_m/2,\qquad E'=E\ \text{(plane stress)},\qquad E'=E/(1-\nu^2)\ \text{(plane strain)} \]

A unit Williams auxiliary field is evaluated separately for Mode I and Mode II.

energy release rate

\[ J=(K_I^2+K_{II}^2)/E' \]

The reported J follows the same two-dimensional isotropic LEFM assumption as the extracted stress-intensity factors.

Inputs¶

Name	Type	Unit role	Meaning
crack geometry and tip identity	CrackSet2D and stable tip ID	length	Declares the tip point, outward extension direction, normal and sign convention.
actual fields	2 by 2 stress and displacement-gradient expressions or sampled arrays	stress and dimensionless gradient	DOLFINx lowering samples only owned cells before MPI reduction; solver-neutral samples can originate from another provider.
material and integration domains	isotropic LEFM material plus inner and outer radii	stress, dimensionless Poisson ratio, and length	Multiple radii are required to expose path sensitivity.

Outputs¶

Name	Type	Unit role	Meaning
StressIntensityReport	per-tip K_I, K_II, J, per-radius values, path variation and status	stress times square-root length and energy per crack area	Carries coordinate, method, material and applicability metadata with the numerical result.
StressIntensityVerification	reference error, path status and acceptance status	dimensionless relative error	Keeps analytical or external reference comparison separate from extraction.

Assumptions¶

The crack is straight in the integration domain and the tip frame is right-handed.
The material is homogeneous, isotropic and linearly elastic under plane stress or plane strain.
The extraction domain is quasi-static and excludes body-force, thermal-eigenstrain and applied crack-face-traction terms.

Conventions¶

The local x1 axis points outward from the crack tip; x2 is its counterclockwise normal.
Positive K_I opens along x2 and positive K_II shears along x1.
Every MPI rank samples owned cells only and the scalar domain integral is summed globally.

Applicability¶

Stationary straight cracks in two-dimensional homogeneous isotropic linear-elastic finite-element or neural-field solutions.

Limitations¶

Curved cracks, bimaterial interfaces, three-dimensional fronts, finite-strain fracture and enriched-domain correction terms require distinct formulations.
A low optimizer loss or one extraction radius is not sufficient verification evidence.
The included mesh builder is a serial benchmark fixture, not a general crack insertion tool.

Minimal example¶

evidence = benchmarks.center_crack_mode_i_benchmark(); assert evidence.status == 'accepted'

Verification¶

Tests

tests/test_fracture_geometry.py
tests/test_fracture_integrals.py
tests/test_fracture_fem.py
tests/test_parallel_fracture_fem.py

Benchmarks

agentfem.benchmark.lefm_center_crack_mode_i

Validation rules

Recover exact Mode-I and Mode-II Williams fields for plane stress and plane strain.
Recover the same exact mixed-mode field after owned-cell sampling and two-rank MPI reduction.
Reject invalid shapes, dimensions, radii and empty domains before returning scientific evidence.
Solve a real split-mesh center crack and meet K, J, path-variation and parasitic-mode tolerances.

References¶

An interaction energy integral method for computation of mixed-mode stress intensity factors along non-planar crack fronts in three dimensions: https://doi.org/10.1016/S0013-7944(01)00080-7
Interaction integral procedures for 3-D curved cracks including surface tractions: https://doi.org/10.1016/j.engfracmech.2005.01.002

Mesh-independent structured observation grids¶

Stable ID: agentfem.workflow.observation_grid_learning
Kind: workflow
Status: supported
Source card: src/agentfem/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

Finite-strain periodic-cell homogenization evidence¶

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

Records macroscopic finite-strain tensors, stress-state invariants, Hill--Mandel work consistency and nonlinear convergence evidence at every accepted affine-periodic increment independently of sparse spatial-field output.

Public API¶

agentfem.results.periodic_cell_history
agentfem.results.homogenize_periodic_cell
agentfem.results.cauchy_stress_invariants
agentfem.results.hill_mandel_increment
agentfem.results.write_homogenized_history
agentfem.results.write_homogenized_csv

Scientific contract¶

An RVE result is a path of accepted compatible states with macroscopic averages, energetic consistency and solve evidence attached to the same increment coordinate, not only a final stress tensor or a sparse collection of visualization frames.

macroscopic first-Piola stress

\[ \bar{\mathbf P}=\frac{1}{V_0}\int_{\Omega_0}\mathbf P\,\mathrm dV \]

For a porous solid-only mesh, void stress is zero and the integral remains normalized by complete reference-cell volume V_0.

finite-strain Hill--Mandel relation

\[ \langle\mathbf P:\dot{\mathbf F}\rangle=\langle\mathbf P\rangle:\langle\dot{\mathbf F}\rangle \]

AgentFEM evaluates a trapezoidal accepted-increment counterpart using identical stress rules at both scales.

stress-state coordinates

\[ \eta=\sigma_m/q,\qquad\bar\theta=1-\frac{2}{\pi}\arccos\left(\frac{27J_3}{2q^3}\right) \]

Undefined hydrostatic or zero-deviator states carry an explicit validity channel.

Inputs¶

Name	Type	Unit role	Meaning
accepted affine-periodic states	displacement, optional pressure, load factor and nonlinear solve evidence	kinematics, stress and dimensionless load coordinate	The recorder observes every accepted increment even when spatial XDMF fields are saved less frequently.
complete reference-cell volume	positive scalar declared by the periodic constraint	volume	Separates effective porous-cell averages from solid-phase averages.

Outputs¶

Name	Type	Unit role	Meaning
accepted macro history	SimulationResult histories plus NPZ and CSV artifacts	tensor, energy-density and dimensionless evidence	Aligns macro tensors, Hill--Mandel evidence, increment size, Newton iterations, residual, periodic mismatch and accepted attempt.

Assumptions¶

Current Hill--Mandel lowering is quasistatic and excludes body-force, natural-load and inertia power.
The finite-strain constitutive response supplies first-Piola and Cauchy stresses for the same accepted state.

Conventions¶

Macroscopic stress is normalized by the complete cell volume.
The initial frame has no accepted nonlinear increment and carries an explicit validity flag.
NPZ represents undefined stress-state coordinates with NaN; structured histories use a zero placeholder plus a validity channel.

Applicability¶

Quasistatic affine-periodic finite-strain cells using a supported hyperelastic or finite-strain J2 step and output plan.
Finite-strain J2 cells may use an identity-starting, positive-determinant piecewise-linear macroscopic deformation-gradient path for unload, reload and non-proportional histories.

Limitations¶

Stress-controlled target triaxiality/Lode paths and external-load power are separate, pending capabilities.
A software-level Hill--Mandel check does not replace mesh, path and external-reference evidence for a material claim.

Minimal example¶

output = results.output_plan('outputs/cell', requests=(results.periodic_cell_history(periodicity),)); step = model.step(target=displacement, material=material, constraints=periodicity, output=output)

Verification¶

Tests

tests/test_results.py
tests/test_engineering_workflows.py
tests/test_finite_strain_j2_periodic.py
tests/finite_strain_j2_path_mpi_driver.py
tests/test_periodic_void_fixture.py
tests/parallel_periodic_void_j2_driver.py
tests/test_periodic_multi_void_fixture.py
tests/test_multi_void_rve_golden.py
tests/multi_void_rve_golden_driver.py
tests/multi_void_rve_restart_driver.py

Benchmarks

agentfem.benchmark.finite_strain_j2_periodic_void
agentfem.benchmark.finite_strain_j2_periodic_multi_void

Validation rules

Recover identical micro and macro work for a homogeneous finite-strain path.
Preserve every accepted macro state while spatial output remains sparse.
Preserve unload and non-proportional deformation-gradient knots in serial and distributed stateful J2 paths.
Recover uniaxial-tension, pure-shear and undefined hydrostatic stress-state conventions.
Keep complete-cell macroscopic stress, physical-weighted quadrature statistics, Hill--Mandel evidence and restart identity consistent for deterministic single- and multi-void periodic cells in serial and distributed execution.
Fail before solving when undeclared external power lies outside the current energy ledger.

References¶

Elastic properties of reinforced solids: Some theoretical principles: https://doi.org/10.1016/0022-5096(63)90036-X
Discrete averaging relations for micro to macro transition: https://doi.org/10.1115/1.4033552
Open manuscript: Discrete averaging relations for micro to macro transition: https://arxiv.org/abs/1509.06621
Flow curves up to high strains considering load reversal and damage: https://doi.org/10.1007/s12289-018-01466-z

Physical-measure statistics for quadrature fields¶

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

Reduces scalar integration-point fields with reference quadrature weights, geometric Jacobians, explicit measure multipliers, owned-cell MPI semantics and exact weighted quantiles instead of treating stored samples as equal-volume observations.

Public API¶

agentfem.results.weighted_field_statistics
agentfem.constitutive.QuadratureField.owned_physical_weights
agentfem.constitutive.QuadratureField.weighted_statistics

Scientific contract¶

A field statistic is a declared integral reduction over physical measure; distorted cells, unequal cell sizes and nonuniform quadrature must therefore contribute through their physical weights.

physical quadrature weight

\[ w_q=w_q^{\mathrm{ref}}|\det\mathbf{J}_q|m_q \]

The optional multiplier m_q is explicit and can represent an axisymmetric or other declared measure factor.

weighted mean

\[ \bar a=\frac{\sum_q w_q a_q}{\sum_q w_q} \]

The same physical weights define the standard deviation, threshold fractions and cumulative measure used for weighted quantiles.

Inputs¶

Name	Type	Unit role	Meaning
scalar quadrature values	owned scalar integration-point values	field-dependent	Tensor fields require an explicitly selected component or invariant before reduction.
physical weights	positive reference weights times absolute geometric Jacobian and optional multiplier	physical measure	Ghost-cell values are excluded from MPI reductions.

Outputs¶

Name	Type	Unit role	Meaning
WeightedFieldStatistics	measure, mean, standard deviation, quantiles and threshold fractions	field units plus measure units	Carries the declared field name, location, representation and MPI reduction mode.

Assumptions¶

Weights are finite and non-negative and their global sum is positive.
Values and weights refer to the same owned quadrature points in the same order.

Conventions¶

Weighted quantiles use the first sorted value whose cumulative physical measure reaches the requested probability.
Exact MPI quantiles gather scalar value and weight arrays to one rank and broadcast only the compact result.

Applicability¶

Scalar quadrature fields from plasticity, creep, damage and other integration-point state models.

Limitations¶

Exact global quantiles are not intended as a distributed full-field storage format.
Axisymmetric and custom weighted measures require an explicit multiplier.

Minimal example¶

summary = state.equivalent_plastic_strain.weighted_statistics(quantiles=(0.5, 0.95), thresholds=(0.02,))

Verification¶

Tests

tests/test_constitutive_models.py
tests/test_parallel_results.py

Benchmarks

None declared.

Validation rules

Recover exact physical means and threshold fractions on unequal or distorted cells.
Reject tensor-valued fields without an explicit scalar reduction.
Use owned quadrature points exactly once in two-rank MPI reductions.
Broadcast validation failures so no rank waits in a collective after another rank has failed.

References¶

AgentFEM RVE homogenization and physical field statistics reference: docs/reference/rve_homogenization_and_statistics.md
DOLFINx finite-element functionality: https://docs.fenicsproject.org/dolfinx/main/python/generated/dolfinx.fem.html

MPI-safe point and path field sampling¶

Stable ID: agentfem.workflow.result_field_sampling
Kind: workflow
Status: supported
Source card: src/agentfem/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

Spawned campaign ensembles and convergence certificates¶

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

Runs independent cases through safe spawned local processes, fingerprints declared and resolved scientific inputs, and issues conservative multi-axis convergence certificates.

Public API¶

agentfem.campaigns.local_processes
agentfem.convergence.axis
agentfem.convergence.observable
agentfem.convergence.audit
agentfem.provenance.scientific_input_manifest
agentfem.results.SimulationResult.add_scientific_inputs

Scientific contract¶

A scalable refinement study remains scientific evidence only when execution resources, failed cases, fixed coordinates, observable policies, and input identity coverage remain explicit.

finest relative change

\[ \eta_q=\frac{\lVert q_{n}-q_{n-1}\rVert}{\max(\lVert q_n\rVert,\epsilon)} \]

The metric is evaluated per declared observable on an explicit coarse-to-fine slice.

uniform-ratio observed order

\[ p=\frac{\log(\lVert q_{n-2}-q_{n-1}\rVert/\lVert q_{n-1}-q_n\rVert)}{\log(h_{n-2}/h_{n-1})} \]

Order is reported only for at least three samples with matching successive refinement ratios.

Inputs¶

Name	Type	Unit role	Meaning
campaign cases	CampaignPlan plus build/evaluate contracts	parameter units retained	Each independent case has a deterministic identity and fresh construction boundary.
refinement axes	positive characteristic size or inverse resolution with fixed coordinates	declared by the corresponding parameter	Prevents unrelated parameter changes from entering a convergence sequence.
scientific inputs	files, arrays, mappings, or objects with IR/summary contracts	preserved by the public scientific record	Opaque objects remain explicit coverage gaps.

Outputs¶

Name	Type	Unit role	Meaning
CampaignReport	ordered case records, worker evidence, runtime and input manifests	inherits declared quantities	Failed cases remain addressable and completed cases are resumable.
ConvergenceCertificate	passed, failed, or inconclusive checks per axis and observable	relative metrics are dimensionless; absolute metrics inherit output units	Includes case IDs, characteristic sizes, values, criteria, and a stable certificate identity.

Assumptions¶

Each local worker can import and serialize the Campaign build/evaluate callables.
Each case constructs fresh mutable solver state.
Convergence axes are positive and all other varying parameters are explicitly fixed.
Exact event/topology records are JSON-safe scientific evidence.

Conventions¶

Across-case local execution uses spawn and cannot be nested inside within-case MPI.
Characteristic sizes are ordered coarse-to-fine; inverse resolution converts element counts to decreasing size.
Missing or failed refinement cases make a check inconclusive.

Applicability¶

Local workstation parameter sweeps, mesh/time/cohesive resolution studies, event-order stability, topology checks, and evidence generation before learning or publication.

Limitations¶

No scheduler or independently launched MPI-job ensemble provider is included yet.
The initial certificate does not calculate generalized GCI or uncertainty intervals.
Field comparison uses declared numeric arrays; mesh-transfer norms require a future field policy.
Complete input identity depends on explicit files or public IR/summary contracts.

Minimal example¶

campaign = campaigns.create(..., execution=campaigns.local_processes(workers=4), scientific_inputs={"mesh": Path("mesh.inp")}); report = campaign.run(plan); certificate = convergence.audit(report, axes=(convergence.axis("h", fixed={"dt": 1e-3}),), observables=(convergence.observable("response", tolerance=0.01),))

Verification¶

Tests

tests/test_campaigns.py
tests/test_convergence_audit.py
tests/test_provenance.py

Benchmarks

None declared.

Validation rules

Reject local-process nesting inside a within-case MPI communicator.
Reject duplicate axis or observable declarations.
Report failed, missing, duplicate-size, or insufficient refinement sequences as inconclusive.
Mark objects without scientific identity contracts as incomplete coverage.

References¶

AgentFEM scientific experiments: docs/scientific_experiments.md
Python multiprocessing contexts and start methods: https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods
W3C PROV-O recommendation: https://www.w3.org/TR/prov-o/

Campaign-backed scientific response experiments¶

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

Freezes runtime evidence, composes serializable loading modes, lowers finite-difference perturbations to ordinary Campaign cases, and preserves first-passage localization and censoring.

Public API¶

agentfem.provenance.freeze_runtime
agentfem.provenance.require_runtime
agentfem.amplitudes.AmplitudeBasis
agentfem.responses.FiniteDifferenceResponse
agentfem.events.first_passage

Scientific contract¶

A derived response is evidence only when its baseline, perturbations, outputs, runtime identity, failures, and event-localization assumptions remain inspectable.

central finite-difference response

\[ J_{ji}\approx\frac{q_j(\mathbf{p}+h_i\mathbf{e}_i)-q_j(\mathbf{p}-h_i\mathbf{e}_i)}{2h_i} \]

Each perturbed evaluation is a deterministic Campaign case rather than an anonymous solver call.

linearly localized first passage

\[ t_*\approx t_k+\frac{q_*-q_k}{q_{k+1}-q_k}(t_{k+1}-t_k) \]

The containing bracket and interpolation assumption remain part of the event record.

Inputs¶

Name	Type	Unit role	Meaning
parameters and perturbations	bounded real ParameterSpace, baseline, and finite-difference steps	declared per parameter	Defines the derivative coordinates and admissible perturbation cases.
response quantities	named scalar/vector Quantity contracts	declared per output	Fixes output order, shape, and units before any case is run.

Outputs¶

Name	Type	Unit role	Meaning
ResponseReport	Jacobian, singular values, rank, condition number, nonlinearity and case identities	output unit divided by parameter unit	A complete report only when every required perturbation succeeded.
FirstPassageEvent	observed or censored threshold event	inherits history coordinate and response units	Retains the sample bracket and localization rule.

Assumptions¶

Finite-difference parameters are continuous real quantities within declared bounds.
Linear first-passage localization assumes a continuous monitored response inside the sample bracket.
Every case is built fresh or safely reset by the Campaign builder.

Conventions¶

Runtime compatibility is separate from scientific verification.
Central differences use baseline, plus, and minus cases with explicit absolute or relative steps.
A failed perturbation makes the response report incomplete.

Applicability¶

Parameter sensitivity, actuator bases, inverse problems, local control studies, and response-space screening for deterministic FEM workflows.

Limitations¶

Finite-difference cost grows with parameter dimension.
The first provider does not claim tangent-linear or adjoint differentiation.
Mixed-unit singular values and condition numbers require explicit nondimensional scaling.
Irreversible damage, contact, and topology changes can produce nonsmooth responses.

Minimal example¶

operator = responses.finite_difference(parameter_space=space, baseline=baseline, outputs=quantities, perturbation=0.01); campaign_report, response = operator.run(build=build_case, evaluate=solve_case)

Verification¶

Tests

tests/test_scientific_experiments.py
tests/test_provenance.py
tests/test_platforms.py

Benchmarks

None declared.

Validation rules

Reject perturbations outside parameter bounds.
Reject non-finite or wrong-shaped response quantities.
Report missing perturbation cases instead of forming a partial Jacobian.
Preserve first-passage brackets and censoring state.

References¶

AgentFEM scientific experiments: docs/scientific_experiments.md
OpenMDAO total derivative documentation: https://openmdao.org/newdocs/versions/latest/features/core_features/working_with_derivatives/compute_totals.html
W3C PROV-O recommendation: https://www.w3.org/TR/prov-o/

Scientific trust and verification workflow¶

Stable ID: agentfem.workflow.scientific_verification
Kind: workflow
Status: supported
Source card: src/agentfem/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 mesh-quality preflight¶

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

Computes topology-appropriate simplex mean ratio or sampled coordinate-map scaled Jacobians 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 measures triangle/tetrahedron shape while sampled scaled Jacobians inspect the active coordinate map of tensor, prism, pyramid, and high-order simplex geometry.

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.

sampled scaled Jacobian

\[ q_J=\min_{\xi\in\mathcal S}\frac{\sqrt{\det(J(\xi)^T J(\xi))}}{\prod_i\lVert J_i(\xi)\rVert} \]

Quadrature points and reference vertices sample the actual coordinate element; singular points or a sign change are invalid.

Inputs¶

Name	Type	Unit role	Meaning
solver mesh and threshold	supported DOLFINx 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 domain owns one reconstructible Basix coordinate element.

Conventions¶

Cells below threshold are poor; zero or non-finite cells are invalid.
Pyramid sampling uses interior quadrature and base vertices; the collapsed-coordinate apex has no unique in-plane derivative and is not sampled as an ordinary vertex.

Applicability¶

Generated or imported triangle, quadrilateral, tetrahedron, hexahedron, prism, and pyramid solver domains.

Limitations¶

Finite sampling is evidence, not a mathematical proof that the Jacobian is positive at every reference point.
A universal threshold is not implied; analysis-specific distortion, integration, and formulation checks remain separate.

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.
Recover one for unit quadrilateral and hexahedral coordinate maps.
Reduce sampled quality under a known shear distortion.
Return values within [0,1].
Reduce counts and statistics collectively over owned MPI cells.
Reject unsupported cell types instead of guessing a metric.

References¶

Algebraic mesh quality metrics for unstructured initial meshes: https://doi.org/10.1002/nme.1429
DOLFINx CoordinateElement Jacobian interface: https://docs.fenicsproject.org/dolfinx/main/cpp/doxygen/d9/d35/classdolfinx_1_1fem_1_1CoordinateElement.html

Solution procedure vocabulary¶

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

Owns how a declared Study is solved: static or transient advancement, linear modal extraction, and provider-neutral direct harmonic response. Constitutive materials own their response and history separately.

Public API¶

agentfem.procedures.SolutionProcedure
agentfem.procedures.resolve
agentfem.studies.modal_solid
agentfem.studies.harmonic_solid
agentfem.time.newmark
agentfem.time.generalized_alpha
agentfem.operators.direct_harmonic_system
agentfem.results.harmonic_response
agentfem.results.harmonic_average_response
agentfem.results.harmonic_probe_response
agentfem.results.SimulationResult.collective_manifest
agentfem.results.prepare_projection
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, a material supplies constitutive response, and a SolutionProcedure owns the numerical evolution or spectral solve that consumes the assembled operators. Modal and direct harmonic response therefore remain procedures rather than material capabilities.

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.

linear structural modes

\[ \mathbf{K}\boldsymbol{\phi}_j=\omega_j^2\mathbf{M}\boldsymbol{\phi}_j \]

The modal procedure removes strong constrained degrees of freedom before a generalized Hermitian eigensolve.

direct harmonic equilibrium

\[ \left(\mathbf{K}+\mathrm{i}\mathbf{K}_{\mathrm{loss}}+\mathrm{i}\omega\mathbf{C}-\omega^2\mathbf{M}\right)\hat{\mathbf{u}}=\hat{\mathbf{F}} \]

The provider-neutral procedure consumes visible frequency-invariant spatial operators and lowers the complex equation to an exact real block system.

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 and procedure controls	analysis intent, algorithm, increment or frequency controls, and solver policy	none plus the declared time or frequency unit	The resolved procedure is carried through capability inspection and executable lowering without changing physical meaning.
modal operator system	symmetric stiffness K, positive mass M, stationary homogeneous strong constraints, mode count and optional target frequency	one consistent mechanical unit system	The low structural spectrum is solved with SLEPc after constrained-degree elimination.
direct harmonic operator system	stiffness K, optional mass M, viscous damping C and loss stiffness K_loss, force F, and stationary homogeneous strong Dirichlet supports	one consistent mechanical and frequency unit system	One frequency or a strictly increasing canonical sweep reuses the frequency-invariant spatial operator system; a material may supply K_loss but does not own the procedure.

Outputs¶

Name	Type	Unit role	Meaning
typed procedure record	immutable StepRequest and structured summary	none	Records family, order, algorithm, control, statefulness, and solve requirements.
modal result	SimulationResult quantities and live mode fields	inverse time and mass-normalized shape	Includes positive frequencies, residuals, orthogonality evidence, cluster completeness, invariant-subspace semantics, deterministically oriented singleton mode fields and a portable identity of the executed mesh, K/M coefficients and constrained degrees of freedom.
direct harmonic result	phasor fields, canonical sweep histories and scalar checkpoint ledger	frequency and the model's consistent mechanical units	Publishes real, imaginary, component amplitude and phase fields, exact discrete vector amplitude, algebraic residual, cycle-energy and load evidence; single-frequency and sweep results bind the executed mesh, live K/M/C/K_loss/F coefficients and constrained degrees of freedom, while portable sweep restart retains scalar evidence rather than every full field.
advanced transient state	field state, execution trace, energy and convergence evidence	problem dependent	Accepted displacement, velocity, acceleration, temperature or material state follows the selected time procedure and common result lifecycle.
reaction and mechanical energy diagnostics	nodal residual field and scalar energy record	force and energy	Strong-constraint reactions and visible M/K quadratic energies are retained for supported systems.

Assumptions¶

Modal analysis is linear, undamped, based on symmetric stiffness and mass operators, and currently linearized about a stationary reference configuration with homogeneous strong constraints.
Direct harmonic analysis is a small-amplitude linear perturbation with one pure-displacement spatial discretization, stationary homogeneous strong Dirichlet supports, and no prestressed small-on-large state.
Implicit heat transfer currently uses backward Euler.
Central difference uses a lumped mass operator.

Conventions¶

Standard means a global implicit or assembled solution route, not an Abaqus compatibility claim.
Explicit means no global linear solve at each time increment.
Step, increment, iteration, attempt, frequency sample, and output frame remain distinct.
SLEPc mass-normalizes generalized Hermitian eigenvectors; repeated or clustered modes are compared as invariant subspaces rather than individual vectors.
Accepted eigenpair residuals gate eigensolver convergence; cluster completeness separately governs whether selected modes may be compared individually or only as an invariant subspace.
A mass-normalized mode shape is a relative spatial pattern and has no physical displacement amplitude until combined with a modal coordinate.
The public harmonic Step accepts cyclic frequency in Hz or angular frequency in rad/s, never both, and records the exp(+iomegat) phasor convention.
U_AMPLITUDE and U_PHASE are component-wise polar values; the sweep maximum is the exact physical-cycle maximum of each discrete vector coefficient, not a continuous-domain supremum.
Frequency sweeps publish histories in ascending canonical order even when points are executed or resumed in reverse order.
A harmonic sweep checkpoint is an atomic scalar evidence ledger; it does not claim recovery of one full finite-element field per frequency.
Automatic transient 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.
Natural-frequency and mode-shape analysis for supported linear solid models.
Linear direct steady-state response through generic K/M/C/K_loss/F operators, named scalar responses and bounded restartable frequency sweeps.

Limitations¶

Modal extraction currently accepts only stationary homogeneous strong Dirichlet constraints. Nonzero, time-dependent, remote, arbitrary MPC and weak kinematics require a verified prestressed/base-state or alternative constraint provider.
Direct harmonic engineering routes accept only stationary homogeneous strong Dirichlet constraints. Nonzero values, prescribed histories, remote displacement, arbitrary MPC and weak kinematics require separate verified providers.
Complex modes, prestressed small-on-large response and nonlinear harmonic balance are not implemented.
The generic direct sweep does not accept arbitrary complex spatial load patterns or frequency-dependent operator families.
Frequency-sweep field output requires explicitly selected snapshot frequencies; scalar-ledger restart does not retain every full field.
The generalized-Maxwell global harmonic provider remains experimental even though it consumes this engineering procedure.
Nonlinear implicit structural dynamics is not implemented.

Minimal example¶

modal = model.step(target=u, modes=6).solve_result(); harmonic = model.step(target=u, K=K, M=M, C=C, K_loss=K_loss, F=F, frequencies=(...)).solve_result()

Verification¶

Tests

tests/test_p1_platform.py
tests/test_transient_restart.py
tests/test_parallel_transient.py
tests/test_dynamics.py
tests/test_parallel_modal.py
tests/test_parallel_operator_identity.py
tests/test_modal_backend_mpi_failures.py
tests/test_harmonic.py
tests/test_harmonic_backend_evidence.py
tests/test_external_forced_vibration_benchmark.py
tests/portable_harmonic_sweep_driver.py

Benchmarks

agentfem.benchmark.linear_cantilever_modal
agentfem.benchmark.nafems_r0016_test5h_forced_vibration
agentfem.benchmark.nafems_r0016_test5h_spatial_refinement

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.
Eliminate strong constrained degrees of freedom before modal solution and reject insufficient free degrees of freedom.
Reject modal stiffness or mass operators that violate the symmetric generalized-Hermitian contract.
Require accepted modes to satisfy finite eigenpair-residual, mass-orthogonality and stiffness-diagonalization convergence contracts.
Record cluster completeness as a separate applicability contract: an incomplete repeated cluster may not be compared as individually identifiable modes even when the eigensolve converged.
Reject nonzero, time-dependent and remote prescribed modal motion before eigensolver assembly.
Bind every published modal result to a partition-neutral executable identity covering topology, physical coordinates, coordinate basis, solution element, live K/M coefficients and the exact constrained degree set; reject incomplete identity or post-solve drift.
Synchronize rank-local modal identity, boundary-reduction, eigenvalue-candidate and reduced-vector failures before the next collective, and require every rank to report the same failed stage.
Require serial and two-rank modal frequencies and invariant-subspace evidence to agree within declared tolerances.
Reject ambiguous frequency units, nonhomogeneous prescribed harmonic motion, unsupported constraint families and unsupported SPD-only harmonic solver policies.
Freeze every operator, live coefficient, boundary condition, load phase, solution field and solver policy captured by a prepared harmonic backend; reject configuration drift before solve.
Bind single-frequency and sweep harmonic results to the partition-neutral executable identity of topology, physical coordinates, coordinate basis, solution element, live K/M/C/K_loss/F coefficients and the exact constrained degree set; reject missing identity before publication.
Synchronize direct-harmonic constraint lowering, homogeneity inspection, executable-identity drift and publication failures before the next collective operation.
Freeze published harmonic fields and rank-zero canonical scientific-input records so later frequency changes, re-solves or coefficient mutation cannot rewrite an earlier Result.
Require complete modal and direct-harmonic SimulationResult manifests to agree across MPI ranks before retaining or writing rank zero's canonical record.
Reject non-finite harmonic solution, residual or energy evidence before publishing a result.
Require the independently assembled real-block residual and phasor-block residuals to satisfy the declared solver tolerance in serial and MPI.
Require nested and monolithic real-block layouts to reproduce the same nonzero-phase response and cycle input work.
Require the NAFEMS R0016 Test 5H comparison to meet the declared AgentFEM peak-frequency, displacement and recovered-stress gates without describing them as NAFEMS tolerances.
Require three successively refined Test 5H meshes to stabilize all three declared observables without inferring an observed order from nonuniform refinement ratios.
Require scalar harmonic sweep restart to preserve canonical results and scientific identity across forward/reverse execution and one/two-rank restart.

References¶

SLEPc EPS generalized eigenvalue problem documentation: https://slepc.upv.es/release/slepc4py/reference/slepc4py.SLEPc.EPS.html
Chung and Hulbert generalized-alpha method: https://deepblue.lib.umich.edu/bitstream/handle/2027.42/50422/1640100803_ftp.pdf?isAllowed=y&sequence=1
NAFEMS R0016 Selected Benchmarks for Forced Vibration: https://www.nafems.org/publications/resource_center/r0016/
Abaqus Benchmarks Guide: NAFEMS Test 5H forced vibration of a simply supported beam: https://docs.software.vt.edu/abaqusv2025/English/SIMACAEBMKRefMap/simabmk-c-forcedvibrationtest5h.htm

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

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

Produces engineering-default S, E, and MISES plus opt-in SENER as traceable cell-average fields, including full (r,theta,z) axisymmetric tensors and weighted projection, extracts MPI-global resultants, and records assembled external-force versus strong-reaction equilibrium.

Public API¶

agentfem.results.project
agentfem.results.prepare_projection
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.constraints.constraint_balance_contract
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{R}_{\mathrm{provider}}+\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}}+\tfrac{1}{2}\mathbf{q}_{p}^{T}\mathbf{a}_{p},\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 prescribed-motion work and each non-Dirichlet provider owns its generalized dual pair.

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.
prepared projection	reusable L2 projection space, mass matrix, KSP and live output Function	the projected expression's unit	Repeated recovery reassembles only the right-hand side while retaining the constant projection operator and solver.
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.
Axisymmetric fields are full 3x3 tensors and projection uses the same 2 pi r physical measure as equilibrium.
reaction_resultant alone reports the unconstrained residual route; complete model-level balance also consumes every declared provider-owned resultant.

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.
A prepared projection owns PETSc resources and should be closed explicitly or used as a context manager after the repeated recovery path.
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 only when every declared constraint has complete strong-reaction semantics.
MPC, weak, contact, projection, multiplier, and unknown constraint assets fail closed through a machine-readable constraint_balance_contract; partial reactions are never presented as complete equilibrium.

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, arbitrary MPC, weak, and contact reactions require their numerical provider to implement the shared dual_evidence(problem) protocol; force or work balance remains unavailable for any provider that has not supplied the corresponding physical dual. The rectangular homogeneous periodic and linear elastic-foundation providers implement their bounded contracts; general weak and contact providers do not yet claim complete evidence.
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
tests/test_parallel_affine.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.
Check that unresolved periodic/MPC evidence suppresses partial force and work balances and reports the missing named channel.
Check that elastic-foundation reactions close force balance while their stored energy remains in system strain energy rather than being counted twice.
Require provider-owned nodal reaction distributions to follow the ordinary solve_result(output=...) path into the same visualization dataset.
Verify a regional two-material series bar through one piecewise projection.
Require a prepared projection to track a changed live field while reusing one assembled mass operator and output Function.

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: src/agentfem/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, with conservative nonlinear enthalpy stepping for tabulated thermal properties and accepted-time field histories for sequential transfer.

Public API¶

agentfem.constitutive.thermoelastic
agentfem.constitutive.temperature_dependent_thermoelastic
agentfem.materials.temperature_property
agentfem.histories.temperature
agentfem.assessments.sequential_energy_ledger
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.

state-dependent heat increment

\[ \frac{h(T_{n+1})-h(T_n)}{\Delta t}-\nabla\!\cdot(k(T_{n+1})\nabla T_{n+1})=Q,\quad dh/dT=\rho c_p(T) \]

Tabulated conductivity or specific heat selects a conservative nonlinear residual and automatic consistent Jacobian.

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 or FieldHistory	absolute temperature	Solved or prescribed temperature consumed by thermal expansion or sampled at the receiving creep step's physical time.
temperature-dependent properties	constant or TemperaturePropertyTable	declared property unit against kelvin	Piecewise-linear tables preserve bounds, interpolation, provenance, and an explicit extrapolation policy.

Outputs¶

Name	Type	Unit role	Meaning
Temperature	transient scalar field	absolute temperature	Implicit-Euler heat-transfer result.
thermal ledger	accepted-time history	consistent heat/heat-rate system	Sensible enthalpy, applied rate, outward rate, and discrete closure residual.
sequential energy ledger	layered thermal and mechanical evidence	each residual retains its own equation and unit system	Links the accepted temperature-history identity while explicitly refusing a fictitious monolithic conservation claim.
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.
Temperature-dependent E, nu, and alpha are known coefficients in a sequential mechanical solve; heat-to-mechanics feedback remains one way.
Temperature-dependent conductivity and specific heat use piecewise-linear tables with explicit bounded extrapolation and an enthalpy primitive.

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.
Accepted FieldHistory metadata retains the source Study, procedure and one-way transfer role.

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.
Convection is supported; radiation and general thermal contact are not yet included in this card.
Portable nodal histories are compact root-gathered archives rather than an extreme-scale parallel field database.
The nonlinear thermal route currently uses fixed physical time increments; adaptive thermal cutback and monolithic temperature-displacement coupling remain.

Minimal example¶

Use materials.temperature_property(..., extrapolation='constant') for k(T) or cp(T), then call heat_step = model.step(target=temperature, dt=..., steps=...); capture its accepted temperature history and pass it to the Arrhenius creep step.

Verification¶

Tests

tests/test_p1_platform.py
tests/test_histories.py
tests/test_parallel_transient.py
tests/portable_field_history_driver.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.
Reject silent temperature-history extrapolation and invalid or unordered property tables.
Reject simultaneous automatic tabulated thermal properties and user-supplied C/K operators; verify failed nonlinear-step rollback and checkpoint/restart equivalence.

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: src/agentfem/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 and uses the same coordinate and solution finite elements.
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.
Structured coordinate- and solution-element identities bind family, degree, mapping and value semantics; identity schema changes fail closed before state mutation.
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: src/agentfem/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\mathbf{u}\rrbracket\cdot\mathbf{n},\quad \boldsymbol{\delta}_t=\llbracket\mathbf{u}\rrbracket-\delta_n\mathbf{n} \]

The same decomposition drives line and triangular-surface facets.

quadratic damage initiation

\[ \left(\frac{\langle t_n\rangle_{+}}{T_n}\right)^2+\left(\frac{\lVert\mathbf{t}_t\rVert}{T_t}\right)^2=1 \]

Compression does not initiate cohesive damage.

BK mixed fracture energy

\[ G_c=G_{\mathrm{I}c}+(G_{\mathrm{II}c}-G_{\mathrm{I}c})\left(\frac{G_s}{G_n+G_s}\right)^{\eta} \]

Power-law energy interaction is an alternative explicit option.

spherical continuation

\[ \lVert\Delta\mathbf{u}\rVert^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