Skip to content

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

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 summary

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

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.

When writing a results reader:

  • Emit rows as dict or tuple/list.
  • Dict rows: keys must match ColumnSpec.name exactly; no extra keys.
  • Tuple rows: values must follow the exact order of RowSchema.columns.
  • If the schema includes a step column, pass step or step_name to ResultsDatabase.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