Skip to main content

xdfem3D

Python versions Core: Rust eurocodepy Licence: LGPLv3

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 .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, 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 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).

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/ 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. 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)

Source distribution for xdfem3d 2026.11.15
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)

Table of built distributions (wheels) for xdfem3d 2026.11.15
File Actions
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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Security 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.

Select from 6 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page