# proteus.LinearSolvers module¶

A hierarchy of classes for linear algebraic system solvers.

class proteus.LinearSolvers.LinearSolver(L, rtol_r=0.0001, atol_r=1e-16, rtol_du=0.0001, atol_du=1e-16, maxIts=100, norm=<function l2Norm>, convergenceTest='r', computeRates=True, printInfo=False)[source]

The base class for linear solvers.

L
: proteus.superluWrappers.SparseMatrix
This is the system matrix.
setResTol(rtol, atol)[source]
prepare(b=None)[source]
solve(u, r=None, b=None, par_u=None, par_b=None)[source]
calculateEigenvalues()[source]
computeResidual(u, r, b, initialGuessIsZero=False)[source]
solveInitialize(u, r, b, initialGuessIsZero=True)[source]
computeConvergenceRates()[source]
converged(r)[source]
failed()[source]
computeAverages()[source]
info()[source]
printPerformance()[source]
setUp(pc)[source]
apply(pc, x, y)[source]
class proteus.LinearSolvers.LU(L, computeEigenvalues=False, computeEigenvectors=None)[source]

A wrapper for pysparse’s wrapper for superlu.

prepare(b=None)[source]
solve(u, r=None, b=None, par_u=None, par_b=None, initialGuessIsZero=False)[source]
calculateEigenvalues()[source]
class proteus.LinearSolvers.PETSc(L, par_L, prefix=None)[source]
prepare(b=None)[source]
solve(u, r=None, b=None, par_u=None, par_b=None, initialGuessIsZero=False)[source]
useTrueResidualTest(par_u)[source]
printPerformance()[source]
class proteus.LinearSolvers.KSP_petsc4py(L, par_L, rtol_r=0.0001, atol_r=1e-16, maxIts=100, norm=<function l2Norm>, convergenceTest='r', computeRates=True, printInfo=False, prefix=None, Preconditioner=None, connectionList=None, linearSolverLocalBlockSize=1, bdyNullSpace=False, preconditionerOptions=None)[source]

A class that interfaces Proteus with PETSc KSP.

Initialize a petsc4py KSP object.

Parameters: L – par_L – rtol_r (float) – atol_r (float) – maxIts (int) – norm (norm type) – convergenceTest – computeRates (bool) – printInfo (bool) – prefix (bool) – Preconditioner – connectionList – linearSolverLocalBlockSize (int) – bdyNullSpace (bool) – preconditionerOptions (tuple) – A list of optional preconditioner settings.
setResTol(rtol, atol)[source]

Set the ksp object’s residual and maximum interations.

prepare(b=None)[source]
solve(u, r=None, b=None, par_u=None, par_b=None, initialGuessIsZero=True)[source]
converged(r)[source]

decide on convention to match norms, convergence criteria

failed()[source]
info()[source]
class proteus.LinearSolvers.SchurOperatorConstructor(linear_smoother, pde_type='general_saddle_point')[source]

Generate matrices for use in Schur complement preconditioner operators.

Initialize a Schur Operator constructor.

Parameters: linear_smoother (class) – Provides the data about the problem. pde_type (str) – Currently supports Stokes and navierStokes
initializeTwoPhaseCp_rho()[source]

Initialize a two phase scaled advection operator Cp.

Returns: two_phase_Cp_rho matrix
initializeTwoPhaseInvScaledAp()[source]

Initialize a two phase scaled laplace operator Ap.

Returns: two_phase_Ap_inv matrix
initializeTwoPhaseQp_rho()[source]

Initialize a two phase scaled laplace operator Ap.

Returns: two_phase_Ap_inv matrix
initializeTwoPhaseInvScaledQp()[source]

Initialize a two phase scaled laplace operator Ap.

Returns: two_phase_Ap_inv matrix
initializeQ()[source]

Initialize a mass matrix Q.

Returns: Q – The mass matrix. matrix
updateQ(output_matrix=False)[source]

Update the mass matrix operator.

Parameters: output_matrix (bool) – Save updated mass operator.
updateNp_rho(density_scaling=True, output_matrix=False)[source]

Update the two-phase advection operator.

Parameters: density_scaling (bool) – Indicates whether advection terms should be scaled with the density (True) or 1 (False) output_matrix (bool) – Save updated advection operator.
updateInvScaledAp(output_matrix=False)[source]

Update the two-phase laplace operator.

Parameters: output_matrix (bool) – Save updated laplace operator.
updateTwoPhaseQp_rho(density_scaling=True, lumped=True, output_matrix=False)[source]

Update the two-phase inverse viscosity scaled mass matrix.

Parameters: density (bool) – Indicates whether the density mass matrix should be scaled with rho (True) or 1 (False). lumped (bool) – Flag indicating whether the mass operator should be calculated as a lumped matrix (True) or as a full matrix (False). output_matrix (bool) – Save updated laplace operator.
updateTwoPhaseInvScaledQp_visc(numerical_viscosity=True, lumped=True, output_matrix=False)[source]

Update the two-phase inverse viscosity scaled mass matrix.

Parameters: numerical_viscosity (bool) – Indicates whether the numerical viscosity should be included with the mass operator (True to include, False to exclude) lumped (bool) – Flag indicating whether the mass operator should be calculated as a lumped matrix (True) or as a full matrix (False). output_matrix (bool) – Save updated mass operator.
getQv(output_matrix=False, recalculate=False)[source]

Return the pressure mass matrix Qp.

Parameters: output_matrix (bool) – Determines whether matrix should be exported. recalculate (bool) – Flag indicating whether matrix should be rebuilt every iteration Qp – The pressure mass matrix. matrix
getQp(output_matrix=False, recalculate=False)[source]

Return the pressure mass matrix Qp.

Parameters: output_matrix (bool) – Determines whether matrix should be exported. recalculate (bool) – Flag indicating whether matrix should be rebuilt every iteration Qp – The pressure mass matrix. matrix
class proteus.LinearSolvers.KSP_Preconditioner[source]

Base class for PETSCc KSP precondtioners.

setup(global_ksp=None)[source]
class proteus.LinearSolvers.petsc_ASM(L, prefix=None)[source]

ASM PETSc preconditioner class.

This class provides an ASM preconditioners for PETSc4py KSP objects.

Initializes the ASMpreconditioner for use with PETSc.

Parameters: L (the global system matrix.) – prefix (str) – Prefix handle for PETSc options.
setUp(global_ksp=None)[source]
class proteus.LinearSolvers.petsc_LU(L, prefix=None)[source]

LU PETSc preconditioner class.

This class provides an LU preconditioner for PETSc4py KSP objects. Provided the LU decomposition is successful, the KSP iterative will converge in a single step.

Initializes the LU preconditioner for use with PETSc.

Parameters: L (the global system matrix.) – prefix (str) – Prefix handle for PETSc options.
setUp(global_ksp=None)[source]
class proteus.LinearSolvers.SchurPrecon(L, prefix=None, bdyNullSpace=False)[source]

Base class for PETSc Schur complement preconditioners.

Initializes the Schur complement preconditioner for use with PETSc.

This class creates a KSP PETSc solver object and initializes flags the pressure and velocity unknowns for a general saddle point problem.

Parameters: L (provides the definition of the problem.) – prefix (str) – Prefix identifier for command line PETSc options. bdyNullSpace (bool) – Flag indicating whether boundary creates nullspace.
setUp(global_ksp)[source]

Set up the NavierStokesSchur preconditioner.

Nothing needs to be done here for a generic NSE preconditioner. Preconditioner arguments can be set with PETSc command line.

class proteus.LinearSolvers.Schur_Sp(L, prefix, bdyNullSpace=False, constNullSpace=True)[source]

This class implements the SIMPLE approximation to the Schur complement proposed in 2009 by Rehman, Vuik and Segal.

Parameters: L (petsc4py matrix) – prefix (str) – bdyNullSpace (bool) – Indicates the models boundary conditions create a global null space. (see notes) constNullSpace (bool) – Indicates the operator Sp has a constant null space. (see Notes)

Notes

This Schur complement approximation is also avaliable in PETSc by the name selfp.

The bdyNullSpace flag is used to indicate that the model has a global null space because it only uses Dirichlet boundary conditions. In contrast, the constNullSpace flag refers to the Sp operator which typically has a constant null space because of its construction. This flag will typically always be be set to True. See the Sp_shell class for more details.

setUp(global_ksp)[source]
class proteus.LinearSolvers.Schur_Qp(L, prefix=None, bdyNullSpace=False)[source]

A Navier-Stokes (or Stokes) preconditioner which uses the viscosity scaled pressure mass matrix.

Initializes the pressure mass matrix class.

Parameters: L (petsc4py matrix) – Defines the problem’s operator.
setUp(global_ksp)[source]

Attaches the pressure mass matrix to PETSc KSP preconditioner.

Parameters: global_ksp (PETSc KSP object) –
class proteus.LinearSolvers.NavierStokesSchur(L, prefix=None, bdyNullSpace=False)[source]

Schur complement preconditioners for Navier-Stokes problems.

This class is derived from SchurPrecond and serves as the base class for all NavierStokes preconditioners which use the Schur complement method.

class proteus.LinearSolvers.NavierStokes_TwoPhasePCD(L, prefix=None, bdyNullSpace=False, density_scaling=True, numerical_viscosity=True, lumped=True, num_chebyshev_its=0)[source]

Two-phase PCD Schur complement approximation class. Details of this operator are in the forthcoming paper ‘Preconditioners for Two-Phase Incompressible Navier-Stokes Flow’, Bootland et. al. 2017.

Since the two-phase Navier-Stokes problem used in the MPRANS module of Proteus has some additional features not include in the above paper, a few additional flags and options are avaliable.

• density scaling - This flag allows the user to specify whether the advection and mass terms in the second term of the PCD operator should use the actual density or the scale with the number one.
• numerical viscosity - This flag specifies whether the additional viscosity introduced from shock capturing stabilization should be included as part of the viscosity coefficient.
• mass form - This flag allows the user to specify what form the mass matrix takes, lumped (True) or full (False).

Initialize the two-phase PCD preconditioning class.

Parameters: L (petsc4py Matrix) – Defines the problem’s operator. prefix (str) – String allowing PETSc4py options. bdyNullSpace (bool) – Indicates whether there is a global null space. density_scaling (bool) – Indicates whether mass and advection terms should be scaled with the density (True) or 1 (False). numerical_viscosity (bool) – Indicates whether the viscosity used to calculate the inverse scaled mass matrix should include numerical viscosity (True) or not (False). lumped (bool) – Indicates whether the viscosity and density mass matrices should be lumped (True) or full (False). num_chebyshev_its (int) – This flag allows the user to apply the mass matrices with a chebyshev semi-iteration. 0 indicates the semi- iteration should not be used, where as a number 1,2,... indicates the number of iterations the method should take.
setUp(global_ksp)[source]
class proteus.LinearSolvers.Schur_LSC(L, prefix=None, bdyNullSpace=False)[source]

The Least-Squares Communtator preconditioner for saddle point problems.

setUp(global_ksp)[source]
class proteus.LinearSolvers.NavierStokes3D(L, prefix=None)[source]
setUp(global_ksp=None)[source]
proteus.LinearSolvers.SimpleNavierStokes3D[source]

alias of NavierStokes3D

class proteus.LinearSolvers.NavierStokes2D(L, prefix=None)[source]
setUp(global_ksp=None)[source]
proteus.LinearSolvers.SimpleNavierStokes2D[source]

alias of NavierStokes2D

class proteus.LinearSolvers.NavierStokesPressureCorrection(L, prefix=None)[source]
setUp(global_ksp=None)[source]
class proteus.LinearSolvers.SimpleDarcyFC(L)[source]
setUp(global_ksp=None)[source]
class proteus.LinearSolvers.Jacobi(L, weight=1.0, rtol_r=0.0001, atol_r=1e-16, rtol_du=0.0001, atol_du=1e-16, maxIts=100, norm=<function l2Norm>, convergenceTest='r', computeRates=True, printInfo=True)[source]

Damped Jacobi iteration.

prepare(b=None)[source]
solve(u, r=None, b=None, par_u=None, par_b=None, initialGuessIsZero=False)[source]
csmoothers = <module 'proteus.csmoothers' from '/home/cekees/proteus/proteus/csmoothers.so'>[source]
class proteus.LinearSolvers.GaussSeidel(connectionList, L, weight=0.33, sym=False, rtol_r=0.0001, atol_r=1e-16, rtol_du=0.0001, atol_du=1e-16, maxIts=100, norm=<function l2Norm>, convergenceTest='r', computeRates=True, printInfo=True)[source]

Damped Gauss-Seidel.

prepare(b=None)[source]
solve(u, r=None, b=None, par_u=None, par_b=None, initialGuessIsZero=False)[source]
csmoothers = <module 'proteus.csmoothers' from '/home/cekees/proteus/proteus/csmoothers.so'>[source]
class proteus.LinearSolvers.StarILU(connectionList, L, weight=1.0, sym=False, rtol_r=0.0001, atol_r=1e-16, rtol_du=0.0001, atol_du=1e-16, maxIts=100, norm=<function l2Norm>, convergenceTest='r', computeRates=True, printInfo=True)[source]

Alternating Schwarz Method on node stars.

prepare(b=None)[source]
solve(u, r=None, b=None, par_u=None, par_b=None, initialGuessIsZero=False)[source]
csmoothers = <module 'proteus.csmoothers' from '/home/cekees/proteus/proteus/csmoothers.so'>[source]
class proteus.LinearSolvers.StarBILU(connectionList, L, bs=1, weight=1.0, sym=False, rtol_r=0.0001, atol_r=1e-16, rtol_du=0.0001, atol_du=1e-16, maxIts=100, norm=<function l2Norm>, convergenceTest='r', computeRates=True, printInfo=True)[source]

Alternating Schwarz Method on ‘blocks’ consisting of consectutive rows in system for things like dg ...

prepare(b=None)[source]
solve(u, r=None, b=None, par_u=None, par_b=None, initialGuessIsZero=False)[source]
csmoothers = <module 'proteus.csmoothers' from '/home/cekees/proteus/proteus/csmoothers.so'>[source]
class proteus.LinearSolvers.TwoLevel(prolong, restrict, coarseL, preSmoother, postSmoother, coarseSolver, L, prepareCoarse=False, rtol_r=0.0001, atol_r=1e-16, rtol_du=0.0001, atol_du=1e-16, maxIts=100, norm=<function l2Norm>, convergenceTest='r', computeRates=True, printInfo=True)[source]

A generic two-level multiplicative Schwarz solver.

prepare(b=None)[source]
solve(u, r=None, b=None, par_u=None, par_b=None, initialGuessIsZero=False)[source]
class proteus.LinearSolvers.MultilevelLinearSolver(levelLinearSolverList, computeRates=False, printInfo=False)[source]

A generic multilevel solver.

info()[source]
class proteus.LinearSolvers.MGM(prolongList, restrictList, LList, preSmootherList, postSmootherList, coarseSolver, mgItsList=[], printInfo=False, computeRates=False)[source]

A generic multigrid W cycle.

prepare(b=None)[source]
solve(u, r=None, b=None, initialGuessIsZero=False)[source]
class proteus.LinearSolvers.NI(solverList, prolongList, restrictList, maxIts=None, tolList=None, atol=None, computeRates=True, printInfo=False)[source]

A generic nested iteration solver.

setResTol(rtol, atol)[source]
prepare(b=None)[source]
solve(u, r=None, b=None, par_u=None, par_b=None, initialGuessIsZero=False)[source]
solveMultilevel(bList, uList, par_bList=None, par_uList=None, initialGuessIsZero=False)[source]
switchToResidualConvergence(solver, rtol)[source]
revertToFixedIteration(solver)[source]
info()[source]
proteus.LinearSolvers.multilevelLinearSolverChooser(linearOperatorList, par_linearOperatorList, multilevelLinearSolverType=<class proteus.LinearSolvers.NI>, relativeToleranceList=None, absoluteTolerance=1e-08, solverConvergenceTest='r', solverMaxIts=500, printSolverInfo=False, computeSolverRates=False, levelLinearSolverType=<class proteus.LinearSolvers.MGM>, printLevelSolverInfo=False, computeLevelSolverRates=False, smootherType=<class proteus.LinearSolvers.Jacobi>, prolongList=None, restrictList=None, connectivityListList=None, cycles=3, preSmooths=3, postSmooths=3, printSmootherInfo=False, computeSmootherRates=False, smootherConvergenceTest='its', relaxationFactor=None, computeEigenvalues=False, parallelUsesFullOverlap=True, par_duList=None, solver_options_prefix=None, linearSolverLocalBlockSize=1, linearSmootherOptions=())[source]
class proteus.LinearSolvers.StorageSet(initializer=[], shape=(0, ), storageType='d')[source]

Bases: set

allocate(storageDict)[source]
class proteus.LinearSolvers.OperatorConstructor(model)[source]

Base class for operator constructors.

attachMassOperator()[source]

Create the discrete Mass operator.

attachInvScaledMassOperator()[source]

Create discrete InvScaled Mass operator.

attachScaledMassOperator()[source]

Create discrete InvScaled Mass operator.

attachLaplaceOperator()[source]

Create discrete Laplace matrix operator.

attachTPAdvectionOperator()[source]

Create discrete Advection matrix operator.

class proteus.LinearSolvers.OperatorConstructor_rans2p(levelModel)[source]

A class for building common discrete rans2p operators.

LevelModel
: proteus.mprans.RANS2P.LevelModel
Level transport model derived from the rans2p class.
updateTPAdvectionOperator(density_scaling)[source]

Update the discrete two-phase advection operator matrix.

Parameters: density_scaling (bool) – Indicates whether advection terms should be scaled with the density (True) or 1 (False)
updateTPInvScaledLaplaceOperator()[source]

Create a discrete two phase laplace operator matrix.

updateTwoPhaseMassOperator_rho(density_scaling=True, lumped=True)[source]

Create a discrete TwoPhase Mass operator matrix.

Parameters: density_scaling (bool) – Indicates whether advection terms should be scaled with the density (True) or 1 (False) lumped (bool) – Indicates whether the mass matrices should be lumped or full.
updateTwoPhaseInvScaledMassOperator(numerical_viscosity=True, lumped=True)[source]

Create a discrete TwoPhase Mass operator matrix.

Parameters: numerical_viscosity (bool) – Indicates whether the numerical viscosity should be included with the Laplace operator.Yes (True) or No (False)
class proteus.LinearSolvers.OperatorConstructor_oneLevel(OLT)[source]

A class for building common discrete operators from one-level transport models.

Parameters: OLT (proteus.Transport.OneLevelTransport) – One level transport class from which operator construction will be based.
updateMassOperator(rho=1.0)[source]
updateTPAdvectionOperator(phase_function=None)[source]
updateTPInvScaleLaplaceOperator()[source]
updateTwoPhaseMassOperator_rho()[source]
updateTwoPhaseInvScaledMassOperator()[source]
class proteus.LinearSolvers.ChebyshevSemiIteration(A, alpha, beta, save_iterations=False)[source]

Class for implementing the ChebyshevSemiIteration.

Notes

The Chebyshev semi-iteration was developed in the 1960s by Golub and Varga. It is an iterative technique for solving linear systems Ax = b with the property of preserving linearity with respect to the Krylov solves (see Wathen, Rees 2009 - Chebyshev semi-iteration in preconditioning for problems including the mass matrix). This makes the method particularly well suited for solving sub-problems that arise in more complicated block preconditioners such as the Schur complement, provided one has an aprior bound on the systems eigenvalues (see Wathen 1987 - Realisitc eigenvalue bounds for Galerkin mass matrix).

When implementing this method it is important you first have tight aprior bounds on the eigenvalues (denoted here as alpha and beta). This can be a challenge, but the references above do provide these results for many relevant mass matrices.

Also, when implementing this method, the residual b - Ax0 will be preconditioned with the inverse of diag(A). Your eigenvalue bounds should reflect the spectrum of this preconditioned system.

A
: :class: p4pyPETSc.Mat
The linear system matrix
alpha
: float
A’s smallest eigenvalue
beta
: float
A’s largest eigenvalue
save_iterations
: bool
A flag indicating whether to store each solution iteration

Notes

The Chebyshev semi-iteration is often used to solve subproblems of larger linear systems. Thus, it is common that this class will use petsc4py matrices and vectors. Currently this is the only case that is implemented, but an additional constructor has been included in the API for superlu matrices for future implementations.

classmethod chebyshev_superlu_constructor()[source]

Future home of a Chebyshev constructor for superlu matrices.

apply(b, x, k=5)[source]

This function applies the Chebyshev-semi iteration.

Parameters: b – The righthand side vector x – An initial guess for the solution. Note that the solution will be returned in the vector too. k (int) – Number of iterations x – The result of the Chebyshev semi-iteration. p4pyPETSc.Vec