The fatiando package has been deprecated. Please check out the new tools in the Fatiando a Terra website: www.fatiando.org

# Forward modeling with tesseroids (fatiando.gravmag.tesseroid)¶

Forward model the gravitational fields of a tesseroid (spherical prism).

Functions in this module calculate the gravitational fields of a tesseroid with respect to the local North-oriented coordinate system of the computation point. See the figure below.

A tesseroid in a geocentric coordinate system (X, Y, Z). Point P is a computation point with associated local North-oriented coordinate system (x, y, z). Image by L. Uieda (doi:10.6084/m9.figshare.1495525).

Coordinate systems

The gravitational attraction and gravity gradient tensor are calculated with respect to the local coordinate system of the computation point. This system has x -> North, y -> East, z -> up (radial direction).

Warning

The $$g_z$$ component is an exception to this. In order to conform with the regular convention of z-axis pointing toward the center of the Earth, this component only is calculated with z -> Down. This way, gravity anomalies of tesseroids with positive density are positive, not negative.

## Gravity¶

Forward modeling of gravitational fields is performed by functions:

The fields are calculated using Gauss-Legendre Quadrature integration and the adaptive discretization algorithm of Uieda et al. (2016). The accuracy of the integration is controlled by the ratio argument. Larger values cause finer discretization and more accuracy but slower computation times. The defaults values are the ones suggested in the paper and guarantee an accuracy of approximately 0.1%.

Warning

The integration error may be larger than this if the computation points are closer than 1 km of the tesseroids. This effect is more significant in the gravity gradient components.

### References¶

Uieda, L., V. Barbosa, and C. Braitenberg (2016), Tesseroids: Forward-modeling gravitational fields in spherical coordinates, Geophysics, F41-F48, doi:10.1190/geo2015-0204.1

fatiando.gravmag.tesseroid.gx(lon, lat, height, model, dens=None, ratio=1.6, njobs=1, pool=None)[source]

Calculate the North component of the gravitational attraction.

Warning

Tesseroids with dimensions < 10 cm will be ignored to avoid numerical errors.

Implements the method of Uieda et al. (2016).

Parameters:

• lon, lat, height
: arrays

Arrays with the longitude, latitude and height coordinates of the computation points.

• model
: list of Tesseroid

The density model used to calculate the gravitational effect. Tesseroids must have the property 'density'. Those that don’t have this property will be ignored in the computations. Elements that are None will also be ignored.

• dens
: float or None

If not None, will use this value instead of the 'density' property of the tesseroids. Use this, e.g., for sensitivity matrix building.

• ratio
: float

Will divide each tesseroid until the distance between it and the computation points is < ratio*size of tesseroid. Used to guarantee the accuracy of the numerical integration.

• njobs
: int

Split the computation into njobs parts and run it in parallel using multiprocessing. If njobs=1 will run the computation in serial.

• pool
: None or multiprocessing.Pool object

If not None, will use this pool to run the computation in parallel instead of creating a new one. You must still specify njobs as the number of processes in the pool. Use this to avoid spawning processes on each call to this functions, which can have significant overhead.

Returns:

• res
: array

The calculated field in mGal

References:

Uieda, L., V. Barbosa, and C. Braitenberg (2016), Tesseroids: Forward-modeling gravitational fields in spherical coordinates, Geophysics, F41-F48, doi:10.1190/geo2015-0204.1

fatiando.gravmag.tesseroid.gxx(lon, lat, height, model, dens=None, ratio=8, njobs=1, pool=None)[source]

Calculate the xx component of the gravity gradient tensor.

Warning

Tesseroids with dimensions < 10 cm will be ignored to avoid numerical errors.

Implements the method of Uieda et al. (2016).

Parameters:

• lon, lat, height
: arrays

Arrays with the longitude, latitude and height coordinates of the computation points.

• model
: list of Tesseroid

The density model used to calculate the gravitational effect. Tesseroids must have the property 'density'. Those that don’t have this property will be ignored in the computations. Elements that are None will also be ignored.

• dens
: float or None

If not None, will use this value instead of the 'density' property of the tesseroids. Use this, e.g., for sensitivity matrix building.

• ratio
: float

Will divide each tesseroid until the distance between it and the computation points is < ratio*size of tesseroid. Used to guarantee the accuracy of the numerical integration.

• njobs
: int

Split the computation into njobs parts and run it in parallel using multiprocessing. If njobs=1 will run the computation in serial.

• pool
: None or multiprocessing.Pool object

If not None, will use this pool to run the computation in parallel instead of creating a new one. You must still specify njobs as the number of processes in the pool. Use this to avoid spawning processes on each call to this functions, which can have significant overhead.

Returns:

• res
: array

The calculated field in Eotvos

References:

Uieda, L., V. Barbosa, and C. Braitenberg (2016), Tesseroids: Forward-modeling gravitational fields in spherical coordinates, Geophysics, F41-F48, doi:10.1190/geo2015-0204.1

fatiando.gravmag.tesseroid.gxy(lon, lat, height, model, dens=None, ratio=8, njobs=1, pool=None)[source]

Calculate the xy component of the gravity gradient tensor.

Warning

Tesseroids with dimensions < 10 cm will be ignored to avoid numerical errors.

Implements the method of Uieda et al. (2016).

Parameters:

• lon, lat, height
: arrays

Arrays with the longitude, latitude and height coordinates of the computation points.

• model
: list of Tesseroid

The density model used to calculate the gravitational effect. Tesseroids must have the property 'density'. Those that don’t have this property will be ignored in the computations. Elements that are None will also be ignored.

• dens
: float or None

If not None, will use this value instead of the 'density' property of the tesseroids. Use this, e.g., for sensitivity matrix building.

• ratio
: float

Will divide each tesseroid until the distance between it and the computation points is < ratio*size of tesseroid. Used to guarantee the accuracy of the numerical integration.

• njobs
: int

Split the computation into njobs parts and run it in parallel using multiprocessing. If njobs=1 will run the computation in serial.

• pool
: None or multiprocessing.Pool object

If not None, will use this pool to run the computation in parallel instead of creating a new one. You must still specify njobs as the number of processes in the pool. Use this to avoid spawning processes on each call to this functions, which can have significant overhead.

Returns:

• res
: array

The calculated field in Eotvos

References:

Uieda, L., V. Barbosa, and C. Braitenberg (2016), Tesseroids: Forward-modeling gravitational fields in spherical coordinates, Geophysics, F41-F48, doi:10.1190/geo2015-0204.1

fatiando.gravmag.tesseroid.gxz(lon, lat, height, model, dens=None, ratio=8, njobs=1, pool=None)[source]

Calculate the xz component of the gravity gradient tensor.

Warning

Tesseroids with dimensions < 10 cm will be ignored to avoid numerical errors.

Implements the method of Uieda et al. (2016).

Parameters:

• lon, lat, height
: arrays

Arrays with the longitude, latitude and height coordinates of the computation points.

• model
: list of Tesseroid

The density model used to calculate the gravitational effect. Tesseroids must have the property 'density'. Those that don’t have this property will be ignored in the computations. Elements that are None will also be ignored.

• dens
: float or None

If not None, will use this value instead of the 'density' property of the tesseroids. Use this, e.g., for sensitivity matrix building.

• ratio
: float

Will divide each tesseroid until the distance between it and the computation points is < ratio*size of tesseroid. Used to guarantee the accuracy of the numerical integration.

• njobs
: int

Split the computation into njobs parts and run it in parallel using multiprocessing. If njobs=1 will run the computation in serial.

• pool
: None or multiprocessing.Pool object

If not None, will use this pool to run the computation in parallel instead of creating a new one. You must still specify njobs as the number of processes in the pool. Use this to avoid spawning processes on each call to this functions, which can have significant overhead.

Returns:

• res
: array

The calculated field in Eotvos

References:

Uieda, L., V. Barbosa, and C. Braitenberg (2016), Tesseroids: Forward-modeling gravitational fields in spherical coordinates, Geophysics, F41-F48, doi:10.1190/geo2015-0204.1

fatiando.gravmag.tesseroid.gy(lon, lat, height, model, dens=None, ratio=1.6, njobs=1, pool=None)[source]

Calculate the East component of the gravitational attraction.

Warning

Tesseroids with dimensions < 10 cm will be ignored to avoid numerical errors.

Implements the method of Uieda et al. (2016).

Parameters:

• lon, lat, height
: arrays

Arrays with the longitude, latitude and height coordinates of the computation points.

• model
: list of Tesseroid

The density model used to calculate the gravitational effect. Tesseroids must have the property 'density'. Those that don’t have this property will be ignored in the computations. Elements that are None will also be ignored.

• dens
: float or None

If not None, will use this value instead of the 'density' property of the tesseroids. Use this, e.g., for sensitivity matrix building.

• ratio
: float

Will divide each tesseroid until the distance between it and the computation points is < ratio*size of tesseroid. Used to guarantee the accuracy of the numerical integration.

• njobs
: int

Split the computation into njobs parts and run it in parallel using multiprocessing. If njobs=1 will run the computation in serial.

• pool
: None or multiprocessing.Pool object

If not None, will use this pool to run the computation in parallel instead of creating a new one. You must still specify njobs as the number of processes in the pool. Use this to avoid spawning processes on each call to this functions, which can have significant overhead.

Returns:

• res
: array

The calculated field in mGal

References:

Uieda, L., V. Barbosa, and C. Braitenberg (2016), Tesseroids: Forward-modeling gravitational fields in spherical coordinates, Geophysics, F41-F48, doi:10.1190/geo2015-0204.1

fatiando.gravmag.tesseroid.gyy(lon, lat, height, model, dens=None, ratio=8, njobs=1, pool=None)[source]

Calculate the yy component of the gravity gradient tensor.

Warning

Tesseroids with dimensions < 10 cm will be ignored to avoid numerical errors.

Implements the method of Uieda et al. (2016).

Parameters:

• lon, lat, height
: arrays

Arrays with the longitude, latitude and height coordinates of the computation points.

• model
: list of Tesseroid

The density model used to calculate the gravitational effect. Tesseroids must have the property 'density'. Those that don’t have this property will be ignored in the computations. Elements that are None will also be ignored.

• dens
: float or None

If not None, will use this value instead of the 'density' property of the tesseroids. Use this, e.g., for sensitivity matrix building.

• ratio
: float

Will divide each tesseroid until the distance between it and the computation points is < ratio*size of tesseroid. Used to guarantee the accuracy of the numerical integration.

• njobs
: int

Split the computation into njobs parts and run it in parallel using multiprocessing. If njobs=1 will run the computation in serial.

• pool
: None or multiprocessing.Pool object

If not None, will use this pool to run the computation in parallel instead of creating a new one. You must still specify njobs as the number of processes in the pool. Use this to avoid spawning processes on each call to this functions, which can have significant overhead.

Returns:

• res
: array

The calculated field in Eotvos

References:

Uieda, L., V. Barbosa, and C. Braitenberg (2016), Tesseroids: Forward-modeling gravitational fields in spherical coordinates, Geophysics, F41-F48, doi:10.1190/geo2015-0204.1

fatiando.gravmag.tesseroid.gyz(lon, lat, height, model, dens=None, ratio=8, njobs=1, pool=None)[source]

Calculate the yz component of the gravity gradient tensor.

Warning

Tesseroids with dimensions < 10 cm will be ignored to avoid numerical errors.

Implements the method of Uieda et al. (2016).

Parameters:

• lon, lat, height
: arrays

Arrays with the longitude, latitude and height coordinates of the computation points.

• model
: list of Tesseroid

The density model used to calculate the gravitational effect. Tesseroids must have the property 'density'. Those that don’t have this property will be ignored in the computations. Elements that are None will also be ignored.

• dens
: float or None

If not None, will use this value instead of the 'density' property of the tesseroids. Use this, e.g., for sensitivity matrix building.

• ratio
: float

Will divide each tesseroid until the distance between it and the computation points is < ratio*size of tesseroid. Used to guarantee the accuracy of the numerical integration.

• njobs
: int

Split the computation into njobs parts and run it in parallel using multiprocessing. If njobs=1 will run the computation in serial.

• pool
: None or multiprocessing.Pool object

If not None, will use this pool to run the computation in parallel instead of creating a new one. You must still specify njobs as the number of processes in the pool. Use this to avoid spawning processes on each call to this functions, which can have significant overhead.

Returns:

• res
: array

The calculated field in Eotvos

References:

Uieda, L., V. Barbosa, and C. Braitenberg (2016), Tesseroids: Forward-modeling gravitational fields in spherical coordinates, Geophysics, F41-F48, doi:10.1190/geo2015-0204.1

fatiando.gravmag.tesseroid.gz(lon, lat, height, model, dens=None, ratio=1.6, njobs=1, pool=None)[source]

Calculate the radial component of the gravitational attraction.

Warning

In order to conform with the regular convention of positive density giving positive gz values, this component only is calculated with z axis -> Down.

Warning

Tesseroids with dimensions < 10 cm will be ignored to avoid numerical errors.

Implements the method of Uieda et al. (2016).

Parameters:

• lon, lat, height
: arrays

Arrays with the longitude, latitude and height coordinates of the computation points.

• model
: list of Tesseroid

The density model used to calculate the gravitational effect. Tesseroids must have the property 'density'. Those that don’t have this property will be ignored in the computations. Elements that are None will also be ignored.

• dens
: float or None

If not None, will use this value instead of the 'density' property of the tesseroids. Use this, e.g., for sensitivity matrix building.

• ratio
: float

Will divide each tesseroid until the distance between it and the computation points is < ratio*size of tesseroid. Used to guarantee the accuracy of the numerical integration.

• njobs
: int

Split the computation into njobs parts and run it in parallel using multiprocessing. If njobs=1 will run the computation in serial.

• pool
: None or multiprocessing.Pool object

If not None, will use this pool to run the computation in parallel instead of creating a new one. You must still specify njobs as the number of processes in the pool. Use this to avoid spawning processes on each call to this functions, which can have significant overhead.

Returns:

• res
: array

The calculated field in mGal

References:

Uieda, L., V. Barbosa, and C. Braitenberg (2016), Tesseroids: Forward-modeling gravitational fields in spherical coordinates, Geophysics, F41-F48, doi:10.1190/geo2015-0204.1

fatiando.gravmag.tesseroid.gzz(lon, lat, height, model, dens=None, ratio=8, njobs=1, pool=None)[source]

Calculate the zz component of the gravity gradient tensor.

Warning

Tesseroids with dimensions < 10 cm will be ignored to avoid numerical errors.

Implements the method of Uieda et al. (2016).

Parameters:

• lon, lat, height
: arrays

Arrays with the longitude, latitude and height coordinates of the computation points.

• model
: list of Tesseroid

The density model used to calculate the gravitational effect. Tesseroids must have the property 'density'. Those that don’t have this property will be ignored in the computations. Elements that are None will also be ignored.

• dens
: float or None

If not None, will use this value instead of the 'density' property of the tesseroids. Use this, e.g., for sensitivity matrix building.

• ratio
: float

Will divide each tesseroid until the distance between it and the computation points is < ratio*size of tesseroid. Used to guarantee the accuracy of the numerical integration.

• njobs
: int

Split the computation into njobs parts and run it in parallel using multiprocessing. If njobs=1 will run the computation in serial.

• pool
: None or multiprocessing.Pool object

If not None, will use this pool to run the computation in parallel instead of creating a new one. You must still specify njobs as the number of processes in the pool. Use this to avoid spawning processes on each call to this functions, which can have significant overhead.

Returns:

• res
: array

The calculated field in Eotvos

References:

Uieda, L., V. Barbosa, and C. Braitenberg (2016), Tesseroids: Forward-modeling gravitational fields in spherical coordinates, Geophysics, F41-F48, doi:10.1190/geo2015-0204.1

fatiando.gravmag.tesseroid.potential(lon, lat, height, model, dens=None, ratio=1, njobs=1, pool=None)[source]

Calculate the gravitational potential due to a tesseroid model.

Warning

Tesseroids with dimensions < 10 cm will be ignored to avoid numerical errors.

Implements the method of Uieda et al. (2016).

Parameters:

• lon, lat, height
: arrays

Arrays with the longitude, latitude and height coordinates of the computation points.

• model
: list of Tesseroid

The density model used to calculate the gravitational effect. Tesseroids must have the property 'density'. Those that don’t have this property will be ignored in the computations. Elements that are None will also be ignored.

• dens
: float or None

If not None, will use this value instead of the 'density' property of the tesseroids. Use this, e.g., for sensitivity matrix building.

• ratio
: float

Will divide each tesseroid until the distance between it and the computation points is < ratio*size of tesseroid. Used to guarantee the accuracy of the numerical integration.

• njobs
: int

Split the computation into njobs parts and run it in parallel using multiprocessing. If njobs=1 will run the computation in serial.

• pool
: None or multiprocessing.Pool object

If not None, will use this pool to run the computation in parallel instead of creating a new one. You must still specify njobs as the number of processes in the pool. Use this to avoid spawning processes on each call to this functions, which can have significant overhead.

Returns:

• res
: array

The calculated field in SI units

References:

Uieda, L., V. Barbosa, and C. Braitenberg (2016), Tesseroids: Forward-modeling gravitational fields in spherical coordinates, Geophysics, F41-F48, doi:10.1190/geo2015-0204.1