Results schema and readers
At the core of xfea is the idea that pre- and post-processing should be independent from the solver. Results are a vital part of that workflow.
A typical workflow outside xfea is:
- the user runs the analysis
- a proprietary results database is created by the solver
- the user must know how to read the solver database
In xfea the workflow is:
- the user runs the analysis
- a proprietary results database is created by the solver
- a results reader converts the solver’s files into neutral rows
- the results database plugin persists and serves results in its own format
- the user never needs to read the solver database directly
Schema model
Section titled “Schema model”Each Result class defines the data for one row via a RowSchema. Columns are
described using ColumnSpec, which uses Python types (int, float, str,
bool) instead of backend-specific SQL strings. This keeps the schema neutral.
A field of results, such as DisplacementFieldResults, names the table its rows go in (u for displacements)
and gives that table’s columns through its schema. The step-level summaries of modal and buckling steps pair a
table name with a row class through TableSchema.
from xfea.results.database import ColumnSpec, RowSchema, TableSchema
class DisplacementResult(Result): schema = RowSchema( [ ColumnSpec("key", int), ColumnSpec("step", str), ColumnSpec("part", str), ColumnSpec("frame", int), ColumnSpec("time", float), ColumnSpec("x", float), ColumnSpec("y", float), ColumnSpec("z", float), ColumnSpec("xx", float), ColumnSpec("yy", float), ColumnSpec("zz", float), ], results_func="find_node_by_key", components_names=["x", "y", "z", "xx", "yy", "zz"], )
EIGENVALUES_TABLE = TableSchema("eigenvalues", EigenvalueResult) # a step-level summarySchemas do not declare primary keys. Each backend is free to manage its own row identity (SQLite’s rowid, for example) without polluting the shared schema.
Results readers and database plugins
Section titled “Results readers and database plugins”Each solver has a results reader, a plugin under xfea.results_readers, that reads the native solver output
and emits neutral rows (dicts or tuples) using the column names from the
RowSchema. Those rows are passed to the active ResultsDatabase.
The database plugin (SQLite today) maps ColumnSpec types to its own
storage types when writing, and performs the inverse mapping when reading.
This keeps the core results model independent from both solver and storage
backend, and allows viewers to consume the same data structure.
In the core, rows are defined in xfea/results/results.py, fields in fields.py and the step-level summaries in
perturbations.py.
Reader contract
Section titled “Reader contract”When writing a results reader:
- Emit rows as
dictortuple/list. - Dict rows: keys must match
ColumnSpec.nameexactly; no extra keys. - Tuple rows: values must follow the exact order of
RowSchema.columns. - If the schema includes a
stepcolumn, passsteporstep_nametoResultsDatabase.record_table(...)so the database can inject it when missing. - Do not add backend-specific columns (no
id, no SQL-only fields).
Optional debug check: set settings.VERBOSE = True to validate rows against
the schema on write.
© 2026 Francesco Ranaudo · Text and pictures CC BY 4.0 · Code Elastic License 2.0 · how to reuse them