<p align="center"><img src="logo/AgentFEM_logo.png" alt="AgentFEM logo" width="280"></p> <h3 align="center">The First Generation of Open-Source AI-Native FEM</h3> <p align="center"><strong>全球第一代开源 AI 原生有限元平台</strong></p>

AgentFEM

AgentFEM is an open-source finite-element platform that turns an engineering analysis into a readable Python workflow: define the study, model, materials, loads, solution procedure, outputs, and verification in one place. The same workflow can be understood and operated by researchers, scripts, IDEs, future GUIs, and AI agents.

AgentFEM was initiated by Haoming Luo and open-sourced on GitHub in July 2026.

Its immediate goal is practical: to become a dependable and unusually usable open-source FEM platform. Its longer-term vision is to make finite-element simulation an accessible scientific workspace connecting engineering, computation, data, and AI.

All You Need Is an Agent

[!TIP] Give this prompt to Codex, DS Harness, or another AI agent:

Bring AgentFEM to life.

Use https://github.com/haoming-luo/agentfem as the guide. Follow the tested
route in INSTALL.md; if I say "走镜像通道 / use the mirror channel", use its
single verified mirror route. Read AGENT_GUIDE.md and run `agentfem doctor`.

When it is ready, reply briefly with the environment, AgentFEM
version, and health-check result.

AgentFEM includes the guidance and machine-readable interfaces an agent needs. Prefer manual setup? Continue to Install.

Why AgentFEM

• AI-Native FEM — finite-element software designed from the start for agents to construct, operate, and automate naturally, without replacing deterministic mechanics and numerical computation with AI.

• Humans and Agents, Together — people and AI agents work through the same readable materials, regions, loads, solution steps, and results. AI work remains understandable, editable, and reusable by humans.

• Results You Can Check — convergence, failures, required outputs, benchmark comparisons, and applicability limits remain attached to the result instead of being separated from the simulation that produced it.

• One Run or Thousands — the same model can support an individual analysis, parameter campaigns, parallel execution, restartable studies, and reproducible data generation.

• Simulation to Learning — results can flow into scientific datasets, user-owned models, PyTorch, surrogate models, and high-fidelity fallback without rebuilding the workflow around separate glue scripts.

• Open at Every Layer — users can begin with a clear engineering workflow and still reach operators, UFL, DOLFINx, PETSc, and custom constitutive models whenever needed.

Our conviction: Open FEM for everyone. Useful simulation within reach with AI. Engineering AI grounded in physical models, observations, and verification.

Install

AgentFEM supports Linux, macOS, and Windows through WSL2.

Recommended: conda-forge

Install AgentFEM and its compatible FEniCSx/PETSc/MPI foundation together:

mamba create -n agentfem-env -c conda-forge agentfem
mamba activate agentfem-env
agentfem doctor

Already in a conda-forge environment? Run mamba install agentfem.

On Windows, run these commands inside an Ubuntu WSL2 terminal, then protect projects and results from distribution removal:

agentfem workspace --protect

<details> <summary><strong>镜像通道</strong></summary>

If you tell an agent "use the mirror channel", or the canonical package source is unreachable, use the TUNA conda-forge mirror without changing your global conda configuration. AgentFEM does not infer this choice from IP or VPN location:

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 mirror carries byte-identical conda artifacts for synchronized releases but may briefly lag a new release. See the installation notes for verification, fallback, and cache-refresh commands.

</details>

Optional: Complete Runtime Preview

For offline setup without managing an environment, preview bundles are available for Apple Silicon macOS and Windows 10/11 through WSL2.

Download the latest Complete Runtime →

On Windows, extract the ZIP and run in PowerShell:

powershell -ExecutionPolicy Bypass -File .\Install-AgentFEM.ps1

See the runtime guide for upgrades, durable project storage, removal, and Preview-specific troubleshooting.

Existing FEniCSx environment: PyPI

If you already maintain a compatible FEniCSx environment:

python -m pip install agentfem
agentfem doctor

In mainland China, the same Python package is also available from the TUNA PyPI mirror; use that route only inside an already compatible FEniCSx/PETSc environment.

See INSTALL.md for platform and MPI details, or the runtime guide for Preview installation and integrity checks.

<details> <summary><strong>Optional integrations</strong></summary>

Optional capabilities stay separate from the core Python package:

python -m pip install 'agentfem[mesh-formats]'   # Abaqus/NASTRAN meshes
python -m pip install 'agentfem[gmsh]'           # Gmsh model/.msh import
python -m pip install 'agentfem[visualization]'  # ParaView-ready helpers
python -m pip install 'agentfem[ml]'             # PyTorch adapters

</details>

Gmsh is an optional, separately licensed GPL component. It is not contained in the Apache-2.0 Python package; the recommended offline Complete runtime may aggregate it with its license and corresponding source for a one-click CAD-to-mesh workflow.

AgentFEM can share a minimal anonymous reliability signal to improve the free, open-source software; models, meshes, parameters, code, paths, and results are never included. Inspect or disable it with agentfem telemetry status|off. See the feedback and privacy contract.

Run Your First Model

Create and run a complete static-solid project in any directory:

mkdir first-agentfem-model && cd first-agentfem-model
agentfem init --template static-solid .
agentfem check
agentfem run --name baseline
agentfem show latest

The generated case.py is ordinary, editable Python. Its public workflow reads like an engineering analysis:

study = studies.static_solid(dimension=2, assumption="plane_strain")
model = models.create(study=study, mesh=domain, name="cantilever")
u = model.field(fields.displacement(domain, degree=1))

model.material(elasticity.isotropic_elastic(young=210e9, poisson=0.30))
model.clamp(u, on=left)
model.traction((0.0, -1.0e6), on=right)

result = model.step(target=u, name="static_load").solve_result()
result.verify("engineering").require()

The CLI gives the same model a readable run folder such as outputs/001-baseline/, an immutable evidence identity, a concise result summary, an MPI launch path, and a machine-readable interface. Use agentfem runs to find earlier runs and --json when an agent or GUI needs the complete record. You can also run case.py directly with Python.

What Works Today

| Area | Available workflow | | --- | --- | | Solid mechanics | Linear and thermoelastic statics; Neo-Hookean and Mooney--Rivlin finite strain; stateful 3D J2 plasticity | | Heat transfer | Steady conduction and implicit transient heat transfer | | Dynamics and vibration | Newmark and generalized-alpha dynamics; central-difference explicit dynamics; engineering linear modal and direct harmonic procedures | | Time-dependent materials | Global power-law creep and generalized-Maxwell relaxation plus material-point Arrhenius, Kachanov--Rabotnov, Sinh, and fatigue assessment tools; generalized-Maxwell harmonic coupling remains experimental | | Fracture interfaces | Fixed-path cohesive interfaces, cyclic cohesive fatigue, mixed-mode driving, cycle jump, rollback, and restart; advanced routes remain experimental | | Meshes and constraints | Structured/XDMF meshes, optional Gmsh and meshio, reviewed Abaqus project migration, direct C3D10H import, equation constraints, and distributed periodic workflows | | Results and automation | Unified fields and histories, progress, checkpoints, Golden benchmarks, campaigns, scientific datasets, surrogate validation, and FEM fallback | | External PDE breadth | One public, case-independent adapter executes all 645 cases across all 11 PDEAgent-Bench families; every family exceeds 60% and the local fixed-solver snapshot passes 558 official accuracy/time gates (method and evidence) |

AgentFEM records capability maturity explicitly. A working material-point law, an integrated global solver, and an externally verified analysis are different levels of evidence; the software does not silently treat them as equivalent. See the capability and verification guide for the detailed scope.

Release Examples

• Static elasticity — the readable beginner workflow.
• NAFEMS LE10 3D elasticity — a public curved- solid pressure benchmark with stress, displacement, force, energy, and MPI evidence.
• Transient heat transfer — implicit time integration, progress, and field output.
• Modal cantilever — linear natural frequencies, mass-normalized mode fields, residuals, orthogonality, and MPI evidence.
• NAFEMS R0016 Test 5H direct harmonic response — a public forced-vibration comparison for the provider-neutral K/M/C/K_loss/F procedure.
• Wave propagation with an inclusion — dynamic fields, source amplitude, and boundary models.
• Abaqus C3D10H periodic cell — direct mesh/equation import, quasi-incompressible hyperelasticity, and homogenized response.
• J2 plasticity and global creep — stateful nonlinear material workflows with cutback and restart.
• Simulation-to-surrogate campaign — accepted FEM data, surrogate validation, applicability guard, and FEM fallback.

These are executable release assets with numerical contracts, not only syntax demonstrations. More examples are indexed in examples/ and on the documentation site.

Open and Extensible

AgentFEM has three visible layers:

Engineering workflow
    -> reusable FEM operators, constitutive laws, constraints, and outputs
        -> FEniCSx / DOLFINx / PETSc / MPI numerical kernel

Users can stay