pyharm.gfm#

Module for spectral gravity forward modelling. Offers:

global and spatially limited spectral gravity forward modelling of band-limited topographic masses having constant, lateral and 3D varying mass density.

Note

This documentation is written for double precision version of PyHarm.

Note

Spatially limited integration radius is available only if --enable-mpfr is specified when calling ./configure during the installation. See Installing for further details.

pyharm.gfm.global_density_3d(shape_shcs, shape_nmax, shape_radius_ref, density_shcs, density_nmax, density_order, grav_const, mass, shape_power_min, shape_power_max, potential_shcs_nmax, shape_density_shcs_path=None, potential_shcs_path=None, shcs_file_format='tbl', encoding='utf-8', return_output=True)#

Performs global spectral gravity forward modelling of an arbitrary 3D polynomial mass density. For more details, refer to charm_gfm.

Parameters:

shape_shcs (Shc) – Spherical harmonic coefficients defining the shape of the body (the upper integration limit in the radial direction)
shape_nmax (integer) – Maximum harmonic degree to take when defining the shape of the gravitating body by the spherical harmonic coefficients in shape_shcs.
shape_radius_ref (floating point) – Radius defining the lower integration limit in the radial direction. Forward modelled will be the masses between the sphere of radius shape_radius_ref and the body’s surface defined by shape_shcs.
density_shcs (list) – List of pyharm.shc.Shc class instances defining the spherical harmonic coefficients of the density polynomial coefficients. For instance, density_shcs[0] is a pyharm.shc.Shc class instance defining the spherical harmonic coefficients of the zero-order laterally varying polynomial density coefficients; density_shcs[1] is a pyharm.shc.Shc class instance holding the spherical harmonic coefficients of the first-order laterally varying polynomial density coefficients; etc.
density_nmax (list) – List of maximum harmonic degrees to be used with the respective pyharm.shc.Shc instances in density_shcs when defining the polynomial density coefficients. More specifically, density_nmax[i] is the maximum harmonic degree that will be used when defining the polynomial density coefficients of order \(i\) by density_shcs[i].
density_order (integer) – Maximum order of the density polynomial.
grav_const (floating point) – Newton’s gravitational constant.
mass (floating point) – Mass of the body. The value affects the output potential coefficients potential_shcs (see below) but do not affect the gravitational effects synthesized from the coefficients.
shape_power_min (integer) – Minimum topography power. In most cases, the value is 1. Values higher than 1 do not produce a complete gravity field model, but are useful in specific situations.
shape_power_max (integer) – Maximum topography power. The value cannot be smaller than shape_power_min. The larger is the value, the more complete is the spectral gravity forward modelling.
potential_shcs_nmax (integer) – Maximum harmonic degree of the output spherical harmonic coefficients of the implied gravitational potential in potential_shcs (see below).
shape_density_shcs_path (str, None) –
Path and prefix of the output files containing the spherical harmonic coefficients of the shape-density functions. Optional, default value is None. Refer to charm_gfm for further details.
potential_shcs_path (str, None) –
Path and prefix of the output files containing the spherical harmonic coefficients of the gravitational potential implied by the shape-density functions. Optional, default value is None. Refer to charm_gfm for further details.
shcs_file_format (str, None) – String defining the format of the output files specified by shape_density_shcs_path and/or potential_shcs_path. Accepted strings are tbl, mtx, dov, bin. Optional, default value is tbl.
encoding (str) –
Encoding of the shape_density_shcs_path, potential_shcs_path, shcs_file_format strings. In case you have special characters in your shape_density_shcs_path or potential_shcs_path strings, you may need to select proper encoding.

The encoding does not apply to the content of the files. The file reading is done by CHarm, so the file content encoding depends on your operating system.
return_output (bool) –
If True (default), returns an output variable (see out below). If False, None is returned. Refer to charm_gfm for the rational behind this variable.

Returns:

out – If return_output is True, returned is a pyharm.shc.Shc class instance with the spherical harmonic coefficients of the implied gravitational potential. If return_output is False, returned is None.

Return type:

Shc, None

pyharm.gfm.global_density_lateral(shape_shcs, shape_nmax, shape_radius_ref, density_shcs, density_nmax, grav_const, mass, shape_power_min, shape_power_max, potential_shcs_nmax, shape_density_shcs_path=None, potential_shcs_path=None, shcs_file_format='tbl', encoding='utf-8', return_output=True)#

Performs global spectral gravity forward modelling with laterally varying mass density. For more details, refer to charm_gfm.

The function input parameters are the same as in global_density_3d() with two exceptions.

Parameters:

density_shcs (Shc) – Spherical harmonic coefficients of the laterally varying mass density function.
density_nmax (integer) – Maximum harmonic degree, up to which the coefficients from density_shcs are used in forward modelling.

pyharm.gfm.global_density_const(shape_shcs, shape_nmax, shape_radius_ref, density, grav_const, mass, shape_power_min, shape_power_max, potential_shcs_nmax, shape_shcs_powers_path=None, potential_shcs_path=None, shcs_file_format='tbl', encoding='utf-8', return_output=True)#

Performs global spectral gravity forward modelling with a constant mass density after Hirt and Kuhn (2014). For more details, refer to charm_gfm.

The function input parameters are the same as in global_density_3d() with two exceptions.

Parameters:

density (floating point) – Constant mass density.
shape_shcs_powers_path (str) –
Path to export spherical harmonic coefficients of the powers of the topographic height function. For more details, refer to charm_gfm.

pyharm.gfm.Q00: int = 0#

Truncation coefficients \(Q_{npi}^{0,0,j}(r, \psi_0, R)\). The --enable-mpfr flag must be attached during the installation for this variable to be available. See Installing.

Type:: int

pyharm.gfm.Q10: int = 10#

Truncation coefficients \(Q_{npi}^{1,0,j}(r, \psi_0, R)\). The --enable-mpfr flag must be attached during the installation for this variable to be available. See Installing.

Type:: int

pyharm.gfm.Q11: int = 11#

Truncation coefficients \(Q_{npi}^{1,1,j}(r, \psi_0, R)\). The --enable-mpfr flag must be attached during the installation for this variable to be available. See Installing.

Type:: int

pyharm.gfm.Q20: int = 20#

Truncation coefficients \(Q_{npi}^{2,0,j}(r, \psi_0, R)\). The --enable-mpfr flag must be attached during the installation for this variable to be available. See Installing.

Type:: int

pyharm.gfm.Q21: int = 21#

Truncation coefficients \(Q_{npi}^{2,1,j}(r, \psi_0, R)\). The --enable-mpfr flag must be attached during the installation for this variable to be available. See Installing.

Type:: int

pyharm.gfm.Q22: int = 22#

Truncation coefficients \(Q_{npi}^{2,2,j}(r, \psi_0, R)\). The --enable-mpfr flag must be attached during the installation for this variable to be available. See Installing.

Type:: int

pyharm.gfm.cap_density_3d(shape_shcs, shape_nmax, shape_radius_ref, density_shcs, density_nmax, density_order, grav_const, mass, shape_power_min, shape_power_max, radial_derivative_min, radial_derivative_max, evaluation_spherical_radius, integration_radius, u, v, zone, nbits, potential_shcs_nmax, shape_density_shcs_path=None, potential_shcs_path=None, shcs_file_format='tbl', encoding='utf-8', return_output=True)#

Performs cap-modified spectral gravity forward modelling of an arbitrary 3D polynomial mass density. For more details, refer to charm_gfm.

Many of the function parameters have exactly the same meaning as in global_density_3d(), so explained will be the new ones only.

Note

This function is available only if the --enable-mpfr flag is specified during the installation. See Installing.

Parameters:

radial_derivative_min (integer) – Minimum radial derivative of the quantity specified by u and v (see below). Use 0 for no radial derivative.
radial_derivative_max (integer) – The same as radial_derivative_min but for the maximum radial derivative.
evaluation_spherical_radius (floating point) – Spherical radius in metres of the evaluation points. The output coefficients potential_shcs refer to this sphere. If your goal is to compute your u,v-quantity on an irregular surface (e.g., on the Earth’s surface), use analytical continuation through radial derivatives. These can be specified by radial_derivative_min and radial_derivative_max.
integration_radius (floating point) – Cap radius in radians defining the masses to be integrated. Masses within the cap are here called near-zone masses and masses beyond the cap are here called far-zone masses.
u (integer) – Order of the potential derivative, of which spherical harmonic coefficients potential_shcs are computed. Use 0 to get the gravitational potential, use 1 to get quantities related to the first-order potential derivatives or use 2 for quantities related to the second-order potential derivatives. Values larger than 2 are not allowed.
v (integer) – Order of the potential derivative with respect to the spherical distance. Valid values are 0, …, u.
zone (integer) – Non-negative integer for near-zone truncation coefficients or negative integer for far-zone truncation coefficients.
nbits (integer) – Number of bits to represent the significand of all floating point numbers used to compute the truncation coefficients.

Returns:

out – If return_output is True, returned is a list of pyharm.shc.Shc class instances with the spherical harmonic coefficients of the implied gravitational potential for radial_derivative_min (out[0]), …, radial_derivative_max (out[radial_derivative_max - radial_derivative_min]). If return_output is False, returned is None.

Return type:

list, None

pyharm.gfm.cap_density_lateral(shape_shcs, shape_nmax, shape_radius_ref, density_shcs, density_nmax, grav_const, mass, shape_power_min, shape_power_max, radial_derivative_min, radial_derivative_max, evaluation_spherical_radius, integration_radius, u, v, zone, nbits, potential_shcs_nmax, shape_density_shcs_path=None, potential_shcs_path=None, shcs_file_format='tbl', encoding='utf-8', return_output=True)#

Performs cap-modified spectral gravity forward modelling of a laterally varying density. For more details, refer to charm_gfm.

The function input parameters are the same as in cap_density_3d(), with two exceptions.

Note

This function is available only if the --enable-mpfr flag is specified during the installation. See Installing.

Parameters:

density_shcs (Shc) – Spherical harmonic coefficients of the laterally varying mass density function.
density_nmax (integer) – Maximum harmonic degree, up to which the coefficients from density_shcs are used in forward modelling.

Returns:

out – List of pyharm.shc.Shc class instances with the spherical harmonic coefficients of the implied gravitational potential for radial_derivative_min (out[0]), …, radial_derivative_max (out[radial_derivative_max - radial_derivative_min]).

Return type:

list

pyharm.gfm.cap_density_const(shape_shcs, shape_nmax, shape_radius_ref, density, grav_const, mass, shape_power_min, shape_power_max, radial_derivative_min, radial_derivative_max, evaluation_spherical_radius, integration_radius, u, v, zone, nbits, potential_shcs_nmax, shape_shcs_powers_path=None, potential_shcs_path=None, shcs_file_format='tbl', encoding='utf-8', return_output=True)#

Performs cap-modified spectral gravity forward modelling of a constant mass density. For more details, refer to charm_gfm.

The function input parameters are the same as in cap_density_3d(), with two exceptions.

Note

This function is available only if the --enable-mpfr flag is specified during the installation. See Installing.

Parameters:

density (floating point) – Constant mass density.
shape_shcs_powers_path (str) –
Path to export spherical harmonic coefficients of the powers of the topographic height function. For more details, refer to charm_gfm.

Returns:

Return type:

list

pyharm.gfm.cap_q(shape_radius_ref, evaluation_spherical_radius, integration_radius, potential_shcs_nmax, shape_power_max, radial_derivative_min, radial_derivative_max, density_order, zone, q_type, nbits)#

Computes trunction coefficients pyharm.gfm.Q00, pyharm.gfm.Q10, pyharm.gfm.Q11, pyharm.gfm.Q20, pyharm.gfm.Q21, pyharm.gfm.Q22 that are used in spectral gravity forward modelling with spatially limited integration radius.

Tip

Use cap_q_check_prec() to determine the appropriate value of the input parameter nbits.

Note

The array returned is of the numpy.float64 data type (or numpy.float32 if compiled in single precision). Too challenging input parameters may lead to truncation coefficients that exceed the range of double (or single) precision. Some array elements may subsequently have the inf or -inf values. To avoid this, you can use the C API, which returns truncation coefficients as the mpfr_t data type, thereby eliminating the underflow and overflow issues.

Note

This function is available only if the --enable-mpfr flag is specified during the installation. See Installing.

Parameters:

shape_radius_ref (floating point) – Radius of the reference sphere.
evaluation_spherical_radius (floating point) – Spherical radius of the evaluation point.
integration_radius (floating point) – Integration radius in radians.
potential_shcs_nmax (integer) – Maximum spherical harmonic degree of the truncation coefficients.
shape_power_max (integer) – Maximum topography power of the truncation coefficients (must be larger than zero).
radial_derivative_min (integer) – Minimum radial derivative of the truncation coefficients.
radial_derivative_max (integer) – Maximum radial derivative of the truncation coefficients.
density_order (integer) – Maximum order of the polynomial density function.
zone (integer) – Non-negative integer for near-zone truncation coefficients or negative integer for far-zone truncation coefficients.
q_type (integer) – Type of the truncation coefficients (one of pyharm.gfm.Q00, pyharm.gfm.Q10, pyharm.gfm.Q11, pyharm.gfm.Q20, pyharm.gfm.Q21, pyharm.gfm.Q22).
nbits (integer) – Number of bits to represent the significand of all floating point numbers used to compute the truncation coefficients.

Returns:

out – The shape of the array is (radial_derivative_max - radial_derivative_min + 1, shape_power_max, density_order + 1, potential_shcs_nmax + 1). The coefficient for the k th radial derivative, p th topography power, i th density order and n th harmonic degree can be accessed as out[k - radial_derivative_min, p - 1, i, n].

Return type:

numpy array of floating points

pyharm.gfm.cap_nq(potential_shcs_nmax, shape_power_max, radial_derivative_min, radial_derivative_max, density_order)#

Returns the number of truncation coefficients qkpin computed by cap_q().

Note

This function is available only if the --enable-mpfr flag is specified during the installation. See Installing.

Parameters:

potential_shcs_nmax (integer) – Maximum spherical harmonic degree of the truncation coefficients.
shape_power_max (integer) – Maximum topography power of the truncation coefficients (must be larger than zero).
radial_derivative_min (integer) – Minimum radial derivative of the truncation coefficients.
radial_derivative_max (integer) – Maximum radial derivative of the truncation coefficients.
density_order (integer) – Maximum order of the polynomial density function.

Returns:

out – The number of truncation coefficients.

Return type:

integer

pyharm.gfm.cap_q_check_prec(shape_radius_ref, evaluation_spherical_radius, integration_radius, potential_shcs_nmax, shape_power_max, radial_derivative_min, radial_derivative_max, density_order, q_type, nbits, nbits_ref)#

Estimates the lowest number of correct digits of the sum of near- and far-zone truncation coefficients obtained by cap_q() when using the same input parameters. The uncertainty of the estimate is 1 digit. In case of an error, returned is a negative integer. For more details, refer to charm_gfm.

First, near- and far-zone truncation coefficients are computed and summed using the nbits precision. Then, reference coefficients from global spectral gravity forward modelling are evaluated using the nbits_ref precision. Finally, the sums are compared with respect to the reference values.

Tip

Use this function before calling cap_density_*() to check whether nbits that you enter to cap_density_*() is large enough to ensure accurate computation of truncation coefficients. The number returned by this function should be at least 7 or 16 for gravity forward modelling in single or double precision, respectively. Otherwise, increase nbits and nbits_ref until the desired accuracy is met. Once the value returned by this function is large enough, that particular (or higher) nbits can safely enter cap_density_*().

Note

If all sums of truncation coefficients are computed accurately to the last bit, returned is a large integer (LONG_MAX from limits.h). This may happen, for instance, if nmax is so small that all truncation coefficients of a given type are zero (e.g., nmax = 0 for type = CHARM_GFM_Q20).

Note

The number returned is related to the sum of near- and far-zone truncation coefficients. Usually, all near- and far-zone coefficients are more accurate than indicated by the returned value. Therefore, even a smaller value of nbits may suffice to get accurate outputs from charm_gfm_cap_density_*().

Note

This function is available only if the --enable-mpfr flag is specified during the installation. See Installing.

Parameters:

shape_radius_ref (floating point) – Radius of the reference sphere.
evaluation_spherical_radius (floating point) – Spherical radius of the evaluation point.
integration_radius (floating point) – Integration radius in radians.
potential_shcs_nmax (integer) – Maximum spherical harmonic degree of the truncation coefficients.
shape_power_max (integer) – Maximum topography power of the truncation coefficients (must be larger than zero).
radial_derivative_min (integer) – Minimum radial derivative of the truncation coefficients.
radial_derivative_max (integer) – Maximum radial derivative of the truncation coefficients.
density_order (integer) – Maximum order of the polynomial density function.
q_type (integer) – Type of the truncation coefficients (one of pyharm.gfm.Q00, pyharm.gfm.Q10, pyharm.gfm.Q11, pyharm.gfm.Q20, pyharm.gfm.Q21, pyharm.gfm.Q22).
nbits (integer) – Number of bits to represent the significand of all floating point numbers used to compute the truncation coefficients.
nbits_ref (integer) – Number of bits to represent the significand of all floating point numbers used to compute the reference values (cannot be smaller than nbits).

Returns:

out – The number of correct digits of the truncation coefficients when computed using the input parameters entered to this method. If the value returned is huge, more specifically, if the value is:

>>> import ctypes
>>> huge_val = ctypes.c_ulong(-1).value
>>> print(huge_val)

then the truncation coefficients are computed accurately to the last bit.

Return type:

integer

pyharm.gfm

Contents

pyharm.gfm#