esys.escript.nonlinearPDE Package

Classes

class esys.escript.nonlinearPDE.Data

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

__init__((object)arg1) → None

__init__( (object)arg1, (object)value [, (object)p2 [, (object)p3 [, (object)p4]]]) -> None

conjugate((Data)arg1) → Data
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 HDF5 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

getX((Data)arg1) → Data :

Returns the spatial coordinates of the spatial nodes. :rtype: Data

hasInf((Data)arg1) → bool :

Returns return true if data contains +-Inf. [Note that for complex values, hasNaN and hasInf are not mutually exclusive.]

hasNaN((Data)arg1) → bool :

Returns return true if data contains NaN. [Note that for complex values, hasNaN and hasInf are not mutually exclusive.]

imag((Data)arg1) → Data
internal_maxGlobalDataPoint((Data)arg1) → tuple :

Please consider using getSupLocator() from pdetools instead.

internal_minGlobalDataPoint((Data)arg1) → tuple :

Please consider using getInfLocator() from pdetools instead.

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

isComplex((Data)arg1) → bool :
Return type:

bool

Returns:

True if this Data stores complex values.

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.

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

phase((Data)arg1) → Data
promote((Data)arg1) → None
real((Data)arg1) → Data
replaceInf((Data)arg1, (object)value) → None :

Replaces +-Inf values with value. [Note, for complex Data, both real and imaginary components are replaced even if only one part is Inf].

replaceNaN((Data)arg1, (object)value) → None :

Replaces NaN values with value. [Note, for complex Data, both real and imaginary components are replaced even if only one part is NaN].

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

Exception thrown if Newton-Raphson did not converge.

__init__(*args, **kwargs)
class esys.escript.nonlinearPDE.InadmissiblePDEOrdering

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

__init__(*args, **kwargs)
class esys.escript.nonlinearPDE.NonlinearPDE(domain, u, debug=0)

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 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=1+5*u)
v = p.getSolution(u=0.)
__init__(domain, u, debug=0)

Initializes a new nonlinear PDE.

Parameters:

  • domain (Domain) – domain of the PDE

  • u (Symbol) – The symbol for the unknown PDE function u.

  • debug – level of debug information to be printed

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:
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

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

__init__(*args, **kwargs)

Functions

esys.escript.nonlinearPDE.concatenateRow(*args)

Others

  • HAVE_SYMBOLS

  • time

Packages