xdfem3D
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.
AI in the engine and in the application — optional, and off until you use
it. The engine includes an MCP 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, 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. It is the manual of the application, and it also describes the engine: the Scripting section is the guide to the Python API, with a reference for every method, and the Command Language 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
.xdfem3dfile. 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 ofModel3D. - The
.xdfem3dfile 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, so building from source needs a
Rust toolchain and uv.
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 (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:
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.
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
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 asxdfem3d._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).
The MCP server
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).
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/andtests/. - 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. 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.
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. It depends on 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, 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.
Metadata
Release files for xdfem3d 2026.11.15
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xdfem3d-2026.11.15.tar.gz | 336.1 kB | With provenance | Details for xdfem3d-2026.11.15.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| xdfem3d-2026.11.15-cp312-abi3-win_amd64.whl | CPython 3.12 | abi3 | Windows x86-64 | Details for xdfem3d-2026.11.15-cp312-abi3-win_amd64.whl |
| xdfem3d-2026.11.15-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl | CPython 3.12 | abi3 | Linux glibc 2.17+ x86-64 | Details for xdfem3d-2026.11.15-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
| xdfem3d-2026.11.15-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl | CPython 3.12 | abi3 | Linux glibc 2.17+ ARM64 | Details for xdfem3d-2026.11.15-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
| xdfem3d-2026.11.15-cp312-abi3-macosx_11_0_arm64.whl | CPython 3.12 | abi3 | macOS 11.0+ ARM64 | Details for xdfem3d-2026.11.15-cp312-abi3-macosx_11_0_arm64.whl |
| xdfem3d-2026.11.15-cp312-abi3-macosx_10_12_x86_64.whl | CPython 3.12 | abi3 | macOS 10.12+ x86-64 | Details for xdfem3d-2026.11.15-cp312-abi3-macosx_10_12_x86_64.whl |
Total release size: 4.5 MB
Release files / xdfem3d-2026.11.15.tar.gz
| Download URL | xdfem3d-2026.11.15.tar.gz |
|---|---|
| Size | 336.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
556f3ae455740ae6f72a8e72dddafd317b07f6c5158716274aa2862d4520c203
|
|
BLAKE2b-256 checksum How to use checksums |
02c49378fb59eb679b7fc9d222c76ab8969f65e1ce7b2f6b21ce735b25ff82d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / xdfem3d-2026.11.15-cp312-abi3-win_amd64.whl
| Download URL | xdfem3d-2026.11.15-cp312-abi3-win_amd64.whl |
|---|---|
| Size | 757.5 kB |
| Tags | CPython 3.12 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
716d9a05a500b480ea4a43f40a2f16794a7259afa5ea8a429741f07791fd47de
|
|
BLAKE2b-256 checksum How to use checksums |
559f51e6412b7c3da5b013422eb2a1c1afa8ea936bb9125ab8c2eede6d94baa5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / xdfem3d-2026.11.15-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | xdfem3d-2026.11.15-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 878.6 kB |
| Tags | CPython 3.12 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
8a27d0036165fb347b8d37d1bcab9d9d6c71b8c50b6bbf208f4585a7e6a21c23
|
|
BLAKE2b-256 checksum How to use checksums |
0906e8caa55cdc93e5dc4dd1505930f50967246f0b540c63db3b94d0e70f65de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / xdfem3d-2026.11.15-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | xdfem3d-2026.11.15-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 855.5 kB |
| Tags | CPython 3.12 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
9824200a22d19eb3a402c43b766d3495a19ab2ac6e3f39923cd188cacd7a2377
|
|
BLAKE2b-256 checksum How to use checksums |
426c0f9e7ee878b8326ab10d5c3f1bcd9169c8b612b0d226a43c52a11567efc4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / xdfem3d-2026.11.15-cp312-abi3-macosx_11_0_arm64.whl
| Download URL | xdfem3d-2026.11.15-cp312-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 805.2 kB |
| Tags | CPython 3.12 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
98a965c9ea511de038684254bcd3fcbfe7588b6c54a0427c498e051ed47c8e3a
|
|
BLAKE2b-256 checksum How to use checksums |
d715bb3ead5fc1c9731b9b7a145c397bdd33e06cc11f1f91f5df4de9a80b8129
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / xdfem3d-2026.11.15-cp312-abi3-macosx_10_12_x86_64.whl
| Download URL | xdfem3d-2026.11.15-cp312-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 827.3 kB |
| Tags | CPython 3.12 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
af165fb21a923056f0854236a32b8dfc848d08d8b5569551282cac6210543957
|
|
BLAKE2b-256 checksum How to use checksums |
9ab1222875e24ac66beb883dc1d9b072755ee011b40d58d901a4a90b627e2b05
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for xdfem3d 2026.11.15
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 6 files in this release have been uploaded with provenance metadata.
Attestation for xdfem3d-2026.11.15.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.