pyharm.shc

pyharm.shc#

Module to work with spherical harmonic coefficients. Defines the Shc class, including its methods that are designed to:

read/write spherical harmonic coefficients,

rescale spherical harmonic coefficients, and

compute (difference) degree variances and amplitudes.

Note

This documentation is written for double precision version of PyHarm.

pyharm.shc.WRITE_N: int = 0#

Ordering scheme to write spherical harmonic coefficients with the pyharm.shc.Shc.to_file() method: harmonic degree varies fastest.

Type:: int

pyharm.shc.WRITE_M: int = 1#

Ordering scheme to write spherical harmonic coefficients with the pyharm.shc.Shc.to_file() method: harmonic order varies fastest.

Type:: int

class pyharm.shc.Shc(nmax, mu, r, coeffs)#

Class for spherical harmonic coefficients.

To create an Shc class instance, always use one of the following factory methods:

from_garbage(),

from_zeros(),

from_arrays(),

from_file().

Examples

>>> import pyharm as ph
>>> shcs = ph.shc.Shc.from_garbage(10)

Parameters:

nmax (integer) – Maximum spherical harmonic degree
mu (floating point) – Scaling parameter
r (floating point) – Radius of the reference sphere
coeffs (None, 0 or tuple) –
Determines the way of initializing spherical harmonic coefficients:
- None to not initialize spherical harmonic coefficients (malloc in C),
- 0 to set all spherical harmonic coefficients to zero (calloc in C),
- (c, s) to define spherical harmonic coefficients based on two numpy floating point arrays c and s, each of shape (((nmax + 2) * (nmax + 1)) // 2,). For ordering scheme of the coefficients in the c and s arrays, see the c and s properties.

Note

Once an Shc class instance is created, its attributes are not writable. The r and mu attributes can properly be changed by the rescale() method.

property nmax#: Maximum harmonic degree of the spherical harmonic coefficients.

property mu#: Scaling parameter \(\mu\) associated with the spherical harmonic coefficients, for instance, the geocentric gravitational constant. In case the coefficients are not associated with any scaling parameter (as it is, for instance, with planetary topographies), simply set this variable to 1.0 (not to 0.0!).

property r#: Radius of the reference sphere \(R\), to which the spherical harmonic coefficients refer (are scaled). The value must be greater than zero. To get the unit sphere, as needed, for instance, when working with planetary topographies, set this variable to 1.0.

property c#: The \(\bar{C}_{nm}\) spherical harmonic coefficients. A numpy array with the shape (((nmax + 2) * (nmax + 1)) / 2,) and the array structure \(\bar{C}_{00}\), \(\bar{C}_{10}\), …, \(\bar{C}_{\mathrm{nmax},0}\), \(\bar{C}_{1,1}\), …, \(\bar{C}_{\mathrm{nmax},\mathrm{nmax}}\).

property s#: The same as c but for the \(\bar{S}_{nm}\) spherical harmonic coefficients.

property owner#

If True, the memory associated with spherical harmonic coefficients is owned by CHarm and therefore it is automatically deallocated by CHarm when the user deletes Shc class instances or when the instances get out of scope, etc. The owner attribute is True for Shc instances returned by all factory methods except for the from_arrays() method.

Examples
```
>>> import pyharm as ph
>>> shcs = ph.shc.Shc.from_garbage(10)
>>> del shcs # Deletes "shcs" and properly deallocates all memory
>>>          # that is associated with "shcs"
```

If False, neither CHarm nor PyHarm own the memory so neither CHarm nor PyHarm will ever deallocate it. This is the case of Shc class instances returned by the from_arrays() factory method. This method builds Shc instances from user-owned external numpy arrays, so it is the responsibility of the user to delete the original arrays (if needed) once the Shc class instance is deleted or got out of scope, etc.

Examples

>>> import numpy as np
>>> import pyharm as ph
>>> nmax = 10
>>> ncs = ((nmax + 2) * (nmax + 1)) // 2
>>> c = np.random.randn(ncs)
>>> s = np.random.randn(ncs)
>>> shcs = ph.shc.Shc.from_arrays(nmax, c, s)
>>> del shcs # Deletes "shcs" but not the original "c" and "s" arrays
>>> # Here, you can still work with "c" and "s"
>>> del c, s # Finally, release the memory associated with "c" and
>>>          # "s" if needed

classmethod from_garbage(nmax, mu=np.float64(1.0), r=np.float64(1.0))#

Returns an Shc class instance with uninitialized spherical harmonic coefficients (malloc in C).

Parameters:

nmax (integer) – Maximum spherical harmonic degree
mu (floating point) – Scaling parameter, optional. Default is 1.0.
r (floating point) – Radius of the reference sphere, optional. Default is 1.0.

Returns:

out – An Shc class instance

Return type:

Shc

classmethod from_zeros(nmax, mu=np.float64(1.0), r=np.float64(1.0))#

Returns an Shc class instance with all spherical harmonic coefficients initialized to zero (calloc in C).

Parameters:

nmax (integer) – Maximum spherical harmonic degree
mu (floating point) – Scaling parameter, optional. Default is 1.0.
r (floating point) – Radius of the reference sphere, optional. Default is 1.0.

Returns:

out – An Shc class instance

Return type:

Shc

classmethod from_arrays(nmax, c, s, mu=np.float64(1.0), r=np.float64(1.0))#

Returns an Shc class instance with spherical harmonic coefficients copied from the c and s input arrays. The copy is shallow, meaning that the c and s attributes of the returned Shc class instance share the memory space with the input c and s arrays.

Parameters:

nmax (integer) – Maximum spherical harmonic degree
c (numpy array of floating points) – Spherical harmonic coefficients \(\bar{C}_{nm}\). For details on the structure of the array, see c.
s (numpy array of floating points) – Spherical harmonic coefficients \(\bar{S}_{nm}\). For details on the structure of the array, see s.
mu (floating point) – Scaling parameter, optional. Default is 1.0.
r (floating point) – Radius of the reference sphere, optional. Default is 1.0.

Returns:

out – An Shc class instance

Return type:

Shc

classmethod from_file(file_type, pathname, nmax, epoch=None, encoding='utf-8')#

Reads spherical harmonic coefficients up to degree nmax from the pathname file of a given file_type. For time variable models stored in the gfc file type, epoch additionally transforms the coefficients to a given epoch.

Tip

To get the maximum harmonic degree stored in pathname, use nmax_from_file().

Tip

To print all supported file types, use get_file_types():

>>> import pyharm as ph
>>> ph.shc.Shc.get_file_types()

For the structure of the file types, refer to charm_shc.

Parameters:

file_type (str) – Type of the input file
pathname (str) – Input file path
nmax (integer) – Maximum harmonic degree to read the spherical harmonic coefficients
epoch (str) –
Epoch, to which spherical harmonic coefficients from gfc file types are transformed in case of time variable gravity field models; optional. For the structure of the string, refer to charm_shc. This input parameter is used only if file_type is gfc. Default value is None.
encoding (str) –
Encoding of the pathname and epoch strings. In case you have special characters in your pathname string, you may need to select proper encoding.

The encoding does not apply to the content of the file. The file reading is done by CHarm, so the file content encoding depends on your operating system.

Returns:

out – An Shc class instance

Return type:

Shc

to_file(file_type, nmax, pathname, formatting='%0.18e', ordering=0, encoding='utf-8')#

Writes an Shc class instance up to degree nmax to a file pathname of a given file_type. If file_type represents a text file (dov, tbl or mtx), formatting specifies the formatting for all floating point numbers. If file_type is dov or tbl, ordering defines the ordering of spherical harmonic coefficients in the output file.

Tip

To print all supported file types, use get_file_types():

>>> import pyharm as ph
>>> ph.shc.Shc.get_file_types()

For the structure of the file types, refer to charm_shc.

Parameters:

file_type (str) – Type of the input file
nmax (integer) – Maximum harmonic degree to write the spherical harmonic coefficients
pathname (str) – Output file path
formatting (str) – Formatting to write floating point numbers to text formats, optional. Default is '%0.18e'.
ordering (integer) – Scheme to sort spherical harmonic coefficients when file_type is dov or tbl, optional. Accepted values are pyharm.shc.WRITE_N and pyharm.shc.WRITE_M. Default is pyharm.shc.WRITE_N.
encoding (str) –
Encoding of the pathname and formatting strings. In case you have special characters in your pathname string, you may need to select proper encoding.

The encoding does not apply to the content of the file. The file writting is done by CHarm, so the file content encoding depends on your operating system.

static get_file_types()#: Prints all file types supported by the to_file() and from_file() methods of the Shc class.

static nmax_from_file(file_type, pathname, encoding='utf-8')#

Returns the maximum harmonic degree of coefficients stored in the pathname file that is of a given file_type.

Tip

Use this method to get the maximum degree of spherical harmonic coefficients stored in a file and then load the file up to its maximum harmonic degree:

>>> import pyharm as ph
>>> path = '/some/path/to/gfc'
>>> nmax = ph.shc.Shc.nmax_from_file('gfc', path)
>>> shcs = ph.shc.Shc.from_file('gfc', path, nmax)

Tip

To print all supported file types, use get_file_types():

>>> import pyharm as ph
>>> ph.shc.Shc.get_file_types()

For the structure of the file types, refer to charm_shc.

Parameters:

file_type (str) – Type of the input file
pathname (str) – Input file path
encoding (str) –
Encoding of the pathname string. In case you have special characters in your pathname string, you may need to select proper encoding.

The encoding does not apply to the content of the input file. The file reading is done by CHarm, so the file content encoding depends on your operating system.

Returns:

out – Maximum harmonic degree of the model

Return type:

integer

get_coeffs(n=None, m=None)#

Returns spherical harmonic coefficients \(\bar{C}_{nm}\) and \(\bar{S}_{nm}\) of degree n and order m. If the returned variables are arrays, these are deep copies, meaning that the arrays have their own memory space.

The behaviour of the method depends on the type of the input variables n and m.

If both n and m are integers, returned are two spherical harmonic coefficients \(\bar{C}_{nm}\) and \(\bar{S}_{nm}\), each of degree n and order m. The two returned values are floating points.
If n is integer and m is None, returned are two arrays of spherical harmonic coefficients \(\bar{C}_{nm}\) and \(\bar{S}_{nm}\) of degree n and all corresponding orders m = 0, 1, ..., n.
If n is None and m is integer, returned are two arrays of spherical harmonic coefficients \(\bar{C}_{nm}\) and \(\bar{S}_{nm}\) of order m and all corresponding degrees n = m, m + 1, ..., self.nmax.
If n and m are lists of equal size, returned are two arrays of spherical harmonic coefficients \(\bar{C}_{nm}\) and \(\bar{S}_{nm}\) of degrees taken from the n list and orders taken from the m list.

Note

When the method returns numpy arrays, the output arrays are always deep copies of the original spherical harmonic coefficients.

Examples

>>> import numpy as np
>>> import pyharm as ph
>>> nmax = 10
>>> ncs = ((nmax + 2) * (nmax + 1)) // 2
>>> c = np.random.randn(ncs)
>>> s = np.random.randn(ncs)
>>> shcs = ph.shc.Shc.from_arrays(nmax, c, s)
>>> shcs.get_coeffs(3, 2) # Returns "C3,2" and "S3,2"
>>> shcs.get_coeffs(n=3) # Returns "C3,0", "C3,1", "C3,2", "C3,3" and
>>>                      # "S3,0", "S3,1", "S3,2", "S3,3"
>>> shcs.get_coeffs(m=8) # Returns "C8,8", "C9,8", "C10,8" and
>>>                      # "S8,8", "S9,8", "S10,8"
>>> n = [3, 5, 6]
>>> m = [2, 4, 6]
>>> shcs.get_coeffs(n, m) # Returns "C3,2", "C5,4", "C6,6" and "S3,2",
>>>                       # "S5,4", "S6,6"

Parameters:

n (integer, list of integers, None) – Spherical harmonic degree, optional.
m (integer, list of integers, None) – Spherical harmonic order, optional.

Returns:

c (floating point, numpy array of floating points) – Spherical harmonic coefficient(s) \(\bar{C}_{nm}\) of degree n and order m
s (floating point, numpy array of floating points) – The same as c but with the \(\bar{S}_{nm}\) coefficient(s)

set_coeffs(n=None, m=None, c=None, s=None)#

Sets spherical harmonic coefficients \(\bar{C}_{nm}\) and \(\bar{S}_{nm}\) of degree n and order m to the values of c and s, respectively.

If both n and m are integers, sets the spherical harmonic coefficients \(\bar{C}_{nm}\) and/or \(\bar{S}_{nm}\) to the input parameters c and/or s, respectively. c and s must be floating point scalars.
If n is integer and m is None, sets spherical harmonic coefficients of degree n and all corresponding harmonic orders m = 0, 1, ..., n to the input parameters c and/or s. c and s must be numpy floating point arrays of shapes (n + 1,).
If n is None and m is integer, sets spherical harmonic coefficients of order m and all corresponding harmonic degrees n = m, m + 1, ..., self.nmax to the input parameters c and/or s. c and s must be numpy floating point arrays of shapes (self.nmax + 1 - m,).
If n and m are lists of equal size, sets spherical spherical harmonic coefficients of degrees and orders taken from the n and m lists, respectively, to the corresponding values taken from the input parameters c and/or s. The length of the input parameters must match.

Note

If the object’s owner attribute is True, the copy of the new coefficients is deep. If owner is False, the copy is shallow.

Examples

>>> import numpy as np
>>> import pyharm as ph
>>> nmax = 10
>>> ncs = ((nmax + 2) * (nmax + 1)) // 2
>>> c = np.random.randn(ncs)
>>> s = np.random.randn(ncs)
>>> shcs = ph.shc.Shc.from_arrays(nmax, c, s)
>>> # Set "C3,2" and "S3,2"
>>> shcs.set_coeffs(3, 2, 3.4, 1.3)
>>> # Set "S3,2"
>>> shcs.set_coeffs(3, 2, s=5.3)
>>> # Set "C3,0", "C3,1", "C3,2", "C3,3" and "S3,0", "S3,1", "S3,2",
>>> #"S3,3"
>>> shcs.set_coeffs(n=3, c=np.array([1.1, 1.2, 1.3, 1.4]),
>>>                      s=np.array([0.0, 1.2, 1.3, 1.4]))
>>>  # Set "C8,8", "C9,8", "C10,8" and "S8,8", "S9,8", "S10,8"
>>> shcs.set_coeffs(m=8, c=np.array([1.1, 1.2, 1.3]),
>>>                      s=np.array([1.1, 1.2, 1.3]))
>>>  # Set "C3,2", "C5,4", "C6,6" and "S3,2", "S5,4", "S6,6"
>>> shcs.set_coeffs(n=[3, 5, 6], m=[2, 4, 6],
>>>                 c=np.array([1.1, 1.2, 1.3]),
>>>                 s=np.array([1.1, 1.2, 1.3]))

Parameters:

n (integer, list of integers, None) – Spherical harmonic degree, optional.
m (integer, list of integers, None) – Spherical harmonic order, optional.
c (floating point, numpy array of floating points, None) – Spherical harmonic coefficient(s) \(\bar{C}_{nm}\), optional.
s (floating point, numpy array of floating points, None) – Spherical harmonic coefficient(s) \(\bar{S}_{nm}\), optional.

get_degrees_orders()#

Returns arrays of spherical harmonic degrees and orders matching the spherical harmonic coefficients stored in c and s.

Returns:

degrees (numpy array of numpy.uint) – Array of spherical harmonic degrees matching the coefficients in c and s.
orders (numpy array of numpy.uint) – Array of spherical harmonic orders matching the coefficients in c and s.

rescale(mu=None, r=None)#

Rescales spherical harmonic coefficients to a new scaling parameter mu and/or a new radius of the reference sphere r.

Parameters:

mu (floating point) – New scaling parameter, optional. If not provided, the mu attribute is not changed.
r (floating point) – New radius of the reference sphere, optional. If not provided, the r attribute is not changed.

dv(nmax=None)#

Computes degree variances up to degree nmax.

Parameters:: nmax (integer) – Maximum spherical harmonic degree to compute the degree variances, optional. If not provided, it will be set to the object’s nmax.
Returns:: out – A numpy floating point array with the degree variances
Return type:: numpy array of floating points

da(nmax=None)#

Computes degree amplitudes up to degree nmax.

Parameters:: nmax (integer) – Maximum spherical harmonic degree to compute the degree amplitudes, optional. If not provided, it will be set to self.nmax.
Returns:: out – A numpy floating point array with the degree amplitudes
Return type:: numpy array of floating points

ddv(shcs, nmax=None)#

Computes difference degree variances with respect to shcs up to degree nmax.

Parameters:

shcs (Shc) – An instance of the Shc class.
nmax (integer) – Maximum spherical harmonic degree to compute the degree variances, optional. If not provided, nmax is set to the smallest of self.nmax and shcs.nmax.

Returns:

out – A numpy floating point array with the difference degree variances

Return type:

numpy array of floating points

dda(shcs, nmax=None)#

Computes difference degree amplitudes with respect to shcs up to degree nmax.

Parameters:

shcs (Shc) – An instance of the Shc class.
nmax (integer) – Maximum spherical harmonic degree to compute the degree amplitudes, optional. If not provided, nmax is set to the smallest of self.nmax and shcs.nmax.

Returns:

out – A numpy floating point array with the difference degree amplitudes

Return type:

numpy array of floating points

pyharm.shc

Contents

pyharm.shc#