Installed Project Workflow

AgentFEM is both a Python library and an installed finite-element application. The same case remains executable with python case.py; the agentfem command adds project discovery, checks, repeatable output locations, MPI launch, and machine-readable run evidence.

Prepare the numerical environment

On Linux, macOS, and Windows through WSL2, install AgentFEM and its compatible FEniCSx/PETSc/MPI foundation from conda-forge. Then check the actual runtime:

mamba create -n agentfem-env --override-channels -c conda-forge \
  python=3.11 fenics-dolfinx=0.11 agentfem
mamba activate agentfem-env
agentfem doctor
agentfem doctor --json

Mirror channel / 镜像通道

If you ask an agent to "use the mirror channel", or the canonical source is unreachable, use one mirror for the complete conda-forge stack. AgentFEM does not infer the route from IP or VPN location. The command below is temporary: it does not rewrite .condarc or affect other environments.

mamba create -n agentfem-env --no-rc --override-channels \
  -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge \
  python=3.11 fenics-dolfinx=0.11 agentfem
mamba activate agentfem-env
agentfem doctor

The full INSTALL.md also covers package search, release-cache refresh, PyPI fallback, and Windows.

Persistent project storage on WSL

On WSL, protect the conventional project directory before creating the first case:

agentfem workspace --protect

It remains available as ~/AgentFEMProjects, while the authoritative files live in Windows Documents\AgentFEMProjects and survive runtime replacement.

The JSON form is intended for issue reports, IDE integrations, and agents. It records the platform route, exact interpreter and imported package, core versions, and optional mesh, visualization, machine-learning, and distributed-MPC integrations.

agentfem capabilities gives people a one-screen index with progressively expandable topics such as materials, procedures, and an individual model name. agentfem capabilities --json supplies the complete stable record and also separates the public Python surface into core, advanced, and expert layers. A generated first case should normally use only the core layer; this reduces API search without restricting direct access to advanced finite-element or backend capabilities. The same report separates the concise Model vocabulary from advanced and 0.2.x compatibility methods, and lists the accepted/required options for every built-in Step provider. Agents and interfaces should consume those contracts instead of guessing solver arguments from examples.

Create a project

On WSL, begin below ~/AgentFEMProjects. On Linux and macOS, projects may live in any user-owned directory.

agentfem templates
mkdir beam
cd beam
agentfem init --template static-solid .
agentfem check
agentfem run --name baseline
agentfem runs
agentfem show latest
agentfem verify

Initial templates include static-solid, steady-heat, and structural-dynamics. The generated layout is intentionally small:

beam/
├── agentfem.toml
├── case.py
├── AGENTS.md
├── README.md
└── outputs/

case.py is the source of modeling truth. It contains the Study, mesh, regions, fields, materials, constraints, loads, steps, and result requests. agentfem.toml does not duplicate the physics; it only identifies the project name, Python entrypoint, and output root.

For an existing Abaqus input deck, begin with migration rather than a blank template:

agentfem inspect-abaqus legacy/model.inp --json
agentfem migrate-abaqus legacy/model.inp ./migrated-model
cd migrated-model
agentfem check

This creates a copied source bundle and a scope-aware migration.json. The generated case.py is deliberately guarded until Part/Instance transforms, sections, materials, element formulations, loads, and procedures have been reviewed. Project creation is therefore automation of evidence and structure, not an unsupported whole-deck equivalence claim.

If migration.json marks the narrow native route eligible, create an inactive reviewed draft with:

agentfem lower-abaqus . --reviewed-by "Your name" --unit-system SI

Review case.native.py and lowering.json; activation is a separate explicit action. Unsupported formulation or workflow semantics remain blocked rather than being approximated silently.

Use the concise Study factories for common engineering work:

study = studies.static_solid(dimension=3)
study = studies.steady_heat_transfer(dimension=3)
study = studies.transient_heat_transfer(dimension=3)
study = studies.dynamic_solid(dimension=3, method="explicit")
study = studies.dynamic_solid(dimension=3, method="newmark")

The Study states the physical problem; method selects the procedure without changing that problem's identity. model.check() uses the same provider rules as model.step(...), so a declared but unsupported combination is rejected before numerical work begins.

Time histories are reusable model assets rather than custom step callbacks:

ramp = amplitudes.ramp(0.0, 1.0, start_time=0.0, end_time=0.1)
model.traction((0.0, -1.0e6), on=loaded, amplitude=ramp)
model.prescribed_temperature(T, temperature_history, on=heated)
model.convection(
    on=cooled,
    coefficient=25.0,
    ambient_temperature=ambient_history,
)

When the engineering input is a total end force rather than a traction, let the model distribute it over the selected reference edge or surface:

model.surface_force((0.0, -50_000.0), on=loaded)

AgentFEM assembles the MPI-global boundary measure and applies a uniform traction whose resultant is the requested vector. In 2D the force is per unit out-of-plane thickness.

Standard/Explicit dynamics and transient heat update registered histories at their physical step times. Manual callbacks remain available for advanced state not represented by a model asset.

Resolve input files from the case directory rather than the shell's current directory:

from pathlib import Path

HERE = Path(__file__).resolve().parent
mesh_path = HERE / "meshes" / "component.inp"

Run directly or through the product shell

Direct Python remains supported:

python case.py

The product shell adds a stable run identity and output contract:

agentfem run
agentfem run --name baseline
agentfem run --mpi 4

--name controls the readable folder label. --run-id is reserved for an explicit immutable execution identity in automation and compatibility flows.

The product shell inspects the launcher against the MPI implementation used by mpi4py. This avoids accidentally starting a conda MPICH runtime with a system Open MPI launcher. For a test or another MPI-aware program, let AgentFEM select the compatible launcher instead of calling bare mpiexec:

agentfem mpi-run -n 2 -- python -m pytest tests/test_parallel_results.py

Do not start a second MPI launcher from an already distributed case. The CLI detects the communicator and runs the entrypoint on it.

Understand the output contract

Each run receives its own directory:

outputs/001-baseline/
├── execution.json
├── result.json
├── summary.md
├── fields.xdmf
├── fields.h5
└── logs/

• execution.json answers whether the application completed or failed. A failed run records its stage, stable validation/error code when available, MPI rank evidence, and complete traceback; numerical result files are not required in order to diagnose a preflight or execution failure.
• result.json is the published SimulationResult, including quantities, histories, artifacts, checkpoints, metadata, and verification evidence.
• outputs/latest.json points to the most recent run without a platform-specific symbolic link.
• XDMF/HDF5, CSV, NPZ, images, and reports are artifacts referenced by the result rather than replacements for it.

001-baseline is a human-facing run number and name. The immutable run_id stored in the records remains the machine/provenance identity. Use agentfem run --name fine-mesh for the next named run, agentfem runs to list recent work, and agentfem show latest for the concise result view. AgentFEM continues to recognize the earlier outputs/<project>/<run-id>/ layout.

Published results are sealed automatically. agentfem verify follows the latest run by default and checks both the manifest and all registered files. It detects changed or incomplete output; it does not replace convergence, mesh-sensitivity, or engineering validation checks.

agentfem run --json reserves standard output for the final machine record and writes case and solver logs into the run directory. A GUI or agent can parse the response without scraping progress prose.

Check before solving

The first agentfem check validates project structure and Python syntax without solving. For a case created with an earlier release, also run:

agentfem upgrade --json

This is a dry-run migration plan. --apply-safe is limited to deterministic project metadata; findings marked semantic_review=true require inspection of the finite-element meaning and renewed evidence. Model construction should additionally call model.check() before the step. The evidence layers are separate:

1. project and entrypoint checks;
2. model, region, material, load, and capability checks;
3. solver convergence evidence;
4. scientific verification and validation evidence.

A zero process exit code means the requested operation completed. It does not by itself promote a result from computed to verified.

Pause and resume transient work

Heat transfer, Standard dynamics, and Explicit dynamics share one restart workflow:

step.run(until_step=50)
checkpoint = step.save_checkpoint("restart/step-50")

resumed = build_the_same_step()
resumed.load_checkpoint(checkpoint)
result = resumed.solve_result(output="restart/continuation.xdmf")

The checkpoint detects incompatible procedures, time contracts, mesh/function layouts, missing shards, and corrupted shards before applying state. Fast rank-local shards support the same MPI size and mesh partition. For supported nodal transient state, save_checkpoint(..., portable=True) or checkpointing.every(..., portable=True) additionally writes a verified physical-node-keyed state that can be restored with a different MPI partition or rank count. Ordinary nodes use quantized coordinates and field components; coincident independent nodes on a split cohesive interface additionally use their durable source-node identity. Constitutive integration-point state requires a separate portable cell/quadrature identity and is not implied by the nodal option. The continued field artifact starts at the checkpoint time and is labeled as a continuation segment; full histories and execution evidence remain attached to the result.

For common post-processing, prefer named, MPI-safe quantities over ad hoc local array inspection: results.region_integral(...), results.region_average(...), results.boundary_resultant(...), and results.field_extrema(...).

Continue into campaigns and learning

One case and a parameter campaign should use the same case builder and result contract. Campaigns consume declared inputs and SimulationResult outputs, then create a ScientificDataset only when the selected evidence policy is satisfied. The dataset can be exported to NumPy, passed to built-in ridge/POD/PyTorch surrogates, or used by an existing user model. A neural-field model can also participate directly in the ordinary Step lifecycle through model.step(target=spec, executor=my_solver); no companion package or framework-specific base class is required. Maintained reference providers for selected methods live in the optional AgentFEM-Learning companion.