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: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 arraysc
ands
, each of shape(((nmax + 2) * (nmax + 1)) // 2,)
. For ordering scheme of the coefficients in the c and s arrays, see thec
ands
properties.
Note
Once an
Shc
class instance is created, its attributes are not writable. Ther
andmu
attributes can properly be changed by therescale()
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 to0.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 C0,0, C1,0, …, Cnmax,0, C1,1, C2,1, …, Cnmax,nmax.
- 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 deletesShc
class instances or when the instances get out of scope, etc. Theowner
attribute isTrue
forShc
instances returned by all factory methods except for thefrom_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 ofShc
class instances returned by thefrom_arrays()
factory method. This method buildsShc
instances from user-owned external numpy arrays, so it is the responsibility of the user to delete the original arrays (if needed) once theShc
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=1.0, r=1.0)#
Returns an
Shc
class instance with uninitialized spherical harmonic coefficients (malloc in C).
- classmethod from_zeros(nmax, mu=1.0, r=1.0)#
Returns an
Shc
class instance with all spherical harmonic coefficients initialized to zero (calloc in C).
- classmethod from_arrays(nmax, c, s, mu=1.0, r=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 thec
ands
attributes of the returnedShc
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 Cnm. For details on the structure of the array, see
c
.s (numpy array of floating points) – Spherical harmonic coefficients Snm. 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:
- classmethod from_file(file_type, pathname, nmax, epoch=None)#
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.
- Returns:
out – An
Shc
class instance- Return type:
- to_file(file_type, nmax, pathname, formatting='%0.16e', ordering=0)#
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.16e'
.ordering (integer) – Scheme to sort spherical harmonic coefficients when file_type is dov or tbl, optional. Accepted values are
pyharm.shc.WRITE_N
andpyharm.shc.WRITE_M
. Default ispyharm.shc.WRITE_N
.
- static get_file_types()#
Prints all file types supported by the
to_file()
andfrom_file()
methods of theShc
class.
- static nmax_from_file(file_type, pathname)#
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
- Returns:
out – Maximum harmonic degree of the model
- Return type:
integer
- get_coeffs(n=None, m=None)#
Returns spherical harmonic coefficients Cnm and Snm of degree
n
and orderm
. 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
andm
.If both
n
andm
are integers, returned are two spherical harmonic coefficients Cnm and Snm, each of degree n and order m. The two returned values are floating points.If
n
is integer andm
isNone
, returned are two arrays of spherical harmonic coefficients Cnm and Snm of degreen
and all corresponding ordersm = 0, 1, ..., n
.If
n
isNone
andm
is integer, returned are two arrays of spherical harmonic coefficients Cnm and Snm of orderm
and all corresponding degreesn = m, m + 1, ..., self.nmax
.If
n
andm
are lists of equal size, returned are two arrays of spherical harmonic coefficients Cnm and Snm of degrees taken from then
list and orders taken from them
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) Cnm of degree n and order m
s (floating point, numpy array of floating points) – The same as c but with the Snm coefficient(s)
- set_coeffs(n=None, m=None, c=None, s=None)#
Sets spherical harmonic coefficients Cnm and Snm of degree n and order m to the values of c and s, respectively.
If both
n
andm
are integers, sets the spherical harmonic coefficients Cnm and/or Snm to the input parameters c and/or s, respectively. c and s must be floating point scalars.If
n
is integer andm
isNone
, sets spherical harmonic coefficients of degreen
and all corresponding harmonic ordersm = 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
isNone
andm
is integer, sets spherical harmonic coefficients of orderm
and all corresponding harmonic degreesn = 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
andm
are lists of equal size, sets spherical spherical harmonic coefficients of degrees and orders taken from then
andm
lists, respectively, to the corresponding values taken from the input parametersc
and/ors
. The length of the input parameters must match.
Note
If the object’s
owner
attribute isTrue
, the copy of the new coefficients is deep. Ifowner
isFalse
, 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) Cnm, optional.
s (floating point, numpy array of floating points, None) – Spherical harmonic coefficient(s) Snm, optional.
- 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.
- 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
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
andshcs.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