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 thec
ands
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 \(\bar{C}_{00}\), \(\bar{C}_{10}\), …, \(\bar{C}_{\mathrm{nmax},0}\), \(\bar{C}_{1,1}\), …, \(\bar{C}_{\mathrm{nmax},\mathrm{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 thec
ands
input arrays. The copy is shallow, meaning that thec
ands
attributes of the returnedShc
class instance share the memory space with the inputc
ands
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:
- classmethod from_file(file_type, pathname, nmax, epoch=None)#
Reads spherical harmonic coefficients up to degree
nmax
from thepathname
file of a givenfile_type
. For time variable models stored in thegfc
file type,epoch
additionally transforms the coefficients to a given epoch.Tip
To get the maximum harmonic degree stored in
pathname
, usenmax_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 iffile_type
isgfc
. Default value isNone
.
- 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 degreenmax
to a filepathname
of a givenfile_type
. Iffile_type
represents a text file (dov
,tbl
ormtx
),formatting
specifies the formatting for all floating point numbers. Iffile_type
isdov
ortbl
,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
isdov
ortbl
, optional. Accepted values arepyharm.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 givenfile_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 \(\bar{C}_{nm}\) and \(\bar{S}_{nm}\) 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 \(\bar{C}_{nm}\) and \(\bar{S}_{nm}\), each of degreen
and orderm
. The two returned values are floating points.If
n
is integer andm
isNone
, returned are two arrays of spherical harmonic coefficients \(\bar{C}_{nm}\) and \(\bar{S}_{nm}\) of degreen
and all corresponding ordersm = 0, 1, ..., n
.If
n
isNone
andm
is integer, returned are two arrays of spherical harmonic coefficients \(\bar{C}_{nm}\) and \(\bar{S}_{nm}\) 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 \(\bar{C}_{nm}\) and \(\bar{S}_{nm}\) 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) \(\bar{C}_{nm}\) of degree
n
and orderm
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 orderm
to the values ofc
ands
, respectively.If both
n
andm
are integers, sets the spherical harmonic coefficients \(\bar{C}_{nm}\) and/or \(\bar{S}_{nm}\) to the input parametersc
and/ors
, respectively.c
ands
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 parametersc
and/ors
.c
ands
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 parametersc
and/ors
.c
ands
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) \(\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
ands
.
- rescale(mu=None, r=None)#
Rescales spherical harmonic coefficients to a new scaling parameter
mu
and/or a new radius of the reference spherer
.
- 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 degreenmax
.- Parameters:
- 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 degreenmax
.- Parameters:
- Returns:
out – A numpy floating point array with the difference degree amplitudes
- Return type:
numpy array of floating points