Claude Skill

agentfem

Build, review, run, validate, migrate, or extend AgentFEM finite-element projects. Use for AgentFEM studies, meshes, materials, constraints, loads, solution steps, results, campaigns, scientific datasets, surrogate/PINN/neural-operator integration, verification, public API extens

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download haoming-luo-agentfem-skills_agentfem-ce72d0e.zip · 24 KB
haoming-luo/agentfem 16 3 forks Apache-2.0 Updated 1d ago
Part of haoming-luo/agentfem — 2 skills

Install

skills CLI npx skills add https://github.com/haoming-luo/agentfem/tree/main/skills/agentfem
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install haoming-luo-agentfem@llmmart
Git git clone https://github.com/haoming-luo/agentfem.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole haoming-luo/agentfem collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

AgentFEM

Use this skill when building, reviewing, or extending finite-element simulations with AgentFEM.

Reference Routing

When this file is installed as a Codex skill, the reference paths below are relative to the skill directory skills/agentfem/. In the generated documentation site, use the left navigation pages Workflow, Concepts, and Module Map instead.

  1. Read references/workflow.md for every model construction, execution, or review task.
  2. Read references/concepts.md when choosing or explaining scientific objects and maturity levels.
  3. Read references/module_map.md when locating implementation code or deciding ownership.
  4. Read references/validation.md before changing executable scientific code or promoting a verification claim.
  5. Read references/extension_rules.md before adding a public helper, provider, constitutive family, or extension boundary.

Rules

  • If the numerical environment does not exist, create the release-tested Python 3.11/DOLFINx 0.11 conda-forge environment before modeling. In mainland China, use one conda-forge mirror for the whole PETSc/MPI/DOLFINx stack; do not assemble the runtime with a bare pip install or mixed channels.
  • Keep the finite-element workflow visible.
  • After a successful first-install or important-upgrade agentfem doctor, read its community_support record. If invitation_due is true, offer the repository Star once and briefly. Never inspect an account or act on it without explicit user consent. With consent, use agentfem support --check-github --json; never request or retain a token. Record a completed voluntary action with agentfem support --acknowledge github_star so later upgrades stay quiet.
  • On WSL, run agentfem workspace --json before creating, upgrading, or removing an installed-use project environment. Require protected_from_distribution_removal: true; otherwise run agentfem workspace --protect. Never issue raw wsl --unregister for an AgentFEM runtime. Project and result custody are scientific provenance, not disposable environment setup.
  • Identify the study context before selecting constitutive laws or operators.
  • Inspect mesh summaries and required tags before building weak forms.
  • Use lightweight models for registry, checks, summaries, and model-owned analysis steps; do not hide K/F systems or finite-element meaning.
  • Prefer model registration helpers such as model.field(...), model.material(...), model.fix(...), model.symmetry(...), model.traction(...), model.surface_force(...), and model.pressure(...) for application examples. Use surface_force when a continuum-solid end resultant should be distributed over a named reference boundary.
  • Use FEMProblem.summary() or equivalent structured summaries when auditing a workflow.
  • Use model.validate() for addressable issue reports, model.check() before execution, and model.write_ir(...) when a persistent AF-IR record is part of the task.
  • Treat model.check() and models.step_capability(model) as the executable Study/provider preflight. Do not advertise or lower a combination that no registered provider accepts. Read both supported and ready: the first reports that an installed provider owns the requested analysis, while the second confirms that required scientific inputs have been supplied.
  • Use AgentFEM modules before writing ad hoc DOLFINx/PETSc boilerplate.
  • Discover modules with agentfem.public_api("core") first. Disclose "advanced" and "expert" only when the requested workflow needs them. Within the model facade, generate methods from models.model_api("core"); do not choose names reported under models.model_api("compatibility") for new cases.
  • Treat agentfem capabilities --json and /agentfem.json as generated views of one product contract. Do not reconstruct a competing API vocabulary from a single example or an old compatibility method.
  • Use the capability record's ownership_contract before adding a public object. Model owns engineering registration, not discrete problem construction; state owns accepted/trial history; operators owns mass, residual and tangent contributions; Procedure, Backend, and Result/Verification retain their declared responsibilities.
  • Treat ir and validation as public inspection/record interfaces. Treat backends as an advanced numerical boundary and extensions as the explicit installed-package boundary. FEniCSx is the only production backend in the current release.
  • Prefer step = model.step(target=u) when a model has a Study and registered materials, constraints, and loads. New analysis/material families belong in a registered step provider; do not add one public model method per material. Every built-in provider must declare a StepOptionContract, and agents should read provider option summaries from agentfem capabilities --json rather than guessing keywords from one example. Respect required and exactly_one_of relationships instead of choosing aliases simultaneously. Solver, output, transient-history, progress, and checkpoint declarations are retained as one inspectable execution-policy summary. Prefer model.step(history=...) when the common result lifecycle should own the history request. Use model.stiffness(...), model.external_force(...), and operators.combine(...) when an example must expose individual contributions.
  • For nonlinear paths, use steps.automatic(...) as the normal step control. Treat max_increments as an accepted-increment ceiling and solver maximum_iterations as the Newton-iteration ceiling for one attempt. Prefer solvers.newton(...) over backend-specific solver classes. Use results.output_plan(...) to combine field, history, diagnostic, and presentation requests; do not use result frames as solve controls.
  • Keep Study and SolutionProcedure distinct. A dynamics Study may lower to Newmark, generalized-alpha, or central difference; do not encode the algorithm by changing the physical problem name.
  • Prefer studies.static_solid, studies.steady_heat_transfer, studies.transient_heat_transfer, and studies.dynamic_solid for common cases. Attach amplitudes to loads, prescribed values, and supported boundary models so procedures update them automatically.
  • For a revolved small-strain solid, declare studies.static_solid(dimension=2, assumption="axisymmetric"); never emulate it with plane strain plus ad hoc r factors. Meridian fields are (r,z), tensors are (r,theta,z), and the model-first workflow applies 2*pi*r to operators and loads. Pass the same Study to direct result-integral helpers. Use constraints.axisymmetric_plane_strain(...) only for the long-cylinder specialization that requires zero axial strain everywhere. If the meridian reaches r=0, register constraints.axisymmetric_axis(u, on=axis) and retain its validation evidence.
  • Use amplitudes.basis(...) for multiple named loading modes. Preserve coefficient order, value/velocity/acceleration behavior, endpoint audit, and the content fingerprint. Anonymous callables remain valid but are not a frozen scientific input record.
  • Keep operator notation such as K = operators.stiffness(...), F = operators.load_vector(...), and step = problems.linear_static(K, F, study=..., ...) available for transparent research/debugging examples.
  • Prefer step = problems.first_order_transient(...) for first-order transient workflows instead of hand-combining effective matrices in tutorial code.
  • Put local response relations under constitutive/.
  • Query constitutive.capabilities() before using nonlinear materials. State whether a law is FEM-integrated, material-point verified, or a postprocessor; never infer a global solver from a material-point update.
  • Stateful materials must use quadrature-owned committed/trial state and prove rollback plus restart equivalence. The current global J2 route has declared serial/MPI structural evidence; global Arrhenius power-law creep remains a 3D/axisymmetric small-strain foundation with a stricter MPI maturity boundary. Other creep laws remain material-point or assessment consumers.
  • Treat constitutive.finite_strain_j2_logarithmic(...) as an experimental public model.step capability with one constraint-neutral FP/PEEQ and dP/dF transaction but two separate equilibrium providers. Use the ordinary provider only with strong Dirichlet/remote-displacement kinematics, proportional amplitudes, and reference dead loads; use the affine/MPC provider only with exactly one reviewed AbaqusPeriodicConstraint and no natural-load power. Both have cutback, two-rank MPI, accepted-state output, and cross-partition restart evidence. Reject unsupported follower loads, weak boundary physics, contact, or MPC rather than silently discarding them. Do not present either route as externally validated finite-strain plasticity until an independent structural benchmark passes.
  • Use constitutive.chaboche(...) for the experimental three-dimensional combined-hardening route. Supply every (C_i, gamma_i) pair from reviewed cyclic calibration data. It shares the ordinary model.step(...), quadrature transaction, cutback and restart lifecycle and reports total backstress as ALPHA; do not present its current external-definition tests as a structure-level stabilized-hysteresis validation or a complete cyclic energy closure.
  • For global implicit creep, keep Newton equilibrium, maximum accepted CEEQ increment, and endpoint creep-rate time-integration accuracy as three separate controls. Use creep_strain_error_tolerance when a physical-time accuracy gate is required; a rejected increment must restore displacement, quadrature state, stress, tangent, loading, and temperature atomically. Declare a model UnitSystem when result histories need a physical time-unit label; never infer seconds from an undeclared consistent-unit system.
  • Prefer sequential heat-transfer then thermal-stress analysis when coupling is one way. Do not claim fully coupled thermo-mechanics unless temperature and mechanics are solved in one consistent nonlinear system.
  • For an evolving one-way thermal input, call temperature_history = heat_step.capture_history(name="temperature", unit="K") before solving and pass that object to the receiving Arrhenius creep Step. Treat its coordinate as physical time, not an output frame or increment number. Keep interpolation and out-of-range behavior explicit; cutback must restore the temperature to the accepted start time. Use save(...) and FieldHistory.load(...) when the handoff crosses runs: nodal archives use a physical-DOF identity and are portable across MPI partition counts. The compact archive is root-gathered, so do not present it as an extreme-scale parallel field database.
  • Use materials.temperature_property(...) and constitutive.temperature_dependent_thermoelastic(...) for tabulated sequential properties. Do not hide interpolation in an anonymous callback or silently extrapolate outside laboratory data. A field-valued UFL coefficient requires an explicit bounded extrapolation policy.
  • Pass the same thermoelastic property asset as elastic=... to a global power-law creep material when E(T), nu(T), alpha(T), heat properties, and Arrhenius flow must share one reviewed record. Temperature is evaluated at the creep quadrature identity; thermal-expansion tables are endpoint secant coefficients relative to the declared reference temperature.
  • Use assessments.creep_time_fraction(...) and assessments.creep_fatigue(...) only as engineering postprocessors. Every rupture-time block and nontrivial interaction diagram needs an explicit source. Do not bake ASME, R5, company, or material-specific curves into the open core or present an assessment as coupled constitutive damage.
  • When the evidence already lives in SimulationResult, declare physical holds with assessments.DwellInterval(...) and use assessments.creep_fatigue_from_result(...). Name the stress and temperature histories, provide a callable rupture relation and its source, and let out-of-range intervals fail instead of silently clamping them.
  • For one-way heat-to-mechanics workflows, use assessments.sequential_energy_ledger(...) to preserve the thermal and mechanical residuals as separate layers. Never add them into a monolithic conservation claim. capture_history(...) already records the source Study, procedure, accepted-time role and portable content identity.
  • If conductivity or specific heat is tabulated, keep the ordinary model.step(target=temperature, dt=..., steps=...) call. AgentFEM lowers it to a conservative enthalpy-based nonlinear heat step. Do not also pass user-defined C= or K= operators, and retain its convergence, heat-ledger, rollback, and checkpoint evidence.
  • Put weak boundary physics under boundary_models/.
  • Put Dirichlet, periodic, and MPC relations under constraints.
  • Put Neumann, traction, flux, and body sources under loads.
  • Treat positive loads.pressure(...) as inward. State whether it is a reference dead load or current follower load.
  • For imported physical surfaces, create mesh.tagged_boundary_region(domain, facet_tags, tag=...). Use that same region for strong constraints and weak loads; do not reconstruct a physical group with a broad coordinate marker. If an independent marker is supplied, run model.audit_boundaries(strict=True) before solving.
  • Validate small cases before reporting success.
  • Use solve_result() and solve_result(output="results.xdmf") for static or transient outputs that feed visualization, reporting, campaigns, or datasets. Do not treat XDMF/CSV as the scientific result itself.
  • After publishing, run agentfem verify <result.json> --json when results are copied, reused, or admitted to a campaign. This checks manifest/artifact integrity, not convergence or scientific validation.
  • Before a frozen or blind campaign, use provenance.freeze_runtime(...); require it on continuation with provenance.require_runtime(...). Review an intentional mismatch rather than editing the stored lock.
  • Declare source meshes as Path values and reusable materials, loading, procedures, and observers through Campaign(scientific_inputs=...). Reject claims of reproducibility when fingerprint coverage is incomplete unless the opaque input has been reviewed and recorded.
  • For an individual result, call result.add_scientific_inputs(...) before write_manifest(...); pass file assets as Path so their bytes are hashed.
  • Use events.first_passage(...) for threshold timing and retain its bracket, localization, and censoring. Refine discontinuous damage/contact events instead of presenting interpolation as exact.
  • For heat, Standard dynamics, and Explicit dynamics, pause with run(until_step=...), save with save_checkpoint(...), rebuild the same step, then load_checkpoint(...). Resume through solve_result(output=...); inspect metadata["transient"]["output_scope"] before presenting the XDMF/HDF5 series as complete. Current transient checkpoints require the same MPI size and mesh partition.
  • Use results.region_integral, results.region_average, results.region_measure, results.boundary_resultant, and results.field_extrema for common MPI-safe quantities instead of case-owned UFL for standard measures or rank-local array reductions. Use field_extrema(..., location=True) when a reported peak needs coordinates and DG0 cell identity.
  • Use results.probe, results.sample_points, and results.sample_path for physical-coordinate field sampling. Every MPI rank must request identical coordinates. Put discontinuous-field probes inside the intended cell rather than relying on an interface-side convention.
  • Use expressions.expression, expressions.as_ufl, and expressions.interpolate for formulas supplied through JSON, benchmark specifications, or agent-authored configuration. Never execute those formulas with Python eval; reject syntax outside the reviewed mathematical language. Lower symbolic physics with as_ufl; use interpolate for known loads, coefficients, initial values, and boundary data so cases reuse stable finite-element forms instead of recompiling each formula.
  • Use results.sample_rectilinear_grid when an external protocol requires a direct mesh-independent array. Preserve its inside mask and declared axis order; do not infer a transpose from array dimensions.
  • For PDEAgent-Bench, use the commit-pinned integrations.pdeagent_bench contract and fixed solver entry point. Consume only the public agent-view case, never case identifiers, oracle numerics, or manufactured solutions. Read SUPPORTED_FAMILIES before selecting a case. Preserve mixed-field, pressure-reference, periodic-MPC, and fourth-order closure evidence reported in solver_info; these are scientific decisions, not disposable backend details. Report fixed-adapter capability separately from an AI-agent A/B experiment and from any official library-track submission.
  • Model-generated static elasticity returns projected S/E/MISES fields automatically; request SENER explicitly when needed. Use results.small_strain_partition_fields for an explicit regional material projection. Use results.reaction_resultant(..., on=..., component=...) only for named strong Dirichlet reactions; do not reuse that definition for affine MPC, weak, or contact constraints.
  • For FNO-style data, use one reviewed surrogates.ObservationGrid across the campaign and datasets.fem_observation_sample(..., outside="mask"). Keep the exported axes, order, components, units, and mask with every sample.
  • Use checkpointing.every(...) through the public Step for automatic transient checkpoints. Cadence follows accepted increments, not output or progress frames.
  • In an installed project, run agentfem doctor --json, agentfem check --json, and agentfem upgrade --json before execution. If [extensions].required is declared, inspect it with agentfem extensions --json; do not install or activate an untrusted package merely to make a project check pass. Required extensions are executable code. Never apply a semantic_review=true migration without inspecting regions, loads, constraints, materials, forms, output meaning, and verification. Use project.current_run() and publish the result so terminal, GUI, and agent consumers receive the same run identity, artifacts, and manifest.
  • Treat agentfem run --json as the machine boundary. Read the versioned execution and result records; do not infer success by matching console text.
  • When an installed run fails, inspect it first with agentfem diagnose --json. After a repeated unresolved failure, create a local private task with agentfem assist --force; read its sanitized evidence without assuming it contains the scientific model. Never run agentfem feedback --github or transmit a support archive without explicit user authorization. agentfem telemetry status --json describes the exact automatic reliability boundary: a minimal anonymous signal used to improve the free, open-source software, with no model, mesh, parameter, source, path, or result data. agentfem telemetry off remains a permanent user control.
  • Use learning as the public umbrella but preserve exact roles. A surrogate, neural operator, neural-field solver, and learned constitutive model are not interchangeable. PINN/DEM/XDEM providers must consume explicit objectives, conditions, sampling, and evidence contracts; do not hide them behind a generic AI model label.
  • For a user-owned PINN, DEM, XDEM, or other neural-field implementation, use model.step(target=spec, executor=...). The executor receives one immutable learning.NeuralFieldExecutionRequest and must return SimulationResult. Do not require an official companion package, inherit an AgentFEM neural model base class, or put live executable objects in result provenance.
  • Inspect external meshes before conversion, retain the conversion manifest, and do not call mesh conversion a full Abaqus/ANSYS model import.
  • For legacy Abaqus projects, run agentfem inspect-abaqus ... --json before agentfem migrate-abaqus .... Preserve the recursive source graph and review migration.json; do not collapse Part/Instance scopes, discard element suffixes, or execute a generated native material candidate without selecting and verifying the complete AgentFEM formulation. The generated case.py is intentionally fail closed. Never invent missing material properties, and review every Step, load, boundary, interaction, and output retained under pending_assets.
  • If migration.json reports native_lowering.status=eligible, create an inactive reviewed draft with agentfem lower-abaqus PROJECT --reviewed-by NAME --unit-system SYSTEM. Inspect case.native.py and lowering.json before adding --activate --force. A native analogue is not Abaqus solver equivalence, and a blocking finding must never be bypassed. Do not collapse temperature-dependent tables, partial or overlapping Section assignments, non-unit 2D thickness, or Step/BC inheritance into the narrow static route. Multiple constant isotropic materials are eligible only when preserved ELSET/SOLID SECTION declarations exactly and unambiguously partition the selected solver domain. A single linear-static Step may lower a named relative tabular amplitude to its final equilibrium multiplier only when lowering.json retains the full table, Step duration, reference value, and final value. Do not describe this as an intermediate-increment replay.
  • Before adapting an Abaqus UMAT or UHYPER, run agentfem inspect-user-material SOURCE --json. Preserve the source hash and findings. adapter_candidate is a development route, not an executable material; an Abaqus utility call requires explicit replacement and verification. Native and adapted material providers must declare one MaterialStateSchema and MaterialTangentConvention and enter through validated_material_update(...). A tensor state must retain its physical initial value (for example, identity rather than zero for a plastic deformation gradient). Never infer global-Newton compatibility from a 6-by-6 array or relabel Abaqus DDSDDE as a first-Piola/deformation-gradient tangent. Lower native/adapted internal variables through MaterialQuadratureState.create(domain, material.state_schema, ...); do not create a second adapter-specific STATEV store. Preserve the schema in checkpoint identity and require a distributed-write/changed-partition-read test before claiming portable restart. Before a total-Lagrangian provider enters global Newton, run check_material_tangent(material, point) across elastic and plastic path locations and retain the evidence. Do not use that direct dP/dF check for a spatial UMAT tangent without a separately verified transformation.
  • Read an Abaqus C3D10H source directly with mesh.read_abaqus_mesh(...), inspect cell.element_definitions, and consume it only through the verified P2-displacement/DG0-pressure mixed route. Do not derive another mesh when the source already declares C3D10H, and do not treat neutral tetra10 geometry as sufficient formulation evidence.
  • When Abaqus constraints use node labels, preserve labels separately from backend dof ordering. Treat *EQUATION as an auditable constraint graph; reject duplicate slaves, cycles, missing node matches, and unsupported parallel ownership rather than silently weakening periodicity.
  • For finite-deformation periodic cells, report the macro deformation gradient, every load increment's convergence, equation mismatch, sampled det(F) bounds, complete accepted-increment homogenized tensor histories, stress-state validity, and deformed geometry at scale one. Spatial field cadence may be sparse; do not infer that the macro CSV has the same cadence. Read the actual macro gradient from solved reference-point motion when any macro component is free; do not replace it with the nominal loading predictor. Read triaxiality and normalized Lode values only where homogenized_stress_state_defined is one. Treat Hill--Mandel evidence as a quasistatic affine/periodic contract without body-force or inertia power. A macro history row must keep its accepted increment size, Newton iterations, residual, periodic mismatch, and accepted attempt beside the physical state. See docs/reference/rve_homogenization_and_statistics.md for formulas and validity conventions. A three-dimensional uniaxial-stress periodic cell leaves both transverse normal macro components free and suppresses macro shear; do not fix one transverse stretch to unity.
  • Prefer solve_result(output=...) for serial multi-field static output and the unified XDMF/HDF5 backend for finite-strain time series. Verify shared topology, retained reference coordinates, deformed geometry, time values, and all point/cell attributes. The low-level io.XDMFTimeSeries follows DOLFINx and can expose one Grid per Function. Use PVD only for a consumer that specifically requires it. Treat completed_with_output_errors as a completed solve with failed optional output, not as a lost numerical result.
  • Do not claim that experimental AF-IR records make arbitrary UFL workflows backend neutral.
  • For parameter collections, build a fresh case per sample, retain case/run evidence, split validation data independently, and guard learned-model applicability. Do not silently extrapolate or imply that neural-operator and PINN contract records are executable trainers.
  • Use responses.finite_difference(...) for campaign-backed baseline and perturbation cases. Declare absolute or relative steps and output Quantity contracts. A failed perturbation makes the response incomplete; do not fill a missing Jacobian column with zeros.
  • A campaign evaluator may return a declared mapping, CaseOutcome, or SimulationResult. Prefer a safe JSON campaign specification for parameter and sampling policy when non-programmers or agents need to edit a sweep; keep trusted model construction in Python.
  • Use campaigns.local_processes(workers=...) for independent local cases. It uses spawned processes; do not nest it inside within-case MPI or replace it with threads. Use plan shards for separate MPI jobs and schedulers.
  • Use convergence.audit(...) only with explicit refinement axes, fixed coordinates for every other varying parameter, and declared relative, absolute, or exact observable policies. Preserve failed, missing, and ambiguous sequences as inconclusive evidence.

When Extending AgentFEM

Before adding a public helper, read references/extension_rules.md. If the new helper is application-specific, keep it in the application package. Private material libraries and domain products belong in separate packages using the versioned agentfem.extensions entry point, not in a long-lived private branch of the open core.

Files (agentfem)
  • agents
    • openai.yaml 296 B 
      interface:
  display_name: "AgentFEM"
  short_description: "Build and verify AI-native finite-element workflows"
  default_prompt: "Use $agentfem to build or review this finite-element workflow through AgentFEM's public API and verification contracts."

policy:
  allow_implicit_invocation: true
  • references
    • concepts.md 7.9 KB 
      # Concepts Reference

- Study: early analysis context containing analysis type, physics, dimension,
  and modeling assumptions.
- Axisymmetric solid: a two-dimensional `(r,z)` meridian whose displacement is
  `(u_r,u_z)`, whose stress/strain tensors retain `(r,theta,z)`, and whose
  physical integrals use the full-revolution `2*pi*r` measure.
- Solution procedure: Standard/Explicit family, equation order, integration
  algorithm, statefulness, and global-solve requirements. It describes how a
  Study is solved without redefining the physical problem.
- Model: lightweight registry for mesh, regions, fields, amplitudes, materials,
  constraints, loads, and checks. It is not a solver.
- Model helpers: `model.field`, `model.material`, `model.fix`, and
  `model.traction` register assets without hiding operator construction.
- Mesh summary: dimension, local/global entity counts, and cell/facet tag
  availability.
- Mesh region: named geometric location where constraints, loads, or material
  data are applied. Boundary regions provide `ds(tag)`; cell/material regions
  provide `dx(tag)`.
- Unknown field: application-level bundle containing space, solution, trial, and
  test objects.
- Field algebra: same-space AgentFEM fields support eager arithmetic such as
  `u + dt * v`, returning a numerical field rather than a symbolic weak form.
- Amplitude: named time history or scale factor used to drive prescribed data;
  it is not a spatial finite-element field.
- Amplitude basis: ordered serializable histories plus named coefficients,
  derivatives, endpoint audit, and content identity.
- Constraint: essential or algebraic dof restriction.
- Fixed constraint: application-level fixed-value Dirichlet condition on a
  target unknown and geometric region. Vector unknowns default to all
  components; selected components are explicit.
- Load: weak right-hand-side source term.
- Boundary model: weak boundary physics such as Robin, impedance, or absorbing
  behavior.
- Constitutive law: local response relation mapping state to stress, flux, or
  tangent quantities.
- Constitutive maturity: `fem_integrated`, `material_point_verified`, or
  `postprocessor`. Query it; do not infer it from the law name.
- Engineering assessment: a postprocessor that consumes result histories and
  reviewed project data without advancing constitutive state. Creep rupture
  relations and nontrivial creep--fatigue interaction curves retain explicit
  sources rather than becoming hidden core constants.
- Material definition: physical identity, source, and one active executable
  behavior per physics role. It remains independent of the Study until
  `model.material(...)` resolves the required role.
- Material record: SI-unit reference constants plus model name and source note.
  It is data, not the equation itself, and packaged generic cards are not
  industrial design allowables.
- Material properties: typed parameter object used by constitutive relations.
- Modal result: frequencies plus relative eigenpair, mass-orthogonality, and
  stiffness-diagonalization evidence. Mode signs follow a deterministic
  largest-global-component-positive convention; normalized shape amplitude is
  not a physical displacement.
- State snapshot: finite accepted/trial values only. Non-finite fields are
  rejected before checkpointing and during restore.
- Analysis step: solve stage under a study, such as linear static or implicit
  Euler, built from visible operators.
- Problem: discrete algebraic or transient system, such as `K x = F`,
  `C xdot + K x = F`, or `M a + C v + K u = F`.
- Operator algebra: use `model.stiffness(...)` for registered material regions
  and `operators.combine(...)` when individual contributions must be explicit.
- State: fields grouped for a solver or time integrator.
- Quadrature state: committed and trial history owned at integration points;
  rejected Newton iterates and cutbacks never mutate committed history.
- Implicit dynamics integrator: Newmark or generalized-alpha solution of a
  second-order system through an assembled effective operator.
- Explicit dynamics integrator: time integrator such as
  `time.explicit.central_difference(...)`; central difference is Newmark with
  beta=0 and gamma=1/2.
- Modal analysis: constrained generalized Hermitian eigensolve
  \(K\phi=\omega^2M\phi\); strong prescribed degrees of freedom are removed
  before solving and each accepted mode retains a relative residual.
- Generalized Maxwell spectrum: small-strain material-point relaxation model
  with an equilibrium modulus and positive relaxing branches. It supplies
  relaxation/storage/loss response and transactional state, but does not by
  itself imply global finite-element viscoelastic assembly.
- Diagnostic: quantity used to inspect correctness, stability, or physics.
- Simulation result: named QoIs, fields, histories, metadata, scientific-input
  identity, and artifact links from one analysis; it bridges solves,
  campaigns, and datasets.
- Runtime lock: compatibility-relevant package, scalar, MPI, and
  source/distribution identity; paths remain evidence but not equality gates.
- Event observation: threshold crossing with bracket, localization rule, and
  observed/left-censored/right-censored status.
- Benchmark: verification case with expected quantities and tolerances.
- AF-IR document: experimental versioned scientific record; it is not yet a
  complete backend-neutral executable serialization.
- Validation issue: stable code, object path, severity, message, and repair
  hint for an addressable model finding.
- Backend adapter: explicit compilation boundary. FEniCSx is currently the only
  production backend.
- Parameter space: ordered typed simulation inputs with admissible values,
  bounds, units, and scale.
- Campaign: deterministic related cases with fresh construction, case IDs,
  output contracts, scientific-input fingerprints, serial/spawned/sharded
  execution evidence, failure records, and resume behavior.
- Scientific-input manifest: content identity for declared files, arrays,
  public scientific objects, and callable code/state; opaque coverage remains
  explicitly incomplete.
- Convergence certificate: explicit refinement-axis slices with fixed
  coordinates and relative, absolute, or exact observable policies.
- Response experiment: named output derivatives with respect to named
  parameters, first implemented as Campaign-backed finite differences.
- External mesh conversion: a topology/set conversion with a manifest, not a
  full commercial solver-deck import. For Abaqus, run
  `agentfem inspect-abaqus ...` first and preserve the distinction among source
  declaration, topology import, native formulation, and verification evidence.
- Migration plan: source-preserving, scope-aware engineering relationships and
  unresolved decisions between a legacy model and AgentFEM. A generated
  project is fail closed; recognizing an Abaqus material or section does not
  authorize numerical lowering or prove equivalence.
- Reviewed native lowering: an explicit source-fingerprint, reviewer, unit,
  asset-decision, and generated-case record. Drafting does not activate it.
- Scientific dataset: numeric inputs/outputs plus units, shapes, field
  encodings, case identities, provenance, and artifacts.
- Surrogate: learned or reduced-order mapping whose scientific asset includes
  independent validation, applicability, and out-of-domain behavior.
- Neural operator: function-to-function model requiring explicit field,
  geometry, boundary, mesh, and projection encodings.
- Neural-field solver: per-problem field optimization through residual,
  variational/energy, data, and constraint objectives. PINN, DEM, and XDEM are
  methods in this family, not surrogate aliases. User-owned implementations
  can consume `NeuralFieldExecutionRequest` directly and return
  `SimulationResult`; an installed provider is optional.
- Physics-informed model: learning contract with explicit strong, weak, or
  discrete residuals and conditions; arbitrary UFL is not automatically a PINN
  residual.

Never treat Neumann data as a Dirichlet constraint.
    • extension_rules.md 1.5 KB 
      # Extension Rules Reference

Add a helper to AgentFEM only when it is a reusable FEM concept or workflow
operation.

Keep problem-specific geometry, source histories, benchmark constants, and paper
parameters in application packages or examples.

Use `materials/` for reusable SI-unit material-property records. Use
`constitutive/` for equations that map state to stress, flux, tangents, or other
responses.

Use `elements/`, `operators/`, and `benchmarks/` only for reusable asset
families. Keep first-level modules focused on the standard FEM workflow.

Use operator-level language for beginner application tutorials. Use weak-form
language only when the tutorial is teaching formulation details.

When a new concept is added, update:

- `CONCEPTS.md`
- `WORKFLOW.md` if the workflow changes
- `docs/module_map.md`
- The relevant skill reference

For a new constitutive capability, also add:

- an entry in `constitutive/catalog.py`;
- a benchmark obligation in `benchmarks/registry.py`;
- material-point evidence before any global FEM convenience step;
- explicit state/tangent/increment-control evidence before marking it
  `fem_integrated`.

For a stateful material, reuse `constitutive.quadrature` and prove
trial/commit/rollback plus restart equivalence. Do not create a case-local
history array or mutate committed state during Newton.

For a new transient route, add or reuse a `SolutionProcedure`; do not encode
the algorithm by renaming the physical Study. Standard/Explicit, time
integration, nonlinear solver, incrementation, and output cadence are
different decisions.
    • module_map.md 5.5 KB 
      # Module Map Reference

Repository package paths below are relative to `src/agentfem/`.

- `_api_contract.py`: dependency-free public module tiers, Model verbs, CLI
  commands, and machine workflow stages
- `_architecture_contract.py`: dependency-free Model/Constitutive/State/
  Operator/Procedure/Backend/Result ownership inventory
- `mesh/`: mesh import/read/write, boundary/cell regions, summaries, tag
  checks, tags, and measures
- `mesh/formats.py`: external CAE inventory, cell/facet conversion, set tags,
  and conversion manifests
- `mesh/abaqus.py`: Abaqus node labels, `*EQUATION` parsing, periodic-cell
  geometry, and source-order VTU output
- `mesh/abaqus_migration.py`: scope-aware Abaqus engineering plans and
  fail-closed installed-project scaffolds
- `mesh/abaqus_lowering.py`: reviewed narrow native lowering and fingerprinted
  one-instance orphan-mesh derivation
- `studies.py`: analysis context, physics, dimensions, and modeling assumptions
- `procedures.py`: Standard/Explicit family, equation order, integration
  algorithm, state policy, and solve requirements
- `models.py`: lightweight model registry/facade, amplitudes, material
  assignments, checks, summaries, and model-first operators
- `_step_builders.py`: internal built-in scientific Step construction; new
  user cases should not call it directly
- `step_providers.py`: extensible analysis/material lowering and normalized
  execution-policy inspection behind `model.step(...)`
- `spaces.py`: function spaces and named functions
- `fields.py`: application-level unknown bundles
- `amplitudes.py`: time histories, derivatives, and serializable loading bases
- `kernel/dofs.py`: low-level dof lookup and field copying
- `constraints/`: constraint containers and semantic Dirichlet constructors
- `loads.py`: loads, natural boundary data, and semantic constructors
- `constitutive/`: local response relations and queryable maturity catalog
- `constitutive/viscoelasticity.py`: generalized-Maxwell/Prony spectra,
  temperature shifts, exact material-point updates, and fixed-spectrum fitting
- `assessments.py`: standard-neutral engineering damage consumers, explicit
  interaction diagrams, and structured result attachment
- `constitutive/quadrature.py`: committed/trial integration-point state,
  schema-driven material state lowering, and partition-portable checkpoint
  identity
- `mechanics/`: global stateful solid-mechanics procedures
- `constitutive/user_material.py`: solver-neutral material-point input/output,
  versioned scalar/tensor state schemas, explicit tangent conventions,
  fail-closed validated updates, and non-executable UMAT/UHYPER bridge
  specifications
- `materials/`: material-property records and loaders
- `boundary_models/`: weak boundary models
- `forms.py`: UFL weak-form blocks
- `assembly.py`: matrix/vector/lumped assembly
- `operators/`: engineering-level K/M/C/F, transport, SUPG, reaction operators,
  and system containers
- `time/`: central difference, Newmark, generalized-alpha, progress, and cadence
- `dynamics.py`: modal reductions, FFT/FRF, and free-decay signal processing
- `state.py`: restart/replace protocols and generic first-/second-order state
- `problems.py`: analysis steps and discrete system problems; historical state
  imports are compatibility aliases
- `solvers.py`: PETSc solver wrappers and convergence evidence
- `steps.py`: automatic/fixed analysis-step incrementation and cutback policy
- `results/`: simulation results, assembled QoIs, histories, artifacts, and
  campaign/dataset bridge
- `events.py`: first-passage localization and censoring records
- `results/finite_strain.py`: named finite-strain visualization fields,
  stress-state invariants, accepted-increment RVE histories, and Hill--Mandel
  work and convergence evidence
- `results/statistics.py`: physical-measure scalar statistics and exact
  weighted quantiles for owned integration-point values
- `results/field_catalog.py`: standard field keys, aliases, and context rules
- `results/output.py`: declarative field requests plus compact unified
  XDMF/HDF5 and optional PVD/VTU writers
- `results/plan.py`: reusable field, history, diagnostic, presentation, and
  manifest orchestration
- `diagnostics.py`: norms and scalar diagnostics
- `io.py`: output writers and scalar logs
- `elements/`: element and integration-policy namespace
- `benchmarks/`: test-linked verification registry
- `integrations/`: versioned external scientific contracts and adapters
- `ir/`: experimental versioned AF-IR scientific records
- `validation.py`: structured issue codes, paths, hints, and reports
- `verification.py`: scientific claims, trust levels, and convergence evidence
- `backends/`: backend descriptors and advanced lowering adapters
- `extensions.py`: explicit installed/private package discovery and staged
  provider, backend, and material registration
- `campaigns/`: typed parameters, deterministic sampling, case plans,
  serial/spawned local execution, deterministic shards, resume, and MPI-aware
  persistence
- `convergence.py`: multi-axis observable-aware convergence certificates
- `responses.py`: Campaign-backed finite-difference response experiments
- `provenance.py`: runtime locks, scientific-input fingerprints, result seals,
  and integrity verification
- `datasets/`: unit/shape-aware learning data and case provenance
- `learning/`: public scientific-learning umbrella and provider-neutral
  neural-field objectives, conditions, sampling, and inferred parameters
- `surrogates/`: baseline learned/ROM models, validation, applicability guards,
  and neural-operator/PINN contracts
    • validation.md 5.8 KB 
      # Validation Reference

Minimum validation after code changes:

1. Compile/import touched modules.
2. Check mesh summaries and required tags when a workflow depends on labels.
3. Run `model.validate()` and report issue codes and paths when public modeling
   assets changed.
4. Check AF-IR JSON safety and determinism when serialization changed.
5. Run a small serial case when the change affects execution.
6. Run a small MPI case when the change affects parallel behavior.
   Use `agentfem mpi-run -n 2 -- ...` (or `agentfem run --mpi 2` for a
   project) so the launcher family is verified against the active `mpi4py`;
   do not assume the first bare `mpiexec` on `PATH` is compatible.
7. Report untested assumptions and unsupported backend capabilities.
8. Keep computed/converged/verified/validated claims distinct. Use named
   quality presets for routine checks; use `verification.VerificationClaim`
   and record the reference validity domain for scientific promotion.
9. For mesh/time accuracy, require an ordered coarse-to-fine
   `verification.ConvergenceStudy`; one converged solve is not convergence.

For modeling changes, also check units, boundary-condition type, and output
availability.
For axisymmetric changes, verify radial regularity when the mesh reaches the
axis, full `(r,theta,z)` tensor output, the `2*pi*r` measure in stiffness,
loads, energy and results, analytical Lamé response, and at least one stateful
thick-cylinder path. Do not interpret an integrated radial meridian component
as a Cartesian vector resultant around the complete circumference.

For constitutive changes, record one of these maturity levels:

- `material_point_verified`: formula, state, and local load-path evidence;
- `fem_integrated`: quadrature/global state and nonlinear/time solve evidence;
- `postprocessor`: consumes results but does not alter the FEM equilibrium.

Every advancement requires a benchmark-registry entry and automated test.
Run `benchmarks.audit_capability_evidence()` before changing a catalog
maturity label. The audit must satisfy the evidence required by the declared
maturity; a passing audit does not promote an experimental capability or erase
its stated limitations.
For external meshes, verify both volume and boundary named-set preservation.
For external scientific benchmarks, pin the upstream commit, retain the exact
public input view, classify execution/accuracy/time failures separately, and
stratify incompatible or inconsistent dataset subsets rather than adding
case-specific exceptions. Never use withheld reference fields to select a
mesh, formulation, or answer.
For Abaqus equation-driven workflows, additionally verify source node-label
mapping, unique/cycle-free slave equations, exact post-solve equation
mismatch, positive sampled `det(F)`, and scale-one deformed output. A serial
equation backend must reject MPI execution explicitly.
For periodic-cell output, distinguish one analysis step from its load
increments, verify every requested XDMF field at every saved factor, normalize
effective stresses by the complete cell volume, and compare direct
first-Piola integration with the transformed Cauchy-stress integral. Verify
that the homogenized history contains every accepted increment even when XDMF
is sparse. Check the stress-state validity channel before consuming
triaxiality or normalized Lode values, and audit microscopic versus
macroscopic first-Piola work through the Hill--Mandel residual.
Keep accepted increment size, Newton iterations, final residual, periodic
equation mismatch and accepted attempt aligned with the same macro frame; do
not reconstruct this evidence from output-frame indices.
For finite-strain output, resolve the conventional `E` request to `LE` and
require `GREEN` explicitly. Verify the unified XDMF/HDF5 series: frame count,
time values, shared topology, retained reference coordinates,
`x + scale*u`, point/cell field presence, and physical scale metadata.
Treat UMAT/UHYPER support as an interface specification until quadrature state,
trial/commit/rollback, tensor conventions, compiler ABI, and consistent-tangent
comparisons are executable. Require a stable `MaterialStateSchema`, including
the correct scalar or tensor initial values, and an explicit
`MaterialTangentConvention`; reject schema/convention drift through
`validated_material_update(...)`. A callable shared library or an undeclared
6-by-6 array alone is not FEM compatibility.
When a material schema is lowered to `MaterialQuadratureState`, verify scalar
and tensor initial values, public output aliases, atomic commit/rollback,
schema-drift rejection, and two-rank-write/changed-partition-read equivalence.
For a declared first-Piola/deformation-gradient tangent, compare the discrete
update against fixed-old-state numerical differentiation over all nine
deformation-gradient components. Include elastic, plastic and near-yield path
locations; a single check at the identity is insufficient.
For campaigns, verify `SimulationResult -> declared QoIs -> ScientificDataset`
without serializing live fields. Use `quality="engineering"` for ordinary
simulation-to-learning admission and `quality="release"` only when every
sample carries release-grade scientific evidence.
Review the campaign scientific-input manifest: files must be content-hashed,
public objects must expose an IR/summary contract, and opaque paths must remain
an explicit coverage gap. For convergence, require explicit fixed coordinates
for all non-refined parameters and retain failed or missing cases as
inconclusive evidence.
For response experiments, verify every baseline/perturbation case, parameter
bound, output shape, step convention, and missing-case decision. Check
finite-difference step sensitivity before interpreting a derivative. Preserve
event brackets and censoring; interpolation does not replace local time-step
refinement for discontinuous events.
    • workflow.md 6.2 KB 
      # Workflow Reference

For an existing installed project, start with `agentfem doctor --json`. On
WSL, also run `agentfem workspace --json` and protect the workspace before any
runtime lifecycle operation. Then run `agentfem check --json` and
`agentfem upgrade --json`. Automatic migration is
limited to deterministic metadata. A finding with `semantic_review=true`
requires inspection and re-verification of the finite-element meaning.

AgentFEM workflow:

Public discovery is progressive. Begin with `agentfem.public_api("core")` and
`models.model_api("core")`. Methods reported by
`models.model_api("compatibility")` remain executable during 0.2.x but are not
the language for new cases. Built-in Step providers publish accepted and
required keyword names and mutually exclusive scientific-coordinate aliases
through `StepOptionContract`; inspect the same contracts with
`agentfem capabilities --json` before generating a Step call. Treat
`supported=true` as provider availability and `ready=true` as confirmation
that the concrete request has all required inputs.
The CLI capability record and `/agentfem.json` documentation manifest are
generated views of the same dependency-free product contract; do not infer a
parallel workflow language from one example.
Read `ownership_contract` from `agentfem capabilities --json` when deciding
where an extension belongs. Model describes the engineering problem; State
owns accepted/trial history; Operator owns mathematical contributions;
Procedure owns evolution; Backend owns execution; Result/Verification owns
evidence.

1. Study context: analysis type, physics, dimension, and assumptions
2. Solution procedure preference when more than one algorithm can solve the
   same physical equation
3. Mesh
4. Model registry when auditability is useful
5. Mesh summary and required tag checks
6. Function spaces
7. Fields and states; use `agentfem.state` for generic transient state and
   inspect transaction capabilities instead of assuming every algorithm has
   the same trial signature
8. Constitutive laws; optionally retain identity/source through
   `materials.define(...)` and let `model.material(...)` resolve the Study's
   mechanical or thermal role. A reviewed project can switch a separate
   Python asset with `materials.load("materials/active.py")`; installed or
   private collections should use an AgentFEM extension package instead.
9. Amplitudes when prescribed data changes with time
10. Constraints
11. Loads
12. Boundary models
13. Operators or forms: model-first helpers for standard registered assets,
    operator-first constructors for explicit contributions
14. Analysis step through `model.step(...)` and an inspectable provider, or
    directly from visible operators for research/debugging
    - nonlinear subdivision belongs to `steps.automatic(...)` or the explicit
      compatibility mode `steps.fixed(...)`;
    - output intervals are a separate result request, not solver increments.
    - solver/output/history/progress/checkpoint inputs are retained as one
      inspectable execution-policy summary; declare transient histories on the
      Step when they should be consumed automatically by `solve_result()`.
15. Structured validation and optional AF-IR record
16. Assembly, solve, or time integration
    - shared transient procedures may pause through `run(until_step=...)` and
      resume from `save_checkpoint(...)` / `load_checkpoint(...)`;
    - a resumed `solve_result(output=...)` produces an explicitly identified
      continuation segment, not reconstructed earlier frames.
17. `SimulationResult`, physical QoIs, diagnostics, and histories
    - optional engineering assessments consume these histories and attach
      source-preserving decisions without changing the solved state;
18. `result.verify("exploratory" | "engineering" | "release")`, required
    outputs, and explicit scientific claims when the result is described as
    verified/validated
19. A declarative `results.output_plan(...)` for reusable field, history,
    diagnostic, and optional presentation requests
20. Compact unified XDMF/HDF5 artifacts attached to the result; use PVD/VTU
    only when specifically required
21. Optional runtime lock before a frozen or blind experiment

If execution fails, read the structured execution record with
`agentfem diagnose --json`. A repeated unresolved failure may be lowered to a
private, sanitized Agent task with `agentfem assist --force`. This does not
upload the model or result. Creating a public issue remains a separate
user-authorized action.

For related-case collections:

22. Typed parameter space and deterministic sampling plan, optionally from
    safe JSON
23. Fresh model construction per case
24. Scientific-input declaration and fingerprint-coverage review
25. Serial, spawned local-process, or externally sharded campaign execution
26. Optional multi-axis convergence certificate with explicit fixed coordinates
27. Optional response experiment lowered to baseline/perturbation Campaign cases
28. Named quality policy before dataset admission
29. Scientific dataset plus independent train/validation split
30. Surrogate/ROM validation, applicability guard, and explicit FEM fallback

Do not collapse these steps so aggressively that a reviewer cannot see the
finite-element model.

Use `examples/` as executable workflow references after identifying the target
problem type.

For an Abaqus input deck, run `agentfem inspect-abaqus model.inp --json`
before `agentfem migrate-abaqus model.inp ./project --json`. Review the copied
source graph, Part/Instance scopes, section/material assignments, and issue
codes before replacing the generated fail-closed guard with an ordinary
AgentFEM workflow. Treat `topology_only` as an explicit migration boundary;
never erase `R`, `H`, incompatible-mode, shell, or cohesive semantics merely
because the connectivity can be read. Missing material properties remain
unresolved, and each `pending_assets` entry needs a reviewed lowering decision.
If the plan reports an eligible native subset, run `agentfem lower-abaqus`
with explicit reviewer and unit system, inspect the inactive draft, then
activate separately. Multiple constant isotropic materials may be lowered
through exact ELSET/SOLID SECTION regions; partial or overlapping converted
tags remain blockers. Never modify the decision JSON to hide a blocker.
  • SKILL.md 27.3 KB 
    ---
name: agentfem
description: Build, review, run, validate, migrate, or extend AgentFEM finite-element projects. Use for AgentFEM studies, meshes, materials, constraints, loads, solution steps, results, campaigns, scientific datasets, surrogate/PINN/neural-operator integration, verification, public API extensions, and agent or GUI integration.
---

# AgentFEM

Use this skill when building, reviewing, or extending finite-element simulations
with AgentFEM.

## Reference Routing

When this file is installed as a Codex skill, the reference paths below are
relative to the skill directory `skills/agentfem/`. In the generated
documentation site, use the left navigation pages `Workflow`, `Concepts`, and
`Module Map` instead.

1. Read `references/workflow.md` for every model construction, execution, or
   review task.
2. Read `references/concepts.md` when choosing or explaining scientific
   objects and maturity levels.
3. Read `references/module_map.md` when locating implementation code or
   deciding ownership.
4. Read `references/validation.md` before changing executable scientific code
   or promoting a verification claim.
5. Read `references/extension_rules.md` before adding a public helper, provider,
   constitutive family, or extension boundary.

## Rules

- If the numerical environment does not exist, create the release-tested
  Python 3.11/DOLFINx 0.11 conda-forge environment before modeling. In
  mainland China, use one conda-forge mirror for the whole PETSc/MPI/DOLFINx
  stack; do not assemble the runtime with a bare pip install or mixed channels.
- Keep the finite-element workflow visible.
- After a successful first-install or important-upgrade `agentfem doctor`, read
  its `community_support` record. If `invitation_due` is true, offer the
  repository Star once and briefly. Never inspect an account or act on it
  without explicit user consent. With consent, use
  `agentfem support --check-github --json`; never request or retain a token.
  Record a completed voluntary action with
  `agentfem support --acknowledge github_star` so later upgrades stay quiet.
- On WSL, run `agentfem workspace --json` before creating, upgrading, or
  removing an installed-use project environment. Require
  `protected_from_distribution_removal: true`; otherwise run
  `agentfem workspace --protect`. Never issue raw `wsl --unregister` for an
  AgentFEM runtime. Project and result custody are scientific provenance, not
  disposable environment setup.
- Identify the study context before selecting constitutive laws or operators.
- Inspect mesh summaries and required tags before building weak forms.
- Use lightweight models for registry, checks, summaries, and model-owned
  analysis steps; do not hide K/F systems or finite-element meaning.
- Prefer model registration helpers such as `model.field(...)`,
  `model.material(...)`, `model.fix(...)`, `model.symmetry(...)`,
  `model.traction(...)`, `model.surface_force(...)`, and `model.pressure(...)`
  for application examples. Use `surface_force` when a continuum-solid end
  resultant should be distributed over a named reference boundary.
- Use `FEMProblem.summary()` or equivalent structured summaries when auditing a
  workflow.
- Use `model.validate()` for addressable issue reports, `model.check()` before
  execution, and `model.write_ir(...)` when a persistent AF-IR record is part
  of the task.
- Treat `model.check()` and `models.step_capability(model)` as the executable
  Study/provider preflight. Do not advertise or lower a combination that no
  registered provider accepts. Read both `supported` and `ready`: the first
  reports that an installed provider owns the requested analysis, while the
  second confirms that required scientific inputs have been supplied.
- Use AgentFEM modules before writing ad hoc DOLFINx/PETSc boilerplate.
- Discover modules with `agentfem.public_api("core")` first. Disclose
  `"advanced"` and `"expert"` only when the requested workflow needs them.
  Within the model facade, generate methods from `models.model_api("core")`;
  do not choose names reported under `models.model_api("compatibility")` for
  new cases.
- Treat `agentfem capabilities --json` and `/agentfem.json` as generated views
  of one product contract. Do not reconstruct a competing API vocabulary from
  a single example or an old compatibility method.
- Use the capability record's `ownership_contract` before adding a public
  object. `Model` owns engineering registration, not discrete problem
  construction; `state` owns accepted/trial history; `operators` owns mass,
  residual and tangent contributions; Procedure, Backend, and
  Result/Verification retain their declared responsibilities.
- Treat `ir` and `validation` as public inspection/record interfaces. Treat
  `backends` as an advanced numerical boundary and `extensions` as the explicit
  installed-package boundary. FEniCSx is the only production backend in the
  current release.
- Prefer `step = model.step(target=u)` when a model has a Study and registered
  materials, constraints, and loads. New analysis/material families belong in
  a registered step provider; do not add one public model method per material.
  Every built-in provider must declare a `StepOptionContract`, and agents
  should read provider option summaries from `agentfem capabilities --json`
  rather than guessing keywords from one example. Respect `required` and
  `exactly_one_of` relationships instead of choosing aliases simultaneously.
  Solver, output, transient-history, progress, and checkpoint declarations are
  retained as one inspectable execution-policy summary. Prefer
  `model.step(history=...)` when the common result lifecycle should own the
  history request.
  Use `model.stiffness(...)`,
  `model.external_force(...)`, and `operators.combine(...)` when an example
  must expose individual contributions.
- For nonlinear paths, use `steps.automatic(...)` as the normal step control.
  Treat `max_increments` as an accepted-increment ceiling and solver
  `maximum_iterations` as the Newton-iteration ceiling for one attempt. Prefer
  `solvers.newton(...)` over backend-specific solver classes. Use
  `results.output_plan(...)` to combine field, history, diagnostic, and
  presentation requests; do not use result frames as solve controls.
- Keep `Study` and `SolutionProcedure` distinct. A dynamics Study may lower to
  Newmark, generalized-alpha, or central difference; do not encode the
  algorithm by changing the physical problem name.
- Prefer `studies.static_solid`, `studies.steady_heat_transfer`,
  `studies.transient_heat_transfer`, and `studies.dynamic_solid` for common
  cases. Attach `amplitudes` to loads, prescribed values, and supported
  boundary models so procedures update them automatically.
- For a revolved small-strain solid, declare
  `studies.static_solid(dimension=2, assumption="axisymmetric")`; never emulate
  it with plane strain plus ad hoc `r` factors. Meridian fields are `(r,z)`,
  tensors are `(r,theta,z)`, and the model-first workflow applies `2*pi*r` to
  operators and loads. Pass the same Study to direct result-integral helpers.
  Use `constraints.axisymmetric_plane_strain(...)` only for the long-cylinder
  specialization that requires zero axial strain everywhere.
  If the meridian reaches `r=0`, register
  `constraints.axisymmetric_axis(u, on=axis)` and retain its validation evidence.
- Use `amplitudes.basis(...)` for multiple named loading modes. Preserve
  coefficient order, value/velocity/acceleration behavior, endpoint audit, and
  the content fingerprint. Anonymous callables remain valid but are not a
  frozen scientific input record.
- Keep operator notation such as `K = operators.stiffness(...)`,
  `F = operators.load_vector(...)`, and
  `step = problems.linear_static(K, F, study=..., ...)` available for
  transparent research/debugging examples.
- Prefer `step = problems.first_order_transient(...)` for first-order transient
  workflows instead of hand-combining effective matrices in tutorial code.
- Put local response relations under `constitutive/`.
- Query `constitutive.capabilities()` before using nonlinear materials. State
  whether a law is FEM-integrated, material-point verified, or a
  postprocessor; never infer a global solver from a material-point update.
- Stateful materials must use quadrature-owned committed/trial state and prove
  rollback plus restart equivalence. The current global J2 route has declared
  serial/MPI structural evidence; global Arrhenius power-law creep remains a
  3D/axisymmetric small-strain foundation with a stricter MPI maturity boundary. Other creep
  laws remain material-point or assessment consumers.
- Treat `constitutive.finite_strain_j2_logarithmic(...)` as an experimental
  public `model.step` capability with one constraint-neutral `FP/PEEQ` and
  `dP/dF` transaction but two separate equilibrium providers. Use the ordinary
  provider only with strong Dirichlet/remote-displacement kinematics,
  proportional amplitudes, and reference dead loads; use the affine/MPC
  provider only with exactly one reviewed `AbaqusPeriodicConstraint` and no
  natural-load power. Both have cutback, two-rank MPI, accepted-state output,
  and cross-partition restart evidence. Reject unsupported follower loads,
  weak boundary physics, contact, or MPC rather than silently discarding them.
  Do not present either route as externally validated finite-strain plasticity
  until an independent structural benchmark passes.
- Use `constitutive.chaboche(...)` for the experimental three-dimensional
  combined-hardening route. Supply every `(C_i, gamma_i)` pair from reviewed
  cyclic calibration data. It shares the ordinary `model.step(...)`,
  quadrature transaction, cutback and restart lifecycle and reports total
  backstress as `ALPHA`; do not present its current external-definition tests
  as a structure-level stabilized-hysteresis validation or a complete cyclic
  energy closure.
- For global implicit creep, keep Newton equilibrium, maximum accepted CEEQ
  increment, and endpoint creep-rate time-integration accuracy as three
  separate controls. Use `creep_strain_error_tolerance` when a physical-time
  accuracy gate is required; a rejected increment must restore displacement,
  quadrature state, stress, tangent, loading, and temperature atomically.
  Declare a model `UnitSystem` when result histories need a physical time-unit
  label; never infer seconds from an undeclared consistent-unit system.
- Prefer sequential heat-transfer then thermal-stress analysis when coupling
  is one way. Do not claim fully coupled thermo-mechanics unless temperature
  and mechanics are solved in one consistent nonlinear system.
- For an evolving one-way thermal input, call
  `temperature_history = heat_step.capture_history(name="temperature", unit="K")`
  before solving and pass that object to the receiving Arrhenius creep Step.
  Treat its coordinate as physical time, not an output frame or increment
  number. Keep interpolation and out-of-range behavior explicit; cutback must
  restore the temperature to the accepted start time. Use `save(...)` and
  `FieldHistory.load(...)` when the handoff crosses runs: nodal archives use a
  physical-DOF identity and are portable across MPI partition counts. The
  compact archive is root-gathered, so do not present it as an extreme-scale
  parallel field database.
- Use `materials.temperature_property(...)` and
  `constitutive.temperature_dependent_thermoelastic(...)` for tabulated
  sequential properties. Do not hide interpolation in an anonymous callback
  or silently extrapolate outside laboratory data. A field-valued UFL
  coefficient requires an explicit bounded extrapolation policy.
- Pass the same thermoelastic property asset as `elastic=...` to a global
  power-law creep material when E(T), nu(T), alpha(T), heat properties, and
  Arrhenius flow must share one reviewed record. Temperature is evaluated at
  the creep quadrature identity; thermal-expansion tables are endpoint secant
  coefficients relative to the declared reference temperature.
- Use `assessments.creep_time_fraction(...)` and
  `assessments.creep_fatigue(...)` only as engineering postprocessors. Every
  rupture-time block and nontrivial interaction diagram needs an explicit
  source. Do not bake ASME, R5, company, or material-specific curves into the
  open core or present an assessment as coupled constitutive damage.
- When the evidence already lives in `SimulationResult`, declare physical
  holds with `assessments.DwellInterval(...)` and use
  `assessments.creep_fatigue_from_result(...)`. Name the stress and temperature
  histories, provide a callable rupture relation and its source, and let
  out-of-range intervals fail instead of silently clamping them.
- For one-way heat-to-mechanics workflows, use
  `assessments.sequential_energy_ledger(...)` to preserve the thermal and
  mechanical residuals as separate layers. Never add them into a monolithic
  conservation claim. `capture_history(...)` already records the source Study,
  procedure, accepted-time role and portable content identity.
- If conductivity or specific heat is tabulated, keep the ordinary
  `model.step(target=temperature, dt=..., steps=...)` call. AgentFEM lowers it
  to a conservative enthalpy-based nonlinear heat step. Do not also pass
  user-defined `C=` or `K=` operators, and retain its convergence, heat-ledger,
  rollback, and checkpoint evidence.
- Put weak boundary physics under `boundary_models/`.
- Put Dirichlet, periodic, and MPC relations under `constraints`.
- Put Neumann, traction, flux, and body sources under `loads`.
- Treat positive `loads.pressure(...)` as inward. State whether it is a
  reference dead load or current follower load.
- For imported physical surfaces, create
  `mesh.tagged_boundary_region(domain, facet_tags, tag=...)`. Use that same
  region for strong constraints and weak loads; do not reconstruct a physical
  group with a broad coordinate marker. If an independent marker is supplied,
  run `model.audit_boundaries(strict=True)` before solving.
- Validate small cases before reporting success.
- Use `solve_result()` and `solve_result(output="results.xdmf")` for static or
  transient outputs that feed
  visualization, reporting, campaigns, or datasets. Do not treat XDMF/CSV as
  the scientific result itself.
- After publishing, run `agentfem verify <result.json> --json` when results are
  copied, reused, or admitted to a campaign. This checks manifest/artifact
  integrity, not convergence or scientific validation.
- Before a frozen or blind campaign, use
  `provenance.freeze_runtime(...)`; require it on continuation with
  `provenance.require_runtime(...)`. Review an intentional mismatch rather
  than editing the stored lock.
- Declare source meshes as `Path` values and reusable materials, loading,
  procedures, and observers through `Campaign(scientific_inputs=...)`. Reject
  claims of reproducibility when fingerprint coverage is incomplete unless the
  opaque input has been reviewed and recorded.
- For an individual result, call `result.add_scientific_inputs(...)` before
  `write_manifest(...)`; pass file assets as `Path` so their bytes are hashed.
- Use `events.first_passage(...)` for threshold timing and retain its bracket,
  localization, and censoring. Refine discontinuous damage/contact events
  instead of presenting interpolation as exact.
- For heat, Standard dynamics, and Explicit dynamics, pause with
  `run(until_step=...)`, save with `save_checkpoint(...)`, rebuild the same
  step, then `load_checkpoint(...)`. Resume through
  `solve_result(output=...)`; inspect `metadata["transient"]["output_scope"]`
  before presenting the XDMF/HDF5 series as complete. Current transient
  checkpoints require the same MPI size and mesh partition.
- Use `results.region_integral`, `results.region_average`,
  `results.region_measure`,
  `results.boundary_resultant`, and `results.field_extrema` for common
  MPI-safe quantities instead of case-owned UFL for standard measures or
  rank-local array reductions. Use `field_extrema(..., location=True)` when a
  reported peak needs coordinates and DG0 cell identity.
- Use `results.probe`, `results.sample_points`, and `results.sample_path` for
  physical-coordinate field sampling. Every MPI rank must request identical
  coordinates. Put discontinuous-field probes inside the intended cell rather
  than relying on an interface-side convention.
- Use `expressions.expression`, `expressions.as_ufl`, and
  `expressions.interpolate` for formulas supplied through JSON, benchmark
  specifications, or agent-authored configuration. Never execute those
  formulas with Python `eval`; reject syntax outside the reviewed mathematical
  language. Lower symbolic physics with `as_ufl`; use `interpolate` for known
  loads, coefficients, initial values, and boundary data so cases reuse stable
  finite-element forms instead of recompiling each formula.
- Use `results.sample_rectilinear_grid` when an external protocol requires a
  direct mesh-independent array. Preserve its `inside` mask and declared axis
  order; do not infer a transpose from array dimensions.
- For PDEAgent-Bench, use the commit-pinned
  `integrations.pdeagent_bench` contract and fixed solver entry point. Consume
  only the public agent-view case, never case identifiers, oracle numerics, or
  manufactured solutions. Read `SUPPORTED_FAMILIES` before selecting a case.
  Preserve mixed-field, pressure-reference, periodic-MPC, and fourth-order
  closure evidence reported in `solver_info`; these are scientific decisions,
  not disposable backend details.
  Report fixed-adapter capability separately from an AI-agent A/B experiment
  and from any official library-track submission.
- Model-generated static elasticity returns projected `S/E/MISES` fields
  automatically; request `SENER` explicitly when needed. Use
  `results.small_strain_partition_fields` for an
  explicit regional material projection. Use
  `results.reaction_resultant(..., on=..., component=...)` only for named
  strong Dirichlet reactions;
  do not reuse that definition for affine MPC, weak, or contact constraints.
- For FNO-style data, use one reviewed `surrogates.ObservationGrid` across the
  campaign and `datasets.fem_observation_sample(..., outside="mask")`. Keep the
  exported axes, order, components, units, and mask with every sample.
- Use `checkpointing.every(...)` through the public Step for automatic
  transient checkpoints. Cadence follows accepted increments, not output or
  progress frames.
- In an installed project, run `agentfem doctor --json`,
  `agentfem check --json`, and `agentfem upgrade --json` before execution.
  If `[extensions].required` is declared, inspect it with
  `agentfem extensions --json`; do not install or activate an untrusted package
  merely to make a project check pass. Required extensions are executable code.
  Never apply a `semantic_review=true` migration without inspecting regions,
  loads, constraints, materials, forms, output meaning, and verification. Use
  `project.current_run()` and
  publish the result so terminal, GUI, and agent consumers receive the same
  run identity, artifacts, and manifest.
- Treat `agentfem run --json` as the machine boundary. Read the versioned
  execution and result records; do not infer success by matching console text.
- When an installed run fails, inspect it first with
  `agentfem diagnose --json`. After a repeated unresolved failure, create a
  local private task with `agentfem assist --force`; read its sanitized
  evidence without assuming it contains the scientific model. Never run
  `agentfem feedback --github` or transmit a support archive without explicit
  user authorization. `agentfem telemetry status --json` describes the exact
  automatic reliability boundary: a minimal anonymous signal used to improve
  the free, open-source software, with no model, mesh, parameter, source, path,
  or result data. `agentfem telemetry off` remains a permanent user control.
- Use `learning` as the public umbrella but preserve exact roles. A surrogate,
  neural operator, neural-field solver, and learned constitutive model are not
  interchangeable. PINN/DEM/XDEM providers must consume explicit objectives,
  conditions, sampling, and evidence contracts; do not hide them behind a
  generic AI model label.
- For a user-owned PINN, DEM, XDEM, or other neural-field implementation, use
  `model.step(target=spec, executor=...)`. The executor receives one immutable
  `learning.NeuralFieldExecutionRequest` and must return `SimulationResult`.
  Do not require an official companion package, inherit an AgentFEM neural
  model base class, or put live executable objects in result provenance.
- Inspect external meshes before conversion, retain the conversion manifest,
  and do not call mesh conversion a full Abaqus/ANSYS model import.
- For legacy Abaqus projects, run `agentfem inspect-abaqus ... --json` before
  `agentfem migrate-abaqus ...`. Preserve the recursive source graph and review
  `migration.json`; do not collapse Part/Instance scopes, discard element
  suffixes, or execute a generated native material candidate without selecting
  and verifying the complete AgentFEM formulation. The generated `case.py` is
  intentionally fail closed. Never invent missing material properties, and
  review every Step, load, boundary, interaction, and output retained under
  `pending_assets`.
- If `migration.json` reports `native_lowering.status=eligible`, create an
  inactive reviewed draft with `agentfem lower-abaqus PROJECT --reviewed-by
  NAME --unit-system SYSTEM`. Inspect `case.native.py` and `lowering.json`
  before adding `--activate --force`. A native analogue is not Abaqus solver
  equivalence, and a blocking finding must never be bypassed. Do not collapse
  temperature-dependent tables, partial or overlapping Section assignments,
  non-unit 2D thickness, or Step/BC inheritance into the narrow static route.
  Multiple constant isotropic materials are eligible only when preserved
  ELSET/SOLID SECTION declarations exactly and unambiguously partition the
  selected solver domain.
  A single linear-static Step may lower a named relative tabular amplitude to
  its final equilibrium multiplier only when `lowering.json` retains the full
  table, Step duration, reference value, and final value. Do not describe this
  as an intermediate-increment replay.
- Before adapting an Abaqus UMAT or UHYPER, run `agentfem
  inspect-user-material SOURCE --json`. Preserve the source hash and findings.
  `adapter_candidate` is a development route, not an executable material; an
  Abaqus utility call requires explicit replacement and verification.
  Native and adapted material providers must declare one
  `MaterialStateSchema` and `MaterialTangentConvention` and enter through
  `validated_material_update(...)`. A tensor state must retain its physical
  initial value (for example, identity rather than zero for a plastic
  deformation gradient). Never infer global-Newton compatibility from a 6-by-6
  array or relabel Abaqus `DDSDDE` as a first-Piola/deformation-gradient
  tangent.
  Lower native/adapted internal variables through
  `MaterialQuadratureState.create(domain, material.state_schema, ...)`; do not
  create a second adapter-specific `STATEV` store. Preserve the schema in
  checkpoint identity and require a distributed-write/changed-partition-read
  test before claiming portable restart.
  Before a total-Lagrangian provider enters global Newton, run
  `check_material_tangent(material, point)` across elastic and plastic path
  locations and retain the evidence. Do not use that direct `dP/dF` check for
  a spatial UMAT tangent without a separately verified transformation.
- Read an Abaqus `C3D10H` source directly with `mesh.read_abaqus_mesh(...)`,
  inspect `cell.element_definitions`, and consume it only through the verified
  P2-displacement/DG0-pressure mixed route. Do not derive another mesh when the
  source already declares `C3D10H`, and do not treat neutral `tetra10` geometry
  as sufficient formulation evidence.
- When Abaqus constraints use node labels, preserve labels separately from
  backend dof ordering. Treat `*EQUATION` as an auditable constraint graph;
  reject duplicate slaves, cycles, missing node matches, and unsupported
  parallel ownership rather than silently weakening periodicity.
- For finite-deformation periodic cells, report the macro deformation
  gradient, every load increment's convergence, equation mismatch, sampled
  `det(F)` bounds, complete accepted-increment homogenized tensor histories,
  stress-state validity, and deformed geometry at scale one. Spatial field
  cadence may be sparse; do not infer that the macro CSV has the same cadence.
  Read the actual macro gradient from solved reference-point motion when any
  macro component is free; do not replace it with the nominal loading
  predictor. Read triaxiality and normalized Lode values only where
  `homogenized_stress_state_defined` is one. Treat Hill--Mandel evidence as a
  quasistatic affine/periodic contract without body-force or inertia power. A
  macro history row must keep its accepted increment size, Newton iterations,
  residual, periodic mismatch, and accepted attempt beside the physical state.
  See `docs/reference/rve_homogenization_and_statistics.md` for formulas and
  validity conventions. A
  three-dimensional uniaxial-stress periodic cell leaves both transverse
  normal macro components free and suppresses macro shear; do not fix one
  transverse stretch to unity.
- Prefer `solve_result(output=...)` for serial multi-field static output and
  the unified XDMF/HDF5 backend for finite-strain time series. Verify
  shared topology, retained reference coordinates, deformed geometry, time
  values, and all point/cell attributes. The low-level `io.XDMFTimeSeries`
  follows DOLFINx and can expose one Grid per Function. Use PVD only for a
  consumer that specifically requires it. Treat
  `completed_with_output_errors` as a completed solve with failed optional
  output, not as a lost numerical result.
- Do not claim that experimental AF-IR records make arbitrary UFL workflows
  backend neutral.
- For parameter collections, build a fresh case per sample, retain case/run
  evidence, split validation data independently, and guard learned-model
  applicability. Do not silently extrapolate or imply that neural-operator and
  PINN contract records are executable trainers.
- Use `responses.finite_difference(...)` for campaign-backed baseline and
  perturbation cases. Declare absolute or relative steps and output Quantity
  contracts. A failed perturbation makes the response incomplete; do not fill
  a missing Jacobian column with zeros.
- A campaign evaluator may return a declared mapping, `CaseOutcome`, or
  `SimulationResult`. Prefer a safe JSON campaign specification for parameter
  and sampling policy when non-programmers or agents need to edit a sweep;
  keep trusted model construction in Python.
- Use `campaigns.local_processes(workers=...)` for independent local cases. It
  uses spawned processes; do not nest it inside within-case MPI or replace it
  with threads. Use plan shards for separate MPI jobs and schedulers.
- Use `convergence.audit(...)` only with explicit refinement axes, fixed
  coordinates for every other varying parameter, and declared relative,
  absolute, or exact observable policies. Preserve failed, missing, and
  ambiguous sequences as inconclusive evidence.

## When Extending AgentFEM

Before adding a public helper, read `references/extension_rules.md`. If the new
helper is application-specific, keep it in the application package.
Private material libraries and domain products belong in separate packages
using the versioned `agentfem.extensions` entry point, not in a long-lived
private branch of the open core.

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude