# esys.downunder Package

Data inversion module built on escript

## Classes

- `AbstractMinimizer`
- `AcousticVelocityMapping`
- `AcousticWaveForm`
- `ArithmeticTuple`
- `BoundedRangeMapping`
- `CartesianReferenceSystem`
- `CostFunction`
- `DataSource`
- `DcRes`
- `DcResistivityForward`
- `DensityMapping`
- `DipoleDipoleSurvey`
- `DomainBuilder`
- `ErMapperData`
- `ForwardModel`
- `ForwardModelWithPotential`
- `FunctionJob`
- `GeodeticCoordinateTransformation`
- `GeodeticReferenceSystem`
- `GravityInversion`
- `GravityModel`
- `HTIWave`
- `InversionCostFunction`
- `InversionDriver`
- `IsostaticPressure`
- `Job`
- `JointGravityMagneticInversion`
- `LinearMapping`
- `LinearPDE`
- `Locator`
- `MT2DModelTEMode`
- `MT2DModelTMMode`
- `MTMapping`
- `MagneticIntensityModel`
- `MagneticInversion`
- `MagneticModel`
- `Mapping`
- `MeteredCostFunction`
- `MinimizerBFGS`
- `MinimizerException`
- `MinimizerIterationIncurableBreakDown`
- `MinimizerLBFGS`
- `MinimizerMaxIterReached`
- `MinimizerNLCG`
- `NetCdfData`
- `NumpyData`
- `PoleDipoleSurvey`
- `PolePoleSurvey`
- `ReferenceSystem`
- `Regularization`
- `Ricker`
- `SchlumbergerSurvey`
- `SeismicSource`
- `SelfDemagnetizationModel`
- `SimpleSEGYWriter`
- `SmoothAnomaly`
- `SonicHTIWave`
- `SonicWave`
- `SpatialCoordinateTransformation`
- `SplitInversionCostFunction`
- `SplitMinimizerLBFGS`
- `SplitRegularization`
- `StrongJointGravityMagneticInversion`
- `Subsidence`
- `SusceptibilityMapping`
- `SyntheticData`
- `SyntheticDataBase`
- `SyntheticFeatureData`
- `TTIWave`
- `VTIWave`
- `WaveBase`
- `WennerSurvey`
- `xrange`

class `esys.downunder.``AbstractMinimizer`(J=None, m_tol=0.0001, J_tol=None, imax=300)

  Bases: `object`

  Base class for function minimization methods.

  `__init__`(J=None, m_tol=0.0001, J_tol=None, imax=300)

    Initializes a new minimizer for a given cost function.

    Parameters:

    - J (`CostFunction`) – the cost function to be minimized
    - m_tol (float) – terminate interations when relative change of the level set function is less than or equal m_tol

  `getCostFunction`()

    return the cost function to be minimized

    Return type: | `CostFunction`

  `getOptions`()

    Returns a dictionary of minimizer-specific options.

  `getResult`()

    Returns the result of the minimization.

  `logSummary`()

    Outputs a summary of the completed minimization process to the logger.

  `run`(x0)

    Executes the minimization algorithm for f starting with the initial guess `x0`.

    Returns: | the result of the minimization

  `setCallback`(callback)

    Sets a callback function to be called after every iteration. It is up to the specific implementation what arguments are passed to the callback. Subclasses should at least pass the current iteration number k, the current estimate x, and possibly f(x), grad f(x), and the current error.

  `setCostFunction`(J)

    set the cost function to be minimized

    Parameters: | J (`CostFunction`) – the cost function to be minimized

  `setMaxIterations`(imax)

    Sets the maximum number of iterations before the minimizer terminates.

  `setOptions`(**opts)

    Sets minimizer-specific options. For a list of possible options see `getOptions()`.

  `setTolerance`(m_tol=0.0001, J_tol=None)

    Sets the tolerance for the stopping criterion. The minimizer stops when an appropriate norm is less than `m_tol`.

class `esys.downunder.``AcousticVelocityMapping`(V_prior, Q_prior)

  Bases: `esys.downunder.mappings.Mapping`

  Maps a p-velocity and Q-index to slowness square sigma=(V*(1-i*1/(2*Q))^{-2} in the form sigma=e^{Mr+m[0])}*( cos(Mi+m[1])) + i * sin(Mi+m[1])

  `__init__`(V_prior, Q_prior)

    initializes the mapping

    Parameters:

    - V_prior – a-priori p-wave velocity
    - Q_prior – a-priori Q-index (must be positive)

  `getDerivative`(m)

    returns the value for the derivative of the mapping for m

  `getInverse`(s)

    returns the value of the inverse of the mapping for s

  `getTypicalDerivative`()

    returns a typical value for the derivative

  `getValue`(m)

    returns the value of the mapping for m

class `esys.downunder.``AcousticWaveForm`(domain, omega, w, data, F, coordinates=None, fixAtBottom=False, tol=1e-10, saveMemory=True, scaleF=True)

  Bases: `esys.downunder.forwardmodels.base.ForwardModel`

  Forward Model for acoustic waveform inversion in the frequency domain. It defines a cost function:

  Math: | `defect = 1/2 integrate( ( w * ( a * u - data ) ) ** 2 )`

  where w are weighting factors, data are the measured data (as a 2-comp vector of real and imaginary part) for real frequency omega, and u is the corresponding result produced by the forward model. u (as a 2-comp vector) is the solution of the complex Helmholtz equation for frequency omega, source F and complex, inverse, squared p-velocity sigma:

  Math: | `-u_{ii} - omega**2 * sigma * u = F`

  It is assumed that the exact scale of source F is unknown and the scaling factor a of F is calculated by minimizing the defect.

  `__init__`(domain, omega, w, data, F, coordinates=None, fixAtBottom=False, tol=1e-10, saveMemory=True, scaleF=True)

    initializes a new forward model with acoustic wave form inversion.

    Parameters:

    - domain (`Domain`) – domain of the model
    - w (`Scalar`) – weighting factors
    - data (`escript.Data` of shape (2,)) – real and imaginary part of data
    - F (`escript.Data` of shape (2,)) – real and imaginary part of source given at Dirac points, on surface or at volume.
    - coordinates (`ReferenceSystem` or `SpatialCoordinateTransformation`) – defines coordinate system to be used (not supported yet)
    - tol (positive `float`) – tolerance of underlying PDE
    - saveMemory (`bool`) – if true stiffness matrix is deleted after solution of PDE to minimize memory requests. This will require more compute time as the matrix needs to be reallocated.
    - scaleF (`bool`) – if true source F is scaled to minimize defect.
    - fixAtBottom (`bool`) – if true pressure is fixed to zero at the bottom of the domain

  `getArguments`(sigma)

    Returns precomputed values shared by `getDefect()` and `getGradient()`.

    Parameters: | sigma (`escript.Data` of shape (2,)) – a suggestion for complex 1/V**2
    Returns: | solution, uTar, uTai, uTu
    Return type: | `escript.Data` of shape (2,), 3 x `float`

  `getCoordinateTransformation`()

    returns the coordinate transformation being used

    Return type: | `CoordinateTransformation`

  `getDefect`(sigma, u, uTar, uTai, uTu)

    Returns the defect value.

    Parameters:

    - sigma (`escript.Data` of shape (2,)) – a suggestion for complex 1/V**2
    - u (`escript.Data` of shape (2,)) – a u vector
    - uTar (`float`) – equals `integrate( w * (data[0]*u[0]+data[1]*u[1]))`
    - uTai – equals `integrate( w * (data[1]*u[0]-data[0]*u[1]))`
    - uTu (`float`) – equals `integrate( w * (u,u))`

    Return type: | `float`

  `getDomain`()

    Returns the domain of the forward model.

    Return type: | `Domain`

  `getGradient`(sigma, u, uTar, uTai, uTu)

    Returns the gradient of the defect with respect to density.

    Parameters:

    - sigma (`escript.Data` of shape (2,)) – a suggestion for complex 1/V**2
    - u (`escript.Data` of shape (2,)) – a u vector
    - uTar (`float`) – equals `integrate( w * (data[0]*u[0]+data[1]*u[1]))`
    - uTai – equals `integrate( w * (data[1]*u[0]-data[0]*u[1]))`
    - uTu (`float`) – equals `integrate( w * (u,u))`

  `getSourceScaling`(u)

    returns the scaling factor s required to rescale source F to minimize defect `|s * u- data|^2`

    Parameters: | u (`escript.Data` of shape (2,)) – value of pressure solution (real and imaginary part)
    Return type: | `complex`

  `getSurvey`(index=None)

    Returns the pair (data, weight)

    If argument index is ignored.

  `rescaleWeights`(scale=1.0, sigma_scale=1.0)

    rescales the weights such that

    Math: | integrate( ( w omega**2 * sigma_scale * data * ((1/L_j)**2)**-1) +1 )/(data*omega**2 * ((1/L_j)**2)**-1) * sigma_scale )=scale

    Parameters:

    - scale (positive `float`) – scale of data weighting factors
    - sigma_scale (`Scalar`) – scale of 1/vp**2 velocity.

  `setUpPDE`()

    Creates and returns the underlying PDE.

    Return type: | `lpde.LinearPDE`

class `esys.downunder.``ArithmeticTuple`(*args)

  Bases: `object`

  Tuple supporting inplace update x+=y and scaling x=a*y where `x,y` is an ArithmeticTuple and `a` is a float.

  Example of usage:

      from esys.escript import Data
      from numpy import array
      a=eData(...)
      b=array([1.,4.])
      x=ArithmeticTuple(a,b)
      y=5.*x

  `__init__`(*args)

    Initializes object with elements `args`.

    Parameters: | args – tuple of objects that support inplace add (x+=y) and scaling (x=a*y)

class `esys.downunder.``BoundedRangeMapping`(s_min=0, s_max=1)

  Bases: `esys.downunder.mappings.Mapping`

  Maps an unbounded parameter to a bounded range. The mapping is smooth and continuous.

  `__init__`(s_min=0, s_max=1)

    Initialize self. See help(type(self)) for accurate signature.

  `getDerivative`(m)

    returns the value for the derivative of the mapping for m

  `getInverse`(s)

    returns the value of the inverse of the mapping for s

  `getTypicalDerivative`()

    returns a typical value for the derivative

  `getValue`(m)

    returns the value of the mapping for m

class `esys.downunder.``CartesianReferenceSystem`(name='CARTESIAN')

  Bases: `esys.downunder.coordinates.ReferenceSystem`

  Identifies the Cartesian coordinate system

  `__init__`(name='CARTESIAN')

    set up Cartesian coordinate system

  `createTransformation`(domain)

    creates an appropriate coordinate transformation on a given domain

    Parameters: | domain (`esys.escript.AbstractDomain`) – domain of transformation
    Return type: | `SpatialCoordinateTransformation`

  `getName`()

    returns the name of the reference system

  `isCartesian`()

    returns if the reference system is Cartesian

    Return type: | `bool`

  `isTheSame`(other)

    test if argument `other` defines the same reference system

    Parameters: | other (`ReferenceSystem`) – a second reference system
    Returns: | `True` if `other` is a `CartesianReferenceSystem` instance.
    Return type: | `bool`
    Note: | every two `CartesianReferenceSystem` instances are considered as being the same.

class `esys.downunder.``CostFunction`

  Bases: `object`

  A function f(x) that can be minimized (base class).

  Example of usage:

      cf=DerivedCostFunction()
      # ... calculate x ...
      args=cf.getArguments(x) # this could be potentially expensive!
      f=cf.getValue(x, *args)
      # ... it could be required to update x without using the gradient...
      # ... but then ...
      gf=cf.getGradient(x, *args)

  The class distinguishes between the representation of the solution x (x-type) and the gradients (r-type).

  Note: | The provides_inverse_Hessian_approximation class member should be set to `True` in subclasses that provide a valid implementation of `getInverseHessianApproximation()`

  `__init__`()

    Constructor. Initializes logger.

  `getArguments`(x)

    returns precalculated values that are shared in the calculation of f(x) and grad f(x) and the Hessian operator. The default implementation returns an empty tuple.

    Note

    The tuple returned by this call will be passed back to this `CostFunction` in other calls(eg: `getGradient`). Its contents are not specified at this level because no code, other than the `CostFunction` which created it, will be interacting with it. That is, the implementor can put whatever information they find useful in it.

    Parameters: | x (x-type) – location of derivative
    Return type: | `tuple`

  `getDualProduct`(x, r)

    returns the dual product of `x` and `r`

    Return type: | `float`

  `getGradient`(x, *args)

    returns the gradient of f at x using the precalculated values for x.

    Parameters:

    - x (x-type) – location of derivative
    - args – pre-calculated values for `x` from `getArguments()`

    Return type: | r-type

  `getInverseHessianApproximation`(x, r, *args)

    returns an approximative evaluation p of the inverse of the Hessian operator of the cost function for a given gradient r at a given location x: H(x) p = r

    Parameters:

    - x (x-type) – location of Hessian operator to be evaluated
    - r (r-type) – a given gradient
    - args – pre-calculated values for `x` from `getArguments()`

    Return type: | x-type
    Note: | In general it is assumed that the Hessian H(x) needs to be calculated in each call for a new location x. However, the solver may suggest that this is not required, typically when the iteration is close to completeness.
    Note: | Subclasses that implement this method should set the class variable `provides_inverse_Hessian_approximation` to `True` to enable the solver to call this method.

  `getNorm`(x)

    returns the norm of `x`

    Return type: | `float`

  `getValue`(x, *args)

    returns the value f(x) using the precalculated values for x.

    Parameters: | x (x-type) – a solution approximation
    Return type: | `float`

  `provides_inverse_Hessian_approximation` = False
  `updateHessian`()

    notifies the class that the Hessian operator needs to be updated. This method is called by the solver class.

class `esys.downunder.``DataSource`(reference_system=None, tags=[])

  Bases: `object`

  A class that provides survey data for the inversion process. This is an abstract base class that implements common functionality. Methods to be overwritten by subclasses are marked as such. This class assumes 2D data which is mapped to a slice of a 3D domain. For other setups override the methods as required.

  `__init__`(reference_system=None, tags=[])

    Constructor. Sets some defaults and initializes logger.

    Parameters:

    - tags (`list` of almost any type (typically `str`)) – a list of tags associated with the data set.
    - reference_system (`None` or `ReferenceSystem`) – the reference coordinate system

  `ACOUSTIC` = 2
  `GRAVITY` = 0
  `MAGNETIC` = 1
  `MT` = 3
  `getDataExtents`()

    returns a tuple of tuples `( (x0, y0), (nx, ny), (dx, dy) )`, where

    - `x0`, `y0` = coordinates of data origin
    - `nx`, `ny` = number of data points in x and y
    - `dx`, `dy` = spacing of data points in x and y

    This method must be implemented in subclasses.

  `getDataType`()

    Returns the type of survey data managed by this source. Subclasses must return `GRAVITY` or `MAGNETIC` or `ACOUSTIC` as appropriate.

  `getHeightScale`()

    returns the height scale factor to convert from meters to the appropriate units of the reference system used.

    Return type: | `float`

  `getReferenceSystem`()

    returns the reference coordinate system

    Return type: | `ReferenceSystem`

  `getSubsamplingFactor`()

    Returns the subsampling factor that was set via `setSubsamplingFactor` (see there).

  `getSurveyData`(domain, origin, NE, spacing)

    This method is called by the `DomainBuilder` to retrieve the survey data as `Data` objects on the given domain.

    Subclasses should return one or more `Data` objects with survey data interpolated on the given `escript` domain. The exact return type depends on the type of data.

    Parameters:

    - domain (`esys.escript.Domain`) – the escript domain to use
    - origin (`tuple` or `list`) – the origin coordinates of the domain
    - NE (`tuple` or `list`) – the number of domain elements in each dimension
    - spacing (`tuple` or `list`) – the cell sizes (node spacing) in the domain

  `getTags`()

    returns the list of tags

    Return type: | `list`

  `getUtmZone`()

    All data source coordinates are converted to UTM (Universal Transverse Mercator) in order to have useful domain extents. Subclasses should implement this method and return the UTM zone number of the projected coordinates.

  `hasTag`(tag)

    returns true if the data set has tag `tag`

    Return type: | `bool`

  `setSubsamplingFactor`(f)

    Sets the data subsampling factor (default=1).

    The factor is applied in all dimensions. For example a 2D dataset with 300 x 150 data points will be reduced to 150 x 75 when a subsampling factor of 2 is used. This becomes important when adding data of varying resolution to a `DomainBuilder`.

class `esys.downunder.``DcRes`(domain, locator, delphiIn, sampleTags, phiPrimary, sigmaPrimary, w=1.0, coordinates=None, tol=1e-08, saveMemory=True, b=None)

  Bases: `esys.downunder.forwardmodels.base.ForwardModel`

  Forward Model for DC resistivity, with a given source pair. The cost function is defined as:

  Math: | defect = 1/2 (sum_s sum_pq w_pqs * ((phi_sp-phi_sq)-v_pqs)**2

  `__init__`(domain, locator, delphiIn, sampleTags, phiPrimary, sigmaPrimary, w=1.0, coordinates=None, tol=1e-08, saveMemory=True, b=None)

    setup new forward model

    Parameters:

    - domain – the domain of the model
    - locator – contains locator to the measurement pairs
    - sampleTags (list of tuples) – tags of measurement points from which potential differences will be calculated.
    - phiPrimary (`Scalar`) – primary potential.

    Type: | escript domain
    Type: | `list` of `Locator`
    Param: | delphiIn: this is v_pq, the potential difference for the current source and a set of measurement pairs. A list of measured potential differences is expected. Note this should be the secondary potential only.

  `getArguments`(sigma)

    Returns precomputed values shared by `getDefect()` and `getGradient()`.

    Parameters: | sigma (`Data` of shape (1,)) – conductivity
    Returns: | phi
    Return type: | `Data` of shape (1,)

  `getCoordinateTransformation`()

    returns the coordinate transformation being used

    Return type: | `CoordinateTransformation`

  `getDefect`(sigma, phi, loc_phi)

    Returns the defect value.

    Parameters:

    - sigma (`Data` of shape (1,)) – a suggestion for conductivity
    - phi (`Data` of shape (1,)) – potential field

    Return type: | `float`

  `getDomain`()

    Returns the domain of the forward model.

    Return type: | `Domain`

  `getGradient`(sigma, phi, loc_phi)

    Returns the gradient of the defect with respect to density.

    Parameters:

    - sigma (`Data` of shape (1,)) – a suggestison for conductivity
    - phi (`Data` of shape (1,)) – potential field

  `getPrimaryPotential`()

    returns the primary potential :rtype: `Data`

  `setUpPDE`()

    Return the underlying PDE.

    Return type: | `LinearPDE`

class `esys.downunder.``DcResistivityForward`

  Bases: `object`

  This class allows for the solution of dc resistivity forward problems via the calculation of a primary and secondary potential. Conductivity values are to be provided for the primary problem which is a homogeneous half space of a chosen conductivity and for the secondary problem which typically varies it conductivity spatially across the domain. The primary potential acts as a reference point typically based of some know reference conductivity however any value will suffice. The primary potential is implemented to avoid the use of dirac delta functions.

  `__init__`()

    This is a skeleton class for all the other forward modeling classes.

  `checkBounds`()
  `getApparentResistivity`()
  `getElectrodes`()

    retuns the list of electrodes with locations

  `getPotential`()

class `esys.downunder.``DensityMapping`(domain, z0=None, rho0=None, drho=None, beta=None)

  Bases: `esys.downunder.mappings.LinearMapping`

  Density mapping with depth weighting

  rho = rho0 + drho * ( (x_2 - z0)/l_z)^(beta/2) ) * m

  `__init__`(domain, z0=None, rho0=None, drho=None, beta=None)

    initializes the mapping

    Parameters:

    - domain (`Domain`) – domain of the mapping
    - z0 (scalar) – depth weighting offset. If not present no depth scaling is applied.
    - rho0 (scalar) – reference density, defaults to 0
    - drho (scalar) – density scale. By default density of granite = 2750kg/m**3 is used.
    - beta (`float`) – depth weighting exponent, defaults to 2

  `getDerivative`(m)

    returns the value for the derivative of the mapping for m

  `getInverse`(p)

    returns the value of the inverse of the mapping for s

  `getTypicalDerivative`()

    returns a typical value for the derivative

  `getValue`(m)

    returns the value of the mapping for m

class `esys.downunder.``DipoleDipoleSurvey`(domain, primaryConductivity, secondaryConductivity, current, a, n, midPoint, directionVector, numElectrodes)

  Bases: `esys.downunder.dcresistivityforwardmodeling.DcResistivityForward`

  DipoleDipoleSurvey forward modeling

  `__init__`(domain, primaryConductivity, secondaryConductivity, current, a, n, midPoint, directionVector, numElectrodes)

    This is a skeleton class for all the other forward modeling classes.

  `checkBounds`()
  `getApparentResistivity`()
  `getApparentResistivityPrimary`()
  `getApparentResistivitySecondary`()
  `getApparentResistivityTotal`()
  `getElectrodes`()

    retuns the list of electrodes with locations

  `getPotential`()

    Returns 3 list each made up of a number of list containing primary, secondary and total potentials diferences. Each of the lists contain a list for each value of n.

class `esys.downunder.``DomainBuilder`(dim=3, reference_system=None)

  Bases: `object`

  This class is responsible for constructing an escript Domain object with suitable extents and resolution for survey data (`DataSource` objects) that are added to it.

  The domain covers a region above and below the Earth surface. The East-West direction is used as the x- or longitudinal or x[0] direction, the North-South direction is used as the y- or latitudinal or x[1] direction, the vertical direction is denoted by z or radial or x[2] direction. The corresponding terms are used synonymously.

  `__init__`(dim=3, reference_system=None)

    Constructor.

    Parameters:

    - dim (`int`) – Dimensionality (2 or 3) of the target domain. This has implications for the survey data than can be added. By default a 3D domain is created.
    - reference_system (`ReferenceSystem`) – reference coordinate system. By default the Cartesian coordinate system is used.

  `addSource`(source)

    Adds a survey data provider to the domain builder. An exception is raised if the domain has already been built. An exception is also reported if the reference system used is cartesian and the UTM zone of `source` does not match the UTM zone of sources already added to the domain builder (see Inversion Cookbook for more information). The dimensionality of the data source must be compatible with this domain builder. That is, the dimensionality of the data must be one less than the dimensionality of the domain (specified in the constructor).

    Parameters: | source (`DataSource`) – The data source to be added. Its reference system needs to match the reference system of the DomainBuilder.

  `fixDensityBelow`(depth=None)

    Defines the depth below which the density anomaly is set to a given value. If no value is given zero is assumed.

    Parameters: | depth (`float`) – depth below which the density is fixed. If not set, no constraint at depth is applied.

  `fixSusceptibilityBelow`(depth=None)

    Defines the depth below which the susceptibility anomaly is set to a given value. If no value is given zero is assumed.

    Parameters: | depth (`float`) – depth below which the susceptibility is fixed. If not set, no constraint at depth is applied.

  `fixVelocityBelow`(depth=None)

    Defines the depth below which the velocity and Q index is set to a given value. If no value is given zero is assumed.

    Parameters: | depth (`float`) – depth below which the velocity is fixed. If not set, no constraint at depth is applied.

  `getBackgroundMagneticFluxDensity`()

    Returns the background magnetic flux density.

  `getDomain`()

    Returns a domain that spans the data area plus padding.

    The domain is created the first time this method is called, subsequent calls return the same domain so anything that affects the domain (such as padding) needs to be set beforehand.

    Returns: | The escript domain for this data source
    Return type: | `esys.escript.Domain`

  `getGravitySurveys`()

    Returns a list of gravity surveys, see `getSurveys` for details.

  `getMagneticSurveys`()

    Returns a list of magnetic surveys, see `getSurveys` for details.

  `getReferenceSystem`()

    returns the reference coordinate system

    Return type: | `ReferenceSystem`

  `getSetDensityMask`()

    Returns the density mask data object which is non-zero for cells whose density value is fixed, zero otherwise.

  `getSetSusceptibilityMask`()

    Returns the susceptibility mask data object which is non-zero for cells whose susceptibility value is fixed, zero otherwise.

  `getSurveys`(datatype, tags=None)

    Returns a list of `Data` objects for all surveys of type `datatype` available to this domain builder. If a list of `tags` is given only data sources whose tag matches the tag list are returned.

    Returns: | List of surveys which are tuples (anomaly,error).
    Return type: | `list`

  `getTags`()

    returns a list of all tags in use by the attached data sources. The list may be empty.

  `setBackgroundMagneticFluxDensity`(B)

    Sets the background magnetic flux density B=(B_East, B_North, B_Vertical)

  `setElementPadding`(pad_x=None, pad_y=None, pad_lat=None, pad_lon=None)

    Sets the amount of padding around the dataset in number of elements (cells).

    When the domain is constructed `pad_x` (`pad_y`) elements are added on each side of the x- (y-) dimension. The arguments must be non-negative.

    Parameters:

    - pad_x (`int`) – Padding per side in x direction (default: no padding)
    - pad_y (`int`) – Padding per side in y direction (default: no padding)

    Note: | `pad_y` is ignored for 2-dimensional datasets.

  `setFractionalPadding`(pad_x=None, pad_y=None, pad_lat=None, pad_lon=None)

    Sets the amount of padding around the dataset as a fraction of the dataset side lengths.

    For example, calling `setFractionalPadding(0.2, 0.1)` with a data source of size 10x20 will result in the padded data set size 14x24 (10*(1+2*0.2), 20*(1+2*0.1))

    Parameters:

    - pad_x (`float`) – Padding per side in x direction (default: no padding)
    - pad_y (`float`) – Padding per side in y direction (default: no padding)
    - pad_lat (`float`) – Padding per side in latitudinal direction (default: no padding)
    - pad_lon (`float`) – Padding per side in longitudinal direction (default: no padding)

    Note: | `pad_y` is ignored for 2-dimensional domains.

  `setGeoPadding`(pad_lat=None, pad_lon=None)

    Sets the amount of padding around the dataset in longitude and latitude.

    The final domain size will be the extent in the latitudinal (in longitudinal) direction of the dataset plus twice the value of `pad_lat` (`pad_lon`). The arguments must be non-negative.

    Parameters:

    - pad_lat (`float` in units of degree) – Padding per side in latitudinal direction (default: 0)
    - pad_lon (`float` in units of degree) – Padding per side in longitudinal direction (default: 0)

    Note: | `pad_lon` is ignored for 2-dimensional domains.
    Note: | this function can only be used if the reference system is not Cartesian

  `setPadding`(pad_x=None, pad_y=None, pad_lat=None, pad_lon=None)

    Sets the amount of padding around the dataset in absolute length units.

    The final domain size will be the length in x (in y) of the dataset plus twice the value of `pad_x` (`pad_y`). The arguments must be non-negative.

    Parameters:

    - pad_x (`float` in units of length (meter)) – Padding per side in x direction (default: no padding)
    - pad_y (`float` in units of length (meter)) – Padding per side in y direction (default: no padding)

    Note: | `pad_y` is ignored for 2-dimensional domains.
    Note: | this function can only be used if the reference system is Cartesian

  `setVerticalExtents`(depth=40000.0, air_layer=10000.0, num_cells=25)

    This method sets the target domain parameters for the vertical dimension.

    Parameters:

    - depth (`float`) – Depth of the domain (in meters)
    - air_layer (`float`) – Depth of the layer above sea level (in meters)
    - num_cells (`int`) – Number of domain elements for the entire vertical dimension

class `esys.downunder.``ErMapperData`(data_type, headerfile, datafile=None, altitude=0.0, error=None, scale_factor=None, null_value=None, reference_system=None)

  Bases: `esys.downunder.datasources.DataSource`

  Data Source for ER Mapper raster data. Note that this class only accepts a very specific type of ER Mapper data input and will raise an exception if other data is found.

  `__init__`(data_type, headerfile, datafile=None, altitude=0.0, error=None, scale_factor=None, null_value=None, reference_system=None)

    Parameters:

    - data_type (`int`) – type of data, must be `GRAVITY` or `MAGNETIC`
    - headerfile (`str`) – ER Mapper header file (usually ends in .ers)
    - datafile (`str`) – ER Mapper binary data file name. If not supplied the name of the header file without ‘.ers’ is assumed
    - altitude (`float`) – altitude of measurements above ground in meters
    - error (`float`) – constant value to use for the data uncertainties. If a value is supplied, it is scaled by the same factor as the measurements. If not provided the error is assumed to be 2 units for all measurements (i.e. 0.2 mGal and 2 nT for gravity and magnetic, respectively)
    - scale_factor (`float`) – the measurements and error values are scaled by this factor. By default, gravity data is assumed to be given in 1e-6 m/s^2 (0.1 mGal), while magnetic data is assumed to be in 1e-9 T (1 nT).
    - null_value (`float`) – value that is used in the file to mark undefined areas. This information is usually included in the file.
    - reference_system (`ReferenceSystem`) – reference coordinate system to be used. For a Cartesian reference (default) the appropriate UTM transformation is applied.

    Note: | consistence in the reference coordinate system and the reference coordinate system used in the data source is not checked.

  `ACOUSTIC` = 2
  `GRAVITY` = 0
  `MAGNETIC` = 1
  `MT` = 3
  `getDataExtents`()

    returns ( (x0, y0), (nx, ny), (dx, dy) )

  `getDataType`()

    Returns the type of survey data managed by this source. Subclasses must return `GRAVITY` or `MAGNETIC` or `ACOUSTIC` as appropriate.

  `getHeightScale`()

    returns the height scale factor to convert from meters to the appropriate units of the reference system used.

    Return type: | `float`

  `getReferenceSystem`()

    returns the reference coordinate system

    Return type: | `ReferenceSystem`

  `getSubsamplingFactor`()

    Returns the subsampling factor that was set via `setSubsamplingFactor` (see there).

  `getSurveyData`(domain, origin, NE, spacing)

    This method is called by the `DomainBuilder` to retrieve the survey data as `Data` objects on the given domain.

    Subclasses should return one or more `Data` objects with survey data interpolated on the given `escript` domain. The exact return type depends on the type of data.

    Parameters:

    - domain (`esys.escript.Domain`) – the escript domain to use
    - origin (`tuple` or `list`) – the origin coordinates of the domain
    - NE (`tuple` or `list`) – the number of domain elements in each dimension
    - spacing (`tuple` or `list`) – the cell sizes (node spacing) in the domain

  `getTags`()

    returns the list of tags

    Return type: | `list`

  `getUtmZone`()

    All data source coordinates are converted to UTM (Universal Transverse Mercator) in order to have useful domain extents. Subclasses should implement this method and return the UTM zone number of the projected coordinates.

  `hasTag`(tag)

    returns true if the data set has tag `tag`

    Return type: | `bool`

  `setSubsamplingFactor`(f)

    Sets the data subsampling factor (default=1).

    The factor is applied in all dimensions. For example a 2D dataset with 300 x 150 data points will be reduced to 150 x 75 when a subsampling factor of 2 is used. This becomes important when adding data of varying resolution to a `DomainBuilder`.

class `esys.downunder.``ForwardModel`

  Bases: `object`

  An abstract forward model that can be plugged into a cost function. Subclasses need to implement `getDefect()`, `getGradient()`, and possibly `getArguments()` and ‘getCoordinateTransformation’.

  `__init__`()

    Initialize self. See help(type(self)) for accurate signature.

  `getArguments`(x)
  `getCoordinateTransformation`()
  `getDefect`(x, *args)
  `getGradient`(x, *args)

class `esys.downunder.``ForwardModelWithPotential`(domain, w, data, coordinates=None, fixPotentialAtBottom=False, tol=1e-08)

  Bases: `esys.downunder.forwardmodels.base.ForwardModel`

  Base class for a forward model using a potential such as magnetic or gravity. It defines a cost function:

  > defect = 1/2 sum_s integrate( ( weight_i[s] * ( r_i - data_i[s] ) )**2 )

  where s runs over the survey, weight_i are weighting factors, data_i are the data, and r_i are the results produced by the forward model. It is assumed that the forward model is produced through postprocessing of the solution of a potential PDE.

  `__init__`(domain, w, data, coordinates=None, fixPotentialAtBottom=False, tol=1e-08)

    initializes a new forward model with potential.

    Parameters:

    - domain (`Domain`) – domain of the model
    - w (`Vector` or list of `Vector`) – data weighting factors
    - data (`Vector` or list of `Vector`) – data
    - coordinates (`ReferenceSystem` or `SpatialCoordinateTransformation`) – defines coordinate system to be used
    - fixPotentialAtBottom (`bool`) – if true potential is fixed to zero at the bottom of the domain in addition to the top.
    - tol (positive `float`) – tolerance of underlying PDE

  `getArguments`(x)
  `getCoordinateTransformation`()

    returns the coordinate transformation being used

    Return type: | `CoordinateTransformation`

  `getData`()

    Returns the data

    Return type: | `list` of `Data`

  `getDataFunctionSpace`()

    Returns the `FunctionSpace` of the data

    Return type: | `FunctionSpace`

  `getDefect`(x, *args)
  `getDefectGradient`(result)
  `getDomain`()

    Returns the domain of the forward model.

    Return type: | `Domain`

  `getGradient`(x, *args)
  `getMisfitWeights`()

    Returns the weights of the misfit function

    Return type: | `list` of `Data`

  `getPDE`()

    Return the underlying PDE.

    Return type: | `LinearPDE`

  `getSurvey`(index=None)

    Returns the pair (data_index, weight_index), where data_i is the data of survey i, weight_i is the weighting factor for survey i. If index is None, all surveys will be returned in a pair of lists.

class `esys.downunder.``FunctionJob`(fn, *args, **kwargs)

  Bases: `esys.escriptcore.splitworld.Job`

  Takes a python function (with only self and keyword params) to be called as the work method

  `__init__`(fn, *args, **kwargs)

    It ignores all of its parameters, except that, it requires the following as keyword arguments

    Variables:

    - domain – Domain to be used as the basis for all `Data` and PDEs in this Job.
    - jobid – sequence number of this job. The first job has id=1

  `clearExports`()

    Remove exported values from the map

  `clearImports`()

    Remove imported values from their map

  `declareImport`(name)

    Adds name to the list of imports

  `exportValue`(name, v)

    Make value v available to other Jobs under the label name. name must have already been registered with the SplitWorld instance. For use inside the work() method.

    Variables:

    - name – registered label for exported value
    - v – value to be imported

  `importValue`(name)

    For use inside the work() method.

    Variables: | name – label for imported value.

  `setImportValue`(name, v)

    Use to make a value available to the job (ie called from outside the job)

    Variables:

    - name – label used to identify this import
    - v – value to be imported

  `work`()

    Need to be overloaded for the job to actually do anthing. A return value of True indicates this job thinks it is done. A return value of False indicates work still to be done

class `esys.downunder.``GeodeticCoordinateTransformation`(domain, reference=<esys.downunder.coordinates.GeodeticReferenceSystem object>)

  Bases: `esys.downunder.coordinates.SpatialCoordinateTransformation`

  A geodetic coordinate transformation

  `__init__`(domain, reference=<esys.downunder.coordinates.GeodeticReferenceSystem object>)

    set up the orthogonal coordinate transformation.

    Parameters:

    - domain (`esys.escript.AbstractDomain`) – domain in the domain of the coordinate transformation
    - reference (`ReferenceSystem`) – the reference system

  `getDomain`()

    returns the domain of the coordinate transformation.

    Return type: | `esys.escript.AbstractDomain`

  `getGradient`(u)

    returns the gradient of a scalar function in direction of the coordinate axis.

    Return type: | `esys.escript.Vector`

  `getReferenceSystem`()

    returns the reference system used to to define the coordinate transformation

    Return type: | `ReferenceSystem`

  `getScalingFactors`()

    returns the scaling factors

    Return type: | `esys.escript.Vector`

  `getVolumeFactor`()

    returns the volume factor for the coordinate transformation

    Return type: | `esys.escript.Scalar`

  `isCartesian`()

    returns `True` if the scaling factors (and the volume factor) are equal to 1

    Return type: | `bool`

  `isTheSame`(other)

    test if argument `other` defines the same coordinate transformation

    Parameters: | other (`SpatialCoordinateTransformation`) – a second coordinate transformation
    Returns: | `True` if other defines then same coordinate transformation
    Return type: | `bool`

class `esys.downunder.``GeodeticReferenceSystem`(a=6378137.0, f=0.0033528106647474805, angular_unit=0.017453292519943295, height_unit=1000.0, name='WGS84')

  Bases: `esys.downunder.coordinates.ReferenceSystem`

  Identifies a Geodetic coordinate system

  `__init__`(a=6378137.0, f=0.0033528106647474805, angular_unit=0.017453292519943295, height_unit=1000.0, name='WGS84')

    initializes a geodetic reference system

    Parameters:

    - a (positive `double`) – semi-major axis in meter
    - f (non-negative `double`, less than one) – flattening
    - name (`str`) – name of the reference system
    - angular_unit (positive `double`) – factor to scale the unit of latitude and longitude to radians.
    - height_unit (positive `double`) – factor to scale the unit of latitude and longitude to radians.

  `createTransformation`(domain)

    creates an appropriate coordinate transformation on a given domain

    Parameters: | domain (`esys.escript.AbstractDomain`) – domain of transformation
    Return type: | `SpatialCoordinateTransformation`

  `getAngularUnit`()

    returns the angular unit

  `getFlattening`()

    returns the flattening

  `getHeightUnit`()

    returns the height unit

  `getName`()

    returns the name of the reference system

  `getSemiMajorAxis`()

    returns the length of semi major axis

  `getSemiMinorAxis`()

    returns the length of semi minor axis

  `isCartesian`()

    returns if the reference system is Cartesian

    Return type: | `bool`

  `isTheSame`(other)

    test if `other` defines the same reference system

    Parameters: | other (`ReferenceSystem`) – a second reference system
    Returns: | `True` if other defines then same reference system
    Return type: | `bool`

    Note

    two `GeodeticReferenceSystem` are considered to be the same if the use the same semi major axis, the same flattening and the same angular unit.

class `esys.downunder.``GravityInversion`(solverclass=None, debug=False, self_demagnetization=False, magnetic_intensity_data=False)

  Bases: `esys.downunder.inversions.InversionDriver`

  Driver class to perform an inversion of Gravity (Bouguer) anomaly data. The class uses the standard `Regularization` class for a single level set function, `DensityMapping` mapping, and the gravity forward model `GravityModel`.

  `__init__`(solverclass=None, debug=False, self_demagnetization=False, magnetic_intensity_data=False)

    creates an instance of an inversion driver.

    Parameters:

    - solverclass ('AbstractMinimizer'.) – class of the solver to be used.
    - self_demagnetization – if True self-demagnitization is applied.
    - magnetic_intensity_data – if True magnetic intensity is used in the cost function.

  `fixGravityPotentialAtBottom`(status=False)

    indicates to fix the gravity potential at the bottom to zero (in addition to the top)

    Parameters: | status (`bool`) – if True gravity potential at the bottom is set to zero

  `fixMagneticPotentialAtBottom`(status=True)

    indicates to fix the magnetic potential at the bottom to zero (in addition to the top)

    Parameters: | status (`bool`) – if True magnetic potential at the bottom is set to zero

  `getCostFunction`()

    returns the cost function of the inversion.

    Return type: | ‘InversionCostFunction’

  `getDomain`()

    returns the domain of the inversion

    Return type: | `Domain`

  `getLevelSetFunction`()

    returns the level set function as solution of the optimization problem

    Return type: | `Data`

  `getSolver`()

    The solver to be used in the inversion process. See the minimizers module for available solvers. By default, the L-BFGS minimizer is used.

    Return type: | ‘AbstractMinimizer’.

  `isSetUp`()

    returns True if the inversion is set up and is ready to run.

    Return type: | `bool`

  `run`()

    Executes the inversion.

    Returns: | physical parameters as result of the inversion
    Return type: | `list` of physical parameters or a physical parameter

  `setCostFunction`(costfunction)

    sets the cost function of the inversion. This function needs to be called before the inversion iteration can be started.

    Parameters: | costfunction ('InversionCostFunction') – domain of the inversion

  `setInitialGuess`(rho=None)

    set the initial guess rho for density the inversion iteration. If no rho present then an appropriate initial guess is chosen.

    Parameters: | rho (`Scalar`) – initial value for the density anomaly.

  `setSolverCallback`(callback=None)

    Sets the callback function which is called after every solver iteration.

  `setSolverMaxIterations`(maxiter=None)

    Sets the maximum number of solver iterations to run. If `maxiter` is reached the iteration is terminated and `MinimizerMaxIterReached` is thrown.

    Parameters: | maxiter (positive `int`) – maximum number of iteration steps.

  `setSolverTolerance`(m_tol=None, J_tol=None)

    Sets the error tolerance for the solver. An acceptable solution is considered to be found once the tolerance is reached.

    Parameters:

    - m_tol (`float` or `None`) – tolerance for changes to level set function. If `None` changes to the level set function are not checked for convergence during iteration.
    - J_tol (`float` or `None`) – tolerance for changes to cost function. If `None` changes to the cost function are not checked for convergence during iteration.

    Note: | if both arguments are `None` the default setting m_tol=1e-4, J_tol=None is used.

  `setup`(domainbuilder, rho0=None, drho=None, z0=None, beta=None, w0=None, w1=None, rho_at_depth=None)

    Sets up the inversion parameters from a `DomainBuilder`.

    Parameters:

    - domainbuilder (`DomainBuilder`) – Domain builder object with gravity source(s)
    - rho0 (`float` or `Scalar`) – reference density, see `DensityMapping`. If not specified, zero is used.
    - drho (`float` or `Scalar`) – density scale, see `DensityMapping`. If not specified, 2750kg/m^3 is used.
    - z0 (`float` or `Scalar`) – reference depth for depth weighting, see `DensityMapping`. If not specified, zero is used.
    - beta (`float` or `Scalar`) – exponent for depth weighting, see `DensityMapping`. If not specified, zero is used.
    - w0 (`Scalar` or `float`) – weighting factor for level set term regularization. If not set zero is assumed.
    - w1 (`Vector` or list of `float`) – weighting factor for the gradient term in the regularization. If not set zero is assumed
    - rho_at_depth (`float` or `None`) – value for density at depth, see `DomainBuilder`.

  `siloWriterCallback`(k, x, Jx, g_Jx, norm_dJ=None, norm_dx=None)

    callback function that can be used to track the solution

    Parameters:

    - k – iteration count
    - x – current approximation
    - Jx – value of cost function
    - g_Jx – gradient of f at x

class `esys.downunder.``GravityModel`(domain, w, g, gravity_constant=6.6742e-11, coordinates=None, fixPotentialAtBottom=False, tol=1e-08)

  Bases: `esys.downunder.forwardmodels.base.ForwardModelWithPotential`

  Forward Model for gravity inversion as described in the inversion cookbook.

  `__init__`(domain, w, g, gravity_constant=6.6742e-11, coordinates=None, fixPotentialAtBottom=False, tol=1e-08)

    Creates a new gravity model on the given domain with one or more surveys (w, g).

    Parameters:

    - domain (`Domain`) – domain of the model
    - w (`Vector` or list of `Vector`) – data weighting factors
    - g (`Vector` or list of `Vector`) – gravity anomaly data
    - coordinates (ReferenceSystem` or `SpatialCoordinateTransformation`) – defines coordinate system to be used
    - tol (positive `float`) – tolerance of underlying PDE
    - fixPotentialAtBottom (`bool`) – if true potential is fixed to zero at the base of the domain in addition to the top

    Note: | It is advisable to call rescaleWeights() to rescale weights before starting the inversion.

  `getArguments`(rho)

    Returns precomputed values shared by `getDefect()` and `getGradient()`.

    Parameters: | rho (`Scalar`) – a suggestion for the density distribution
    Returns: | gravity potential and corresponding gravity field.
    Return type: | `Scalar`, `Vector`

  `getCoordinateTransformation`()

    returns the coordinate transformation being used

    Return type: | `CoordinateTransformation`

  `getData`()

    Returns the data

    Return type: | `list` of `Data`

  `getDataFunctionSpace`()

    Returns the `FunctionSpace` of the data

    Return type: | `FunctionSpace`

  `getDefect`(rho, phi, gravity_force)

    Returns the value of the defect

    Parameters:

    - rho (`Scalar`) – density distribution
    - phi (`Scalar`) – corresponding potential
    - gravity_force (`Vector`) – gravity force

    Return type: | `float`

  `getDefectGradient`(result)
  `getDomain`()

    Returns the domain of the forward model.

    Return type: | `Domain`

  `getGradient`(rho, phi, gravity_force)

    Returns the gradient of the defect with respect to density.

    Parameters:

    - rho (`Scalar`) – density distribution
    - phi (`Scalar`) – corresponding potential
    - gravity_force (`Vector`) – gravity force

    Return type: | `Scalar`

  `getMisfitWeights`()

    Returns the weights of the misfit function

    Return type: | `list` of `Data`

  `getPDE`()

    Return the underlying PDE.

    Return type: | `LinearPDE`

  `getPotential`(rho)

    Calculates the gravity potential for a given density distribution.

    Parameters: | rho (`Scalar`) – a suggestion for the density distribution
    Returns: | gravity potential
    Return type: | `Scalar`

  `getSurvey`(index=None)

    Returns the pair (data_index, weight_index), where data_i is the data of survey i, weight_i is the weighting factor for survey i. If index is None, all surveys will be returned in a pair of lists.

  `rescaleWeights`(scale=1.0, rho_scale=1.0)

    rescales the weights such that

    sum_s integrate( ( w_i[s] *g_i[s]) (w_j[s]*1/L_j) * L**2 * 4*pi*G*rho_scale )=scale

    Parameters:

    - scale (positive `float`) – scale of data weighting factors
    - rho_scale (`Scalar`) – scale of density.

class `esys.downunder.``HTIWave`(domain, v_p, v_s, wavelet, source_tag, source_vector=[1.0, 0.0, 0.0], eps=0.0, gamma=0.0, delta=0.0, rho=1.0, dt=None, u0=None, v0=None, absorption_zone=None, absorption_cut=0.01, lumping=True, disable_fast_assemblers=False)

  Bases: `esys.downunder.seismic.WaveBase`

  Solving the HTI wave equation (along the x_0 axis)

  Note: | In case of a two dimensional domain a horizontal domain is considered, i.e. the depth component is dropped.

  `__init__`(domain, v_p, v_s, wavelet, source_tag, source_vector=[1.0, 0.0, 0.0], eps=0.0, gamma=0.0, delta=0.0, rho=1.0, dt=None, u0=None, v0=None, absorption_zone=None, absorption_cut=0.01, lumping=True, disable_fast_assemblers=False)

    initialize the VTI wave solver

    Parameters:

    - domain (`Domain`) – domain of the problem
    - v_p (`escript.Scalar`) – vertical p-velocity field
    - v_s (`escript.Scalar`) – vertical s-velocity field
    - wavelet (`Wavelet`) – wavelet to describe the time evolution of source term
    - source_tag ('str' or 'int') – tag of the source location
    - source_vector – source orientation vector
    - eps – first Thompsen parameter
    - delta – second Thompsen parameter
    - gamma – third Thompsen parameter
    - rho – density
    - dt – time step size. If not present a suitable time step size is calculated.
    - u0 – initial solution. If not present zero is used.
    - v0 – initial solution change rate. If not present zero is used.
    - absorption_zone – thickness of absorption zone
    - absorption_cut – boundary value of absorption decay factor
    - lumping – if True mass matrix lumping is being used. This is accelerates the computing but introduces some diffusion.
    - disable_fast_assemblers – if True, forces use of slower and more general PDE assemblers

  `getTimeStepSize`()
  `setQ`(q)

    sets the PDE q value

    Parameters: | q – the value to set

  `update`(t)

    returns the solution for the next time marker t which needs to greater than the time marker from the previous call.

class `esys.downunder.``InversionCostFunction`(regularization, mappings, forward_models)

  Bases: `esys.downunder.costfunctions.MeteredCostFunction`

  Class to define cost function J(m) for inversion with one or more forward models based on a multi-valued level set function m:

  J(m) = J_reg(m) + sum_f mu_f * J_f(p)

  where J_reg(m) is the regularization and cross gradient component of the cost function applied to a level set function m, J_f(p) are the data defect cost functions involving a physical forward model using the physical parameter(s) p and mu_f is the trade-off factor for model f.

  A forward model depends on a set of physical parameters p which are constructed from components of the level set function m via mappings.

  Example 1 (single forward model):
    m=Mapping() f=ForwardModel() J=InversionCostFunction(Regularization(), m, f)
  Example 2 (two forward models on a single valued level set)

    m0=Mapping() m1=Mapping() f0=ForwardModel() f1=ForwardModel()

    J=InversionCostFunction(Regularization(), mappings=[m0, m1], forward_models=[(f0, 0), (f1,1)])

  Example 3 (two forward models on 2-valued level set)

    m0=Mapping() m1=Mapping() f0=ForwardModel() f1=ForwardModel()

    J=InversionCostFunction(Regularization(self.numLevelSets=2), mappings=[(m0,0), (m1,0)], forward_models=[(f0, 0), (f1,1)])

  Note: | If provides_inverse_Hessian_approximation is true, then the class provides an approximative inverse of the Hessian operator.

  `__init__`(regularization, mappings, forward_models)

    constructor for the cost function. Stores the supplied object references and sets default weights.

    Parameters:

    - regularization (`Regularization`) – the regularization part of the cost function
    - mappings (`Mapping` or `list`) – the mappings to calculate physical parameters from the regularization. This is a list of 2-tuples (map, i) where the first component map defines a `Mapping` and the second component i defines the index of the component of level set function to be used to calculate the mapping. Items in the list may also be just `Mapping` objects in which case the entire level set function is fed into the `Mapping` (typically used for a single-component level set function.
    - forward_models – the forward models involved in the calculation of the cost function. This is a list of 2-tuples (f, ii) where the first component f defines a `ForwardModel` and the second component ii a list of indexes referring to the physical parameters in the `mappings` list. The 2-tuple can be replaced by a `ForwardModel` if the `mappings` list has a single entry.
    - forward_models – `ForwardModel` or `list`

  `createLevelSetFunction`(*props)

    returns an instance of an object used to represent a level set function initialized with zeros. Components can be overwritten by physical properties `props`. If present entries must correspond to the `mappings` arguments in the constructor. Use `None` for properties for which no value is given.

  `getArguments`(x)

    returns precalculated values that are shared in the calculation of f(x) and grad f(x) and the Hessian operator

    Note

    The tuple returned by this call will be passed back to this `CostFunction` in other calls(eg: `getGradient`). Its contents are not specified at this level because no code, other than the `CostFunction` which created it, will be interacting with it. That is, the implementor can put whatever information they find useful in it.

    Parameters: | x (x-type) – location of derivative
    Return type: | `tuple`

  `getComponentValues`(m, *args)
  `getDomain`()

    returns the domain of the cost function

    Return type: | `Domain`

  `getDualProduct`(x, r)

    returns the dual product of `x` and `r`

    Return type: | `float`

  `getForwardModel`(idx=None)

    returns the idx-th forward model.

    Parameters: | idx (`int`) – model index. If cost function contains one model only `idx` can be omitted.

  `getGradient`(x, *args)

    returns the gradient of f at x using the precalculated values for x.

    Parameters:

    - x (x-type) – location of derivative
    - args – pre-calculated values for `x` from `getArguments()`

    Return type: | r-type

  `getInverseHessianApproximation`(x, r, *args)

    returns an approximative evaluation p of the inverse of the Hessian operator of the cost function for a given gradient r at a given location x: H(x) p = r

    Note

    In general it is assumed that the Hessian H(x) needs to be calculate in each call for a new location x. However, the solver may suggest that this is not required, typically when the iteration is close to completeness.

    Parameters:

    - x (x-type) – location of Hessian operator to be evaluated.
    - r (r-type) – a given gradient
    - args – pre-calculated values for `x` from `getArguments()`

    Return type: | x-type

  `getNorm`(x)

    returns the norm of `x`

    Return type: | `float`

  `getNumTradeOffFactors`()

    returns the number of trade-off factors being used including the trade-off factors used in the regularization component.

    Return type: | `int`

  `getProperties`(m, return_list=False)

    returns a list of the physical properties from a given level set function m using the mappings of the cost function.

    Parameters:

    - m (`Data`) – level set function
    - return_list (`bool`) – if `True` a list is returned.

    Return type: | `list` of `Data`

  `getRegularization`()

    returns the regularization

    Return type: | `Regularization`

  `getTradeOffFactors`(mu=None)

    returns a list of the trade-off factors.

    Return type: | `list` of `float`

  `getTradeOffFactorsModels`()

    returns the trade-off factors for the forward models

    Return type: | `float` or `list` of `float`

  `getValue`(x, *args)

    returns the value f(x) using the precalculated values for x.

    Parameters: | x (x-type) – a solution approximation
    Return type: | `float`

  `provides_inverse_Hessian_approximation` = True
  `resetCounters`()

    resets all statistical counters

  `setTradeOffFactors`(mu=None)

    sets the trade-off factors for the forward model and regularization terms.

    Parameters: | mu (`list` of `float`) – list of trade-off factors.

  `setTradeOffFactorsModels`(mu=None)

    sets the trade-off factors for the forward model components.

    Parameters: | mu (`float` in case of a single model or a `list` of `float` with the length of the number of models.) – list of the trade-off factors. If not present ones are used.

  `setTradeOffFactorsRegularization`(mu=None, mu_c=None)

    sets the trade-off factors for the regularization component of the cost function, see `Regularization` for details.

    Parameters:

    - mu – trade-off factors for the level-set variation part
    - mu_c – trade-off factors for the cross gradient variation part

  `updateHessian`()

    notifies the class that the Hessian operator needs to be updated.

class `esys.downunder.``InversionDriver`(solverclass=None, debug=False, self_demagnetization=False, magnetic_intensity_data=False)

  Bases: `object`

  Base class for running an inversion

  `__init__`(solverclass=None, debug=False, self_demagnetization=False, magnetic_intensity_data=False)

    creates an instance of an inversion driver.

    Parameters:

    - solverclass ('AbstractMinimizer'.) – class of the solver to be used.
    - self_demagnetization – if True self-demagnitization is applied.
    - magnetic_intensity_data – if True magnetic intensity is used in the cost function.

  `fixGravityPotentialAtBottom`(status=False)

    indicates to fix the gravity potential at the bottom to zero (in addition to the top)

    Parameters: | status (`bool`) – if True gravity potential at the bottom is set to zero

  `fixMagneticPotentialAtBottom`(status=True)

    indicates to fix the magnetic potential at the bottom to zero (in addition to the top)

    Parameters: | status (`bool`) – if True magnetic potential at the bottom is set to zero

  `getCostFunction`()

    returns the cost function of the inversion.

    Return type: | ‘InversionCostFunction’

  `getDomain`()

    returns the domain of the inversion

    Return type: | `Domain`

  `getLevelSetFunction`()

    returns the level set function as solution of the optimization problem

    Return type: | `Data`

  `getSolver`()

    The solver to be used in the inversion process. See the minimizers module for available solvers. By default, the L-BFGS minimizer is used.

    Return type: | ‘AbstractMinimizer’.

  `isSetUp`()

    returns True if the inversion is set up and is ready to run.

    Return type: | `bool`

  `run`()

    Executes the inversion.

    Returns: | physical parameters as result of the inversion
    Return type: | `list` of physical parameters or a physical parameter

  `setCostFunction`(costfunction)

    sets the cost function of the inversion. This function needs to be called before the inversion iteration can be started.

    Parameters: | costfunction ('InversionCostFunction') – domain of the inversion

  `setInitialGuess`(*props)

    Sets the initial guess for the inversion iteration. By default zero is used.

  `setSolverCallback`(callback=None)

    Sets the callback function which is called after every solver iteration.

  `setSolverMaxIterations`(maxiter=None)

    Sets the maximum number of solver iterations to run. If `maxiter` is reached the iteration is terminated and `MinimizerMaxIterReached` is thrown.

    Parameters: | maxiter (positive `int`) – maximum number of iteration steps.

  `setSolverTolerance`(m_tol=None, J_tol=None)

    Sets the error tolerance for the solver. An acceptable solution is considered to be found once the tolerance is reached.

    Parameters:

    - m_tol (`float` or `None`) – tolerance for changes to level set function. If `None` changes to the level set function are not checked for convergence during iteration.
    - J_tol (`float` or `None`) – tolerance for changes to cost function. If `None` changes to the cost function are not checked for convergence during iteration.

    Note: | if both arguments are `None` the default setting m_tol=1e-4, J_tol=None is used.

  `setup`(*args, **k_args)

    sets up the inversion. The default implementation does nothing but it is advised to call this method before calling `run()`.

class `esys.downunder.``IsostaticPressure`(domain, p0=0.0, level0=0, gravity0=-9.81, background_density=2670.0, gravity_constant=6.6742e-11, coordinates=None, tol=1e-08)

  Bases: `object`

  class to calculate isostatic pressure field correction due to gravity forces

  `__init__`(domain, p0=0.0, level0=0, gravity0=-9.81, background_density=2670.0, gravity_constant=6.6742e-11, coordinates=None, tol=1e-08)

    Parameters:

    - domain (`Domain`) – domain of the model
    - p0 (scalar `Data` or `float`) – pressure at level0
    - background_density (`float`) – defines background_density in kg/m^3
    - coordinates (ReferenceSystem` or `SpatialCoordinateTransformation`) – defines coordinate system to be used
    - tol (positive `float`) – tolerance of underlying PDE
    - level0 (`float`) – pressure for z>=`level0` is set to zero.
    - gravity0 (`float`) – vertical background gravity at `level0`

  `getPressure`(g=None, rho=None)

    return the pressure for gravity force anomaly `g` and density anomaly `rho`

    Parameters:

    - g (`Vector`) – gravity anomaly data
    - rho (`Scalar`) – gravity anomaly data

    Returns: | pressure distribution
    Return type: | `Scalar`

class `esys.downunder.``Job`(*args, **kwargs)

  Bases: `object`

  Describes a sequence of work to be carried out in a subworld. The instances of this class used in the subworlds will be constructed by the system. To do specific work, this class should be subclassed and the work() (and possibly __init__ methods overloaded). The majority of the work done by the job will be in the overloaded work() method. The work() method should retrieve values from the outside using importValue() and pass values to the rest of the system using exportValue(). The rest of the methods should be considered off limits.

  `__init__`(*args, **kwargs)

    It ignores all of its parameters, except that, it requires the following as keyword arguments

    Variables:

    - domain – Domain to be used as the basis for all `Data` and PDEs in this Job.
    - jobid – sequence number of this job. The first job has id=1

  `clearExports`()

    Remove exported values from the map

  `clearImports`()

    Remove imported values from their map

  `declareImport`(name)

    Adds name to the list of imports

  `exportValue`(name, v)

    Make value v available to other Jobs under the label name. name must have already been registered with the SplitWorld instance. For use inside the work() method.

    Variables:

    - name – registered label for exported value
    - v – value to be imported

  `importValue`(name)

    For use inside the work() method.

    Variables: | name – label for imported value.

  `setImportValue`(name, v)

    Use to make a value available to the job (ie called from outside the job)

    Variables:

    - name – label used to identify this import
    - v – value to be imported

  `work`()

    Need to be overloaded for the job to actually do anthing. A return value of True indicates this job thinks it is done. A return value of False indicates work still to be done

class `esys.downunder.``JointGravityMagneticInversion`(solverclass=None, debug=False, self_demagnetization=False, magnetic_intensity_data=False)

  Bases: `esys.downunder.inversions.InversionDriver`

  Driver class to perform a joint inversion of Gravity (Bouguer) and magnetic anomaly data. The class uses the standard `Regularization` class for two level set functions with cross-gradient correlation, `DensityMapping` and `SusceptibilityMapping` mappings, the gravity forward model `GravityModel` and the linear magnetic forward model `MagneticModel`.

  `__init__`(solverclass=None, debug=False, self_demagnetization=False, magnetic_intensity_data=False)

    creates an instance of an inversion driver.

    Parameters:

    - solverclass ('AbstractMinimizer'.) – class of the solver to be used.
    - self_demagnetization – if True self-demagnitization is applied.
    - magnetic_intensity_data – if True magnetic intensity is used in the cost function.

  `DENSITY` = 0
  `SUSCEPTIBILITY` = 1
  `fixGravityPotentialAtBottom`(status=False)

    indicates to fix the gravity potential at the bottom to zero (in addition to the top)

    Parameters: | status (`bool`) – if True gravity potential at the bottom is set to zero

  `fixMagneticPotentialAtBottom`(status=True)

    indicates to fix the magnetic potential at the bottom to zero (in addition to the top)

    Parameters: | status (`bool`) – if True magnetic potential at the bottom is set to zero

  `getCostFunction`()

    returns the cost function of the inversion.

    Return type: | ‘InversionCostFunction’

  `getDomain`()

    returns the domain of the inversion

    Return type: | `Domain`

  `getLevelSetFunction`()

    returns the level set function as solution of the optimization problem

    Return type: | `Data`

  `getSolver`()

    The solver to be used in the inversion process. See the minimizers module for available solvers. By default, the L-BFGS minimizer is used.

    Return type: | ‘AbstractMinimizer’.

  `isSetUp`()

    returns True if the inversion is set up and is ready to run.

    Return type: | `bool`

  `run`()

    Executes the inversion.

    Returns: | physical parameters as result of the inversion
    Return type: | `list` of physical parameters or a physical parameter

  `setCostFunction`(costfunction)

    sets the cost function of the inversion. This function needs to be called before the inversion iteration can be started.

    Parameters: | costfunction ('InversionCostFunction') – domain of the inversion

  `setInitialGuess`(rho=None, k=None)

    set the initial guess rho for density and k for susceptibility for the inversion iteration.

    Parameters:

    - rho (`Scalar`) – initial value for the density anomaly.
    - k (`Scalar`) – initial value for the susceptibility anomaly.

  `setSolverCallback`(callback=None)

    Sets the callback function which is called after every solver iteration.

  `setSolverMaxIterations`(maxiter=None)

    Sets the maximum number of solver iterations to run. If `maxiter` is reached the iteration is terminated and `MinimizerMaxIterReached` is thrown.

    Parameters: | maxiter (positive `int`) – maximum number of iteration steps.

  `setSolverTolerance`(m_tol=None, J_tol=None)

    Sets the error tolerance for the solver. An acceptable solution is considered to be found once the tolerance is reached.

    Parameters:

    - m_tol (`float` or `None`) – tolerance for changes to level set function. If `None` changes to the level set function are not checked for convergence during iteration.
    - J_tol (`float` or `None`) – tolerance for changes to cost function. If `None` changes to the cost function are not checked for convergence during iteration.

    Note: | if both arguments are `None` the default setting m_tol=1e-4, J_tol=None is used.

  `setup`(domainbuilder, rho0=None, drho=None, rho_z0=None, rho_beta=None, k0=None, dk=None, k_z0=None, k_beta=None, w0=None, w1=None, w_gc=None, rho_at_depth=None, k_at_depth=None)

    Sets up the inversion from an instance `domainbuilder` of a `DomainBuilder`. Gravity and magnetic data attached to the `domainbuilder` are considered in the inversion. If magnetic data are given as scalar it is assumed that values are collected in direction of the background magnetic field.

    Parameters:

    - domainbuilder (`DomainBuilder`) – Domain builder object with gravity source(s)
    - rho0 (`float` or `Scalar`) – reference density, see `DensityMapping`. If not specified, zero is used.
    - drho (`float` or `Scalar`) – density scale, see `DensityMapping`. If not specified, 2750kg/m^3 is used.
    - rho_z0 (`float` or `Scalar`) – reference depth for depth weighting for density, see `DensityMapping`. If not specified, zero is used.
    - rho_beta (`float` or `Scalar`) – exponent for depth weighting for density, see `DensityMapping`. If not specified, zero is used.
    - k0 (`float` or `Scalar`) – reference susceptibility, see `SusceptibilityMapping`. If not specified, zero is used.
    - dk (`float` or `Scalar`) – susceptibility scale, see `SusceptibilityMapping`. If not specified, 2750kg/m^3 is used.
    - k_z0 (`float` or `Scalar`) – reference depth for depth weighting for susceptibility, see `SusceptibilityMapping`. If not specified, zero is used.
    - k_beta (`float` or `Scalar`) – exponent for depth weighting for susceptibility, see `SusceptibilityMapping`. If not specified, zero is used.
    - w0 (`es.Data` or `ndarray` of shape (2,)) – weighting factors for level set term regularization, see `Regularization`. If not set zero is assumed.
    - w1 (`es.Data` or `ndarray` of shape (2,DIM)) – weighting factor for the gradient term in the regularization see `Regularization`. If not set zero is assumed
    - w_gc (`Scalar` or `float`) – weighting factor for the cross gradient term in the regularization, see `Regularization`. If not set one is assumed
    - k_at_depth (`float` or `None`) – value for susceptibility at depth, see `DomainBuilder`.
    - rho_at_depth (`float` or `None`) – value for density at depth, see `DomainBuilder`.

  `siloWriterCallback`(k, x, Jx, g_Jx, norm_dJ=None, norm_dx=None)

    callback function that can be used to track the solution

    Parameters:

    - k – iteration count
    - x – current approximation
    - Jx – value of cost function
    - g_Jx – gradient of f at x

class `esys.downunder.``LinearMapping`(a=1.0, p0=0.0)

  Bases: `esys.downunder.mappings.Mapping`

  Maps a parameter by a linear transformation p = a * m + p0

  `__init__`(a=1.0, p0=0.0)

    Initialize self. See help(type(self)) for accurate signature.

  `getDerivative`(m)

    returns the value for the derivative of the mapping for m

  `getInverse`(p)

    returns the value of the inverse of the mapping for s

  `getTypicalDerivative`()

    returns a typical value for the derivative

  `getValue`(m)

    returns the value of the mapping for m

class `esys.downunder.``LinearPDE`(domain, numEquations=None, numSolutions=None, isComplex=False, 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()

  `__init__`(domain, numEquations=None, numSolutions=None, isComplex=False, debug=False)

    Initializes a new linear PDE.

    Parameters:

    - domain (`Domain`) – domain of the PDE
    - numEquations – number of equations. If `None` the number of equations is extracted from the PDE coefficients.
    - numSolutions – number of solution components. If `None` the number of solution components is extracted from the PDE coefficients.
    - debug – if True debug information is printed

  `addPDEToLumpedSystem`(operator, a, b, c, hrz_lumping)

    adds a PDE to the lumped system, results depend on domain

    Parameters:

    - mat (`OperatorAdapter`) –
    - rhs (`Data`) –
    - a (`Data`) –
    - b (`Data`) –
    - c (`Data`) –
    - hrz_lumping (`bool`) –

  `addPDEToRHS`(righthandside, X, Y, y, y_contact, y_dirac)

    adds a PDE to the right hand side, results depend on domain

    Parameters:

    - mat (`OperatorAdapter`) –
    - righthandside (`Data`) –
    - X (`Data`) –
    - Y (`Data`) –
    - y (`Data`) –
    - y_contact (`Data`) –
    - y_dirac (`Data`) –

  `addPDEToSystem`(operator, righthandside, A, B, C, D, X, Y, d, y, d_contact, y_contact, d_dirac, y_dirac)

    adds a PDE to the system, results depend on domain

    Parameters:

    - mat (`OperatorAdapter`) –
    - rhs (`Data`) –
    - A (`Data`) –
    - B (`Data`) –
    - C (`Data`) –
    - D (`Data`) –
    - X (`Data`) –
    - Y (`Data`) –
    - d (`Data`) –
    - y (`Data`) –
    - d_contact (`Data`) –
    - y_contact (`Data`) –
    - d_dirac (`Data`) –
    - y_dirac (`Data`) –

  `addToRHS`(rhs, data)

    adds a PDE to the right hand side, results depend on domain

    Parameters:

    - mat (`OperatorAdapter`) –
    - righthandside (`Data`) –
    - data (`list`) –

  `addToSystem`(op, rhs, data)

    adds a PDE to the system, results depend on domain

    Parameters:

    - mat (`OperatorAdapter`) –
    - rhs (`Data`) –
    - data (`list`) –

  `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.

  `isComplex`()

    Returns true if this is a complex-valued LinearProblem, false if real-valued.

    Return type: | `bool`

  `isHermitian`()

    Checks if the pde is indicated to be Hermitian.

    Returns: | True if a Hermitian PDE is indicated, False otherwise
    Return type: | `bool`
    Note: | the method is equivalent to use getSolverOptions().isHermitian()

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

  `preservePreconditioner`(preserve=True)

    Notifies the PDE that the preconditioner should not be reset when making changes to the operator.

    Building the preconditioner data can be quite expensive (e.g. for multigrid methods) so if it is known that changes to the operator are going to be minor calling this method can speed up successive PDE solves.

    Note: | Not all operator types support this.
    Parameters: | preserve (`bool`) – if True, preconditioner will be preserved, otherwise it will be reset when making changes to the operator, which is the default behaviour.

  `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.

  `setHermitian`(flag=False)

    Sets the Hermitian flag to `flag`.

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

  `setHermitianOff`()

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

  `setHermitianOn`()

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

  `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

  `shouldPreservePreconditioner`()

    Returns true if the preconditioner / factorisation should be kept even when resetting the operator.

    Return type: | `bool`

  `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.downunder.``Locator`(where, x=array([0., 0., 0.]))

  Bases: `object`

  Locator provides access to the values of data objects at a given spatial coordinate x.

  In fact, a Locator object finds the sample in the set of samples of a given function space or domain which is closest to the given point x.

  `__init__`(where, x=array([0., 0., 0.]))

    Initializes a Locator to access values in Data objects on the Doamin or FunctionSpace for the sample point which is closest to the given point x.

    Parameters:

    - where (`escript.FunctionSpace`) – function space
    - x (`numpy.ndarray` or `list` of `numpy.ndarray`) – location(s) of the Locator

  `getFunctionSpace`()

    Returns the function space of the Locator.

  `getId`(item=None)

    Returns the identifier of the location.

  `getValue`(data)

    Returns the value of `data` at the Locator if `data` is a `Data` object otherwise the object is returned.

  `getX`()

    Returns the exact coordinates of the Locator.

  `setValue`(data, v)

    Sets the value of the `data` at the Locator.

class `esys.downunder.``MT2DModelTEMode`(domain, omega, x, Z_XY, eta=None, w0=1.0, mu=1.2566370614359173e-06, sigma0=0.01, airLayerLevel=None, coordinates=None, Ex_top=1, fixAtTop=False, tol=1e-08, saveMemory=False, directSolver=True)

  Bases: `esys.downunder.forwardmodels.magnetotelluric2d.MT2DBase`

  Forward Model for two dimensional MT model in the TE mode for a given frequency omega. It defines a cost function:

  > - defect = 1/2 integrate( sum_s w^s * ( E_x/H_y - Z_XY^s ) ) ** 2 *

  where E_x is the horizontal electric field perpendicular to the YZ-domain, horizontal magnetic field H_y=1/(i*omega*mu) * E_{x,z} with complex unit i and permeability mu. The weighting factor w^s is set to

  > - w^s(X) = w_0^s *

  if length(X-X^s) <= eta and zero otherwise. X^s is the location of impedance measurement Z_XY^s, w_0^s is the level of confidence (eg. 1/measurement error) and eta is level of spatial confidence.

  E_x is given as solution of the PDE

  > - -E_{x,ii} - i omega * mu * sigma * E_x = 0

  where E_x at top and bottom is set to solution for background field. Homogeneous Neuman conditions are assumed elsewhere.

  `__init__`(domain, omega, x, Z_XY, eta=None, w0=1.0, mu=1.2566370614359173e-06, sigma0=0.01, airLayerLevel=None, coordinates=None, Ex_top=1, fixAtTop=False, tol=1e-08, saveMemory=False, directSolver=True)

    initializes a new forward model. See base class for a description of the arguments.

  `getArguments`(sigma)

    Returns precomputed values shared by `getDefect()` and `getGradient()`.

    Parameters: | sigma (`Data` of shape (2,)) – conductivity
    Returns: | E_x, E_z
    Return type: | `Data` of shape (2,)

  `getCoordinateTransformation`()

    returns the coordinate transformation being used

    Return type: | `CoordinateTransformation`

  `getDefect`(sigma, Ex, dExdz)

    Returns the defect value.

    Parameters:

    - sigma (`Data` of shape ()) – a suggestion for conductivity
    - Ex (`Data` of shape (2,)) – electric field
    - dExdz (`Data` of shape (2,)) – vertical derivative of electric field

    Return type: | `float`

  `getDomain`()

    Returns the domain of the forward model.

    Return type: | `Domain`

  `getGradient`(sigma, Ex, dExdz)

    Returns the gradient of the defect with respect to density.

    Parameters:

    - sigma (`Data` of shape ()) – a suggestion for conductivity
    - Ex (`Data` of shape (2,)) – electric field
    - dExdz (`Data` of shape (2,)) – vertical derivative of electric field

  `getWeightingFactor`(x, wx0, x0, eta)

    returns the weighting factor

  `setUpPDE`()

    Return the underlying PDE.

    Return type: | `LinearPDE`

class `esys.downunder.``MT2DModelTMMode`(domain, omega, x, Z_YX, eta=None, w0=1.0, mu=1.2566370614359173e-06, sigma0=0.01, airLayerLevel=None, coordinates=None, tol=1e-08, saveMemory=False, directSolver=True)

  Bases: `esys.downunder.forwardmodels.magnetotelluric2d.MT2DBase`

  Forward Model for two-dimensional MT model in the TM mode for a given frequency omega. It defines a cost function:

  > - defect = 1/2 integrate( sum_s w^s * ( rho*H_x/Hy - Z_YX^s ) ) ** 2 *

  where H_x is the horizontal magnetic field perpendicular to the YZ-domain, horizontal magnetic field H_y=1/(i*omega*mu) * E_{x,z} with complex unit i and permeability mu. The weighting factor w^s is set to

  > - w^s(X) = w_0^s *

  if length(X-X^s) <= eta and zero otherwise. X^s is the location of impedance measurement Z_XY^s, w_0^s is the level of confidence (eg. 1/measurement error) and eta is level of spatial confidence.

  H_x is given as solution of the PDE

  > - -(rho*H_{x,i})_{,i} + i omega * mu * H_x = 0

  where H_x at top and bottom is set to solution for background field. Homogeneous Neuman conditions are assumed elsewhere.

  `__init__`(domain, omega, x, Z_YX, eta=None, w0=1.0, mu=1.2566370614359173e-06, sigma0=0.01, airLayerLevel=None, coordinates=None, tol=1e-08, saveMemory=False, directSolver=True)

    initializes a new forward model. See base class for a description of the arguments.

  `getArguments`(rho)

    Returns precomputed values shared by `getDefect()` and `getGradient()`.

    Parameters: | rho (`Data` of shape (2,)) – resistivity
    Returns: | Hx, grad(Hx)
    Return type: | `tuple` of `Data`

  `getCoordinateTransformation`()

    returns the coordinate transformation being used

    Return type: | `CoordinateTransformation`

  `getDefect`(rho, Hx, g_Hx)

    Returns the defect value.

    Parameters:

    - rho (`Data` of shape ()) – a suggestion for resistivity
    - Hx (`Data` of shape (2,)) – magnetic field
    - g_Hx (`Data` of shape (2,2)) – gradient of magnetic field

    Return type: | `float`

  `getDomain`()

    Returns the domain of the forward model.

    Return type: | `Domain`

  `getGradient`(rho, Hx, g_Hx)

    Returns the gradient of the defect with respect to resistivity.

    Parameters:

    - rho (`Data` of shape ()) – a suggestion for resistivity
    - Hx (`Data` of shape (2,)) – magnetic field
    - g_Hx (`Data` of shape (2,2)) – gradient of magnetic field

  `getWeightingFactor`(x, wx0, x0, eta)

    returns the weighting factor

  `setUpPDE`()

    Return the underlying PDE.

    Return type: | `LinearPDE`

class `esys.downunder.``MTMapping`(sigma_prior, a=1.0)

  Bases: `esys.downunder.mappings.Mapping`

  mt mapping

  sigma=sigma0*exp(a*m)

  `__init__`(sigma_prior, a=1.0)

    initializes the mapping

    Parameters: | sigma_prior – a a-priori conductivity

  `getDerivative`(m)

    returns the derivative of the mapping for m

  `getInverse`(s)

    returns the value of the inverse of the mapping for s

  `getTypicalDerivative`()

    returns a typical value for the derivative

  `getValue`(m)

    returns the value of the mapping for m

class `esys.downunder.``MagneticIntensityModel`(domain, w, b, background_magnetic_flux_density, coordinates=None, fixPotentialAtBottom=False, tol=1e-08)

  Bases: `esys.downunder.forwardmodels.base.ForwardModelWithPotential`

  Forward Model for magnetic intensity inversion as described in the inversion cookbook.

  `__init__`(domain, w, b, background_magnetic_flux_density, coordinates=None, fixPotentialAtBottom=False, tol=1e-08)

    Creates a new magnetic intensity model on the given domain with one or more surveys (w, b).

    Parameters:

    - domain (`Domain`) – domain of the model
    - w (`Scalar` or list of `Scalar`) – data weighting factors
    - b (`Scalar` or list of `Scalar`) – magnetic intensity field data
    - tol (positive `float`) – tolerance of underlying PDE
    - background_magnetic_flux_density (`Vector` or list of `float`) – background magnetic flux density (in Tesla) with components (B_east, B_north, B_vertical)
    - coordinates (None) – defines coordinate system to be used
    - fixPotentialAtBottom (`bool`) – if true potential is fixed to zero at the bottom of the domain in addition to the top

  `getArguments`(k)

    Returns precomputed values shared by `getDefect()` and `getGradient()`.

    Parameters: | k (`Scalar`) – susceptibility
    Returns: | scalar magnetic potential and corresponding magnetic field
    Return type: | `Scalar`, `Vector`

  `getCoordinateTransformation`()

    returns the coordinate transformation being used

    Return type: | `CoordinateTransformation`

  `getData`()

    Returns the data

    Return type: | `list` of `Data`

  `getDataFunctionSpace`()

    Returns the `FunctionSpace` of the data

    Return type: | `FunctionSpace`

  `getDefect`(k, phi, magnetic_flux_density)

    Returns the value of the defect.

    Parameters:

    - k (`Scalar`) – susceptibility
    - phi (`Scalar`) – corresponding potential
    - magnetic_flux_density (`Vector`) – magnetic field

    Return type: | `float`

  `getDefectGradient`(result)
  `getDomain`()

    Returns the domain of the forward model.

    Return type: | `Domain`

  `getGradient`(k, phi, magnetic_flux_density)

    Returns the gradient of the defect with respect to susceptibility.

    Parameters:

    - k (`Scalar`) – susceptibility
    - phi (`Scalar`) – corresponding potential
    - magnetic_flux_density (`Vector`) – magnetic field

    Return type: | `Scalar`

  `getMisfitWeights`()

    Returns the weights of the misfit function

    Return type: | `list` of `Data`

  `getPDE`()

    Return the underlying PDE.

    Return type: | `LinearPDE`

  `getPotential`(k)

    Calculates the magnetic potential for a given susceptibility.

    Parameters: | k (`Scalar`) – susceptibility
    Returns: | magnetic potential
    Return type: | `Scalar`

  `getSurvey`(index=None)

    Returns the pair (data_index, weight_index), where data_i is the data of survey i, weight_i is the weighting factor for survey i. If index is None, all surveys will be returned in a pair of lists.

  `rescaleWeights`(scale=1.0, k_scale=1.0)

    rescales the weights such that

    sum_s integrate( ( w_i[s] *B_i[s]) (w_j[s]*1/L_j) * L**2 * (background_magnetic_flux_density_j[s]*1/L_j) * k_scale )=scale

    Parameters:

    - scale (positive `float`) – scale of data weighting factors
    - k_scale (`Scalar`) – scale of susceptibility.

class `esys.downunder.``MagneticInversion`(solverclass=None, debug=False, self_demagnetization=False, magnetic_intensity_data=False)

  Bases: `esys.downunder.inversions.InversionDriver`

  Driver class to perform an inversion of magnetic anomaly data. The class uses the standard `Regularization` class for a single level set function, `SusceptibilityMapping` mapping and the linear magnetic forward model `MagneticModel`.

  `__init__`(solverclass=None, debug=False, self_demagnetization=False, magnetic_intensity_data=False)

    creates an instance of an inversion driver.

    Parameters:

    - solverclass ('AbstractMinimizer'.) – class of the solver to be used.
    - self_demagnetization – if True self-demagnitization is applied.
    - magnetic_intensity_data – if True magnetic intensity is used in the cost function.

  `fixGravityPotentialAtBottom`(status=False)

    indicates to fix the gravity potential at the bottom to zero (in addition to the top)

    Parameters: | status (`bool`) – if True gravity potential at the bottom is set to zero

  `fixMagneticPotentialAtBottom`(status=True)

    indicates to fix the magnetic potential at the bottom to zero (in addition to the top)

    Parameters: | status (`bool`) – if True magnetic potential at the bottom is set to zero

  `getCostFunction`()

    returns the cost function of the inversion.

    Return type: | ‘InversionCostFunction’

  `getDomain`()

    returns the domain of the inversion

    Return type: | `Domain`

  `getLevelSetFunction`()

    returns the level set function as solution of the optimization problem

    Return type: | `Data`

  `getSolver`()

    The solver to be used in the inversion process. See the minimizers module for available solvers. By default, the L-BFGS minimizer is used.

    Return type: | ‘AbstractMinimizer’.

  `isSetUp`()

    returns True if the inversion is set up and is ready to run.

    Return type: | `bool`

  `run`()

    Executes the inversion.

    Returns: | physical parameters as result of the inversion
    Return type: | `list` of physical parameters or a physical parameter

  `setCostFunction`(costfunction)

    sets the cost function of the inversion. This function needs to be called before the inversion iteration can be started.

    Parameters: | costfunction ('InversionCostFunction') – domain of the inversion

  `setInitialGuess`(k=None)

    set the initial guess k for susceptibility for the inversion iteration. If no k present then an appropriate initial guess is chosen.

    Parameters: | k (`Scalar`) – initial value for the susceptibility anomaly.

  `setSolverCallback`(callback=None)

    Sets the callback function which is called after every solver iteration.

  `setSolverMaxIterations`(maxiter=None)

    Sets the maximum number of solver iterations to run. If `maxiter` is reached the iteration is terminated and `MinimizerMaxIterReached` is thrown.

    Parameters: | maxiter (positive `int`) – maximum number of iteration steps.

  `setSolverTolerance`(m_tol=None, J_tol=None)

    Sets the error tolerance for the solver. An acceptable solution is considered to be found once the tolerance is reached.

    Parameters:

    - m_tol (`float` or `None`) – tolerance for changes to level set function. If `None` changes to the level set function are not checked for convergence during iteration.
    - J_tol (`float` or `None`) – tolerance for changes to cost function. If `None` changes to the cost function are not checked for convergence during iteration.

    Note: | if both arguments are `None` the default setting m_tol=1e-4, J_tol=None is used.

  `setup`(domainbuilder, k0=None, dk=None, z0=None, beta=None, w0=None, w1=None, k_at_depth=None)

    Sets up the inversion from a `DomainBuilder`. If magnetic data are given as scalar it is assumed that values are collected in direction of the background magnetic field.

    Parameters:

    - domainbuilder (`DomainBuilder`) – Domain builder object with gravity source(s)
    - k0 (`float` or `Scalar`) – reference susceptibility, see `SusceptibilityMapping`. If not specified, zero is used.
    - dk (`float` or `Scalar`) – susceptibility scale, see `SusceptibilityMapping`. If not specified, 1. is used.
    - z0 (`float` or `Scalar`) – reference depth for depth weighting, see `SusceptibilityMapping`. If not specified, zero is used.
    - beta (`float` or `Scalar`) – exponent for depth weighting, see `SusceptibilityMapping`. If not specified, zero is used.
    - w0 (`Scalar` or `float`) – weighting factor for level set term regularization. If not set zero is assumed.
    - w1 (`Vector` or list of `float`) – weighting factor for the gradient term in the regularization. If not set zero is assumed
    - k_at_depth (`float` or `None`) – value for susceptibility at depth, see `DomainBuilder`.

  `siloWriterCallback`(k, x, Jx, g_Jx, norm_dJ=None, norm_dx=None)

    callback function that can be used to track the solution

    Parameters:

    - k – iteration count
    - x – current approximation
    - Jx – value of cost function
    - g_Jx – gradient of f at x

class `esys.downunder.``MagneticModel`(domain, w, B, background_magnetic_flux_density, coordinates=None, fixPotentialAtBottom=False, tol=1e-08)

  Bases: `esys.downunder.forwardmodels.base.ForwardModelWithPotential`

  Forward Model for magnetic inversion as described in the inversion cookbook.

  `__init__`(domain, w, B, background_magnetic_flux_density, coordinates=None, fixPotentialAtBottom=False, tol=1e-08)

    Creates a new magnetic model on the given domain with one or more surveys (w, B).

    Parameters:

    - domain (`Domain`) – domain of the model
    - w (`Vector` or list of `Vector`) – data weighting factors
    - B (`Vector` or list of `Vector`) – magnetic field data
    - tol (positive `float`) – tolerance of underlying PDE
    - background_magnetic_flux_density (`Vector` or list of `float`) – background magnetic flux density (in Tesla) with components (B_east, B_north, B_vertical)
    - coordinates (`ReferenceSystem` or `SpatialCoordinateTransformation`) – defines coordinate system to be used
    - fixPotentialAtBottom (`bool`) – if true potential is fixed to zero at the bottom of the domain in addition to the top

  `getArguments`(k)

    Returns precomputed values shared by `getDefect()` and `getGradient()`.

    Parameters: | k (`Scalar`) – susceptibility
    Returns: | scalar magnetic potential and corresponding magnetic field
    Return type: | `Scalar`, `Vector`

  `getCoordinateTransformation`()

    returns the coordinate transformation being used

    Return type: | `CoordinateTransformation`

  `getData`()

    Returns the data

    Return type: | `list` of `Data`

  `getDataFunctionSpace`()

    Returns the `FunctionSpace` of the data

    Return type: | `FunctionSpace`

  `getDefect`(k, phi, magnetic_flux_density)

    Returns the value of the defect.

    Parameters:

    - k (`Scalar`) – susceptibility
    - phi (`Scalar`) – corresponding potential
    - magnetic_flux_density (`Vector`) – magnetic field

    Return type: | `float`

  `getDefectGradient`(result)
  `getDomain`()

    Returns the domain of the forward model.

    Return type: | `Domain`

  `getGradient`(k, phi, magnetic_flux_density)

    Returns the gradient of the defect with respect to susceptibility.

    Parameters:

    - k (`Scalar`) – susceptibility
    - phi (`Scalar`) – corresponding potential
    - magnetic_flux_density (`Vector`) – magnetic field

    Return type: | `Scalar`

  `getMisfitWeights`()

    Returns the weights of the misfit function

    Return type: | `list` of `Data`

  `getPDE`()

    Return the underlying PDE.

    Return type: | `LinearPDE`

  `getPotential`(k)

    Calculates the magnetic potential for a given susceptibility.

    Parameters: | k (`Scalar`) – susceptibility
    Returns: | magnetic potential
    Return type: | `Scalar`

  `getSurvey`(index=None)

    Returns the pair (data_index, weight_index), where data_i is the data of survey i, weight_i is the weighting factor for survey i. If index is None, all surveys will be returned in a pair of lists.

  `rescaleWeights`(scale=1.0, k_scale=1.0)

    rescales the weights such that

    sum_s integrate( ( w_i[s] *B_i[s]) (w_j[s]*1/L_j) * L**2 * (background_magnetic_flux_density_j[s]*1/L_j) * k_scale )=scale

    Parameters:

    - scale (positive `float`) – scale of data weighting factors
    - k_scale (`Scalar`) – scale of susceptibility.

class `esys.downunder.``Mapping`(*args)

  Bases: `object`

  An abstract mapping class to map level set functions m to physical parameters p.

  `__init__`(*args)

    Initialize self. See help(type(self)) for accurate signature.

  `getDerivative`(m)

    returns the value for the derivative of the mapping for m

  `getInverse`(s)

    returns the value of the inverse of the mapping for physical parameter p

  `getTypicalDerivative`()

    returns a typical value for the derivative

  `getValue`(m)

    returns the value of the mapping for m

class `esys.downunder.``MeteredCostFunction`

  Bases: `esys.downunder.costfunctions.CostFunction`

  This an intrumented version of the `CostFunction` class. The function calls update statistical information. The actual work is done by the methods with corresponding name and a leading underscore. These functions need to be overwritten for a particular cost function implementation.

  `__init__`()

    the base constructor initializes the counters so subclasses should ensure the super class constructor is called.

  `getArguments`(x)

    returns precalculated values that are shared in the calculation of f(x) and grad f(x) and the Hessian operator

    Note

    The tuple returned by this call will be passed back to this `CostFunction` in other calls(eg: `getGradient`). Its contents are not specified at this level because no code, other than the `CostFunction` which created it, will be interacting with it. That is, the implementor can put whatever information they find useful in it.

    Parameters: | x (x-type) – location of derivative
    Return type: | `tuple`

  `getDualProduct`(x, r)

    returns the dual product of `x` and `r`

    Return type: | `float`

  `getGradient`(x, *args)

    returns the gradient of f at x using the precalculated values for x.

    Parameters:

    - x (x-type) – location of derivative
    - args – pre-calculated values for `x` from `getArguments()`

    Return type: | r-type

  `getInverseHessianApproximation`(x, r, *args)

    returns an approximative evaluation p of the inverse of the Hessian operator of the cost function for a given gradient r at a given location x: H(x) p = r

    Note

    In general it is assumed that the Hessian H(x) needs to be calculate in each call for a new location x. However, the solver may suggest that this is not required, typically when the iteration is close to completeness.

    Parameters:

    - x (x-type) – location of Hessian operator to be evaluated.
    - r (r-type) – a given gradient
    - args – pre-calculated values for `x` from `getArguments()`

    Return type: | x-type

  `getNorm`(x)

    returns the norm of `x`

    Return type: | `float`

  `getValue`(x, *args)

    returns the value f(x) using the precalculated values for x.

    Parameters: | x (x-type) – a solution approximation
    Return type: | `float`

  `provides_inverse_Hessian_approximation` = False
  `resetCounters`()

    resets all statistical counters

  `updateHessian`()

    notifies the class that the Hessian operator needs to be updated. This method is called by the solver class.

class `esys.downunder.``MinimizerBFGS`(J=None, m_tol=0.0001, J_tol=None, imax=300)

  Bases: `esys.downunder.minimizers.AbstractMinimizer`

  Minimizer that uses the Broyden-Fletcher-Goldfarb-Shanno method.

  `__init__`(J=None, m_tol=0.0001, J_tol=None, imax=300)

    Initializes a new minimizer for a given cost function.

    Parameters:

    - J (`CostFunction`) – the cost function to be minimized
    - m_tol (float) – terminate interations when relative change of the level set function is less than or equal m_tol

  `getCostFunction`()

    return the cost function to be minimized

    Return type: | `CostFunction`

  `getOptions`()

    Returns a dictionary of minimizer-specific options.

  `getResult`()

    Returns the result of the minimization.

  `logSummary`()

    Outputs a summary of the completed minimization process to the logger.

  `run`(x)
    The callback function is called with the following arguments:
      k - iteration number x - current estimate Jx - value of cost function at x g_Jx - gradient of cost function at x gnorm - norm of g_Jx (stopping criterion)
  `setCallback`(callback)

    Sets a callback function to be called after every iteration. It is up to the specific implementation what arguments are passed to the callback. Subclasses should at least pass the current iteration number k, the current estimate x, and possibly f(x), grad f(x), and the current error.

  `setCostFunction`(J)

    set the cost function to be minimized

    Parameters: | J (`CostFunction`) – the cost function to be minimized

  `setMaxIterations`(imax)

    Sets the maximum number of iterations before the minimizer terminates.

  `setOptions`(**opts)

    setOptions for LBFGS. use solver.setOptions( key = value) :key initialHessian: 1 if initial Hessian is given :type initialHessian: 1 or 0 :default initialHessian: 1 :key interpolationOrder: order of the interpolation used for line search :type interpolationOrder: 1,2,3 or 4 :default interpolationOrder: 1 :key tol_df: interpolated value of alpha, alpha_i, must differ

    > : from the previous value by at least this much : abs(alpha_i-alpha_{i-1}) < tol_df (line search)

    Default tol_df: | 1e-6
    Key tol_sm: | interpolated value of alpha must not be less than tol_sm : abs(alpha_i) < tol_sm*abs(alpha_{i-1})

    Default tol_sm:

    1e-5
    Example of usage::

      cf=DerivedCostFunction() solver=MinimizerBFGS(J=cf, m_tol = 1e-5, J_tol = 1e-5, imax=300) solver.setOptions(tol_df =1e-7) solver.run(initial_m) result=solver.getResult()

  `setTolerance`(m_tol=0.0001, J_tol=None)

    Sets the tolerance for the stopping criterion. The minimizer stops when an appropriate norm is less than `m_tol`.

class `esys.downunder.``MinimizerException`

  Bases: `Exception`

  This is a generic exception thrown by a minimizer.

  `__init__`()

    Initialize self. See help(type(self)) for accurate signature.

  `args`
  `with_traceback`()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class `esys.downunder.``MinimizerIterationIncurableBreakDown`

  Bases: `esys.downunder.minimizers.MinimizerException`

  Exception thrown if the iteration scheme encountered an incurable breakdown.

  `__init__`()

    Initialize self. See help(type(self)) for accurate signature.

  `args`
  `with_traceback`()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class `esys.downunder.``MinimizerLBFGS`(J=None, m_tol=0.0001, J_tol=None, imax=300)

  Bases: `esys.downunder.minimizers.AbstractMinimizer`

  Minimizer that uses the limited-memory Broyden-Fletcher-Goldfarb-Shanno method. See Chapter 6 of ‘Numerical Optimization’ by J. Nocedal for an explanation.

  `__init__`(J=None, m_tol=0.0001, J_tol=None, imax=300)

    Initializes a new minimizer for a given cost function.

    Parameters:

    - J (`CostFunction`) – the cost function to be minimized
    - m_tol (float) – terminate interations when relative change of the level set function is less than or equal m_tol

  `getCostFunction`()

    return the cost function to be minimized

    Return type: | `CostFunction`

  `getOptions`()

    returns a dictionary of LBFGS options rtype: dictionary with keys ‘truncation’, ‘initialHessian’, ‘restart’, ‘max_linesearch_steps’, ‘max_zoom_steps’ ‘interpolationOrder’, ‘tol_df’, ‘tol_sm’

  `getResult`()

    Returns the result of the minimization.

  `logSummary`()

    Outputs a summary of the completed minimization process to the logger.

  `run`(x)
    The callback function is called with the following arguments:
      k - iteration number x - current estimate Jx - value of cost function at x g_Jx - gradient of cost function at x norm_dJ - ||Jx_k - Jx_{k-1}|| (only if J_tol is set) norm_dx - ||x_k - x_{k-1}|| (only if m_tol is set)

    Parameters: | x (`Data`) – Level set function representing our initial guess
    Returns: | Level set function representing the solution
    Return type: | `Data`

  `setCallback`(callback)

    Sets a callback function to be called after every iteration. It is up to the specific implementation what arguments are passed to the callback. Subclasses should at least pass the current iteration number k, the current estimate x, and possibly f(x), grad f(x), and the current error.

  `setCostFunction`(J)

    set the cost function to be minimized

    Parameters: | J (`CostFunction`) – the cost function to be minimized

  `setMaxIterations`(imax)

    Sets the maximum number of iterations before the minimizer terminates.

  `setOptions`(**opts)

    setOptions for LBFGS. use solver.setOptions( key = value) :key truncation: sets the number of previous LBFGS iterations to keep :type truncation : int :default truncation: 30 :key initialHessian: 1 if initial Hessian is given :type initialHessian: 1 or 0 :default initialHessian: 1 :key restart: restart after this many iteration steps :type restart: int :default restart: 60 :key max_linesearch_steps: maximum number of line search iterations :type max_linesearch_steps: int :default max_linesearch_steps: 25 :key max_zoom_steps: maximum number of zoom iterations :type max_zoom_steps: int :default max_zoom_steps: 60 :key interpolationOrder: order of the interpolation used for line search :type interpolationOrder: 1,2,3 or 4 :default interpolationOrder: 1 :key tol_df: interpolated value of alpha, alpha_i, must differ

    > : from the previous value by at least this much : abs(alpha_i-alpha_{i-1}) < tol_df (line search)

    Default tol_df: | 1e-6
    Key tol_sm: | interpolated value of alpha must not be less than tol_sm : abs(alpha_i) < tol_sm*abs(alpha_{i-1})

    Default tol_sm:

    1e-5
    Example of usage::

      cf=DerivedCostFunction() solver=MinimizerLBFGS(J=cf, m_tol = 1e-5, J_tol = 1e-5, imax=300) solver.setOptions(truncation=20, tol_df =1e-7) solver.run(initial_m) result=solver.getResult()

  `setTolerance`(m_tol=0.0001, J_tol=None)

    Sets the tolerance for the stopping criterion. The minimizer stops when an appropriate norm is less than `m_tol`.

class `esys.downunder.``MinimizerMaxIterReached`

  Bases: `esys.downunder.minimizers.MinimizerException`

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

  `__init__`()

    Initialize self. See help(type(self)) for accurate signature.

  `args`
  `with_traceback`()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class `esys.downunder.``MinimizerNLCG`(J=None, m_tol=0.0001, J_tol=None, imax=300)

  Bases: `esys.downunder.minimizers.AbstractMinimizer`

  Minimizer that uses the nonlinear conjugate gradient method (Fletcher-Reeves variant).

  `__init__`(J=None, m_tol=0.0001, J_tol=None, imax=300)

    Initializes a new minimizer for a given cost function.

    Parameters:

    - J (`CostFunction`) – the cost function to be minimized
    - m_tol (float) – terminate interations when relative change of the level set function is less than or equal m_tol

  `getCostFunction`()

    return the cost function to be minimized

    Return type: | `CostFunction`

  `getOptions`()

    Returns a dictionary of minimizer-specific options.

  `getResult`()

    Returns the result of the minimization.

  `logSummary`()

    Outputs a summary of the completed minimization process to the logger.

  `run`(x)
    The callback function is called with the following arguments:
      k - iteration number x - current estimate Jx - value of cost function at x g_Jx - gradient of cost function at x gnorm - norm of g_Jx (stopping criterion)
  `setCallback`(callback)

    Sets a callback function to be called after every iteration. It is up to the specific implementation what arguments are passed to the callback. Subclasses should at least pass the current iteration number k, the current estimate x, and possibly f(x), grad f(x), and the current error.

  `setCostFunction`(J)

    set the cost function to be minimized

    Parameters: | J (`CostFunction`) – the cost function to be minimized

  `setMaxIterations`(imax)

    Sets the maximum number of iterations before the minimizer terminates.

  `setOptions`(**opts)

    Sets minimizer-specific options. For a list of possible options see `getOptions()`.

  `setTolerance`(m_tol=0.0001, J_tol=None)

    Sets the tolerance for the stopping criterion. The minimizer stops when an appropriate norm is less than `m_tol`.

class `esys.downunder.``NetCdfData`(data_type, filename, altitude=0.0, data_variable=None, error=None, scale_factor=None, null_value=None, reference_system=None)

  Bases: `esys.downunder.datasources.DataSource`

  Data Source for gridded netCDF data that use CF/COARDS conventions.

  `__init__`(data_type, filename, altitude=0.0, data_variable=None, error=None, scale_factor=None, null_value=None, reference_system=None)

    Parameters:

    - filename (`str`) – file name for survey data in netCDF format
    - data_type (`int`) – type of data, must be `GRAVITY` or `MAGNETIC`
    - altitude (`float`) – altitude of measurements in meters
    - data_variable (`str`) – name of the netCDF variable that holds the data. If not provided an attempt is made to determine the variable and an exception thrown on failure.
    - error (`str` or `float`) – either the name of the netCDF variable that holds the uncertainties of the measurements or a constant value to use for the uncertainties. If a constant value is supplied, it is scaled by the same factor as the measurements. If not provided the error is assumed to be 2 units for all measurements (i.e. 0.2 mGal and 2 nT for gravity and magnetic, respectively)
    - scale_factor (`float`) – the measurements and error values are scaled by this factor. By default, gravity data is assumed to be given in 1e-6 m/s^2 (0.1 mGal), while magnetic data is assumed to be in 1e-9 T (1 nT).
    - null_value (`float`) – value that is used in the file to mark undefined areas. This information is usually included in the file.
    - reference_system (`ReferenceSystem`) – reference coordinate system to be used. For a Cartesian reference (default) the appropriate UTM transformation is applied.

    Note: | it is the responsibility of the caller to ensure all data sources and the domain builder use the same reference system.

  `ACOUSTIC` = 2
  `GRAVITY` = 0
  `MAGNETIC` = 1
  `MT` = 3
  `getDataExtents`()

    returns ( (x0, y0), (nx, ny), (dx, dy) )

  `getDataType`()

    Returns the type of survey data managed by this source. Subclasses must return `GRAVITY` or `MAGNETIC` or `ACOUSTIC` as appropriate.

  `getHeightScale`()

    returns the height scale factor to convert from meters to the appropriate units of the reference system used.

    Return type: | `float`

  `getReferenceSystem`()

    returns the reference coordinate system

    Return type: | `ReferenceSystem`

  `getScaleFactor`()

    returns the data scale factor for adjusting measurement to SI

  `getSubsamplingFactor`()

    Returns the subsampling factor that was set via `setSubsamplingFactor` (see there).

  `getSurveyData`(domain, origin, NE, spacing)

    This method is called by the `DomainBuilder` to retrieve the survey data as `Data` objects on the given domain.

    Subclasses should return one or more `Data` objects with survey data interpolated on the given `escript` domain. The exact return type depends on the type of data.

    Parameters:

    - domain (`esys.escript.Domain`) – the escript domain to use
    - origin (`tuple` or `list`) – the origin coordinates of the domain
    - NE (`tuple` or `list`) – the number of domain elements in each dimension
    - spacing (`tuple` or `list`) – the cell sizes (node spacing) in the domain

  `getTags`()

    returns the list of tags

    Return type: | `list`

  `getUtmZone`()

    All data source coordinates are converted to UTM (Universal Transverse Mercator) in order to have useful domain extents. Subclasses should implement this method and return the UTM zone number of the projected coordinates.

  `hasTag`(tag)

    returns true if the data set has tag `tag`

    Return type: | `bool`

  `setSubsamplingFactor`(f)

    Sets the data subsampling factor (default=1).

    The factor is applied in all dimensions. For example a 2D dataset with 300 x 150 data points will be reduced to 150 x 75 when a subsampling factor of 2 is used. This becomes important when adding data of varying resolution to a `DomainBuilder`.

class `esys.downunder.``NumpyData`(data_type, data, error=1.0, length=1000.0, null_value=-1.0, tags=[], origin=None)

  Bases: `esys.downunder.datasources.DataSource`

  `__init__`(data_type, data, error=1.0, length=1000.0, null_value=-1.0, tags=[], origin=None)

    A data source that uses survey data from a `numpy` object or list instead of a file. The dimensionality is inferred from the shape of `data` (1- and 2-dimensional data is supported). The data origin is assumed to be at the coordinate origin.

    Parameters:

    - data_type (`DataSource.GRAVITY`, `DataSource.MAGNETIC`) – data type indicator
    - data (`numpy.array` or `list`) – the survey data array. Note that for a cartesian coordinate system the shape of the data is considered to be (nz,ny,nx).
    - error (`float` or `list` or `ndarray`) – constant value to use for the data uncertainties or a numpy object with uncertainties for every data point.
    - length (`float` or `list` or `ndarray`) – side length(s) of the data slice/volume. This can be a scalar to indicate constant length in all dimensions or an array/list of values in each coordinate dimension.
    - null_value (`float`) – value that is used in the undefined regions of the survey data object.
    - tags (`list` of almost any type (typically `str`)) – a list of tags associated with the data set.
    - origin (`list` of `float`) – offset of origin of offset

  `ACOUSTIC` = 2
  `GRAVITY` = 0
  `MAGNETIC` = 1
  `MT` = 3
  `getDataExtents`()

    returns a tuple of tuples `( (x0, y0), (nx, ny), (dx, dy) )`, where

    - `x0`, `y0` = coordinates of data origin
    - `nx`, `ny` = number of data points in x and y
    - `dx`, `dy` = spacing of data points in x and y

    This method must be implemented in subclasses.

  `getDataType`()

    Returns the type of survey data managed by this source. Subclasses must return `GRAVITY` or `MAGNETIC` or `ACOUSTIC` as appropriate.

  `getHeightScale`()

    returns the height scale factor to convert from meters to the appropriate units of the reference system used.

    Return type: | `float`

  `getReferenceSystem`()

    returns the reference coordinate system

    Return type: | `ReferenceSystem`

  `getSubsamplingFactor`()

    Returns the subsampling factor that was set via `setSubsamplingFactor` (see there).

  `getSurveyData`(domain, origin, NE, spacing)

    This method is called by the `DomainBuilder` to retrieve the survey data as `Data` objects on the given domain.

    Subclasses should return one or more `Data` objects with survey data interpolated on the given `escript` domain. The exact return type depends on the type of data.

    Parameters:

    - domain (`esys.escript.Domain`) – the escript domain to use
    - origin (`tuple` or `list`) – the origin coordinates of the domain
    - NE (`tuple` or `list`) – the number of domain elements in each dimension
    - spacing (`tuple` or `list`) – the cell sizes (node spacing) in the domain

  `getTags`()

    returns the list of tags

    Return type: | `list`

  `getUtmZone`()

    returns a dummy UTM zone since this class does not use real coordinate values.

  `hasTag`(tag)

    returns true if the data set has tag `tag`

    Return type: | `bool`

  `setSubsamplingFactor`(f)

    Sets the data subsampling factor (default=1).

    The factor is applied in all dimensions. For example a 2D dataset with 300 x 150 data points will be reduced to 150 x 75 when a subsampling factor of 2 is used. This becomes important when adding data of varying resolution to a `DomainBuilder`.

class `esys.downunder.``PoleDipoleSurvey`(domain, primaryConductivity, secondaryConductivity, current, a, n, midPoint, directionVector, numElectrodes)

  Bases: `esys.downunder.dcresistivityforwardmodeling.DcResistivityForward`

  Forward model class for a poledipole setup

  `__init__`(domain, primaryConductivity, secondaryConductivity, current, a, n, midPoint, directionVector, numElectrodes)

    Parameters:

    - domain (`Domain`) – domain of the model
    - primaryConductivity (data) – preset primary conductivity data object
    - secondaryConductivity (data) – preset secondary conductivity data object
    - current (float or int) – amount of current to be injected at the current electrode
    - a (list) – the spacing between current and potential electrodes
    - n (float or int) – multiple of spacing between electrodes. typicaly interger
    - midPoint – midPoint of the survey, as a list containing x,y coords
    - directionVector – two element list specifying the direction the survey should extend from the midpoint
    - numElectrodes (int) – the number of electrodes to be used in the survey must be a multiple of 2 for polepole survey:

  `checkBounds`()
  `getApparentResistivity`()
  `getApparentResistivityPrimary`()
  `getApparentResistivitySecondary`()
  `getApparentResistivityTotal`()
  `getElectrodes`()

    retuns the list of electrodes with locations

  `getPotential`()

    Returns 3 list each made up of a number of list containing primary, secondary and total potentials diferences. Each of the lists contain a list for each value of n.

class `esys.downunder.``PolePoleSurvey`(domain, primaryConductivity, secondaryConductivity, current, a, midPoint, directionVector, numElectrodes)

  Bases: `esys.downunder.dcresistivityforwardmodeling.DcResistivityForward`

  Forward model class for a polepole setup

  `__init__`(domain, primaryConductivity, secondaryConductivity, current, a, midPoint, directionVector, numElectrodes)

    Parameters:

    - domain (`Domain`) – domain of the model
    - primaryConductivity (data) – preset primary conductivity data object
    - secondaryConductivity (data) – preset secondary conductivity data object
    - current (float or int) – amount of current to be injected at the current electrode
    - a (list) – the spacing between current and potential electrodes
    - midPoint – midPoint of the survey, as a list containing x,y coords
    - directionVector – two element list specifying the direction the survey should extend from the midpoint
    - numElectrodes (int) – the number of electrodes to be used in the survey must be a multiple of 2 for polepole survey:

  `checkBounds`()
  `getApparentResistivity`()
  `getApparentResistivityPrimary`()
  `getApparentResistivitySecondary`()
  `getApparentResistivityTotal`()
  `getElectrodes`()

    retuns the list of electrodes with locations

  `getPotential`()

    returns a list containing 3 lists one for each the primary, secondary and total potential.

class `esys.downunder.``ReferenceSystem`(name='none')

  Bases: `object`

  Generic identifier for coordinate systems.

  `__init__`(name='none')

    initialization of reference system

    Parameters: | name (`str`) – name of the reference system

  `createTransformation`(domain)

    creates an appropriate coordinate transformation on a given domain

    Note

    needs to be overwritten by a particular reference system

    Parameters: | domain (`esys.escript.AbstractDomain`) – domain of transformation
    Return type: | `SpatialCoordinateTransformation`

  `getName`()

    returns the name of the reference system

  `isCartesian`()

    returns if the reference system is Cartesian

    Note

    needs to be overwritten by a particular reference system

    Return type: | `bool`

  `isTheSame`(other)

    test if argument `other` defines the same reference system

    Parameters: | other (`ReferenceSystem`) – a second reference system
    Returns: | `True` if other defines the same reference system
    Return type: | `bool`

    Note

    needs to be overwritten by a particular reference system

class `esys.downunder.``Regularization`(domain, numLevelSets=1, w0=None, w1=None, wc=None, location_of_set_m=<esys.escriptcore.escriptcpp.Data object>, useDiagonalHessianApproximation=False, tol=1e-08, coordinates=None, scale=None, scale_c=None)

  Bases: `esys.downunder.costfunctions.CostFunction`

  The regularization term for the level set function `m` within the cost function J for an inversion:

  J(m)=1/2 * sum_k integrate( mu[k] * ( w0[k] * m_k**2 * w1[k,i] * m_{k,i}**2) + sum_l<k mu_c[l,k] wc[l,k] * | curl(m_k) x curl(m_l) |^2

  where w0[k], w1[k,i] and wc[k,l] are non-negative weighting factors and mu[k] and mu_c[l,k] are trade-off factors which may be altered during the inversion. The weighting factors are normalized such that their integrals over the domain are constant:

  integrate(w0[k] + inner(w1[k,:],1/L[:]**2))=scale[k] volume(domain)* integrate(wc[l,k]*1/L**4)=scale_c[k] volume(domain) *

  `__init__`(domain, numLevelSets=1, w0=None, w1=None, wc=None, location_of_set_m=<esys.escriptcore.escriptcpp.Data object>, useDiagonalHessianApproximation=False, tol=1e-08, coordinates=None, scale=None, scale_c=None)

    initialization.

    Parameters:

    - domain (`Domain`) – domain
    - numLevelSets (`int`) – number of level sets
    - w0 (`Scalar` if `numLevelSets` == 1 or `Data` object of shape (`numLevelSets` ,) if `numLevelSets` > 1) – weighting factor for the m**2 term. If not set zero is assumed.
    - w1 (`Vector` if `numLevelSets` == 1 or `Data` object of shape (`numLevelSets` , DIM) if `numLevelSets` > 1) – weighting factor for the grad(m_i) terms. If not set zero is assumed
    - wc (`Data` object of shape (`numLevelSets` , `numLevelSets`)) – weighting factor for the cross gradient terms. If not set zero is assumed. Used for the case if `numLevelSets` > 1 only. Only values `wc[l,k]` in the lower triangle (l<k) are used.
    - location_of_set_m (`Scalar` if `numLevelSets` == 1 or `Data` object of shape (`numLevelSets` ,) if `numLevelSets` > 1) – marks location of zero values of the level set function `m` by a positive entry.
    - useDiagonalHessianApproximation (`bool`) – if True cross gradient terms between level set components are ignored when calculating approximations of the inverse of the Hessian Operator. This can speed-up the calculation of the inverse but may lead to an increase of the number of iteration steps in the inversion.
    - tol (positive `float`) – tolerance when solving the PDE for the inverse of the Hessian Operator
    - coordinates (ReferenceSystem` or `SpatialCoordinateTransformation`) – defines coordinate system to be used
    - scale (`Scalar` if `numLevelSets` == 1 or `Data` object of shape (`numLevelSets` ,) if `numLevelSets` > 1) – weighting factor for level set function variation terms. If not set one is used.
    - scale_c (`Data` object of shape (`numLevelSets`,``numLevelSets``)) – scale for the cross gradient terms. If not set one is assumed. Used for the case if `numLevelSets` > 1 only. Only values `scale_c[l,k]` in the lower triangle (l<k) are used.

  `getArguments`(m)
  `getCoordinateTransformation`()

    returns the coordinate transformation being used

    Return type: | `CoordinateTransformation`

  `getDomain`()

    returns the domain of the regularization term

    Return type: | `Domain`

  `getDualProduct`(m, r)

    returns the dual product of a gradient represented by X=r[1] and Y=r[0] with a level set function m:

    > Y_i*m_i + X_ij*m_{i,j}

    Return type: | `float`

  `getGradient`(m, grad_m)

    returns the gradient of the cost function J with respect to m.

    Note: | This implementation returns Y_k=dPsi/dm_k and X_kj=dPsi/dm_kj

  `getInverseHessianApproximation`(m, r, grad_m, solve=True)
  `getNorm`(m)

    returns the norm of `m`.

    Parameters: | m (`Data`) – level set function
    Return type: | `float`

  `getNumLevelSets`()

    returns the number of level set functions

    Return type: | `int`

  `getNumTradeOffFactors`()

    returns the number of trade-off factors being used.

    Return type: | `int`

  `getPDE`()

    returns the linear PDE to be solved for the Hessian Operator inverse

    Return type: | `LinearPDE`

  `getValue`(m, grad_m)

    returns the value of the cost function J with respect to m. This equation is specified in the inversion cookbook.

    Return type: | `float`

  `provides_inverse_Hessian_approximation` = False
  `setTradeOffFactors`(mu=None)

    sets the trade-off factors for the level-set variation and the cross-gradient.

    Parameters: | mu (`list` of `float` or ``numpy.array``) – new values for the trade-off factors where values mu[:numLevelSets] are the trade-off factors for the level-set variation and the remaining values for the cross-gradient part with mu_c[l,k]=mu[numLevelSets+l+((k-1)*k)/2] (l<k). If no values for mu are given ones are used. Values must be positive.

  `setTradeOffFactorsForCrossGradient`(mu_c=None)

    sets the trade-off factors for the cross-gradient terms.

    Parameters: | mu_c (`float`, `list` of `float` or `numpy.array`) – new values for the trade-off factors for the cross-gradient terms. Values must be positive. If no value is given ones are used. Only value mu_c[l,k] for l<k are used.

  `setTradeOffFactorsForVariation`(mu=None)

    sets the trade-off factors for the level-set variation part.

    Parameters: | mu (`float`, `list` of `float` or ``numpy.array``) – new values for the trade-off factors. Values must be positive.

  `updateHessian`()

    notifies the class to recalculate the Hessian operator.

class `esys.downunder.``Ricker`(f_dom=40, t_dom=None)

  Bases: `esys.downunder.seismic.Wavelet`

  The Ricker Wavelet w=f(t)

  `__init__`(f_dom=40, t_dom=None)

    Sets up a Ricker wavelet wih dominant frequence `f_dom` and center at time `t_dom`. If `t_dom` is not given an estimate for suitable `t_dom` is calculated so f(0)~0.

    Note: | maximum frequence is about 2 x the dominant frequence.

  `getAcceleration`(t)

    get the acceleration f’’(t) at time `t`

  `getCenter`()

    Return value of wavelet center

  `getTimeScale`()

    Returns the time scale which is the inverse of the largest frequence with a significant spectral component.

  `getValue`(t)

    get value of wavelet at time `t`

  `getVelocity`(t)

    get the velocity f’(t) at time `t`

class `esys.downunder.``SchlumbergerSurvey`(domain, primaryConductivity, secondaryConductivity, current, a, n, midPoint, directionVector, numElectrodes)

  Bases: `esys.downunder.dcresistivityforwardmodeling.DcResistivityForward`

  Schlumberger survey forward calculation

  `__init__`(domain, primaryConductivity, secondaryConductivity, current, a, n, midPoint, directionVector, numElectrodes)

    This is a skeleton class for all the other forward modeling classes.

  `checkBounds`()
  `getApparentResistivity`(delPhiList)
  `getElectrodeDict`()

    retuns the electrode dictionary

  `getElectrodes`()

    retuns the list of electrodes with locations

  `getPotential`()
  `getPotentialAnalytic`()

    Returns 3 list each made up of a number of list containing primary, secondary and total potentials diferences. Each of the lists contain a list for each value of n.

  `getPotentialNumeric`()

    Returns 3 list each made up of a number of list containing primary, secondary and total potentials diferences. Each of the lists contain a list for each value of n.

  `getSourcesSamples`()

    return a list of tuples of sample locations followed by a list of tuples of source locations.

class `esys.downunder.``SeismicSource`(x, y=0.0, omega=0.0, elevation=0.0, power=None, orientation=None)

  Bases: `object`

  describes a seimic source by location (x,y), frequency omega, power (if known) and orientation (if known). this class is used to tag seismic data sources.

  `__init__`(x, y=0.0, omega=0.0, elevation=0.0, power=None, orientation=None)

    initiale the source

    Parameters:

    - x (`float`) – lateral x location
    - y (`float`) – lateral y location
    - omega (`float`) – frequency of source
    - elevation – elevation of source above reference level
    - power (`complex` or `None`) – power of source at frequence
    - orientation (vector of appropriate length or `None`) – oriententation of source in 3D or 2D (or None)

  `getElevation`()

    return elevation of source :rtype: `float`

  `getFrequency`()

    return frequency of source :rtype: `float`

  `getLocation`()

    return location of source :rtype: `tuple` of `float`

  `getOrientation`()

    return power of source orientation at frequency :rtype: vector type object or `None`

  `getPower`()

    return power of source at frequency :rtype: `complex` or `None`

class `esys.downunder.``SelfDemagnetizationModel`(domain, w, B, background_magnetic_flux_density, coordinates=None, fixPotentialAtBottom=False, tol=1e-08)

  Bases: `esys.downunder.forwardmodels.base.ForwardModelWithPotential`

  Forward Model for magnetic inversion with self-demagnetization as described in the inversion cookbook.

  `__init__`(domain, w, B, background_magnetic_flux_density, coordinates=None, fixPotentialAtBottom=False, tol=1e-08)

    Creates a new magnetic model on the given domain with one or more surveys (w, B).

    Parameters:

    - domain (`Domain`) – domain of the model
    - w (`Vector` or list of `Vector`) – data weighting factors
    - B (`Vector` or list of `Vector`) – magnetic field data
    - background_magnetic_flux_density (`Vector` or list of `float`) – background magnetic flux density (in Tesla) with components (B_east, B_north, B_vertical)
    - coordinates (`ReferenceSystem` or `SpatialCoordinateTransformation`) – defines coordinate system to be used
    - fixPotentialAtBottom (`bool`) – if true potential is fixed to zero at the bottom of the domain in addition to the top
    - tol (positive `float`) – tolerance of underlying PDE

  `getArguments`(k)

    Returns precomputed values shared by `getDefect()` and `getGradient()`.

    Parameters: | k (`Scalar`) – susceptibility
    Returns: | scalar magnetic potential and corresponding magnetic field
    Return type: | `Scalar`, `Vector`

  `getCoordinateTransformation`()

    returns the coordinate transformation being used

    Return type: | `CoordinateTransformation`

  `getData`()

    Returns the data

    Return type: | `list` of `Data`

  `getDataFunctionSpace`()

    Returns the `FunctionSpace` of the data

    Return type: | `FunctionSpace`

  `getDefect`(k, phi, grad_phi, magnetic_flux_density)

    Returns the value of the defect.

    Parameters:

    - k (`Scalar`) – susceptibility
    - phi (`Scalar`) – corresponding potential
    - magnetic_flux_density (`Vector`) – magnetic field

    Return type: | `float`

  `getDefectGradient`(result)
  `getDomain`()

    Returns the domain of the forward model.

    Return type: | `Domain`

  `getGradient`(k, phi, grad_phi, magnetic_flux_density)

    Returns the gradient of the defect with respect to susceptibility.

    Parameters:

    - k (`Scalar`) – susceptibility
    - phi (`Scalar`) – corresponding potential
    - magnetic_flux_density (`Vector`) – magnetic field

    Return type: | `Scalar`

  `getMisfitWeights`()

    Returns the weights of the misfit function

    Return type: | `list` of `Data`

  `getPDE`()

    Return the underlying PDE.

    Return type: | `LinearPDE`

  `getPotential`(k)

    Calculates the magnetic potential for a given susceptibility.

    Parameters: | k (`Scalar`) – susceptibility
    Returns: | magnetic potential
    Return type: | `Scalar`

  `getSurvey`(index=None)

    Returns the pair (data_index, weight_index), where data_i is the data of survey i, weight_i is the weighting factor for survey i. If index is None, all surveys will be returned in a pair of lists.

  `rescaleWeights`(scale=1.0, k_scale=1.0)

    rescales the weights such that

    sum_s integrate( ( w_i[s] *B_i[s]) (w_j[s]*1/L_j) * L**2 * (background_magnetic_flux_density_j[s]*1/L_j) * k_scale )=scale

    Parameters:

    - scale (positive `float`) – scale of data weighting factors
    - k_scale (`Scalar`) – scale of susceptibility.

class `esys.downunder.``SimpleSEGYWriter`(receiver_group=None, source=0.0, sampling_interval=0.004, text='some seimic data')

  Bases: `object`

  A simple writer for 2D and 3D seismic lines, in particular for synthetic data

  Typical usage:

      from esys.escript import unitsSI as U
      sw=SimpleSEGYWriter([0.,100*U.m,200*U,m,300.], source=200*U.m, sampling_interval=4*U.msec)
      while n < 10:
          sw.addRecord([i*2., i*0.67, i**2, -i*7])
      sw.write('example.segy')

  Note: | the writer uses `obspy`

  `__init__`(receiver_group=None, source=0.0, sampling_interval=0.004, text='some seimic data')

    initalize writer

    Parameters:

    - receiver_group – list of receiver coordinates (in meters). For the 2D case a list of floats is given, for the 3D case a list of coordinate tuples are given
    - source – coordinates of the source (in meters). For the 2D case a single floats is given, for the 3D case a coordinate tuples
    - sampling_interval – sample rate in seconds
    - text – a text for the header file (e.g a description)

  `COORDINATE_SCALE` = 1000.0
  `addRecord`(record)

    Adds a record to the traces. A time difference of sample_interval between two records is assumed. The record mast be a list of as many values as given receivers or a float if a single receiver is used.

    Parameters: | record – list of tracks to be added to the record.

  `getSamplingInterval`()

    returns the sampling interval in seconds.

  `obspy_available`()

    for checking if the obspy module is available

  `write`(filename)

    writes to segy file

    Parameters: | filename – file name
    Note: | the function uses the `obspy` module.

class `esys.downunder.``SmoothAnomaly`(lx, ly, lz, x, y, depth, v_inner=None, v_outer=None)

  Bases: `esys.downunder.datasources.SourceFeature`

  A source feature in the form of a blob (roughly gaussian).

  `__init__`(lx, ly, lz, x, y, depth, v_inner=None, v_outer=None)

    Intializes the smooth anomaly data.

    Parameters:

    - lx – size of blob in x-dimension
    - ly – size of blob in y-dimension
    - lz – size of blob in z-dimension
    - x – location of blob in x-dimension
    - y – location of blob in y-dimension
    - depth – depth of blob
    - v_inner – value in the centre of the blob
    - v_outer – value in the periphery of the blob

  `getMask`(x)

    Returns the mask of the area of interest for this feature. That is, mask is non-zero where the value returned by `getValue()` should be applied, zero elsewhere.

  `getValue`(x)

    Returns the value for the area covered by mask. It can be constant or a `Data` object with spatial dependency.

class `esys.downunder.``SonicHTIWave`(domain, v_p, wavelet, source_tag, source_vector=[1.0, 0.0], eps=0.0, delta=0.0, azimuth=0.0, dt=None, p0=None, v0=None, absorption_zone=300.0, absorption_cut=0.01, lumping=True)

  Bases: `esys.downunder.seismic.WaveBase`

  Solving the HTI wave equation (along the x_0 axis) with azimuth (rotation around verticle axis) under the assumption of zero shear wave velocities The unknowns are the transversal (along x_0) and vertial stress (Q, P)

  Note: | In case of a two dimensional domain the second spatial dimenion is depth.

  `__init__`(domain, v_p, wavelet, source_tag, source_vector=[1.0, 0.0], eps=0.0, delta=0.0, azimuth=0.0, dt=None, p0=None, v0=None, absorption_zone=300.0, absorption_cut=0.01, lumping=True)

    initialize the HTI wave solver

    Parameters:

    - domain (`Doamin`) – domain of the problem
    - v_p (`escript.Scalar`) – vertical p-velocity field
    - v_s (`escript.Scalar`) – vertical s-velocity field
    - wavelet (`Wavelet`) – wavelet to describe the time evolution of source term
    - source_tag ('str' or 'int') – tag of the source location
    - source_vector – source orientation vector
    - eps – first Thompsen parameter
    - azimuth – azimuth (rotation around verticle axis)
    - gamma – third Thompsen parameter
    - rho – density
    - dt – time step size. If not present a suitable time step size is calculated.
    - p0 – initial solution (Q(t=0), P(t=0)). If not present zero is used.
    - v0 – initial solution change rate. If not present zero is used.
    - absorption_zone – thickness of absorption zone
    - absorption_cut – boundary value of absorption decay factor
    - lumping – if True mass matrix lumping is being used. This is accelerates the computing but introduces some diffusion.

  `getTimeStepSize`()
  `update`(t)

    returns the solution for the next time marker t which needs to greater than the time marker from the previous call.

class `esys.downunder.``SonicWave`(domain, v_p, wavelet, source_tag, dt=None, p0=None, p0_t=None, absorption_zone=300.0, absorption_cut=0.01, lumping=True)

  Bases: `esys.downunder.seismic.WaveBase`

  Solving the sonic wave equation

  `p_tt = (v_p**2 * p_i)_i + f(t) * delta_s` where (p-) velocity v_p.

  f(t) is wavelet acting at a point source term at positon s

  `__init__`(domain, v_p, wavelet, source_tag, dt=None, p0=None, p0_t=None, absorption_zone=300.0, absorption_cut=0.01, lumping=True)

    initialize the sonic wave solver

    Parameters:

    - domain (`Domain`) – domain of the problem
    - v_p (`escript.Scalar`) – p-velocity field
    - wavelet (`Wavelet`) – wavelet to describe the time evolution of source term
    - source_tag ('str' or 'int') – tag of the source location
    - dt – time step size. If not present a suitable time step size is calculated.
    - p0 – initial solution. If not present zero is used.
    - p0_t – initial solution change rate. If not present zero is used.
    - absorption_zone – thickness of absorption zone
    - absorption_cut – boundary value of absorption decay factor
    - lumping – if True mass matrix lumping is being used. This is accelerates the computing but introduces some diffusion.

  `getTimeStepSize`()
  `update`(t)

    returns the solution for the next time marker t which needs to greater than the time marker from the previous call.

class `esys.downunder.``SpatialCoordinateTransformation`(domain, reference=<esys.downunder.coordinates.CartesianReferenceSystem object>)

  Bases: `object`

  Defines an orthogonal coordinate transformation from a domain into the Cartesian domain using a coordinate transformation.

  The default implementation is the identity transformation (i.e. no changes are applied to the domain). Overwrite the appropriate methods to define other coordinate systems.

  `__init__`(domain, reference=<esys.downunder.coordinates.CartesianReferenceSystem object>)

    set up the orthogonal coordinate transformation.

    Parameters:

    - domain (`esys.escript.AbstractDomain`) – domain in the domain of the coordinate transformation
    - reference (`ReferenceSystem`) – the reference system

  `getDomain`()

    returns the domain of the coordinate transformation.

    Return type: | `esys.escript.AbstractDomain`

  `getGradient`(u)

    returns the gradient of a scalar function in direction of the coordinate axis.

    Return type: | `esys.escript.Vector`

  `getReferenceSystem`()

    returns the reference system used to to define the coordinate transformation

    Return type: | `ReferenceSystem`

  `getScalingFactors`()

    returns the scaling factors

    Return type: | `esys.escript.Vector`

  `getVolumeFactor`()

    returns the volume factor for the coordinate transformation

    Return type: | `esys.escript.Scalar`

  `isCartesian`()

    returns `True` if the scaling factors (and the volume factor) are equal to 1

    Return type: | `bool`

  `isTheSame`(other)

    test if argument `other` defines the same coordinate transformation

    Parameters: | other (`SpatialCoordinateTransformation`) – a second coordinate transformation
    Returns: | `True` if other defines then same coordinate transformation
    Return type: | `bool`

class `esys.downunder.``SplitInversionCostFunction`(numLevelSets=None, numModels=None, numMappings=None, splitworld=None, worldsinit_fn=None)

  Bases: `esys.downunder.costfunctions.MeteredCostFunction`

  Class to define cost function J(m) for inversion with one or more forward models based on a multi-valued level set function m:

  J(m) = J_reg(m) + sum_f mu_f * J_f(p)

  where J_reg(m) is the regularization and cross gradient component of the cost function applied to a level set function m, J_f(p) are the data defect cost functions involving a physical forward model using the physical parameter(s) p and mu_f is the trade-off factor for model f.

  A forward model depends on a set of physical parameters p which are constructed from components of the level set function m via mappings.

  Example 1 (single forward model):
    m=Mapping() f=ForwardModel() J=InversionCostFunction(Regularization(), m, f)
  Example 2 (two forward models on a single valued level set)

    m0=Mapping() m1=Mapping() f0=ForwardModel() f1=ForwardModel()

    J=InversionCostFunction(Regularization(), mappings=[m0, m1], forward_models=[(f0, 0), (f1,1)])

  Example 3 (two forward models on 2-valued level set)

    m0=Mapping() m1=Mapping() f0=ForwardModel() f1=ForwardModel()

    J=InversionCostFunction(Regularization(self.numLevelSets=2), mappings=[(m0,0), (m1,0)], forward_models=[(f0, 0), (f1,1)])

  Note: | If provides_inverse_Hessian_approximation is true, then the class provides an approximative inverse of the Hessian operator.

  `__init__`(numLevelSets=None, numModels=None, numMappings=None, splitworld=None, worldsinit_fn=None)

    fill this in.

  `calculateGradient`(vnames1, vnames2)

    The gradient operation produces two components (designated (Y^,X) in the non-split version). vnames1 gives the variable name(s) where the first component should be stored. vnames2 gives the variable name(s) where the second component should be stored.

  static `calculatePropertiesHelper`(self, m, mappings)

    returns a list of the physical properties from a given level set function m using the mappings of the cost function.

    Parameters: | m (`Data`) – level set function
    Return type: | `list` of `Data`

  `calculateValue`(vname)
  `createLevelSetFunction`(*props)

    returns an instance of an object used to represent a level set function initialized with zeros. Components can be overwritten by physical properties `props`. If present entries must correspond to the `mappings` arguments in the constructor. Use `None` for properties for which no value is given.

  static `createLevelSetFunctionHelper`(self, regularization, mappings, *props)

    Returns an object (init-ed) with 0s. Components can be overwritten by physical properties `props`. If present entries must correspond to the `mappings` arguments in the constructor. Use `None` for properties for which no value is given.

  static `formatMappings`(mappings, numLevelSets)
  static `formatModels`(forward_models, numMappings)
  `getArguments`(x)

    returns precalculated values that are shared in the calculation of f(x) and grad f(x) and the Hessian operator

    Note

    The tuple returned by this call will be passed back to this `CostFunction` in other calls(eg: `getGradient`). Its contents are not specified at this level because no code, other than the `CostFunction` which created it, will be interacting with it. That is, the implementor can put whatever information they find useful in it.

    Parameters: | x (x-type) – location of derivative
    Return type: | `tuple`

  `getComponentValues`(m, *args)
  `getDomain`()

    returns the domain of the cost function

    Return type: | `Domain`

  `getDualProduct`(x, r)

    returns the dual product of `x` and `r`

    Return type: | `float`

  `getForwardModel`(idx=None)

    returns the idx-th forward model.

    Parameters: | idx (`int`) – model index. If cost function contains one model only `idx` can be omitted.

  `getGradient`(x, *args)

    returns the gradient of f at x using the precalculated values for x.

    Parameters:

    - x (x-type) – location of derivative
    - args – pre-calculated values for `x` from `getArguments()`

    Return type: | r-type

  `getInverseHessianApproximation`(x, r, *args)

    returns an approximative evaluation p of the inverse of the Hessian operator of the cost function for a given gradient r at a given location x: H(x) p = r

    Note

    In general it is assumed that the Hessian H(x) needs to be calculate in each call for a new location x. However, the solver may suggest that this is not required, typically when the iteration is close to completeness.

    Parameters:

    - x (x-type) – location of Hessian operator to be evaluated.
    - r (r-type) – a given gradient
    - args – pre-calculated values for `x` from `getArguments()`

    Return type: | x-type

  static `getModelArgs`(self, fwdmodels)

    Attempts to import the arguments for forward models, if they are not available, Computes and exports them

  `getNorm`(x)

    returns the norm of `x`

    Return type: | `float`

  `getNumTradeOffFactors`()

    returns the number of trade-off factors being used including the trade-off factors used in the regularization component.

    Return type: | `int`

  `getProperties`(m, return_list=False)

    returns a list of the physical properties from a given level set function m using the mappings of the cost function.

    Parameters:

    - m (`Data`) – level set function
    - return_list (`bool`) – if `True` a list is returned.

    Return type: | `list` of `Data`

  `getRegularization`()

    returns the regularization

    Return type: | `Regularization`

  `getTradeOffFactors`(mu=None)

    returns a list of the trade-off factors.

    Return type: | `list` of `float`

  `getTradeOffFactorsModels`()

    returns the trade-off factors for the forward models

    Return type: | `float` or `list` of `float`

  `getValue`(x, *args)

    returns the value f(x) using the precalculated values for x.

    Parameters: | x (x-type) – a solution approximation
    Return type: | `float`

  `provides_inverse_Hessian_approximation` = True
  `resetCounters`()

    resets all statistical counters

  `setPoint`()
  `setTradeOffFactors`(mu=None)

    sets the trade-off factors for the forward model and regularization terms.

    Parameters: | mu (`list` of `float`) – list of trade-off factors.

  `setTradeOffFactorsModels`(mu=None)

    sets the trade-off factors for the forward model components.

    Parameters: | mu (`float` in case of a single model or a `list` of `float` with the length of the number of models.) – list of the trade-off factors. If not present ones are used.

  `setTradeOffFactorsRegularization`(mu=None, mu_c=None)

    sets the trade-off factors for the regularization component of the cost function, see `Regularization` for details.

    Parameters:

    - mu – trade-off factors for the level-set variation part
    - mu_c – trade-off factors for the cross gradient variation part

  static `subworld_setMu_model`(self, **args)
  `updateHessian`()

    notifies the class that the Hessian operator needs to be updated.

  static `update_point_helper`(self, newpoint)

    Call within a subworld to set ‘current_point’ to newpoint and update all the cached args info

class `esys.downunder.``SplitMinimizerLBFGS`(J=None, m_tol=0.0001, J_tol=None, imax=300)

  Bases: `esys.downunder.minimizers.AbstractMinimizer`

  Minimizer that uses the limited-memory Broyden-Fletcher-Goldfarb-Shanno method.

  version modified to fit with split world.

  `__init__`(J=None, m_tol=0.0001, J_tol=None, imax=300)

    Initializes a new minimizer for a given cost function.

    Parameters:

    - J (`CostFunction`) – the cost function to be minimized
    - m_tol (float) – terminate interations when relative change of the level set function is less than or equal m_tol

  `getCostFunction`()

    return the cost function to be minimized

    Return type: | `CostFunction`

  `getOptions`()

    Returns a dictionary of minimizer-specific options.

  `getResult`()

    Returns the result of the minimization.

  `logSummary`()

    Outputs a summary of the completed minimization process to the logger.

  static `move_point_from_base`(self, **kwargs)
  `run`()

    This version relies on the costfunction already having an initial guess loaded. It also does not return the result, meaning a job needs to be submitted to get the result out.

  `setCallback`(callback)

    Sets a callback function to be called after every iteration. It is up to the specific implementation what arguments are passed to the callback. Subclasses should at least pass the current iteration number k, the current estimate x, and possibly f(x), grad f(x), and the current error.

  `setCostFunction`(J)

    set the cost function to be minimized

    Parameters: | J (`CostFunction`) – the cost function to be minimized

  `setMaxIterations`(imax)

    Sets the maximum number of iterations before the minimizer terminates.

  `setOptions`(**opts)

    Sets minimizer-specific options. For a list of possible options see `getOptions()`.

  `setTolerance`(m_tol=0.0001, J_tol=None)

    Sets the tolerance for the stopping criterion. The minimizer stops when an appropriate norm is less than `m_tol`.

class `esys.downunder.``SplitRegularization`(domain, numLevelSets=1, w0=None, w1=None, wc=None, location_of_set_m=<esys.escriptcore.escriptcpp.Data object>, useDiagonalHessianApproximation=False, tol=1e-08, coordinates=None, scale=None, scale_c=None)

  Bases: `esys.downunder.costfunctions.CostFunction`

  The regularization term for the level set function `m` within the cost function J for an inversion:

  J(m)=1/2 * sum_k integrate( mu[k] * ( w0[k] * m_k**2 * w1[k,i] * m_{k,i}**2) + sum_l<k mu_c[l,k] wc[l,k] * | curl(m_k) x curl(m_l) |^2

  where w0[k], w1[k,i] and wc[k,l] are non-negative weighting factors and mu[k] and mu_c[l,k] are trade-off factors which may be altered during the inversion. The weighting factors are normalized such that their integrals over the domain are constant:

  integrate(w0[k] + inner(w1[k,:],1/L[:]**2))=scale[k] volume(domain)* integrate(wc[l,k]*1/L**4)=scale_c[k] volume(domain) *

  `__init__`(domain, numLevelSets=1, w0=None, w1=None, wc=None, location_of_set_m=<esys.escriptcore.escriptcpp.Data object>, useDiagonalHessianApproximation=False, tol=1e-08, coordinates=None, scale=None, scale_c=None)

    initialization.

    Parameters:

    - domain (`Domain`) – domain
    - numLevelSets (`int`) – number of level sets
    - w0 (`Scalar` if `numLevelSets` == 1 or `Data` object of shape (`numLevelSets` ,) if `numLevelSets` > 1) – weighting factor for the m**2 term. If not set zero is assumed.
    - w1 (`Vector` if `numLevelSets` == 1 or `Data` object of shape (`numLevelSets` , DIM) if `numLevelSets` > 1) – weighting factor for the grad(m_i) terms. If not set zero is assumed
    - wc (`Data` object of shape (`numLevelSets` , `numLevelSets`)) – weighting factor for the cross gradient terms. If not set zero is assumed. Used for the case if `numLevelSets` > 1 only. Only values `wc[l,k]` in the lower triangle (l<k) are used.
    - location_of_set_m (`Scalar` if `numLevelSets` == 1 or `Data` object of shape (`numLevelSets` ,) if `numLevelSets` > 1) – marks location of zero values of the level set function `m` by a positive entry.
    - useDiagonalHessianApproximation (`bool`) – if True cross gradient terms between level set components are ignored when calculating approximations of the inverse of the Hessian Operator. This can speed-up the calculation of the inverse but may lead to an increase of the number of iteration steps in the inversion.
    - tol (positive `float`) – tolerance when solving the PDE for the inverse of the Hessian Operator
    - coordinates (ReferenceSystem` or `SpatialCoordinateTransformation`) – defines coordinate system to be used
    - scale (`Scalar` if `numLevelSets` == 1 or `Data` object of shape (`numLevelSets` ,) if `numLevelSets` > 1) – weighting factor for level set function variation terms. If not set one is used.
    - scale_c (`Data` object of shape (`numLevelSets`,``numLevelSets``)) – scale for the cross gradient terms. If not set one is assumed. Used for the case if `numLevelSets` > 1 only. Only values `scale_c[l,k]` in the lower triangle (l<k) are used.

  `getArguments`(m)
  `getCoordinateTransformation`()

    returns the coordinate transformation being used

    Return type: | `CoordinateTransformation`

  `getDomain`()

    returns the domain of the regularization term

    Return type: | `Domain`

  `getDualProduct`(m, r)

    returns the dual product of a gradient represented by X=r[1] and Y=r[0] with a level set function m:

    > Y_i*m_i + X_ij*m_{i,j}

    Return type: | `float`

  `getGradient`()

    returns the gradient of f at x using the precalculated values for x.

    Parameters:

    - x (x-type) – location of derivative
    - args – pre-calculated values for `x` from `getArguments()`

    Return type: | r-type

  `getGradientAtPoint`()

    returns the gradient of the cost function J with respect to m.

    Note: | This implementation returns Y_k=dPsi/dm_k and X_kj=dPsi/dm_kj

  `getInverseHessianApproximation`(x, r, *args)

    returns an approximative evaluation p of the inverse of the Hessian operator of the cost function for a given gradient r at a given location x: H(x) p = r

    Parameters:

    - x (x-type) – location of Hessian operator to be evaluated
    - r (r-type) – a given gradient
    - args – pre-calculated values for `x` from `getArguments()`

    Return type: | x-type
    Note: | In general it is assumed that the Hessian H(x) needs to be calculated in each call for a new location x. However, the solver may suggest that this is not required, typically when the iteration is close to completeness.
    Note: | Subclasses that implement this method should set the class variable `provides_inverse_Hessian_approximation` to `True` to enable the solver to call this method.

  `getInverseHessianApproximationAtPoint`(r, solve=True)
  `getNorm`(m)

    returns the norm of `m`.

    Parameters: | m (`Data`) – level set function
    Return type: | `float`

  `getNumLevelSets`()

    returns the number of level set functions

    Return type: | `int`

  `getNumTradeOffFactors`()

    returns the number of trade-off factors being used.

    Return type: | `int`

  `getPDE`()

    returns the linear PDE to be solved for the Hessian Operator inverse

    Return type: | `linearPDEs.LinearPDE`

  `getValue`(m, grad_m)

    returns the value of the cost function J with respect to m. This equation is specified in the inversion cookbook.

    Return type: | `float`

  `getValueAtPoint`()

    returns the value of the cost function J with respect to m. This equation is specified in the inversion cookbook.

    Return type: | `float`

  `provides_inverse_Hessian_approximation` = False
  `setPoint`(m)

    sets the point which this function will work with

    Parameters: | m (`Data`) – level set function

  `setTradeOffFactors`(mu=None)

    sets the trade-off factors for the level-set variation and the cross-gradient.

    Parameters: | mu (`list` of `float` or ``numpy.array``) – new values for the trade-off factors where values mu[:numLevelSets] are the trade-off factors for the level-set variation and the remaining values for the cross-gradient part with mu_c[l,k]=mu[numLevelSets+l+((k-1)*k)/2] (l<k). If no values for mu are given ones are used. Values must be positive.

  `setTradeOffFactorsForCrossGradient`(mu_c=None)

    sets the trade-off factors for the cross-gradient terms.

    Parameters: | mu_c (`float`, `list` of `float` or `numpy.array`) – new values for the trade-off factors for the cross-gradient terms. Values must be positive. If no value is given ones are used. Only value mu_c[l,k] for l<k are used.

  `setTradeOffFactorsForVariation`(mu=None)

    sets the trade-off factors for the level-set variation part.

    Parameters: | mu (`float`, `list` of `float` or ``numpy.array``) – new values for the trade-off factors. Values must be positive.

  `updateHessian`()

    notifies the class to recalculate the Hessian operator.

class `esys.downunder.``StrongJointGravityMagneticInversion`(solverclass=None, debug=False, self_demagnetization=False, magnetic_intensity_data=False)

  Bases: `esys.downunder.inversions.InversionDriver`

  Driver class to perform a joint inversion of Gravity (Bouguer) and magnetic anomaly data with the assumption that there is a functional relationship between density and susceptibility.

  The class uses the standard `Regularization` class for a single level set function, `DensityMapping` and `SusceptibilityMapping` mappings, the gravity forward model `GravityModel` and the linear magnetic forward model `MagneticModel`.

  `__init__`(solverclass=None, debug=False, self_demagnetization=False, magnetic_intensity_data=False)

    creates an instance of an inversion driver.

    Parameters:

    - solverclass ('AbstractMinimizer'.) – class of the solver to be used.
    - self_demagnetization – if True self-demagnitization is applied.
    - magnetic_intensity_data – if True magnetic intensity is used in the cost function.

  `DENSITY` = 0
  `SUSCEPTIBILITY` = 1
  `fixGravityPotentialAtBottom`(status=False)

    indicates to fix the gravity potential at the bottom to zero (in addition to the top)

    Parameters: | status (`bool`) – if True gravity potential at the bottom is set to zero

  `fixMagneticPotentialAtBottom`(status=True)

    indicates to fix the magnetic potential at the bottom to zero (in addition to the top)

    Parameters: | status (`bool`) – if True magnetic potential at the bottom is set to zero

  `getCostFunction`()

    returns the cost function of the inversion.

    Return type: | ‘InversionCostFunction’

  `getDomain`()

    returns the domain of the inversion

    Return type: | `Domain`

  `getLevelSetFunction`()

    returns the level set function as solution of the optimization problem

    Return type: | `Data`

  `getSolver`()

    The solver to be used in the inversion process. See the minimizers module for available solvers. By default, the L-BFGS minimizer is used.

    Return type: | ‘AbstractMinimizer’.

  `isSetUp`()

    returns True if the inversion is set up and is ready to run.

    Return type: | `bool`

  `run`()

    Executes the inversion.

    Returns: | physical parameters as result of the inversion
    Return type: | `list` of physical parameters or a physical parameter

  `setCostFunction`(costfunction)

    sets the cost function of the inversion. This function needs to be called before the inversion iteration can be started.

    Parameters: | costfunction ('InversionCostFunction') – domain of the inversion

  `setInitialGuess`(rho=None, k=None)

    set the initial guess rho for density and k for susceptibility for the inversion iteration.

    Parameters:

    - rho (`Scalar`) – initial value for the density anomaly.
    - k (`Scalar`) – initial value for the susceptibility anomaly.

  `setSolverCallback`(callback=None)

    Sets the callback function which is called after every solver iteration.

  `setSolverMaxIterations`(maxiter=None)

    Sets the maximum number of solver iterations to run. If `maxiter` is reached the iteration is terminated and `MinimizerMaxIterReached` is thrown.

    Parameters: | maxiter (positive `int`) – maximum number of iteration steps.

  `setSolverTolerance`(m_tol=None, J_tol=None)

    Sets the error tolerance for the solver. An acceptable solution is considered to be found once the tolerance is reached.

    Parameters:

    - m_tol (`float` or `None`) – tolerance for changes to level set function. If `None` changes to the level set function are not checked for convergence during iteration.
    - J_tol (`float` or `None`) – tolerance for changes to cost function. If `None` changes to the cost function are not checked for convergence during iteration.

    Note: | if both arguments are `None` the default setting m_tol=1e-4, J_tol=None is used.

  `setup`(domainbuilder, rho0=None, drho=None, rho_z0=None, rho_beta=None, k0=None, dk=None, k_z0=None, k_beta=None, w0=None, w1=None, w_gc=None, rho_at_depth=None, k_at_depth=None)

    Sets up the inversion from an instance `domainbuilder` of a `DomainBuilder`. Gravity and magnetic data attached to the `domainbuilder` are considered in the inversion. If magnetic data are given as scalar it is assumed that values are collected in direction of the background magnetic field.

    Parameters:

    - domainbuilder (`DomainBuilder`) – Domain builder object with gravity source(s)
    - rho0 (`float` or `Scalar`) – reference density, see `DensityMapping`. If not specified, zero is used.
    - drho (`float` or `Scalar`) – density scale, see `DensityMapping`. If not specified, 2750 kg/m^3 is used.
    - rho_z0 (`float` or `Scalar`) – reference depth for depth weighting for density, see `DensityMapping`. If not specified, zero is used.
    - rho_beta (`float` or `Scalar`) – exponent for density depth weighting, see `DensityMapping`. If not specified, zero is used.
    - k0 (`float` or `Scalar`) – reference susceptibility, see `SusceptibilityMapping`. If not specified, zero is used.
    - dk (`float` or `Scalar`) – susceptibility scale, see `SusceptibilityMapping`. If not specified, 1. is used.
    - k_z0 (`float` or `Scalar`) – reference depth for susceptibility depth weighting, see `SusceptibilityMapping`. If not specified, zero is used.
    - k_beta (`float` or `Scalar`) – exponent for susceptibility depth weighting, see `SusceptibilityMapping`. If not specified, zero is used.
    - w0 (`Scalar` or `float`) – weighting factor for level set term in the regularization. If not set zero is assumed.
    - w1 (`es.Data` or `ndarray` of shape (DIM,)) – weighting factor for the gradient term in the regularization see `Regularization`. If not set zero is assumed.
    - w_gc (`Scalar` or `float`) – weighting factor for the cross gradient term in the regularization, see `Regularization`. If not set one is assumed.
    - k_at_depth (`float` or `None`) – value for susceptibility at depth, see `DomainBuilder`.
    - rho_at_depth (`float` or `None`) – value for density at depth, see `DomainBuilder`.

  `siloWriterCallback`(k, x, Jx, g_Jx, norm_dJ=None, norm_dx=None)

    callback function that can be used to track the solution

    Parameters:

    - k – iteration count
    - x – current m approximation
    - Jx – value of cost function
    - g_Jx – gradient of f at x

class `esys.downunder.``Subsidence`(domain, w, d, lam, mu, coordinates=None, tol=1e-08)

  Bases: `esys.downunder.forwardmodels.base.ForwardModel`

  Forward Model for subsidence inversion minimizing integrate( (inner(w,u)-d)**2) where u is the surface displacement due to a pressure change P

  `__init__`(domain, w, d, lam, mu, coordinates=None, tol=1e-08)

    Creates a new subsidence on the given domain

    Parameters:

    - domain (`Domain`) – domain of the model
    - w (`Vector` with `FunctionOnBoundary`) – data weighting factors and direction
    - d (`Scalar` with `FunctionOnBoundary`) – displacement measured at surface
    - lam (`Scalar` with `Function`) – 1st Lame coefficient
    - lam – 2st Lame coefficient/Shear modulus
    - coordinates (`ReferenceSystem` or `SpatialCoordinateTransformation`) – defines coordinate system to be used (not supported yet))
    - tol (positive `float`) – tolerance of underlying PDE

  `getArguments`(P)

    Returns precomputed values shared by `getDefect()` and `getGradient()`.

    Parameters: | P (`Scalar`) – pressure
    Returns: | displacement u
    Return type: | `Vector`

  `getCoordinateTransformation`()
  `getDefect`(P, u)

    Returns the value of the defect.

    Parameters:

    - P (`Scalar`) – pressure
    - u (`Vector`) – corresponding displacement

    Return type: | `float`

  `getGradient`(P, u)

    Returns the gradient of the defect with respect to susceptibility.

    Parameters:

    - P (`Scalar`) – pressure
    - u (`Vector`) – corresponding displacement

    Return type: | `Scalar`

  `rescaleWeights`(scale=1.0, P_scale=1.0)

    rescales the weights

    Parameters:

    - scale (positive `float`) – scale of data weighting factors
    - P_scale (`Scalar`) – scale of pressure increment

class `esys.downunder.``SusceptibilityMapping`(domain, z0=None, k0=None, dk=None, beta=None)

  Bases: `esys.downunder.mappings.LinearMapping`

  Susceptibility mapping with depth weighting

  k = k0 + dk * ( (x_2 - z0)/l_z)^(beta/2) ) * m

  `__init__`(domain, z0=None, k0=None, dk=None, beta=None)

    set up mapping

    Parameters:

    - domain (`Domain`) – domain of the mapping
    - z0 (scalar) – depth weighting offset. If not present no depth scaling is applied.
    - k0 (scalar) – reference density, defaults to 0
    - dk (scalar) – susceptibility scale, defaults to 1
    - beta (`float`) – depth weighting exponent, defaults to 2

  `getDerivative`(m)

    returns the value for the derivative of the mapping for m

  `getInverse`(p)

    returns the value of the inverse of the mapping for s

  `getTypicalDerivative`()

    returns a typical value for the derivative

  `getValue`(m)

    returns the value of the mapping for m

class `esys.downunder.``SyntheticData`(data_type, n_length=1, n_depth=1, depth_offset=0.0, depth=None, amplitude=None, DIM=2, number_of_elements=10, length=1000.0, B_b=None, data_offset=0, full_knowledge=False, s=0.0)

  Bases: `esys.downunder.datasources.SyntheticDataBase`

  Defines synthetic gravity/magnetic data based on harmonic property anomaly

  > rho = amplitude * sin(n_depth * pi /depth * (z+depth_offset)) * sin(n_length * pi /length * (x - shift) )

  for all x and z<=0. For z>0 rho = 0.

  `__init__`(data_type, n_length=1, n_depth=1, depth_offset=0.0, depth=None, amplitude=None, DIM=2, number_of_elements=10, length=1000.0, B_b=None, data_offset=0, full_knowledge=False, s=0.0)

    Parameters:

    - data_type (`DataSource.GRAVITY`, `DataSource.MAGNETIC`) – data type indicator
    - n_length (`int`) – number of oscillations in the anomaly data within the observation region
    - n_depth (`int`) – number of oscillations in the anomaly data below surface
    - depth_offset (`float`) – vertical offset of the data
    - depth (`float`) – vertical extent in the anomaly data. If not present the depth of the domain is used.
    - amplitude – data amplitude. Default value is 200 U.kg/U.m**3 for gravity and 0.1 for magnetic data.
    - DIM (`int` (2 or 3)) – spatial dimensionality
    - number_of_elements (`int`) – lateral number of elements in the region where data are collected
    - length (`float`) – lateral extent of the region where data are collected
    - B_b (`list` of `Scalar`) – background magnetic flux density [B_r, B_latiude, B_longitude]. Only used for magnetic data.
    - data_offset (`float`) – offset of the data collection region from the surface
    - full_knowledge (`Bool`) – if `True` data are collected from the entire subsurface region. This is mainly for testing.

  `ACOUSTIC` = 2
  `GRAVITY` = 0
  `MAGNETIC` = 1
  `MT` = 3
  `getDataExtents`()

    returns the lateral data extend of the data set

  `getDataType`()

    returns the data type

  `getHeightScale`()

    returns the height scale factor to convert from meters to the appropriate units of the reference system used.

    Return type: | `float`

  `getReferenceProperty`(domain=None)

    Returns the reference `Data` object that was used to generate the gravity/susceptibility anomaly data.

  `getReferenceSystem`()

    returns the reference coordinate system

    Return type: | `ReferenceSystem`

  `getSubsamplingFactor`()

    Returns the subsampling factor that was set via `setSubsamplingFactor` (see there).

  `getSurveyData`(domain, origin, number_of_elements, spacing)

    returns the survey data placed on a given domain.

    Parameters:

    - domain (`Domain`) – domain on which the data are to be placed
    - origin (`list` of `float`) – origin of the domain
    - number_of_elements (`list` of `int`) – number of elements (or cells) in each spatial direction used to span the domain
    - spacing (`list` of `float`) – cell size in each spatial direction

    Returns: | observed gravity field or magnetic flux density for each cell in the domain and for each cell an indicator 1/0 if the data are valid or not.
    Return type: | pair of `Scalar`

  `getTags`()

    returns the list of tags

    Return type: | `list`

  `getUtmZone`()

    returns a dummy UTM zone since this class does not use real coordinate values.

  `hasTag`(tag)

    returns true if the data set has tag `tag`

    Return type: | `bool`

  `setSubsamplingFactor`(f)

    Sets the data subsampling factor (default=1).

    The factor is applied in all dimensions. For example a 2D dataset with 300 x 150 data points will be reduced to 150 x 75 when a subsampling factor of 2 is used. This becomes important when adding data of varying resolution to a `DomainBuilder`.

class `esys.downunder.``SyntheticDataBase`(data_type, DIM=2, number_of_elements=10, length=1000.0, B_b=None, data_offset=0, full_knowledge=False)

  Bases: `esys.downunder.datasources.DataSource`

  Base class to define reference data based on a given property distribution (density or susceptibility). Data are collected from a square region of vertical extent `length` on a grid with `number_of_elements` cells in each direction.

  The synthetic data are constructed by solving the appropriate forward problem. Data can be sampled with an offset from the surface at z=0 or using the entire subsurface region.

  `__init__`(data_type, DIM=2, number_of_elements=10, length=1000.0, B_b=None, data_offset=0, full_knowledge=False)

    Parameters:

    - data_type (`DataSource.GRAVITY`, `DataSource.MAGNETIC`) – data type indicator
    - DIM (`int` (2 or 3)) – number of spatial dimensions
    - number_of_elements (`int`) – lateral number of elements in the region where data are collected
    - length (`float`) – lateral extent of the region where data are collected
    - B_b (`list` of `Scalar`) – background magnetic flux density [B_r, B_latiude, B_longitude]. Only used for magnetic data.
    - data_offset (`float`) – offset of the data collection region from the surface
    - full_knowledge (`Bool`) – if `True` data are collected from the entire subsurface region. This is mainly for testing.

  `ACOUSTIC` = 2
  `GRAVITY` = 0
  `MAGNETIC` = 1
  `MT` = 3
  `getDataExtents`()

    returns the lateral data extend of the data set

  `getDataType`()

    returns the data type

  `getHeightScale`()

    returns the height scale factor to convert from meters to the appropriate units of the reference system used.

    Return type: | `float`

  `getReferenceProperty`(domain=None)

    Returns the reference `Data` object that was used to generate the gravity/susceptibility anomaly data.

    Returns: | the density or susceptibility anomaly used to create the survey data
    Note: | it can be assumed that in the first call the `domain` argument is present so the actual anomaly data can be created. In subsequent calls this may not be true.
    Note: | method needs to be overwritten

  `getReferenceSystem`()

    returns the reference coordinate system

    Return type: | `ReferenceSystem`

  `getSubsamplingFactor`()

    Returns the subsampling factor that was set via `setSubsamplingFactor` (see there).

  `getSurveyData`(domain, origin, number_of_elements, spacing)

    returns the survey data placed on a given domain.

    Parameters:

    - domain (`Domain`) – domain on which the data are to be placed
    - origin (`list` of `float`) – origin of the domain
    - number_of_elements (`list` of `int`) – number of elements (or cells) in each spatial direction used to span the domain
    - spacing (`list` of `float`) – cell size in each spatial direction

    Returns: | observed gravity field or magnetic flux density for each cell in the domain and for each cell an indicator 1/0 if the data are valid or not.
    Return type: | pair of `Scalar`

  `getTags`()

    returns the list of tags

    Return type: | `list`

  `getUtmZone`()

    returns a dummy UTM zone since this class does not use real coordinate values.

  `hasTag`(tag)

    returns true if the data set has tag `tag`

    Return type: | `bool`

  `setSubsamplingFactor`(f)

    Sets the data subsampling factor (default=1).

    The factor is applied in all dimensions. For example a 2D dataset with 300 x 150 data points will be reduced to 150 x 75 when a subsampling factor of 2 is used. This becomes important when adding data of varying resolution to a `DomainBuilder`.

class `esys.downunder.``SyntheticFeatureData`(data_type, features, DIM=2, number_of_elements=10, length=1000.0, B_b=None, data_offset=0, full_knowledge=False)

  Bases: `esys.downunder.datasources.SyntheticDataBase`

  Uses a list of `SourceFeature` objects to define synthetic anomaly data.

  `__init__`(data_type, features, DIM=2, number_of_elements=10, length=1000.0, B_b=None, data_offset=0, full_knowledge=False)

    Parameters:

    - data_type (`DataSource.GRAVITY`, `DataSource.MAGNETIC`) – data type indicator
    - features (`list` of `SourceFeature`) – list of features. It is recommended that the features are located entirely below the surface.
    - DIM (`int` (2 or 3)) – spatial dimensionality
    - number_of_elements (`int`) – lateral number of elements in the region where data are collected
    - length (`float`) – lateral extent of the region where data are collected
    - B_b (`list` of `Scalar`) – background magnetic flux density [B_r, B_latiude, B_longitude]. Only used for magnetic data.
    - data_offset (`float`) – offset of the data collection region from the surface
    - full_knowledge (`Bool`) – if `True` data are collected from the entire subsurface region. This is mainly for testing.

  `ACOUSTIC` = 2
  `GRAVITY` = 0
  `MAGNETIC` = 1
  `MT` = 3
  `getDataExtents`()

    returns the lateral data extend of the data set

  `getDataType`()

    returns the data type

  `getHeightScale`()

    returns the height scale factor to convert from meters to the appropriate units of the reference system used.

    Return type: | `float`

  `getReferenceProperty`(domain=None)

    Returns the reference `Data` object that was used to generate the gravity/susceptibility anomaly data.

  `getReferenceSystem`()

    returns the reference coordinate system

    Return type: | `ReferenceSystem`

  `getSubsamplingFactor`()

    Returns the subsampling factor that was set via `setSubsamplingFactor` (see there).

  `getSurveyData`(domain, origin, number_of_elements, spacing)

    returns the survey data placed on a given domain.

    Parameters:

    - domain (`Domain`) – domain on which the data are to be placed
    - origin (`list` of `float`) – origin of the domain
    - number_of_elements (`list` of `int`) – number of elements (or cells) in each spatial direction used to span the domain
    - spacing (`list` of `float`) – cell size in each spatial direction

    Returns: | observed gravity field or magnetic flux density for each cell in the domain and for each cell an indicator 1/0 if the data are valid or not.
    Return type: | pair of `Scalar`

  `getTags`()

    returns the list of tags

    Return type: | `list`

  `getUtmZone`()

    returns a dummy UTM zone since this class does not use real coordinate values.

  `hasTag`(tag)

    returns true if the data set has tag `tag`

    Return type: | `bool`

  `setSubsamplingFactor`(f)

    Sets the data subsampling factor (default=1).

    The factor is applied in all dimensions. For example a 2D dataset with 300 x 150 data points will be reduced to 150 x 75 when a subsampling factor of 2 is used. This becomes important when adding data of varying resolution to a `DomainBuilder`.

class `esys.downunder.``TTIWave`(domain, v_p, v_s, wavelet, source_tag, source_vector=[0.0, 1.0], eps=0.0, delta=0.0, theta=0.0, rho=1.0, dt=None, u0=None, v0=None, absorption_zone=300.0, absorption_cut=0.01, lumping=True)

  Bases: `esys.downunder.seismic.WaveBase`

  Solving the 2D TTI wave equation with

  `sigma_xx= c11*e_xx + c13*e_zz + c15*e_xz` `sigma_zz= c13*e_xx + c33*e_zz + c35*e_xz` `sigma_xz= c15*e_xx + c35*e_zz + c55*e_xz`

  the coefficients `c11`, `c13`, etc are calculated from the tompsen parameters `eps`, `delta` and the tilt `theta`

  Note: | currently only the 2D case is supported.

  `__init__`(domain, v_p, v_s, wavelet, source_tag, source_vector=[0.0, 1.0], eps=0.0, delta=0.0, theta=0.0, rho=1.0, dt=None, u0=None, v0=None, absorption_zone=300.0, absorption_cut=0.01, lumping=True)

    initialize the TTI wave solver

    Parameters:

    - domain (`Domain`) – domain of the problem
    - v_p (`escript.Scalar`) – vertical p-velocity field
    - v_s (`escript.Scalar`) – vertical s-velocity field
    - wavelet (`Wavelet`) – wavelet to describe the time evolution of source term
    - source_tag ('str' or 'int') – tag of the source location
    - source_vector – source orientation vector
    - eps – first Thompsen parameter
    - delta – second Thompsen parameter
    - theta – tilting (in Rad)
    - rho – density
    - dt – time step size. If not present a suitable time step size is calculated.
    - u0 – initial solution. If not present zero is used.
    - v0 – initial solution change rate. If not present zero is used.
    - absorption_zone – thickness of absorption zone
    - absorption_cut – boundary value of absorption decay factor
    - lumping – if True mass matrix lumping is being used. This is accelerates the computing but introduces some diffusion.

  `getTimeStepSize`()
  `update`(t)

    returns the solution for the next time marker t which needs to greater than the time marker from the previous call.

class `esys.downunder.``VTIWave`(domain, v_p, v_s, wavelet, source_tag, source_vector=[0.0, 0.0, 1.0], eps=0.0, gamma=0.0, delta=0.0, rho=1.0, dt=None, u0=None, v0=None, absorption_zone=None, absorption_cut=0.01, lumping=True, disable_fast_assemblers=False)

  Bases: `esys.downunder.seismic.WaveBase`

  Solving the VTI wave equation

  Note: | In case of a two dimensional domain the second spatial dimenion is depth.

  `__init__`(domain, v_p, v_s, wavelet, source_tag, source_vector=[0.0, 0.0, 1.0], eps=0.0, gamma=0.0, delta=0.0, rho=1.0, dt=None, u0=None, v0=None, absorption_zone=None, absorption_cut=0.01, lumping=True, disable_fast_assemblers=False)

    initialize the VTI wave solver

    Parameters:

    - domain (`Domain`) – domain of the problem
    - v_p (`escript.Scalar`) – vertical p-velocity field
    - v_s (`escript.Scalar`) – vertical s-velocity field
    - wavelet (`Wavelet`) – wavelet to describe the time evolution of source term
    - source_tag ('str' or 'int') – tag of the source location
    - source_vector – source orientation vector
    - eps – first Thompsen parameter
    - delta – second Thompsen parameter
    - gamma – third Thompsen parameter
    - rho – density
    - dt – time step size. If not present a suitable time step size is calculated.
    - u0 – initial solution. If not present zero is used.
    - v0 – initial solution change rate. If not present zero is used.
    - absorption_zone – thickness of absorption zone
    - absorption_cut – boundary value of absorption decay factor
    - lumping – if True mass matrix lumping is being used. This is accelerates the computing but introduces some diffusion.
    - disable_fast_assemblers (`boolean`) – if True, forces use of slower and more general PDE assemblers

  `getTimeStepSize`()
  `setQ`(q)

    sets the PDE q value

    Parameters: | q – the value to set

  `update`(t)

    returns the solution for the next time marker t which needs to greater than the time marker from the previous call.

class `esys.downunder.``WaveBase`(dt, u0, v0, t0=0.0)

  Bases: `object`

  Base for wave propagation using the Verlet scheme.

  > `u_tt = A(t,u), u(t=t0)=u0, u_t(t=t0)=v0`

  with a given acceleration force as function of time.

  a_n=A(t_{n-1}) v_n=v_{n-1} + dt * a_n u_n=u_{n-1} + dt * v_n

  `__init__`(dt, u0, v0, t0=0.0)

    set up the wave base

    Parameters:

    - dt – time step size (need to be sufficiently small)
    - u0 – initial value
    - v0 – initial velocity
    - t0 – initial time

  `getTimeStepSize`()
  `update`(t)

    returns the solution for the next time marker t which needs to greater than the time marker from the previous call.

class `esys.downunder.``WennerSurvey`(domain, primaryConductivity, secondaryConductivity, current, a, midPoint, directionVector, numElectrodes)

  Bases: `esys.downunder.dcresistivityforwardmodeling.DcResistivityForward`

  WennerSurvey forward calculation

  `__init__`(domain, primaryConductivity, secondaryConductivity, current, a, midPoint, directionVector, numElectrodes)

    Parameters:

    - domain (`Domain`) – domain of the model
    - primaryConductivity (`data`) – preset primary conductivity data object
    - secondaryConductivity (`data`) – preset secondary conductivity data object
    - current (`float` or `int`) – amount of current to be injected at the current electrode
    - a (`list`) – the spacing between current and potential electrodes
    - midPoint – midPoint of the survey, as a list containing x,y coords
    - directionVector – two element list specifying the direction the survey should extend from the midpoint
    - numElectrodes (`int`) – the number of electrodes to be used in the survey must be a multiple of 2 for polepole survey

  `checkBounds`()
  `getApparentResistivity`()
  `getApparentResistivityPrimary`()
  `getApparentResistivitySecondary`()
  `getApparentResistivityTotal`()
  `getElectrodes`()

    retuns the list of electrodes with locations

  `getPotential`()

    returns a list containing 3 lists one for each the primary, secondary and total potential.

`esys.downunder.``xrange`

  alias of `builtins.range`

## Functions

`esys.downunder.``CartesianCoordinateTransformation`(domain, reference=<esys.downunder.coordinates.CartesianReferenceSystem object>)

`esys.downunder.``GRS80ReferenceSystem`()

  returns the `GeodeticReferenceSystem` for the GRS80 Ellipsoid eg. used by Geocentric Datum of Australia GDA94

`esys.downunder.``SphericalReferenceSystem`(R=6378137.0)

  returns the `GeodeticReferenceSystem` of a sphere :param R: sphere radius :type R: positive `double`

`esys.downunder.``WGS84ReferenceSystem`()

  returns the `GeodeticReferenceSystem` for the WGS84 Ellipsoid

`esys.downunder.``createAbsorptionLayerFunction`(x, absorption_zone=300.0, absorption_cut=0.01, top_absorption=False)

  Creates a distribution which is one in the interior of the domain of `x` and is falling down to the value ‘absorption_cut’ over a margin of thickness ‘absorption_zone’ toward each boundary except the top of the domain.

  Parameters:

  - x (`escript.Data`) – location of points in the domain
  - absorption_zone – thickness of the absorption zone
  - absorption_cut – value of decay function on domain boundary

  Returns: | function on ‘x’ which is one in the iterior and decays to almost zero over a margin toward the boundary.

`esys.downunder.``makeTransformation`(domain, coordinates=None)

  returns a `SpatialCoordinateTransformation` for the given domain

  Parameters:

  - domain (`esys.escript.AbstractDomain`) – domain in the domain of the coordinate transformation
  - coordinates (`ReferenceSystem` or `SpatialCoordinateTransformation`) – the reference system or spatial coordinate system.

  Returns: | the spatial coordinate system for the given domain of the specified reference system `coordinates`. If `coordinates` is already spatial coordinate system based on the riven domain `coordinates` is returned. Otherwise an appropriate spatial coordinate system is created.
  Return type: | `SpatialCoordinateTransformation`

`esys.downunder.``saveSilo`(filename, domain=None, write_meshdata=False, time=0.0, cycle=0, **data)

  Writes `Data` objects and their mesh to a file using the SILO file format.

  Example:

      temp=Scalar(..)
      v=Vector(..)
      saveSilo("solution.silo", temperature=temp, velocity=v)

  `temp` and `v` are written to “solution.silo” where `temp` is named “temperature” and `v` is named “velocity”.

  Parameters:

  - filename (`str`) – name of the output file (‘.silo’ is added if required)
  - domain (`escript.Domain`) – domain of the `Data` objects. If not specified, the domain of the given `Data` objects is used.
  - write_meshdata (`bool`) – whether to save mesh-related data such as element identifiers, ownership etc. This is mainly useful for debugging.
  - time (`float`) – the timestamp to save within the file
  - cycle (`int`) – the cycle (or timestep) of the data
  - <name> – writes the assigned value to the Silo file using <name> as identifier

  Note: | All data objects have to be defined on the same domain but they may be defined on separate `FunctionSpace` s.

## Others

- pi

## Packages

- esys.downunder.dcresistivityforwardmodeling Package
  - Classes
  - Functions
  - Others
  - Packages
- esys.downunder.domainbuilder Package
  - Classes
  - Functions
  - Others
  - Packages
- esys.downunder.seismic Package
  - Classes
  - Functions
  - Others
  - Packages
- esys.downunder.splitinversioncostfunctions Package
  - Classes
  - Functions
  - Others
  - Packages
- esys.downunder.splitminimizers Package
  - Classes
  - Functions
  - Others
  - Packages
- esys.downunder.splitregularizations Package
  - Classes
  - Functions
  - Others
  - Packages