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):

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+):

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:

Easier to install and use, without the heavy dependencies of dolfinx.
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.