Equation systems define the algebraic systems that implicit solvers work on. They are created under the EquationSystems section in input files and are typically consumed by ImplicitUpdate or by nonlinear solvers directly. Equation systems are tightly coupled with solvers because the solver queries the system for the assembled operator and right-hand side.

Base class

All equation systems derive from EquationSystem, which is a manufacturable object with its options section set to EquationSystems. The base class provides the to interface for moving internal data to a different device or dtype.

Linear system interface

LinearSystem defines the interface for a system of the form

\[ A u = b, \]

with the following roles:

Unknowns \(u\): set with set_u and retrieved with u.
Given variables \(g\): set with set_g and retrieved with g.
Operator \(A\): assembled with A() or the combined A_and_* methods.
Right-hand side \(b\): assembled with b() or the combined A_and_* methods.
Auxiliary matrix \(B = \partial r / \partial g\): assembled by A_and_B or A_and_B_and_b when available.

The assembled objects are stored in SparseTensorList, which is a vector of tensors where missing entries represent zeros in a sparse representation. The order of entries is controlled by the ID-to-variable maps returned by umap, gmap, and bmap, with associated layouts (ulayout, glayout, blayout) and optional intermediate layouts.

LinearSystem tracks whether \(A\), \(B\), and \(b\) are up-to-date. By default, g_changed invalidates all cached assemblies, while u_changed is a no-op for linear systems. Derived classes can override these hooks and the assemble method to control caching and assembly behavior.

Nonlinear system

NonlinearSystem represents a nonlinear system

\[ r(u; g) = 0. \]

Its linearization is expressed as

\[ \frac{\partial r}{\partial u} \Delta u = -r, \]

so the assembled matrices are interpreted as \(A := \partial r / \partial u\) and \(b := -r\). The auxiliary matrix \(B := \partial r / \partial g\) is also available when requested. In a nonlinear system, u_changed invalidates \(A\), \(B\), and \(b\) because the linearization depends on the current unknowns.

Model-based nonlinear system

ModelNonlinearSystem is the default implementation and is registered under the alias NonlinearSystem. It wraps a Model and uses the model's variables to define the system:

Unknowns \(u\) are the input variables on the state sub-axis.
Given variables \(g\) are all other input variables.
Residuals \(r\) are the output variables on the residual sub-axis.
\(A\) and \(B\) are assembled from the model's derivatives of residual with respect to state and non-state inputs.

The state and residual sub-axes must be conformal so that the Jacobian \(A\) is square. This is the same requirement imposed by solvers (see Solver).

In an input file, a model-based nonlinear system looks like:

[EquationSystems]
  [eq_sys]
    type = NonlinearSystem
    model = 'system'
  []
[]

This system can then be referenced by ImplicitUpdate or passed directly to a nonlinear solver.

Table of Contents

Base class

Linear system interface

Nonlinear system

Model-based nonlinear system