Solution Procedures, Thermal Stress, and the Creep Route¶

Problem type is not a solver algorithm¶

Study answers what is being modeled: solid mechanics or heat transfer, static or transient, dimension, and kinematic assumptions. SolutionProcedure answers how it is solved:

Physical equation	Standard route	Explicit route
\(K u=F\)	linear solve	not applicable
\(R(u)=0\)	incremental Newton	not yet available
\(C\dot T+KT=Q\)	implicit Euler	not yet available
\(R(u,CE,t)=0\)	backward-Euler creep + Newton	not applicable
\(M\ddot u+C\dot u+Ku=F\)	Newmark or generalized-\(\alpha\)	central difference

This keeps second_order_dynamics from meaning “central difference” merely because that was the first implemented algorithm. It also keeps incrementation, Newton settings, time integration, and output cadence as separate decisions.

The implicit structural route currently assumes linear operators and time-invariant prescribed displacement supports. Newmark uses average acceleration by default. Generalized-\(\alpha\) derives \(\alpha_m,\alpha_f,\beta,\gamma\) from the spectral radius at infinite frequency and provides controllable high-frequency damping. Nonlinear implicit dynamics and moving supports require additional residual, linearization, and prescribed-kinematics work.

For linear implicit dynamics, the effective operator is fixed when the mesh, spaces, mass, damping, stiffness, time step, integration parameters, and constrained dof set remain unchanged. AgentFEM therefore uses operator_policy="auto" by default: it prepares the matrix and PETSc solver once, then assembles only the evolving right-hand side. "reuse" makes that contract explicit, while "refresh_each_step" retains conservative repeated assembly for externally mutated operators. A change to a guarded runtime invariant fails closed rather than continuing with a stale matrix. Step and result summaries record the selected policy, matrix and right-hand-side assembly counts, solve counts, KSP iterations, and the reason for the selection. Partial run(until_step=...) calls retain the prepared allocation; terminal completion or failure closes it deterministically. Checkpoints store scientific state rather than backend handles, so the receiving Step prepares one new operator safely under its declared policy.

Time-dependent inputs carry an explicit invalidation contract. Built-in load amplitudes and supported ambient-temperature histories declare that they change only the right-hand side. A custom callback is conservative by default, so operator_policy="auto" refreshes the effective matrix rather than risking a stale solve. When the callback is known to update forcing only, declare it:

from agentfem import time

update_force = time.input_update(
    update_my_constant,
    effects="right_hand_side",  # `"rhs"` is accepted as a short alias
    name="pulse_force",
    identity={"kind": "pulse_force", "revision": 1},
)

step = model.step(
    target=u,
    dt=dt,
    steps=steps,
    update_load=update_force,
)

Use effects="operator" when stiffness, mass, damping, or another bilinear coefficient changes; use "state" for accepted history that can alter a residual or tangent, and "output" for observation-only changes. Forcing operator_policy="reuse" against an operator/state declaration is rejected before the first solve. Step and result evidence record every declaration and whether the plan has a restart identity. Transient checkpoint schema v5 binds the complete plan and rejects a changed or anonymous callback before restoring any field. A v4 archive remains readable by the AgentFEM version that created it, but current AgentFEM does not guess whether its omitted load history is compatible.

The same policy now governs linear implicit-Euler heat transfer. A fixed capacity/conduction operator is prepared once while the history and source vectors are assembled at every accepted physical time. Operator- or state-changing inputs select per-step matrix refresh, and a bare callback takes that conservative path. Temperature-dependent conductivity or heat capacity uses a nonlinear residual and therefore remains per-step assembled; requesting operator_policy="reuse" for that route is rejected rather than interpreted as nonlinear Jacobian reuse.

The useful first thermal-mechanical route¶

Many component analyses do not need a monolithic temperature-displacement solve. If temperature affects stress but deformation and dissipation do not meaningfully affect heat transfer, the transparent route is:

solve \(\rho c_p \dot T-\nabla\cdot(k\nabla T)=Q\);
retain the temperature history;
evaluate \(\epsilon_{\mathrm{th}}=\alpha(T-T_{\mathrm{ref}})I\);
solve mechanical equilibrium with the named equivalent operator \(F_{\mathrm{thermal}}\).

AgentFEM stores \(E,\nu,\rho,\alpha,k,c_p,T_{\mathrm{ref}}\) in one thermoelastic property object. Constants may be replaced by inspectable temperature tables. Tabulated conductivity or specific heat automatically selects a nonlinear implicit-Euler residual using the conservative enthalpy difference \([h(T_{n+1})-h(T_n)]/\Delta t\), with \(dh/dT=\rho c_p(T)\). The thermal step can capture its accepted fields in a FieldHistory; the receiving creep step samples that history at its own physical increment endpoints. Interpolation, range policy, units, time coordinates, content hash, source Study, source procedure, and accepted-time transfer role remain part of the transfer contract. Saved nodal histories are keyed by physical DOF coordinates and can be restored across changed MPI partitions and rank counts. Plane strain keeps the constrained out-of-plane thermal strain; plane stress uses the reduced constitutive relation.

This follows the same modeling distinction documented by Abaqus: fully coupled analysis is needed when stress and temperature mutually influence each other; sequential analysis is appropriate when the coupling is effectively one way. The current route does not claim monolithic coupling.

The first global creep state consumer¶

The local ArrheniusPowerLawCreep relation is normalized at a declared reference temperature:

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

The implementation uses the equivalent exponent form in code; all temperatures are absolute. The global three-dimensional and axisymmetric Mises power-law route now accepts either an isothermal material or the same thermoelastic property asset used by heat transfer. A scalar, finite-element field, or accepted FieldHistory supplies \(T\) at every creep quadrature point. The local update consumes the normalized Arrhenius rate, \(E(T)\), \(\nu(T)\), and the endpoint secant thermal strain \(\alpha(T)[T-T_{\mathrm{ref}}]I\) through one consistent material contract. It provides:

committed/trial CE and CEEQ at every quadrature point;
a safeguarded backward-Euler local scalar solve over \(\Delta t\);
an analytical algorithmic consistent tangent consumed by global Newton;
atomic commit after acceptance and rollback after Newton, local, or maximum-creep-increment failure;
complete regional material assignment, fixed or automatic physical-time increments, natural-load work, prescribed-motion work, elastic energy, creep dissipation, total internal energy, a mechanical energy residual, and portable full-Step checkpoint/restart;
MPI-safe regional constitutive dispatch and a portable quadrature-state archive keyed by original physical cell, quadrature point, rule, material contract, and mesh fingerprint;
integration-point temperature consumption, TEMP output, increment-wise temperature evidence, and temperature identity in checkpoints;
scalar, finite-element, or physical-time FieldHistory temperature input; attempted increments move the live temperature to their endpoint, while rollback and restart restore it to the accepted physical time;
a three-dimensional homogeneous stress-relaxation Golden contract.

The mechanical residual compares external mechanical work with stored elastic energy plus creep dissipation. Under a changing prescribed temperature it also contains the unreported thermal/material energy transfer, so it is evidence for auditing the mechanical ledger rather than a full thermo-mechanical conservation error.

assessments.sequential_energy_ledger(thermal_result, mechanical_result, field_history=temperature_history) records this boundary explicitly. It keeps the thermal heat-balance residual and the receiving mechanical work/energy residual in separate channels. It deliberately does not add them or claim a monolithic thermo-mechanical conservation equation.

This is implemented by reusing QuadratureTransaction; creep does not own a second private state store. Checkpoint recovery reconstructs accepted stress from displacement and committed CE without advancing a fictitious time increment. The route follows the same consistent-linearization principle that underpins robust Newton convergence in inelastic finite elements.

Arrhenius power-law creep is therefore a global consumer, while Sinh and Kachanov--Rabotnov remain material-point capabilities. The accepted transient temperature history is now an explicit transfer object; it does not silently promote damage, mesh regularization, or structural rupture prediction.

Engineering creep--fatigue assessment¶

agentfem.assessments is a postprocessing layer, not a new constitutive law. It combines three independently reviewable assets:

source-identified dwell blocks evaluated by the time-fraction rule \(D_c=\sum_i n_i t_i/t_{r,i}\);
an existing FatigueAssessment produced from a declared stress history, cycle-counting policy, mean-stress policy and S--N curve;
an explicit interaction diagram whose points and source are supplied by the project.

AgentFEM includes only the transparent reference \(D_c+D_f=1\). It does not embed ASME, R5, company, or material-specific allowable curves. Licensed and current normative data therefore stays at the reviewed project boundary, while the software provides one stable decision margin and structured result record.

For a result-driven assessment, DwellInterval declares each physical hold and creep_fatigue_from_result(...) extracts governing stress and temperature from named scalar histories. The supplied rupture-time callable and its source remain project assets. Out-of-range dwells, missing histories, non-scalar histories, and nonphysical rupture times fail explicitly.

Current boundary and next gates¶

Implemented now:

explicit central difference and implicit Newmark/generalized-\(\alpha\);
implicit-Euler heat transfer as a model-owned Step;
conservative state-dependent conductivity/capacity using the same Step, Result, progress, heat-ledger, rollback, checkpoint, and MPI contracts;
accepted-time field capture and temperature-history transfer to creep;
coordinate-keyed field-history persistence verified in both two-rank-to-one and one-rank-to-two-rank directions;
bounded temperature-property tables for sequential thermoelastic stiffness and thermal expansion;
sequential isotropic thermal expansion as a visible vector operator;
normalized Arrhenius temperature dependence at material-point and global integration-point level;
global 3D and axisymmetric J2 quadrature state with regional materials, analytical tangent, and portable full-Step restart;
cumulative J2 restart history, analytical uniaxial Golden verification, quadrature S/PE/PEEQ/MISES and nodal RF result fields, cyclic amplitude, physical-increment cutback, prescribed work, and internal-energy decomposition;
exact material-point Kachanov-Rabotnov creep-damage updates, Sinh creep, and modified-theta curve projection;
a sequential hot-wall FEM-to-creep assessment example with explicit calibration and maturity boundaries.
global 3D and axisymmetric power-law creep with backward Euler, analytical tangent, shared transaction, automatic cutback, CE/CEEQ/S/MISES/RF/TEMP, prescribed Arrhenius temperature fields, dissipation history, regional materials, portable full-Step restart, MPI-portable quadrature state, and a relaxation Golden contract;
a 3D component contract in which accepted transient heat states drive the global Arrhenius creep step on the same physical clock and through the same temperature-dependent thermoelastic material asset;
a source-preserving engineering creep--fatigue assessment contract with named-history dwell extraction, explicit interaction data, and no hidden design-code constants;
an experimental three-dimensional Chaboche combined-hardening route with multiple Armstrong--Frederick backstresses, global cyclic equilibrium, quadrature rollback and restart, and standard ALPHA output;
the published NAFEMS R0027 Test 7 thick-cylinder stress oracle and a native Q2 axisymmetric elastic-preload-to-creep route. One-, two-, and four-cell radial meridians reduce the maximum radial/hoop/axial stress error from 1.40% to 0.203% to 0.0268%. On the four-cell mesh the individual errors are 0.0141%, 0.0145%, and 0.0268%, measured directly from integration-point stress with the full-revolution volume weight. The 0.5% automated acceptance criterion is AgentFEM's verification contract, not an official NAFEMS tolerance. The public Abaqus reproduction reports differences from the reference solution rather than a pass/fail threshold: its largest tabulated radial-stress difference is 1.84% for CAX8R (1.85% for CCL24R), and its largest hoop-stress difference is 1.00%. The former 3D quarter-sector formulation remains available as an explicit comparison route.

For creep, nonlinear equilibrium convergence and time-integration accuracy are separate decisions. creep_strain_error_tolerance limits

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

at owned integration points. An otherwise converged increment that exceeds the tolerance is rolled back and cut back atomically. This follows the public NAFEMS/Abaqus CETOL meaning; maximum_inelastic_increment remains the separate bound on the magnitude of the accepted CEEQ increment.

The J2 and creep Steps compile their live displacement-to-quadrature strain expression once. Newton iterations, line-search trials, rollback recovery and result reconstruction reevaluate its coefficients without repeatedly asking FFCx to rediscover the same compiled expression. This is an implementation detail below the public workflow, but it is important for long adaptive paths.

Homogeneous isothermal creep regions also use a vectorized quadrature update. This is an execution optimization, not a second constitutive model: the batch follows the same safeguarded backward-Euler equation and returns the same algorithmic tangent as the scalar material-point update. Temperature-dependent and multi-material regions retain pointwise material dispatch so scientific semantics take precedence over batching.

Next gates:

improve the global Newton/increment controller toward the public deck's 40-increment execution efficiency without weakening the scientific gates, and add intermediate-time observables when a transient rather than terminal benchmark contract is available;
exercise tabulated heat properties and accepted history transfer on an external 3D power-component benchmark with time-step convergence;
finish field/energy/checkpoint products on top of the common complete execution-event trace, accepted-increment histories, status files, and result manifest across heat, implicit dynamics, and explicit dynamics;
exercise the portable full-Step archive on larger partition changes and scheduled HPC restart campaigns;
add multi-element and external power-component benchmarks, then promote the experimental global Newton MPI path;
introduce K-R/Liu--Murakami damage only with near-failure time control and a declared mesh-regularization policy;
add a distributed archive backend only when field histories outgrow the current compact root-gathered format;
monolithic coupling only after a real case demonstrates two-way feedback.

References: