esys.escript.nonlinearPDE Package

Classes

class esys.escript.nonlinearPDE.Data

Bases: Boost.Python.instance

Represents a collection of datapoints. It is used to store the values of a function. For more details please consult the c++ class documentation.

copy((Data)arg1, (Data)other) → None :

Make this object a copy of other

note:The two objects will act independently from now on. That is, changing other after this call will not change this object and vice versa.
copy( (Data)arg1) -> Data :
note:In the no argument form, a new object will be returned which is an independent copy of this object.
copyWithMask((Data)arg1, (Data)other, (Data)mask) → None :

Selectively copy values from other Data.Datapoints which correspond to positive values in mask will be copied from other

Parameters:
  • other (Data) – source of values
  • mask (Scalar Data) –
delay((Data)arg1) → Data :

Convert this object into lazy representation

dump((Data)arg1, (str)fileName) → None :

Save the data as a netCDF file

Parameters:fileName (string) –
expand((Data)arg1) → None :

Convert the data to expanded representation if it is not expanded already.

getDomain((Data)arg1) → Domain :
Return type:Domain
getFunctionSpace((Data)arg1) → FunctionSpace :
Return type:FunctionSpace
getNumberOfDataPoints((Data)arg1) → int :
Return type:int
Returns:Number of datapoints in the object
getRank((Data)arg1) → int :
Returns:the number of indices required to address a component of a datapoint
Return type:positive int
getShape((Data)arg1) → tuple :

Returns the shape of the datapoints in this object as a python tuple. Scalar data has the shape ()

Return type:tuple
getTagNumber((Data)arg1, (int)dpno) → int :

Return tag number for the specified datapoint

Return type:int
Parameters:dpno (int) – datapoint number
getTupleForDataPoint((Data)arg1, (int)dataPointNo) → object :
Returns:Value of the specified datapoint
Return type:tuple
Parameters:dataPointNo (int) – datapoint to access
getTupleForGlobalDataPoint((Data)arg1, (int)procNo, (int)dataPointNo) → object :

Get a specific datapoint from a specific process

Return type:

tuple

Parameters:
  • procNo (positive int) – MPI rank of the process
  • dataPointNo (int) – datapoint to access
interpolate((Data)arg1, (FunctionSpace)functionspace) → Data :

Interpolate this object’s values into a new functionspace.

interpolateTable((Data)arg1, (object)table, (float)Amin, (float)Astep, (Data)B, (float)Bmin, (float)Bstep[, (float)undef=1e+50[, (bool)check_boundaries=False]]) → Data :

Creates a new Data object by interpolating using the source data (which are looked up in table) A must be the outer dimension on the table

param table:two dimensional collection of values
param Amin:The base of locations in table
type Amin:float
param Astep:size of gap between each item in the table
type Astep:float
param undef:upper bound on interpolated values
type undef:float
param B:Scalar representing the second coordinate to be mapped into the table
type B:Data
param Bmin:The base of locations in table for 2nd dimension
type Bmin:float
param Bstep:size of gap between each item in the table for 2nd dimension
type Bstep:float
param check_boundaries:
 if true, then values outside the boundaries will be rejected. If false, then boundary values will be used.
raise RuntimeError(DataException):
 if the coordinates do not map into the table or if the interpolated value is above undef
rtype:Data

interpolateTable( (Data)arg1, (object)table, (float)Amin, (float)Astep [, (float)undef=1e+50 [, (bool)check_boundaries=False]]) -> Data

isConstant((Data)arg1) → bool :
Return type:bool
Returns:True if this Data is an instance of DataConstant
Note :This does not mean the data is immutable.
isEmpty((Data)arg1) → bool :

Is this object an instance of DataEmpty

Return type:bool
Note :This is not the same thing as asking if the object contains datapoints.
isExpanded((Data)arg1) → bool :
Return type:bool
Returns:True if this Data is expanded.
isLazy((Data)arg1) → bool :
Return type:bool
Returns:True if this Data is lazy.
isProtected((Data)arg1) → bool :

Can this instance be modified. :rtype: bool

isReady((Data)arg1) → bool :
Return type:bool
Returns:True if this Data is not lazy.
isTagged((Data)arg1) → bool :
Return type:bool
Returns:True if this Data is expanded.
maxGlobalDataPoint((Data)arg1) → tuple :

Please consider using getSupLocator() from pdetools instead.

minGlobalDataPoint((Data)arg1) → tuple :

Please consider using getInfLocator() from pdetools instead.

nonuniformInterpolate((Data)arg1, (object)in, (object)out, (bool)check_boundaries) → Data :

1D interpolation with non equally spaced points

nonuniformSlope((Data)arg1, (object)in, (object)out, (bool)check_boundaries) → Data :

1D interpolation of slope with non equally spaced points

resolve((Data)arg1) → None :

Convert the data to non-lazy representation.

setProtection((Data)arg1) → None :

Disallow modifications to this data object

Note :This method does not allow you to undo protection.
setTaggedValue((Data)arg1, (int)tagKey, (object)value) → None :

Set the value of tagged Data.

param tagKey:tag to update
type tagKey:int
setTaggedValue( (Data)arg1, (str)name, (object)value) -> None :
param name:tag to update
type name:string
param value:value to set tagged data to
type value:object which acts like an array, tuple or list
setToZero((Data)arg1) → None :

After this call the object will store values of the same shape as before but all components will be zero.

setValueOfDataPoint((Data)arg1, (int)dataPointNo, (object)value) → None

setValueOfDataPoint( (Data)arg1, (int)arg2, (object)arg3) -> None

setValueOfDataPoint( (Data)arg1, (int)arg2, (float)arg3) -> None :

Modify the value of a single datapoint.

param dataPointNo:
 
type dataPointNo:
 int
param value:
type value:float or an object which acts like an array, tuple or list
warning:Use of this operation is discouraged. It prevents some optimisations from operating.
tag((Data)arg1) → None :

Convert data to tagged representation if it is not already tagged or expanded

toListOfTuples((Data)arg1[, (bool)scalarastuple=False]) → object :

Return the datapoints of this object in a list. Each datapoint is stored as a tuple.

Parameters:scalarastuple – if True, scalar data will be wrapped as a tuple. True => [(0), (1), (2)]; False => [0, 1, 2]
class esys.escript.nonlinearPDE.DivergenceDetected

Bases: exceptions.Exception

Exception thrown if Newton-Raphson did not converge.

args
message
class esys.escript.nonlinearPDE.Evaluator(*expressions)

Bases: object

addExpression(expression)

Adds an expression to this evaluator.

Returns:the modified Evaluator object
evaluate(**args)

Evaluates all expressions in this evaluator and returns the result as a tuple.

Returns:the evaluated expressions in the order they were added to this Evaluator.
subs(**args)

Symbol substitution.

Returns:the modified Evaluator object
class esys.escript.nonlinearPDE.IllegalCoefficient

Bases: exceptions.ValueError

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

args
message
class esys.escript.nonlinearPDE.IllegalCoefficientValue

Bases: exceptions.ValueError

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

args
message
class esys.escript.nonlinearPDE.InadmissiblePDEOrdering

Bases: exceptions.Exception

Exception thrown if the ordering of the PDE equations should be revised.

args
message
class esys.escript.nonlinearPDE.LinearPDE(domain, numEquations=None, numSolutions=None, debug=False)

Bases: esys.escript.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.escript.nonlinearPDE.NonlinearPDE(domain, u, debug=0)

Bases: object

This class is used to define a general nonlinear, 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 nonlinear PDE is defined in the following form:

-div(X) + Y = 0

where X,*Y*=f(u,*grad(u)*), div(F) denotes the divergence of F and grad(F) is the spatial derivative of F.

The coefficients X (rank 1) and Y (scalar) have to be specified through Symbol objects.

The following natural boundary conditions are considered:

n[j]*X[j] - y = 0

where n is the outer normal field. Notice that the coefficient X is defined in the PDE. The coefficient y is a scalar Symbol.

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.

For a system of PDEs and a solution with several components, u is rank one, while the PDE coefficient X is rank two and Y and y is rank one.

The PDE is solved by linearising the coefficients and iteratively solving the corresponding linear PDE until the error is smaller than a tolerance or a maximum number of iterations is reached.

Typical usage:

u = Symbol('u', dim=dom.getDim())
p = NonlinearPDE(dom, u)
p.setValue(X=grad(u), Y=5*u)
v = p.getSolution(u=0.)
DEBUG0 = 0
DEBUG1 = 1
DEBUG2 = 2
DEBUG3 = 3
DEBUG4 = 4
ORDER = 0
createCoefficient(name)

Creates a new coefficient name as Symbol

Parameters:name (string) – name of the coefficient requested
Returns:the value of the coefficient
Return type:Symbol or Data (for name = “q”)
Raises IllegalCoefficient:
 if name is not a coefficient of the PDE
getCoefficient(name)

Returns the value of the coefficient name as Symbol

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

Returns the linear PDE used to calculate the Newton-Raphson update

Return type:LinearPDE
getLinearSolverOptions()

Returns the options of the linear PDE solver class

getNumSolutions()

Returns the number of the solution components :rtype: int

getSensitivity(f, g=None, **subs)

Calculates the sensitivity of the solution of an input factor f in direction g.

Parameters:
  • f (Symbol) – the input factor to be investigated. f may be of rank 0 or 1.
  • g (list or single of float, numpy.array or Data.) – the direction(s) of change. If not present, it is g=eye(n) where n is the number of components of f.
  • subs – Substitutions for all symbols used in the coefficients including unknown u and the input factor f to be investigated
Returns:

the sensitivity

Return type:

Data with shape u.getShape()+(len(g),) if len(g)>1 or u.getShape() if len(g)==1

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(**subs)

Returns the solution of the PDE.

Parameters:subs – Substitutions for all symbols used in the coefficients including the initial value for the unknown u.
Returns:the solution
Return type:Data
getUnknownSymbol()

Returns the symbol of the PDE unknown

Returns:the symbol of the PDE unknown
Return type:Symbol
setOptions(**opts)

Allows setting options for the nonlinear PDE.

The supported options are:
tolerance
error tolerance for the Newton method
iteration_steps_max
maximum number of Newton iterations
omega_min
minimum relaxation factor
atol
solution norms less than atol are assumed to be atol. This can be useful if one of your solutions is expected to be zero.
quadratic_convergence_limit
if the norm of the Newton-Raphson correction is reduced by less than quadratic_convergence_limit between two iteration steps quadratic convergence is assumed.
simplified_newton_limit
if the norm of the defect is reduced by less than simplified_newton_limit between two iteration steps and quadratic convergence is detected the iteration switches to the simplified Newton-Raphson scheme.
setValue(**coefficients)

Sets new values to one or more coefficients.

Parameters:
  • coefficients – new values assigned to coefficients
  • coefficients – new values assigned to coefficients
  • X (Symbol or any type that can be cast to a Data object) – value for coefficient X
  • Y (Symbol or any type that can be cast to a Data object) – value for coefficient Y
  • y (Symbol or any type that can be cast to a Data object) – value for coefficient y
  • y_contact (Symbol or any type that can be cast to a Data object) – value for coefficient y_contact
  • y_dirac (Symbol or any type that can be cast to a Data object) – value for coefficient y_dirac
  • q (any type that can be cast to a Data object) – mask for location of constraint
  • r (Symbol or any type that can be cast to a Data object) – value of solution prescribed by constraint
Raises:
  • IllegalCoefficient – if an unknown coefficient keyword is used
  • IllegalCoefficientValue – if a supplied coefficient value has an invalid shape
trace1(text)

Prints the text message if the debug level is greater than DEBUG0

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

Prints the text message if the debug level is greater than DEBUG3

Parameters:text (string) – message to be printed
class esys.escript.nonlinearPDE.Symbol(*args, **kwargs)

Bases: object

Symbol objects are placeholders for a single mathematical symbol, such as ‘x’, or for arbitrarily complex mathematical expressions such as ‘c*x**4+alpha*exp(x)-2*sin(beta*x)’, where ‘alpha’, ‘beta’, ‘c’, and ‘x’ are also Symbols (the symbolic ‘atoms’ of the expression).

With the help of the ‘Evaluator’ class these symbols and expressions can be resolved by substituting numeric values and/or escript Data objects for the atoms. To facilitate the use of Data objects a Symbol has a shape (and thus a rank) as well as a dimension (see constructor). Symbols are useful to perform mathematical simplifications, compute derivatives and as coefficients for nonlinear PDEs which can be solved by the NonlinearPDE class.

applyfunc(f, on_type=None)

Applies the function f to all elements (if on_type is None) or to all elements of type on_type.

atoms(*types)

Returns the atoms that form the current Symbol.

By default, only objects that are truly atomic and cannot be divided into smaller pieces are returned: symbols, numbers, and number symbols like I and pi. It is possible to request atoms of any type, however.

Note that if this symbol contains components such as [x]_i_j then only their main symbol ‘x’ is returned.

Parameters:types – types to restrict result to
Returns:list of atoms of specified type
Return type:set
coeff(x, expand=True)

Returns the coefficient of the term “x” or 0 if there is no “x”.

If “x” is a scalar symbol then “x” is searched in all components of this symbol. Otherwise the shapes must match and the coefficients are checked component by component.

Example:

x=Symbol('x', (2,2))
y=3*x
print y.coeff(x)
print y.coeff(x[1,1])

will print:

[[3 3]
 [3 3]]

[[0 0]
 [0 3]]
Parameters:x (Symbol, numpy.ndarray, list) – the term whose coefficients are to be found
Returns:the coefficient(s) of the term
Return type:Symbol
diff(*symbols, **assumptions)
expand()

Applies the sympy.expand operation on all elements in this symbol

getDataSubstitutions()

Returns a dictionary of symbol names and the escript Data objects they represent within this Symbol.

Returns:the dictionary of substituted Data objects
Return type:dict
getDim()

Returns the spatial dimensionality of this symbol.

Returns:the symbol’s spatial dimensionality, or -1 if undefined
Return type:int
getRank()

Returns the rank of this symbol.

Returns:the symbol’s rank which is equal to the length of the shape.
Return type:int
getShape()

Returns the shape of this symbol.

Returns:the symbol’s shape
Return type:tuple of int
grad(where=None)

Returns a symbol which represents the gradient of this symbol. :type where: Symbol, FunctionSpace

inverse()
is_Add = False
is_Float = False
item(*args)

Returns an element of this symbol. This method behaves like the item() method of numpy.ndarray. If this is a scalar Symbol, no arguments are allowed and the only element in this Symbol is returned. Otherwise, ‘args’ specifies a flat or nd-index and the element at that index is returned.

Parameters:args – index of item to be returned
Returns:the requested element
Return type:sympy.Symbol, int, or float
lambdarepr()
simplify()

Applies the sympy.simplify operation on all elements in this symbol

subs(old, new)

Substitutes an expression.

swap_axes(axis0, axis1)
tensorProduct(other, axis_offset)
tensorTransposedProduct(other, axis_offset)
trace(axis_offset)

Returns the trace of this Symbol.

transpose(axis_offset)

Returns the transpose of this Symbol.

transposedTensorProduct(other, axis_offset)
class esys.escript.nonlinearPDE.VariationalProblem(domain, u, p=None, debug=0)

Bases: object

This class is used to define a general constraint vartional problem for an unknown function u and (spatially variable) parameter p on a given domain defined through a Domain object. u may be a scalar or a vector. p which may be a scalar or a vector may not be present.

The solution u and the paremeter p are given as the solution of the minimization problem:

min_{u,p} int(H) + int(h)

where int{H} refers to integration over the domain and H*=f(*x,*u*,*grad(u)*,*p*, grad(p)) is a function which may depend on the location x within the domain and is a function of the solution u and the parameter p and their gradients grad(u) and grad(p), respectively. Similarly, int{H} refers to integration over the boundary of the domain and h=f(*x,*u*, p) is a function which may depend on the location x within the domain boundary and is a function of the solution u and the parameter p.

If p is present, u is the solution of a PDE with coefficients depending on the parameter p. The PDE defines a constraint for the variational problem. It is assumed that, if p is present, for any given parameter p a unique solution u of the PDE exists.

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

-div(X) + Y = 0

where X,*Y*=f(x,*u*,*grad(u)*, p, grad(p)), div(F) denotes the divergence of F and grad(F) is the spatial derivative of F.

The coefficients X (rank 1) and Y (scalar) have to be specified through Symbol objects.

The following natural boundary conditions are considered:

n[j]*X[j] - y = 0

where n is the outer normal field. Notice that the coefficient X is defined in the PDE. The coefficient y is a scalar Symbol.

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.

For a system of PDEs and a solution with several components, u is rank one, while the PDE coefficient X is rank two and Y and y is rank one.

The PDE is solved by linearising the coefficients and iteratively solving the corresponding linear PDE until the error is smaller than a tolerance or a maximum number of iterations is reached.

Typical usage:

s=Symbol(‘s’, dim=dom.getDim()) T = Symbol(‘T’, dim=dom.getDim()) log_k = Symbol(‘log_k’, dim=dom.getDim()) v = VariationalProblem(dom, u=T, p=log_k) v.setValue(X=exp(-log_k)*grad(T), Y=s, h=0.3*(T-0.3)**2) T, log_k, l = v.getSolution(T=0., log_k=1, s=2.45) sT,S_log_k=v.getSensitivity(s, direction=1, T=T, log_k=log_k, s=2.45)
DEBUG0 = 0
DEBUG1 = 1
DEBUG2 = 2
DEBUG3 = 3
DEBUG4 = 4
createCoefficient(name)

Creates a new coefficient name as Symbol

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

Returns the value of the coefficient name as Symbol

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

Returns the NonlinearPDE used to solve the variational problem

Returns:underlying nonlinear PDE
Return type:NonlinearPDE
getNumParameters()

Returns the number of parameter components. If no parameter is present zero is returned.

Return type:int
getNumSolutions()

Returns the number of solution components :rtype: int

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(**subs)

Returns the solution of the variational problem.

Parameters:subs – Substitutions for all symbols used in the coefficients including the initial value for solution u and for the parameter p (if present)
Returns:parameter, corresponding solution and lagrangean multiplier
Return type:tuple of Data or single Data (if no parameter present)
setValue(**coefficients)

Sets new values to one or more coefficients.

Parameters:
  • H (Symbol) – value for coefficient H
  • h (Symbol) – value for coefficient h
  • h_contact (Symbol) – value for coefficient h_contact
  • h_dirac (Symbol) – value for coefficient y_dirac
  • X (Symbol or any type that can be cast to a Data object) – value for coefficient X
  • Y (Symbol or any type that can be cast to a Data object) – value for coefficient Y = r
  • y (Symbol or any type that can be cast to a Data object) – value for coefficient y
  • y_contact (Symbol or any type that can be cast to a Data object) – value for coefficient y_contact
  • y_dirac (Symbol or any type that can be cast to a Data object) – value for coefficient y_dirac
  • q (any type that can be casted to a Data object) – mask for location of constraint
  • r (Symbol or any type that can be cast to a Data object) – value of solution prescribed by constraint
  • qp (any type that can be casted to a Data object) – mask for location of constraint fro parameter
  • rp (Symbol or any type that can be cast to a Data object) – value of the parameter prescribed by parameter constraint
Raises:
  • IllegalCoefficient – if an unknown coefficient keyword is used
  • IllegalCoefficientValue – if a supplied coefficient value has an invalid shape
trace1(text)

Prints the text message if the debug level is greater than DEBUG0

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

Prints the text message if the debug level is greater than DEBUG3

Parameters:text (string) – message to be printed
class esys.escript.nonlinearPDE.iteration_steps_maxReached

Bases: exceptions.Exception

Exception thrown if the maximum number of iteration steps is reached.

args
message

Functions

esys.escript.nonlinearPDE.concatenateRow(*args)
esys.escript.nonlinearPDE.getTotalDifferential(f, x, order=0)

This function computes:

| Df/Dx = del_f/del_x + del_f/del_grad(x)*del_grad(x)/del_x + ...
|            \   /         \   /
|              a             b
esys.escript.nonlinearPDE.isSymbol(arg)

Returns True if the argument arg is an escript Symbol or sympy.Basic object, False otherwise.

Others

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