API stability
xfea is at 0.x: the API for building models, analysis problems and
solver-neutral workflows is in use, but not yet frozen. Until 1.0, a minor
release (0.1 → 0.2) may change it; a patch release (0.1.0 → 0.1.1) does not.
Pin a minor version (xfea~=0.1.0) if your scripts must keep working
unchanged.
The public surface
Section titled “The public surface”These are the parts of xfea the compatibility policy below covers, and
what will become the stable surface at 1.0:
- Top-level package exports in
xfea - The namespaces
xfea.model,xfea.problemandxfea.results - The CLI entry point
xfea - Persistent runtime settings exposed through
xfea.settings
Within those namespaces, symbols exported through module __all__ are public
unless a docstring or page marks them as experimental.
Not public
Section titled “Not public”These can change in any release:
xfea._internal: the plugin registries, the logger and the terminal output xfea’s own packages share- Private modules, functions, and attributes prefixed with
_ - Internal registration details used to swap backend implementations
- Test-only helpers and docs-generation scripts
Compatibility policy
Section titled “Compatibility policy”- Patch releases fix behaviour so that it matches the documentation, and add nothing that breaks existing scripts.
- Minor releases may add to the public surface and, before 1.0, change it. Each change is listed in the changelog with how to update a script.
- Where it can, a public API that is going away is first deprecated, with a warning that names its replacement, for at least one minor release.
- From 1.0, breaking changes to the public surface need a new major release.
Backend expectation
Section titled “Backend expectation”Backends remain an implementation detail behind the core workflow. xfea guarantees the core data model and user API, not that every backend plugin is present in every environment.
Core code should therefore:
- fail clearly when a backend-specific action requires a missing plugin
- avoid noisy failures during routine import
- keep solver-neutral modeling and result access usable without implicit plugin activation
© 2026 Francesco Ranaudo · Text and pictures CC BY 4.0 · Code Elastic License 2.0 · how to reuse them