Python API

This index is generated from the public workflow modules declared by AgentFEM. It is a discovery surface: detailed scientific meaning, maturity, and evidence remain in the linked guides and scientific function reference.

Generated reference

Run python build_docs.py to refresh this page after public API changes.

agentfem.studies

Kind	Public object	Purpose
class	Study	Early analysis context for a finite-element workflow.
function	define(*, analysis: str, physics: str, dimension: int, assumption: str \| None = None, name: str \| None = None, preferred_procedure: str \| None = None) -> Study	Define a general finite-element study context.
function	linear_static(*, physics: str, dimension: int, assumption: str \| None = None, name: str \| None = None) -> Study	Define a linear static study.
function	nonlinear_static(*, physics: str, dimension: int, assumption: str \| None = None, name: str \| None = None) -> Study	Define a nonlinear static study.
function	static_solid(*, dimension: int, assumption: str \| None = None, nonlinear: bool = False, name: str \| None = None) -> Study	Define a static solid-mechanics study with concise engineering syntax.
function	static_membrane(*, name: str \| None = None) -> Study	Define a two-dimensional finite-kinematics membrane study.
function	steady_heat_transfer(*, dimension: int, name: str \| None = None) -> Study	Define steady heat conduction, including source, flux, and convection.
function	first_order_transient(*, physics: str, dimension: int, assumption: str \| None = None, name: str \| None = None, procedure: str \| None = None) -> Study	Define a first-order transient study.
function	transient(*, physics: str, dimension: int, assumption: str \| None = None, name: str \| None = None, procedure: str \| None = None) -> Study	Compatibility alias for first_order_transient.
function	transient_heat_transfer(*, dimension: int, name: str \| None = None) -> Study	Define an implicit first-order heat-transfer study.
function	viscoelastic_solid(*, dimension: int = 3, assumption: str \| None = None, name: str \| None = None) -> Study	Define quasi-static small-strain generalized-Maxwell evolution.
function	harmonic_solid(*, dimension: int = 3, assumption: str \| None = None, name: str \| None = None) -> Study	Define a direct steady-state harmonic solid-mechanics study.
function	nonlinear_transient(*, physics: str, dimension: int, assumption: str \| None = None, name: str \| None = None, procedure: str \| None = None) -> Study	Define a nonlinear time-domain study.
function	creep_solid(*, dimension: int = 3, assumption: str \| None = None, name: str \| None = None) -> Study	Define an implicit quasi-static creep study.
function	second_order_dynamics(*, physics: str, dimension: int, assumption: str \| None = None, name: str \| None = None, procedure: str \| None = None) -> Study	Define a second-order dynamics study.
function	implicit_dynamics(*, physics: str, dimension: int, assumption: str \| None = None, method: str = 'newmark', name: str \| None = None) -> Study	Define second-order dynamics with a Standard/implicit preference.
function	explicit_dynamics(*, physics: str, dimension: int, assumption: str \| None = None, name: str \| None = None) -> Study	Define second-order dynamics with an Explicit preference.
function	dynamic_solid(*, dimension: int, assumption: str \| None = None, method: str = 'explicit', name: str \| None = None) -> Study	Define structural dynamics without repeating the physics name.
function	modal_solid(*, dimension: int, assumption: str \| None = None, name: str \| None = None) -> Study	Define a linear structural modal analysis.

agentfem.mesh

Kind	Public object	Purpose
class	FEMMesh	DOLFINx mesh plus optional cell and facet tags.
class	TagSummary	Summary of integer mesh tags on one topological entity dimension.
class	MeshSummary	Human- and agent-readable mesh summary.
class	BoundaryRegion	Named exterior boundary region on a mesh.
class	CellRegion	Named cell/material region on a mesh.
class	NodeRegion	Named source-node region, including high-order geometry nodes.
function	import_gmsh_model(model, comm: MPI.Comm = MPI.COMM_WORLD, *, model_rank: int = 0, gdim: int = 3) -> FEMMesh	Convert an in-memory Gmsh model to a DOLFINx mesh.
function	rectangle(lower, upper, cells, comm: MPI.Comm = MPI.COMM_WORLD, *, cell_type: str \| mesh.CellType = 'quadrilateral')	Create a structured 2D rectangular mesh.
function	cuboid(lower, upper, cells, comm: MPI.Comm = MPI.COMM_WORLD, *, cell_type: str \| mesh.CellType = 'hexahedron')	Create a structured 3D cuboid mesh.
function	read_gmsh_mesh(path: str \| Path, comm: MPI.Comm = MPI.COMM_WORLD, *, model_rank: int = 0, gdim: int = 3) -> FEMMesh	Read a .msh file with Gmsh and convert it to a DOLFINx mesh.
function	require_gmsh()	Return the optional Gmsh Python API used only for direct Gmsh import.
function	optional_mesh_capabilities() -> tuple[dependencies.DependencyStatus, ...]	Return availability of optional mesh-format integrations.
function	read_xdmf_mesh(path: str \| Path, comm: MPI.Comm = MPI.COMM_WORLD, *, mesh_name: str = 'mesh', cell_tags_name: str \| None = None, facet_tags_name: str \| None = None) -> FEMMesh	Read a DOLFINx XDMF mesh and optional cell/facet meshtags.
function	write_xdmf_mesh(path: str \| Path, domain, comm: MPI.Comm \| None = None, *, mode: str = 'w') -> None	Write a DOLFINx mesh to XDMF.
function	convert_external_mesh_to_xdmf(*args, **kwargs)	Convert Abaqus/NASTRAN/COMSOL-like external meshes to XDMF.
function	convert_external_mesh_bundle(*args, **kwargs)	Convert selected source topologies into explicit solver-domain files.
function	inspect_external_mesh(path, *, input_format: str \| None = None)	Inventory external element blocks and named sets before conversion.
function	inspect_abaqus_input(path: str \| Path) -> abaqus.AbaqusMigrationReport	Inventory Abaqus engineering semantics before conversion or solving.
function	inspect_abaqus_source_graph(path: str \| Path) -> abaqus.AbaqusSourceGraph	Resolve and fingerprint nested Abaqus input sources without flattening.
function	plan_abaqus_migration(path: str \| Path) -> 'AbaqusMigrationPlan'	Build a scope-aware Abaqus migration plan without solving.
function	create_abaqus_migration_project(source: str \| Path, destination: str \| Path, *, name: str \| None = None, created_with: str = 'unknown', user_material_sources: dict[str, str \| Path] \| None = None) -> dict[str, object]	Create a fail-closed AgentFEM project from inspected Abaqus sources.
function	assess_abaqus_native_lowering(path: str \| Path)	Assess whether an Abaqus source fits the reviewed native subset.
function	lower_abaqus_migration_project(project: str \| Path, *, reviewed_by: str, unit_system: str, activate: bool = False, force: bool = False) -> dict[str, object]	Emit an explicitly reviewed native draft from a migration project.
function	supported_abaqus_element_types(*, family: str \| None = None) -> tuple[str, ...]	Return Abaqus declarations with explicit AgentFEM import semantics.
function	split_gmsh_physical_interface(*args, **kwargs)	Lower named Gmsh physical cell/surface groups to a split interface.
function	read_abaqus_mesh(path: str \| Path, converted_path: str \| Path, comm: MPI.Comm = MPI.COMM_WORLD, *, cell_type: str \| None = None, reuse_conversion: bool = True) -> abaqus.AbaqusMeshImport	Convert and read an Abaqus mesh while retaining source node labels.
function	external_mesh_formats() -> dict[str, str]	Return common external formats supported through optional meshio.
function	read_converted_xdmf(conversion, comm: MPI.Comm = MPI.COMM_WORLD, *, mesh_name: str = 'Grid', tag_grid_name: str = 'Grid') -> FEMMesh	Read a :class:mesh.formats.MeshConversionResult into DOLFINx.
function	summarize_tags(tags) -> TagSummary \| None	Summarize a DOLFINx meshtags object.
function	summarize_mesh(domain, cell_tags = None, facet_tags = None) -> MeshSummary	Return local/global mesh size and tag summaries.
function	require_tags(tags, required: int \| tuple[int, ...] \| list[int], *, name: str = 'tags', comm = None) -> None	Raise if required tags are absent globally.
function	require_cell_tags(cell_tags, required: int \| tuple[int, ...] \| list[int], *, comm = None) -> None	Require cell/material region tags.
function	require_facet_tags(facet_tags, required: int \| tuple[int, ...] \| list[int], *, comm = None) -> None	Require boundary/facet tags.
function	boundary(domain, marker, *, name: str = 'boundary', tag: int = 1) -> BoundaryRegion	Create a named exterior boundary region from a geometric marker.
function	tagged_boundary_region(domain, facet_tags, *, tag: int, name: str = 'tagged_boundary', marker = None) -> BoundaryRegion	Create a boundary whose canonical selection is an imported facet tag.
function	audit_boundary_region(region: BoundaryRegion, *, strict: bool = False) -> dict[str, object]	Inspect a boundary's identity, size, orientation, and tag/marker agreement.
function	face(domain, *, axis: str \| int, value: float, name: str \| None = None, tag: int = 1, tolerance: float \| None = None) -> BoundaryRegion	Create a planar exterior boundary region such as x = 0.
function	boundary_region(domain, marker, *, name: str = 'boundary', tag: int = 1) -> BoundaryRegion	Alias for boundary when a more explicit name reads better.
function	cell_region(domain, cell_tags = None, *, tag: int, name: str = 'cell_region', marker = None) -> CellRegion	Create a named cell/material region.
function	region_measure(location)	Return a region's restricted measure or pass through a measure.
function	region_marker(location)	Return a region's marker or pass through a marker callable.
function	cells(domain, *, name: str, where, tag: int = 1) -> CellRegion	Create a named cell region from a selector.
function	partition_cells(domain, **regions) -> RegionSet	Partition mesh cells into named cell regions.
function	partition_boundaries(domain, **regions) -> RegionSet	Create named exterior boundary regions from selectors.
function	locate_cells(domain, marker)	Locate cells using a geometrical marker.
function	mark_cells(domain, cells, tag: int)	Create cell meshtags for a set of cells.
function	mark_cell_regions(domain, tag_to_marker: dict[int, object])	Create cell meshtags from several geometric cell markers.
function	tag_field(domain, tags, *, name: str = 'Tag')	Create a DG0 visualization field from cell tags.
function	locate_boundary_facets(domain, marker)	Locate exterior facets using a geometrical marker.
function	mark_facets(domain, facets, tag: int)	Create a meshtags object for a set of facets.
function	mark_boundary_facets(domain, marker, tag: int)	Locate and tag exterior facets in one step.
function	boundary_measure(domain, facet_tags = None)	Create a boundary integration measure.
function	cell_measure(domain, cell_tags = None)	Create a domain integration measure.
function	facet_normal(domain)	Return the outward facet normal for boundary models.
function	tagged_boundary_measure(domain, marker, tag: int)	Locate/tag exterior facets and return (ds, facet_tags).
function	from_arrays(*, cells, coordinates, coordinate_element, comm = None, partitioner = None)	Create a DOLFINx mesh through explicit topology/geometry keywords.
class	CellCompatibility	One meshio-style source cell mapped to an AgentFEM solver topology.
class	TopologyCapability	One narrowly scoped, evidence-bearing runtime topology capability.
class	TopologyCompatibility	Runtime solver-topology support independent of source element names.
function	compatibility_matrix() -> tuple[CellCompatibility, ...]	Return the complete, deterministic neutral-geometry matrix.
function	describe_cell(source_cell_type: str) -> CellCompatibility	Describe a meshio-style cell name without guessing equivalence.
function	describe_topology(topology: str) -> TopologyCompatibility	Describe one runtime cell topology without inferring formulation.
function	from_geometry_spec(specification: Mapping[str, object], *, resolution: int = 32, comm: MPI.Comm = MPI.COMM_WORLD)	Create an :class:agentfem.mesh.FEMMesh from a public geometry spec.
class	RegionSet	Named collection of regions sharing one mesh tag object.
class	CellGradientOperator	Reusable local sparse operator from cell values to owned-cell gradients.
class	CellGradientReconstruction	Owned-cell gradients and conditioning evidence for one reconstruction.
class	CellGradientStencil	One owned cell's compact linear gradient stencil.
function	cell_gradient_operator(domain, *, rings: int = 2, weight_power: float = 1.0, condition_limit: float = 10000000000.0) -> CellGradientOperator	Precompute a reusable, compact cell-gradient operator from geometry.
function	owned_cell_measures(domain) -> np.ndarray	Integrate one physical measure for every owned mesh cell.
function	reconstruct_cell_gradient(domain, cell_values, *, rings: int = 2, weight_power: float = 1.0, condition_limit: float = 10000000000.0) -> CellGradientReconstruction	Build and apply a cell-gradient operator in one convenience call.
class	CellNeighborhood	Owned interior-facet adjacency plus explicit partition evidence.
class	CellNeighborhoodGeometry	Geometric evidence for every pair in a :class:CellNeighborhood.
class	CellPairDifference	Directional cell-value difference on every interior-facet pair.
class	CellStencilNeighborhood	All locally visible interior pairs touching an owned cell.
class	InteriorFacetGeometry	Geometric scale and direction for one interior-facet cell pair.
class	InteriorFacetPair	Two cells adjacent to one owned interior facet on the current partition.
function	cell_neighborhood(domain) -> CellNeighborhood	Return every owned interior facet and its two adjacent cells.
function	cell_neighborhood_geometry(domain, neighborhood: CellNeighborhood \| CellStencilNeighborhood \| None = None) -> CellNeighborhoodGeometry	Attach centroids, facet midpoints, and pair distances to a neighborhood.
function	cell_pair_directional_difference(geometry: CellNeighborhoodGeometry, cell_values) -> CellPairDifference	Difference local/ghost cell values along each center-to-center line.
function	cell_stencil_neighborhood(domain) -> CellStencilNeighborhood	Return all local interior pairs needed by owned-cell reconstruction.
class	Selector	Boolean selector evaluated on coordinate arrays.
function	ball(center, radius: float) -> Selector	Select points inside a 3D ball.
function	box(lower, upper) -> Selector	Select points inside an axis-aligned box.
function	disk(center, radius: float) -> Selector	Select points inside a 2D disk.
function	layer(axis: str \| int, lower = None, upper = None) -> Selector	Select points inside a coordinate interval along one axis.
function	plane(axis: str \| int, value: float, *, tolerance: float = 1e-12) -> Selector	Select points near a coordinate plane such as x = 0.
function	where(predicate, *, name: str \| None = None) -> Selector	Create a selector from a vectorized coordinate predicate.

agentfem.models

Kind	Public object	Purpose
function	model_api(level: str = 'core') -> tuple[str, ...]	Return the recommended Model vocabulary at one discovery level.
function	model_api_contract(level: str = 'all') -> tuple[dict[str, object], ...]	Return machine-readable lifecycle metadata for Model methods.
class	Model	Finite-element model registry for humans and agents.
function	create(*, study, mesh = None, name: str = 'model', units = None) -> Model	Create a lightweight model registry.

agentfem.fields

Kind	Public object	Purpose
class	Field	Tensor-like finite-element field with immediate-value algebra.
class	UnknownField	Finite-element unknown bundle for application-level workflows.
class	DisplacementPressureUnknown	Mixed displacement/pressure unknown for hybrid solid mechanics.
class	VelocityPressureUnknown	Taylor--Hood velocity/pressure unknown for incompressible flow.
function	scalar_unknown(domain, *, name: str = 'Unknown', degree: int = 1, value = 0.0) -> UnknownField	Create a scalar finite-element unknown.
function	vector_unknown(domain, *, name: str = 'Unknown', degree: int = 1, dim: int \| None = None, value = 0.0) -> UnknownField	Create a vector finite-element unknown.
function	displacement(domain, *, degree: int = 1, dim: int \| None = None, value = 0.0) -> UnknownField	Create a displacement unknown for mechanics workflows.
function	displacement_pressure(domain, *, displacement_degree: int = 2, pressure_degree: int = 0, pressure_family: str = 'DG', name: str = 'DisplacementPressure') -> DisplacementPressureUnknown	Create a mixed displacement/pressure unknown.
function	velocity_pressure(domain, *, velocity_degree: int = 2, pressure_degree: int = 1, name: str = 'VelocityPressure') -> VelocityPressureUnknown	Create a Taylor--Hood incompressible-flow unknown.
function	temperature(domain, *, degree: int = 1, value = 0.0) -> UnknownField	Create a temperature unknown for heat-transfer workflows.
function	wrap(function, *, name: str \| None = None) -> Field	Wrap a DOLFINx function as an AgentFEM field.
function	unwrap(field_or_function)	Return the underlying DOLFINx function when given an AgentFEM field.
function	empty_like(field_or_function, *, name: str \| None = None) -> Field	Create a zero-valued field with the same function space.
function	compute(expression, *, name: str \| None = None) -> Field	Return a computed field.
function	assign(target, source) -> None	Assign a scalar, compatible field, or DOLFINx function into target.
function	dot(left, right) -> float	Return the distributed algebraic dot product of two compatible fields.
function	weighted_dot(left, weights, right = None) -> float	Return left^T diag(weights) right for compatible fields.
function	norm(field, *, weight = None) -> float	Return the distributed algebraic norm of a field.
function	require_same_space(left, right) -> None	Raise if two fields/functions are not on the same function space.
function	same_space(left, right) -> bool	Return whether two fields/functions share the same function space.

agentfem.materials

Kind	Public object	Purpose
function	learned(specification)	Bind a learned-constitutive specification to an active provider.
class	MaterialAssetError	A project material asset could not be loaded unambiguously.
function	load(source: str \| Path, *, model: str \| None = None, symbol: str \| None = None, role: str = 'mechanical') -> MaterialDefinition	Load a packaged card by name or an explicitly selected Python asset.
function	load_python(path: str \| Path, *, symbol: str \| None = None, role: str = 'mechanical') -> MaterialDefinition	Load one trusted project-owned Python material with source provenance.
class	MaterialBehavior	One named behavior carried by a physical material definition.
class	MaterialCompatibility	Pre-solve explanation of one material/Study pairing.
class	MaterialDefinition	Physical material identity plus independently reusable behaviors.
function	define(name: str, behavior = None, *, mechanical = None, thermal = None, behaviors: Mapping[str, object] \| None = None, source: str = 'user_defined', reference_only: bool = False, metadata: Mapping[str, object] \| None = None) -> MaterialDefinition	Define a named material without coupling it to one Study.
class	MaterialRecord	Material-library record before conversion to a constitutive law.
function	list_material_models(name: str) -> tuple[str, ...]	List model names available for one material.
function	list_materials(*, model: str \| None = None) -> tuple[str, ...]	List available material names, optionally filtered by model.
function	load_material(name: str, model: str \| None = None)	Load one material model and return a constitutive material object.
function	load_definition(name: str, model: str \| None = None)	Load a packaged reference card as a named material definition.
function	material_record(name: str) -> MaterialRecord	Return a validated material record without constructing a model object.
function	register_material(name: str, data: dict, *, overwrite: bool = False) -> None	Register or override a material record in memory.
class	ElasticAnisotropic2DProperties	2D linear-elastic properties using engineering-strain Voigt notation.
class	ElasticAnisotropic3DProperties	3D linear elasticity in engineering-strain Voigt notation.
class	ElasticIsotropicProperties	Isotropic linear-elastic material properties.
class	ThermoElasticIsotropicProperties	Isotropic thermoelastic and heat-conduction properties.
class	TemperatureDependentThermoElasticProperties	Isotropic thermoelastic properties containing constants or tables.
class	TemperaturePropertyTable	One material property tabulated against absolute temperature.
function	temperature_property(temperatures, values, **kwargs) -> TemperaturePropertyTable	Create an inspectable temperature-dependent material property.
class	FiberFrame	Two independent structural directions for a woven reinforcement.
class	MaterialFrame	Right-handed orthonormal material frame in the reference configuration.
class	OrientedMaterial	One constitutive behavior combined with a separate material frame.
function	fiber_frame(warp, weft, *, name: str = 'fiber_frame') -> FiberFrame	Build two independent reference yarn directions.
function	material_frame(primary, secondary = None, *, normal = None, name: str = 'material_frame', evolution: str = 'fixed') -> MaterialFrame	Build a checked right-handed orthonormal material frame from axes.
function	oriented(material, orientation: MaterialFrame, *, name: str \| None = None) -> OrientedMaterial	Assign an elastic material to a reusable material frame.
class	LaminateResponse	Classical-laminate generalized forces plus recoverable ply fields.
class	LaminateSection	Ordered composite plies evaluated by classical laminate theory.
class	Ply	One named lamina with a material, thickness, and section orientation.
class	PlyPointResult	Strain and stress at one stable laminate section point.
class	SectionPoint	Stable through-thickness integration-point identity.
function	laminate(plies: Sequence[Ply], *, name: str = 'laminate', reference_surface_offset: float = 0.0, source: str = 'user_defined', metadata: Mapping[str, object] \| None = None) -> LaminateSection	Create an ordered laminate section without coupling it to an element.
function	laminate_from_abaqus_section(section, materials_by_name: Mapping[str, object], *, reviewed_by: str, name: str \| None = None) -> LaminateSection	Lower one reviewed Abaqus composite-section inventory.
function	ply(material, thickness: float, *, angle: float = 0.0, name: str = 'ply', integration_points: int = 3) -> Ply	Create one ply; angle follows the industry-standard degree convention.
function	transformed_reduced_stiffness(stiffness_voigt, angle_degrees: float) -> np.ndarray	Rotate one planar engineering-Voigt stiffness into section axes.
function	validate_material_record(name: str, record: dict) -> None	Validate one material-centered library record.

agentfem.constitutive

Kind	Public object	Purpose
class	ConstitutiveCapability	What a material capability can truthfully do in this release.
function	capabilities() -> tuple[ConstitutiveCapability, ...]	Return all constitutive capabilities in stable name order.
function	capability(name: str) -> ConstitutiveCapability	Return one capability or raise with the available names.
class	ArrheniusPowerLawCreep	Temperature-dependent Mises power-law creep.
class	CreepDamageState	Local creep strain and scalar continuum-damage state.
class	CreepDamageUpdate	Accepted material-point increment from a creep-damage law.
class	CreepHistory	Integrated piecewise-constant stress history.
class	ImplicitCreepBatchUpdate	Vectorized backward-Euler updates for one homogeneous material region.
class	ImplicitCreepState	Committed small-strain creep state at one integration point.
class	ImplicitCreepUpdate	Backward-Euler material-point update and consistent tangent.
class	IsotropicPowerLawCreepMaterial	Isotropic elasticity with an implicit Mises power-law creep branch.
class	KachanovRabotnovCreep	Classical scalar Kachanov--Rabotnov creep-damage coupling.
class	ModifiedThetaProjection	Three-parameter modified-theta representation of a creep curve.
class	PowerLawCreep	Mises time-hardening creep law.
class	SinhCreep	Stress-sensitive hyperbolic-sine Mises creep law.
function	integrate_stress_history(law: PowerLawCreep, times, interval_stresses) -> CreepHistory	Integrate a piecewise-constant scalar or tensor stress history.
function	isotropic_power_law(*, young: float \| None = None, poisson: float \| None = None, density: float \| None = None, elastic: ElasticIsotropicProperties \| ThermoElasticIsotropicProperties \| TemperatureDependentThermoElasticProperties \| None = None, coefficient: float, stress_exponent: float, time_exponent: float = 0.0, reference_stress: float = 1.0, reference_time: float = 1.0, name: str = 'isotropic power-law creep') -> IsotropicPowerLawCreepMaterial	Create one Abaqus-style material record with elastic and creep data.
function	isotropic_arrhenius_power_law(*, young: float \| None = None, poisson: float \| None = None, density: float \| None = None, elastic: ElasticIsotropicProperties \| ThermoElasticIsotropicProperties \| TemperatureDependentThermoElasticProperties \| None = None, coefficient: float, stress_exponent: float, activation_energy: float, reference_temperature: float, time_exponent: float = 0.0, reference_stress: float = 1.0, reference_time: float = 1.0, gas_constant: float = 8.31446261815324, name: str = 'isotropic Arrhenius power-law creep') -> IsotropicPowerLawCreepMaterial	Create elasticity plus a globally consumable Arrhenius creep law.
function	anisotropic_stress_2d(displacement, properties: ElasticAnisotropic2DProperties, *, study = None, orientation = None)	2D anisotropic stress from engineering-strain Voigt stiffness.
function	anisotropic_stress_3d(displacement, properties: ElasticAnisotropic3DProperties, *, study = None, orientation = None)	3D anisotropic stress with an optional independent material frame.
function	anisotropic_elastic_2d(*, stiffness_voigt, density: float, name: str = 'anisotropic elastic 2D') -> ElasticAnisotropic2DProperties	Create 2D anisotropic linear-elastic properties.
function	anisotropic_elastic_3d(*, stiffness_voigt, density: float, name: str = 'anisotropic elastic 3D') -> ElasticAnisotropic3DProperties	Create 3D anisotropic elasticity in engineering Voigt notation.
function	estimate_elastic_wave_speeds(material) -> tuple[float, float]	Return approximate (pressure_speed, shear_speed) for a material.
function	isotropic_stress(displacement, properties: ElasticIsotropicProperties, *, study = None, temperature = None)	Small-strain isotropic stress, sigma(u).
function	isotropic_elastic(*, young: float, density: float, poisson: float, name: str = 'isotropic elastic') -> ElasticIsotropicProperties	Create isotropic linear-elastic properties.
function	thermal_expansion_stress(temperature, properties, *, study = None, dimension = None)	Return positive C:epsilon_thermal for an equivalent thermal load.
function	thermal_strain(temperature, properties, *, dimension: int)	Return isotropic free thermal strain alpha (T-T_ref) I.
function	thermoelastic(*, young: float, density: float, poisson: float, thermal_expansion: float, conductivity: float, specific_heat: float, reference_temperature: float = 293.15, name: str = 'isotropic thermoelastic') -> ThermoElasticIsotropicProperties	Create one material record for sequential thermal-stress workflows.
function	temperature_dependent_thermoelastic(*, young, density: float, poisson, thermal_expansion, conductivity, specific_heat, reference_temperature: float = 293.15, name: str = 'temperature-dependent isotropic thermoelastic') -> TemperatureDependentThermoElasticProperties	Create tabulated properties for sequential thermo-mechanics.
function	thermoelastic_stress(displacement, temperature, properties, *, study = None)	Small-strain isotropic stress including thermal eigenstrain.
function	orthotropic_plane_stress_2d(*, ex: float, ey: float, nuxy: float, gxy: float, density: float, name: str = 'orthotropic plane-stress elastic 2D') -> ElasticAnisotropic2DProperties	Create 2D orthotropic plane-stress elastic properties.
function	orthotropic_elastic_3d(*, ex: float, ey: float, ez: float, nuxy: float, nuxz: float, nuyz: float, gxy: float, gxz: float, gyz: float, density: float, name: str = 'orthotropic elastic 3D') -> ElasticAnisotropic3DProperties	Create a reciprocal, positive-definite 3D orthotropic material.
function	stress(displacement, properties, *, study = None, temperature = None)	Dispatch to the matching elastic stress relation.
function	stress_from_strain(strain_tensor, properties, *, study = None, temperature = None)	Return elastic stress from an explicit strain tensor.
class	DecoupledFabricSurface	Independent yarn tension, trellising shear, and bending channels.
class	DecoupledFibrousShell	Provider-neutral local law for a fibre-specific shell layer.
class	FabricFormingAssessment	Dimensionless utilization report for declared forming limits.
class	FabricFormingLimits	User-declared forming limits, separate from constitutive calibration.
class	FabricKinematics	Non-orthogonal warp/weft surface deformation measures.
class	FabricLayer	One named computational layer in a shared-kinematics stack.
class	FabricLayerResponse	Stable identity and local response of one stack layer.
class	FabricMembraneExpressions	Symbolic observables used by the global woven-membrane provider.
class	FabricStack	Named layers sharing one surface deformation.
class	FabricStackResponse	Per-layer response without inventing one ambiguous aggregate frame.
class	FabricSurfaceResponse	Local generalized resultants, tangent, energy, and physical measures.
class	FibrousShellExpressions	Symbolic generalized shell energy and conjugate resultants.
class	FibrousShellResponse	Local shell channels without prescribing an element technology.
class	SurfaceConstitutive	Extension contract for a local surface constitutive response.
class	TabulatedResponse	Piecewise-linear scalar constitutive channel with an energy primitive.
function	decoupled_fabric_surface(*, frame: FiberFrame, warp_tension: TabulatedResponse, weft_tension: TabulatedResponse, shear: TabulatedResponse, bending_stiffness, tension_only: bool = True, name: str = 'fabric_surface') -> DecoupledFabricSurface	Public AgentFEM object.
function	decoupled_fibrous_shell(membrane: DecoupledFabricSurface, *, transverse_shear_stiffness, in_plane_bending_stiffness, normal_bending_stiffness, name: str = 'fibrous_shell') -> DecoupledFibrousShell	Create a local fibrous-shell law with four independent energy channels.
function	fabric_forming_limits(*, warp_tensile_strain: float \| None = None, weft_tensile_strain: float \| None = None, trellising_angle: float \| None = None, angle_unit: str = 'degree', in_plane_curvature: float \| None = None, normal_curvature: float \| None = None) -> FabricFormingLimits	Create forming-screening limits with an explicit angle unit.
function	fabric_layer(material: DecoupledFabricSurface, *, name: str, physical_layer_ids = ()) -> FabricLayer	Create one named layer for a shared-kinematics fabric stack.
function	fabric_membrane_internal_virtual_work(displacement, test, material: DecoupledFabricSurface, *, measure = None)	Return the in-plane fabric membrane residual from stored energy.
function	fabric_stack(layers, *, name: str = 'fabric_stack') -> FabricStack	Create a checked multilayer fabric asset with stable layer identities.
function	tabulated_response(abscissa, ordinate, *, name: str = 'response', symmetry: str = 'none', extrapolation: str = 'error') -> TabulatedResponse	Public AgentFEM object.
class	CompositeStrengths2D	Plane-stress unidirectional-ply strengths in material axes.
class	Hashin2D	Plane-stress Hashin fibre/matrix initiation indices.
class	LaminateFailureAssessment	Stable section-point assessments and the governing laminate location.
class	MaximumStress2D	Sign-aware maximum-stress screening for a plane-stress ply.
class	PlyFailureAssessment	Per-mode initiation indices and proportional first-failure factor.
class	PlyFailureCriterion	Extension contract for one material-axis ply failure surface.
class	PlyPointFailureAssessment	One laminate section point assessed in its ply material frame.
class	TsaiWu2D	Plane-stress Tsai--Wu surface with explicit normalized interaction.
function	assess_laminate_failure(section, response, strengths: CompositeStrengths2D \| Mapping[str, CompositeStrengths2D], *, criterion: str \| PlyFailureCriterion = 'hashin_2d') -> LaminateFailureAssessment	Assess all recovered section points in their named ply material axes.
function	assess_ply_failure(material_stress, strengths: CompositeStrengths2D, *, criterion: str \| PlyFailureCriterion = 'hashin_2d') -> PlyFailureAssessment	Assess one plane-stress material-axis state without evolving damage.
function	composite_strengths_2d(*, xt: float, xc: float, yt: float, yc: float, s12: float, name: str = 'composite_strengths_2d') -> CompositeStrengths2D	Create the common five-strength plane-stress ply contract.
class	BasquinCurve	Fully reversed stress-life curve sigma_a = sigma_f' (2N)^b.
class	FatigueAssessment	Auditable stress-life assessment derived from one scalar history.
class	FatigueBlock	One constant-amplitude block for cumulative-damage assessment.
class	StressCycle	One rainflow-counted stress cycle or residual half-cycle.
class	TabulatedSNCurve	Log-log interpolated S-N data with explicit extrapolation policy.
function	assess_history(history, curve, *, ultimate_strength: float \| None = None, source: str \| None = None) -> FatigueAssessment	Return cycles, Miner damage, and repeated-history life together.
function	assess_result_history(result, history_name: str, curve, *, ultimate_strength: float \| None = None) -> FatigueAssessment	Assess one named SimulationResult history with provenance.
function	damage_from_history(history, curve, *, ultimate_strength: float \| None = None) -> float	Rainflow count a stress history and apply Palmgren-Miner damage.
function	goodman_amplitude(stress_amplitude: float, mean_stress: float, ultimate_strength: float) -> float	Return fully reversed amplitude using the linear Goodman correction.
function	life_scale_factor(blocks: Iterable[FatigueBlock], curve) -> float	Return the number of repeated block sequences to Miner damage one.
function	miner_damage(blocks: Iterable[FatigueBlock], curve) -> float	Return Palmgren-Miner cumulative damage sum(n_i / N_i).
function	rainflow_cycles(history) -> tuple[StressCycle, ...]	Count full and residual half-cycles from a scalar stress history.
function	turning_points(history) -> np.ndarray	Return endpoints and local reversals from a scalar stress history.
class	FiniteStrainJ2Logarithmic	Multiplicative finite-strain J2 plasticity with Hencky elasticity.
function	finite_strain_j2_logarithmic(*, young: float, poisson: float, yield_stress: float, hardening_modulus: float = 0.0, tangent_relative_step: float = 2e-06, tangent_evaluation: str = 'analytic_spectral') -> FiniteStrainJ2Logarithmic	Create the logarithmic finite-strain J2 material provider.
class	FiniteStrainKinematics	Standard total-Lagrangian kinematics derived from one displacement.
class	MixedNeoHookeanProperties	Isochoric Neo-Hookean solid with an independent pressure field.
class	MooneyRivlinProperties	Two-parameter isotropic Mooney-Rivlin finite-strain solid.
class	NeoHookeanProperties	Compressible Neo-Hookean parameters derived from E and nu.
class	PlaneStressNeoHookeanProperties	Compressible Neo-Hookean membrane with locally relaxed thickness.
function	kinematics(displacement) -> FiniteStrainKinematics	Return the standard finite-strain kinematic measures for u.
function	mooney_rivlin(*, shear_modulus: float, first_invariant_fraction: float, bulk_modulus: float, density: float \| None = None, name: str = 'compressible Mooney-Rivlin') -> MooneyRivlinProperties	Create a three-dimensional compressible Mooney-Rivlin solid.
function	mooney_rivlin_plane_stress(*, shear_modulus: float, first_invariant_fraction: float, density: float \| None = None, name: str = 'incompressible plane-stress Mooney-Rivlin') -> MooneyRivlinProperties	Create the exact incompressible sheet reduction of Eq. (17).
function	mixed_condensed_energy_value(deformation_gradient, properties: MixedNeoHookeanProperties) -> float	Evaluate the pressure-eliminated quadratic-volumetric energy.
function	mixed_neo_hookean(*, young: float \| None = None, poisson: float \| None = None, shear_modulus: float \| None = None, bulk_modulus: float \| None = None, density: float \| None = None, name: str = 'mixed Neo-Hookean') -> MixedNeoHookeanProperties	Create a quadratic-volumetric mixed Neo-Hookean material.
function	neo_hookean(*, young: float, poisson: float, density: float \| None = None, name: str = 'compressible Neo-Hookean') -> NeoHookeanProperties	Create a compressible Neo-Hookean material.
function	neo_hookean_plane_stress(*, young: float, poisson: float, density: float \| None = None, name: str = 'plane-stress compressible Neo-Hookean') -> PlaneStressNeoHookeanProperties	Create a finite-strain plane-stress Neo-Hookean membrane material.
function	plane_stress_first_piola_value(deformation_gradient, properties: PlaneStressNeoHookeanProperties) -> np.ndarray	Return the condensed numerical in-plane first Piola stress.
function	plane_stress_out_of_plane_first_piola_from_gradient(F, properties: PlaneStressNeoHookeanProperties)	Return the condensed P33 residual for diagnostics and tests.
function	plane_stress_thickness_stretch_value(deformation_gradient, properties: PlaneStressNeoHookeanProperties, *, tolerance: float = 1e-12, maximum_iterations: int = 30) -> float	Solve the local P33=0 condition for one numerical 2x2 F.
function	plane_stress_uniaxial_deformation_gradient(axial_stretch: float, properties: PlaneStressNeoHookeanProperties \| MooneyRivlinProperties, *, tolerance: float = 1e-12, maximum_iterations: int = 30) -> np.ndarray	Return homogeneous uniaxial F2 with traction-free lateral faces.
function	supports_hyperelastic_study(properties, *, dimension: int, assumption) -> bool	Return whether one material has a formulation for the declared Study.
class	MaterialPointBatchResult	Responses from one atomic integration-point constitutive update.
class	MaterialQuadratureResponse	Quadrature stress/tangent fields sharing one typed state transaction.
class	SmallStrainMaterialQuadratureResponse	Rollback-safe local state and fields for a generic small-strain material.
function	update_material_points(material: UserMaterial \| QuadratureMaterialMap, state: MaterialQuadratureState, *, deformation_gradient_old, deformation_gradient_new, time: float, time_increment: float, properties = (), temperature = None, temperature_increment = None, field_variables = None, commit: bool = False) -> MaterialPointBatchResult	Update every local quadrature point as one rollback-safe transaction.
class	ChabocheCombinedHardening	Small-strain J2 plasticity with nonlinear combined hardening.
class	ChabocheState	History for small-strain combined isotropic/kinematic hardening.
class	J2LinearIsotropicHardening	Rate-independent von Mises plasticity with linear isotropic hardening.
class	J2PlasticState	History variables for small-strain isotropic J2 plasticity.
class	J2Update	Result of one radial-return material-point update.
class	PlasticEnergyIncrement	One accepted plastic substep written as an explicit energy ledger.
class	TabulatedIsotropicHardening	Piecewise-linear yield radius as a function of equivalent plastic strain.
class	UniaxialPlasticState	History variables for the exact one-dimensional counterpart.
function	chaboche(*, young: float, poisson: float, yield_stress: float, backstresses: Iterable[tuple[float, float]], isotropic_saturation: float = 0.0, isotropic_rate: float = 0.0, isotropic_hardening: TabulatedIsotropicHardening \| None = None, name: str = 'Chaboche combined hardening') -> ChabocheCombinedHardening	Create a combined-hardening material from (C, gamma) pairs.
function	update_uniaxial(total_strain: float, material: J2LinearIsotropicHardening, state: UniaxialPlasticState \| None = None) -> tuple[float, UniaxialPlasticState]	Return stress and state for a one-dimensional bilinear material test.
function	von_mises(stress) -> float	Return sqrt(3/2 s:s) for a symmetric Cauchy stress.
class	ChabocheQuadratureState	Committed/trial integration-point state for combined-hardening J2.
class	CreepQuadratureState	Committed/trial integration-point state for implicit 3D creep.
class	J2QuadratureState	Committed/trial integration-point state for 3D small-strain J2.
class	MaterialQuadratureState	Schema-lowered committed/trial state for one material provider.
class	QuadratureField	A DOLFINx quadrature function with an explicit NumPy point view.
class	QuadratureMaterialMap	Cell-region material dispatch shared by stateful solid procedures.
class	QuadratureTransaction	Shared trial/commit/rollback contract for integration-point state.
function	j2_quadrature_state(domain, material, *, degree: int = 2, scheme: str = 'default')	Create the quadrature state matching one homogeneous J2 family.
function	load_portable_quadrature_state(path, state, *, material = None) -> None	Collectively restore committed state under a changed MPI partition.
function	save_portable_quadrature_state(path, state, *, material = None) -> Path	Collectively save committed state by physical cell and point identity.
class	AbaqusUserMaterialBridge	Truthful capability description for an intended UMAT/UHYPER adapter.
class	BatchedUserMaterial	Optional vectorized extension of the scalar finite-strain contract.
class	MaterialPointBatchInput	Ordered finite-strain material-point updates for one atomic call.
class	MaterialPointBatchOutput	Ordered responses from one finite-strain provider batch call.
class	MaterialPointInput	Solver-neutral finite-strain input for one material-point update.
class	MaterialPointOutput	Constitutive response returned to a nonlinear finite-element driver.
class	MaterialStateSchema	Named layout for portable, auditable material internal variables.
class	MaterialStateVariable	One named entry in a solver-neutral material state vector.
class	MaterialTangentCheck	Numerical-differentiation evidence for one declared material tangent.
class	MaterialTangentConvention	Declared stress/kinematic pair represented by a material Jacobian.
class	UserMaterial	Protocol implemented by native or adapted material-point models.
function	check_material_tangent(material: UserMaterial, point: MaterialPointInput, *, relative_step: float = 1e-07, tolerance: float = 1e-05) -> MaterialTangentCheck	Compare a declared dP/dF against fixed-state finite differences.
function	validated_material_batch_update(material: UserMaterial, request: MaterialPointBatchInput) -> MaterialPointBatchOutput	Evaluate a provider batch, falling back to the scalar contract.
function	validated_material_update(material: UserMaterial, point: MaterialPointInput) -> MaterialPointOutput	Run one material update and verify the complete solver contract.
class	MaterialApplicabilityError(status: str, message: str) -> None	A material refused to extrapolate or accepted state was invalid.
class	MaterialParameter	One named, unit-aware constitutive parameter.
class	MaterialParameterSchema	Stable named parameter layout for native and external materials.
class	SmallStrainMaterialPointBatchInput	Vectorized request for all local points owned by one provider call.
class	SmallStrainMaterialPointBatchOutput	Validated vectorized constitutive response.
class	SmallStrainMaterialPointInput	One three-dimensional small-strain constitutive update request.
class	SmallStrainMaterialPointOutput	Stress, consistent tangent, state, energy and diagnostics for one point.
class	SmallStrainMaterialTangentCheck	Public AgentFEM object.
class	SmallStrainUserMaterial	Scalar update protocol implemented by native or external providers.
function	check_small_strain_material_tangent(material: SmallStrainUserMaterial, point: SmallStrainMaterialPointInput, *, relative_step: float = 1e-07, tolerance: float = 1e-05) -> SmallStrainMaterialTangentCheck	Check the discrete d sigma / d epsilon at fixed old state.
function	small_strain_matrix_to_tensor(matrix, convention: MaterialTangentConvention) -> np.ndarray	Expand a declared 6x6 small-strain tangent to a minor-symmetric tensor.
function	small_strain_tangent_convention(*, shear_convention: str = 'tensor') -> MaterialTangentConvention	Return the canonical 3D Cauchy/small-strain matrix convention.
function	validated_small_strain_batch_update(material: SmallStrainUserMaterial, request: SmallStrainMaterialPointBatchInput, *, require_usable: bool = True) -> SmallStrainMaterialPointBatchOutput	Use a provider batch kernel when available, otherwise a scalar fallback.
function	validated_small_strain_update(material: SmallStrainUserMaterial, point: SmallStrainMaterialPointInput, *, require_usable: bool = True) -> SmallStrainMaterialPointOutput	Run one update and fail closed on schema or convention drift.
class	ArrheniusShift	Arrhenius time-temperature shift factor.
class	GeneralizedMaxwell	Small-strain generalized-Maxwell relaxation spectrum.
class	IsotropicGeneralizedMaxwell	Small-strain isotropic generalized-Maxwell solid for global FEM.
class	IsotropicHarmonicModuli	Complex isotropic moduli at one angular frequency.
class	IsotropicMaxwellUpdate	One exact tensor-valued generalized-Maxwell trial update.
class	MaxwellState	Committed state for a generalized-Maxwell material point.
class	PronyFit	Deterministic fixed-spectrum relaxation fit with validation evidence.
class	ViscoelasticUpdate	One trial material-point update that can be committed atomically.
class	WLFShift	Williams--Landel--Ferry time-temperature shift factor.
function	fit_relaxation_prony(time, modulus, relaxation_times, *, nonnegative: bool = True, name: str = 'fitted_prony_series') -> PronyFit	Fit a relaxation spectrum for user-declared relaxation times.
function	isotropic_generalized_maxwell(**kwargs) -> IsotropicGeneralizedMaxwell	Create an isotropic tensor Prony solid from instantaneous properties.
function	standard_linear_solid(*, equilibrium_modulus: float, relaxing_modulus: float, relaxation_time: float, shift: WLFShift \| ArrheniusShift \| None = None, name: str = 'standard_linear_solid') -> GeneralizedMaxwell	Create a standard linear solid as one Maxwell branch in parallel.

agentfem.eigenstrains

Kind	Public object	Purpose
class	ThermalEigenstrain	Isotropic free strain driven by an explicit temperature field.
class	PrescribedEigenstrain	Explicit stress-free strain tensor supplied by an expert workflow.
function	thermal(temperature, *, name: str = 'thermal_eigenstrain') -> ThermalEigenstrain	Create an explicit thermal eigenstrain source.
function	prescribed(value, *, name: str = 'prescribed_eigenstrain', source: str = 'prescribed') -> PrescribedEigenstrain	Create a checked expert-defined eigenstrain source.

agentfem.constraints

Kind	Public object	Purpose
class	ConstraintCapabilities	Solver-facing capability contract for one kinematic constraint.
class	ConstraintDualEvidence	Provider-owned force and optional work-conjugate coordinate.
function	constraint_dual(constraint, *, force, coordinate = None, resultant = None, distribution = None, diagnostics = None, role = 'mpc_constraint', source = 'provider_dual', complete = True) -> ConstraintDualEvidence	Create provider evidence tied to one named constraint asset.
function	collect_provider_duals(constraints, problem, *, extra = ()) -> tuple[ConstraintDualEvidence, ...]	Collect converged dual evidence from active constraint providers.
class	DirichletConstraint	Strong Dirichlet constraint and its optional mutable value object.
class	RigidModeAudit	Rank test of strong constraints against analytical rigid modes.
function	rigid_mode_audit(target, constraints, *, tolerance: float = 1e-10) -> RigidModeAudit	Report rigid translations/rotations removed by strong constraints.
class	TimeDependentDirichlet	Dirichlet constraint driven by an amplitude.
class	RemoteDisplacementConstraint	Rigid boundary motion prescribed about a named reference point.
class	PrescribedValuePath	Update ordinary strong boundary values along a normalized step path.
function	prescribed_value_path(constraints) -> PrescribedValuePath	Create a normalized load-factor driver from registered constraints.
function	dirichlet_constraints(constraints) -> tuple[object, ...]	Return concrete Dirichlet assets from nested model constraint sets.
function	constraint_assets(constraints) -> tuple[object, ...]	Return every concrete asset from nested constraint containers.
function	scalar_dirichlet(V, marker = None, value = 0.0, *, location = None, on = None, name: str = 'dirichlet') -> DirichletConstraint	Semantic wrapper for scalar essential boundary data.
function	component_dirichlet(V, component: int, marker = None, value = 0.0, *, location = None, on = None, name: str = 'dirichlet') -> DirichletConstraint	Semantic wrapper for vector-component essential boundary data.
function	axisymmetric_plane_strain(displacement, *, value: float = 0.0, name: str = 'axisymmetric_plane_strain') -> DirichletConstraint	Constrain u_z everywhere in an (r, z) meridian model.
function	axisymmetric_axis(displacement, *, location = None, on = None, value: float = 0.0, name: str = 'axisymmetric_axis') -> DirichletConstraint	Enforce radial regularity u_r=0 on the revolution axis.
function	dirichlet(V, marker = None, value = 0.0, *, component: int \| None = None, location = None, on = None, name: str = 'dirichlet') -> DirichletConstraint	Create scalar or component-wise Dirichlet data from one entry point.
function	time_dependent_component_dirichlet(target, component: int, marker = None, value = None, *, amplitude = None, location = None, on = None, name: str = 'time_dependent_dirichlet') -> TimeDependentDirichlet	Create a component-wise Dirichlet constraint driven by an amplitude.
function	time_dependent_scalar_dirichlet(target, marker = None, value = None, *, amplitude = None, location = None, on = None, name: str = 'time_dependent_dirichlet') -> TimeDependentDirichlet	Create a scalar Dirichlet constraint driven by an amplitude.
function	apply_dirichlet_bcs(function, bcs) -> None	Apply strong Dirichlet boundary conditions to a function vector.
function	fixed(target, *, location = None, on = None, value = 0.0, components: int \| tuple[int, ...] \| list[int] \| None = None, name: str \| None = None) -> 'ConstraintSet'	Create fixed-value Dirichlet constraints for an application field.
function	fixed_component(target, component: int, *, location = None, on = None, value = 0.0, name: str \| None = None)	Create a fixed-value constraint for one vector component.
function	symmetry(target, *, on = None, location = None, normal_axis: int \| str, value = 0.0, name: str \| None = None) -> 'ConstraintSet'	Apply an axis-aligned solid-mechanics symmetry condition.
function	roller(target, *, on = None, location = None, normal_axis: int \| str, value = 0.0, name: str \| None = None) -> 'ConstraintSet'	Alias for an axis-aligned frictionless roller/support condition.
function	pin(target, *, at, components = None, value = 0.0, tolerance: float = 1e-10, name: str = 'pin')	Create an explicit point support at one physical coordinate.
function	fixed_all(target, *, location = None, on = None, value = 0.0, name: str \| None = None)	Create a scalar/all-dof fixed-value constraint.
function	prescribed(target, *, on = None, location = None, value = 0.0, component = None, components = None, name: str \| None = None)	Create prescribed scalar or vector-component values.
function	clamped(target, *, on = None, location = None, value = 0.0, name: str \| None = None)	Fix every displacement component on a support boundary.
function	prescribed_temperature(target, value, *, on = None, location = None, name: str \| None = None)	Prescribe temperature on a named boundary.
function	remote_displacement(target, *, reference_point, on = None, location = None, translation = None, rotation = None, system = None, name: str = 'remote_displacement') -> RemoteDisplacementConstraint	Prescribe rigid translation/rotation of a solid boundary.
class	PeriodicProjectionConstraint	Projection-style periodic constraint for explicit field updates.
function	periodic(target, *, master, slave, match_axis: str \| int = 0, method: str = 'projection', tolerance: float = 1e-12, name: str = 'periodic')	Create a periodic constraint with an explicit method choice.
function	periodic_projection(target, *, master, slave, match_axis: str \| int = 0, tolerance: float = 1e-12, name: str = 'periodic_projection') -> PeriodicProjectionConstraint	Create component-wise dof pairs for projection-style periodicity.
function	constraint_capabilities(constraint) -> ConstraintCapabilities \| None	Return the public capability contract of a known constraint asset.
function	constraint_balance_contract(constraints, *, provider_duals = ()) -> dict[str, object]	Describe whether strong-reaction force/work diagnostics are complete.
function	validate_solver_compatibility(*, constraints, analysis: str, procedure: str \| None = None, comm_size: int = 1)	Validate constraint/procedure compatibility before assembly or solve.
class	PeriodicConstraintSpec	Geometric description of a periodic constraint.
class	ConstraintSet	Collection of constraints used by assembly or field updates.
class	AbaqusPeriodicConstraint	Periodic equations controlled by prescribed or free reference dofs.
class	AffineMacroGradientLift	Exact full-DOF lift for independent macroscopic gradient changes.
class	AffineReduction	Sparse serial representation of u = T q + offset.
class	DeformationGradientPath	Piecewise-linear macroscopic deformation-gradient history.
class	DistributedAffineReduction	Homogeneous correction space for a distributed affine constraint.
function	abaqus_periodic_cell(target, *, nodes: AbaqusNodeTable, equations: AbaqusEquationSet, anchor_node: int, reference_nodes, deformation_gradient = None, deformation_gradient_path: DeformationGradientPath \| None = None, control_displacements = None, tolerance: float = 1e-09, name: str = 'abaqus_periodic_cell') -> AbaqusPeriodicConstraint	Create exact periodic equations and explicit macro-control semantics.
function	deformation_gradient_path(coordinates: Iterable[float], gradients: Iterable[Iterable[Iterable[float]]], *, name: str = 'deformation_gradient_path') -> DeformationGradientPath	Create an inspectable unload/reload or non-proportional macro path.
class	RectangularPeriodicMPC	Exact rectangular periodic relation and construction diagnostics.
function	rectangular_periodic_mpc(target, *, axes = None, bcs = (), tolerance: float \| None = None, name: str = 'rectangular_periodic_mpc') -> RectangularPeriodicMPC	Constrain maximum faces of a rectangular mesh to minimum faces.
class	LinearKinematicControl	One scalar generalized coordinate q = sum(a_i u_i).
class	PointKinematicTerm	One coefficient multiplying one displacement component at a point.
function	linear_kinematic_control(target, terms, *, name: str = 'linear_kinematic_control', unit: str \| None = None, tolerance: float = 1e-10) -> LinearKinematicControl	Create a scalar control with a provider-owned conjugate reaction.
function	point_kinematic_term(point, *, component: int, coefficient: float, name: str = 'point_displacement') -> PointKinematicTerm	Create one readable term of a generalized displacement coordinate.
class	ConstraintDualHistory	Restartable force--coordinate evidence from accepted nonlinear states.

agentfem.amplitudes

Kind	Public object	Purpose
class	Amplitude	Named scalar history function.
class	AmplitudeAudit	Portable endpoint and range evidence for one amplitude.
function	as_amplitude(value, *, name: str = 'amplitude') -> Amplitude	Convert a scalar, callable, or Amplitude into an Amplitude.
function	constant(value: float, *, name: str = 'constant') -> Amplitude	Create a constant amplitude.
function	ramp(start_value: float = 0.0, end_value: float = 1.0, *, start_time: float = 0.0, end_time: float = 1.0, name: str = 'ramp') -> Amplitude	Create a clipped linear ramp amplitude.
function	smooth_step(start_value: float = 0.0, end_value: float = 1.0, *, start_time: float = 0.0, end_time: float = 1.0, name: str = 'smooth_step') -> Amplitude	Create a clipped half-cosine transition with zero endpoint slopes.
function	tabular(times, values, *, name: str = 'tabular', left: float \| None = None, right: float \| None = None) -> Amplitude	Create a linearly interpolated tabular amplitude.
function	sine(amplitude: float = 1.0, frequency: float = 1.0, *, phase: float = 0.0, offset: float = 0.0, name: str = 'sine') -> Amplitude	Create a sinusoidal amplitude.
function	gaussian_modulated_sine(amplitude: float, frequency: float, width: float, *, center: float \| None = None, phase: float = 0.0, name: str = 'gaussian_modulated_sine') -> Amplitude	Create a Gaussian-windowed sinusoidal pulse.
class	AmplitudeBasis	Named, serializable loading modes with a declared coefficient order.
function	basis(*components: Amplitude, name: str = 'amplitude_basis', coefficient_names: Sequence[str] \| None = None, coordinate_name: str = 'time', coordinate_unit: str \| None = 's', value_unit: str \| None = None) -> AmplitudeBasis	Create a named basis for control, inverse, and transient studies.

agentfem.loads

Kind	Public object	Purpose
function	time_dependent_component_dirichlet(V, component: int, marker, time_function)	Compatibility wrapper for time-dependent component Dirichlet constraints.
function	apply_dirichlet_bcs(function, bcs) -> None	Apply strong Dirichlet boundary conditions to a function vector.
function	constant_time_function(value: float, name: str = 'constant') -> amplitudes.Amplitude	Represent a constant value with the same interface as transient data.
class	BodyLoad	Domain source/body-force term for a weak form.
class	GravityLoad	Gravity body force rho g over a material domain.
class	CentrifugalLoad	Rotating-frame body force rho omega x (omega x r) outward.
class	BoundaryLoad	Boundary flux/traction term for a weak form.
class	PressureLoad	Pressure load pulled back to a reference boundary measure.
class	HydrostaticPressureLoad	Pressure varying with elevation from a reference free surface.
class	SurfaceResultantLoad	A requested total force uniformly distributed over a reference boundary.
class	DistributedCouplingLoad	Force and moment distributed over a continuum surface.
class	NeumannLoad	Natural boundary condition applied through the weak-form right hand side.
class	AmplitudeLoad	A spatial load multiplied by one reusable scalar amplitude.
class	LoadSet	Ordered collection of weak-form load terms.
function	load_assets(loads, *, unwrap_amplitudes: bool = False) -> tuple[object, ...]	Return concrete loads from nested public load containers.
function	body_load(value, measure = ufl.dx, *, name: str = 'body_load', domain = None, target = None) -> BodyLoad	Create a domain source/body-force load.
function	body_force(value, *, domain = None, target = None, measure = ufl.dx, system = None, name: str = 'body_force') -> BodyLoad	Create a mechanical body-force load in global or local components.
function	gravity(acceleration, *, density, domain = None, target = None, region = None, measure = None, system = None, name: str = 'gravity') -> GravityLoad	Create a gravity load from acceleration and material density.
function	centrifugal(angular_velocity, *, density, center = None, domain = None, target = None, region = None, measure = None, name: str = 'centrifugal') -> CentrifugalLoad	Create the outward body force caused by constant angular velocity.
function	heat_source(value, *, domain = None, target = None, measure = ufl.dx, name: str = 'heat_source') -> BodyLoad	Create a volumetric heat-source load.
function	boundary_load(value, measure = None, *, location = None, on = None, name: str = 'boundary_load') -> BoundaryLoad	Create a generic natural boundary load.
function	neumann(value, measure, *, name: str = 'neumann_load') -> NeumannLoad	Create a Neumann force/flux/traction term for the weak RHS.
function	with_amplitude(load, amplitude, *, domain = None, name: str \| None = None) -> AmplitudeLoad	Drive an existing load by a scalar amplitude multiplier.
function	traction(value, *, location = None, on = None, system = None, name: str = 'traction') -> BoundaryLoad	Create a traction in global or an explicit local coordinate system.
function	surface_force(resultant, *, location = None, on = None, reference_measure: float \| None = None, study = None, system = None, name: str = 'surface_force') -> SurfaceResultantLoad	Distribute a total reference-configuration force over a boundary.
function	distributing_coupling(force, *, moment = None, reference_point = None, location = None, on = None, system = None, name: str = 'distributing_coupling') -> DistributedCouplingLoad	Distribute force/moment over a surface with tributary-area weighting.
function	remote_force(force, *, reference_point, moment = None, location = None, on = None, system = None, name: str = 'remote_force') -> DistributedCouplingLoad	Apply a reference-point force/moment through a continuum surface.
function	pressure(value, *, location = None, on = None, normal = None, configuration: str = 'reference', displacement = None, name: str = 'pressure') -> PressureLoad	Create inward pressure on a reference or current boundary.
function	hydrostatic_pressure(*, density, gravity, reference_point, reference_pressure = 0.0, on = None, location = None, clip_at_zero: bool = True, configuration: str = 'reference', displacement = None, name: str = 'hydrostatic_pressure') -> HydrostaticPressureLoad	Create p = p_ref + rho g dot (x - x_ref) on a boundary.
function	heat_flux(value, *, location = None, on = None, name: str = 'heat_flux') -> BoundaryLoad	Create a prescribed heat flux applied on a boundary region.
function	body_force_form(force, test_function)	Create a body-force virtual-work form.
function	boundary_traction_form(traction, test_function, ds_measure)	Create a boundary-traction virtual-work form.

agentfem.project

Kind	Public object	Purpose
function	new_run_id(now: datetime \| None = None) -> str	Return a sortable, collision-resistant identifier for one execution.
function	recommended_workspace(path: str \| Path \| None = None) -> Path	Return the cross-installation project root recommended on this host.
class	WorkspaceReport	Custody report for the conventional installed-use project directory.
function	workspace_report(path: str \| Path \| None = None, *, link: str \| Path \| None = None) -> WorkspaceReport	Inspect project custody without changing the filesystem.
function	storage_custody(path: str \| Path) -> dict[str, object]	Describe whether a project path survives removal of its runtime.
function	protect_workspace(path: str \| Path \| None = None, *, link: str \| Path \| None = None) -> WorkspaceReport	Create or migrate the conventional workspace to durable host storage.
class	ProjectConfig	Operational metadata for an AgentFEM case directory.
function	discover(start: str \| Path \| None = None) -> ProjectConfig	Find the nearest agentfem.toml from start upward.
class	RunContext	Filesystem and identity contract shared by scripts, CLIs, GUIs, and agents.
function	current_run(*, project_root: str \| Path \| None = None, project_name: str \| None = None) -> RunContext	Return the CLI-provided context or create one for direct Python use.

agentfem.results

Kind	Public object	Purpose
class	CheckpointRecord	One restart asset with an explicit portability boundary.
class	FieldResult	A named live field or an external field artifact.
class	HistoryResult	Time, load, or iteration history with a fixed value shape.
class	ResultQuantity	One scalar or fixed-shape quantity of interest.
class	SimulationResult	Scientific results and artifacts from one simulation.
function	dof_statistics(field) -> dict[str, float \| int]	Return global finite dof statistics for a DOLFINx-like field.
function	from_solution(solution, *, name: str = 'result', field_name: str \| None = None, unit: str \| None = None, metadata: Mapping[str, object] \| None = None, scientific_inputs: Mapping[str, object] \| None = None) -> SimulationResult	Wrap one solved field in a :class:SimulationResult.
class	ForceMomentResultant	Integrated force and moment about an explicit physical point.
class	PathSample	Values sampled along one straight physical-space path.
class	PointSample	Point values with distinct mesh coverage and numerical validity masks.
class	RectilinearGridSample	A finite-element field sampled on a Cartesian observation grid.
class	StaticForceBalance	Global algebraic force equilibrium for one linear static solid.
class	StaticWorkBalance	Energy closure including proportional prescribed boundary motion.
function	average(expression, *, measure = ufl.dx, comm = None)	Return the measure-weighted global average of an expression.
function	boundary_resultant(traction, *, on, study = None)	Integrate traction/flux over a named physical boundary.
function	field_extrema(field, *, magnitude: bool = False, location: bool = False) -> dict[str, object]	Return MPI-global field extrema, optionally with physical locations.
function	free_body_resultant(*, boundary_tractions = (), body_forces = (), about) -> ForceMomentResultant	Integrate boundary and volume forces into one free-body resultant.
function	external_force_resultant(problem)	Return the MPI-global resultant of a static problem's assembled load.
function	integral(expression, *, measure = ufl.dx, comm = None)	Return the global integral of a scalar, vector, or tensor expression.
function	l2_norm(expression, *, measure = ufl.dx, comm = None) -> float	Return sqrt(integral(inner(value, value))) globally.
function	probe(field, *, at, padding: float = 1e-10)	Return one scalar, vector, or tensor field value at a physical point.
function	quadrature_extrema(expression, domain, *, degree: int = 4) -> tuple[float, float]	Return global min/max sampled at Basix quadrature points.
function	reaction_resultant(problem, *, on = None, component: int \| None = None, name: str = 'RF')	Return an MPI-global strong-constraint reaction resultant.
function	region_average(expression, *, on, study = None)	Return a measure-weighted average over a named mesh region.
function	region_integral(expression, *, on, study = None)	Integrate over a named region using its declared physical measure.
function	region_measure(*, on, study = None) -> float	Return the global length, area, or volume of a named region.
function	sample_path(field, *, start, end, count: int = 101, padding: float = 1e-10, missing: str = 'raise') -> PathSample	Sample a field along the straight segment from start to end.
function	sample_points(field, points, *, padding: float = 1e-10, missing: str = 'raise', return_info: bool = False) -> np.ndarray \| PointSample	Evaluate a finite-element field at common physical points under MPI.
function	sample_rectilinear_grid(field, *, bbox, shape, reduction: str \| None = None, component: int \| None = None, padding: float = 1e-10) -> RectilinearGridSample	Sample a scalar or vector field on a 2D/3D rectilinear grid.
function	section_resultant(stress, *, on, normal = None, about = None) -> ForceMomentResultant	Integrate section force and moment from a Cauchy/nominal stress field.
function	static_force_balance(problem, *, constraints = (), provider_duals = ()) -> StaticForceBalance	Evaluate R + F = 0 for a converged static solid.
function	static_work_balance(problem, *, constraints = (), provider_duals = ()) -> StaticWorkBalance	Evaluate linear-static work including nonzero strong Dirichlet data.
class	PreparedProjection(problem, output) -> None	A reusable L2 projection with one assembled mass matrix.
function	fabric_membrane_cell_fields(displacement, material, *, variables = ('FABRIC_GENERALIZED_STRAIN', 'FABRIC_GENERALIZED_RESULTANT', 'FABRIC_WARP_DIRECTION', 'FABRIC_WEFT_DIRECTION', 'SENER'), degree: int = 0, scale: float = 1.0) -> tuple[object, ...]	Project standard woven-membrane observables for inspection and export.
function	fabric_stack_membrane_cell_fields(displacement, material, *, variables = ('FABRIC_GENERALIZED_STRAIN', 'FABRIC_GENERALIZED_RESULTANT', 'FABRIC_WARP_DIRECTION', 'FABRIC_WEFT_DIRECTION', 'SENER'), degree: int = 0) -> tuple[object, ...]	Project unambiguous per-layer observables for a fabric stack.
function	fabric_stack_result_manifest(material) -> tuple[dict[str, object], ...]	Return the stable public mapping between layers and field prefixes.
function	prepare_projection(expression, *, domain = None, family: str = 'DG', degree: int = 0, name: str = 'ProjectedField', weight = 1.0) -> PreparedProjection	Prepare a reusable global L2 projection with a static mass operator.
function	project(expression, *, domain = None, family: str = 'DG', degree: int = 0, name: str = 'ProjectedField', weight = 1.0)	Return the global L2 projection of a UFL expression.
function	project_piecewise(terms, *, domain = None, family: str = 'DG', degree: int = 0, name: str = 'ProjectedField', weight = 1.0)	Project region-dependent expressions into one finite-element field.
function	small_strain_cell_fields(displacement, properties, *, study = None, variables = ('S', 'E', 'MISES', 'SENER'), degree: int = 0) -> tuple[object, ...]	Create standard projected fields for linear small-strain elasticity.
function	small_strain_partition_fields(displacement, assignments, *, study = None, variables = ('S', 'E', 'MISES', 'SENER'), degree: int = 0, eigenstrains = ()) -> tuple[object, ...]	Create standard fields for a complete regional material partition.
class	FieldRecovery	A reviewable conversion from constitutive evidence to a field.
function	cell_average_recovery() -> FieldRecovery	Return the standard scientific integration-point recovery policy.
function	recover_integration_point_field(source, *, name: str \| None = None, policy: FieldRecovery \| None = None, unit: str \| None = None, description: str = '') -> FieldResult	Recover one QuadratureField without hiding its processing history.
function	add_execution_trace(result, events: Iterable[object]) -> tuple[dict[str, object], ...]	Attach one complete execution trace and its standard histories.
function	execution_records(events: Iterable[object]) -> tuple[dict[str, object], ...]	Normalize solver events without depending on a particular procedure.
function	complete_result(step, result, *, output = None, fields = (), strict_output: bool = False, deformation_scale: float = 0.0, metadata: Mapping[str, object] \| None = None)	Complete output and metadata through one compatibility-safe path.
function	execution_context(step)	Return the context bound by :meth:Model.step, when available.
class	HarmonicAverageResponse	Measure-weighted complex average with rank-local assembly.
class	HarmonicProbeResponse	Complex finite-element point probe with framework-owned MPI selection.
class	HarmonicResponse	One scalar response computed locally and reduced by AgentFEM.
function	harmonic_average_response(name: str, evaluate, *, on, study = None, unit: str \| None = None, description: str = '') -> HarmonicAverageResponse	Declare a complex region average safe for serial and MPI sweeps.
function	harmonic_probe_response(name: str, evaluate, *, at, component: int \| None = None, padding: float = 1e-10, unit: str \| None = None, description: str = '') -> HarmonicProbeResponse	Declare a complex point response safe for serial and MPI sweeps.
function	harmonic_response(name: str, evaluate, *, unit: str \| None = None, description: str = '', reduction: str \| None = None) -> HarmonicResponse	Declare a scalar response with an explicit rank-local reduction.
class	HillMandelIncrement	Finite-strain macrohomogeneity evidence over one accepted increment.
class	HomogenizedFrame	Macroscopic response reconstructed from one periodic-cell state.
class	HomogenizedAlgorithmicTangent	Condensed current-state tangent for a prescribed periodic cell.
class	LiveFiniteStrainCellFields	Derived cell fields refreshed from active Explicit state at output time.
class	MixedJ2ElasticEnergyDiagnostics	Volume-normalized energy identity for mixed finite-strain J2 fields.
class	StressStateInvariants	Three-dimensional Cauchy-stress invariants with explicit validity.
function	cauchy_stress_invariants(stress, *, relative_tolerance: float = 1e-12) -> StressStateInvariants	Return triaxiality and normalized Lode state from a 3D Cauchy tensor.
function	finite_strain_dynamic_cell_fields(displacement, velocity, properties, *, variables = ('SENER', 'KED', 'J'), pressure = None, density = None) -> LiveFiniteStrainCellFields	Create reusable SED/KED/stress fields for Explicit saved frames.
function	finite_strain_diagnostics(displacement, *, constraint = None, quadrature_degree: int = 4) -> dict[str, object]	Evaluate reusable physical checks for a finite-deformation solution.
function	finite_strain_cell_fields(displacement, properties, *, variables = ('F', 'E', 'GREEN', 'P', 'S', 'MISES', 'J', 'SENER', 'EVOL'), pressure = None, velocity = None, density = None) -> tuple[object, ...]	Create requested standard P0 finite-strain cell fields.
function	homogenize_periodic_cell(displacement, properties, *, pressure = None, accepted_fields = None, macro_deformation_gradient, cell_reference_volume: float, load_factor: float) -> HomogenizedFrame	Return volume-normalized macroscopic finite-strain response.
function	homogenize_periodic_path(snapshots, properties, *, constraint) -> tuple[HomogenizedFrame, ...]	Homogenize every saved state of an affine periodic-cell analysis.
function	homogenized_algorithmic_tangent(problem, constraint, *, linear_solver_options = None) -> HomogenizedAlgorithmicTangent	Condense a converged periodic-cell Jacobian to :math:d\bar P/d\bar F.
function	hill_mandel_increment(start_snapshot, snapshot, properties, *, constraint, start_frame: HomogenizedFrame \| None = None, frame: HomogenizedFrame \| None = None) -> HillMandelIncrement	Compare microscopic and macroscopic first-Piola work increments.
function	hill_mandel_periodic_path(snapshots, properties, *, constraint, frames = None) -> tuple[HillMandelIncrement, ...]	Evaluate Hill--Mandel evidence between consecutive saved states.
function	mixed_j2_elastic_energy_diagnostics(*, deformation_gradient, pressure, inverse_bulk_modulus, condensed_elastic_energy_density, reference_volume: float) -> MixedJ2ElasticEnergyDiagnostics	Audit mixed J2 elastic energy using aligned accepted quadrature fields.
function	write_homogenized_csv(path: str \| Path, frames, *, hill_mandel = (), increment_info = ()) -> Path	Write flattened macro tensors in a human-readable table.
function	write_homogenized_history(path: str \| Path, frames, *, hill_mandel = (), increment_info = ()) -> Path	Write an exact, compact NumPy history for plotting and ML reuse.
class	FieldVariable	Stable public meaning of one result variable.
function	field_variable(name: str, *, finite_strain: bool = False) -> FieldVariable	Resolve a standard variable, including the context-dependent E alias.
function	preselected_fields(*, physics: str, finite_strain: bool = False) -> tuple[str, ...]	Return the engineering-default field set for one physics context.
function	resolve_field_variables(names, *, finite_strain: bool = False) -> tuple[FieldVariable, ...]	Resolve aliases, preserve request order, and remove duplicates.
class	WeightedFieldStatistics	Global weighted distribution with explicit field semantics.
function	weighted_field_statistics(values, weights, *, quantiles: Sequence[float] = (0.05, 0.5, 0.95), thresholds: Sequence[float] = (), location: str, representation: str, comm = None) -> WeightedFieldStatistics	Return exact global statistics from physical sample weights.
class	PerformanceEvidence	Comparable execution-cost evidence for one result lifecycle.
function	attach_performance(result, *, stages: Mapping[str, object], solution = None, source = None, scope: str = 'solve_result_call')	Attach normalized performance evidence and return result.
function	performance_evidence(*, stages: Mapping[str, object], solution = None, source = None, scope: str = 'solve_result_call') -> PerformanceEvidence	Build collective, rank-consistent evidence from local stage timings.
class	FiniteStrainDiagnosticRequest	Record physical admissibility and constraint checks.
class	HistoryRequest	Evaluate one scientific quantity on every accepted output frame.
class	OutputPlan	One declarative output contract for a completed finite-strain step.
class	PeriodicCellHistoryRequest	Record complete tensor histories for a finite-strain periodic cell.
class	ProbeHistoryRequest	Record a field value at one physical point on every accepted frame.
class	PresentationOutput	Optional serial rendering from the scientific XDMF/HDF5 series.
class	SolverHistoryRequest	Record accepted-increment convergence history.
class	SourceNodeHistoryRequest	Record U and current coordinates using source-mesh node labels.
function	finite_strain_checks(*, constraint = None, quadrature_degree: int = 4) -> FiniteStrainDiagnosticRequest	Public AgentFEM object.
function	history(name: str, evaluate, *, coordinate = None, unit: str \| None = None, abscissa_name: str \| None = None, abscissa_unit: str \| None = None, description: str = '') -> HistoryRequest	Create a scalar history evaluated on accepted analysis states.
function	output_plan(directory, *, field: FieldOutput \| None = None, requests = (), presentation: PresentationOutput \| None = None, basename: str = 'results') -> OutputPlan	Create a complete finite-strain output plan.
function	periodic_cell_history(constraint, *, basename: str = 'homogenized_history') -> PeriodicCellHistoryRequest	Public AgentFEM object.
function	probe_history(name: str, *, at, field = None, component: int \| None = None, unit: str \| None = None, description: str = '') -> ProbeHistoryRequest	Create a point-probe history for accepted static or transient states.
function	presentation(*, comparison: bool = True, animation: str \| None = 'gif', scalar: str = 'UMAG', fps: int = 2) -> PresentationOutput	Public AgentFEM object.
function	solver_history() -> SolverHistoryRequest	Public AgentFEM object.
function	source_node_history(nodes, **points: int) -> SourceNodeHistoryRequest	Public AgentFEM object.
class	FieldOutput	What fields to save, how often, and in which configuration.
class	FieldOutputArtifacts	Files and final live fields produced by one output plan.
class	ResultFieldArtifacts	One completed-result field dataset and its explicit layout contract.
class	UnifiedXDMFTimeSeries(path, *, deformation_scale: float = 0.0, store_reference_geometry: bool = True, compression: int = 4, primary_name: str \| None = None, primary_semantic_name: str \| None = None) -> None	Incremental single-grid XDMF/HDF5 writer for serial result histories.
function	field_output(*variables, every: int \| str \| None = None, intervals: int \| None = None, configuration: str = 'deformed', deformation_scale: float = 1.0, backend: str = 'xdmf') -> FieldOutput	Create a concise, inspectable field-output request.
function	read_unified_xdmf_series(xdmf_path) -> tuple[object, ...]	Read AgentFEM's compact XDMF/HDF5 frames as PyVista grids.
function	write_deformed_vtk_series(pvd_path, snapshots, cell_fields, *, deformation_scale: float = 1.0) -> tuple[Path, tuple[Path, ...]]	Write one deformed VTU grid per frame and a ParaView PVD collection.
function	write_parallel_vtk_series(path, snapshots, fields_by_frame) -> Path	Write collective single-dataset ParaView frames under MPI.
function	write_result_fields(result, path, *, time: float = 0.0, names = (), deformation_scale: float = 0.0) -> ResultFieldArtifacts	Write the live, visualization-ready fields of one SimulationResult.
function	write_unified_xdmf_series(xdmf_path, snapshots, cell_fields, *, deformation_scale: float = 1.0, store_reference_geometry: bool = True, compression: int = 4, primary_name: str \| None = None, primary_semantic_name: str \| None = None) -> Path	Write one temporal XDMF and one compressed HDF5 heavy-data file.
function	render_deformation_animation(undeformed_path, snapshots, nodes, output_path, *, fps: int = 2) -> Path	Render scale-one deformation history as GIF or MP4.
function	render_deformation_comparison(undeformed_path, deformed_path, output_path, *, scalar: str = 'DisplacementMagnitude') -> Path	Render side-by-side undeformed/deformed surfaces with PyVista.
function	render_unified_xdmf_animation(xdmf_path, output_path, *, scalar: str = 'UMAG', fps: int = 2) -> Path	Render a GIF or MP4 from AgentFEM's single XDMF/HDF5 series.
function	render_unified_xdmf_comparison(xdmf_path, output_path, *, scalar: str = 'UMAG') -> Path	Render the first and final grids from a unified XDMF series.
function	render_vtk_series_animation(frame_paths, output_path, *, scalar: str = 'UMAG', fps: int = 2) -> Path	Render a GIF directly from a combined-field deformed VTU series.

agentfem.steps

Kind	Public object	Purpose
class	AutomaticIncrementation	Adaptive load/time incrementation for one analysis step.
class	FixedIncrementation	A prescribed monotone load-factor path for one analysis step.
function	automatic(*, initial: float = 0.1, minimum: float = 1e-05, maximum: float = 0.25, max_increments: int = 100, max_cutbacks: int = 5, cutback_factor: float = 0.25, growth_factor: float = 1.5, fast_iterations: int = 4, slow_iterations: int = 10, maximum_inelastic_increment: float \| None = None) -> AutomaticIncrementation	Create inspectable Abaqus-style automatic incrementation.
function	fixed(increments: int) -> FixedIncrementation	Divide the normalized step interval into exactly increments parts.
function	at(*load_factors: float) -> FixedIncrementation	Create a prescribed, nonuniform load-factor path.
function	normalize(value = None, *, increments: int \| None = None, load_factors = None)	Normalize public and compatibility incrementation inputs.
class	MonotonicTargetAdvance	Accepted internal path used to reach one requested physical target.
function	advance_monotonic_targets(targets: Iterable[float], *, try_accept: Callable[[float], object \| None], initial_coordinate: float = 0.0, minimum_increment: float, maximum_cutbacks: int, coordinate_name: str = 'load', failure_message: Callable[[], str] \| None = None) -> tuple[MonotonicTargetAdvance, ...]	Reach requested monotonic targets with transactional bisection.
class	EngineeringStep	Named inherited activation state, separate from solver controls.
function	engineering_step(name: str, *, previous: EngineeringStep \| None = None, inherit_model_loads: bool = False, inherit_model_constraints: bool = True)	Public AgentFEM object.

agentfem.units

Kind	Public object	Purpose
class	UnitSystem	Named consistent base-unit contract attached to a model.
function	consistent(*, length, mass, time, temperature = 'K', name = 'consistent_units')	Declare the base units used consistently by all model inputs.
function	si(*, temperature = 'K') -> UnitSystem	Return the SI m-kg-s engineering contract.
function	n_mm_mpa(*, temperature = 'K') -> UnitSystem	Return the common mm-N-s-MPa consistent system.

agentfem.verification

Kind	Public object	Purpose
function	trust_rank(level: str) -> int	Return the ordered rank of one public trust level.
class	VerificationClaim	One explicit, machine-readable scientific acceptance claim.
class	VerificationReport	Trust decision derived from execution state and scientific claims.
class	QualityPolicy	Low-ceremony acceptance policy for one result or dataset boundary.
class	ConvergenceSample	One observable evaluated at a declared discretization size.
class	ConvergenceStudy	A coarse-to-fine mesh or time-step convergence sequence.
function	report(*claims: VerificationClaim, computed: bool = True, converged: bool = True, scope: str = 'simulation') -> VerificationReport	Concise public constructor for a verification report.
function	quality_policy(value: str \| QualityPolicy) -> QualityPolicy	Return one named public quality policy.
function	assess(result, quality: str \| QualityPolicy = 'engineering', *, claims: Iterable[VerificationClaim] = (), converged: bool \| None = None, required_quantities: Iterable[str] = (), required_histories: Iterable[str] = (), required_artifacts: Iterable[str] = (), attach: bool = True) -> VerificationReport	Apply a quality preset and inexpensive deterministic result checks.
function	convergence_study(name: str, observable: str, samples: Iterable[ConvergenceSample], *, discretization: str = 'mesh') -> ConvergenceStudy	Public AgentFEM object.

agentfem.assessments

Kind	Public object	Purpose
class	SequentialEnergyLedger	Layered evidence for a one-way heat-to-mechanics workflow.
function	sequential_energy_ledger(thermal_result, mechanical_result, *, field_history = None) -> SequentialEnergyLedger	Audit thermal and mechanical energy channels across sequential steps.
class	CreepDamageBlock	One dwell or service block for the time-fraction rule.
class	DwellInterval	One explicitly declared hold interval in a result time history.
function	creep_blocks_from_result(result, *, stress_history: str, temperature_history: str, dwells: Iterable[DwellInterval], rupture_time: Callable[[float, float], float], rupture_source: str, stress_reducer: str = 'maximum_absolute', temperature_reducer: str = 'maximum') -> tuple[CreepDamageBlock, ...]	Create source-identified creep blocks from named result histories.
class	CreepDamageAssessment	Auditable linear time-fraction assessment over service blocks.
class	InteractionDiagram	Declared creep/fatigue allowable boundary in damage coordinates.
class	CreepFatigueAssessment	Combined engineering assessment from independent damage consumers.
function	creep_time_fraction(blocks: Iterable[CreepDamageBlock]) -> CreepDamageAssessment	Evaluate the linear creep time-fraction rule for declared blocks.
function	interaction_diagram(*, points, name: str, source: str) -> InteractionDiagram	Create an explicit piecewise-linear creep/fatigue interaction curve.
function	linear_interaction() -> InteractionDiagram	Return the transparent reference boundary Dc + Df = 1.
function	creep_fatigue(*, fatigue: FatigueAssessment, creep: CreepDamageAssessment, interaction: InteractionDiagram \| None = None) -> CreepFatigueAssessment	Combine existing fatigue and creep assessments against one boundary.
function	creep_fatigue_from_result(result, *, fatigue_history: str, fatigue_curve, stress_history: str, temperature_history: str, dwells: Iterable[DwellInterval], rupture_time: Callable[[float, float], float], rupture_source: str, interaction: InteractionDiagram \| None = None, ultimate_strength: float \| None = None, stress_reducer: str = 'maximum_absolute', temperature_reducer: str = 'maximum') -> CreepFatigueAssessment	Build the engineering V1 assessment from named result histories.

agentfem.boundary_models

Kind	Public object	Purpose
class	ElasticFoundation	Distributed linear spring support on a solid boundary.
class	RigidObstaclePenaltyContact	Frictionless one-sided contact with a fixed rigid plane.
function	elastic_foundation(*, on = None, location = None, stiffness, mode: str = 'isotropic', normal = None, name: str = 'elastic_foundation') -> ElasticFoundation	Public AgentFEM object.
function	rigid_obstacle_contact(*, on = None, location = None, penalty, normal, initial_gap = 0.0, name: str = 'rigid_obstacle_contact') -> RigidObstaclePenaltyContact	Create conservative frictionless contact with one fixed rigid plane.
class	ConvectionBoundary	Linear convection -k grad(T).n = h (T - T_inf).
function	convection(*, on = None, location = None, coefficient, ambient_temperature, name: str = 'convection') -> ConvectionBoundary	Create a linear thermal convection boundary condition.

agentfem.campaigns

Kind	Public object	Purpose
class	ChoiceParameter	Finite categorical or policy parameter.
class	IntegerParameter	Bounded integer parameter.
class	ParameterSpace	Ordered scientific input schema for a campaign.
class	RealParameter	Bounded continuous parameter with optional units and log scaling.
class	SamplingPlan	Immutable, validated collection of parameter samples.
function	explicit(space: ParameterSpace, samples: Iterable[Mapping[str, object]], *, metadata: Mapping[str, object] \| None = None) -> SamplingPlan	Create a plan from caller-supplied samples.
function	full_factorial(space: ParameterSpace, levels: int \| Mapping[str, int] = 3) -> SamplingPlan	Create a full-factorial design in normalized coordinates.
function	latin_hypercube(space: ParameterSpace, count: int, *, seed: int = 0) -> SamplingPlan	Draw a reproducible Latin-hypercube design.
function	random(space: ParameterSpace, count: int, *, seed: int = 0) -> SamplingPlan	Draw reproducible independent uniform samples in normalized space.
class	Campaign(*, name: str, parameter_space: ParameterSpace, outputs: tuple[Quantity, ...], evaluate: Callable[[object], Mapping[str, object] \| CaseOutcome \| SimulationResult], build: Callable[[Mapping[str, object]], object] \| None = None, metadata: Mapping[str, object] \| None = None, scientific_inputs: Mapping[str, object] \| None = None, execution: ExecutionPolicy \| None = None) -> None	Build and evaluate a collection of immutable scientific cases.
class	CampaignCase	One immutable case in a campaign plan.
class	CampaignPlan	Immutable cases and their design-of-experiment evidence.
class	CampaignReport	Case-level evidence and the successful scientific dataset.
class	CaseOutcome	Successful case outputs plus links to scientific evidence.
class	CaseRunRecord	Execution evidence for one attempted case.
class	ExecutionPolicy	Declared execution behavior for the current campaign runner.
function	case_id(campaign_name: str, parameters: Mapping[str, object], *, schema_version: str = CAMPAIGN_SCHEMA_VERSION) -> str	Return a deterministic scientific case identity.
function	create(**kwargs) -> Campaign	Create a :class:Campaign using the public functional spelling.
function	local_processes(*, workers: int \| None = None, fail_fast: bool = False, resume: bool = True) -> ExecutionPolicy	Use spawned local processes for independent campaign cases.
class	CampaignSpecification	Validated declarative part of a campaign.
function	load_specification(path: str \| Path) -> CampaignSpecification	Load a safe JSON campaign specification.
function	specification_from_dict(record: Mapping[str, object]) -> CampaignSpecification	Validate a dictionary and construct a campaign specification.

agentfem.convergence

Kind	Public object	Purpose
class	ConvergenceAxis	One refinement coordinate with all other coordinates fixed explicitly.
class	ObservablePolicy	How one scalar, vector, event, or topology record is compared.
class	ConvergenceCheck	One observable checked along one explicitly selected refinement axis.
class	ConvergenceCertificate	Auditable multi-axis convergence decision for one CampaignReport.
function	axis(parameter: str, *, fixed: Mapping[str, object] \| None = None, discretization: str = 'mesh', characteristic: Characteristic = 'value') -> ConvergenceAxis	Public AgentFEM object.
function	observable(name: str, *, comparison: Comparison = 'relative', tolerance: float \| None = None, source: Source = 'output', path: str \| None = None, minimum_observed_order: float \| None = None, unit: str \| None = None) -> ObservablePolicy	Public AgentFEM object.
function	audit(report: CampaignReport, *, axes: tuple[ConvergenceAxis, ...], observables: tuple[ObservablePolicy, ...], output: str \| Path \| None = None) -> ConvergenceCertificate	Build a conservative convergence certificate from campaign evidence.

agentfem.checkpointing

Kind	Public object	Purpose
class	CheckpointPolicy	Automatic accepted-increment checkpoint cadence for transient steps.
function	every(increments: int, *, directory = 'checkpoints', final: bool = True, prefix: str \| None = None, keep_last: int \| None = None, portable: bool = False) -> CheckpointPolicy	Create an automatic checkpoint policy for accepted time increments.
function	save_harmonic_sweep_checkpoint(path, *, step_name: str, frequencies, records, scientific_inputs, field_identity: dict[str, object], execution_events = (), comm = MPI.COMM_WORLD)	Atomically publish a partition-independent scalar sweep ledger.
function	load_harmonic_sweep_checkpoint(path, *, step_name: str, frequencies, scientific_inputs, field_identity: dict[str, object], comm = MPI.COMM_WORLD) -> dict[str, object]	Validate and load a scalar harmonic sweep ledger without field mutation.
function	remove_harmonic_sweep_checkpoint(path, *, comm = MPI.COMM_WORLD) -> None	Collectively remove exactly one typed scalar sweep manifest.
function	save_transient_checkpoint(path, *, step_kind: str, step_name: str, procedure, dt: float, total_steps: int, completed_steps: int, state: dict[str, object], time_inputs: dict[str, object], accepted_times = (), execution_events = (), history_records = (), auxiliary_state: dict[str, object] \| None = None, portable: bool = False)	Write a transient restart, optionally with partition-independent state.
function	load_transient_checkpoint(path, *, step_kind: str, step_name: str, procedure, dt: float, total_steps: int, state: dict[str, object], time_inputs: dict[str, object]) -> dict[str, object]	Restore a transient state after validating its scientific identity.
function	save_portable_state_bundle(path, *, state: dict[str, object]) -> dict[str, object]	Collectively publish a portable nodal-state bundle.
function	load_portable_state_bundle(path, *, state: dict[str, object], record: dict[str, object], identities: dict[str, object]) -> None	Collectively restore a bundle written by :func:save_portable_state_bundle.
function	checkpoint_file_record(path) -> dict[str, object]	Describe one checkpoint payload by name, size, and digest.
function	validate_checkpoint_record(directory, record: dict[str, object]) -> Path	Validate and return a payload referenced by a scientific manifest.
function	function_portable_identity(function) -> dict[str, object]	Return an MPI-partition-independent identity for a nodal field.
function	mesh_portable_identity(domain) -> dict[str, object]	Hash cell geometry independently of local numbering and partition.
function	remove_stateful_checkpoint(path, *, comm, expected_schema: str = 'agentfem.affine-stateful-checkpoint.v1') -> None	Collectively remove one manifest and only its declared state payloads.
function	remove_serial_checkpoint(path, *, comm, expected_schema: str) -> None	Collectively remove one serial payload and its typed result sidecar.
function	function_partition_identity(function) -> dict[str, object]	Return a JSON-safe identity for one field on one mesh partition.
function	atomic_savez(path, **arrays) -> Path	Atomically publish one NumPy archive in its destination directory.
function	atomic_write_text(path, content: str) -> Path	Atomically publish UTF-8 text in its destination directory.

agentfem.coordinates

Kind	Public object	Purpose
class	CartesianSystem	Right-handed orthonormal Cartesian coordinate system.
class	ReferencePoint	Named engineering point used for remote resultants and kinematics.
function	cartesian(*, origin = None, axes = None, x = None, y = None, z = None, name = 'local') -> CartesianSystem	Create a Cartesian system from a matrix or named basis vectors.
function	reference_point(coordinates, *, name = 'reference_point', system = None) -> ReferencePoint	Create a named engineering reference point.

agentfem.datasets

Kind	Public object	Purpose
class	DatasetSplit	Reproducible train/validation partition.
class	ScientificDataset	A numeric dataset whose columns retain scientific meaning.
class	FieldCaseData	Physical fields extracted from one successful campaign case.
class	FieldDatasetAssembler	Declarative bridge from accepted Campaign records to complete fields.
class	ExternalDatasetAudit	Local evidence that downloaded public data matches its manifest.
class	ExternalDatasetManifest	Versioned public dataset identity, scope, and local audit policy.
class	ExternalFile	One immutable file identity in a public scientific dataset.
class	SpreadsheetSheet	Rectangular values from one XLSX worksheet.
class	SpreadsheetWorkbook	Dependency-free, read-only representation of one XLSX workbook.
function	read_xlsx_workbook(path: str \| Path) -> SpreadsheetWorkbook	Read values and cached formula results from an XLSX without pandas.
function	science_supershear_dryad_manifest() -> ExternalDatasetManifest	Return the pinned CC0 Dryad v7 manifest for Science 2023.
function	science_supershear_v5_research_task() -> dict[str, object]	Return the installed machine-readable V5 research handoff.
class	FieldDatasetSplit	Reproducible train/validation/test partition of field cases.
class	ScientificFieldDataset	A scientific collection whose samples are complete physical fields.
class	Quantity	One scalar, curve, vector, or sampled-field output contract.
class	Sample	One successful simulation sample and its scientific lineage.
function	decode_quantities(quantities: tuple[Quantity, ...], row) -> dict[str, object]	Restore one flattened numeric row to declared named quantities.
class	RectilinearObservation	One scalar field on explicit physical x/y axes.
class	FEMFieldSample	One FEM field representation with coordinates and scientific encoding.
class	TorchDatasetBundle	PyTorch dataset plus the schema needed to interpret its columns.
function	fem_field_sample(function, encoding) -> FEMFieldSample	Export owned nodal coefficients for external neural/PINN tooling.
function	fem_observation_sample(function, grid, *, name: str \| None = None, unit: str \| None = None, role: str = 'output', components = (), outside: str = 'raise', fill_value: float = 0.0, coordinate_map = None, configuration: str = 'reference') -> FEMFieldSample	Sample a FEM field on a reusable structured observation grid.
function	to_torch(dataset: ScientificDataset, *, normalized_inputs: bool = True, dtype: str = 'float32', device: str = 'cpu') -> TorchDatasetBundle	Expose a validated campaign dataset as a PyTorch TensorDataset.

agentfem.dynamics

Kind	Public object	Purpose
class	ModalSolveInfo	Convergence, operator and eigenspace evidence for one FEM solve.
class	SignalSpectrum	One-sided spectrum of a uniformly sampled real signal.
class	FrequencyResponse	Complex frequency-response function with inspectable coherence mask.
class	DampingEstimate	Free-decay damping estimate from same-sign displacement peaks.
class	ModalBasis	Mass-normalized modes and their natural frequencies.
function	spectrum(time, signal = None, *, window: str \| None = 'hann', remove_mean: bool = True) -> SignalSpectrum	Compute a correctly scaled one-sided FFT for a real signal.
function	frequency_response(time, excitation, response = None, *, window: str \| None = 'hann', minimum_input_ratio: float = 1e-10) -> FrequencyResponse	Estimate an FRF from synchronous input and output time histories.
function	damping_from_free_decay(signal, *, peak_indices: Sequence[int] \| None = None) -> DampingEstimate	Estimate damping from positive peaks of an underdamped free decay.
function	solve_dense_modes(stiffness, mass, *, modes: int \| None = None) -> ModalBasis	Solve a small dense symmetric generalized eigenproblem.
function	modal_frequency_response(basis: ModalBasis, frequencies, modal_force, *, damping_ratio = 0.0) -> np.ndarray	Return modal coordinates for harmonic forcing by modal superposition.

agentfem.events

Kind	Public object	Purpose
class	SolveEvent	One backend-neutral observation from an analysis procedure.
class	FirstPassageEvent	One threshold event with explicit localization and censoring evidence.
function	first_passage(abscissa, values = None, *, threshold: float, direction: EventDirection = 'rising', localization: str = 'linear', component: int \| tuple[int, ...] \| None = None, name: str = 'first_passage', coordinate_name: str \| None = None, coordinate_unit: str \| None = None, value_name: str \| None = None, value_unit: str \| None = None) -> FirstPassageEvent	Locate the first threshold crossing in a history or numeric arrays.

agentfem.elements

Kind	Public object	Purpose
class	ElementIdentity	Backend-readable identity of one scalar, vector, tensor, or mixed element.
class	FieldDiscretization	One model field bound to its actual finite-element space.
class	DiscretizationAudit	Inspectable mesh/element/Study preflight with optional quality evidence.
function	describe_element(element_or_space) -> ElementIdentity	Describe a UFL element or a function space without constructing forms.
function	describe_field(field, *, registered_mesh = None) -> FieldDiscretization	Describe the runtime discretization of one AgentFEM or DOLFINx field.
function	audit(model, *, check_quality: bool = False, quality_threshold: float = 0.1, reject_poor_quality: bool = False) -> DiscretizationAudit	Audit mesh topology, field elements, Study shapes, and mesh quality.

agentfem.expressions

Kind	Public object	Purpose
class	ExpressionError	Raised when a scientific expression is invalid or unsupported.
class	ScientificExpression	An inspectable expression that can be lowered to UFL.
function	expression(source: str \| Real \| ScientificExpression) -> ScientificExpression	Return a validated :class:ScientificExpression.
function	as_ufl(source, domain, *, parameters: Mapping[str, object] \| None = None)	Validate and lower one scalar expression to UFL.
function	vector_as_ufl(sources: Sequence[str \| Real \| ScientificExpression], domain, *, parameters: Mapping[str, object] \| None = None)	Validate and lower a vector of scalar expressions to UFL.
function	interpolate(target, source, *, parameters: Mapping[str, object] \| None = None) -> object	Interpolate scalar, vector or tensor expressions into target.

agentfem.fatigue_fracture

Kind	Public object	Purpose
class	ForceCycle	One scalar cyclic-load definition expressed in test parameters.
function	force_cycle(*, minimum: float \| None = None, maximum: float \| None = None, fmin: float \| None = None, fmax: float \| None = None, frequency: float = 1.0, waveform: str = 'sine', hold_minimum_fraction: float = 0.0, hold_maximum_fraction: float = 0.0, table = (), name: str = 'force cycle') -> ForceCycle	Create a cyclic force from minimum/maximum or fmin/fmax.
class	CycleJumpDecision	One inspectable proposal for advancing the independent cycle count.
class	CycleJumpPolicy	Bound a cycle block by predicted damage and exact output landings.
class	CycleJumpRecord	Accepted or rejected cycle-block evidence.
class	CycleJumpLedger(*, start_cycle: int = 0)	Record exact cycle progress and every jump/cutback decision.
class	CyclicCohesiveResponse	Mode-I response with separated monotonic and fatigue evidence.
class	CyclicCohesiveLaw	Replaceable power-law range fatigue layered on a bilinear envelope.
class	CyclicCohesiveTransaction(law: CyclicCohesiveLaw, size: int)	Atomic monotonic trials and cycle-block trials for cohesive points.
class	MixedModeEnergyRange	Local cohesive-energy driver from one physical peak/valley pair.
class	OrderedJumpCyclePath	One ordered closed cycle of complete local cohesive jump vectors.
class	MixedModeEnergyPath	Segment-resolved local cohesive energy evidence for one ordered path.
class	OrderedMixedModeEnergyPathDriver	Segment-resolved BK/power driver for ordered mixed-mode cycles.
class	MixedModeEnergyRangeDriver	BK/power interaction for local mixed-mode cyclic energy ranges.
class	MixedModeCyclicCohesiveResponse	Mixed-mode monotonic response with committed cyclic evidence.
class	MixedModeCyclicCohesiveLaw	Replaceable cyclic damage layered on a mixed-mode cohesive envelope.
class	MixedModeCyclicCohesiveTransaction(law: MixedModeCyclicCohesiveLaw, size: int)	Atomic full-vector cycle transaction with mixed-mode energy evidence.
class	FieldStateTransaction(fields, *, assets = None)	In-memory rollback for bulk fields and other transactional assets.
class	CyclicEquilibriumPoint	Evidence returned by one converged cyclic equilibrium solve.
class	CyclicFatigueBlock	Accepted structure-level cycle block and its error evidence.
class	GlobalCyclicFatigueStep(*, cycle: ForceCycle, stop_cycle: int, interfaces, state, solve_equilibrium, jump: CycleJumpPolicy \| None = None, landing_cycles = (), maximum_opening_feedback: float = 0.02, maximum_energy_balance_error: float \| None = None, energy_ledger: CyclicWorkEnergyLedger \| None = None, ordered_path_phases = (), observe = None, name: str = 'cyclic fatigue')	Quasi-static cyclic fatigue loop with global rollback and cutback.
class	SurfaceCrackComponent	One connected failed component in a surface-crack observation.
class	SurfaceCrackObservation	One cycle's geometric evidence on a triangular cohesive surface.
class	CrackTopologyEvent	Auditable identity change between two accepted crack observations.
class	TrackedSurfaceCrack	A connected crack component with identity stable across cycle blocks.
class	SurfaceCrackTrackingFrame	Persistent component identities and topology events at one cycle.
class	SurfaceCrackTracker(*, interface_name: str, id_prefix: str \| None = None)	Track cracks on one fixed cohesive surface by physical facet identity.
class	CrackInteractionObservation	Two-crack geometry and growth evidence at one exact cycle.
function	observe_surface_crack(coordinates, facets, damage, opening, *, cycle: int, name: str = 'surface crack', damage_threshold: float = 0.95, include_boundary_front: bool = False, facet_ids = None) -> SurfaceCrackObservation	Recover connected failed area and a three-dimensional crack front.
function	surface_crack_interaction(first: SurfaceCrackObservation, second: SurfaceCrackObservation, *, first_single_growth_rate: float \| None = None, second_single_growth_rate: float \| None = None, first_double_growth_rate: float \| None = None, second_double_growth_rate: float \| None = None, coalescence_tolerance: float = 0.0) -> CrackInteractionObservation	Compare two named fronts without hiding the single-crack baseline.
class	ParisEvidence	Postprocessed Paris-region evidence; never a crack-growth solver law.
function	paris_evidence(cycles, crack_size, driving_force, *, fit_cycle_range: tuple[float, float] \| None = None, fit_mask = None, derivative_window: int = 3, driving_force_name: str = 'Delta K', crack_size_name: str = 'a', driving_force_unit: str = 'declared', crack_size_unit: str = 'declared') -> ParisEvidence	Fit a Paris relation after simulation from a(N) and a driver.
function	cyclic_cohesive(*, monotonic: BilinearCohesiveLaw \| MixedModeBilinearCohesiveLaw, fatigue_coefficient: float, fatigue_exponent: float, range_threshold: float, peak_exponent: float = 0.0, residual_exponent: float = 0.0, driver: MixedModeEnergyRangeDriver \| OrderedMixedModeEnergyPathDriver \| None = None, name: str \| None = None) -> CyclicCohesiveLaw \| MixedModeCyclicCohesiveLaw	Create a Mode-I or mixed-mode cyclic cohesive law.
function	mixed_mode_energy_range_driver(**options) -> MixedModeEnergyRangeDriver	Create the first proportional peak/valley mixed-mode fatigue driver.
function	ordered_jump_cycle(phases, jumps, *, name = 'ordered jump cycle')	Create a closed, station-resolved local cohesive cycle.
function	ordered_mixed_mode_energy_path_driver(**options) -> OrderedMixedModeEnergyPathDriver	Create a segment-resolved non-proportional mixed-mode driver.
function	field_state(fields = None, *, assets = None, **named_fields) -> FieldStateTransaction	Create rollback state from a field mapping or named field arguments.
function	global_cyclic_fatigue_step(**kwargs) -> GlobalCyclicFatigueStep	Create a reusable extrema- or ordered-path fatigue controller.

agentfem.fracture

Kind	Public object	Purpose
function	finite_strain_internal_force(displacement, test_function, material, *, measure = ufl.dx, name: str = 'F_internal_finite_strain') -> OperatorForm	Return the current Total-Lagrangian hyperelastic internal force.
class	FiniteStrainEnergyMonitor	Accepted-frame kinetic and hyperelastic bulk energy monitor.
class	FiniteStrainRegionalEnergyMonitor	Accepted-frame energy for a partitioned hyperelastic solid.
class	DofMappedCohesiveForce(assembler, displacement, *, node_to_block_dof)	Map a serial cohesive facet kernel to vector finite-element dofs.
class	NamedCohesiveResponse	Responses and aggregate energy from several named interfaces.
class	CohesiveForceCollection(interfaces)	Atomically compose independent named cohesive-interface forces.
function	named_cohesive_forces(**interfaces) -> CohesiveForceCollection	Create an atomically managed collection from named cohesive forces.
function	named_mode_i_cohesive_forces(split, displacement, *, laws, normal_hints, thicknesses = None, tangential = 'free', tangential_stiffness = None, tolerance: float = 1e-10) -> CohesiveForceCollection	Build independent named forces on one atomically split solver mesh.
function	cohesive_forces(split, displacement, *, laws, normal_hints, thicknesses = None, tangential = None, tangential_stiffness = None, tolerance: float = 1e-10) -> CohesiveForceCollection	Build a recommended force for every named split interface.
class	DistributedDofMappedCohesiveForce(assembler, displacement, *, input_node_to_block_dof, input_node_owned, global_topology, global_facet_indices, local_input_nodes = None)	MPI assembler for a physical-keyed split interface.
function	p1_input_node_to_block_dof(displacement, *, number_of_input_nodes: int)	Recover the complete serial input-node to block-DOF map.
function	mode_i_cohesive_force(split: interface_api.SplitInterfaceMesh, displacement, law, *, normal_hint, thickness: float = 1.0, tolerance: float = 1e-10, tangential: str = 'free', tangential_stiffness: float \| None = None) -> DofMappedCohesiveForce \| DistributedDofMappedCohesiveForce	Build a fixed-path cohesive force from a split mesh contract.
function	cohesive_force(split: interface_api.SplitInterfaceMesh, displacement, law, *, normal_hint, tangential: str \| None = None, tangential_stiffness: float \| None = None, thickness: float = 1.0, tolerance: float = 1e-10)	Build the recommended full-vector fixed-path interface consumer.
class	FiniteStrainCohesiveResidual(bulk, cohesive)	Assemble bulk UFL and paired-facet interface forces into one residual.
class	CohesiveNewtonSolveInfo	Convergence evidence for one native bulk-plus-interface equilibrium.
class	ArcLengthOptions	Crisfield-style spherical continuation controls.
class	ArcLengthSolveInfo	Public AgentFEM object.
class	FiniteStrainCohesiveEquilibrium(residual: FiniteStrainCohesiveResidual, tangent, displacement, *, set_load = None, load_parameter = None, reference_load: float = 1.0, bcs = (), solver_options = None, control_displacement = None, reaction = None, bulk_strain_energy = None)	Native Newton consumer for UFL bulk and zero-thickness interfaces.
class	FiniteStrainCohesiveKinematicEquilibrium(residual: FiniteStrainCohesiveResidual, tangent, displacement, *, control, bcs = (), solver_options = None, control_absolute_tolerance: float = 1e-10, bulk_strain_energy = None)	Cohesive Newton solve under one exact generalized displacement.
class	FiniteStrainCohesiveArcLength(equilibrium: FiniteStrainCohesiveEquilibrium, options: ArcLengthOptions, *, initial_load: float = 0.0)	Spherical arc-length continuation for cohesive equilibrium paths.
class	MassProportionalDampingResidual(base, *, mass, velocity, coefficient: float, dt: float)	Add alpha M v_mid with transactional dissipation accounting.
class	DampingEnergyMonitor	Add accepted viscous dissipation to an existing mechanical monitor.
class	FiniteStrainCohesiveEnergyMonitor	Typed accepted-frame energy for bulk plus cohesive dynamics.
class	DynamicEnergyLedger	Accepted-frame external work and mechanical-energy closure.
class	IsotropicWaveSpeeds	Reference small-on-zero wave speeds for one isotropic material.
class	IncrementalWaveSpeeds	Small-on-large bulk-wave modes about one homogeneous deformation.
class	PrincipalSurfaceWaveSpeed	Reference-coordinate principal surface-wave secular solution.
function	neo_hookean_material_tangent(deformation_gradient, material) -> np.ndarray	Return A[i,J,k,L] = dP[i,J]/dF[k,L] for a supported energy.
function	incremental_wave_speeds(deformation_gradient, direction, material, *, direction_configuration: str = 'current') -> IncrementalWaveSpeeds	Return homogeneous small-on-large bulk-wave speeds.
function	principal_surface_wave_speed(deformation_gradient, material: hyperelasticity.NeoHookeanProperties, *, propagation_axis: int = 0, scan_points: int = 320) -> PrincipalSurfaceWaveSpeed	Solve the 2D small-on-large principal surface-wave secular problem.
function	isotropic_reference_wave_speeds(material) -> IsotropicWaveSpeeds	Return unstretched 3D isotropic c_d, c_s, and c_R.
class	StableTimeIncrement	Visible body/interface estimate for central difference.
class	CohesiveCrackHistory	Crack-front position and window-fitted speed on a fixed path.
class	CrackPropagationFit	Representative crack speed fitted across a declared path interval.
class	InterfaceFrontHistory	Front position and fitted speed for one declared interface signal.
class	CohesiveFrontEnsemble	Crack-front evidence from multiple thresholds and physical signals.
class	PreloadTransferReport	Evidence for a quasi-static displacement to Explicit state transfer.
function	transfer_preload_to_explicit(preload_displacement, *, state, mass, residual, initial_velocity = None, mode: str = 'equilibrium', force_tolerance: float = 1e-08, acceleration_projection = None, energy_monitor = None, source_energy: float \| None = None, source_step: str \| None = None, destination_step: str \| None = None) -> PreloadTransferReport	Initialize u/v/a consistently from a quasi-static preload state.
function	cohesive_crack_tip(path_coordinate, damage, *, threshold: float = 0.95, direction: str = 'increasing') -> float	Locate the contiguous crack front by interpolating a damage threshold.
function	crack_tip_history(time_values, path_coordinate, damage_frames, *, threshold: float = 0.95, fit_window: int = 5, direction: str = 'increasing') -> CohesiveCrackHistory	Build a crack history without single-failed-element speed spikes.
function	fit_crack_propagation_speed(history: CohesiveCrackHistory, *, start_position: float, end_position: float, minimum_samples: int = 3) -> CrackPropagationFit \| None	Fit one representative speed over a fixed physical path interval.
function	interface_front_history(time_values, path_coordinate, signal_frames, *, signal: str, threshold: float, fit_window: int = 5, direction: str = 'increasing') -> InterfaceFrontHistory	Track a contiguous interface front from any increasing damage signal.
function	cohesive_front_ensemble(trace: CohesiveInterfaceTrace, *, damage_thresholds = (0.5, 0.75, 0.95), opening_thresholds = (), dissipation_thresholds = (), fit_window: int = 5, direction: str = 'increasing') -> CohesiveFrontEnsemble	Build observer-sensitivity evidence from a portable interface trace.
function	compare_curve(reference_coordinate, reference_values, simulation_coordinate, simulation_values, *, coordinate_name: str = 'coordinate', quantity_name: str = 'value') -> ScientificComparison	Interpolate a simulated curve onto observed coordinates and compare.
function	compare_mach_cone(*, crack_speed: float, shear_wave_speed: float, observed_angle: float, unit: str = 'radian') -> ScientificComparison	Compare an observed Mach angle with asin(c_s/v).
function	compare_rectilinear_field(reference_x, reference_y, reference_values, simulation_x, simulation_y, simulation_values, *, quantity_name: str = 'field', reference_mask = None, simulation_mask = None) -> ScientificComparison	Compare scalar maps after bilinear interpolation on their overlap.
function	compare_rectilinear_observations(reference, simulation, *, quantity_name: str \| None = None) -> ScientificComparison	Compare two portable rectilinear observations with semantic checks.
function	mach_cone_angle(*, crack_speed: float, shear_wave_speed: float) -> float	Return the ideal Mach angle asin(c_s / v) in radians.
function	separation_regime(*, crack_speed: float, rayleigh_wave_speed: float, shear_wave_speed: float, failed_fraction: float, simultaneous_failed_fraction: float, spall_fraction: float = 0.8, rapid_failed_fraction: float \| None = None, ligament_traction_ratio: float \| None = None, pressure_wave_speed: float \| None = None) -> str	Classify one frame with explicit crack-speed and spall evidence.
function	estimate_stable_time_increment(*, characteristic_length, dilatational_speed: float, safety_factor: float = 0.8, interface_stiffness: float \| None = None, interface_area: float \| None = None, negative_mass: float \| None = None, positive_mass: float \| None = None) -> StableTimeIncrement	Estimate explicit stability from body transit and interface oscillator.
function	minimum_cell_nodal_spacing(domain) -> float	Return an MPI-global conservative spacing from cell geometry nodes.
class	CohesiveInterfaceTrace	Portable accepted-frame record on one fixed cohesive interface.
class	DynamicFractureEvidenceBundle	Trace, fields, energies, comparisons, and provenance for one condition.
class	ScientificComparison	Common scalar evidence for a simulation-to-observation comparison.

agentfem.histories

Kind	Public object	Purpose
class	FieldHistory	A sampled scalar or finite-element field over physical time.
function	field_history(source, **kwargs) -> FieldHistory	Create a generic field-history recorder.
function	temperature(source, *, name: str = 'temperature', unit: str = 'K', **kwargs) -> FieldHistory	Create a physical-time temperature history.

agentfem.interfaces

Kind	Public object	Purpose
class	CohesiveResponse	One Mode-I traction--separation update.
class	VectorCohesiveResponse	Local-basis response of a two- or three-dimensional interface.
class	MixedModeBilinearCohesiveLaw	Bilinear mixed-mode cohesive law for proportional loading paths.
class	BilinearCohesiveLaw	Irreversible bilinear Mode-I cohesive law.
class	CohesiveTransaction(law: BilinearCohesiveLaw, size: int)	Trial/commit/rollback state for a batch of cohesive points.
class	MixedModeCohesiveTransaction(law: MixedModeBilinearCohesiveLaw, size: int)	Trial/commit state for :class:MixedModeBilinearCohesiveLaw.
class	PairedLineFacets	Deterministically paired zero-thickness line facets for a 2D mesh.
class	PairedSurfaceFacets	Deterministically paired zero-thickness triangular facets in 3D.
class	SplitInterfaceMesh	Array-level result of splitting one conforming interface manifold.
class	NamedSplitInterfaceMesh	One solver mesh carrying several disjoint named cohesive surfaces.
class	InterfaceRigidModeAudit	Rigid-body constraint rank of a split-interface model.
function	audit_split_interface_rigid_modes(split: SplitInterfaceMesh \| NamedSplitInterfaceMesh, *, constrained_components, tangential = 'free', active_facets = None, rank_tolerance: float \| None = None, error_if_singular: bool = False) -> InterfaceRigidModeAudit	Audit rigid translations and rotations before creating a solver mesh.
function	create_dolfinx_split_mesh(split: SplitInterfaceMesh \| NamedSplitInterfaceMesh, *, comm = None, cell_type: str \| None = None, input_order: str = 'counterclockwise')	Create an executable DOLFINx mesh for an audited split interface.
class	CohesiveFacetResponse	Trial force, kinematics and energy from paired interface facets.
class	ModeIKinematicsAudit	Accepted-state check that a declared Mode-I path remains Mode-I.
function	audit_mode_i_kinematics(response: CohesiveFacetResponse, *, ratio_limit: float = 0.1, absolute_tolerance: float = 1e-12, error_if_exceeded: bool = False) -> ModeIKinematicsAudit	Check tangential jump without changing cohesive history.
class	CohesiveElementTangents	Element-node layouts and consistent scalar-dof tangent matrices.
class	ModeICohesiveFacetAssembler(topology: PairedLineFacets, law, *, number_of_nodes: int, thickness: float = 1.0, tangential: str = 'free', tangential_stiffness: float \| None = None)	Two-point line integration for a fixed-path 2D interface.
class	ModeICohesiveSurfaceAssembler(topology: PairedSurfaceFacets, law, *, number_of_nodes: int, tangential: str = 'free', tangential_stiffness: float \| None = None)	Three-point integration of linear triangular interfaces in 3D.
function	pair_coincident_surface_facets(coordinates, negative_facets, positive_facets, *, normal_hint, tolerance: float = 1e-10) -> PairedSurfaceFacets	Pair coincident three-node triangular facets in 3D.
function	pair_coincident_line_facets(coordinates, negative_facets, positive_facets, *, normal_hint, tolerance: float = 1e-10) -> PairedLineFacets	Pair coincident two-node line facets with a declared normal direction.
function	split_conforming_line_interface(coordinates, cells, interface_facets, *, positive_cells) -> SplitInterfaceMesh	Duplicate nodes on a declared conforming 2D cell interface.
function	split_conforming_surface_interface(coordinates, cells, interface_facets, *, positive_cells) -> SplitInterfaceMesh	Duplicate nodes on a declared conforming triangular surface in 3D.
function	split_conforming_named_interfaces(coordinates, cells, named_interfaces) -> NamedSplitInterfaceMesh	Atomically split several disjoint conforming cohesive manifolds.
function	split_conforming_cell_interface(coordinates, cells, *, positive_cells) -> SplitInterfaceMesh	Split the internal facet separating two declared cell partitions.
class	CohesiveSurface	Public description of a fixed-path zero-thickness interface.
function	bilinear_cohesive(*, strength: float, fracture_energy: float, initial_stiffness: float, compression_stiffness: float \| None = None, name: str = 'bilinear Mode-I cohesive law') -> BilinearCohesiveLaw	Create a bilinear Mode-I cohesive law.
function	mixed_mode_bilinear_cohesive(*, normal_strength: float, shear_strength: float, normal_fracture_energy: float, shear_fracture_energy: float, normal_stiffness: float, tangential_stiffness: float, interaction: str = 'bk', interaction_exponent: float = 1.45, compression_stiffness: float \| None = None, residual_tangential_fraction: float = 0.0, friction_coefficient: float = 0.0, friction_regularization: float = 1e-08, name: str = 'bilinear mixed-mode cohesive law') -> MixedModeBilinearCohesiveLaw	Create a quadratic-initiation, energy-evolution mixed-mode law.
function	cohesive_surface(*, law, mode: str = 'normal', name: str = 'cohesive surface') -> CohesiveSurface	Declare a fixed-path zero-thickness cohesive interface.
function	cohesive_characteristic_length(*, young: float, fracture_energy: float, strength: float) -> float	Return the declared scale E * Gamma / strength**2.

agentfem.manifests

Kind	Public object	Purpose
function	read(path: str \| Path, *, schema: str \| None = None) -> dict[str, object]	Read and validate one versioned JSON manifest.
function	result(path: str \| Path) -> dict[str, object]	Read a SimulationResult manifest and reject duplicate field names.
function	campaign(path: str \| Path) -> dict[str, object]	Read a campaign report and reject duplicate case identities.

agentfem.learning

Kind	Public object	Purpose
class	ConditionSpec	A physical condition and the declared way it enters an objective.
class	IntegrationEvidence	Independent objective re-integration and refinement evidence.
class	IntegrationPlan	Training, held-out validation, and optional refinement integration.
class	IntegrationRule	One inspectable numerical-integration point set.
class	NeuralFieldSpec	Provider-neutral contract for PINN, DEM, XDEM, and related solvers.
class	NeuralRepresentation	How one neural function represents one or more unknown fields.
class	ObjectiveTerm	One named contribution to a neural-field optimization objective.
class	SamplingPlan	Inspectable coordinates or integration samples for one physical set.
class	TrainableParameter	A physical parameter inferred jointly with one or more fields.
function	integration_consistency_check(plan: IntegrationPlan, *, training_value: float, validation_value: float, refinement_values = (), balance_error: float \| None = None, relative_tolerance: float = 0.05) -> IntegrationEvidence	Compare optimized and held-out integration without trusting loss alone.
class	NeuralFieldExecutionRequest	Immutable input supplied to a user- or package-owned executor.
class	LearnedConstitutiveMaterial(specification: LearnedConstitutiveSpec) -> None	Ordinary small-strain material delegating execution to one provider.
class	LearnedConstitutiveProvider	Registered factory owned by an activated extension package.
class	LearnedConstitutiveProviderError(code: str, message: str) -> None	Addressable provider, artifact, or compatibility failure.
class	LearnedConstitutiveSpec	Immutable scientific identity for an externally executed local model.
function	learned_constitutive(*, provider: str, architecture: str, artifact: str, revision: str, artifact_sha256: str, parameter_schema: MaterialParameterSchema, parameters: Mapping[str, float], state_schema: MaterialStateSchema, tangent_convention: MaterialTangentConvention, **options) -> LearnedConstitutiveSpec	Construct a descriptive specification without loading executable code.
function	learned_constitutive_providers() -> tuple[LearnedConstitutiveProvider, ...]	Public AgentFEM object.
function	learned_material(specification: LearnedConstitutiveSpec) -> LearnedConstitutiveMaterial	Bind one immutable specification to an explicitly active provider.
function	record_learned_constitutive_evidence(result, selected_material: LearnedConstitutiveMaterial, *, runtime: Mapping[str, object], diagnostics: Mapping[str, object])	Attach reserved, portable provider evidence to a SimulationResult.
function	register_learned_constitutive_provider(provider: LearnedConstitutiveProvider, *, replace: bool = False) -> None	Register one already-activated framework provider.
function	resolve_learned_constitutive_provider(specification: LearnedConstitutiveSpec) -> LearnedConstitutiveProvider	Public AgentFEM object.

agentfem.mechanics

Kind	Public object	Purpose
class	CreepEnergyFrame	Accepted work and energy evidence for one physical-time increment.
class	CreepIncrementInfo	Public AgentFEM object.
class	CreepPathInfo	Public AgentFEM object.
class	ImplicitCreepStep	Adaptive backward-Euler creep step with global Newton equilibrium.
function	implicit_creep_step(*, displacement, material, duration: float, external_force, constraints = (), study = None, incrementation = None, solver_options = None, quadrature_degree: int = 2, creep_strain_error_tolerance: float \| None = None, time_unit: str \| None = None, progress = True, status_file = None, amplitude = None, temperature = None, name: str = 'implicit_creep', _experimental_distributed: bool = False) -> ImplicitCreepStep	Build global 3D or axisymmetric implicit power-law creep.
class	ExperimentalFiniteStrainPlasticityStep	Stateful Total-Lagrangian J2 equilibrium with ordinary strong BCs.
class	FiniteStrainJ2AffineTransaction	Constraint-neutral trial/commit state for finite-strain J2 Newton.
class	FiniteStrainJ2StateTransaction	Constraint-neutral trial/commit state for finite-strain J2 Newton.
class	FiniteStrainJ2StandardProblem	Stateful Total-Lagrangian J2 equilibrium with ordinary strong BCs.
class	FiniteStrainPlasticityIncrementInfo	Public AgentFEM object.
class	FiniteStrainPlasticityPathInfo	Accepted and attempted increments for a standard finite-strain J2 path.
function	experimental_finite_strain_j2_step(*, displacement, material: FiniteStrainJ2Logarithmic, external_force = None, constraints = (), incrementation = None, solver_options = None, quadrature_degree: int = 2, amplitude = None, name: str = 'finite_strain_j2_experimental') -> ExperimentalFiniteStrainPlasticityStep	Compatibility alias for :func:finite_strain_j2_standard_problem.
function	finite_strain_j2_affine_problem(*, displacement, material: FiniteStrainJ2Logarithmic \| QuadratureMaterialMap, constraint, external_force = None, incrementation = None, solver_options = None, quadrature_degree: int = 2, output_every: int \| None = 1, output_factors = (), progress = True, status_file = None, checkpoint_policy = None, name: str = 'finite_strain_j2')	Build stateful finite-strain J2 under exact affine/MPC kinematics.
function	finite_strain_j2_mixed_affine_problem(*, target, material: FiniteStrainJ2Logarithmic \| QuadratureMaterialMap, constraint, incrementation = None, solver_options = None, quadrature_degree: int = 2, output_every: int \| None = 1, output_factors = (), progress = True, status_file = None, checkpoint_policy = None, name: str = 'finite_strain_j2_mixed')	Build mixed logarithmic-J2 equilibrium under affine kinematics.
function	finite_strain_j2_standard_problem(*, displacement, material: FiniteStrainJ2Logarithmic \| QuadratureMaterialMap, external_force = None, load_identity = None, constraints = (), incrementation = None, solver_options = None, quadrature_degree: int = 2, amplitude = None, output_every: int \| None = 1, output_factors = (), progress = True, status_file = None, checkpoint_policy = None, name: str = 'finite_strain_j2') -> FiniteStrainJ2StandardProblem	Build stateful finite-strain J2 under ordinary strong boundaries.
class	DirectHarmonicStep	One direct steady-state harmonic solve with separated ownership.
class	DirectHarmonicSweepStep	A bounded-memory ordered frequency sweep over one prepared Step.
function	direct_harmonic_step(*, displacement, system: DirectHarmonicSystem, frequency: float \| None = None, angular_frequency: float \| None = None, constraints = (), load_phase: float = 0.0, study = None, solver_options = None, name: str = 'direct_harmonic') -> DirectHarmonicStep	Build one direct harmonic Step from explicit operator contributions.
function	harmonic_frequency_sweep_step(point_step: DirectHarmonicStep, *, frequencies, responses = (), execution_order: str = 'forward', scientific_assets: dict[str, object] \| None = None, status_file = None, name: str \| None = None) -> DirectHarmonicSweepStep	Create a reusable ordered sweep around one direct harmonic Step.
class	ModalAnalysisStep	Constrained linear modes from K phi = lambda M phi.
class	J2IncrementInfo	Public AgentFEM object.
class	J2LoadPathInfo	Public AgentFEM object.
class	J2PlasticityStep	Incremental global equilibrium for 3D small-strain J2 plasticity.
function	j2_plasticity_step(*, displacement, material, external_force, constraints = (), study = None, incrementation = None, solver_options = None, quadrature_degree: int = 2, progress = True, status_file = None, amplitude = None, name: str = 'j2_plasticity', _experimental_distributed: bool = False) -> J2PlasticityStep	Build a global 3D or axisymmetric J2 step.
class	SmallStrainMaterialIncrementInfo	Evidence for one attempted equilibrium increment.
class	SmallStrainMaterialPathInfo	Public AgentFEM object.
class	SmallStrainMaterialStep	Implicit Newton Step driven by an ordinary small-strain material.
function	small_strain_material_step(*, displacement, material, external_force, constraints = (), study = None, incrementation = None, solver_options = None, quadrature_degree = 2, progress = True, status_file = None, amplitude = None, name = 'small_strain_material') -> SmallStrainMaterialStep	Public AgentFEM object.
class	DirectorShellKinematics	Finite-rotation surface measures at one material point.
class	FiberCurveKinematics	Objective bending measures for one material fibre curve.
class	ReconstructedFiberCurvature	Owned-cell fibre curvatures plus neighbour reconstruction evidence.
class	RotationFreeEdgeBoundarySemantics	Declare the two work-conjugate boundary pairs of a thin shell.
class	FibrousShellCompatibilityExpressions	Minimal mixed-field compatibility residuals for a no-slip layer.
class	FibrousShellKinematicsExpressions	Symbolic operator-owned measures consumed by a fibrous-shell law.
function	director_shell_kinematics(reference_tangents, current_tangents, director, *, director_gradient = None, reference_director = None, reference_director_gradient = None) -> DirectorShellKinematics	Evaluate objective membrane, shear, and curvature measures.
function	fiber_curve_kinematics(reference_tangents, current_tangents, reference_direction, current_direction, *, current_direction_gradient, reference_direction_gradient = None) -> FiberCurveKinematics	Evaluate in-plane and normal curvature changes of one fibre family.
function	reconstruct_fiber_curvature(domain, current_directions, current_tangents, *, rings: int = 2, weight_power: float = 1.0, condition_limit: float = 10000000000.0) -> ReconstructedFiberCurvature	Reconstruct in-plane and normal fibre curvature on owned cells.
function	rotation_free_edge_boundary(*, translation: str, bending: str, name: str = 'rotation_free_edge') -> RotationFreeEdgeBoundarySemantics	Create an inspectable rotation-free shell edge contract.
function	fibrous_shell_compatibility_ufl(reference_tangents, current_tangents, director, *, reference_fibers, current_fibers) -> FibrousShellCompatibilityExpressions	Return the minimal exact-constraint residual for mixed shell fields.
function	fibrous_shell_kinematics_ufl(reference_tangents, current_tangents, director, *, reference_fibers, current_fibers, current_fiber_gradients, reference_director = None, reference_fiber_gradients = None) -> FibrousShellKinematicsExpressions	Build the nine objective fibrous-shell measures as UFL expressions.
function	surface_deformation_gradient(reference_tangents, current_tangents) -> np.ndarray	Return the three-dimensional tangential deformation lift.
class	HarmonicViscoelasticStep	Direct harmonic generalized-Maxwell equilibrium in a real PETSc build.
class	QuasistaticViscoelasticStep	Incremental equilibrium for a small-strain generalized-Maxwell solid.
class	ViscoelasticEnergyFrame	Exact constitutive work--storage--dissipation ledger.
class	ViscoelasticIncrementInfo	Accepted equilibrium evidence for one physical-time increment.
class	ViscoelasticPathInfo	Resolved fixed physical-time path.
class	ViscoelasticQuadratureState	Typed committed/trial Maxwell state and current response fields.
function	harmonic_viscoelastic_step(*, displacement, material, frequency: float \| None = None, angular_frequency: float \| None = None, external_force = None, constraints = (), density: float \| None = None, load_phase: float = 0.0, temperature: float \| None = None, study = None, solver_options = None, name: str = 'harmonic_viscoelastic') -> HarmonicViscoelasticStep	Build one direct 3D harmonic generalized-Maxwell equilibrium Step.
function	quasistatic_viscoelastic_step(*, displacement, material, duration: float, steps: int \| None = None, time_points = None, incrementation = None, time_error_tolerance: float \| None = None, external_force = None, constraints = (), study = None, solver_options = None, quadrature_degree: int = 2, amplitude = None, temperature = None, time_unit: str \| None = None, progress = True, status_file = None, checkpoint_policy = None, name: str = 'viscoelastic') -> QuasistaticViscoelasticStep	Build a 3D quasi-static generalized-Maxwell Step.

agentfem.operators

Kind	Public object	Purpose
class	LumpedMassOperator	Diagonal mass operator owned by the mathematical operator layer.
class	NonlinearOperatorContribution	Additive nonlinear contribution consumed by a numerical Procedure.
class	OperatorForm	Named scientific operator with a current backend expression.
function	action(operator, field)	Return the algebraic action of a matrix-like operator on a field.
function	assemble_matrix(operator, *, bcs = None, backend = None)	Assemble an operator-level matrix from an OperatorForm or UFL form.
function	assemble_vector(operator, *, backend = None)	Assemble an operator-level vector from an OperatorForm or UFL form.
function	bilinear_form(operator, left, right) -> float	Return the algebraic scalar left^T operator right.
function	body_force_vector(force, test_function, *, measure = ufl.dx) -> OperatorForm	Create a body-force/source vector F.
function	boundary_load_vector(load = None, test_function = None, *, value = None, target = None, measure = None, location = None) -> OperatorForm	Create a boundary load vector F_boundary.
function	boundary_force_vector(*, target, value = None, location = None, load = None) -> OperatorForm	Create a boundary force vector from a load object or value/location pair.
function	boundary_model_vector(boundary_model, velocity, test_function = None) -> OperatorForm	Create a vector contribution from a weak boundary model.
function	capacity_operator(temperature, capacity, *, measure = ufl.dx) -> OperatorForm	Create a capacity/storage operator C.
function	combine(*operators, name: str = 'combined_operator', kind: str = 'combined_operator') -> OperatorForm	Combine operator forms or raw UFL expressions into one operator form.
function	compile_form(operator: OperatorForm, *, backend = None)	Compile an OperatorForm or raw UFL form.
function	conduction_operator(temperature, conductivity, *, measure = ufl.dx) -> OperatorForm	Create a conduction/diffusion stiffness operator K.
function	damping_operator(trial_function, test_function = None, coefficient = None, *, measure = ufl.dx) -> OperatorForm	Create a viscous damping operator C.
function	dual_product(vector_operator, field) -> float	Return the global discrete pairing field^T vector_operator.
function	diffusion_operator(trial_function, test_function = None, conductivity = None, *, measure = ufl.dx) -> OperatorForm	Create a scalar diffusion/conduction operator.
function	force_vector(target, loads = None, *, load = None, study = None) -> OperatorForm	Create a total force/source vector from one or more load objects.
function	form_arity(expression) -> int \| None	Return the number of UFL arguments, or None for opaque backends.
function	from_ufl(expression, *, name: str, kind: str = 'custom_operator', family: str = 'custom', role: str \| None = None) -> OperatorForm	Adopt an integrated UFL form without changing its numerical expression.
function	flux_vector(flux, target, *, measure = None, location = None) -> OperatorForm	Create a prescribed scalar boundary-flux vector.
function	heat_capacity_operator(temperature, capacity, *, measure = ufl.dx) -> OperatorForm	Create a heat-capacity operator C for transient heat problems.
function	heat_capacity_vector(previous_temperature, temperature, capacity, *, measure = ufl.dx) -> OperatorForm	Create the known heat-capacity vector C * T_previous.
function	heat_conduction_operator(temperature, conductivity, *, measure = ufl.dx) -> OperatorForm	Create a heat-conduction operator K for -div(k grad(T)).
function	heat_source_vector(source, temperature, *, measure = ufl.dx) -> OperatorForm	Create a heat-source vector Q for a temperature unknown.
function	inertial_force_vector(acceleration, target, density = 1.0, *, measure = ufl.dx) -> OperatorForm	Create the inertial virtual-work vector F_inertia = M a.
function	load_vector(target, loads = None, *, load = None, study = None) -> OperatorForm	Create a total external-load vector F for a target unknown.
function	lumped_mass(V, density = 1.0, *, measure = ufl.dx)	Assemble a lumped mass vector for explicit dynamics.
function	lumped_operator(V, coefficient = 1.0, *, measure = ufl.dx)	Assemble a generic lumped diagonal operator.
function	mass_action_vector(field, target, coefficient = 1.0, *, measure = ufl.dx) -> OperatorForm	Create a vector from a mass-like operator acting on a known field.
function	mass_operator(trial_function, test_function = None, density = 1.0, *, measure = ufl.dx) -> OperatorForm	Create a consistent mass operator M.
function	linearize(residual, unknown, direction = None, *, name: str = 'K_t') -> OperatorForm	Differentiate a residual to obtain its consistent tangent operator.
function	residual_operator(expression, *, name: str = 'R', family: str = 'nonlinear', metadata: dict[str, object] \| None = None) -> OperatorForm	Wrap a nonlinear weak residual R(u; v) as a public operator.
function	rayleigh_damping(mass, stiffness, *, mass_coefficient = 0.0, stiffness_coefficient = 0.0) -> OperatorForm	Create proportional damping C = alpha M + beta K.
function	robin_operator(target, coefficient, *, measure = None, location = None) -> OperatorForm	Create the boundary matrix K_R = integral(h trial test).
function	robin_source_vector(target, coefficient, reference_value, *, measure = None, location = None) -> OperatorForm	Create the Robin environment vector F_R = integral(h x_ref test).
function	scale(operator, factor, *, name: str \| None = None, kind: str \| None = None) -> OperatorForm	Scale an operator or vector form while preserving its engineering role.
function	source_vector(source, target, *, measure = ufl.dx) -> OperatorForm	Create a scalar or vector source/load vector for a target unknown.
function	quadratic_form(operator, field) -> float	Return the algebraic scalar field^T operator field.
function	xtmx(field, operator) -> float	Cast3M-style alias for field^T operator field.
function	xtmy(left, operator, right) -> float	Cast3M-style alias for left^T operator right.
function	stiffness(field, properties = None, *, law = None, study = None, temperature = None, measure = ufl.dx) -> OperatorForm	Create the primary stiffness-like operator K for an unknown field.
class	CellGradientEnergyOperator	Quadratic energy and exact first/second actions for a cell field.
function	cell_gradient_energy(gradient: CellGradientOperator, *, cell_weights, stiffness = 1.0) -> CellGradientEnergyOperator	Create one quadratic matrix-free energy from a cached gradient.
class	CellAverageGradientOperator	Map a FEM field to DG0 cell-average gradients and apply its transpose.
class	ConvectedCellFiberIncrement	Directional derivative of convected cell-fibre kinematics.
class	ConvectedCellFiberKinematics	Current cell tangents, stretch, and unit direction for one fibre family.
class	ConvectedCellFiberOperator	Displacement-derived surface tangents and one convected fibre family.
function	cell_average_gradient(source_space) -> CellAverageGradientOperator	Assemble a reusable FEM-to-DG0 cell-average gradient transfer.
function	convected_cell_fiber(transfer: CellAverageGradientOperator, *, reference_tangents, reference_tangent_coordinates) -> ConvectedCellFiberOperator	Create a displacement-derived cell-fibre kinematic transfer.
class	DisplacementFiberBendingOperator	Exact energy, residual, and tangent for one convected fibre family.
function	displacement_fiber_bending(kinematics: ConvectedCellFiberOperator, gradient: CellGradientOperator, *, cell_weights, in_plane_stiffness = 0.0, normal_stiffness = 0.0, reference_in_plane_curvature = 0.0, reference_normal_curvature = 0.0) -> DisplacementFiberBendingOperator	Compose one displacement-derived neighbour-bending contribution.
class	FiberDirectionBendingIncrement	Directional derivative of a complete bending response.
class	FiberDirectionBendingOperator	Exact first variation of a two-channel fibre-curvature energy.
class	FiberDirectionBendingResponse	Curvature energy and exact direction/surface-tangent duals.
function	fiber_direction_bending(gradient: CellGradientOperator, *, current_tangents, cell_weights, in_plane_stiffness = 0.0, normal_stiffness = 0.0, reference_in_plane_curvature = 0.0, reference_normal_curvature = 0.0) -> FiberDirectionBendingOperator	Create an independent-direction fibre-bending energy operator.
function	elastic_stiffness(displacement, properties, *, study = None, temperature = None, measure = ufl.dx) -> OperatorForm	Create an elastic stiffness operator K from a displacement unknown.
function	internal_force_vector(displacement, test_function = None, properties = None, *, study = None, measure = ufl.dx) -> OperatorForm	Create an elastic internal-force vector contribution.
function	stiffness_operator(displacement, test_function = None, properties = None, *, study = None, temperature = None, measure = ufl.dx) -> OperatorForm	Create an elastic stiffness/internal virtual-work operator K.
function	thermal_expansion_vector(target, temperature, properties, *, study = None, measure = ufl.dx, name: str = 'F_thermal') -> OperatorForm	Equivalent nodal load produced by isotropic thermal expansion.
function	eigenstrain_vector(target, source, properties, *, study = None, measure = ufl.dx, name: str = 'F_eigenstrain') -> OperatorForm	Equivalent nodal load produced by one explicit eigenstrain source.
function	convective_momentum_operator(advecting_velocity, transported_velocity, test_velocity, *, measure = ufl.dx, name: str = 'N_convection') -> OperatorForm	Return ((w . grad) u, v) for vector momentum transport.
function	incompressibility_operator(velocity, test_pressure, *, measure = ufl.dx, name: str = 'D_incompressibility') -> OperatorForm	Return the symmetric saddle-point term -(q, div(u)).
function	pressure_coupling_operator(pressure, test_velocity, *, measure = ufl.dx, name: str = 'G_pressure') -> OperatorForm	Return the pressure contribution -(p, div(v)).
function	viscous_flow_operator(velocity, test_velocity, viscosity, *, measure = ufl.dx, name: str = 'K_viscous') -> OperatorForm	Return nu (grad(u), grad(v)) for incompressible momentum.
function	auxiliary_laplacian_boundary(boundary_expression)	Return -Delta(g) for the auxiliary field w=-Delta(u).
function	split_laplacian_operator(trial, test, *, measure = ufl.dx, name: str = 'K_split_laplacian') -> OperatorForm	Return one second-order block of a mixed biharmonic split.
class	DirectHarmonicSystem	One linear steady-state harmonic system.
function	direct_harmonic_system(K, F, *, M = None, C = None, K_loss = None, name: str = 'direct_harmonic_system') -> DirectHarmonicSystem	Create an inspectable direct harmonic K/M/C/F system.
class	FirstOrderSystem	First-order transient system, C x_dot + K x = F.
class	LinearSystem	Engineering-level static system, usually K x = F.
class	SecondOrderSystem	Engineering-level second-order system, M a + C v + K u = F.
function	first_order_system(C, K, F = None, *, name: str = 'Cxdot_plus_Kx_eq_F')	Create C x_dot + K x = F for heat/diffusion-like evolution.
function	linear_system(K, F = None, *, name: str = 'Kx_eq_F') -> LinearSystem	Create a static linear system in engineering notation, K x = F.
function	second_order_system(M, K, C = None, F = None, *, name: str = 'Ma_plus_Cv_plus_Ku_eq_F')	Create M a + C v + K u = F with optional damping and force.
function	advection_operator(trial, test, velocity, *, measure = ufl.dx, name: str = 'A_advection') -> OperatorForm	Return the Galerkin advection operator (v . grad(u), w).
function	as_velocity(velocity)	Normalize a public velocity sequence without hiding UFL expressions.
function	burgers_convection_operator(advecting_scalar, transported_scalar, test, *, direction = None, measure = ufl.dx, name: str = 'N_burgers') -> OperatorForm	Return scalar Burgers transport u_adv (d . grad(u)).
function	intrinsic_time_scale(domain, velocity, *, diffusivity = None, degree: int = 1, directional: bool = False, time_step: float \| None = None)	Return a cellwise SUPG scale.
function	reaction_expression(value, law: str \| Mapping[str, object], **parameters)	Lower a named scalar reaction law to a UFL expression.
function	streamline_upwind_operator(strong_residual, test, velocity, *, tau = None, domain = None, measure = ufl.dx, name: str = 'A_supg') -> OperatorForm	Return a SUPG contribution tau R(u) (v . grad(w)).
function	transient_transport_forms(trial, test, previous, source, previous_source, velocity, diffusivity, *, dt: float, theta: float = 0.5, tau = None, measure = ufl.dx)	Return (a, L) for a constant-coefficient transport theta step.

agentfem.procedures

Kind	Public object	Purpose
class	SolutionProcedure	Inspectable, backend-neutral description of a solution algorithm.
function	linear_static() -> SolutionProcedure	Public AgentFEM object.
function	modal() -> SolutionProcedure	Undamped linear modes from K phi = lambda M phi.
function	nonlinear_static(*, stateful: bool = False) -> SolutionProcedure	Public AgentFEM object.
function	implicit_euler(*, nonlinear: bool = False, stateful: bool = True) -> SolutionProcedure	Public AgentFEM object.
function	quasistatic_viscoelasticity() -> SolutionProcedure	Exact generalized-Maxwell update with incremental equilibrium.
function	direct_harmonic() -> SolutionProcedure	Direct real-block solve of a complex steady-state harmonic system.
function	direct_harmonic_sweep() -> SolutionProcedure	Ordered independent solves over one canonical frequency axis.
function	implicit_creep() -> SolutionProcedure	Quasi-static backward-Euler creep with global Newton equilibrium.
function	viscoelastic_history() -> SolutionProcedure	Exact increment-wise generalized-Maxwell material history.
function	material_history() -> SolutionProcedure	Increment-wise material-point response without a global FEM solve.
function	newmark() -> SolutionProcedure	Public AgentFEM object.
function	generalized_alpha() -> SolutionProcedure	Public AgentFEM object.
function	central_difference() -> SolutionProcedure	Public AgentFEM object.
function	cyclic_fatigue() -> SolutionProcedure	Quasi-static peak/valley equilibrium with independent cycle blocks.
function	for_step(*, analysis: str, method: str \| None = None, stateful: bool = False)	Resolve a procedure without coupling Study to one solver route.
function	resolve(*, analysis: str, requested: SolutionProcedure \| str \| None = None, preferred: str \| None = None, stateful: bool = False) -> SolutionProcedure	Resolve and validate the numerical procedure for one analysis request.

agentfem.responses

Kind	Public object	Purpose
class	ResponseReport	A finite-difference Jacobian and the cases that support it.
class	FiniteDifferenceResponse	A method-neutral response contract with a finite-difference provider.
function	finite_difference(**kwargs) -> FiniteDifferenceResponse	Create a campaign-backed finite-difference response experiment.

agentfem.solvers

Kind	Public object	Purpose
class	LinearSolverOptions	PETSc KSP options for a linear solve.
function	direct_solver(*, package: str \| None = None) -> LinearSolverOptions	Create a direct linear-solver policy without PETSc option names.
class	NonlinearSolverOptions	PETSc SNES/KSP policy for nonlinear finite-element solves.
class	NewtonSolverOptions	Backend-neutral Newton policy for nonlinear equilibrium.
function	newton(*, relative_tolerance: float = 1e-08, absolute_tolerance: float = 1e-09, maximum_iterations: int = 30, line_search: str \| None = 'backtracking', linear_solver: LinearSolverOptions \| None = None, error_if_not_converged: bool = True) -> NewtonSolverOptions	Create one Newton policy for ordinary and affine-constrained steps.
class	NonlinearSolveInfo	Convergence evidence returned by a PETSc SNES solve.
class	AffineNewtonOptions	Newton policy for an affine-reduced nonlinear equilibrium path.
class	AffineLoadIncrementInfo	Convergence evidence for one macroscopic load increment.
class	AffineLoadPathInfo	Convergence evidence for an incrementally applied affine constraint.
function	create_ksp(comm, options: LinearSolverOptions \| None = None)	Create and configure a PETSc KSP object.
class	LinearSolveInfo	PETSc KSP convergence evidence for one linear system solve.
class	PreparedLinearProblem(bilinear_form, linear_form, solution, *, bcs = None, bc_assembly: str = 'lifting', options: LinearSolverOptions \| None = None)	A linear problem whose constant matrix and KSP are assembled once.
function	prepare_linear_problem(bilinear_form, linear_form, solution, *, bcs = None, bc_assembly: str = 'lifting', options: LinearSolverOptions \| None = None) -> PreparedLinearProblem	Prepare one constant linear operator for repeated right-hand sides.
class	PreparedMPCLinearProblem(bilinear_form, linear_form, solution, constraint, *, bcs = None, options: LinearSolverOptions \| None = None, petsc_options_prefix: str = 'agentfem_mpc_linear_')	Reusable linear solve lowered through one exact MPC provider.
function	prepare_mpc_linear_problem(bilinear_form, linear_form, solution, constraint, *, bcs = None, options: LinearSolverOptions \| None = None, petsc_options_prefix: str = 'agentfem_mpc_linear_') -> PreparedMPCLinearProblem	Prepare one exact-MPC operator for repeated right-hand sides.
function	solve_mpc_linear_problem(bilinear_form, linear_form, solution, constraint, *, bcs = None, options: LinearSolverOptions \| None = None, petsc_options_prefix: str = 'agentfem_mpc_linear_', return_info: bool = False)	Solve one linear variational problem with an exact MPC backend.
function	solve_matrix_system(A, b, x, options: LinearSolverOptions \| None = None, *, ksp = None, raise_on_failure: bool \| None = None) -> LinearSolveInfo	Solve A x = b and return explicit PETSc convergence evidence.
function	solve_linear_problem(bilinear_form, linear_form, solution, *, bcs = None, bc_assembly: str = 'lifting', options: LinearSolverOptions \| None = None, return_info: bool = False)	Assemble and solve a standard linear variational problem.
function	solve_nonlinear_problem(residual_form, solution, *, bcs = None, jacobian_form = None, options: NonlinearSolverOptions \| NewtonSolverOptions \| None = None, petsc_options_prefix: str = 'agentfem_nonlinear_') -> tuple[object, NonlinearSolveInfo]	Solve R(u; v) = 0 with the current DOLFINx PETSc/SNES interface.
function	solve_affine_nonlinear_path(residual_form, jacobian_form, solution, constraint, *, load_factors = None, incrementation = None, output_factors = (), options: AffineNewtonOptions \| NewtonSolverOptions \| None = None, on_increment = None, on_accepted_boundary = None, on_acceptance_failure = None, acceptance_check = None, state_transaction = None, stop_factor: float = 1.0, accepted_history = (), attempted_history = (), next_increment_size: float \| None = None, reporter = None, step_name: str = 'affine_nonlinear', step_number: int = 1) -> tuple[object, AffineLoadPathInfo]	Solve a nonlinear path under u = T q + u_bar constraints.
function	attach_nullspace(matrix, modes, *, rhs = None)	Attach explicit orthonormalized null modes (e.g. constant pressure).

agentfem.state

Kind	Public object	Purpose
class	RestartableState	State whose accepted scientific identity can cross a restart.
class	ReplaceableState	State with an atomic trial/accept/reject boundary.
class	StateCapabilities	Inspectable transaction features without guessing from class names.
function	capabilities(value: object) -> StateCapabilities	Describe the transaction boundary implemented by value.
function	require_restartable(value: object, *, name: str = 'state') -> RestartableState	Return value or fail with an addressable ownership error.
function	require_replaceable(value: object, *, name: str = 'state') -> ReplaceableState	Return value or fail unless it owns atomic accept/reject semantics.
class	TransientState	Accepted/trial fields for a first-order transient unknown.
class	SecondOrderDynamicsState	Accepted/trial displacement, velocity, and acceleration fields.
function	second_order_state(field_or_space, **kwargs) -> SecondOrderDynamicsState	Create a second-order state from a field or function space.

agentfem.surrogates

Kind	Public object	Purpose
class	Prediction	One named prediction with source and trust diagnostics.
class	QuantityMetrics	Error evidence for one declared output quantity.
class	SurrogateValidationReport	Independent validation metrics and optional acceptance decision.
function	validate_predictions(*, model_kind: str, dataset: ScientificDataset, predictions: np.ndarray, thresholds: Mapping[str, float] \| None = None) -> SurrogateValidationReport	Compare flattened predictions with a dataset's declared quantities.
class	BoxApplicabilityDomain	Axis-aligned envelope in normalized scientific parameter space.
class	GuardedSurrogate	Use a surrogate only inside its declared applicability domain.
class	OutOfDomainError	Raised when an unguarded surrogate is asked to extrapolate.
class	PODRidgeSurrogate	Proper-orthogonal-decomposition outputs plus ridge latent dynamics.
class	RidgeSurrogate	Multi-output ridge regression baseline.
class	TrainedPODRidge	Fitted POD-ridge field/curve surrogate.
class	TrainedRidge	Fitted ridge surrogate with named prediction and validation methods.
class	AffineCoordinateMap	Explicit affine map from observation coordinates to model coordinates.
class	FieldEncoding	How a physical field becomes a machine-learning tensor.
class	NeuralOperatorSpec	Function-to-function learning contract for an external trainer.
class	ObservationGrid	Mesh-independent Cartesian coordinates for field learning and sensing.
class	PhysicsCondition	Boundary, initial, interface, or observation condition in a loss.
class	PhysicsResidual	One explicit differentiable residual used in a physics loss.
class	PINNSpec	Physics-informed training contract for selected explicit residuals.
function	regular_grid(*, bounds, shape, axis_names = None, coordinate_system: str = 'cartesian', order: str = 'C', coordinate_unit: str \| None = None) -> ObservationGrid	Create an evenly spaced observation grid from physical bounds.
class	TorchMLPSurrogate	Configurable dense-network baseline for parameter-to-QoI learning.
class	TrainedTorchMLP	In-memory trained PyTorch adapter.
class	PINNTrainingRecord	In-memory training evidence without serializing a PyTorch pickle.
class	TorchPINNAdapter	Bind explicit residual/condition callables to a :class:PINNSpec.
class	SurrogateTrainingRun	A trained model together with its independent validation evidence.
function	train(dataset: ScientificDataset, *, estimator = None, validation_fraction: float = 0.2, seed: int = 0, thresholds = None) -> SurrogateTrainingRun	Split, fit, and independently validate one surrogate estimator.

agentfem.assembly

Kind	Public object	Purpose
function	make_form(ufl_form)	Compile a UFL form for assembly.
function	assemble_vector(form)	Assemble a vector and accumulate ghost contributions to owned entries.
function	assemble_cell_residual(space, cell_contributions)	Accumulate local-and-ghost cell contributions into a DG0 PETSc vector.
function	assemble_matrix(form, bcs = None)	Assemble a matrix and apply optional strong Dirichlet BC structure.
function	assemble_lumped_operator(V, coefficient = 1.0, measure = ufl.dx) -> np.ndarray	Assemble a diagonal/lumped operator vector on V.
function	assemble_lumped_mass(V, density = 1.0, measure = ufl.dx) -> np.ndarray	Assemble a lumped mass vector for a scalar or vector space.
function	inverse_diagonal(diagonal: np.ndarray) -> np.ndarray	Return a safe inverse for a diagonal vector.

agentfem.backends

Kind	Public object	Purpose
class	BackendAdapter	Minimal interface used by operator compilation and assembly.
class	BackendDescriptor	Inspectable backend identity and capability statement.
class	AdditiveTangentMatrix	Owned shell operator paired with its assembled preconditioner matrix.
function	create_additive_tangent_matrix(local_matrix: PETSc.Mat, actions: Iterable[TangentAction] = (), *, preconditioner_matrix: PETSc.Mat \| None = None, constrained_local_dofs: Iterable[int] = ()) -> AdditiveTangentMatrix	Create A = A_local + sum(A_nonlocal) with an assembled P.
class	FEniCSxTangentAction	Bind a nonlinear contribution and state to a PETSc tangent callback.
function	fenicsx_tangent_action(contribution, state) -> FEniCSxTangentAction	Create a reusable PETSc callback for one FEniCSx primary field.
class	FEniCSxBackend	Current production backend for AgentFEM operator forms.
function	available_backends() -> tuple[str, ...]	Return registered backend names without importing their dependencies.
function	backend_descriptors() -> tuple[BackendDescriptor, ...]	Return descriptors for all registered backends.
function	default_backend_name() -> str	Public AgentFEM object.
function	get_backend(name: str \| None = None) -> BackendAdapter	Return a lazily constructed backend adapter.
function	register_backend(name: str, factory: BackendFactory, *, overwrite: bool = False) -> None	Register a lazy backend factory.
function	set_default_backend(name: str) -> None	Select the process-local default backend by registered name.

agentfem.benchmarks

Kind	Public object	Purpose
class	BenchmarkSpec	One verification obligation and its executable evidence.
function	benchmark(identifier: str) -> BenchmarkSpec	Return one benchmark by stable identifier.
function	list_benchmarks(*, capability: str \| None = None) -> tuple[BenchmarkSpec, ...]	Return all benchmarks or those for one capability.
class	CapabilityEvidence	Evidence supporting one declared constitutive maturity boundary.
function	audit_capability_evidence() -> tuple[CapabilityEvidence, ...]	Return a stable, machine-readable audit for the whole catalog.
function	capability_evidence(capability: ConstitutiveCapability, *, benchmarks: tuple[BenchmarkSpec, ...] \| None = None) -> CapabilityEvidence	Audit one catalog capability against the benchmark registry.
class	GoldenBenchmark	A named collection of numerical observables from a benchmark card.
class	GoldenQuantity	One expected physical observable with explicit numerical tolerances.
function	golden_benchmark(identifier: str) -> GoldenBenchmark	Load a numerical contract by stable benchmark-card identifier.
class	AxisymmetricRatchetingCrosscheck	Global axisymmetric equilibrium checked against the same local path.
class	CyclicPlasticityBenchmark	Compact acceptance evidence against two published cyclic observables.
class	RatchetingPathComparison	Published-path conformance without inventing a numerical Golden.
function	abaqus_316_steel_ratcheting_path_comparison(*, cycle_count: int = 50, refinement: int = 2, residual_tolerance: float = 1e-07)	Exercise the published 316-steel asymmetric stress path.
function	abaqus_ofhc_copper_cyclic_benchmark(*, substeps_per_half_cycle: int = 10, points_per_cycle: int = 20, relative_tolerance: float = 0.01, saturation_tolerance: float = 0.01)	Run the published symmetric and nonproportional OFHC copper tests.
function	axisymmetric_chaboche_ratcheting_crosscheck(*, cycle_count: int = 3, refinement: int = 2, radial_cells: int = 1, axial_cells: int = 2, relative_tolerance: float = 0.002, residual_tolerance: float = 1e-07)	Cross-check a global axisymmetric tube against one material point.
class	DigitizedRatchetingCurve	Traceable points read from a published raster figure.
class	ShoulderedRatchetingAccuracy	Spatial and accuracy-driven path-integration certificate.
class	ShoulderedRatchetingAssessment	Structure-level comparison without overstating plotted evidence.
class	ShoulderedRatchetingConvergence	Independent spatial and path-integration convergence certificate.
class	ShoulderedRatchetingFullReference	One fine-path run covering every point on the public 100-cycle curve.
function	certify_simulia_316_shouldered_ratcheting_accuracy(*, cycle_count: int = 5, mesh_sizes: tuple[float, ...] = (3.5, 2.5), maximum_inelastic_increments: tuple[float, ...] = (0.004, 0.002, 0.001), relative_tolerance: float = 0.01, progress: bool = False)	Certify mesh and adaptive constitutive-path accuracy independently.
function	certify_simulia_316_shouldered_ratcheting_convergence(*, cycle_count: int = 5, mesh_sizes: tuple[float, ...] = (3.5, 2.5), refinements: tuple[int, ...] = (8, 16, 32), relative_tolerance: float = 0.01, progress: bool = False)	Certify spatial and material-path refinement independently.
function	certify_simulia_316_shouldered_ratcheting_full_reference(*, cycle_count: int = 100, mesh_size: float = 2.5, maximum_inelastic_increment: float = 0.001, progress: bool = False)	Run the fine-path case over the complete published cycle range.
function	simulia_316_experimental_ratcheting_curve() -> DigitizedRatchetingCurve	Return auditable experimental points digitized from public Figure 4.
function	simulia_316_shouldered_ratcheting_benchmark(*, cycle_count: int = 5, refinement: int = 4, mesh_size: float = 3.5, backstress_count: int = 2, allowed_absolute_curve_error: float = 0.00125, residual_tolerance: float = 1e-07, maximum_inelastic_increment: float \| None = None, source_input: str \| Path \| None = None, progress: bool = False)	Run the public shouldered-specimen ratcheting comparison.
function	simulia_316_shouldered_specimen_mesh(*, mesh_size: float = 1.25, comm = None)	Mesh the published meridian without redistributing a vendor input deck.
function	verify_simulia_ratcheting_input(path: str \| Path) -> bool	Verify the exact public two-backstress Abaqus input deck by SHA-256.
class	DCBCohesivePropagationCertificate	Three-level DCB propagation, energy and process-zone certificate.
class	DCBCohesivePropagationCurve	Accepted DCB cohesive evolution and its work--energy evidence.
class	DCBCohesivePropagationPoint	One accepted displacement-controlled DCB propagation increment.
class	DCBCohesivePropagationStudy	Three-or-more-level assembled DCB cohesive propagation study.
class	DCBComplianceConvergenceCertificate	Spatial-convergence evidence for a precracked, elastic DCB model.
class	DCBFiniteElementCurve	Structure-level DCB compliance and energy-release evidence.
class	DCBFiniteElementConvergenceStudy	Three-or-more-level assembled DCB compliance study.
class	DCBFiniteElementPoint	One load--opening solution for a discretized DCB specimen.
function	certify_dcb_cohesive_propagation(spec: DelaminationBenchmarkSpec, curves, *, refinement_relative_tolerance: float = 0.1, energy_relative_tolerance: float = 0.03, required_process_zone_elements: float = 3.0) -> DCBCohesivePropagationCertificate	Certify refined DCB propagation without conflating local-law tests.
function	certify_dcb_compliance_convergence(spec: DelaminationBenchmarkSpec, curves, *, reference_relative_tolerance: float, refinement_relative_tolerance: float, residual_tolerance: float = 1e-08) -> DCBComplianceConvergenceCertificate	Certify assembled DCB compliance against a declared beam oracle.
function	dcb_cohesive_propagation_convergence(spec: DelaminationBenchmarkSpec, *, precrack_length: float, specimen_length: float, opening, strength: float, fracture_energy: float, initial_stiffness: float, mesh_levels, poisson: float = 0.3, assumption: str = 'plane_stress', solver_options = None, minimum_opening_increment: float \| None = None, maximum_cutbacks: int = 12, refinement_relative_tolerance: float = 0.1, energy_relative_tolerance: float = 0.03, required_process_zone_elements: float = 3.0) -> DCBCohesivePropagationStudy	Execute and certify three or more DCB cohesive propagation levels.
function	dcb_cohesive_propagation_curve(spec: DelaminationBenchmarkSpec, *, precrack_length: float, specimen_length: float, opening, strength: float, fracture_energy: float, initial_stiffness: float, elements_along: int, elements_per_arm: int, poisson: float = 0.3, assumption: str = 'plane_stress', solver_options = None, minimum_opening_increment: float \| None = None, maximum_cutbacks: int = 12) -> DCBCohesivePropagationCurve	Run a displacement-controlled, irreversible Mode-I DCB path.
function	dcb_finite_element_convergence(spec: DelaminationBenchmarkSpec, *, crack_length, load: float, specimen_length: float, mesh_levels, poisson: float = 0.3, assumption: str = 'plane_stress', interface_stiffness: float \| None = None, solver_options = None, reference_relative_tolerance: float = 0.1, refinement_relative_tolerance: float = 0.05, residual_tolerance: float = 1e-08) -> DCBFiniteElementConvergenceStudy	Run and certify three or more assembled DCB mesh levels.
function	dcb_finite_element_curve(spec: DelaminationBenchmarkSpec, *, crack_length, load: float, specimen_length: float, elements_along: int, elements_per_arm: int, poisson: float = 0.3, assumption: str = 'plane_stress', interface_stiffness: float \| None = None, solver_options = None) -> DCBFiniteElementCurve	Solve a linear-elastic DCB family with one fixed-path interface.
class	ENFCohesivePropagationCertificate	Three-level ENF propagation, energy and Mode-II certificate.
class	ENFCohesivePropagationCurve	Accepted ENF cohesive evolution and its work--energy evidence.
class	ENFCohesivePropagationPoint	One accepted displacement-controlled ENF propagation increment.
class	ENFCohesivePropagationStudy	Three-or-more-level assembled ENF cohesive propagation study.
class	ENFComplianceConvergenceCertificate	Three-level ENF compliance evidence against a declared beam oracle.
class	ENFFiniteElementConvergenceStudy	Three-or-more-level assembled ENF compliance study.
class	ENFFiniteElementCurve	Assembled ENF compliance and pure Mode-II energy-release evidence.
class	ENFFiniteElementPoint	One displacement-controlled solution of an ENF specimen.
function	certify_enf_cohesive_propagation(spec: DelaminationBenchmarkSpec, curves, *, refinement_relative_tolerance: float = 0.1, energy_relative_tolerance: float = 0.03, required_process_zone_elements: float = 3.0, required_mode_ii_fraction: float = 0.9) -> ENFCohesivePropagationCertificate	Certify refined ENF propagation without accepting damage images alone.
function	certify_enf_compliance_convergence(spec: DelaminationBenchmarkSpec, curves, *, reference_relative_tolerance: float, refinement_relative_tolerance: float, residual_tolerance: float = 1e-08) -> ENFComplianceConvergenceCertificate	Compare refined assembled ENF compliance with simple-beam theory.
function	enf_cohesive_propagation_convergence(spec: DelaminationBenchmarkSpec, *, precrack_length: float, displacement, normal_strength: float, shear_strength: float, normal_fracture_energy: float, shear_fracture_energy: float, normal_stiffness: float, tangential_stiffness: float, mesh_levels, poisson: float = 0.3, assumption: str = 'plane_stress', interaction: str = 'bk', interaction_exponent: float = 1.45, solver_options = None, minimum_displacement_increment: float \| None = None, maximum_cutbacks: int = 12, refinement_relative_tolerance: float = 0.1, energy_relative_tolerance: float = 0.03, required_process_zone_elements: float = 3.0, required_mode_ii_fraction: float = 0.9) -> ENFCohesivePropagationStudy	Execute and certify three or more ENF cohesive propagation levels.
function	enf_cohesive_propagation_curve(spec: DelaminationBenchmarkSpec, *, precrack_length: float, displacement, normal_strength: float, shear_strength: float, normal_fracture_energy: float, shear_fracture_energy: float, normal_stiffness: float, tangential_stiffness: float, elements_along: int, elements_per_arm: int, poisson: float = 0.3, assumption: str = 'plane_stress', interaction: str = 'bk', interaction_exponent: float = 1.45, solver_options = None, minimum_displacement_increment: float \| None = None, maximum_cutbacks: int = 12) -> ENFCohesivePropagationCurve	Run an irreversible ENF path with explicit Mode-II evidence.
function	enf_finite_element_convergence(spec: DelaminationBenchmarkSpec, *, crack_length, control_displacement: float, mesh_levels, poisson: float = 0.3, assumption: str = 'plane_stress', interface_stiffness: float \| None = None, solver_options = None, reference_relative_tolerance: float = 0.1, refinement_relative_tolerance: float = 0.05, residual_tolerance: float = 1e-08) -> ENFFiniteElementConvergenceStudy	Run and certify three or more assembled ENF mesh levels.
function	enf_finite_element_curve(spec: DelaminationBenchmarkSpec, *, crack_length, control_displacement: float, elements_along: int, elements_per_arm: int, poisson: float = 0.3, assumption: str = 'plane_stress', interface_stiffness: float \| None = None, solver_options = None) -> ENFFiniteElementCurve	Solve a precracked ENF family under three-point bending.
class	DelaminationBenchmarkAssessment	Acceptance evidence for one structural cohesive benchmark.
class	DelaminationBenchmarkSpec	Geometry and evidence contract for DCB, ENF or MMB verification.
class	DelaminationConvergenceCertificate	Three-level spatial convergence and structural-reference evidence.
class	DelaminationEnergyReleaseCurve	Compliance-derived structural GI/GII evidence versus crack length.
class	MixedModeBendingComparison	Curve-level errors under explicitly declared scientific tolerances.
class	MixedModeBendingCurve	One traceable load/displacement/mode-mix curve versus crack length.
function	assess_delamination_benchmark(spec, predicted, reference, *, energy_release_relative_tolerance, minimum_process_zone_elements, required_process_zone_elements = 3.0, artificial_dissipation = 0.0, internal_energy = 1.0) -> DelaminationBenchmarkAssessment	Apply curve, cohesive-zone resolution and dissipation guardrails.
function	beam_theory_energy_release_curve(spec, *, crack_length, load)	Return a DCB/ENF analytical oracle through the same public contract.
function	compliance_energy_release_curve(spec: DelaminationBenchmarkSpec, *, crack_length, load, displacement = None, compliance = None, mode_i_fraction = None, source: str \| None = None) -> DelaminationEnergyReleaseCurve	Recover structural energy release by the compliance derivative.
function	certify_delamination_convergence(spec, curves, reference, *, element_sizes, process_zone_elements, artificial_dissipation_fractions, reference_relative_tolerance, refinement_relative_tolerance, mode_partition_absolute_tolerance = 0.02, required_process_zone_elements = 3.0, allowed_artificial_dissipation_fraction = 0.05) -> DelaminationConvergenceCertificate	Certify a DCB/ENF/MMB curve using three or more structural levels.
function	compare_mixed_mode_bending_curves(reference: MixedModeBendingCurve, predicted: MixedModeBendingCurve, *, load_relative_tolerance: float, displacement_relative_tolerance: float, mode_i_fraction_absolute_tolerance: float) -> MixedModeBendingComparison	Compare a computed curve on the reference crack-length coordinates.
function	dcb_beam_compliance(spec, crack_length)	Euler--Bernoulli DCB compliance for two arms of thickness h.
function	delamination_benchmark_spec(kind, **geometry) -> DelaminationBenchmarkSpec	Create a DCB, ENF or MMB numerical-verification specification.
function	enf_beam_compliance(spec, crack_length)	Classical simple-beam ENF compliance with support half-span L.
function	mmb_beam_energy_release_curve(spec: DelaminationBenchmarkSpec, *, crack_length, load, lever_length: float) -> DelaminationEnergyReleaseCurve	Return the classical Reeder--Crews MMB simple-beam oracle.
function	nasa_cr_2012_mmb_80_reference() -> MixedModeBendingCurve	Load the vector-extracted NASA 80%-Mode-II MMB reference curve.
class	MMBComplianceCertificate	Assembled MMB compliance comparison with a Reeder--Crews oracle.
class	MMBCohesivePropagationCertificate	Fail-closed certificate for one assembled mixed-mode propagation path.
class	MMBCohesivePropagationCurve	Accepted mixed-mode cohesive path and work--energy evidence.
class	MMBCohesivePropagationPoint	One accepted rigid-lever MMB cohesive increment.
class	MMBFiniteElementCurve	Rigid-lever MMB compliance and energy-release evidence.
class	MMBFiniteElementPoint	One rigid-lever controlled solution of a discretized MMB specimen.
class	MMBModePartitionCertificate	Independent VCCT comparison with the Reeder--Crews beam partition.
function	certify_mmb_cohesive_propagation(curve: MMBCohesivePropagationCurve, *, energy_relative_tolerance: float = 0.03, required_process_zone_elements: float = 3.0, control_residual_tolerance: float = 1e-10, newton_residual_tolerance: float = 1e-07) -> MMBCohesivePropagationCertificate	Certify mechanism evidence without calling it external validation.
function	certify_mmb_compliance(curve: MMBFiniteElementCurve, *, compliance_relative_tolerance: float, control_residual_tolerance: float = 1e-10, newton_residual_tolerance: float = 1e-08) -> MMBComplianceCertificate	Compare one assembled fixture curve with its declared beam oracle.
function	certify_mmb_mode_partition(curve: MMBFiniteElementCurve, *, energy_closure_relative_tolerance: float = 0.08, mode_i_fraction_absolute_tolerance: float = 0.08) -> MMBModePartitionCertificate	Compare independently recovered VCCT channels with beam theory.
function	mmb_cohesive_propagation_curve(spec: DelaminationBenchmarkSpec, *, precrack_length: float, displacement, lever_length: float, normal_strength: float, shear_strength: float, normal_fracture_energy: float, shear_fracture_energy: float, normal_stiffness: float, tangential_stiffness: float, elements_along: int, elements_per_arm: int, poisson: float = 0.3, assumption: str = 'plane_stress', bulk_material = None, interaction: str = 'bk', interaction_exponent: float = 1.45, solver_options = None, minimum_displacement_increment: float \| None = None, maximum_cutbacks: int = 12) -> MMBCohesivePropagationCurve	Run an irreversible MMB path with exact work-conjugate control.
function	mmb_finite_element_curve(spec: DelaminationBenchmarkSpec, *, crack_length, control_displacement: float, lever_length: float, elements_along: int, elements_per_arm: int, poisson: float = 0.3, assumption: str = 'plane_stress', interface_stiffness: float \| None = None, bulk_material = None, solver_options = None) -> MMBFiniteElementCurve	Solve elastic precracked MMB points with an exact rigid-lever control.
class	CohesiveEnergyBenchmark	Energy closure for one uniformly separating cohesive interface.
class	ClassicalCrackBenchmark	Fixed-path Mode-I crack propagation evidence for the V3 guardrail.
class	ThinThreeDimensionalCrossCheck	Plane-stress condensation versus an affine thin-3D FEM patch.
class	WaveArrivalBenchmark	Measured and acoustic-tensor wave speed in reference coordinates.
class	WeakInterfaceConvergenceStudy	Two-dimensional mesh and time-step evidence for one V4 mechanism.
class	WeakInterfaceTransitionBenchmark	One prestressed thin-sheet case in the JMPS V4 mechanism ladder.
class	WeakInterfaceTransitionSuite	Auditable crack-like to supershear to spall-like V4 mechanism gate.
function	cohesive_energy_balance(*, dt: float = 0.001, loading_time: float = 0.2, opening: float = 0.08) -> CohesiveEnergyBenchmark	Open one split interface through a smooth prescribed-motion history.
function	classical_cohesive_crack(*, cells: int = 60, length: float = 3.0, precrack_length: float = 0.5, opening: float = 0.0135, loading_time: float = 0.15, hold_time: float = 0.15, time_step_scale: float = 0.8, damping: float = 0.0) -> ClassicalCrackBenchmark	Propagate a precracked cohesive strip below the classical limit.
function	finite_strain_wave_arrival(*, prestrain: float = 0.0, cells: int = 80, courant: float = 0.3, length: float = 2.0, source_position: float = 0.25, receiver_positions = (0.75, 1.25), pulse_width: float = 0.1) -> WaveArrivalBenchmark	Measure a small longitudinal pulse about a held homogeneous stretch.
function	jmps_weak_interface_transition_v4(*, cells: int = 30, total_time: float = 0.1, history_every: int = 5) -> WeakInterfaceTransitionSuite	Run the first fixed, executable JMPS-inspired V4 mechanism ladder.
function	jmps_weak_interface_convergence_v4(*, history_every: int = 20, spatial_speed_tolerance: float = 0.1, temporal_speed_tolerance: float = 0.02) -> WeakInterfaceConvergenceStudy	Run the opt-in two-dimensional V4 supershear convergence contract.
function	plane_stress_thin_3d_crosscheck(*, axial_stretch: float = 1.12, reference_thickness: float = 0.02, cells = (2, 2, 1), young: float = 1000000.0, poisson: float = 0.49, density: float = 1000.0, tolerance: float = 1e-09) -> ThinThreeDimensionalCrossCheck	Compare condensed 2D membrane response with a thin 3D FEM patch.
function	prestressed_weak_interface_separation(*, label: str = 'v4_candidate', cells: int = 60, transverse_cells: int = 2, length: float = 3.0, height: float = 1.0, precrack_length: float = 0.5, axial_strain: float = 0.12, strength: float = 10.0, fracture_energy: float = 0.1, initial_stiffness: float = 10000.0, young: float = 1000.0, poisson: float = 0.49, density: float = 1.0, total_time: float = 0.2, time_step_scale: float = 0.8, damping: float = 0.0, history_every: int = 1, impact_displacement: float = 0.0, impact_rise_time: float \| None = None, speed_fit_length: float \| None = None, bulk_material = None, retain_trace: bool = False) -> WeakInterfaceTransitionBenchmark	Drive a precrack through a prestressed plane-stress weak interface.
function	creep_thick_cylinder_benchmark(*, comm = MPI.COMM_WORLD, radial_cells: int = 4, angular_cells: int = 8, axial_cells: int = 1, increments: int = 300, duration: float = 1000.0, creep_strain_error_tolerance: float = 0.0005, progress: object = False, formulation: str = 'axisymmetric') -> InelasticStructuralBenchmark	Run the NAFEMS R0027 Test 7 secondary-creep benchmark.
class	InelasticStructuralBenchmark	Compact, rank-independent evidence from one structural benchmark.
function	j2_plane_strain_first_yield_pressure(*, inner_radius: float, outer_radius: float, poisson: float, yield_stress: float) -> float	Lamé plane-strain pressure at first Mises yield on the inner wall.
function	j2_thick_cylinder_benchmark(*, comm = MPI.COMM_WORLD, radial_cells: int = 4, angular_cells: int = 8, axial_cells: int = 1, increments: int = 24, formulation: str = 'three_dimensional_sector') -> InelasticStructuralBenchmark	Run the Comet-FEniCSx thick-cylinder first-yield benchmark.
function	power_law_creep_cylinder_stress(radius, *, inner_radius: float, outer_radius: float, pressure: float, stress_exponent: float) -> tuple[np.ndarray, np.ndarray, np.ndarray]	Return the NAFEMS R0027 Test 7 steady-state cylinder stresses.
function	thick_cylinder_sector_mesh(*, inner_radius: float, outer_radius: float, thickness: float, radial_cells: int, angular_cells: int, cell_type: str = 'tetrahedron', comm = MPI.COMM_WORLD)	Create a one-layer 3D quarter-cylinder benchmark mesh.
class	Elasticity3DBenchmark	Rank-independent evidence from a public 3D elasticity benchmark.
function	nafems_le10_3d_benchmark(*, radial_cells: int = 4, angular_cells: int = 12, thickness_cells: int = 2, comm = MPI.COMM_WORLD, output = None) -> tuple[Elasticity3DBenchmark, object]	Solve NAFEMS LE10 and return benchmark evidence plus SimulationResult.
function	nafems_le10_mesh(*, radial_cells: int = 4, angular_cells: int = 12, thickness_cells: int = 2, geometry_degree: int = 2, comm = MPI.COMM_WORLD)	Create the quarter thick-elliptical-plate domain from NAFEMS LE10.
class	ForcedVibrationBenchmark	Rank-independent evidence for one public forced-vibration problem.
class	ForcedVibrationConvergenceCertificate	Spatial-refinement stability evidence for a harmonic benchmark.
function	certify_nafems_r0016_test5h_spatial_convergence(levels, *, refinement_relative_tolerances = None, residual_tolerance: float = 1e-08, energy_tolerance: float = 1e-08) -> ForcedVibrationConvergenceCertificate	Certify a declared three-or-more-level Test 5H refinement sequence.
function	nafems_r0016_test5h_benchmark(*, cells = (5, 2, 1), frequencies = None, comm = MPI.COMM_WORLD) -> tuple[ForcedVibrationBenchmark, object]	Solve the public NAFEMS R0016 Test 5H physical problem.
function	nafems_r0016_test5h_spatial_convergence(*, cells = ((5, 2, 1), (9, 4, 3), (13, 6, 5)), comm = MPI.COMM_WORLD)	Execute the declared Test 5H spatial-refinement stability study.
class	CenterCrackLEFMBenchmark	One solved center-crack model and its independently extracted evidence.
function	center_crack_lefm_mesh(*, half_crack_length: float = 1.0, half_width: float = 8.0, half_height: float = 8.0, comm = MPI.COMM_SELF)	Build the serial, conforming split mesh used by the LEFM benchmark.
function	center_crack_mode_i_benchmark(*, young_modulus: float = 1000.0, poisson_ratio: float = 0.25, half_crack_length: float = 1.0, half_width: float = 8.0, half_height: float = 8.0, remote_strain: float = 0.001, relative_tolerance: float = 0.05) -> CenterCrackLEFMBenchmark	Solve and verify a finite-plate Mode-I crack with the public workflow.

agentfem.dependencies

Kind	Public object	Purpose
class	OptionalDependencyError(*, package: str, extra: str, capability: str)	Raised when a requested optional capability is not installed.
class	DependencyStatus	Inspectable availability record for one optional integration.
function	require(package: str, *, extra: str, capability: str)	Import an optional package or raise an installation-specific error.
function	status(package: str, *, extra: str, capability: str) -> DependencyStatus	Return package availability without importing compiled extensions.

agentfem.diagnostics

Kind	Public object	Purpose
class	PerformanceLedger	Low-overhead, rank-local timing evidence for one solver lifecycle.
class	DiscreteInfSupEvidence	Basis-normalized singular evidence for one mixed discretization.
class	DiscreteInfSupSample	One normalized mixed-stability measurement on a declared mesh.
class	DiscreteInfSupStudy	Coarse-to-fine evidence for one family of mixed discretizations.
function	discrete_inf_sup(constraint_matrix, *, primal_norm, multiplier_norm, rank_tolerance: float \| None = None) -> DiscreteInfSupEvidence	Compute one norm-aware discrete inf-sup spectrum.
function	comm_of(obj = None, default = MPI.COMM_WORLD)	Return the MPI communicator associated with an object when possible.
function	is_root(obj = None, *, root: int = 0) -> bool	Return whether the current MPI rank is the selected reporting rank.
function	print_on_root(obj, *args, root: int = 0, flush: bool = True, **kwargs) -> None	Print a message only on the selected MPI root rank.
class	StandardRunReporter	Immediate rank-zero progress for long-running analysis steps.
class	SolveEventRecorder	In-memory structured execution trace shared by every procedure.
class	ReporterGroup	Fan one solver event out to several independent consumers.
function	compose_reporters(*reporters) -> object \| None	Compose progress, persistence, and agent observers without coupling.
function	kinetic_energy(mass_lumped: np.ndarray, velocity: fem.Function) -> float	Global kinetic energy from a lumped mass vector and velocity field.
class	MechanicalEnergy	Kinetic, recoverable strain, and total mechanical energy.
function	mechanical_energy(*, mass, stiffness, displacement, velocity) -> MechanicalEnergy	Evaluate 1/2 v^T M v and 1/2 u^T K u from visible operators.
class	LinearStaticEnergy	Energy closure for a proportional linear-static load path.
function	linear_static_energy(*, stiffness, force, displacement) -> LinearStaticEnergy	Evaluate energy for loads ramped proportionally from zero to force.
class	MechanicalEnergyMonitor	Cache visible M/K operators and sample mechanical energy in time.
class	ThermalBalanceMonitor	Sample discrete heat content, applied rate, outflow, and closure.
class	StateDependentThermalBalanceMonitor	Heat ledger for nonlinear conductivity and heat-capacity models.
class	ThermalContentMonitor	Backwards-compatible sensible-heat monitor without balance terms.
function	max_abs(function: fem.Function) -> float	Global max absolute value of a finite-element field.
function	max_magnitude(function) -> float	Global maximum magnitude of a scalar or vector finite-element field.
class	FieldStats	Distributed scalar statistics for a finite-element field.
class	ScalarDiagnostic	Named scalar diagnostic evaluated on demand.
class	DiagnosticSet	Ordered collection of scalar diagnostics.
function	magnitude_stats(function, *, on = None, name: str \| None = None) -> FieldStats	Return distributed magnitude statistics for a scalar or vector field.
function	field_stats(function, *, on = None, name: str \| None = None) -> FieldStats	Alias for magnitude_stats for application-level diagnostics.
class	ComputationalFailure(diagnostic, message)	Runtime failure with a stable machine-readable diagnosis and next checks.
function	linear_failure_diagnostic(reason, iterations, residual_norm)	Describe solver evidence without claiming an unobserved root cause.

agentfem.extensions

Kind	Public object	Purpose
class	ExtensionError	An installed extension could not be discovered or activated safely.
class	ExtensionSpec	Identity and compatibility contract published by one extension.
class	Extension	One loadable extension and its side-effect-free registration callback.
class	ExtensionDescriptor	Package metadata visible without importing extension code.
class	ExtensionContext	Staging area exposed to an extension during activation.
class	LoadedExtension	Activated identity and the capabilities registered into this process.
function	discover_extensions() -> tuple[ExtensionDescriptor, ...]	Return installed extension metadata without importing extension code.
function	extension_status() -> dict[str, object]	Return the machine-facing installed and activated extension inventory.
function	loaded_extensions() -> tuple[LoadedExtension, ...]	Return activated extensions in stable name order.
function	missing_extensions(names) -> tuple[str, ...]	Return required names that are not advertised by installed packages.
function	load_extension(name: str) -> LoadedExtension	Explicitly import, validate, and activate one installed extension.
function	load_extensions(names) -> tuple[LoadedExtension, ...]	Activate required extensions in declaration order.

agentfem.feedback

Kind	Public object	Purpose
class	FeedbackEndpoint	One reviewed collector route; never inferred from the user's address.
class	FeedbackPreferences	Persistent, user-controllable reliability-report preferences.
function	preferences() -> FeedbackPreferences	Return the effective preferences without creating local state.
function	configure(mode: str, *, route: str \| None = None, endpoint: str \| None = None, notice_shown: bool \| None = None) -> FeedbackPreferences	Persist basic or off and return the effective preferences.
function	notice_text() -> str	Public AgentFEM object.
function	show_notice_once(*, as_json: bool = False, stream = None) -> bool	Show the one-time reliability notice on an interactive human route.
function	failure_fingerprint(error: Mapping[str, object] \| None, *, command: str = 'run') -> str \| None	Return a message/path-free identity for one class of failure.
function	build_event(command: str, outcome: str, *, duration_seconds: float \| None = None, error: Mapping[str, object] \| None = None, now: datetime \| None = None, event_id: str \| None = None) -> dict[str, object]	Build the exact data allowed on the automatic reliability channel.
function	validate_event(record: Mapping[str, object]) -> None	Fail closed when an event contains an undeclared field.
function	queue_size() -> int	Public AgentFEM object.
function	clear_queue() -> int	Remove every unsent automatic event when reporting is disabled.
function	enqueue(record: Mapping[str, object]) -> Path \| None	Queue one event atomically; never write when reporting is disabled.
function	last_event() -> dict[str, object] \| None	Public AgentFEM object.
function	flush(*, timeout: float = DEFAULT_TIMEOUT_SECONDS) -> dict[str, object]	Send a bounded batch and return status without raising into a solve.
function	observe_cli(command: str \| None, exit_code: int, *, duration_seconds: float \| None = None, project: str \| Path \| None = None) -> dict[str, object] \| None	Record one CLI outcome; this function is deliberately fail-open.
function	record_failure(error: Mapping[str, object], *, command: str = 'run') -> dict[str, object]	Update a local, version-scoped repetition counter for one failure class.
function	diagnose(path: str \| Path \| None = None, *, project: str \| Path \| None = None) -> dict[str, object]	Explain one execution locally without uploading or modifying the case.
function	format_diagnosis(record: Mapping[str, object]) -> str	Public AgentFEM object.
function	create_support_directory(path: str \| Path \| None = None, *, project: str \| Path \| None = None, destination: str \| Path \| None = None, force: bool = False) -> dict[str, object]	Create a local, sanitized task that any AI agent can inspect.
function	create_feedback_archive(path: str \| Path \| None = None, *, project: str \| Path \| None = None, destination: str \| Path \| None = None) -> dict[str, object]	Create a portable local support archive without sending it.
function	submit_github_issue(path: str \| Path \| None = None, *, project: str \| Path \| None = None) -> dict[str, object]	Submit a sanitized issue after an explicit --github user action.

agentfem.forms

Kind	Public object	Purpose
function	stiffness_form(stress, strain_test, measure = ufl.dx)	Internal stiffness/virtual-work form, sigma : epsilon(test).
function	mass_form(density, trial_function, test_function, measure = ufl.dx)	Consistent mass form, rho * trial . test.
function	damping_form(coefficient, trial_function, test_function, measure = ufl.dx)	Viscous damping form, c * trial . test.
function	diffusion_form(conductivity, trial_function, test_function, measure = ufl.dx)	Diffusion/conduction form, k * grad(trial) . grad(test).
function	inertial_form(density, acceleration, test_function, measure = ufl.dx)	Inertial virtual-work form, rho * acceleration . test.
function	body_load_form(force, test_function, measure = ufl.dx)	Body-force/source virtual-work form, force . test.
function	boundary_load_form(load, test_function, measure)	Boundary flux/traction virtual-work form, load . test.
function	scalar_flux_form(flux, test_function, measure)	Scalar flux weak form, flux * test on a boundary or domain measure.
function	robin_form(coefficient, trial_function, test_function, measure)	Robin/impedance bilinear form, coefficient * trial * test.
function	internal_virtual_work(stress, strain_test)	Compatibility wrapper for stiffness_form.
function	inertial_virtual_work(density, acceleration, test_function)	Compatibility wrapper for inertial_form.
function	body_force_virtual_work(force, test_function, measure = ufl.dx)	Compatibility wrapper for body_load_form.
function	boundary_flux_virtual_work(flux, test_function, ds_measure)	Compatibility wrapper for boundary_load_form.

agentfem.io

Kind	Public object	Purpose
function	ensure_output_dir(path: Path, comm: MPI.Comm) -> None	Create an output directory once, then synchronize all ranks.
class	CSVLogger	Rank-zero CSV writer for time histories and scalar diagnostics.
class	XDMFTimeSeries(path: Path, domain, mode: str = 'w') -> None	Small context manager for writing a mesh and time-dependent fields.
class	ParaViewTimeSeries(path: Path, domain, mode: str = 'w') -> None	Collective VTK/PVD series with one geometry carrying all fields.
class	ResultWriter(path: Path, domain, fields = (), mode: str = 'w') -> None	Named result writer for one mesh and a stable field list.
function	interpolate_for_xdmf(field, *, degree: int = 1, name: str \| None = None)	Interpolate a field to an XDMF-friendly Lagrange output space.

agentfem.integrations

This package exposes its public objects through focused submodules.

agentfem.ir

Kind	Public object	Purpose
function	describe(item)	Prefer semantic records over display-only summaries.
function	describe_many(items: Iterable[object]) -> tuple[object, ...]	Describe a collection without retaining backend memory addresses.
function	model_document(model, *, agentfem_version: str, backend: Mapping[str, object] \| None = None, include_validation: bool = True, metadata: Mapping[str, object] \| None = None) -> IRDocument	Build an experimental AF-IR model document.
class	IRDocument	Canonical envelope for an AF-IR artifact.
class	IRSerializationError	Raised when a value cannot be represented without hiding its meaning.
function	to_json_safe(value, *, path: str = '$')	Convert scientific summaries to deterministic JSON-safe values.
function	write_document(document: IRDocument \| Mapping[str, object], path: str \| Path, *, indent: int = 2) -> Path	Write one deterministic AF-IR JSON document and return its path.
function	describe_value(value)	Return a JSON-safe coefficient value or an explicit opaque marker.

agentfem.platforms

Kind	Public object	Purpose
class	PlatformSupport	One operating-system support decision with explicit limitations.
class	RuntimeReport	Compact runtime inventory for bug reports and agent inspection.
function	support_for(system: str, *, wsl: bool = False, wsl_version: int \| None = None) -> PlatformSupport	Return the first-release support tier for an operating-system route.
function	current_support() -> PlatformSupport	Detect the current OS, including Windows Subsystem for Linux.
function	runtime_report() -> RuntimeReport	Return versions and optional integrations useful in issue reports.

agentfem.problems

Kind	Public object	Purpose
class	FEMProblem	Lightweight finite-element problem description.
class	LinearVariationalProblem	A standard linear variational problem, a(u, v) = L(v).
class	LinearSystemProblem	Engineering-level linear system problem, usually K x = F.
class	NonlinearVariationalProblem	Nonlinear residual problem R(u; v) = 0 solved by PETSc SNES.
class	AnalysisStep	Inspectable analysis step that owns one algebraic solve.
function	linear_system(K, F, *, unknown = None, solution = None, constraints = None, bcs = None, solver_options: LinearSolverOptions \| None = None, name: str = 'Kx_eq_F') -> LinearSystemProblem	Create a K x = F problem without exposing variational boilerplate.
function	linear_static(K, F, *, study = None, unknown = None, solution = None, constraints = None, bcs = None, solver_options: LinearSolverOptions \| None = None, result_field_factory = None, result_units = None, name: str = 'linear_static') -> AnalysisStep	Create a linear static analysis step in K x = F notation.
function	nonlinear(residual, solution, *, jacobian = None, constraints = None, bcs = None, solver_options: NonlinearSolverOptions \| NewtonSolverOptions \| None = None, name: str = 'nonlinear', petsc_options_prefix: str = 'agentfem_nonlinear_') -> NonlinearVariationalProblem	Create a general nonlinear residual problem.
function	incremental_nonlinear(residual, solution, *, factor, value_path, update_load = None, acceptance_check = None, jacobian = None, incrementation = None, constraints = None, constraint_assets = (), bcs = None, solver_options: NonlinearSolverOptions \| NewtonSolverOptions \| None = None, output_every: int \| None = 1, progress = True, status_file = None, name: str = 'incremental_nonlinear', petsc_options_prefix: str = 'agentfem_incremental_nonlinear_') -> IncrementalNonlinearVariationalProblem	Create standard-BC nonlinear equilibrium over a normalized load path.
function	affine_nonlinear(residual, solution, *, jacobian, constraint, load_factors = None, incrementation = None, solver_options: AffineNewtonOptions \| NewtonSolverOptions \| None = None, output_every: int \| None = 1, output_factors = (), state_transaction = None, checkpoint_policy = None, acceptance_check = None, progress = True, status_file = None, name: str = 'affine_nonlinear', procedure = None) -> AffineNonlinearVariationalProblem	Create a nonlinear problem reduced by an affine constraint map.
function	first_order_transient(*, capacity, stiffness, history, source = None, dt: float, study = None, unknown = None, solution = None, constraints = None, bcs = None, solver_options: LinearSolverOptions \| None = None, name: str = 'first_order_transient_step', method: str = 'implicit_euler') -> AnalysisStep	Create a first-order transient step.
function	first_order_transient_run(*, capacity, stiffness, history, current, previous, dt: float, steps: int, source = None, study = None, constraints = None, bcs = None, solver_options: LinearSolverOptions \| None = None, update_load = None, save_every: int \| None = None, print_every: int \| None = None, progress = True, status_file = None, checkpoint_policy = None, operator_policy: str = 'auto', name: str = 'first_order_transient') -> FirstOrderTransientStep	Create an executable implicit-Euler time step and loop.
function	nonlinear_first_order_transient_run(*, residual, jacobian, current, previous, dt: float, steps: int, study = None, constraints = None, bcs = None, solver_options: NonlinearSolverOptions \| NewtonSolverOptions \| None = None, update_load = None, save_every: int \| None = None, print_every: int \| None = None, progress = True, status_file = None, checkpoint_policy = None, operator_policy: str = 'auto', history_monitor = None, name: str = 'nonlinear_first_order_transient', petsc_options_prefix: str = 'agentfem_nonlinear_transient_') -> FirstOrderTransientStep	Create a nonlinear implicit-Euler step with the shared lifecycle.
function	explicit_dynamics(*, state, integrator, residual, stiffness = None, dt: float, steps: int, study = None, prescribed = (), constraints = (), update_load = None, save_every: int \| None = None, print_every: int \| None = None, history_every: int = 1, progress = True, status_file = None, checkpoint_policy = None, history_monitor = None, stability = None, name: str = 'explicit_dynamics') -> ExplicitDynamicsStep	Create a second-order explicit dynamics step.
function	modal_analysis(*, target, mass, stiffness, modes: int, study = None, constraints = (), bcs = None, target_frequency: float \| None = None, tolerance: float = 1e-09, maximum_iterations: int = 1000, rigid_mode_tolerance: float = 1e-10, name: str = 'modal_analysis') -> ModalAnalysisStep	Create an undamped linear structural modal analysis.
function	implicit_dynamics(*, state, mass, stiffness, force, damping = None, dt: float, steps: int, parameters = None, study = None, constraints = (), bcs = None, solver_options: LinearSolverOptions \| None = None, update_load = None, progress = True, status_file = None, checkpoint_policy = None, save_every: int \| None = None, print_every: int \| None = None, operator_policy: str = 'auto', name: str = 'implicit_dynamics') -> ImplicitDynamicsStep	Create a linear Newmark or generalized-alpha dynamics step.
class	PreparedSolve	One reusable numerical allocation with an explicit terminal lifetime.
class	AffineNonlinearVariationalProblem	Nonlinear equilibrium under an exact affine dof reduction.
class	IncrementalNonlinearVariationalProblem	Ordinary nonlinear equilibrium with automatic load incrementation.
class	LoadIncrementSnapshot	A copied solution state at one nonlinear load factor.
class	NonlinearLoadIncrementInfo	Convergence evidence for one ordinary nonlinear load increment.
class	NonlinearLoadPathInfo	Accepted and attempted increments for an ordinary nonlinear step.
class	ExplicitDynamicsStep	Inspectable second-order explicit dynamics step.
class	FirstOrderTransientStep	Reusable implicit-Euler step loop for heat/diffusion problems.
class	ImplicitDynamicsStep	Linear Newmark/generalized-alpha structural-dynamics step.

agentfem.provenance

Kind	Public object	Purpose
function	content_fingerprint(record: object) -> str	Return a canonical content identity for one JSON-safe scientific record.
function	collective_call(operation, *, comm, label: str)	Evaluate rank-local Python work and deliver any failure to all ranks.
function	collective_canonical_record(record: object, *, comm, label: str) -> object	Require one JSON-safe record on every rank and retain rank zero's copy.
function	scientific_input_manifest(value: object, *, label: str = 'scientific_inputs', require_nonempty: bool = False) -> dict[str, object]	Describe and fingerprint scientific inputs without hiding opaque parts.
function	collective_scientific_input_manifest(value: object, *, comm, label: str = 'scientific_inputs', require_nonempty: bool = False) -> dict[str, object]	Return one rank-consistent scientific-input manifest.
function	seal_manifest(manifest: Mapping[str, object], *, base: str \| Path, producer_version: str) -> dict[str, object]	Return a deterministic integrity seal for an unsealed manifest.
function	runtime_manifest() -> dict[str, object]	Capture runtime evidence and a stable compatibility identity.
function	freeze_runtime(path: str \| Path) -> Path	Atomically write the current runtime lock for a frozen campaign.
class	RuntimeComparison	Compatibility decision between a frozen and current runtime.
function	compare_runtime(expected: str \| Path \| Mapping[str, object], *, actual: Mapping[str, object] \| None = None) -> RuntimeComparison	Compare a stored runtime identity with the current or supplied one.
function	require_runtime(expected: str \| Path \| Mapping[str, object], *, policy: str = 'error') -> RuntimeComparison	Enforce or warn about a frozen runtime before a scientific campaign.
class	SealVerification	Outcome of checking one stored provenance seal.
function	verify_manifest(path: str \| Path) -> SealVerification	Verify a result manifest and every artifact recorded in its seal.

agentfem.spaces

Kind	Public object	Purpose
function	lagrange_space(domain, degree: int = 1)	Create a scalar Lagrange function space.
function	scalar_space(domain, degree: int = 1)	Create a scalar Lagrange function space.
function	vector_lagrange_space(domain, degree: int = 1, dim: int \| None = None)	Create a vector Lagrange function space.
function	vector_space(domain, degree: int = 1, dim: int \| None = None)	Create a vector Lagrange function space.
function	velocity_pressure_space(domain, *, velocity_degree: int = 2, pressure_degree: int = 1)	Create a Taylor--Hood velocity/pressure mixed space.
function	independent_subspace(space, component: int)	Build an independently numbered space for one mixed-field component.
function	displacement_pressure_space(domain, *, displacement_degree: int = 2, pressure_degree: int = 0, pressure_family: str = 'DG')	Create the mixed H1 displacement / discontinuous-pressure space.
function	test_function(V)	Create a UFL test function for a function space.
function	trial_function(V)	Create a UFL trial function for a function space.
function	named_function(V, name: str, value = 0.0)	Create a named finite-element function and optionally initialize it.

agentfem.time

Kind	Public object	Purpose
function	central_difference_predict_displacement(u_next, u, velocity, acceleration, dt: float) -> None	Predict displacement with the explicit central-difference/Newmark formula.
function	acceleration_from_residual(acceleration, residual, inv_mass: np.ndarray) -> None	Set acceleration from residual and inverse lumped mass.
function	central_difference_update_midstep_velocity(velocity_mid, velocity, acceleration, dt: float) -> None	Update the central-difference mid-step velocity.
function	central_difference_correct_velocity(velocity_next, velocity, acceleration, acceleration_next, dt: float) -> None	Correct velocity with the explicit central-difference/Newmark formula.
function	central_difference_update_velocity(velocity_next, velocity_mid, acceleration_next, dt: float) -> None	Update whole-step velocity from mid-step velocity and new acceleration.
function	error_step_factor(error, tolerance, *, order = 1, safety = 0.9, minimum = 0.5, maximum = 2.0)	Bounded proportional step-size factor for a local error estimate.
class	ProgressPrinter	Rank-zero progress printer controlled by a fixed step interval.
class	TimeStep	Metadata for one transient-solve step.
class	TimeStepper	Iterate over transient-solve step metadata.
function	format_duration(seconds: float) -> str	Format elapsed seconds as HH:MM:SS.
class	GeneralizedAlphaParameters	Parameters for Newmark/generalized-alpha time integration.
function	generalized_alpha(*, spectral_radius: float = 0.8)	Second-order generalized-alpha parameters from rho_infinity.
function	newmark(*, beta: float = 0.25, gamma: float = 0.5)	Average-acceleration Newmark by default.

agentfem.upgrades

Kind	Public object	Purpose
class	UpgradeFinding	One stable, addressable compatibility or migration finding.
class	UpgradeReport	Dry-run migration plan for one installed-use project.
function	inspect_project(project: ProjectConfig) -> UpgradeReport	Return a dry-run upgrade report without executing or changing the case.
function	apply_safe_metadata(project: ProjectConfig) -> tuple[Path, ...]	Apply only deterministic project-metadata migrations, atomically.
function	migrate_cohesive_checkpoint(snapshot: dict[str, object], *, tangential: str, tangential_stiffness: float \| None = None, acknowledge_physics_change: bool = False) -> dict[str, object]	Explicitly promote a physical-keyed scalar checkpoint to schema v5.

agentfem.validation

Kind	Public object	Purpose
class	ValidationIssue	One addressable model, numerical, or execution issue.
class	ValidationReport	Immutable collection of structured validation issues.
class	ModelValidationError(report: ValidationReport)	Raised when a structured model validation report contains errors.
function	issue(code: str, path: str, message: str, *, severity: Severity = 'error', hint: str \| None = None, **context) -> ValidationIssue	Concise constructor used by model validators and backend adapters.