xdfem3d 2026.11.14__tar.gz

xdfem3d-2026.11.14/LICENSE.md

@@ -0,0 +1,58 @@
+xdfem3d — GNU Lesser General Public License v3
+================================================
+
+This licence covers the **calculation engine**: the `xdfem3d` Python package.
+
+It does **not** cover the xdfem3D desktop application — the graphical
+interface, which forms a separate package — distributed as freeware in
+compiled form only, under its own terms (the License Agreement that comes
+with the application). Nothing in those terms restricts the rights granted here.
+
+(Described by package rather than by directory on purpose: this file travels
+with the engine to a repository where the application's directories do not
+exist, and a licence that points at a path the reader cannot find tells them
+nothing.)
+
+---
+
+Copyright (c) 2026 Paulo Cachim
+
+The xdfem3d calculation engine is free software: you can redistribute it
+and/or modify it under the terms of the GNU Lesser General Public License
+as published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+The xdfem3d calculation engine is distributed in the hope that it will be
+useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
+General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+Full LGPL v3 text: <https://www.gnu.org/licenses/lgpl-3.0.html>
+
+---
+
+Engineering notice
+------------------
+
+The warranty disclaimer above is the operative legal text, and the following
+adds nothing to it — but it is the part that matters in practice, so it is
+stated plainly rather than left to be inferred from capital letters.
+
+xdfem3d computes structural analysis results. Those results are not verified,
+certified, or checked against any code of practice by their being produced.
+The software is an aid to calculation and not a substitute for engineering
+judgement. Anyone using its output in the design, verification, or
+construction of a real structure is responsible for independently verifying
+it, and remains the engineer of record.
+
+Third-party components
+----------------------
+
+The engine depends on other packages, each under its own licence — NumPy,
+SciPy, eurocodepy and others listed in pyproject.toml. They are
+dependencies, not part of this Software, and are not relicensed by this
+file. See NOTICE.md for the components bundled with the compiled
+application, where the distinction matters a great deal more.

xdfem3d-2026.11.14/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: xdfem3d
+Version: 2026.11.14
+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.
+

xdfem3d-2026.11.14/README.md

@@ -0,0 +1,279 @@
+# 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.