fipy.terms.residualTerm¶

Classes

ResidualTerm(equation[, underRelaxation])

The ResidualTerm is a special form of explicit SourceTerm that adds the residual of one equation to another equation.

class fipy.terms.residualTerm.ResidualTerm(equation, underRelaxation=1.0)¶

Bases: _ExplicitSourceTerm

The ResidualTerm is a special form of explicit SourceTerm that adds the residual of one equation to another equation. Useful for Newton’s method.

Parameters:

coeff (float or CellVariable) – Coefficient of source (default: 0)
var (CellVariable) – Variable \(\phi\) that SourceTerm is implicit in.

property RHSvector¶: Return the RHS vector calculated in solve() or sweep(). The cacheRHSvector() method should be called before solve() or sweep() to cache the vector.

__eq__(other)¶: Return self==value.

__hash__()¶: Return hash(self).

__mul__(other)¶

Multiply a term

>>> 2. * __NonDiffusionTerm(coeff=0.5)
__NonDiffusionTerm(coeff=1.0)

Test for ticket:291.

>>> from fipy import PowerLawConvectionTerm
>>> PowerLawConvectionTerm(coeff=[[1], [0]]) * 1.0
PowerLawConvectionTerm(coeff=array([[ 1.],
       [ 0.]]))

__neg__()¶

Negate a Term.

>>> -__NonDiffusionTerm(coeff=1.)
__NonDiffusionTerm(coeff=-1.0)

__repr__()¶

The representation of a Term object is given by,

>>> print(__UnaryTerm(123.456))
__UnaryTerm(coeff=123.456)

__rmul__(other)¶

Multiply a term

>>> 2. * __NonDiffusionTerm(coeff=0.5)
__NonDiffusionTerm(coeff=1.0)

Test for ticket:291.

>>> from fipy import PowerLawConvectionTerm
>>> PowerLawConvectionTerm(coeff=[[1], [0]]) * 1.0
PowerLawConvectionTerm(coeff=array([[ 1.],
       [ 0.]]))

cacheMatrix()¶: Informs solve() and sweep() to cache their matrix so that matrix can return the matrix.

cacheRHSvector()¶: Informs solve() and sweep() to cache their right hand side vector so that getRHSvector() can return it.

justErrorVector(var=None, solver=None, boundaryConditions=(), dt=1.0, underRelaxation=None, residualFn=None)¶

Builds the Term’s linear system once.

This method also recalculates and returns the error as well as applying under-relaxation.

justErrorVector returns the overlapping local value in parallel (not the non-overlapping value).

>>> from fipy.solvers import DummySolver
>>> from fipy import *
>>> m = Grid1D(nx=10)
>>> v = CellVariable(mesh=m)
>>> len(DiffusionTerm().justErrorVector(v, solver=DummySolver())) == m.numberOfCells
True

Parameters:

var (CellVariable) – Variable to be solved for. Provides the initial condition, the old value and holds the solution on completion.
solver (Solver) – Iterative solver to be used to solve the linear system of equations. The default sovler depends on the solver package selected.
boundaryConditions (tuple of BoundaryCondition) –
dt (float) – Timestep size.
underRelaxation (float) – Usually a value between 0 and 1 or None in the case of no under-relaxation
residualFn (function) – Takes var, matrix, and RHSvector arguments, used to customize the residual calculation.

Returns:

error – The residual vector \(\vec{e}=\mathsf{L}\vec{x}_\text{old} - \vec{b}\)

Return type:

CellVariable

justResidualVector(var=None, solver=None, boundaryConditions=(), dt=None, underRelaxation=None, residualFn=None)¶

Builds the Term’s linear system once.

This method also recalculates and returns the residual as well as applying under-relaxation.

justResidualVector returns the overlapping local value in parallel (not the non-overlapping value).

>>> from fipy import *
>>> m = Grid1D(nx=10)
>>> v = CellVariable(mesh=m)
>>> len(numerix.asarray(DiffusionTerm().justResidualVector(v))) == m.numberOfCells
True

Parameters:

var (CellVariable) – Variable to be solved for. Provides the initial condition, the old value and holds the solution on completion.
solver (Solver) – Iterative solver to be used to solve the linear system of equations. The default sovler depends on the solver package selected.
boundaryConditions (tuple of BoundaryCondition) –
dt (float) – Timestep size.
underRelaxation (float) – Usually a value between 0 and 1 or None in the case of no under-relaxation
residualFn (function) – Takes var, matrix, and RHSvector arguments, used to customize the residual calculation.

Returns:

residual – The residual vector \(\vec{r}=\mathsf{L}\vec{x} - \vec{b}\)

Return type:

CellVariable

property matrix¶: Return the matrix calculated in solve() or sweep(). The cacheMatrix() method should be called before solve() or sweep() to cache the matrix.

residualVectorAndNorm(var=None, solver=None, boundaryConditions=(), dt=None, underRelaxation=None, residualFn=None)¶

Builds the Term’s linear system once.

This method also recalculates and returns the residual as well as applying under-relaxation.

Parameters:

var (CellVariable) – Variable to be solved for. Provides the initial condition, the old value and holds the solution on completion.
solver (Solver) – Iterative solver to be used to solve the linear system of equations. The default sovler depends on the solver package selected.
boundaryConditions (tuple of BoundaryCondition) –
dt (float) – Timestep size.
underRelaxation (float) – Usually a value between 0 and 1 or None in the case of no under-relaxation
residualFn (function) – Takes var, matrix, and RHSvector arguments, used to customize the residual calculation.

Returns:

residual (CellVariable) – The residual vector \(\vec{r}=\mathsf{L}\vec{x} - \vec{b}\)
norm (float) – The L2 norm of residual, \(\|\vec{r}\|_2\)

solve(var=None, solver=None, boundaryConditions=(), dt=None)¶

Builds and solves the Term’s linear system once. This method does not return the residual. It should be used when the residual is not required.

Parameters:

var (CellVariable) – Variable to be solved for. Provides the initial condition, the old value and holds the solution on completion.
solver (Solver) – Iterative solver to be used to solve the linear system of equations. The default sovler depends on the solver package selected.
boundaryConditions (tuple of BoundaryCondition) –
dt (float) – Timestep size.

sweep(var=None, solver=None, boundaryConditions=(), dt=None, underRelaxation=None, residualFn=None, cacheResidual=False, cacheError=False)¶

Builds and solves the Term’s linear system once. This method also recalculates and returns the residual as well as applying under-relaxation.

Parameters:

var (CellVariable) – Variable to be solved for. Provides the initial condition, the old value and holds the solution on completion.
solver (Solver) – Iterative solver to be used to solve the linear system of equations. The default sovler depends on the solver package selected.
boundaryConditions (tuple of BoundaryCondition) –
dt (float) – Timestep size.
underRelaxation (float) – Usually a value between 0 and 1 or None in the case of no under-relaxation
residualFn (function) – Takes var, matrix, and RHSvector arguments, used to customize the residual calculation.
cacheResidual (bool) – If True, calculate and store the residual vector \(\vec{r}=\mathsf{L}\vec{x} - \vec{b}\) in the residualVector member of Term
cacheError (bool) – If True, use the residual vector \(\vec{r}\) to solve \(\mathsf{L}\vec{e}=\vec{r}\) for the error vector \(\vec{e}\) and store it in the errorVector member of Term

Returns:

residual – The residual vector \(\vec{r}=\mathsf{L}\vec{x} - \vec{b}\)

Return type:

CellVariable

Last updated on Sep 16, 2025. Created using Sphinx 7.1.2.