lenapy.lenapy_harmo

The lenapy_harmo module provides functionalities for spherical harmonics dataset (clm/slm) and projections on latitude/longitude grids.

This module includes two classes:

  • HarmoSet: Provides methods for handling spherical harmonics decompositions, converting them to grid representations and performing operations such as changing reference frames and tide systems.

  • HarmoArray: Converts grid representation of a spherical harmonics dataset back to spherical harmonics.

The module is designed to work seamlessly with xarray datasets, enabling efficient manipulation and visualization.

Examples

>>> import xarray as xr
>>> from lenapy import lenapy_harmo
# Load a dataset from a .gfc file
>>> ds = xr.open_dataset('example_file.gfc', engine='lenapyGfc')
# Access HarmoSet methods
>>> grid = ds.lnharmo.to_grid()
# Plot the spherical harmonics
>>> ds.lnharmo.plot_hs()
class lenapy.lenapy_harmo.HarmoSet(xarray_obj)[source]

Bases: object

This class implements an extension of any xr.Dataset to add some methods related to spherical harmonics decomposition. The initial dataset must contain the necessary fields to define the spherical harmonics properties.

Standardized coordinates names:

  • l, m (optional: time)

Standardized variables names:

  • clm, slm (optional: eclm, eslm, begin_time, end_time, exact_time)

Initialize the HarmoSet accessor.

Parameters:

xarray_obj (xr.Dataset) – Input dataset

to_grid(**kwargs) → DataArray[source]

Transform Spherical Harmonics (SH) dataset into spatial DataArray. For details on the function, see lenapy.utils.harmo.sh_to_grid() documentation.

Parameters:

**kwargs – Supplementary parameters used by the function sh_to_grid() for conversion between SH and grid

Returns:

The spatial grid representation of the spherical harmonics dataset.

Return type:

xr.DataArray

change_reference(new_radius: float, new_earth_gravity_constant: float, old_radius: float | None = None, old_earth_gravity_constant: float | None = None, apply: bool = False) → Dataset[source]

Update the reference frame for spherical harmonics. For details on the function, see lenapy.utils.gravity.change_reference() documentation.

Parameters:

  • new_radius (float) – New Earth radius constant in meters.

  • new_earth_gravity_constant (float) – New gravitational constant of the Earth in m³/s².

  • old_radius (float | None, optional) – Current Earth radius constant of the dataset in meters. If not provided, uses ds.attrs[‘radius’].

  • old_earth_gravity_constant (float | None, optional) – Current gravitational constant of the Earth of the dataset in m³/s². If not provided, uses ds.attrs[‘earth_gravity_constant’].

  • apply (bool, optional) – If True, apply the update to the current dataset without making a deep copy. Default is False.

Returns:

ds_out – Updated dataset with the new constants.

Return type:

xr.Dataset

change_tide_system(new_tide: Literal['tide_free', 'zero_tide', 'mean_tide'], old_tide: Literal['tide_free', 'zero_tide', 'mean_tide'] | None = None, k20: float | None = None, apply: bool = False) → Dataset[source]

Apply a C20 offset to the dataset to change the tide system. For details on the function, see lenapy.utils.gravity.change_tide_system() documentation.

Parameters:

  • new_tide (str) – Output tidal system, either ‘tide_free’, ‘zero_tide’ or ‘mean_tide’.

  • old_tide (str | None, optional) – Input tidal system. If not provided, uses ds.attrs[‘tide_system’].

  • k20 (float | None, optional) – k20 Earth tide external potential Love number. If not provided, the default value from IERS2010 is used.

  • apply (bool, optional) – If True, apply the update to the current dataset without making a deep copy. Default is False.

Returns:

ds_out – Updated dataset with the new tidal system.

Return type:

xr.Dataset

change_normalization(new_normalization: Literal['4pi', 'ortho', 'schmidt'] = '4pi', old_normalization: Literal['4pi', 'ortho', 'schmidt'] | None = None, apply: bool = False) → Dataset[source]

Apply a C20 offset to the dataset to change the tide system. For details on the function, see lenapy.utils.gravity.change_tide_system() documentation.

Parameters:

  • new_normalization (str) – New normalization for the SH dataset, either ‘4pi’, ‘ortho’, or ‘schmidt’.

  • old_normalization (str | None, optional) –

    Current normalization of the SH dataset, either ‘4pi’, ‘ortho’, ‘schmidt’, or ‘unnorm’.

    If not provided, uses ds.attrs[‘norm’].

  • apply (bool, optional) – If True, apply the update to the current dataset without making a deep copy. Default is False.

Returns:

ds_out – Updated dataset with the new normalization.

Return type:

xr.Dataset

apply_normal_zonal_correction(**kwargs) → Dataset[source]

Apply a correction of the normal gravity field on zonal coefficients on a SH dataset. For details on the function, see lenapy.utils.gravity.apply_normal_zonal_correction() documentation.

Parameters:

**kwargs – Supplementary parameters used by the function apply_normal_zonal_correction()

Returns:

ds_out – Updated dataset with the correction.

Return type:

xr.Dataset

plot_hs(**kwargs)[source]

Plot time series of spherical harmonics. For details on the function, see lenapy.plots.plotting.plot_hs() documentation.

Parameters:

**kwargs – Additional parameters to customize the plot.

Returns:

The generated plot of the spherical harmonics.

Return type:

matplotlib.figure.Figure

plot_power(**kwargs)[source]

Plot the power of the spherical harmonics. For details on the function, see lenapy.plots.plotting.plot_power_hs() documentation.

Parameters:

**kwargs – Additional parameters to customize the plot.

Returns:

The generated plot of the power of the spherical harmonics.

Return type:

matplotlib.figure.Figure

to_gfc(filename: str | PathLike, **kwargs)[source]

Save the dataset to a .gfc file. For details on the function, see lenapy.writers.gravi_writer.dataset_to_gfc() documentation.

Parameters:

  • filename (str | os.PathLike) – The file path where to save the dataset.

  • **kwargs – Additional parameters for the .gfc file.

class lenapy.lenapy_harmo.HarmoArray(xarray_obj)[source]

Bases: object

This class implements an extension of any xr.DataArray to add some methods related to spatial grids representing spherical harmonics projected onto a grid. The initial dataset must contain the necessary fields to define the spherical harmonics properties.

Initialize the HarmoArray accessor

Parameters:

xarray_obj (xr.DataArray) – Input dataarray

to_sh(lmax: int, **kwargs) → Dataset[source]

Transform gravity field spatial representation DataArray into Spherical Harmonics (SH) dataset. For details on the function, see lenapy.utils.harmo.grid_to_sh() documentation.

Parameters:

  • lmax (int) – Maximal degree of the SH coefficients to be computed.

  • **kwargs – Supplementary parameters used by the function grid_to_sh() for conversion between grid and SH

Return type:

Dataset