Skip to content

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 xfea library (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.

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:

  1. 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.
  2. Problem (local: core). Loads, analysis type, requested outputs.
  3. 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.
  4. Solve (local: the user’s solver). The solver runs the input file.
  5. 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.


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)
  • 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.
  • Return a neutral MeshResult (nodes, elements, groups, mesh metadata), which the core applies to a Part.
  • Run locally, as part of building the model. They need no solver.
  • 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.
  • Render neutral scene objects, through the core contracts Scene, SceneContext and ViewerSettings.
  • Work on model objects plus database-backed results, whatever the database.

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.py
def __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.

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.


  • One schema: every solver’s results are mapped to the xfea results schema, whatever the native format.
  • Database contract: results databases are plugins in xfea.results_databases. xfea_sqlite stores 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, and Numbering from 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.json with the reader’s name and the numbering, and problem.extract_results() uses it.

  • 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_CHECKING blocks.

© 2026 Francesco Ranaudo · Text and pictures CC BY 4.0 · Code Elastic License 2.0 · how to reuse them