SfePy Documentation

SfePy (Simple finite elements in Python) is a software package designed for solving systems of coupled partial differential equations (PDEs) using the finite element method (FEM) in 1D, 2D, and 3D.

It serves two primary purposes:

1. Black-box PDE solver: A standalone tool for solving mathematical models.
2. Python package: A library that can be imported and used to build custom scientific applications.

Key technical characteristics:

• Implementation: Primarily written in Python, with performance-critical routines implemented in C and wrapped via Cython.
• Dependencies: Relies on NumPy and SciPy for scientific computations.
• License: Free software released under the New BSD License.
• Platform Support: Multi-platform (Linux, Mac OS X, and Windows).

For complex, real-world physics simulations, SfePy hosts a collection of advanced example applications. These cover topics such as:

• Peristaltic flows and piezoelectric porous media
• Deformation of foam-reinforced shell beams
• Two-scale and multiscale numerical simulations (e.g., fluid-saturated porous structures, Biot-Darcy-Brinkman models)
• Vibro-acoustic transmission
• Viscous flow in deformable double porous media
• Biological models (e.g., Fish heart model)
• Phononic materials

Note: Older examples (pre-2020) may not reflect the current state of the SfePy API or best practices. It is recommended to prioritize newer examples for current development.

The typical process for solving a problem using SfePy follows these four stages:

1. Meshing: Create a geometric model and discretize it into a mesh (e.g., using Gmsh).
2. Problem Description: Draft a Python problem definition file that specifies the mesh, material properties, boundary conditions, and equations.
3. Running SfePy: Execute the problem description file using the sfepy-run command to solve the equations.
4. Post-processing: Visualize the results (e.g., displacements, stresses) using tools like sfepy-view or external VTK viewers.

In SfePy, Fields define the discrete approximation spaces (e.g., linear finite elements) on a region. Variables are then mapped to these fields.

To solve a PDE in weak form, you must define both an unknown field (the state variable) and a test field (the virtual variable). The test variable must explicitly link to its corresponding unknown variable using the 'dual' parameter.

Example mapping:

• Unknown variable 't' is associated with field 'temperature'.
• Test variable 's' is associated with field 'temperature' and its dual is 't'.

fields = {
    'temperature': ('real', 1, 'Omega', 1)
}

variables = {
    't': ('unknown field', 'temperature', 0),
    's': ('test field', 'temperature', 't'),
}

When using SfePy to solve problems with EBCs, the internal evaluation of the residual and tangent matrix follows a specific lifecycle to maintain the reduction:

1. Reconstruction: The full DOF vector $u$ is reconstructed from the current reduced vector $u_r$.
2. Local Evaluation: Local element contributions are calculated using the reconstructed $u$.
3. Reduced Assembly: Local contributions are assembled into the reduced residual $f_r$ or tangent matrix $K_r$. Crucially, any values corresponding to fixed DOF positions are thrown away during this step.
4. Linear Solve: The reduced system $K_r \Delta u_r = r_r$ is solved for the increment $\Delta u_r$.
5. Update: The reduced solution is updated: $u_r \leftarrow u_r - \Delta u_r$.
6. Final Reconstruction: Once the Newton loop terminates, the final full vector $u$ is reconstructed from the final $u_r$.

A problem description file (or input file) is a regular Python module that defines a PDE problem. Because it is a standard Python file, it can be imported normally and does not require a special parser.

To define a problem, you use specific Python variables (typically of type dict) with reserved names. These keywords allow you to define:

• Equations
• Variables
• Finite element approximations
• Solvers
• Solution domain and subdomains