Metadata-Version: 2.4
Name: qf-solver
Version: 0.2.8
Summary: Open-source white-box Python finite element solver for structural mechanics, dynamics and verifiable engineering simulation.
Author: Quentin Farinazzo
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/emptiesvoid-cloud/QF_solver
Project-URL: Source, https://github.com/emptiesvoid-cloud/QF_solver
Project-URL: Issues, https://github.com/emptiesvoid-cloud/QF_solver/issues
Project-URL: Documentation, https://emptiesvoid-cloud.github.io/QF_solver/
Project-URL: Changelog, https://github.com/emptiesvoid-cloud/QF_solver/blob/main/CHANGELOG.md
Keywords: finite-element-method,fem,structural-mechanics,engineering-prototyping,scientific-computing,qf-solver,white-box-audit
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-DOCS
License-File: NOTICE
License-File: THIRD_PARTY_LICENSES.md
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Provides-Extra: hdf5
Requires-Dist: h5py>=3.10; extra == "hdf5"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-cov>=6.2; extra == "test"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "test"
Requires-Dist: h5py>=3.10; extra == "test"
Requires-Dist: psutil>=5.9; extra == "test"
Requires-Dist: jsonschema<5,>=4.26; extra == "test"
Requires-Dist: PyYAML>=6.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=6.2; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
Requires-Dist: coverage>=7.9; extra == "dev"
Requires-Dist: psutil>=5.9; extra == "dev"
Requires-Dist: h5py>=3.10; extra == "dev"
Requires-Dist: jsonschema<5,>=4.26; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.16; extra == "dev"
Requires-Dist: hypothesis>=6.135; extra == "dev"
Requires-Dist: PyYAML>=6.0; extra == "dev"
Provides-Extra: large
Requires-Dist: h5py>=3.10; extra == "large"
Requires-Dist: mpi4py>=3.1; extra == "large"
Requires-Dist: petsc4py>=3.20; extra == "large"
Provides-Extra: hpc
Requires-Dist: mpi4py>=3.1; extra == "hpc"
Requires-Dist: petsc4py>=3.20; extra == "hpc"
Requires-Dist: slepc4py>=3.20; extra == "hpc"
Provides-Extra: docs
Requires-Dist: gmsh==4.15.2; extra == "docs"
Requires-Dist: reportlab==4.4.9; extra == "docs"
Requires-Dist: svglib==2.0.2; extra == "docs"
Requires-Dist: pypdf==6.10.0; extra == "docs"
Requires-Dist: platformdirs==4.9.4; extra == "docs"
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
Provides-Extra: mesh
Requires-Dist: gmsh==4.15.2; extra == "mesh"
Dynamic: license-file

# QF Solver

[![Python](https://img.shields.io/pypi/pyversions/qf-solver.svg)](https://pypi.org/project/qf-solver/)
[![PyPI](https://img.shields.io/pypi/v/qf-solver.svg)](https://pypi.org/project/qf-solver/)
[![License](https://img.shields.io/github/license/emptiesvoid-cloud/QF_solver.svg)](https://github.com/emptiesvoid-cloud/QF_solver/blob/main/LICENSE)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-2f80ed.svg)](https://emptiesvoid-cloud.github.io/QF_solver/)
[![CI](https://github.com/emptiesvoid-cloud/QF_solver/actions/workflows/quality.yml/badge.svg)](https://github.com/emptiesvoid-cloud/QF_solver/actions/workflows/quality.yml)

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?](README.md#why-qf-solver) ·
[Intended use](README.md#intended-use) ·
[Installation](README.md#installation) · [Quick start](README.md#quick-start) ·
[Main capabilities](README.md#main-capabilities) ·
[Verification](README.md#verification-and-maturity) ·
[Performance](README.md#performance-context) · [Limitations](README.md#limitations) ·
[Documentation](README.md#documentation) ·
[Contributing](README.md#contributing-citation-and-license)

## 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](https://emptiesvoid-cloud.github.io/QF_solver/) |

Release availability is authoritative on [PyPI](https://pypi.org/project/qf-solver/)
and [GitHub Releases](https://github.com/emptiesvoid-cloud/QF_solver/releases).
This page describes the `0.2.8` release line and does not make a transient
publication-state claim. Citation metadata, including any DOI if one is
assigned, is authoritative in [`CITATION.cff`](https://github.com/emptiesvoid-cloud/QF_solver/blob/main/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:

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

To install a repository checkout (for example, the pre-publication branch
during development):

```bash
git clone --branch 0.2.8-pre-publication 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 when one is published. Optional
development and integration extras are described in the
[installation guide](https://emptiesvoid-cloud.github.io/QF_solver/getting-started/installation/).
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:

```bash
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](https://emptiesvoid-cloud.github.io/QF_solver/getting-started/quickstart/)
for the complete workflow.

### Python

Use the public `qf_solver` namespace:

```python
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](https://emptiesvoid-cloud.github.io/QF_solver/reference/api_stability/).

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](https://emptiesvoid-cloud.github.io/QF_solver/capabilities/)
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](https://github.com/emptiesvoid-cloud/QF_solver/blob/b706795a8d7d2d8e64df4ec669e343ef1a666ead/qualification/0_2_8/consolidated_registry.json)
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 exact
`0.2.8` candidate commit; 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](https://emptiesvoid-cloud.github.io/QF_solver/verification/evidence-and-maturity/)
and the [0.2.8 verification summary pinned to the candidate commit](https://github.com/emptiesvoid-cloud/QF_solver/tree/b706795a8d7d2d8e64df4ec669e343ef1a666ead/docs/verification/0_2_8/).

## 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](https://emptiesvoid-cloud.github.io/QF_solver/etat/limites/)
and [solver/backend notes](https://emptiesvoid-cloud.github.io/QF_solver/solveurs/).

## Documentation

- [Getting started](https://emptiesvoid-cloud.github.io/QF_solver/getting-started/quickstart/)
- [Capability index](https://emptiesvoid-cloud.github.io/QF_solver/capabilities/)
- [Elements](https://emptiesvoid-cloud.github.io/QF_solver/elements/)
- [Analyses](https://emptiesvoid-cloud.github.io/QF_solver/analyses/)
- [What's New in 0.2.8](https://emptiesvoid-cloud.github.io/QF_solver/whats-new/0.2.8/)
- [Benchmarks](https://emptiesvoid-cloud.github.io/QF_solver/benchmarks/)
- [V&V and maturity](https://emptiesvoid-cloud.github.io/QF_solver/verification/evidence-and-maturity/)
- [API stability](https://emptiesvoid-cloud.github.io/QF_solver/reference/api_stability/)
- [Historical 0.2.7 verification](https://emptiesvoid-cloud.github.io/QF_solver/verification/0_2_7/)
- [Detailed changelog](https://github.com/emptiesvoid-cloud/QF_solver/blob/main/CHANGELOG.md)

## Contributing, citation and license

Development setup and quality checks are described in
[CONTRIBUTING.md](https://github.com/emptiesvoid-cloud/QF_solver/blob/main/CONTRIBUTING.md).
QF Solver is distributed under the
[Apache License 2.0](https://github.com/emptiesvoid-cloud/QF_solver/blob/main/LICENSE);
documentation and original examples are under
[CC BY 4.0](https://github.com/emptiesvoid-cloud/QF_solver/blob/main/LICENSE-DOCS).
Third-party terms are listed in
[THIRD_PARTY_LICENSES.md](https://github.com/emptiesvoid-cloud/QF_solver/blob/main/THIRD_PARTY_LICENSES.md).
For citation metadata, see
the [CITATION.cff file](https://github.com/emptiesvoid-cloud/QF_solver/blob/main/CITATION.cff).

No claim of certification or universal physical validation is made.
