esys.escriptcore.linearPDEs Package

Classes

class esys.escriptcore.linearPDEs.Helmholtz(domain, debug=False)

Bases: esys.escriptcore.linearPDEs.LinearPDE

Class to define a Helmholtz equation problem. This is generally a LinearPDE of the form

omega*u - grad(k*grad(u)[j])[j] = f

with natural boundary conditions

k*n[j]*grad(u)[j] = g- alphau

and constraints:

u=r where q>0

alteredCoefficient(name)

Announces that coefficient name has been changed.

Parameters:name (string) – name of the coefficient affected
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
Note :if name is q or r, the method will not trigger a rebuild of the system as constraints are applied to the solved system.
checkReciprocalSymmetry(name0, name1, verbose=True)

Tests two coefficients for reciprocal symmetry.

Parameters:
  • name0 (str) – name of the first coefficient
  • name1 (str) – name of the second coefficient
  • verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed
Returns:

True if coefficients name0 and name1 are reciprocally symmetric.

Return type:

bool

checkSymmetricTensor(name, verbose=True)

Tests a coefficient for symmetry.

Parameters:
  • name (str) – name of the coefficient
  • verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed.
Returns:

True if coefficient name is symmetric

Return type:

bool

checkSymmetry(verbose=True)

Tests the PDE for symmetry.

Parameters:verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed.
Returns:True if the PDE is symmetric
Return type:bool
Note :This is a very expensive operation. It should be used for degugging only! The symmetry flag is not altered.
createCoefficient(name)

Creates a Data object corresponding to coefficient name.

Returns:the coefficient name initialized to 0
Return type:Data
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
createOperator()

Returns an instance of a new operator.

createRightHandSide()

Returns an instance of a new right hand side.

createSolution()

Returns an instance of a new solution.

getCoefficient(name)

Returns the value of the coefficient name of the general PDE.

Parameters:name (string) – name of the coefficient requested
Returns:the value of the coefficient name
Return type:Data
Raises IllegalCoefficient:
 invalid name
getCurrentOperator()

Returns the operator in its current state.

getCurrentRightHandSide()

Returns the right hand side in its current state.

getCurrentSolution()

Returns the solution in its current state.

getDim()

Returns the spatial dimension of the PDE.

Returns:the spatial dimension of the PDE domain
Return type:int
getDomain()

Returns the domain of the PDE.

Returns:the domain of the PDE
Return type:Domain
getDomainStatus()

Return the status indicator of the domain

getFlux(u=None)

Returns the flux J for a given u.

J[i,j]=(A[i,j,k,l]+A_reduced[A[i,j,k,l]]*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])u[k]-X[i,j]-X_reduced[i,j]

or

J[j]=(A[i,j]+A_reduced[i,j])*grad(u)[l]+(B[j]+B_reduced[j])u-X[j]-X_reduced[j]

Parameters:u (Data or None) – argument in the flux. If u is not present or equals None the current solution is used.
Returns:flux
Return type:Data
getFunctionSpaceForCoefficient(name)

Returns the FunctionSpace to be used for coefficient name.

Parameters:name (string) – name of the coefficient enquired
Returns:the function space to be used for coefficient name
Return type:FunctionSpace
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getFunctionSpaceForEquation()

Returns the FunctionSpace used to discretize the equation.

Returns:representation space of equation
Return type:FunctionSpace
getFunctionSpaceForSolution()

Returns the FunctionSpace used to represent the solution.

Returns:representation space of solution
Return type:FunctionSpace
getNumEquations()

Returns the number of equations.

Returns:the number of equations
Return type:int
Raises UndefinedPDEError:
 if the number of equations is not specified yet
getNumSolutions()

Returns the number of unknowns.

Returns:the number of unknowns
Return type:int
Raises UndefinedPDEError:
 if the number of unknowns is not specified yet
getOperator()

Returns the operator of the linear problem.

Returns:the operator of the problem
getOperatorType()

Returns the current system type.

getRequiredOperatorType()

Returns the system type which needs to be used by the current set up.

getResidual(u=None)

Returns the residual of u or the current solution if u is not present.

Parameters:u (Data or None) – argument in the residual calculation. It must be representable in self.getFunctionSpaceForSolution(). If u is not present or equals None the current solution is used.
Returns:residual of u
Return type:Data
getRightHandSide()

Returns the right hand side of the linear problem.

Returns:the right hand side of the problem
Return type:Data
getShapeOfCoefficient(name)

Returns the shape of the coefficient name.

Parameters:name (string) – name of the coefficient enquired
Returns:the shape of the coefficient name
Return type:tuple of int
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getSolution()

Returns the solution of the PDE.

Returns:the solution
Return type:Data
getSolverOptions()

Returns the solver options

Return type:SolverOptions
getSystem()

Returns the operator and right hand side of the PDE.

Returns:the discrete version of the PDE
Return type:tuple of Operator and Data
getSystemStatus()

Return the domain status used to build the current system

hasCoefficient(name)

Returns True if name is the name of a coefficient.

Parameters:name (string) – name of the coefficient enquired
Returns:True if name is the name of a coefficient of the general PDE, False otherwise
Return type:bool
initializeSystem()

Resets the system clearing the operator, right hand side and solution.

insertConstraint(rhs_only=False)

Applies the constraints defined by q and r to the PDE.

Parameters:rhs_only (bool) – if True only the right hand side is altered by the constraint
introduceCoefficients(**coeff)

Introduces new coefficients into the problem.

Use:

p.introduceCoefficients(A=PDECoef(...), B=PDECoef(...))

to introduce the coefficients A and B.

invalidateOperator()

Indicates the operator has to be rebuilt next time it is used.

invalidateRightHandSide()

Indicates the right hand side has to be rebuilt next time it is used.

invalidateSolution()

Indicates the PDE has to be resolved if the solution is requested.

invalidateSystem()

Announces that everything has to be rebuilt.

isOperatorValid()

Returns True if the operator is still valid.

isRightHandSideValid()

Returns True if the operator is still valid.

isSolutionValid()

Returns True if the solution is still valid.

isSymmetric()

Checks if symmetry is indicated.

Returns:True if a symmetric PDE is indicated, False otherwise
Return type:bool
Note :the method is equivalent to use getSolverOptions().isSymmetric()
isSystemValid()

Returns True if the system (including solution) is still vaild.

isUsingLumping()

Checks if matrix lumping is the current solver method.

Returns:True if the current solver method is lumping
Return type:bool
reduceEquationOrder()

Returns the status of order reduction for the equation.

Returns:True if reduced interpolation order is used for the representation of the equation, False otherwise
Return type:bool
reduceSolutionOrder()

Returns the status of order reduction for the solution.

Returns:True if reduced interpolation order is used for the representation of the solution, False otherwise
Return type:bool
resetAllCoefficients()

Resets all coefficients to their default values.

resetOperator()

Makes sure that the operator is instantiated and returns it initialized with zeros.

resetRightHandSide()

Sets the right hand side to zero.

resetRightHandSideCoefficients()

Resets all coefficients defining the right hand side

resetSolution()

Sets the solution to zero.

setDebug(flag)

Switches debug output on if flag is True otherwise it is switched off.

Parameters:flag (bool) – desired debug status
setDebugOff()

Switches debug output off.

setDebugOn()

Switches debug output on.

setReducedOrderForEquationOff()

Switches reduced order off for equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForEquationOn()

Switches reduced order on for equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForEquationTo(flag=False)

Sets order reduction state for equation representation according to flag.

Parameters:flag (bool) – if flag is True, the order reduction is switched on for equation representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForSolutionOff()

Switches reduced order off for solution representation

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set.
setReducedOrderForSolutionOn()

Switches reduced order on for solution representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForSolutionTo(flag=False)

Sets order reduction state for solution representation according to flag.

Parameters:flag (bool) – if flag is True, the order reduction is switched on for solution representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderOff()

Switches reduced order off for solution and equation representation

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderOn()

Switches reduced order on for solution and equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderTo(flag=False)

Sets order reduction state for both solution and equation representation according to flag.

Parameters:flag (bool) – if True, the order reduction is switched on for both solution and equation representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setSolution(u, validate=True)

Sets the solution assuming that makes the system valid with the tolrance defined by the solver options

setSolverOptions(options=None)

Sets the solver options.

Parameters:options (SolverOptions or None) – the new solver options. If equal None, the solver options are set to the default.
Note :The symmetry flag of options is overwritten by the symmetry flag of the LinearProblem.
setSymmetry(flag=False)

Sets the symmetry flag to flag.

Parameters:flag (bool) – If True, the symmetry flag is set otherwise reset.
Note :The method overwrites the symmetry flag set by the solver options
setSymmetryOff()

Clears the symmetry flag. :note: The method overwrites the symmetry flag set by the solver options

setSymmetryOn()

Sets the symmetry flag. :note: The method overwrites the symmetry flag set by the solver options

setSystemStatus(status=None)

Sets the system status to status if status is not present the current status of the domain is used.

setValue(**coefficients)

Sets new values to coefficients.

Parameters:
  • coefficients – new values assigned to coefficients
  • omega (any type that can be cast to a Scalar object on Function) – value for coefficient omega
  • k (any type that can be cast to a Scalar object on Function) – value for coefficient k
  • f (any type that can be cast to a Scalar object on Function) – value for right hand side f
  • alpha (any type that can be cast to a Scalar object on FunctionOnBoundary) – value for right hand side alpha
  • g (any type that can be cast to a Scalar object on FunctionOnBoundary) – value for right hand side g
  • r (any type that can be cast to a Scalar object on Solution or ReducedSolution depending on whether reduced order is used for the representation of the equation) – prescribed values r for the solution in constraints
  • q (any type that can be cast to a Scalar object on Solution or ReducedSolution depending on whether reduced order is used for the representation of the equation) – mask for the location of constraints
Raises IllegalCoefficient:
 

if an unknown coefficient keyword is used

trace(text)

Prints the text message if debug mode is switched on.

Parameters:text (string) – message to be printed
validOperator()

Marks the operator as valid.

validRightHandSide()

Marks the right hand side as valid.

validSolution()

Marks the solution as valid.

class esys.escriptcore.linearPDEs.IllegalCoefficient

Bases: exceptions.ValueError

Exception that is raised if an illegal coefficient of the general or particular PDE is requested.

args
message
class esys.escriptcore.linearPDEs.IllegalCoefficientFunctionSpace

Bases: exceptions.ValueError

Exception that is raised if an incorrect function space for a coefficient is used.

args
message
class esys.escriptcore.linearPDEs.IllegalCoefficientValue

Bases: exceptions.ValueError

Exception that is raised if an incorrect value for a coefficient is used.

args
message
class esys.escriptcore.linearPDEs.LameEquation(domain, debug=False)

Bases: esys.escriptcore.linearPDEs.LinearPDE

Class to define a Lame equation problem. This problem is defined as:

-grad(mu*(grad(u[i])[j]+grad(u[j])[i]))[j] - grad(lambda*grad(u[k])[k])[j] = F_i -grad(sigma[ij])[j]

with natural boundary conditions:

n[j]*(mu*(grad(u[i])[j]+grad(u[j])[i]) + lambda*grad(u[k])[k]) = f_i +n[j]*sigma[ij]

and constraints:

u[i]=r[i] where q[i]>0

alteredCoefficient(name)

Announces that coefficient name has been changed.

Parameters:name (string) – name of the coefficient affected
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
Note :if name is q or r, the method will not trigger a rebuild of the system as constraints are applied to the solved system.
checkReciprocalSymmetry(name0, name1, verbose=True)

Tests two coefficients for reciprocal symmetry.

Parameters:
  • name0 (str) – name of the first coefficient
  • name1 (str) – name of the second coefficient
  • verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed
Returns:

True if coefficients name0 and name1 are reciprocally symmetric.

Return type:

bool

checkSymmetricTensor(name, verbose=True)

Tests a coefficient for symmetry.

Parameters:
  • name (str) – name of the coefficient
  • verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed.
Returns:

True if coefficient name is symmetric

Return type:

bool

checkSymmetry(verbose=True)

Tests the PDE for symmetry.

Parameters:verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed.
Returns:True if the PDE is symmetric
Return type:bool
Note :This is a very expensive operation. It should be used for degugging only! The symmetry flag is not altered.
createCoefficient(name)

Creates a Data object corresponding to coefficient name.

Returns:the coefficient name initialized to 0
Return type:Data
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
createOperator()

Returns an instance of a new operator.

createRightHandSide()

Returns an instance of a new right hand side.

createSolution()

Returns an instance of a new solution.

getCoefficient(name)

Returns the value of the coefficient name of the general PDE.

Parameters:name (string) – name of the coefficient requested
Returns:the value of the coefficient name
Return type:Data
Raises IllegalCoefficient:
 invalid coefficient name
getCurrentOperator()

Returns the operator in its current state.

getCurrentRightHandSide()

Returns the right hand side in its current state.

getCurrentSolution()

Returns the solution in its current state.

getDim()

Returns the spatial dimension of the PDE.

Returns:the spatial dimension of the PDE domain
Return type:int
getDomain()

Returns the domain of the PDE.

Returns:the domain of the PDE
Return type:Domain
getDomainStatus()

Return the status indicator of the domain

getFlux(u=None)

Returns the flux J for a given u.

J[i,j]=(A[i,j,k,l]+A_reduced[A[i,j,k,l]]*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])u[k]-X[i,j]-X_reduced[i,j]

or

J[j]=(A[i,j]+A_reduced[i,j])*grad(u)[l]+(B[j]+B_reduced[j])u-X[j]-X_reduced[j]

Parameters:u (Data or None) – argument in the flux. If u is not present or equals None the current solution is used.
Returns:flux
Return type:Data
getFunctionSpaceForCoefficient(name)

Returns the FunctionSpace to be used for coefficient name.

Parameters:name (string) – name of the coefficient enquired
Returns:the function space to be used for coefficient name
Return type:FunctionSpace
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getFunctionSpaceForEquation()

Returns the FunctionSpace used to discretize the equation.

Returns:representation space of equation
Return type:FunctionSpace
getFunctionSpaceForSolution()

Returns the FunctionSpace used to represent the solution.

Returns:representation space of solution
Return type:FunctionSpace
getNumEquations()

Returns the number of equations.

Returns:the number of equations
Return type:int
Raises UndefinedPDEError:
 if the number of equations is not specified yet
getNumSolutions()

Returns the number of unknowns.

Returns:the number of unknowns
Return type:int
Raises UndefinedPDEError:
 if the number of unknowns is not specified yet
getOperator()

Returns the operator of the linear problem.

Returns:the operator of the problem
getOperatorType()

Returns the current system type.

getRequiredOperatorType()

Returns the system type which needs to be used by the current set up.

getResidual(u=None)

Returns the residual of u or the current solution if u is not present.

Parameters:u (Data or None) – argument in the residual calculation. It must be representable in self.getFunctionSpaceForSolution(). If u is not present or equals None the current solution is used.
Returns:residual of u
Return type:Data
getRightHandSide()

Returns the right hand side of the linear problem.

Returns:the right hand side of the problem
Return type:Data
getShapeOfCoefficient(name)

Returns the shape of the coefficient name.

Parameters:name (string) – name of the coefficient enquired
Returns:the shape of the coefficient name
Return type:tuple of int
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getSolution()

Returns the solution of the PDE.

Returns:the solution
Return type:Data
getSolverOptions()

Returns the solver options

Return type:SolverOptions
getSystem()

Returns the operator and right hand side of the PDE.

Returns:the discrete version of the PDE
Return type:tuple of Operator and Data
getSystemStatus()

Return the domain status used to build the current system

hasCoefficient(name)

Returns True if name is the name of a coefficient.

Parameters:name (string) – name of the coefficient enquired
Returns:True if name is the name of a coefficient of the general PDE, False otherwise
Return type:bool
initializeSystem()

Resets the system clearing the operator, right hand side and solution.

insertConstraint(rhs_only=False)

Applies the constraints defined by q and r to the PDE.

Parameters:rhs_only (bool) – if True only the right hand side is altered by the constraint
introduceCoefficients(**coeff)

Introduces new coefficients into the problem.

Use:

p.introduceCoefficients(A=PDECoef(...), B=PDECoef(...))

to introduce the coefficients A and B.

invalidateOperator()

Indicates the operator has to be rebuilt next time it is used.

invalidateRightHandSide()

Indicates the right hand side has to be rebuilt next time it is used.

invalidateSolution()

Indicates the PDE has to be resolved if the solution is requested.

invalidateSystem()

Announces that everything has to be rebuilt.

isOperatorValid()

Returns True if the operator is still valid.

isRightHandSideValid()

Returns True if the operator is still valid.

isSolutionValid()

Returns True if the solution is still valid.

isSymmetric()

Checks if symmetry is indicated.

Returns:True if a symmetric PDE is indicated, False otherwise
Return type:bool
Note :the method is equivalent to use getSolverOptions().isSymmetric()
isSystemValid()

Returns True if the system (including solution) is still vaild.

isUsingLumping()

Checks if matrix lumping is the current solver method.

Returns:True if the current solver method is lumping
Return type:bool
reduceEquationOrder()

Returns the status of order reduction for the equation.

Returns:True if reduced interpolation order is used for the representation of the equation, False otherwise
Return type:bool
reduceSolutionOrder()

Returns the status of order reduction for the solution.

Returns:True if reduced interpolation order is used for the representation of the solution, False otherwise
Return type:bool
resetAllCoefficients()

Resets all coefficients to their default values.

resetOperator()

Makes sure that the operator is instantiated and returns it initialized with zeros.

resetRightHandSide()

Sets the right hand side to zero.

resetRightHandSideCoefficients()

Resets all coefficients defining the right hand side

resetSolution()

Sets the solution to zero.

setDebug(flag)

Switches debug output on if flag is True otherwise it is switched off.

Parameters:flag (bool) – desired debug status
setDebugOff()

Switches debug output off.

setDebugOn()

Switches debug output on.

setReducedOrderForEquationOff()

Switches reduced order off for equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForEquationOn()

Switches reduced order on for equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForEquationTo(flag=False)

Sets order reduction state for equation representation according to flag.

Parameters:flag (bool) – if flag is True, the order reduction is switched on for equation representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForSolutionOff()

Switches reduced order off for solution representation

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set.
setReducedOrderForSolutionOn()

Switches reduced order on for solution representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForSolutionTo(flag=False)

Sets order reduction state for solution representation according to flag.

Parameters:flag (bool) – if flag is True, the order reduction is switched on for solution representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderOff()

Switches reduced order off for solution and equation representation

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderOn()

Switches reduced order on for solution and equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderTo(flag=False)

Sets order reduction state for both solution and equation representation according to flag.

Parameters:flag (bool) – if True, the order reduction is switched on for both solution and equation representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setSolution(u, validate=True)

Sets the solution assuming that makes the system valid with the tolrance defined by the solver options

setSolverOptions(options=None)

Sets the solver options.

Parameters:options (SolverOptions or None) – the new solver options. If equal None, the solver options are set to the default.
Note :The symmetry flag of options is overwritten by the symmetry flag of the LinearProblem.
setSymmetry(flag=False)

Sets the symmetry flag to flag.

Parameters:flag (bool) – If True, the symmetry flag is set otherwise reset.
Note :The method overwrites the symmetry flag set by the solver options
setSymmetryOff()

Clears the symmetry flag. :note: The method overwrites the symmetry flag set by the solver options

setSymmetryOn()

Sets the symmetry flag. :note: The method overwrites the symmetry flag set by the solver options

setSystemStatus(status=None)

Sets the system status to status if status is not present the current status of the domain is used.

setValue(**coefficients)

Sets new values to coefficients.

Parameters:
  • coefficients – new values assigned to coefficients
  • A (any type that can be cast to a Data object on Function) – value for coefficient A
  • A_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient A_reduced
  • B (any type that can be cast to a Data object on Function) – value for coefficient B
  • B_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient B_reduced
  • C (any type that can be cast to a Data object on Function) – value for coefficient C
  • C_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient C_reduced
  • D (any type that can be cast to a Data object on Function) – value for coefficient D
  • D_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient D_reduced
  • X (any type that can be cast to a Data object on Function) – value for coefficient X
  • X_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient X_reduced
  • Y (any type that can be cast to a Data object on Function) – value for coefficient Y
  • Y_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient Y_reduced
  • d (any type that can be cast to a Data object on FunctionOnBoundary) – value for coefficient d
  • d_reduced (any type that can be cast to a Data object on ReducedFunctionOnBoundary) – value for coefficient d_reduced
  • y (any type that can be cast to a Data object on FunctionOnBoundary) – value for coefficient y
  • d_contact (any type that can be cast to a Data object on FunctionOnContactOne or FunctionOnContactZero) – value for coefficient d_contact
  • d_contact_reduced (any type that can be cast to a Data object on ReducedFunctionOnContactOne or ReducedFunctionOnContactZero) – value for coefficient d_contact_reduced
  • y_contact (any type that can be cast to a Data object on FunctionOnContactOne or FunctionOnContactZero) – value for coefficient y_contact
  • y_contact_reduced (any type that can be cast to a Data object on ReducedFunctionOnContactOne or ReducedFunctionOnContactZero) – value for coefficient y_contact_reduced
  • d_dirac (any type that can be cast to a Data object on DiracDeltaFunctions) – value for coefficient d_dirac
  • y_dirac (any type that can be cast to a Data object on DiracDeltaFunctions) – value for coefficient y_dirac
  • r (any type that can be cast to a Data object on Solution or ReducedSolution depending on whether reduced order is used for the solution) – values prescribed to the solution at the locations of constraints
  • q (any type that can be cast to a Data object on Solution or ReducedSolution depending on whether reduced order is used for the representation of the equation) – mask for location of constraints
Raises IllegalCoefficient:
 

if an unknown coefficient keyword is used

setValues(**coefficients)

Sets new values to coefficients.

Parameters:
  • coefficients – new values assigned to coefficients
  • lame_mu (any type that can be cast to a Scalar object on Function) – value for coefficient mu
  • lame_lambda (any type that can be cast to a Scalar object on Function) – value for coefficient lambda
  • F (any type that can be cast to a Vector object on Function) – value for internal force F
  • sigma (any type that can be cast to a Tensor object on Function) – value for initial stress sigma
  • f (any type that can be cast to a Vector object on FunctionOnBoundary) – value for external force f
  • r (any type that can be cast to a Vector object on Solution or ReducedSolution depending on whether reduced order is used for the representation of the equation) – prescribed values r for the solution in constraints
  • q (any type that can be cast to a Vector object on Solution or ReducedSolution depending on whether reduced order is used for the representation of the equation) – mask for the location of constraints
Raises IllegalCoefficient:
 

if an unknown coefficient keyword is used

trace(text)

Prints the text message if debug mode is switched on.

Parameters:text (string) – message to be printed
validOperator()

Marks the operator as valid.

validRightHandSide()

Marks the right hand side as valid.

validSolution()

Marks the solution as valid.

class esys.escriptcore.linearPDEs.LinearPDE(domain, numEquations=None, numSolutions=None, debug=False)

Bases: esys.escriptcore.linearPDEs.LinearProblem

This class is used to define a general linear, steady, second order PDE for an unknown function u on a given domain defined through a Domain object.

For a single PDE having a solution with a single component the linear PDE is defined in the following form:

-(grad(A[j,l]+A_reduced[j,l])*grad(u)[l]+(B[j]+B_reduced[j])u)[j]+(C[l]+C_reduced[l])*grad(u)[l]+(D+D_reduced)=-grad(X+X_reduced)[j,j]+(Y+Y_reduced)

where grad(F) denotes the spatial derivative of F. Einstein’s summation convention, ie. summation over indexes appearing twice in a term of a sum performed, is used. The coefficients A, B, C, D, X and Y have to be specified through Data objects in Function and the coefficients A_reduced, B_reduced, C_reduced, D_reduced, X_reduced and Y_reduced have to be specified through Data objects in ReducedFunction. It is also allowed to use objects that can be converted into such Data objects. A and A_reduced are rank two, B, C, X, B_reduced, C_reduced and X_reduced are rank one and D, D_reduced, Y and Y_reduced are scalar.

The following natural boundary conditions are considered:

n[j]*((A[i,j]+A_reduced[i,j])*grad(u)[l]+(B+B_reduced)[j]*u)+(d+d_reduced)*u=n[j]*(X[j]+X_reduced[j])+y

where n is the outer normal field. Notice that the coefficients A, A_reduced, B, B_reduced, X and X_reduced are defined in the PDE. The coefficients d and y are each a scalar in FunctionOnBoundary and the coefficients d_reduced and y_reduced are each a scalar in ReducedFunctionOnBoundary.

Constraints for the solution prescribe the value of the solution at certain locations in the domain. They have the form

u=r where q>0

r and q are each scalar where q is the characteristic function defining where the constraint is applied. The constraints override any other condition set by the PDE or the boundary condition.

The PDE is symmetrical if

A[i,j]=A[j,i] and B[j]=C[j] and A_reduced[i,j]=A_reduced[j,i] and B_reduced[j]=C_reduced[j]

For a system of PDEs and a solution with several components the PDE has the form

-grad((A[i,j,k,l]+A_reduced[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k])[j]+(C[i,k,l]+C_reduced[i,k,l])*grad(u[k])[l]+(D[i,k]+D_reduced[i,k]*u[k] =-grad(X[i,j]+X_reduced[i,j])[j]+Y[i]+Y_reduced[i]

A and A_reduced are of rank four, B, B_reduced, C and C_reduced are each of rank three, D, D_reduced, X_reduced and X are each of rank two and Y and Y_reduced are of rank one. The natural boundary conditions take the form:

n[j]*((A[i,j,k,l]+A_reduced[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k])+(d[i,k]+d_reduced[i,k])*u[k]=n[j]*(X[i,j]+X_reduced[i,j])+y[i]+y_reduced[i]

The coefficient d is of rank two and y is of rank one both in FunctionOnBoundary. The coefficients d_reduced is of rank two and y_reduced is of rank one both in ReducedFunctionOnBoundary.

Constraints take the form

u[i]=r[i] where q[i]>0

r and q are each rank one. Notice that at some locations not necessarily all components must have a constraint.

The system of PDEs is symmetrical if

  • A[i,j,k,l]=A[k,l,i,j]
  • A_reduced[i,j,k,l]=A_reduced[k,l,i,j]
  • B[i,j,k]=C[k,i,j]
  • B_reduced[i,j,k]=C_reduced[k,i,j]
  • D[i,k]=D[i,k]
  • D_reduced[i,k]=D_reduced[i,k]
  • d[i,k]=d[k,i]
  • d_reduced[i,k]=d_reduced[k,i]

LinearPDE also supports solution discontinuities over a contact region in the domain. To specify the conditions across the discontinuity we are using the generalised flux J which, in the case of a system of PDEs and several components of the solution, is defined as

J[i,j]=(A[i,j,k,l]+A_reduced[[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k]-X[i,j]-X_reduced[i,j]

For the case of single solution component and single PDE J is defined as

J[j]=(A[i,j]+A_reduced[i,j])*grad(u)[j]+(B[i]+B_reduced[i])*u-X[i]-X_reduced[i]

In the context of discontinuities n denotes the normal on the discontinuity pointing from side 0 towards side 1 calculated from FunctionSpace.getNormal of FunctionOnContactZero. For a system of PDEs the contact condition takes the form

n[j]*J0[i,j]=n[j]*J1[i,j]=(y_contact[i]+y_contact_reduced[i])- (d_contact[i,k]+d_contact_reduced[i,k])*jump(u)[k]

where J0 and J1 are the fluxes on side 0 and side 1 of the discontinuity, respectively. jump(u), which is the difference of the solution at side 1 and at side 0, denotes the jump of u across discontinuity along the normal calculated by jump. The coefficient d_contact is of rank two and y_contact is of rank one both in FunctionOnContactZero or FunctionOnContactOne. The coefficient d_contact_reduced is of rank two and y_contact_reduced is of rank one both in ReducedFunctionOnContactZero or ReducedFunctionOnContactOne. In case of a single PDE and a single component solution the contact condition takes the form

n[j]*J0_{j}=n[j]*J1_{j}=(y_contact+y_contact_reduced)-(d_contact+y_contact_reduced)*jump(u)

In this case the coefficient d_contact and y_contact are each scalar both in FunctionOnContactZero or FunctionOnContactOne and the coefficient d_contact_reduced and y_contact_reduced are each scalar both in ReducedFunctionOnContactZero or ReducedFunctionOnContactOne.

Typical usage:

p = LinearPDE(dom)
p.setValue(A=kronecker(dom), D=1, Y=0.5)
u = p.getSolution()
alteredCoefficient(name)

Announces that coefficient name has been changed.

Parameters:name (string) – name of the coefficient affected
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
Note :if name is q or r, the method will not trigger a rebuild of the system as constraints are applied to the solved system.
checkReciprocalSymmetry(name0, name1, verbose=True)

Tests two coefficients for reciprocal symmetry.

Parameters:
  • name0 (str) – name of the first coefficient
  • name1 (str) – name of the second coefficient
  • verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed
Returns:

True if coefficients name0 and name1 are reciprocally symmetric.

Return type:

bool

checkSymmetricTensor(name, verbose=True)

Tests a coefficient for symmetry.

Parameters:
  • name (str) – name of the coefficient
  • verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed.
Returns:

True if coefficient name is symmetric

Return type:

bool

checkSymmetry(verbose=True)

Tests the PDE for symmetry.

Parameters:verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed.
Returns:True if the PDE is symmetric
Return type:bool
Note :This is a very expensive operation. It should be used for degugging only! The symmetry flag is not altered.
createCoefficient(name)

Creates a Data object corresponding to coefficient name.

Returns:the coefficient name initialized to 0
Return type:Data
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
createOperator()

Returns an instance of a new operator.

createRightHandSide()

Returns an instance of a new right hand side.

createSolution()

Returns an instance of a new solution.

getCoefficient(name)

Returns the value of the coefficient name.

Parameters:name (string) – name of the coefficient requested
Returns:the value of the coefficient
Return type:Data
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getCurrentOperator()

Returns the operator in its current state.

getCurrentRightHandSide()

Returns the right hand side in its current state.

getCurrentSolution()

Returns the solution in its current state.

getDim()

Returns the spatial dimension of the PDE.

Returns:the spatial dimension of the PDE domain
Return type:int
getDomain()

Returns the domain of the PDE.

Returns:the domain of the PDE
Return type:Domain
getDomainStatus()

Return the status indicator of the domain

getFlux(u=None)

Returns the flux J for a given u.

J[i,j]=(A[i,j,k,l]+A_reduced[A[i,j,k,l]]*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])u[k]-X[i,j]-X_reduced[i,j]

or

J[j]=(A[i,j]+A_reduced[i,j])*grad(u)[l]+(B[j]+B_reduced[j])u-X[j]-X_reduced[j]

Parameters:u (Data or None) – argument in the flux. If u is not present or equals None the current solution is used.
Returns:flux
Return type:Data
getFunctionSpaceForCoefficient(name)

Returns the FunctionSpace to be used for coefficient name.

Parameters:name (string) – name of the coefficient enquired
Returns:the function space to be used for coefficient name
Return type:FunctionSpace
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getFunctionSpaceForEquation()

Returns the FunctionSpace used to discretize the equation.

Returns:representation space of equation
Return type:FunctionSpace
getFunctionSpaceForSolution()

Returns the FunctionSpace used to represent the solution.

Returns:representation space of solution
Return type:FunctionSpace
getNumEquations()

Returns the number of equations.

Returns:the number of equations
Return type:int
Raises UndefinedPDEError:
 if the number of equations is not specified yet
getNumSolutions()

Returns the number of unknowns.

Returns:the number of unknowns
Return type:int
Raises UndefinedPDEError:
 if the number of unknowns is not specified yet
getOperator()

Returns the operator of the linear problem.

Returns:the operator of the problem
getOperatorType()

Returns the current system type.

getRequiredOperatorType()

Returns the system type which needs to be used by the current set up.

getResidual(u=None)

Returns the residual of u or the current solution if u is not present.

Parameters:u (Data or None) – argument in the residual calculation. It must be representable in self.getFunctionSpaceForSolution(). If u is not present or equals None the current solution is used.
Returns:residual of u
Return type:Data
getRightHandSide()

Returns the right hand side of the linear problem.

Returns:the right hand side of the problem
Return type:Data
getShapeOfCoefficient(name)

Returns the shape of the coefficient name.

Parameters:name (string) – name of the coefficient enquired
Returns:the shape of the coefficient name
Return type:tuple of int
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getSolution()

Returns the solution of the PDE.

Returns:the solution
Return type:Data
getSolverOptions()

Returns the solver options

Return type:SolverOptions
getSystem()

Returns the operator and right hand side of the PDE.

Returns:the discrete version of the PDE
Return type:tuple of Operator and Data
getSystemStatus()

Return the domain status used to build the current system

hasCoefficient(name)

Returns True if name is the name of a coefficient.

Parameters:name (string) – name of the coefficient enquired
Returns:True if name is the name of a coefficient of the general PDE, False otherwise
Return type:bool
initializeSystem()

Resets the system clearing the operator, right hand side and solution.

insertConstraint(rhs_only=False)

Applies the constraints defined by q and r to the PDE.

Parameters:rhs_only (bool) – if True only the right hand side is altered by the constraint
introduceCoefficients(**coeff)

Introduces new coefficients into the problem.

Use:

p.introduceCoefficients(A=PDECoef(...), B=PDECoef(...))

to introduce the coefficients A and B.

invalidateOperator()

Indicates the operator has to be rebuilt next time it is used.

invalidateRightHandSide()

Indicates the right hand side has to be rebuilt next time it is used.

invalidateSolution()

Indicates the PDE has to be resolved if the solution is requested.

invalidateSystem()

Announces that everything has to be rebuilt.

isOperatorValid()

Returns True if the operator is still valid.

isRightHandSideValid()

Returns True if the operator is still valid.

isSolutionValid()

Returns True if the solution is still valid.

isSymmetric()

Checks if symmetry is indicated.

Returns:True if a symmetric PDE is indicated, False otherwise
Return type:bool
Note :the method is equivalent to use getSolverOptions().isSymmetric()
isSystemValid()

Returns True if the system (including solution) is still vaild.

isUsingLumping()

Checks if matrix lumping is the current solver method.

Returns:True if the current solver method is lumping
Return type:bool
reduceEquationOrder()

Returns the status of order reduction for the equation.

Returns:True if reduced interpolation order is used for the representation of the equation, False otherwise
Return type:bool
reduceSolutionOrder()

Returns the status of order reduction for the solution.

Returns:True if reduced interpolation order is used for the representation of the solution, False otherwise
Return type:bool
resetAllCoefficients()

Resets all coefficients to their default values.

resetOperator()

Makes sure that the operator is instantiated and returns it initialized with zeros.

resetRightHandSide()

Sets the right hand side to zero.

resetRightHandSideCoefficients()

Resets all coefficients defining the right hand side

resetSolution()

Sets the solution to zero.

setDebug(flag)

Switches debug output on if flag is True otherwise it is switched off.

Parameters:flag (bool) – desired debug status
setDebugOff()

Switches debug output off.

setDebugOn()

Switches debug output on.

setReducedOrderForEquationOff()

Switches reduced order off for equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForEquationOn()

Switches reduced order on for equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForEquationTo(flag=False)

Sets order reduction state for equation representation according to flag.

Parameters:flag (bool) – if flag is True, the order reduction is switched on for equation representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForSolutionOff()

Switches reduced order off for solution representation

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set.
setReducedOrderForSolutionOn()

Switches reduced order on for solution representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForSolutionTo(flag=False)

Sets order reduction state for solution representation according to flag.

Parameters:flag (bool) – if flag is True, the order reduction is switched on for solution representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderOff()

Switches reduced order off for solution and equation representation

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderOn()

Switches reduced order on for solution and equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderTo(flag=False)

Sets order reduction state for both solution and equation representation according to flag.

Parameters:flag (bool) – if True, the order reduction is switched on for both solution and equation representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setSolution(u, validate=True)

Sets the solution assuming that makes the system valid with the tolrance defined by the solver options

setSolverOptions(options=None)

Sets the solver options.

Parameters:options (SolverOptions or None) – the new solver options. If equal None, the solver options are set to the default.
Note :The symmetry flag of options is overwritten by the symmetry flag of the LinearProblem.
setSymmetry(flag=False)

Sets the symmetry flag to flag.

Parameters:flag (bool) – If True, the symmetry flag is set otherwise reset.
Note :The method overwrites the symmetry flag set by the solver options
setSymmetryOff()

Clears the symmetry flag. :note: The method overwrites the symmetry flag set by the solver options

setSymmetryOn()

Sets the symmetry flag. :note: The method overwrites the symmetry flag set by the solver options

setSystemStatus(status=None)

Sets the system status to status if status is not present the current status of the domain is used.

setValue(**coefficients)

Sets new values to coefficients.

Parameters:
  • coefficients – new values assigned to coefficients
  • A (any type that can be cast to a Data object on Function) – value for coefficient A
  • A_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient A_reduced
  • B (any type that can be cast to a Data object on Function) – value for coefficient B
  • B_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient B_reduced
  • C (any type that can be cast to a Data object on Function) – value for coefficient C
  • C_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient C_reduced
  • D (any type that can be cast to a Data object on Function) – value for coefficient D
  • D_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient D_reduced
  • X (any type that can be cast to a Data object on Function) – value for coefficient X
  • X_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient X_reduced
  • Y (any type that can be cast to a Data object on Function) – value for coefficient Y
  • Y_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient Y_reduced
  • d (any type that can be cast to a Data object on FunctionOnBoundary) – value for coefficient d
  • d_reduced (any type that can be cast to a Data object on ReducedFunctionOnBoundary) – value for coefficient d_reduced
  • y (any type that can be cast to a Data object on FunctionOnBoundary) – value for coefficient y
  • d_contact (any type that can be cast to a Data object on FunctionOnContactOne or FunctionOnContactZero) – value for coefficient d_contact
  • d_contact_reduced (any type that can be cast to a Data object on ReducedFunctionOnContactOne or ReducedFunctionOnContactZero) – value for coefficient d_contact_reduced
  • y_contact (any type that can be cast to a Data object on FunctionOnContactOne or FunctionOnContactZero) – value for coefficient y_contact
  • y_contact_reduced (any type that can be cast to a Data object on ReducedFunctionOnContactOne or ReducedFunctionOnContactZero) – value for coefficient y_contact_reduced
  • d_dirac (any type that can be cast to a Data object on DiracDeltaFunctions) – value for coefficient d_dirac
  • y_dirac (any type that can be cast to a Data object on DiracDeltaFunctions) – value for coefficient y_dirac
  • r (any type that can be cast to a Data object on Solution or ReducedSolution depending on whether reduced order is used for the solution) – values prescribed to the solution at the locations of constraints
  • q (any type that can be cast to a Data object on Solution or ReducedSolution depending on whether reduced order is used for the representation of the equation) – mask for location of constraints
Raises IllegalCoefficient:
 

if an unknown coefficient keyword is used

trace(text)

Prints the text message if debug mode is switched on.

Parameters:text (string) – message to be printed
validOperator()

Marks the operator as valid.

validRightHandSide()

Marks the right hand side as valid.

validSolution()

Marks the solution as valid.

class esys.escriptcore.linearPDEs.LinearProblem(domain, numEquations=None, numSolutions=None, debug=False)

Bases: object

This is the base class to define a general linear PDE-type problem for for an unknown function u on a given domain defined through a Domain object. The problem can be given as a single equation or as a system of equations.

The class assumes that some sort of assembling process is required to form a problem of the form

L u=f

where L is an operator and f is the right hand side. This operator problem will be solved to get the unknown u.

alteredCoefficient(name)

Announces that coefficient name has been changed.

Parameters:name (string) – name of the coefficient affected
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
Note :if name is q or r, the method will not trigger a rebuild of the system as constraints are applied to the solved system.
checkReciprocalSymmetry(name0, name1, verbose=True)

Tests two coefficients for reciprocal symmetry.

Parameters:
  • name0 (str) – name of the first coefficient
  • name1 (str) – name of the second coefficient
  • verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed
Returns:

True if coefficients name0 and name1 are reciprocally symmetric.

Return type:

bool

checkSymmetricTensor(name, verbose=True)

Tests a coefficient for symmetry.

Parameters:
  • name (str) – name of the coefficient
  • verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed.
Returns:

True if coefficient name is symmetric

Return type:

bool

checkSymmetry(verbose=True)

Tests the PDE for symmetry.

Parameters:verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed
Returns:True if the problem is symmetric
Return type:bool
Note :Typically this method is overwritten when implementing a particular linear problem.
createCoefficient(name)

Creates a Data object corresponding to coefficient name.

Returns:the coefficient name initialized to 0
Return type:Data
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
createOperator()

Returns an instance of a new operator.

Note :This method is overwritten when implementing a particular linear problem.
createRightHandSide()

Returns an instance of a new right hand side.

createSolution()

Returns an instance of a new solution.

getCoefficient(name)

Returns the value of the coefficient name.

Parameters:name (string) – name of the coefficient requested
Returns:the value of the coefficient
Return type:Data
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getCurrentOperator()

Returns the operator in its current state.

getCurrentRightHandSide()

Returns the right hand side in its current state.

getCurrentSolution()

Returns the solution in its current state.

getDim()

Returns the spatial dimension of the PDE.

Returns:the spatial dimension of the PDE domain
Return type:int
getDomain()

Returns the domain of the PDE.

Returns:the domain of the PDE
Return type:Domain
getDomainStatus()

Return the status indicator of the domain

getFunctionSpaceForCoefficient(name)

Returns the FunctionSpace to be used for coefficient name.

Parameters:name (string) – name of the coefficient enquired
Returns:the function space to be used for coefficient name
Return type:FunctionSpace
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getFunctionSpaceForEquation()

Returns the FunctionSpace used to discretize the equation.

Returns:representation space of equation
Return type:FunctionSpace
getFunctionSpaceForSolution()

Returns the FunctionSpace used to represent the solution.

Returns:representation space of solution
Return type:FunctionSpace
getNumEquations()

Returns the number of equations.

Returns:the number of equations
Return type:int
Raises UndefinedPDEError:
 if the number of equations is not specified yet
getNumSolutions()

Returns the number of unknowns.

Returns:the number of unknowns
Return type:int
Raises UndefinedPDEError:
 if the number of unknowns is not specified yet
getOperator()

Returns the operator of the linear problem.

Returns:the operator of the problem
getOperatorType()

Returns the current system type.

getRequiredOperatorType()

Returns the system type which needs to be used by the current set up.

Note :Typically this method is overwritten when implementing a particular linear problem.
getRightHandSide()

Returns the right hand side of the linear problem.

Returns:the right hand side of the problem
Return type:Data
getShapeOfCoefficient(name)

Returns the shape of the coefficient name.

Parameters:name (string) – name of the coefficient enquired
Returns:the shape of the coefficient name
Return type:tuple of int
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getSolution(**options)

Returns the solution of the problem.

Returns:the solution
Return type:Data
Note :This method is overwritten when implementing a particular linear problem.
getSolverOptions()

Returns the solver options

Return type:SolverOptions
getSystem()

Returns the operator and right hand side of the PDE.

Returns:the discrete version of the PDE
Return type:tuple of Operator and Data.
Note :This method is overwritten when implementing a particular linear problem.
getSystemStatus()

Return the domain status used to build the current system

hasCoefficient(name)

Returns True if name is the name of a coefficient.

Parameters:name (string) – name of the coefficient enquired
Returns:True if name is the name of a coefficient of the general PDE, False otherwise
Return type:bool
initializeSystem()

Resets the system clearing the operator, right hand side and solution.

introduceCoefficients(**coeff)

Introduces new coefficients into the problem.

Use:

p.introduceCoefficients(A=PDECoef(...), B=PDECoef(...))

to introduce the coefficients A and B.

invalidateOperator()

Indicates the operator has to be rebuilt next time it is used.

invalidateRightHandSide()

Indicates the right hand side has to be rebuilt next time it is used.

invalidateSolution()

Indicates the PDE has to be resolved if the solution is requested.

invalidateSystem()

Announces that everything has to be rebuilt.

isOperatorValid()

Returns True if the operator is still valid.

isRightHandSideValid()

Returns True if the operator is still valid.

isSolutionValid()

Returns True if the solution is still valid.

isSymmetric()

Checks if symmetry is indicated.

Returns:True if a symmetric PDE is indicated, False otherwise
Return type:bool
Note :the method is equivalent to use getSolverOptions().isSymmetric()
isSystemValid()

Returns True if the system (including solution) is still vaild.

isUsingLumping()

Checks if matrix lumping is the current solver method.

Returns:True if the current solver method is lumping
Return type:bool
reduceEquationOrder()

Returns the status of order reduction for the equation.

Returns:True if reduced interpolation order is used for the representation of the equation, False otherwise
Return type:bool
reduceSolutionOrder()

Returns the status of order reduction for the solution.

Returns:True if reduced interpolation order is used for the representation of the solution, False otherwise
Return type:bool
resetAllCoefficients()

Resets all coefficients to their default values.

resetOperator()

Makes sure that the operator is instantiated and returns it initialized with zeros.

resetRightHandSide()

Sets the right hand side to zero.

resetRightHandSideCoefficients()

Resets all coefficients defining the right hand side

resetSolution()

Sets the solution to zero.

setDebug(flag)

Switches debug output on if flag is True otherwise it is switched off.

Parameters:flag (bool) – desired debug status
setDebugOff()

Switches debug output off.

setDebugOn()

Switches debug output on.

setReducedOrderForEquationOff()

Switches reduced order off for equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForEquationOn()

Switches reduced order on for equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForEquationTo(flag=False)

Sets order reduction state for equation representation according to flag.

Parameters:flag (bool) – if flag is True, the order reduction is switched on for equation representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForSolutionOff()

Switches reduced order off for solution representation

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set.
setReducedOrderForSolutionOn()

Switches reduced order on for solution representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForSolutionTo(flag=False)

Sets order reduction state for solution representation according to flag.

Parameters:flag (bool) – if flag is True, the order reduction is switched on for solution representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderOff()

Switches reduced order off for solution and equation representation

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderOn()

Switches reduced order on for solution and equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderTo(flag=False)

Sets order reduction state for both solution and equation representation according to flag.

Parameters:flag (bool) – if True, the order reduction is switched on for both solution and equation representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setSolution(u, validate=True)

Sets the solution assuming that makes the system valid with the tolrance defined by the solver options

setSolverOptions(options=None)

Sets the solver options.

Parameters:options (SolverOptions or None) – the new solver options. If equal None, the solver options are set to the default.
Note :The symmetry flag of options is overwritten by the symmetry flag of the LinearProblem.
setSymmetry(flag=False)

Sets the symmetry flag to flag.

Parameters:flag (bool) – If True, the symmetry flag is set otherwise reset.
Note :The method overwrites the symmetry flag set by the solver options
setSymmetryOff()

Clears the symmetry flag. :note: The method overwrites the symmetry flag set by the solver options

setSymmetryOn()

Sets the symmetry flag. :note: The method overwrites the symmetry flag set by the solver options

setSystemStatus(status=None)

Sets the system status to status if status is not present the current status of the domain is used.

setValue(**coefficients)

Sets new values to coefficients.

Raises IllegalCoefficient:
 if an unknown coefficient keyword is used
trace(text)

Prints the text message if debug mode is switched on.

Parameters:text (string) – message to be printed
validOperator()

Marks the operator as valid.

validRightHandSide()

Marks the right hand side as valid.

validSolution()

Marks the solution as valid.

class esys.escriptcore.linearPDEs.PDECoef(where, pattern, altering)

Bases: object

A class for describing a PDE coefficient.

Variables:
  • INTERIOR – indicator that coefficient is defined on the interior of the PDE domain
  • BOUNDARY – indicator that coefficient is defined on the boundary of the PDE domain
  • CONTACT – indicator that coefficient is defined on the contact region within the PDE domain
  • INTERIOR_REDUCED – indicator that coefficient is defined on the interior of the PDE domain using a reduced integration order
  • BOUNDARY_REDUCED – indicator that coefficient is defined on the boundary of the PDE domain using a reduced integration order
  • CONTACT_REDUCED – indicator that coefficient is defined on the contact region within the PDE domain using a reduced integration order
  • SOLUTION – indicator that coefficient is defined through a solution of the PDE
  • REDUCED – indicator that coefficient is defined through a reduced solution of the PDE
  • DIRACDELTA – indicator that coefficient is defined as Dirac delta functions
  • BY_EQUATION – indicator that the dimension of the coefficient shape is defined by the number of PDE equations
  • BY_SOLUTION – indicator that the dimension of the coefficient shape is defined by the number of PDE solutions
  • BY_DIM – indicator that the dimension of the coefficient shape is defined by the spatial dimension
  • OPERATOR – indicator that the coefficient alters the operator of the PDE
  • RIGHTHANDSIDE – indicator that the coefficient alters the right hand side of the PDE
  • BOTH – indicator that the coefficient alters the operator as well as the right hand side of the PDE
BOTH = 12
BOUNDARY = 1
BOUNDARY_REDUCED = 14
BY_DIM = 7
BY_EQUATION = 5
BY_SOLUTION = 6
CONTACT = 2
CONTACT_REDUCED = 15
DIRACDELTA = 16
INTERIOR = 0
INTERIOR_REDUCED = 13
OPERATOR = 10
REDUCED = 4
RIGHTHANDSIDE = 11
SOLUTION = 3
definesNumEquation()

Checks if the coefficient allows to estimate the number of equations.

Returns:True if the coefficient allows an estimate of the number of equations, False otherwise
Return type:bool
definesNumSolutions()

Checks if the coefficient allows to estimate the number of solution components.

Returns:True if the coefficient allows an estimate of the number of solution components, False otherwise
Return type:bool
estimateNumEquationsAndNumSolutions(domain, shape=())

Tries to estimate the number of equations and number of solutions if the coefficient has the given shape.

Parameters:
  • domain (Domain) – domain on which the PDE uses the coefficient
  • shape (tuple of int values) – suggested shape of the coefficient
Returns:

the number of equations and number of solutions of the PDE if the coefficient has given shape. If no appropriate numbers could be identified, None is returned

Return type:

tuple of two int values or None

getFunctionSpace(domain, reducedEquationOrder=False, reducedSolutionOrder=False)

Returns the FunctionSpace of the coefficient.

Parameters:
  • domain (Domain) – domain on which the PDE uses the coefficient
  • reducedEquationOrder (bool) – True to indicate that reduced order is used to represent the equation
  • reducedSolutionOrder (bool) – True to indicate that reduced order is used to represent the solution
Returns:

FunctionSpace of the coefficient

Return type:

FunctionSpace

getShape(domain, numEquations=1, numSolutions=1)

Builds the required shape of the coefficient.

Parameters:
  • domain (Domain) – domain on which the PDE uses the coefficient
  • numEquations (int) – number of equations of the PDE
  • numSolutions (int) – number of components of the PDE solution
Returns:

shape of the coefficient

Return type:

tuple of int values

getValue()

Returns the value of the coefficient.

Returns:value of the coefficient
Return type:Data
isAlteringOperator()

Checks if the coefficient alters the operator of the PDE.

Returns:True if the operator of the PDE is changed when the coefficient is changed
Return type:bool
isAlteringRightHandSide()

Checks if the coefficient alters the right hand side of the PDE.

Return type:bool
Returns:True if the right hand side of the PDE is changed when the coefficient is changed, None otherwise.
resetValue()

Resets the coefficient value to the default.

setValue(domain, numEquations=1, numSolutions=1, reducedEquationOrder=False, reducedSolutionOrder=False, newValue=None)

Sets the value of the coefficient to a new value.

Parameters:
  • domain (Domain) – domain on which the PDE uses the coefficient
  • numEquations (int) – number of equations of the PDE
  • numSolutions (int) – number of components of the PDE solution
  • reducedEquationOrder (bool) – True to indicate that reduced order is used to represent the equation
  • reducedSolutionOrder (bool) – True to indicate that reduced order is used to represent the solution
  • newValue (any object that can be converted into a Data object with the appropriate shape and FunctionSpace) – number of components of the PDE solution
Raises:
  • IllegalCoefficientValue – if the shape of the assigned value does not match the shape of the coefficient
  • IllegalCoefficientFunctionSpace – if unable to interpolate value to appropriate function space
class esys.escriptcore.linearPDEs.Poisson(domain, debug=False)

Bases: esys.escriptcore.linearPDEs.LinearPDE

Class to define a Poisson equation problem. This is generally a LinearPDE of the form

-grad(grad(u)[j])[j] = f

with natural boundary conditions

n[j]*grad(u)[j] = 0

and constraints:

u=0 where q>0

alteredCoefficient(name)

Announces that coefficient name has been changed.

Parameters:name (string) – name of the coefficient affected
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
Note :if name is q or r, the method will not trigger a rebuild of the system as constraints are applied to the solved system.
checkReciprocalSymmetry(name0, name1, verbose=True)

Tests two coefficients for reciprocal symmetry.

Parameters:
  • name0 (str) – name of the first coefficient
  • name1 (str) – name of the second coefficient
  • verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed
Returns:

True if coefficients name0 and name1 are reciprocally symmetric.

Return type:

bool

checkSymmetricTensor(name, verbose=True)

Tests a coefficient for symmetry.

Parameters:
  • name (str) – name of the coefficient
  • verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed.
Returns:

True if coefficient name is symmetric

Return type:

bool

checkSymmetry(verbose=True)

Tests the PDE for symmetry.

Parameters:verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed.
Returns:True if the PDE is symmetric
Return type:bool
Note :This is a very expensive operation. It should be used for degugging only! The symmetry flag is not altered.
createCoefficient(name)

Creates a Data object corresponding to coefficient name.

Returns:the coefficient name initialized to 0
Return type:Data
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
createOperator()

Returns an instance of a new operator.

createRightHandSide()

Returns an instance of a new right hand side.

createSolution()

Returns an instance of a new solution.

getCoefficient(name)

Returns the value of the coefficient name of the general PDE.

Parameters:name (string) – name of the coefficient requested
Returns:the value of the coefficient name
Return type:Data
Raises IllegalCoefficient:
 invalid coefficient name
Note :This method is called by the assembling routine to map the Poisson equation onto the general PDE.
getCurrentOperator()

Returns the operator in its current state.

getCurrentRightHandSide()

Returns the right hand side in its current state.

getCurrentSolution()

Returns the solution in its current state.

getDim()

Returns the spatial dimension of the PDE.

Returns:the spatial dimension of the PDE domain
Return type:int
getDomain()

Returns the domain of the PDE.

Returns:the domain of the PDE
Return type:Domain
getDomainStatus()

Return the status indicator of the domain

getFlux(u=None)

Returns the flux J for a given u.

J[i,j]=(A[i,j,k,l]+A_reduced[A[i,j,k,l]]*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])u[k]-X[i,j]-X_reduced[i,j]

or

J[j]=(A[i,j]+A_reduced[i,j])*grad(u)[l]+(B[j]+B_reduced[j])u-X[j]-X_reduced[j]

Parameters:u (Data or None) – argument in the flux. If u is not present or equals None the current solution is used.
Returns:flux
Return type:Data
getFunctionSpaceForCoefficient(name)

Returns the FunctionSpace to be used for coefficient name.

Parameters:name (string) – name of the coefficient enquired
Returns:the function space to be used for coefficient name
Return type:FunctionSpace
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getFunctionSpaceForEquation()

Returns the FunctionSpace used to discretize the equation.

Returns:representation space of equation
Return type:FunctionSpace
getFunctionSpaceForSolution()

Returns the FunctionSpace used to represent the solution.

Returns:representation space of solution
Return type:FunctionSpace
getNumEquations()

Returns the number of equations.

Returns:the number of equations
Return type:int
Raises UndefinedPDEError:
 if the number of equations is not specified yet
getNumSolutions()

Returns the number of unknowns.

Returns:the number of unknowns
Return type:int
Raises UndefinedPDEError:
 if the number of unknowns is not specified yet
getOperator()

Returns the operator of the linear problem.

Returns:the operator of the problem
getOperatorType()

Returns the current system type.

getRequiredOperatorType()

Returns the system type which needs to be used by the current set up.

getResidual(u=None)

Returns the residual of u or the current solution if u is not present.

Parameters:u (Data or None) – argument in the residual calculation. It must be representable in self.getFunctionSpaceForSolution(). If u is not present or equals None the current solution is used.
Returns:residual of u
Return type:Data
getRightHandSide()

Returns the right hand side of the linear problem.

Returns:the right hand side of the problem
Return type:Data
getShapeOfCoefficient(name)

Returns the shape of the coefficient name.

Parameters:name (string) – name of the coefficient enquired
Returns:the shape of the coefficient name
Return type:tuple of int
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getSolution()

Returns the solution of the PDE.

Returns:the solution
Return type:Data
getSolverOptions()

Returns the solver options

Return type:SolverOptions
getSystem()

Returns the operator and right hand side of the PDE.

Returns:the discrete version of the PDE
Return type:tuple of Operator and Data
getSystemStatus()

Return the domain status used to build the current system

hasCoefficient(name)

Returns True if name is the name of a coefficient.

Parameters:name (string) – name of the coefficient enquired
Returns:True if name is the name of a coefficient of the general PDE, False otherwise
Return type:bool
initializeSystem()

Resets the system clearing the operator, right hand side and solution.

insertConstraint(rhs_only=False)

Applies the constraints defined by q and r to the PDE.

Parameters:rhs_only (bool) – if True only the right hand side is altered by the constraint
introduceCoefficients(**coeff)

Introduces new coefficients into the problem.

Use:

p.introduceCoefficients(A=PDECoef(...), B=PDECoef(...))

to introduce the coefficients A and B.

invalidateOperator()

Indicates the operator has to be rebuilt next time it is used.

invalidateRightHandSide()

Indicates the right hand side has to be rebuilt next time it is used.

invalidateSolution()

Indicates the PDE has to be resolved if the solution is requested.

invalidateSystem()

Announces that everything has to be rebuilt.

isOperatorValid()

Returns True if the operator is still valid.

isRightHandSideValid()

Returns True if the operator is still valid.

isSolutionValid()

Returns True if the solution is still valid.

isSymmetric()

Checks if symmetry is indicated.

Returns:True if a symmetric PDE is indicated, False otherwise
Return type:bool
Note :the method is equivalent to use getSolverOptions().isSymmetric()
isSystemValid()

Returns True if the system (including solution) is still vaild.

isUsingLumping()

Checks if matrix lumping is the current solver method.

Returns:True if the current solver method is lumping
Return type:bool
reduceEquationOrder()

Returns the status of order reduction for the equation.

Returns:True if reduced interpolation order is used for the representation of the equation, False otherwise
Return type:bool
reduceSolutionOrder()

Returns the status of order reduction for the solution.

Returns:True if reduced interpolation order is used for the representation of the solution, False otherwise
Return type:bool
resetAllCoefficients()

Resets all coefficients to their default values.

resetOperator()

Makes sure that the operator is instantiated and returns it initialized with zeros.

resetRightHandSide()

Sets the right hand side to zero.

resetRightHandSideCoefficients()

Resets all coefficients defining the right hand side

resetSolution()

Sets the solution to zero.

setDebug(flag)

Switches debug output on if flag is True otherwise it is switched off.

Parameters:flag (bool) – desired debug status
setDebugOff()

Switches debug output off.

setDebugOn()

Switches debug output on.

setReducedOrderForEquationOff()

Switches reduced order off for equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForEquationOn()

Switches reduced order on for equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForEquationTo(flag=False)

Sets order reduction state for equation representation according to flag.

Parameters:flag (bool) – if flag is True, the order reduction is switched on for equation representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForSolutionOff()

Switches reduced order off for solution representation

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set.
setReducedOrderForSolutionOn()

Switches reduced order on for solution representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForSolutionTo(flag=False)

Sets order reduction state for solution representation according to flag.

Parameters:flag (bool) – if flag is True, the order reduction is switched on for solution representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderOff()

Switches reduced order off for solution and equation representation

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderOn()

Switches reduced order on for solution and equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderTo(flag=False)

Sets order reduction state for both solution and equation representation according to flag.

Parameters:flag (bool) – if True, the order reduction is switched on for both solution and equation representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setSolution(u, validate=True)

Sets the solution assuming that makes the system valid with the tolrance defined by the solver options

setSolverOptions(options=None)

Sets the solver options.

Parameters:options (SolverOptions or None) – the new solver options. If equal None, the solver options are set to the default.
Note :The symmetry flag of options is overwritten by the symmetry flag of the LinearProblem.
setSymmetry(flag=False)

Sets the symmetry flag to flag.

Parameters:flag (bool) – If True, the symmetry flag is set otherwise reset.
Note :The method overwrites the symmetry flag set by the solver options
setSymmetryOff()

Clears the symmetry flag. :note: The method overwrites the symmetry flag set by the solver options

setSymmetryOn()

Sets the symmetry flag. :note: The method overwrites the symmetry flag set by the solver options

setSystemStatus(status=None)

Sets the system status to status if status is not present the current status of the domain is used.

setValue(**coefficients)

Sets new values to coefficients.

Parameters:
  • coefficients – new values assigned to coefficients
  • f (any type that can be cast to a Scalar object on Function) – value for right hand side f
  • q (any type that can be cast to a rank zero Data object on Solution or ReducedSolution depending on whether reduced order is used for the representation of the equation) – mask for location of constraints
Raises IllegalCoefficient:
 

if an unknown coefficient keyword is used

trace(text)

Prints the text message if debug mode is switched on.

Parameters:text (string) – message to be printed
validOperator()

Marks the operator as valid.

validRightHandSide()

Marks the right hand side as valid.

validSolution()

Marks the solution as valid.

class esys.escriptcore.linearPDEs.SolverOptions

Bases: object

this class defines the solver options for a linear or non-linear solver.

The option also supports the handling of diagnostic informations.

Typical usage is

opts=SolverOptions()
print(opts)
opts.resetDiagnostics()
u=solver(opts)
print("number of iteration steps: =",opts.getDiagnostics("num_iter"))
Variables:
  • DEFAULT – The default method used to solve the system of linear equations
  • DIRECT – The direct solver based on LDU factorization
  • CHOLEVSKY – The direct solver based on LDLt factorization (can only be applied for symmetric PDEs)
  • PCG – The preconditioned conjugate gradient method (can only be applied for symmetric PDEs)
  • CR – The conjugate residual method
  • CGS – The conjugate gradient square method
  • BICGSTAB – The stabilized Bi-Conjugate Gradient method
  • TFQMR – Transpose Free Quasi Minimal Residual method
  • MINRES – Minimum residual method
  • ILU0 – The incomplete LU factorization preconditioner with no fill-in
  • ILUT – The incomplete LU factorization preconditioner with fill-in
  • JACOBI – The Jacobi preconditioner
  • GMRES – The Gram-Schmidt minimum residual method
  • PRES20 – Special GMRES with restart after 20 steps and truncation after 5 residuals
  • ROWSUM_LUMPING – Matrix lumping using row sum
  • HRZ_LUMPING – Matrix lumping using the HRZ approach
  • NO_REORDERING – No matrix reordering allowed
  • MINIMUM_FILL_IN – Reorder matrix to reduce fill-in during factorization
  • NESTED_DISSECTION – Reorder matrix to improve load balancing during factorization
  • PASO – PASO solver package
  • SCSL – SGI SCSL solver library
  • MKL – Intel’s MKL solver library
  • UMFPACK – The UMFPACK library
  • TRILINOS – The TRILINOS parallel solver class library from Sandia National Labs
  • ITERATIVE – The default iterative solver
  • AMG – Algebraic Multi Grid
  • AMLI – Algebraic Multi Level Iteration
  • REC_ILU – recursive ILU0
  • RILU – relaxed ILU0
  • GAUSS_SEIDEL – Gauss-Seidel preconditioner
  • DEFAULT_REORDERING – the reordering method recommended by the solver
  • SUPER_LU – the Super_LU solver package
  • PASTIX – the Pastix direct solver_package
  • YAIR_SHAPIRA_COARSENING – AMG and AMLI coarsening method by Yair-Shapira
  • RUGE_STUEBEN_COARSENING – AMG and AMLI coarsening method by Ruge and Stueben
  • AGGREGATION_COARSENING – AMG and AMLI coarsening using (symmetric) aggregation
  • STANDARD_COARSENING – AMG and AMLI standard coarsening using mesure of importance of the unknowns
  • MIN_COARSE_MATRIX_SIZE – minimum size of the coarsest level matrix to use direct solver.
  • NO_PRECONDITIONER – no preconditioner is applied.
  • CLASSIC_INTERPOLATION_WITH_FF_COUPLING – classical interpolation in AMG with enforced
  • CLASSIC_INTERPOLATION – classical interpolation in AMG
  • DIRECT_INTERPOLATION – direct interploation in AMG
  • BOOMERAMG – Boomer AMG in hypre library
  • CIJP_FIXED_RANDOM_COARSENING – BoomerAMG parallel coarsening method CIJP by using fixed random vector
  • CIJP_COARSENING – BoomerAMG parallel coarsening method CIJP
  • PASO_FALGOUT_COARSENING – BoomerAMG parallel coarsening method falgout
  • PASO_PMIS_COARSENING – BoomerAMG parallel coarsening method PMIS
  • PASO_HMIS_COARSENING – BoomerAMG parallel coarsening method HMIS
  • BACKWARD_EULER – backward Euler scheme
  • CRANK_NICOLSON – Crank-Nicolson scheme
  • LINEAR_CRANK_NICOLSON – linerized Crank-Nicolson scheme
AGGREGATION_COARSENING = 35
AMG = 22
AMLI = 38
BACKWARD_EULER = 68
BICGSTAB = 6
BOOMERAMG = 60
CGS = 5
CHOLEVSKY = 2
CIJP_COARSENING = 62
CIJP_FIXED_RANDOM_COARSENING = 61
CLASSIC_INTERPOLATION = 51
CLASSIC_INTERPOLATION_WITH_FF_COUPLING = 50
CR = 4
CRANK_NICOLSON = 67
DEFAULT = 0
DEFAULT_REORDERING = 30
DIRECT = 1
DIRECT_INTERPOLATION = 52
FALGOUT_COARSENING = 63
GAUSS_SEIDEL = 28
GMRES = 11
HMIS_COARSENING = 65
HRZ_LUMPING = 14
ILU0 = 8
ILUT = 9
ITERATIVE = 20
JACOBI = 10
LINEAR_CRANK_NICOLSON = 66
LUMPING = 13
MINIMUM_FILL_IN = 18
MINRES = 27
MIN_COARSE_MATRIX_SIZE = 37
MKL = 15
NESTED_DISSECTION = 19
NONLINEAR_GMRES = 25
NO_PRECONDITIONER = 36
NO_REORDERING = 17
PASO = 21
PASTIX = 32
PCG = 3
PMIS_COARSENING = 64
PRES20 = 12
REC_ILU = 23
RILU = 29
ROWSUM_LUMPING = 13
RUGE_STUEBEN_COARSENING = 34
STANDARD_COARSENING = 39
SUPER_LU = 31
TFQMR = 26
TRILINOS = 24
UMFPACK = 16
YAIR_SHAPIRA_COARSENING = 33
acceptConvergenceFailure()

Returns True if a failure to meet the stopping criteria within the given number of iteration steps is not raising in exception. This is useful if a solver is used in a non-linear context where the non-linear solver can continue even if the returned the solution does not necessarily meet the stopping criteria. One can use the hasConverged method to check if the last call to the solver was successful.

Returns:True if a failure to achieve convergence is accepted.
Return type:bool
adaptInnerTolerance()

Returns True if the tolerance of the inner solver is selected automatically. Otherwise the inner tolerance set by setInnerTolerance is used.

Returns:True if inner tolerance adaption is chosen.
Return type:bool
getAMGInterpolation()

Returns key of the interpolation method for the AMG preconditioner

Return type:in the list SolverOptions.CLASSIC_INTERPOLATION_WITH_FF_COUPLING, SolverOptions.CLASSIC_INTERPOLATION, SolverOptions.DIRECT_INTERPOLATION
getAbsoluteTolerance()

Returns the absolute tolerance for the solver

Return type:float
getCoarsening()

Returns the key of the coarsening algorithm to be applied AMG or AMLI or BoomerAMG

Return type:in the list SolverOptions.DEFAULT, SolverOptions.YAIR_SHAPIRA_COARSENING, SolverOptions.RUGE_STUEBEN_COARSENING, SolverOptions.AGGREGATION_COARSENING, SolverOptions.CIJP_FIXED_RANDOM_COARSENING, SolverOptions.CIJP_COARSENING, SolverOptions.FALGOUT_COARSENING, SolverOptions.PMIS_COARSENING, SolverOptions.HMIS_COARSENING
getCoarseningThreshold()

Returns the threshold for coarsening in the algebraic multi level solver or preconditioner

Return type:float
getCycleType()

Returns the cyle type (V- or W-cycle) to be used in an algebraic multi level solver or preconditioner

Return type:int
getDiagnostics(name)

Returns the diagnostic information name. Possible values are:

  • “num_iter”: the number of iteration steps
  • “cum_num_iter”: the cumulative number of iteration steps
  • “num_level”: the number of level in multi level solver
  • “num_inner_iter”: the number of inner iteration steps
  • “cum_num_inner_iter”: the cumulative number of inner iteration steps
  • “time”: execution time
  • “cum_time”: cumulative execution time
  • “set_up_time”: time to set up of the solver, typically this includes factorization and reordering
  • “cum_set_up_time”: cumulative time to set up of the solver
  • “net_time”: net execution time, excluding setup time for the solver and execution time for preconditioner
  • “cum_net_time”: cumulative net execution time
  • “preconditioner_size”: size of preconditioner [Bytes]
  • “converged”: return True if solution has converged.
  • “time_step_backtracking_used”: returns True if time step back tracking has been used.
  • “coarse_level_sparsity”: returns the sparsity of the matrix on the coarsest level
  • “num_coarse_unknowns”: returns the number of unknowns on the coarsest level
Parameters:name (str in the list above.) – name of diagnostic information to return
Returns:requested value. None is returned if the value is undefined.
Note :If the solver has thrown an exception diagnostic values have an undefined status.
getDiagonalDominanceThreshold()

Returns the threshold for diagonal dominant rows which are eliminated during AMG coarsening.

Return type:float
getDropStorage()

Returns the maximum allowed increase in storage for ILUT

Return type:float
getDropTolerance()

Returns the relative drop tolerance in ILUT

Return type:float
getInnerIterMax()

Returns maximum number of inner iteration steps

Return type:int
getInnerTolerance()

Returns the relative tolerance for an inner iteration scheme

Return type:float
getIterMax()

Returns maximum number of iteration steps

Return type:int
getLevelMax()

Returns the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner

Return type:int
getMinCoarseMatrixSize()

Returns the minimum size of the coarsest level matrix in AMG or AMLI

Return type:int
getMinCoarseMatrixSparsity()

Returns the minimum sparsity on the coarsest level. Typically a direct solver is used when the sparsity becomes bigger than the set limit.

Returns:minimual sparsity
Return type:float
getName(key)

returns the name of a given key

Parameters:key – a valid key
getNumCoarseMatrixRefinements()

Returns the number of resfinement steps to refine the solution on the coarset level when a direct solver is applied.

Return type:non-negative int
getNumPostSweeps()

Returns he number of sweeps in the post-smoothing step of a multi level solver or preconditioner

Return type:int
getNumPreSweeps()

Returns he number of sweeps in the pre-smoothing step of a multi level solver or preconditioner

Return type:int
getNumRefinements()

Returns the number of refinement steps to refine the solution when a direct solver is applied.

Return type:non-negative int
getNumSweeps()

Returns the number of sweeps in a Jacobi or Gauss-Seidel/SOR preconditioner.

Return type:int
getODESolver(method=None)

Returns key of the solver method for ODEs.

Parameters:method (in SolverOptions.CRANK_NICOLSON, SolverOptions.BACKWARD_EULER, SolverOptions.LINEAR_CRANK_NICOLSON) – key of the ODE solver method to be used.
getPackage()

Returns the solver package key

Return type:in the list SolverOptions.DEFAULT, SolverOptions.PASO, SolverOptions.SUPER_LU, SolverOptions.PASTIX, SolverOptions.MKL, SolverOptions.UMFPACK, SolverOptions.TRILINOS
getPreconditioner()

Returns the key of the preconditioner to be used.

Return type:in the list SolverOptions.ILU0, SolverOptions.ILUT, SolverOptions.JACOBI, SolverOptions.AMLI, SolverOptions.AMG, SolverOptions.REC_ILU, SolverOptions.GAUSS_SEIDEL, SolverOptions.RILU, SolverOptions.BOOMERAMG, SolverOptions.NO_PRECONDITIONER
getRelaxationFactor()

Returns the relaxation factor used to add dropped elements in RILU to the main diagonal.

Return type:float
getReordering()

Returns the key of the reordering method to be applied if supported by the solver.

Return type:in SolverOptions.NO_REORDERING, SolverOptions.MINIMUM_FILL_IN, SolverOptions.NESTED_DISSECTION, SolverOptions.DEFAULT_REORDERING
getRestart()

Returns the number of iterations steps after which GMRES is performing a restart. If None is returned no restart is performed.

Return type:int or None
getSmoother()

Returns key of the smoother to be used.

Return type:in the list SolverOptions.JACOBI, SolverOptions.GAUSS_SEIDEL
getSolverMethod()

Returns key of the solver method to be used.

Return type:in the list SolverOptions.DEFAULT, SolverOptions.DIRECT, SolverOptions.CHOLEVSKY, SolverOptions.PCG, SolverOptions.CR, SolverOptions.CGS, SolverOptions.BICGSTAB, SolverOptions.GMRES, SolverOptions.PRES20, SolverOptions.ROWSUM_LUMPING, SolverOptions.HRZ_LUMPING, SolverOptions.ITERATIVE, SolverOptions.NONLINEAR_GMRES, SolverOptions.TFQMR, SolverOptions.MINRES
getSummary()

Returns a string reporting the current settings

getTolerance()

Returns the relative tolerance for the solver

Return type:float
getTruncation()

Returns the number of residuals in GMRES to be stored for orthogonalization

Return type:int
hasConverged()

Returns True if the last solver call has been finalized successfully. :note: if an exception has been thrown by the solver the status of this flag is undefined.

isSymmetric()

Checks if symmetry of the coefficient matrix is indicated.

Returns:True if a symmetric PDE is indicated, False otherwise
Return type:bool
isVerbose()

Returns True if the solver is expected to be verbose.

Returns:True if verbosity of switched on.
Return type:bool
resetDiagnostics(all=False)

resets the diagnostics

Parameters:all (bool) – if all is True all diagnostics including accumulative counters are reset.
setAMGInterpolation(method=None)

Set the interpolation method for the AMG preconditioner.

Parameters:method (in SolverOptions.CLASSIC_INTERPOLATION_WITH_FF_COUPLING, SolverOptions.CLASSIC_INTERPOLATION, SolverOptions.DIRECT_INTERPOLATION) – key of the interpolation method to be used.
setAbsoluteTolerance(atol=0.0)

Sets the absolute tolerance for the solver

Parameters:atol (non-negative float) – absolute tolerance
setAcceptanceConvergenceFailure(accept=False)

Sets the flag to indicate the acceptance of a failure of convergence.

Parameters:accept (bool) – If True, any failure to achieve convergence is accepted.
setAcceptanceConvergenceFailureOff()

Switches the acceptance of a failure of convergence off.

setAcceptanceConvergenceFailureOn()

Switches the acceptance of a failure of convergence on

setCoarsening(method=0)

Sets the key of the coarsening method to be applied in AMG or AMLI or BoomerAMG

Parameters:method (in {SolverOptions.DEFAULT}, SolverOptions.YAIR_SHAPIRA_COARSENING, SolverOptions.RUGE_STUEBEN_COARSENING, SolverOptions.AGGREGATION_COARSENING, SolverOptions.CIJP_FIXED_RANDOM_COARSENING, SolverOptions.CIJP_COARSENING, SolverOptions.FALGOUT_COARSENING, SolverOptions.PMIS_COARSENING, SolverOptions.HMIS_COARSENING) – selects the coarsening method .
setCoarseningThreshold(theta=0.25)

Sets the threshold for coarsening in the algebraic multi level solver or preconditioner

Parameters:theta (positive float) – threshold for coarsening
setCycleType(cycle_type=1)

Sets the cycle type (V-cycle or W-cycle) to be used in an algebraic multi level solver or preconditioner

Parameters:cycle_type (int) – the type of cycle
setDiagonalDominanceThreshold(value=0.5)

Sets the threshold for diagonal dominant rows which are eliminated during AMG coarsening.

Parameters:value (float) – threshold
setDropStorage(storage=2.0)

Sets the maximum allowed increase in storage for ILUT. storage =2 would mean that a doubling of the storage needed for the coefficient matrix is allowed in the ILUT factorization.

Parameters:storage (float) – allowed storage increase
setDropTolerance(drop_tol=0.01)

Sets the relative drop tolerance in ILUT

Parameters:drop_tol (positive float) – drop tolerance
setInnerIterMax(iter_max=10)

Sets the maximum number of iteration steps for the inner iteration.

Parameters:iter_max (int) – maximum number of inner iterations
setInnerTolerance(rtol=0.9)

Sets the relative tolerance for an inner iteration scheme for instance on the coarsest level in a multi-level scheme.

Parameters:rtol (positive float) – inner relative tolerance
setInnerToleranceAdaption(adapt=True)

Sets the flag to indicate automatic selection of the inner tolerance.

Parameters:adapt (bool) – If True, the inner tolerance is selected automatically.
setInnerToleranceAdaptionOff()

Switches the automatic selection of inner tolerance off.

setInnerToleranceAdaptionOn()

Switches the automatic selection of inner tolerance on

setIterMax(iter_max=100000)

Sets the maximum number of iteration steps

Parameters:iter_max (int) – maximum number of iteration steps
setLevelMax(level_max=100)

Sets the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner

Parameters:level_max (int) – maximum number of levels
setLocalPreconditioner(use=False)

Sets the flag to use local preconditioning

Parameters:use (bool) – If True, local proconditioning on each MPI rank is applied
setLocalPreconditionerOff()

Sets the flag to use local preconditioning to off

setLocalPreconditionerOn()

Sets the flag to use local preconditioning to on

setMinCoarseMatrixSize(size=None)

Sets the minumum size of the coarsest level matrix in AMG or AMLI

Parameters:size (positive int or None) – minumum size of the coarsest level matrix .
setMinCoarseMatrixSparsity(sparsity=0.05)

Sets the minimum sparsity on the coarsest level. Typically a direct solver is used when the sparsity becomes bigger than the set limit.

Parameters:sparsity (float) – minimual sparsity
setNumCoarseMatrixRefinements(refinements=2)

Sets the number of refinement steps to refine the solution on the coarset level when a direct solver is applied.

Parameters:refinements (non-negative int) – number of refinements
setNumPostSweeps(sweeps=1)

Sets the number of sweeps in the post-smoothing step of a multi level solver or preconditioner

Parameters:sweeps (positive int) – number of sweeps
setNumPreSweeps(sweeps=1)

Sets the number of sweeps in the pre-smoothing step of a multi level solver or preconditioner

Parameters:sweeps (positive int) – number of sweeps
setNumRefinements(refinements=2)

Sets the number of refinement steps to refine the solution when a direct solver is applied.

Parameters:refinements (non-negative int) – number of refinements
setNumSweeps(sweeps=1)

Sets the number of sweeps in a Jacobi or Gauss-Seidel/SOR preconditioner.

Parameters:sweeps (positive int) – number of sweeps
setODESolver(method=None)

Set the solver method for ODEs.

Parameters:method (in SolverOptions.CRANK_NICOLSON, SolverOptions.BACKWARD_EULER, SolverOptions.LINEAR_CRANK_NICOLSON) – key of the ODE solver method to be used.
setPackage(package=0)

Sets the solver package to be used as a solver.

Parameters:package (in SolverOptions.DEFAULT, SolverOptions.PASO, SolverOptions.SUPER_LU, SolverOptions.PASTIX, SolverOptions.MKL, SolverOptions.UMFPACK, SolverOptions.TRILINOS) – key of the solver package to be used.
Note :Not all packages are support on all implementation. An exception may be thrown on some platforms if a particular is requested.
setPreconditioner(preconditioner=10)

Sets the preconditioner to be used.

Parameters:preconditioner (in SolverOptions.ILU0, SolverOptions.ILUT, SolverOptions.JACOBI, SolverOptions.AMG, SolverOptions.AMLI, SolverOptions.REC_ILU, SolverOptions.GAUSS_SEIDEL, SolverOptions.RILU, SolverOptions.BOOMERAMG, SolverOptions.NO_PRECONDITIONER) – key of the preconditioner to be used.
Note :Not all packages support all preconditioner. It can be assumed that a package makes a reasonable choice if it encounters an unknown preconditioner.
setRelaxationFactor(factor=0.3)

Sets the relaxation factor used to add dropped elements in RILU to the main diagonal.

Parameters:factor (float) – relaxation factor
Note :RILU with a relaxation factor 0 is identical to ILU0
setReordering(ordering=30)

Sets the key of the reordering method to be applied if supported by the solver. Some direct solvers support reordering to optimize compute time and storage use during elimination.

Parameters:ordering (in ‘SolverOptions.NO_REORDERING’, ‘SolverOptions.MINIMUM_FILL_IN’, ‘SolverOptions.NESTED_DISSECTION’, ‘SolverOptions.DEFAULT_REORDERING’) – selects the reordering strategy.
setRestart(restart=None)

Sets the number of iterations steps after which GMRES perfors a restart.

Parameters:restart (int or None) – number of iteration steps after which to perform a restart. If None no restart is performed.
setSmoother(smoother=None)

Sets the smoother to be used.

Parameters:smoother (in SolverOptions.JACOBI, SolverOptions.GAUSS_SEIDEL) – key of the smoother to be used.
Note :Not all packages support all smoothers. It can be assumed that a package makes a reasonable choice if it encounters an unknown smoother.
setSolverMethod(method=0)

Sets the solver method to be used. Use method``=``SolverOptions.DIRECT to indicate that a direct rather than an iterative solver should be used and Use method``=``SolverOptions.ITERATIVE to indicate that an iterative rather than a direct solver should be used.

Parameters:method (in SolverOptions.DEFAULT, SolverOptions.DIRECT, SolverOptions.CHOLEVSKY, SolverOptions.PCG, SolverOptions.CR, SolverOptions.CGS, SolverOptions.BICGSTAB, SolverOptions.GMRES, SolverOptions.PRES20, SolverOptions.ROWSUM_LUMPING, SolverOptions.HRZ_LUMPING, SolverOptions.ITERATIVE, SolverOptions.NONLINEAR_GMRES, SolverOptions.TFQMR, SolverOptions.MINRES) – key of the solver method to be used.
Note :Not all packages support all solvers. It can be assumed that a package makes a reasonable choice if it encounters an unknown solver method.
setSymmetry(flag=False)

Sets the symmetry flag for the coefficient matrix to flag.

Parameters:flag (bool) – If True, the symmetry flag is set otherwise reset.
setSymmetryOff()

Clears the symmetry flag for the coefficient matrix.

setSymmetryOn()

Sets the symmetry flag to indicate that the coefficient matrix is symmetric.

setTolerance(rtol=1e-08)

Sets the relative tolerance for the solver

Parameters:rtol (non-negative float) – relative tolerance
setTruncation(truncation=20)

Sets the number of residuals in GMRES to be stored for orthogonalization. The more residuals are stored the faster GMRES converged but

Parameters:truncation (int) – truncation
setUsePanel(use=True)

Sets the flag to use a panel to find unknowns in AMG coarsening

Parameters:use (bool) – If True,a panel is used to find unknowns in AMG coarsening
setUsePanelOff()

Sets the flag to use a panel to find unknowns in AMG coarsening to off

setUsePanelOn()

Sets the flag to use a panel to find unknowns in AMG coarsening

setVerbosity(verbose=False)

Sets the verbosity flag for the solver to flag.

Parameters:verbose (bool) – If True, the verbosity of the solver is switched on.
setVerbosityOff()

Switches the verbosity of the solver off.

setVerbosityOn()

Switches the verbosity of the solver on.

useLocalPreconditioner()

Returns True if the preconditoner is applied locally on each MPI. This reducess communication costs and speeds up the application of the preconditioner but at the costs of more iteration steps. This can be an advantage on clusters with slower interconnects.

Returns:True if local preconditioning is applied
Return type:bool
usePanel()

Returns True if a panel is used to serach for unknown in the AMG coarsening, The panel approach is normally faster but can lead to larger coarse level systems.

Returns:True if a panel is used to find unknowns in AMG coarsening
Return type:bool
class esys.escriptcore.linearPDEs.TransportPDE(domain, numEquations=None, numSolutions=None, useBackwardEuler=None, debug=False)

Bases: esys.escriptcore.linearPDEs.LinearProblem

This class is used to define a transport problem given by a general linear, time dependent, second order PDE for an unknown, non-negative, time-dependent function u on a given domain defined through a Domain object.

For a single equation with a solution with a single component the transport problem is defined in the following form:

(M+M_reduced)*u_t=-(grad(A[j,l]+A_reduced[j,l]) * grad(u)[l]+(B[j]+B_reduced[j])u)[j]+(C[l]+C_reduced[l])*grad(u)[l]+(D+D_reduced)-grad(X+X_reduced)[j,j]+(Y+Y_reduced)

where u_t denotes the time derivative of u and grad(F) denotes the spatial derivative of F. Einstein’s summation convention, ie. summation over indexes appearing twice in a term of a sum performed, is used. The coefficients M, A, B, C, D, X and Y have to be specified through Data objects in Function and the coefficients M_reduced, A_reduced, B_reduced, C_reduced, D_reduced, X_reduced and Y_reduced have to be specified through Data objects in ReducedFunction. It is also allowed to use objects that can be converted into such Data objects. M and M_reduced are scalar, A and A_reduced are rank two, B, C, X, B_reduced, C_reduced and X_reduced are rank one and D, D_reduced, Y and Y_reduced are scalar.

The following natural boundary conditions are considered:

n[j]*((A[i,j]+A_reduced[i,j])*grad(u)[l]+(B+B_reduced)[j]*u+X[j]+X_reduced[j])+(d+d_reduced)*u+y+y_reduced=(m+m_reduced)*u_t

where n is the outer normal field. Notice that the coefficients A, A_reduced, B, B_reduced, X and X_reduced are defined in the transport problem. The coefficients m, d and y are each a scalar in FunctionOnBoundary and the coefficients m_reduced, d_reduced and y_reduced are each a scalar in ReducedFunctionOnBoundary.

Constraints for the solution prescribing the value of the solution at certain locations in the domain have the form

u_t=r where q>0

r and q are each scalar where q is the characteristic function defining where the constraint is applied. The constraints override any other condition set by the transport problem or the boundary condition.

The transport problem is symmetrical if

A[i,j]=A[j,i] and B[j]=C[j] and A_reduced[i,j]=A_reduced[j,i] and B_reduced[j]=C_reduced[j]

For a system and a solution with several components the transport problem has the form

(M[i,k]+M_reduced[i,k]) * u[k]_t=-grad((A[i,j,k,l]+A_reduced[i,j,k,l]) * grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k]) * u[k])[j]+(C[i,k,l]+C_reduced[i,k,l]) * grad(u[k])[l]+(D[i,k]+D_reduced[i,k] * u[k]-grad(X[i,j]+X_reduced[i,j])[j]+Y[i]+Y_reduced[i]

A and A_reduced are of rank four, B, B_reduced, C and C_reduced are each of rank three, M, M_reduced, D, D_reduced, X_reduced and X are each of rank two and Y and Y_reduced are of rank one. The natural boundary conditions take the form:

n[j]*((A[i,j,k,l]+A_reduced[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k]+X[i,j]+X_reduced[i,j])+(d[i,k]+d_reduced[i,k])*u[k]+y[i]+y_reduced[i]= (m[i,k]+m_reduced[i,k])*u[k]_t

The coefficient d and m are of rank two and y is of rank one with all in FunctionOnBoundary. The coefficients d_reduced and m_reduced are of rank two and y_reduced is of rank one all in ReducedFunctionOnBoundary.

Constraints take the form

u[i]_t=r[i] where q[i]>0

r and q are each rank one. Notice that at some locations not necessarily all components must have a constraint.

The transport problem is symmetrical if

  • M[i,k]=M[i,k]
  • M_reduced[i,k]=M_reduced[i,k]
  • A[i,j,k,l]=A[k,l,i,j]
  • A_reduced[i,j,k,l]=A_reduced[k,l,i,j]
  • B[i,j,k]=C[k,i,j]
  • B_reduced[i,j,k]=C_reduced[k,i,j]
  • D[i,k]=D[i,k]
  • D_reduced[i,k]=D_reduced[i,k]
  • m[i,k]=m[k,i]
  • m_reduced[i,k]=m_reduced[k,i]
  • d[i,k]=d[k,i]
  • d_reduced[i,k]=d_reduced[k,i]
  • d_dirac[i,k]=d_dirac[k,i]

TransportPDE also supports solution discontinuities over a contact region in the domain. To specify the conditions across the discontinuity we are using the generalised flux J which, in the case of a system of PDEs and several components of the solution, is defined as

J[i,j]=(A[i,j,k,l]+A_reduced[[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k]+X[i,j]+X_reduced[i,j]

For the case of single solution component and single PDE J is defined as

J[j]=(A[i,j]+A_reduced[i,j])*grad(u)[j]+(B[i]+B_reduced[i])*u+X[i]+X_reduced[i]

In the context of discontinuities n denotes the normal on the discontinuity pointing from side 0 towards side 1 calculated from FunctionSpace.getNormal of FunctionOnContactZero. For a system of transport problems the contact condition takes the form

n[j]*J0[i,j]=n[j]*J1[i,j]=(y_contact[i]+y_contact_reduced[i])- (d_contact[i,k]+d_contact_reduced[i,k])*jump(u)[k]

where J0 and J1 are the fluxes on side 0 and side 1 of the discontinuity, respectively. jump(u), which is the difference of the solution at side 1 and at side 0, denotes the jump of u across discontinuity along the normal calculated by jump. The coefficient d_contact is of rank two and y_contact is of rank one both in FunctionOnContactZero or FunctionOnContactOne. The coefficient d_contact_reduced is of rank two and y_contact_reduced is of rank one both in ReducedFunctionOnContactZero or ReducedFunctionOnContactOne. In case of a single PDE and a single component solution the contact condition takes the form

n[j]*J0_{j}=n[j]*J1_{j}=(y_contact+y_contact_reduced)-(d_contact+y_contact_reduced)*jump(u)

In this case the coefficient d_contact and y_contact are each scalar both in FunctionOnContactZero or FunctionOnContactOne and the coefficient d_contact_reduced and y_contact_reduced are each scalar both in ReducedFunctionOnContactZero or ReducedFunctionOnContactOne.

Typical usage:

p = TransportPDE(dom)
p.setValue(M=1., C=[-1.,0.])
p.setInitialSolution(u=exp(-length(dom.getX()-[0.1,0.1])**2)
t = 0
dt = 0.1
while (t < 1.):
    u = p.solve(dt)
alteredCoefficient(name)

Announces that coefficient name has been changed.

Parameters:name (string) – name of the coefficient affected
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
Note :if name is q or r, the method will not trigger a rebuild of the system as constraints are applied to the solved system.
checkReciprocalSymmetry(name0, name1, verbose=True)

Tests two coefficients for reciprocal symmetry.

Parameters:
  • name0 (str) – name of the first coefficient
  • name1 (str) – name of the second coefficient
  • verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed
Returns:

True if coefficients name0 and name1 are reciprocally symmetric.

Return type:

bool

checkSymmetricTensor(name, verbose=True)

Tests a coefficient for symmetry.

Parameters:
  • name (str) – name of the coefficient
  • verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed.
Returns:

True if coefficient name is symmetric

Return type:

bool

checkSymmetry(verbose=True)

Tests the transport problem for symmetry.

Parameters:verbose (bool) – if set to True or not present a report on coefficients which break the symmetry is printed.
Returns:True if the PDE is symmetric
Return type:bool
Note :This is a very expensive operation. It should be used for degugging only! The symmetry flag is not altered.
createCoefficient(name)

Creates a Data object corresponding to coefficient name.

Returns:the coefficient name initialized to 0
Return type:Data
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
createOperator()

Returns an instance of a new transport operator.

createRightHandSide()

Returns an instance of a new right hand side.

createSolution()

Returns an instance of a new solution.

getCoefficient(name)

Returns the value of the coefficient name.

Parameters:name (string) – name of the coefficient requested
Returns:the value of the coefficient
Return type:Data
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getCurrentOperator()

Returns the operator in its current state.

getCurrentRightHandSide()

Returns the right hand side in its current state.

getCurrentSolution()

Returns the solution in its current state.

getDim()

Returns the spatial dimension of the PDE.

Returns:the spatial dimension of the PDE domain
Return type:int
getDomain()

Returns the domain of the PDE.

Returns:the domain of the PDE
Return type:Domain
getDomainStatus()

Return the status indicator of the domain

getFunctionSpaceForCoefficient(name)

Returns the FunctionSpace to be used for coefficient name.

Parameters:name (string) – name of the coefficient enquired
Returns:the function space to be used for coefficient name
Return type:FunctionSpace
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getFunctionSpaceForEquation()

Returns the FunctionSpace used to discretize the equation.

Returns:representation space of equation
Return type:FunctionSpace
getFunctionSpaceForSolution()

Returns the FunctionSpace used to represent the solution.

Returns:representation space of solution
Return type:FunctionSpace
getNumEquations()

Returns the number of equations.

Returns:the number of equations
Return type:int
Raises UndefinedPDEError:
 if the number of equations is not specified yet
getNumSolutions()

Returns the number of unknowns.

Returns:the number of unknowns
Return type:int
Raises UndefinedPDEError:
 if the number of unknowns is not specified yet
getOperator()

Returns the operator of the linear problem.

Returns:the operator of the problem
getOperatorType()

Returns the current system type.

getRequiredOperatorType()

Returns the system type which needs to be used by the current set up.

Returns:a code to indicate the type of transport problem scheme used
Return type:float
getRightHandSide()

Returns the right hand side of the linear problem.

Returns:the right hand side of the problem
Return type:Data
getSafeTimeStepSize()

Returns a safe time step size to do the next time step.

Returns:safe time step size
Return type:float
Note :If not getSafeTimeStepSize() < getUnlimitedTimeStepSize() any time step size can be used.
getShapeOfCoefficient(name)

Returns the shape of the coefficient name.

Parameters:name (string) – name of the coefficient enquired
Returns:the shape of the coefficient name
Return type:tuple of int
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getSolution(dt=None, u0=None)

Returns the solution by marching forward by time step dt. if ‘’u0’’ is present, ‘’u0’’ is used as the initial value otherwise the solution from the last call is used.

Parameters:
  • dt (positive float or None) – time step size. If None the last solution is returned.
  • u0 (any object that can be interpolated to a Data object on Solution or ReducedSolution) – new initial solution or None
Returns:

the solution

Return type:

Data

getSolverOptions()

Returns the solver options

Return type:SolverOptions
getSystem()

Returns the operator and right hand side of the PDE.

Returns:the discrete version of the PDE
Return type:tuple of Operator and Data
getSystemStatus()

Return the domain status used to build the current system

getUnlimitedTimeStepSize()

Returns the value returned by the getSafeTimeStepSize method to indicate no limit on the safe time step size.

return:the value used to indicate that no limit is set to the time step size
rtype:float
note:Typically the biggest positive float is returned
hasCoefficient(name)

Returns True if name is the name of a coefficient.

Parameters:name (string) – name of the coefficient enquired
Returns:True if name is the name of a coefficient of the general PDE, False otherwise
Return type:bool
initializeSystem()

Resets the system clearing the operator, right hand side and solution.

introduceCoefficients(**coeff)

Introduces new coefficients into the problem.

Use:

p.introduceCoefficients(A=PDECoef(...), B=PDECoef(...))

to introduce the coefficients A and B.

invalidateOperator()

Indicates the operator has to be rebuilt next time it is used.

invalidateRightHandSide()

Indicates the right hand side has to be rebuilt next time it is used.

invalidateSolution()

Indicates the PDE has to be resolved if the solution is requested.

invalidateSystem()

Announces that everything has to be rebuilt.

isOperatorValid()

Returns True if the operator is still valid.

isRightHandSideValid()

Returns True if the operator is still valid.

isSolutionValid()

Returns True if the solution is still valid.

isSymmetric()

Checks if symmetry is indicated.

Returns:True if a symmetric PDE is indicated, False otherwise
Return type:bool
Note :the method is equivalent to use getSolverOptions().isSymmetric()
isSystemValid()

Returns True if the system (including solution) is still vaild.

isUsingLumping()

Checks if matrix lumping is the current solver method.

Returns:True if the current solver method is lumping
Return type:bool
reduceEquationOrder()

Returns the status of order reduction for the equation.

Returns:True if reduced interpolation order is used for the representation of the equation, False otherwise
Return type:bool
reduceSolutionOrder()

Returns the status of order reduction for the solution.

Returns:True if reduced interpolation order is used for the representation of the solution, False otherwise
Return type:bool
resetAllCoefficients()

Resets all coefficients to their default values.

resetOperator()

Makes sure that the operator is instantiated and returns it initialized with zeros.

resetRightHandSide()

Sets the right hand side to zero.

resetRightHandSideCoefficients()

Resets all coefficients defining the right hand side

resetSolution()

Sets the solution to zero.

setDebug(flag)

Switches debug output on if flag is True, otherwise it is switched off.

Parameters:flag (bool) – desired debug status
setDebugOff()

Switches debug output off.

setDebugOn()

Switches debug output on.

setInitialSolution(u)

Sets the initial solution.

Parameters:u (any object that can be interpolated to a Data object on Solution or ReducedSolution) – initial solution
setReducedOrderForEquationOff()

Switches reduced order off for equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForEquationOn()

Switches reduced order on for equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForEquationTo(flag=False)

Sets order reduction state for equation representation according to flag.

Parameters:flag (bool) – if flag is True, the order reduction is switched on for equation representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForSolutionOff()

Switches reduced order off for solution representation

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set.
setReducedOrderForSolutionOn()

Switches reduced order on for solution representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderForSolutionTo(flag=False)

Sets order reduction state for solution representation according to flag.

Parameters:flag (bool) – if flag is True, the order reduction is switched on for solution representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderOff()

Switches reduced order off for solution and equation representation

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderOn()

Switches reduced order on for solution and equation representation.

Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setReducedOrderTo(flag=False)

Sets order reduction state for both solution and equation representation according to flag.

Parameters:flag (bool) – if True, the order reduction is switched on for both solution and equation representation, otherwise or if flag is not present order reduction is switched off
Raises RuntimeError:
 if order reduction is altered after a coefficient has been set
setSolution(u, validate=True)

Sets the solution assuming that makes the system valid with the tolrance defined by the solver options

setSolverOptions(options=None)

Sets the solver options.

Parameters:options (SolverOptions or None) – the new solver options. If equal None, the solver options are set to the default.
Note :The symmetry flag of options is overwritten by the symmetry flag of the LinearProblem.
setSymmetry(flag=False)

Sets the symmetry flag to flag.

Parameters:flag (bool) – If True, the symmetry flag is set otherwise reset.
Note :The method overwrites the symmetry flag set by the solver options
setSymmetryOff()

Clears the symmetry flag. :note: The method overwrites the symmetry flag set by the solver options

setSymmetryOn()

Sets the symmetry flag. :note: The method overwrites the symmetry flag set by the solver options

setSystemStatus(status=None)

Sets the system status to status if status is not present the current status of the domain is used.

setValue(**coefficients)

Sets new values to coefficients.

Parameters:
  • coefficients – new values assigned to coefficients
  • M (any type that can be cast to a Data object on Function) – value for coefficient M
  • M_reduced (any type that can be cast to a Data object on Function) – value for coefficient M_reduced
  • A (any type that can be cast to a Data object on Function) – value for coefficient A
  • A_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient A_reduced
  • B (any type that can be cast to a Data object on Function) – value for coefficient B
  • B_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient B_reduced
  • C (any type that can be cast to a Data object on Function) – value for coefficient C
  • C_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient C_reduced
  • D (any type that can be cast to a Data object on Function) – value for coefficient D
  • D_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient D_reduced
  • X (any type that can be cast to a Data object on Function) – value for coefficient X
  • X_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient X_reduced
  • Y (any type that can be cast to a Data object on Function) – value for coefficient Y
  • Y_reduced (any type that can be cast to a Data object on ReducedFunction) – value for coefficient Y_reduced
  • m (any type that can be cast to a Data object on FunctionOnBoundary) – value for coefficient m
  • m_reduced (any type that can be cast to a Data object on FunctionOnBoundary) – value for coefficient m_reduced
  • d (any type that can be cast to a Data object on FunctionOnBoundary) – value for coefficient d
  • d_reduced (any type that can be cast to a Data object on ReducedFunctionOnBoundary) – value for coefficient d_reduced
  • y (any type that can be cast to a Data object on FunctionOnBoundary) – value for coefficient y
  • d_contact (any type that can be cast to a Data object on FunctionOnContactOne or FunctionOnContactZero) – value for coefficient d_contact
  • d_contact_reduced (any type that can be cast to a Data object on ReducedFunctionOnContactOne or ReducedFunctionOnContactZero) – value for coefficient d_contact_reduced
  • y_contact (any type that can be cast to a Data object on FunctionOnContactOne or FunctionOnContactZero) – value for coefficient y_contact
  • y_contact_reduced (any type that can be cast to a Data object on ReducedFunctionOnContactOne or ReducedFunctionOnContactZero) – value for coefficient y_contact_reduced
  • d_dirac (any type that can be cast to a Data object on DiracDeltaFunctions) – value for coefficient d_dirac
  • y_dirac (any type that can be cast to a Data object on DiracDeltaFunctions) – value for coefficient y_dirac
  • r (any type that can be cast to a Data object on Solution or ReducedSolution depending on whether reduced order is used for the solution) – values prescribed to the solution at the locations of constraints
  • q (any type that can be cast to a Data object on Solution or ReducedSolution depending on whether reduced order is used for the representation of the equation) – mask for the location of constraints
Raises IllegalCoefficient:
 

if an unknown coefficient keyword is used

trace(text)

Prints the text message if debug mode is switched on.

Parameters:text (string) – message to be printed
validOperator()

Marks the operator as valid.

validRightHandSide()

Marks the right hand side as valid.

validSolution()

Marks the solution as valid.

class esys.escriptcore.linearPDEs.UndefinedPDEError

Bases: exceptions.ValueError

Exception that is raised if a PDE is not fully defined yet.

args
message

Functions

esys.escriptcore.linearPDEs.LinearPDESystem(domain, debug=False)

Defines a system of linear PDEs.

Parameters:
  • domain (Domain) – domain of the PDEs
  • debug – if True debug information is printed
Return type:

LinearPDE

esys.escriptcore.linearPDEs.LinearSinglePDE(domain, debug=False)

Defines a single linear PDE.

Parameters:
  • domain (Domain) – domain of the PDE
  • debug – if True debug information is printed
Return type:

LinearPDE

esys.escriptcore.linearPDEs.SingleTransportPDE(domain, debug=False)

Defines a single transport problem

Parameters:
  • domain (Domain) – domain of the PDE
  • debug – if True debug information is printed
Return type:

TransportPDE

Others

  • __author__
  • __builtins__
  • __copyright__
  • __doc__
  • __file__
  • __license__
  • __name__
  • __package__
  • __url__