Skip to content

Models

A FEM model combines a mesh (nodes and elements) with a material to form a solvable finite-element problem. All models share the same workflow:

  1. Create the model from nodes, elements, and a material.
  2. Apply loads and boundary conditions by setting entries of the model attributes: forces and displacements for mechanics models (Truss, Planar, Shell, Solid), or heat_flux and temperatures for thermal models (PlanarHeat, SolidHeat). Prescribed values are activated by setting the corresponding entries of the boolean mask constraints to True.
  3. Solve with solve(), which returns the nodal solution, the internal nodal forces, and the flux, gradient, and material state at the elements.
  4. Postprocess the resulting tensors, e.g. with plot().

See Getting Started for a worked example.

All models inherit their construction and solution interface from the abstract base class FEM:

FEM

Bases: ABC

Abstract base class for all finite-element models.

A model is defined by nodal coordinates, an element connectivity, and a material. Loads and boundary conditions are set through attributes of the concrete model classes, and the quasi-static solution is computed with solve().

Attributes:

  • nodes –

    Nodal coordinates with shape [n_nod, n_dim].

  • elements –

    Element connectivity with shape [n_elem, nodes_per_element].

  • material (Material | None) –

    Vectorized material model (or None for laminate shells).

  • constraints (Tensor) –

    Boolean mask of constrained degrees of freedom with shape [n_nod, n_dof_per_node].

  • n_nod –

    Number of nodes.

  • n_elem –

    Number of elements.

  • n_dofs –

    Total number of degrees of freedom.

__init__(nodes, elements, material)

Initialize a finite-element model.

Parameters:

  • nodes (Tensor) –

    Nodal coordinates with shape [n_nod, n_dim].

  • elements (Tensor) –

    Connectivity with shape [n_elem, n_nodes_per_element].

  • material (Material | None) –

    Material model. If not vectorized, it is vectorized over elements during initialization. May be None for shells that use a laminate section instead.

solve(increments=None, max_iter=10, rtol=1e-08, atol=1e-06, stol=1e-10, cutback_factor=0.5, growth_factor=1.1, max_cutbacks=10, verbose=False, method=None, device=None, return_intermediate=False, aggregate_integration_points=True, use_cached_solve=False, nlgeom=False, alpha=0.0, differentiable_parameters=None)

Solve the quasi-static finite-element problem by load increments.

Parameters:

  • increments (Tensor | None, default: None ) –

    Monotonic load scale factors, typically [0, 1]. Results are always returned at exactly these values. If a Newton solve does not converge, the increment is subdivided internally and retried, and the substep is grown again after each success.

  • max_iter (int, default: 10 ) –

    Maximum Newton iterations before an increment is cut back.

  • rtol (float, default: 1e-08 ) –

    Relative residual tolerance for Newton convergence.

  • atol (float, default: 1e-06 ) –

    Absolute residual tolerance for Newton convergence.

  • stol (float, default: 1e-10 ) –

    Tolerance used by iterative linear solvers.

  • cutback_factor (float, default: 0.5 ) –

    Factor applied to the substep size after a Newton solve failed to converge.

  • growth_factor (float, default: 1.1 ) –

    Factor applied to the substep size after a Newton solve converged, capped at the requested increment.

  • max_cutbacks (int, default: 10 ) –

    Number of successive cutbacks accepted within an increment before the solve is given up.

  • verbose (bool, default: False ) –

    If True, reports the solver configuration and a table of per-increment progress, updated in place inside notebooks.

  • method (Literal['spsolve', 'minres', 'cg', 'pardiso'] | None, default: None ) –

    Linear solver backend name.

  • device (str | None, default: None ) –

    Optional device hint for the linear solver backend.

  • return_intermediate (bool, default: False ) –

    If True, returns values for all increments.

  • aggregate_integration_points (bool, default: True ) –

    If True, averages flux, gradient, and state over integration points.

  • use_cached_solve (bool, default: False ) –

    If True, reuses cached linear solver data.

  • nlgeom (bool, default: False ) –

    If True, includes geometric nonlinearity.

  • alpha (float, default: 0.0 ) –

    Damping factor for viscous stabilization. Dissipated energy is accumulated in self.stabilization_energy.

  • differentiable_parameters (Tensor | Iterable[Tensor] | None, default: None ) –

    Explicit parameter(s) to differentiate through implicit Newton/sparse solves. Accepts either a single tensor or an iterable of tensors.

Returns:

  • tuple[Tensor, Tensor, Tensor, Tensor, Tensor] –

    Tuple of displacement, internal force, flux, gradient, and material state. If return_intermediate is True, each tensor includes an increment dimension as the leading axis.