# Migration Guide: v0.1.3 to v1.0+

The release of *pyforce* v1.0.0 marks a major architectural change. This guide explains the differences between the original implementation (v0.1.3) described in the JOSS paper and the current stable version.

## Key Differences

| Feature | v0.1.3 (JOSS Reference) | v1.0+ (Current) |
| :--- | :--- | :--- |
| **Backend** | `dolfinx` (FEniCSx) | `pyvista` + `numpy` |
| **Mesh Support** | `.xdmf`, `.h5` | VTK formats (`.vtu`, `.vtk`, etc.) |
| **Dependencies** | Heavy (MPI, PETSc, complex installation) | Light (`numpy`, `scipy`, `pyvista`) |
| **Solver Support** | Tightly coupled with FEniCSx | Solver-agnostic (OpenFOAM, Ansys, MOOSE) |

## Moving to v1.0

### 1. Mesh Handling and Integral Calculations
In v0.1.3, meshes were handled via `dolfinx.mesh`. In v1.0+, we use `pyvista`.

**Old (v0.1.3):**
```python
import dolfinx
from mpi4py import MPI
domain = dolfinx.mesh.create_unit_square(MPI.COMM_WORLD, 10, 10)
```
The integral calculations were performed using `dolfinx.fem.assemble_scalar` and similar functions:

$$ \int_{\Omega} f(\mathbf{x}) \, d\Omega \approx \sum_i f(\mathbf{x}_i) w_i $$

where \(w_i\) are the quadrature weights.

**New (v1.0+):**
```python
import pyvista as pv
domain = pv.Plane(i_resolution=10, j_resolution=10)
# Or loading from file
domain = pv.read("mesh.vtk")
```
Integral calculations can be done using `pyvista`'s built-in methods or by converting data to `numpy` arrays for custom computations

$$ \int_{\Omega} f(\mathbf{x}) \, d\Omega \approx \sum_i f(\mathbf{x}_i) \Omega_i $$

where $\Omega_i$ are the cell volumes/areas.

> **Note**: the previous implementations was actually more accurate, due to high-order quadrature rules available in `dolfinx`. The new version is based on rectanglular integration rules (extended to 2D/3D), which may be less accurate for complex geometries: this choice has been made to prioritize generality and ease of use.



### 2. Snapshot Management
The way data is stored has changed.

- v.0.1.3 used `dolfinx` functions and store them into lists or arrays (then mapped to function spaces, when needed).
- v1.0+ Snapshots are standard `numpy.ndarray` vectors, making it easier to integrate with other machine learning tools (like `scikit-learn` or `pytorch`).

### 3. Workflow changes

The new version is more informatically consistent, with a strong modular approach: each method (either in the offline or online phase) has its own father class, and the user can easily extend the package by adding new methods.

### Why the change?

The shift to `pyvista` allows pyforce to be:

1. Easier to install and use, without the heavy dependencies of `dolfinx`.
2. Solver Independent: You can now use pyforce to reduce models generated by any software that exports to standard formats (OpenFOAM, Ansys, etc.), not just map them to FEniCSx environments.