lenapy.writers.gravi_writer

The gravi_writer module provides writer functions to save Spherical Harmonics dataset in .gfc ascii file.

lenapy.writers.gravi_writer.dataset_to_gfc(ds: Dataset, filename: str | PathLike, overwrite: bool = True, include_errors: bool = False, fmt: str = ' .12e', fast_save: bool = False, **kwargs) → None[source]

Save a Spherical Harmonics xr.Dataset to a .gfc ASCII file according to the ICGEM format specifications: https://icgem.gfz-potsdam.de/docs/ICGEM-Format-2023.pdf If the dataset contains additional dimensions beyond ‘l’ and ‘m’, raise error if the size of these dimensions exceed 1. The saving time for degree maximum of 60 is around 10 seconds. If the given l and m dimensions are continuous (from 0 to lmax/mmax), this saving time can be reduced under 100ms with argument fast_save=True.

Parameters:

  • ds (xr.Dataset) – The dataset to be saved.

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

  • overwrite (bool, optional) – If True, overwrite the existing file. Default is True.

  • include_errors (bool, optional) – If True, include error coefficients in the dataset. Default is False.

  • fmt (str, optional) – The format specifier for clm, slm and errors values to save. Default is ‘ .12e’.

  • fast_save (bool, optional) – If True, assume that ‘l’ and ‘m’ dimensions are continuous (from 0 to lmax/mmax) to reduce saving time. Default is False.

  • **kwargs (optional) – Additional .gfc attributes to be included in the .gfc file header.

Return type:

None

Examples

>>> ds = xr.open_dataset('example_file.nc')
# Saving a basic dataset without error coefficients and without fast saving:
>>> dataset_to_gfc(ds, 'output_file.gfc')
# Saving a dataset with error coefficients included:
>>> dataset_to_gfc(ds, 'output_file_with_errors.gfc', include_errors=True)
# Using `fast_save` for a dataset with 'l' and 'm' dimensions that goes continuously from 0 to lmax/mmax:
>>> dataset_to_gfc(ds, 'fast_save_file.gfc', fast_save=True)
# Adding custom attributes that are not in ds.attrs to the .gfc file header:
>>> dataset_to_gfc(ds, 'custom_attrs_file.gfc', modelname='My_Model_Name', tide_system='tide_free')