# esys.downunder.domainbuilder Package

Domain construction from survey data for inversions

## Classes

- `CartesianReferenceSystem`

- `DataSource`

- `DomainBuilder`

- `ReferenceSystem`

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

  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`

  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.domainbuilder.DataSource(reference_system=None, tags=[])

  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.domainbuilder.DomainBuilder(dim=3, reference_system=None)

  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.domainbuilder.ReferenceSystem(name='none')

  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

## Functions

esys.downunder.domainbuilder.Brick((object)n0, (object)n1, (object)n2[, (object)l0=1.0[, (object)l1=1.0[, (object)l2=1.0[, (object)d0=-1[, (object)d1=-1[, (object)d2=-1[, (object)diracPoints=[][, (object)diracTags=[][, (SubWorld)escriptworld=None]]]]]]]]]) → Domain :

  Creates a hexagonal mesh with n0 x n1 x n2 elements over the brick [0,l0] x [0,l1] x [0,l2].

  Parameters

    - n0 (`int`) – number of elements in direction 0

    - n1 (`int`) – number of elements in direction 1

    - n2 (`int`) – number of elements in direction 2

    - l0 (`float` or `tuple`) – length of side 0 or coordinate range of side 0

    - l1 (`float` or `tuple`) – length of side 1 or coordinate range of side 1

    - l2 (`float` or `tuple`) – length of side 2 or coordinate range of side 2

    - d0 (`int`) – number of subdivisions in direction 0

    - d1 (`int`) – number of subdivisions in direction 1

    - d2 (`int`) – number of subdivisions in direction 2

esys.downunder.domainbuilder.Rectangle((object)n0, (object)n1[, (object)l0=1.0[, (object)l1=1.0[, (object)d0=-1[, (object)d1=-1[, (object)diracPoints=[][, (object)diracTags=[][, (SubWorld)escriptworld=None]]]]]]]) → Domain :

  Creates a rectangular mesh with n0 x n1 elements over the rectangle [0,l0] x [0,l1].

  Parameters

    - n0 (`int`) – number of elements in direction 0

    - n1 (`int`) – number of elements in direction 1

    - l0 (`float` or `tuple`) – length of side 0 or coordinate range of side 0

    - l1 (`float` or `tuple`) – length of side 1 or coordinate range of side 1

    - d0 (`int`) – number of subdivisions in direction 0

    - d1 (`int`) – number of subdivisions in direction 1

## Others

- HAVE_RIPLEY

## Packages