Survey¶

class emg3d.surveys.Survey(name, sources, receivers, frequencies, data=None, fixed=0)[source]¶

Bases: object

Create a survey with sources, receivers, and data.

A survey contains all the sources with their frequencies, receivers, and corresponding data.

Underlying the survey-class is an xarray, which is basically a regular ndarray with axis labels and more. The module xarray is a soft dependency, and has to be installed manually to use the Survey functionality.

This class was developed with a node-based, marine CSEM survey layout in mind. It is therefore optimised for and mostly tested with that setup. This means for a number of receivers which measure for all source positions. The general layout of the data for such a survey is (S, R, F), where S is the number of sources, R the number of receivers, and F the number of frequencies:

                      f1
     Rx1 Rx2  .  RxR /   f2
    ┌───┬───┬───┬───┐   /   .
Tx1 │   │   │   │   │──┐   /   fF
    ├───┼───┼───┼───┤  │──┐   /
Tx2 │   │   │   │   │──┤  │──┐
    ├───┼───┼───┼───┤  │──┤  │
 .  │   │   │   │   │──┤  │──┤
    ├───┼───┼───┼───┤  │──┤  │
TxS │   │   │   │   │──┤  │──┤
    └───┴───┴───┴───┘  │──┤  │
       └───┴───┴───┴───┘  │──┤
          └───┴───┴───┴───┘  │
             └───┴───┴───┴───┘

However, the class can also be used for a CSEM streamer-style survey layout (by setting fixed=True), where there is a moving source with one or several receivers at a fixed offset. The layout of the data is then also (S, R, F), but here S is the number of locations of the only source, R is the number of receiver-offsets, and F is the number of frequencies:

                                 f1
         Offs1     .   OffsR    /   .
       ┌─────────┬───┬─────────┐   /   fF
TxPos1 │ Rx1-TP1 │ . │ RxR-TP1 │──┐   /
       ├─────────┼───┼─────────┤  │──┐
TxPos2 │ Rx1-TP2 │ . │ RxR-TP2 │──┤  │
       ├─────────┼───┼─────────┤  │──┤
 .     │ .       │ . │ .       │──┤  │
       ├─────────┼───┼─────────┤  │──┤
TxPosS │ Rx1-TPS │ . │ RxR-TPS │──┤  │
       └─────────┴───┴─────────┘  │──┤
          └─────────┴───┴─────────┘  │
             └─────────┴───┴─────────┘

This means that even though there is only one source, there are actually S source dipoles, as each position is treated as a different dipole. The number of receiver dipoles in this case is SxR. This setup can also be used for airborne EM.

Parameters:

name : str

Name of the survey

sources, receivers : tuple, list, or dict

Sources and receivers.

Tuples: Coordinates in one of the two following formats:
- (x, y, z, azimuth, dip) [m, m, m, °, °];
- (x0, x1, y0, y1, z0, z1) [m, m, m, m, m, m].
Dimensions will be expanded (hence, if n dipoles, each parameter must have length 1 or n). These dipoles will be named sequential with Tx### and Rx###.

The tuple can additionally contain an additional element at the end (after dip or z1), electric, a boolean of length 1 or n, that indicates if the dipoles are electric or magnetic.
List: A list of Dipole-instances. The names of all dipoles in the list must be unique.
Dictionary: A dict of de-serialized Dipole-instances; mainly used for loading from file.

frequencies : ndarray

Source frequencies (Hz).

data : ndarray or None

The observed data (dtype=np.complex128); must have shape (nsrc, nrec, nfreq) or, if fixed=True, (nsrc, noff, nfreq). If None, it will be initiated with NaN’s.

fixed : bool

Node-based CSEM survey (fixed=False; default) or streamer-type CSEM survey (fixed=True). In the streamer-type survey, the number of receivers supplied must be a multiple of the source positions. In this case, the receivers are grouped into offsets.

Attributes Summary

`data`	Data, a `xarray.DataSet` instance.
`frequencies`	Frequency array.
`rec_coords`	Return receiver coordinates.
`receivers`	Receiver dict containing all receiver dipoles.
`shape`	Return nsrc x nrec x nfreq.
`size`	Return actual data size (does NOT equal nsrc x nrec x nfreq).
`sources`	Source dict containing all source dipoles.
`src_coords`	Return source coordinates.

Methods Summary

`copy`()	Return a copy of the Survey.
`from_dict`(inp)	Convert dictionary into `Survey` instance.
`from_file`(fname[, verb])	Load Survey from a file.
`to_dict`([copy])	Store the necessary information of the Survey in a dict.
`to_file`(fname[, compression, json_indent, verb])	Store Survey to a file.

Attributes Documentation

data¶

Data, a xarray.DataSet instance.

Contains the xarray.DataArray element .observed, but other data can be added. E.g., emg3d.simulations.Simulation adds the synthetic array.

frequencies¶: Frequency array.

rec_coords¶

Return receiver coordinates.

The returned format is (x, y, z, azm, dip), a tuple of 5 tuples. If fixed=True it returns a dict with the offsets as keys, and for each offset it returns the corresponding receiver coordinates as just outlined.

receivers¶: Receiver dict containing all receiver dipoles.

shape¶

Return nsrc x nrec x nfreq.

Note that not all source-receiver-frequency pairs do actually have data. Check size to see how many data points there are.

size¶: Return actual data size (does NOT equal nsrc x nrec x nfreq).

sources¶: Source dict containing all source dipoles.

src_coords¶

Return source coordinates.

The returned format is (x, y, z, azm, dip), a tuple of 5 tuples.

Methods Documentation

copy()[source]¶: Return a copy of the Survey.

classmethod from_dict(inp)[source]¶

Convert dictionary into Survey instance.

Parameters:	inp : dict Dictionary as obtained from `Survey.to_dict()`. The dictionary needs the keys name, sources, receivers frequencies, observed, and fixed.
Returns:	obj : `Survey` instance

classmethod from_file(fname, verb=1)[source]¶

Load Survey from a file.

Parameters:	fname : str File name including extension. Used backend depends on the file extensions: ‘.npz’: numpy-binary ‘.h5’: h5py-binary (needs h5py) ‘.json’: json verb : int Silent if 0, verbose if 1.
Returns:	survey : `Survey` The survey that was stored in the file.

to_dict(copy=False)[source]¶: Store the necessary information of the Survey in a dict.

to_file(fname, compression='gzip', json_indent=2, verb=1)[source]¶

Store Survey to a file.

Parameters:

fname : str

File name inclusive ending, which defines the used data format. Implemented are currently:

.h5 (default): Uses h5py to store inputs to a hierarchical, compressed binary hdf5 file. Recommended file format, but requires the module h5py. Default format if ending is not provided or not recognized.
.npz: Uses numpy to store inputs to a flat, compressed binary file. Default format if h5py is not installed.
.json: Uses json to store inputs to a hierarchical, plain text file.

compression : int or str, optional

Passed through to h5py, default is ‘gzip’.

json_indent : int or None

Passed through to json, default is 2.

verb : int

Silent if 0, verbose if 1.