Architecture
xfea is an open, solver-independent language for FEA models and results. The user’s own AI writes models in it, queries and checks them, and runs them on the user’s own solver. The input side is one model representation for the AI to work in; the output side is one results schema for it to read from, whatever solver produced the results.
The architecture follows from that:
- The core is open. The
xfealibrary (the model, units, the results schema and the plugin contracts) can be read by the user and by their AI. Meshing, the results databases and the viewers are open plugins on top of it. - The conversion is closed. Turning a neutral model into a solver’s input file is the part that is not readable. It runs as a service: the model’s definition in, a plan for the input file out.
- The solver is the user’s. It always runs on the user’s machine, or their firm’s server.
- Results stay local. Result files are too large to send anywhere, so the open core reads them where they are.
- The AI is the user’s. xfea does not host one. It gives the AI tools, through an MCP server, and the AI does the reasoning, including checking its own work.
1. Where each part runs
Section titled “1. Where each part runs”flowchart TB
subgraph off["Off the user's machine"]
provider["AI model provider<br/>runs the user's AI"]
conversion["xfea conversion service<br/>definition in, plan out"]
end
subgraph local["The user's machine, or their firm's server"]
assistant["AI assistant<br/>Claude Desktop, or any MCP client"]
mcp["xfea-mcp<br/>tools for the AI"]
core["xfea core<br/>model · units · results schema · plugin contracts"]
plugins["Open plugins<br/>meshing · results database · viewers"]
solver["The user's solver"]
folder["Project folder<br/>scripts · models · input files · results"]
end
provider <-->|"conversation and tool results"| assistant
assistant <-->|"MCP over stdio"| mcp
mcp --> core
core <-->|"definition out, plan back"| conversion
core --> plugins
core -->|"input file"| solver
solver -->|"result files"| folder
plugins <--> folder
The steps of building and running a model, and where each one happens:
- Modelling (local: core and open plugins). The AI writes an xfea script: geometry, parts, materials, sections, mesh, connections, supports. The core builds the model; the AI looks at it (a description, a picture, the 3D viewer) and fixes it.
- Problem (local: core). Loads, analysis type, requested outputs.
- Conversion (server). The model’s definition, without the mesh, goes to the conversion service, which returns a plan; the core writes the input file from it, here.
- Solve (local: the user’s solver). The solver runs the input file.
- Results (local: core and open plugins). The results are read into the results database, which the AI queries.
Checking is not a step of its own: the AI checks after every step, with the inspection tools xfea gives it.
2. Packages
Section titled “2. Packages”| Package | Kind | What it does |
|---|---|---|
xfea |
Core | The model, problems and steps, units, the results schema, the registries and plugin contracts |
xfea_gmsh (in xfea) |
Meshing plugin | Mesh geometry and return a neutral mesh for the core to apply to a part |
xfea_sqlite (in xfea) |
Results database plugin | Store results in the neutral schema and link them back to parts, nodes and elements |
xfea_view (in xfea) |
Viewer plugin | Show models and results: the browser viewer (three.js), and the ParaView desktop app |
xfea_tools (in xfea) |
Tools | Cutting planes and cross-section plots, filtering and smoothing a mesh, selecting faces, fire curves |
xfea-mcp |
MCP server | The tools the AI uses: write and run scripts, build and show a model, read results |
| One per solver | Results reader | Read the solver’s result files into the results database (open) |
| One per solver | Solver backend (conversion) | Write the solver’s input file and say how to run it (closed, on the service) |
The core library (xfea)
Section titled “The core library (xfea)”- Abstractions: the language of structural analysis: nodes, elements, sections, materials, parts, problems, steps, loads.
- Base classes: model objects inherit from
FEAData, which gives them serialization (__data__/__from_data__) and registration. - Registry: maps core classes to the active backend’s implementations (section 3).
- Units: the model’s unit system (
Model(units=...), e.g.SI_mm) sets its physical constants, such as g; xfea does not convert or check units. See Units and conventions. - Plugin contracts: the registries and neutral payloads for meshing, results databases and viewers.
Meshing plugins
Section titled “Meshing plugins”- Return a neutral
MeshResult(nodes, elements, groups, mesh metadata), which the core applies to aPart. - Run locally, as part of building the model. They need no solver.
Results database plugins
Section titled “Results database plugins”- Store neutral field-result rows, with the unit system, the ordered steps and an index linking results back to parts, nodes and elements.
- Rebuild results onto model entities for post-processing and viewing.
Viewer plugins
Section titled “Viewer plugins”- Render neutral scene objects, through the core contracts
Scene,SceneContextandViewerSettings. - Work on model objects plus database-backed results, whatever the database.
3. How the backend is chosen (__new__)
Section titled “3. How the backend is chosen (__new__)”User code only ever uses the core classes. When a backend is active, creating a core object returns the backend’s implementation instead:
# FEAObject.__new__ in xfea/base.pydef __new__(cls, *args, **kwargs): imp = _IMPLS.get(cls) # the active backend's implementation of this class, if any if not imp: return super(FEAObject, cls).__new__(cls) return super(FEAObject, imp).__new__(imp)Node(xyz=[0, 0, 0])is the same line for every solver.- With no backend active, the core classes are used as they are. That is enough to build, inspect, show and
solve a model (the conversion service writes the input); only
write_input_file, which writes the input here, needs a backend. - One backend per process:
set_backend()chooses it once, and choosing a second one raises an error.
4. Plugin registration
Section titled “4. Plugin registration”Plugins are found through Python entry points declared in their pyproject.toml:
| Entry point group | Plugins |
|---|---|
xfea.backends |
one per solver |
xfea.meshing |
gmsh |
xfea.results_databases |
sqlite |
xfea.results_readers |
one per solver |
xfea.viewers |
browser, paraview |
Plugins are looked up by name when they are first asked for. A solver plugin on a firm’s own server is licensed by agreement; the other plugins need none. See What’s free, what needs an account.
5. Results
Section titled “5. Results”- One schema: every solver’s results are mapped to the
xfearesults schema, whatever the native format. - Database contract: results databases are plugins in
xfea.results_databases.xfea_sqlitestores field rows, unit-system metadata, ordered steps and the entity index. - Readers: an open package per solver (
xfea.results_readers) reads the solver’s own, documented output files into these rows, on the user’s machine. Readers are per solver because their dependencies differ (one solver’s files can only be read with that solver’s own library); the contract is the core’s (xfea.results.readers:ResultsReader, andNumberingfrom the solver’s node and element numbers to the model’s, leaving out helpers a conversion added). - After a solve through the conversion service, the run leaves
xfea-run.jsonwith the reader’s name and the numbering, andproblem.extract_results()uses it.
6. Design rules
Section titled “6. Design rules”- Inherit from the core: backend classes subclass the core’s abstract bases or concrete classes, so they keep the core’s serialization and checks.
- Keep the core neutral: core classes describe the physics and the geometry; nothing solver-specific goes in them. A solver’s behaviour is the backend’s job.
- One meaning per input: an argument means the same thing in the core and in every backend, and backends read
derived values from the core (for example a beam’s local axes from
element.frame) instead of computing them again. - Type hints: annotate public APIs, with imports for type checking in
TYPE_CHECKINGblocks.
© 2026 Francesco Ranaudo · Text and pictures CC BY 4.0 · Code Elastic License 2.0 · how to reuse them