Metadata-Version: 2.4
Name: xdfem3d
Version: 2026.11.15
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Requires-Dist: eurocodepy>=2027.0.12
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: ezdxf ; extra == 'dxf'
Requires-Dist: ifcopenshell ; extra == 'ifc'
Requires-Dist: mcp ; extra == 'mcp'
Provides-Extra: dxf
Provides-Extra: ifc
Provides-Extra: mcp
License-File: LICENSE.md
Summary: 3D structural FEM engine with a compiled Rust core
Keywords: finite element,structural analysis,structural engineering,FEM,Eurocode,building frames,shells,solids
Author: Paulo Cachim
License: LGPL-3.0-or-later
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://pcachim.github.io/xdfem3d
Project-URL: Homepage, https://github.com/pcachim/xdfem3d
Project-URL: Issues, https://github.com/pcachim/xdfem3d/issues

# xdfem3D

[![Python versions](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
[![Core: Rust](https://img.shields.io/badge/core-Rust-orange)](https://www.rust-lang.org/)
[![eurocodepy](https://img.shields.io/badge/uses-eurocodepy-green)](https://github.com/pcachim/eurocodepy)
[![Licence: LGPLv3](https://img.shields.io/badge/licence-LGPLv3-blue)](LICENSE.md)

This repository holds two things, under two licences.

**The calculation engine** — the source in this tree, `xdfem3d`, is a Python
library with a compiled core (Rust) for three-dimensional finite element
analysis of building frames, shells, slabs, walls and solids: linear and
nonlinear, modal and time-history. It is under the GNU Lesser General Public
License v3 (LGPLv3). It has no interface and no dependency on one: it builds a
model, solves it, and gives back numbers.

**The desktop application** — a graphical interface built on that engine. It is
free to use, distributed as a compiled application under its own terms, and its
source is **not** published. It is the way most people will meet the engine:
you draw and load a model in a window, run it, and look at the results. Download
it from [Releases](https://github.com/pcachim/xdfem3d/releases).

**AI in the engine and in the application** — optional, and off until you use
it. The engine includes an [MCP](https://modelcontextprotocol.io) server
(`python -m xdfem3d.mcp`) through which an agent you already use (Claude Code,
OpenCode, Codex, Visual Studio Code, Claude Desktop) builds, checks and analyses
a model. The application adds an Agent panel in which an agent works on the model
you have open, while you watch it change, with a model of your choice (a local
one through [Ollama](https://ollama.com), or a remote one with your own
account). Remote models receive what the agent reads of your model.

**The documentation** is at
[pcachim.github.io/xdfem3d](https://pcachim.github.io/xdfem3d). It is the
manual of the application, and it also describes the engine: the
[Scripting](https://pcachim.github.io/xdfem3d/scripting.html) section is the
guide to the Python API, with a reference for every method, and the
[Command Language](https://pcachim.github.io/xdfem3d/commands.html) lists the
commands.

The rest of this page is about the library.

## The engine and the application

They are two programs with one boundary, and the boundary is kept on purpose:

- **The application uses the engine only through its public API and the
  `.xdfem3d` file.** It reaches nothing else, which is checked by a test on the
  application's side. So everything the application does to a model, a program
  can do: every change is a *command*, a method of `Model3D`.
- **The `.xdfem3d` file is the meeting point.** A model saved by the
  application opens in a script, and the other way round, with its results if it
  has some. The format is versioned: a file is read by the version that wrote
  it and by every newer one, and a newer file is refused with a message and not
  guessed at.
- **They are released independently**, on separate cycles. An engine release
  does not imply an application release, and vice versa; the two version numbers
  do not line up. The application's **Help ▸ About** lists both, so a report
  can name the right one.
- **The licences differ, and neither restricts the other.** The engine is
  LGPLv3: you may use, modify and redistribute it, from here. The application is
  a separate work, freeware in compiled form, under its own terms. Nothing in
  those terms restricts your rights to the engine.

What you would use the engine alone for: scripts that build or change many
models, parametric studies and optimisation, analysis in a service or a
pipeline, a post-processor, a front end of your own, or an AI agent working on a
model with no window at all.

## Install

Python **3.12 or later**. The compiled core is written in Rust and built with
[maturin](https://www.maturin.rs), so building from source needs a
[Rust toolchain](https://rustup.rs) and [`uv`](https://docs.astral.sh/uv/).

```bash
git clone https://github.com/pcachim/xdfem3d.git
cd xdfem3d
uv sync
uv run maturin develop        # builds the core and installs the package in the environment
uv run pytest                 # the tests, and the validation cases
```

The core install is NumPy, SciPy and
[eurocodepy](https://github.com/pcachim/eurocodepy) (the Eurocode actions and
combinations, and the catalogues of materials and profiles). The formats that
need a library of their own are extras, so that a solver in a script or a
service does not have to install them:

```bash
pip install "xdfem3d[mcp]"   # the MCP server: the mcp package
pip install "xdfem3d[ifc]"   # ifcopenshell — IFC (openBIM) import and export
pip install "xdfem3d[dxf]"   # ezdxf — DXF import and export
```

Everything they cover is reached when it is used, so the engine imports,
assembles and solves without them.

## A first model

Units are metres, kN and kPa (kN/m²), tonne for mass, degrees for angles. A
model is built from the materials and the sections up to the elements and the
loads, and an analysis case says what to solve.

```python
from xdfem3d import Model3D

m = Model3D("beam")
m.add_material("C30", E=3.3e7, nu=0.2, unit_weight=25.0, type="concrete")
m.add_section_shape("S", "C30", "rectangular", b=0.3, h=0.5)

m.add_node("A", 0, 0, 0)
m.add_node("B", 6, 0, 0)
m.add_bar("b", "A", "B", "S")

m.support("A", "ux", "uy", "uz", "rx")          # a pin that also holds the twist
m.support("B", "uy", "uz")                      # a roller along x

m.add_load_case("Q", action_type="Q")
m.add_uniform_load("Q", "b", (0, 0, -10))       # 10 kN/m downwards, in global axes
m.add_analysis_case("ULS", "linear", coefficients={"Q": 1.0})

assert m.check() == []                          # what would stop the analysis; empty when nothing does
results = m.solve_pending()                     # the analysis cases that have no current results
r = results["ULS"]

print(r.reaction("ULS", "A"))                   # fx, fy, fz, mx, my, mz — here fz = qL/2 = 30 kN
print(r.displacement("ULS", "B"))
```

Every id is a name you choose. A command that gets something that does not
exist or does not fit raises `ModelError`, says what is wrong, and leaves the
model as it was. A model with results can be **locked**, so that its input
cannot change under them.

A model is saved with `xdfem3d.save(m, "beam.xdfem3d")` and read with
`xdfem3d.load(...)`; `export_script(m)` writes the model as a Python script that
rebuilds it. The [Scripting](https://pcachim.github.io/xdfem3d/scripting.html)
section goes on from here: combinations, results, files, and recipes that are
run by the tests of the documentation.

## What it does

- **Elements** — 3D frame bars with releases, offsets and member loads, in any
  orientation; triangular and quadrilateral **shells** (membrane and bending,
  with layered and reinforced-concrete sections); **solids** (hexahedra,
  prisms, tetrahedra); node, line and surface **springs**; rigid links,
  rigid diaphragms and equal-DOF constraints imposed exactly. **Panels** (slabs
  and walls) are meshed from their outline, with openings, and share nodes with
  their neighbours.
- **Sections and materials** — rectangular and general shapes, rolled profiles
  and reinforced-concrete sections from the catalogues, fibre sections, and
  shell and solid sections; materials from the catalogue or your own, with
  uniaxial laws for the nonlinear analyses.
- **Loads** — nodal, point and uniform loads, loads on part of a bar, shell
  pressure, temperature on bars, shells and solids, support settlements, masses,
  and **field loads** given by functions of the coordinates.
- **Analysis** — linear static, P-Delta (second order), modal, response
  spectrum (EC8 spectra included, CQC and SRSS), buckling, geometric nonlinear
  (large displacements, corotational), material nonlinear (fibre sections,
  plasticity in solids and in layered shells), pushover, and time history.
- **Combinations** — sums, envelopes, absolute sums and SRSS over the results
  of analysis cases and of other combinations, and the **EN 1990** combinations
  generated for you.
- **Structures from the library** — 26 **templates** (frames, trusses, slabs,
  walls, a tower, a steel hall, a bridge deck, a block of solids…), and a
  frame grid with stories.
- **File formats** — its own `.xdfem3d` (a zip of JSON, reproducible
  byte for byte), IFC, DXF, SAP2000 `.s2k`, and an import of xdfem2D models
  (`.x2d`) as a starting point.
- **Checks and editing** — a model check that says what is wrong or doubtful
  before you run, and about 120 editing commands (add, edit, move, copy, rotate,
  scale, divide, merge, rename, remove…) that are the same commands for a script,
  the application and an agent.

Inside, the element kernels (bars, corotational bars, fibres, shells, solids,
springs and the materials) are written in Rust; assembly and solving use SciPy's
sparse solvers and ARPACK for the eigenproblems.

## Layout

- `rust/` — the compiled core (`xdfem3d_core`, exposed to Python with PyO3 as `xdfem3d._core`): the element kernels.
- `src/xdfem3d/` — the Python package: the model and its commands, the analyses, the file formats, the library and the MCP server.
- `tests/` — pytest: unit tests and closed-form cases.
- `validation/` — the cases against xdfem2D and OpenSees (frozen results, so they need neither).
- `docs/` — design notes of the core ([CORE_DESIGN.md](docs/CORE_DESIGN.md)).

## The MCP server

```bash
python -m xdfem3d.mcp                  # serves one model over MCP, on standard input and output
python -m xdfem3d.mcp --root ./work    # the agent may read and write files only in that folder
claude mcp add xdfem3d -- python -m xdfem3d.mcp
```

An agent builds, edits, checks and analyses a model and reads the results through
fifteen tools; an `edit` is a list of commands applied all together or not at all, and
undone together. The server works on a model of its own, in memory, and has no window.
To let an agent work on the model that is open in the application, use the
application's Agent panel (see [AI Agents](https://pcachim.github.io/xdfem3d/mcp.html)).

## Validation and known limits

The engine is compared with what is independent of it, and the cases run with
`uv run pytest` (the validation cases are in `validation/`, next to the unit
tests in `tests/`):

- **Closed forms**: axial, torsion, bending, releases and member loads, diagrams,
  constraints, vibration frequencies, effective masses, a single-degree-of-freedom
  spectrum, Euler loads, beam-columns, the elastica, the Von Mises truss, moment-
  curvature of steel and reinforced-concrete sections, a plastic cantilever, shell
  plates against the Navier–Mindlin series, buckling of a plate, patch tests on
  distorted meshes, among others.
- **xdfem2D**: plane frames solved by the 3D beam reproduce the 2D engine
  (static, modal, response spectrum with CQC and SRSS, and P-Delta) to 1e-8 and
  better.
- **OpenSees**: a space frame with torsion and different member axes (static,
  modal and time history), a corotational cantilever in large displacement, fibre
  and reinforced-concrete pushovers, brick and shell plasticity, and MITC4 plates.
  The OpenSees results are frozen in the repository, so the tests need no OpenSees.

What that does and does not establish, so the result is not taken for more:

- **Validated against a formula** is not **validated for your structure**. A
  case here checks that an element reproduces a textbook solution or another
  program, not that it suits a given geometry, mesh or load path.
- **There are no design checks in the engine yet**: no verification of
  reinforced concrete, steel or timber members to a code, and no design
  reports. It analyses; it does not dimension. The Eurocode parts it has are the
  actions, the combinations (EN 1990) and the response spectra (EC8).
- A generated validation report like the one of xdfem2D is **not published
  yet**; what exists is the suite in `validation/` and `tests/`.
- Where neither a closed form nor a comparison with xdfem2D or OpenSees
  covers a kind of problem, nothing independent does: say so, in a report, when
  your problem is of that kind.

## A note on results

xdfem3d computes analysis results. It does not verify them, and producing a
number is not the same as the number being right for your problem. It is an aid
to calculation, not a substitute for engineering judgement: anyone using its
output in the design or construction of a real structure is responsible for
verifying it independently and remains the engineer of record. The same holds
for anything that an AI agent does with the model or says about it.

## Citing

If xdfem3d contributes to published work, please cite it:

> Cachim, P. (2026). *pcachim/xdfem3d* [Computer software].
> https://github.com/pcachim/xdfem3d

Say the version of the engine you used (`xdfem3d.__version__`, and the
application's Help ▸ About if you used it).

## Support and contributing

Bugs and questions, for the library or the application, go to
[Issues](https://github.com/pcachim/xdfem3d/issues). A report with a model that
reproduces the problem (the `.xdfem3d` file, or a script) is the most useful
thing you can send. For anything else, write to
[eurocodepy@gmail.com](mailto:eurocodepy@gmail.com).

Development happens in a private repository, and what is published here is
that work: open an issue before you spend time on a pull request, because a
change may not be able to land as it is.

## Licence

The engine — everything in this tree — is under the **LGPLv3**; see
[LICENSE.md](LICENSE.md). It depends on
[eurocodepy](https://github.com/pcachim/eurocodepy), also LGPLv3, for the
Eurocode actions and combinations and the catalogues of materials and profiles.

The desktop application is a separate work, distributed as freeware in compiled
form under its own terms (see the
[Licenses page](https://pcachim.github.io/xdfem3d/license.html), and
`LICENSE.md` shipped with the application). Nothing in those terms restricts
your rights to the engine: you may use, modify and redistribute it under the
LGPLv3, from here.

