QF Solver

Python FEM/FEA solver for structural mechanics and dynamics, with inspectable formulations, reproducible V&V and bounded large-model workflows.

QF Solver is deliberately evidence-led: support is scoped by element, analysis, material, mesh, loading and solver route. A passing example is not a universal qualification.

On this page: Why QF Solver? · Intended use · Installation · Quick start · Main capabilities · Verification · Performance · Limitations · Documentation · Contributing

Why QF Solver?

• Python-native API and inspectable finite-element implementations.
• Numerical diagnostics intended to make assumptions and failure modes visible.
• Reproducible verification evidence with explicit capability maturity.
• Optional integrations for bounded HDF5 and documented large-model workflows; mixed distributed PETSc/MPI remains not validated.

Project status

Item	Status
Release line	0.2.8
Development stage	Beta
Python	>=3.10
CI validation	Windows and Linux
License	Apache-2.0
Documentation	Online documentation
Release archive	Zenodo v0.2.8

Release availability is authoritative on PyPI and GitHub Releases. This page describes the published 0.2.8 release line. Citation metadata is authoritative in CITATION.cff.

Intended use

QF Solver is designed for inspectable structural FEM, engineering prototyping and reproducible V&V. It is not presented as a certified solver, a universal nonlinear solver or a replacement for a commercial general-purpose FEA package.

Installation

For a published package:

python -m pip install qf-solver
qf-solver --version

To install the immutable source for this release:

git clone --branch v0.2.8 --single-branch https://github.com/emptiesvoid-cloud/QF_solver.git
cd QF_solver
python -m pip install .
qf-solver --version

Use the matching release tag or source archive for reproducibility. Optional development and integration extras are described in the installation guide. HDF5, PETSc, MPI and SLEPc remain optional integrations and are not required for the core import or standard small examples.

Quick start

Command line

From the repository root, run the maintained TET4 example:

qf-solver check-mesh --input examples/tet4_static.json
qf-solver solve --input examples/tet4_static.json --output results/tet4.json

See the first-calculation guide for the complete workflow.

Python

Use the public qf_solver namespace:

from qf_solver import check_mesh, load_model, save_result, solve_model

model = load_model("examples/tet4_static.json")
check_mesh(model)
result = solve_model(model)
save_result(result, "results/tet4.json")

The historical solveur namespace remains available for compatibility. New applications should use qf_solver; see the API stability guide.

A successful maintained example writes the requested JSON result file and returns a passing solve status. Inspect the result object or JSON for displacements and derived result fields; model-specific stresses, reactions and diagnostics remain subject to the documented route scope.

Main capabilities

The public status model is bounded and route-specific. The central capability index links each status to its evidence and limitations.

At a glance: solids include TET4, TET10, HEX8, HEX20 and WEDGE6; the repository also contains BEAM2 and MITC3/MITC4 shell routes. Main analyses are static, modal and buckling, with mixed Newmark/harmonic dynamics remaining experimental-bounded. Geometric nonlinearity and PYRAMID5 are research or internal paths, and mixed distributed PETSc/MPI is not validated.

Capability	Status	Boundary
Linear static and small-strain solid routes	QUALIFIED_BOUNDED	Recorded element/material/load combinations only.
WEDGE6 static	QUALIFIED_BOUNDED	Documented Gmsh Prism 6 static scope.
WEDGE6 modal	QUALIFIED_BOUNDED	Documented homogeneous consistent-mass modal scope.
Mixed static, modal, translational MPC and multi-material	QUALIFIED_BOUNDED	Connected conforming serial TET4/WEDGE6/HEX8 workflows.
Mixed Newmark and harmonic	EXPERIMENTAL_BOUNDED	Connected serial TET4/WEDGE6/HEX8 frozen dynamic cases.
Bounded Abaqus/CalculiX .inp subset	EXPERIMENTAL_BOUNDED	Documented subset; not general format compatibility.
Family-aware mixed HDF5 results	EXPERIMENTAL_BOUNDED	Opt-in schema 1.0 storage and selective reads.
Frictionless contact	EXPERIMENTAL_BOUNDED	Penalty node-to-triangle, bounded small-sliding cases.
HEX8-SRI	EXPERIMENTAL_BOUNDED	Locking-sensitive linear-elastic capability; not locking-free.
MITC4 modal	EXPERIMENTAL	Experimental route with its recorded scope.
Mixed distributed PETSc/MPI	NOT_VALIDATED	Architecture evidence only; no validated runtime claim.
PYRAMID5	INTERNAL / RESEARCH_ONLY	Internal feasibility path; not a supported public element.

The authoritative 0.2.8 element-analysis registry contains 32 QUALIFIED_BOUNDED, 14 EXPERIMENTAL, 0 NOT_QUALIFIED and 46 records. Mixed workflows and separate capabilities are not added to those 46 records. Release-specific evidence links in this page are pinned to the immutable v0.2.8 tag; project-global links may follow the project default branch.

Verification and maturity

Qualification records use prospective contracts, frozen gates, reproducible evidence, replay checks and failure cases. The maturity labels mean:

• QUALIFIED_BOUNDED: frozen gates passed within the declared scope; not a universal claim.
• EXPERIMENTAL_BOUNDED: usable route with bounded evidence and explicit limitations.
• EXPERIMENTAL: evidence exists, but the route remains below bounded qualification.
• RESEARCH_ONLY: discovery or feasibility work; no production support claim.
• NOT_VALIDATED: implementation or architecture exists, but required runtime evidence is absent or failed.
• INTERNAL: not part of the supported public surface.

Read the V&V and maturity model and the 0.2.8 verification summary pinned to the release tag.

Performance context

Recorded large-model results are historical, bounded evidence for structured TET4 workloads in documented PETSc/MPI environments:

Workload	Recorded context	Boundary
~1.029M DOF	Two stable PETSc replays	Structured TET4 only.
~3M DOF	Silver replays and bounded Gold evidence	Same recorded route and environment.
~5.01264M DOF	Bronze and two complete 5M Silver replays	Structured TET4, recorded 8-rank environment.
~10M DOF	Bounded C3 capacity/solve context	Not a universal scaling guarantee.

No claim of GPU, general HPC, hardware-independent scaling, mixed-mesh support or general nonlinear scaling is made. The mixed distributed PETSc/MPI runtime remains NOT_VALIDATED.

Limitations

• General nonlinear dynamics and finite-kinematic material routes are not production-qualified.
• PYRAMID5 is internal/research only; WEDGE15 is not supported.
• MITC4 modal remains EXPERIMENTAL.
• HEX8-SRI remains EXPERIMENTAL_BOUNDED, not locking-free or universally robust.
• The .inp reader supports a bounded Abaqus/CalculiX subset only.
• Contact is limited to the documented frictionless penalty node-to-triangle scope.
• Mixed Newmark and harmonic are bounded linear serial workflows.
• Mixed distributed PETSc/MPI is NOT_VALIDATED; no partial-rank or general distributed claim is made.

See the dedicated limitations page and solver/backend notes.

Documentation

• Getting started
• Capability index
• Elements
• Analyses
• What's New in 0.2.8
• Benchmarks
• V&V and maturity
• API stability
• Historical 0.2.7 verification
• Detailed changelog

Contributing, citation and license

Development setup and quality checks are described in CONTRIBUTING.md. QF Solver is distributed under the Apache License 2.0; documentation and original examples are under CC BY 4.0. Third-party terms are listed in THIRD_PARTY_LICENSES.md. For QF Solver 0.2.8 specifically, cite the version DOI. The concept DOI identifies the evolving QF Solver project. Full citation metadata is in CITATION.cff.

No claim of certification or universal physical validation is made.