API Documentation

class ggcmpy.openggcm.AmieTimeArrayCoder(use_cftime=None)

A custom coder for encoding and decoding time arrays in xarray Variables. This class extends the CFDatetimeCoder to handle variables with a custom “time_array” encoding, and otherwise falls back to the usual CF coding/encoding.

encode(variable: xr.Variable, name: Hashable | None = None) → xr.Variable

Encodes an xarray Variable with a “time_array” unit into a custom format.

decode(variable: xr.Variable, name: Hashable | None = None) → xr.Variable

Decodes an xarray Variable with a “time_array” unit from a custom format.

Parameters:

use_cftime (bool | None)

decode(variable, name=None)

Convert a decoded variable to an encoded variable

Parameters:

• variable (Variable)

• name (Hashable | None)

Return type:

Variable

encode(variable, name=None)

Convert an encoded variable to a decoded variable

Parameters:

• variable (Variable)

• name (Hashable | None)

Return type:

Variable

class ggcmpy.openggcm.OpenGGCMAccessor(xarray_obj)

Xarray accessor to add OpenGGCM-specific features

As of now, that is ds.ggcm.coords which provides mlts and colats.

Parameters:

xarray_obj (Any)

cl_index()

Calculate the CL index from an iof dataset.

Returns:

CL index as a DataArray.

Return type:

xarray.DataArray

property coords: Coordinates

cpcp()

Calculate Cross Polar Cap Potential (CPCP) from an iof dataset.

Returns:

Cross Polar Cap Potential (CPCP) as a DataArray.

Return type:

xarray.DataArray

plot(lats_max=90, lats_min=50, spacing=10, mlt=True, **kwargs)

Parameters:

• lats_max (int)

• lats_min (int)

• spacing (int)

• mlt (bool)

• kwargs (Any)

Return type:

None

ggcmpy.openggcm.cl_index(iof)

Calculate the CL index from an iof dataset.

Parameters:

iof (xarray.Dataset) – Input iof dataset – needs to contain ‘bfield’ variable.

Returns:

CL index as a DataArray.

Return type:

xarray.DataArray

ggcmpy.openggcm.cotr(date, cfr, cto, r1)

Transform coordinates between different coordinate systems.

This function wraps the Fortran routine cotr() in the f2py module ggcmpy._jrrle.f2py. takes vector r1 in coordinate system ‘cfr’ and returns the corresponding vector in coordinate system ‘cto’

Coordinate systems ‘cfr’ and ‘cto’ can be any of the following: ‘gei’ : geocentric equatorial inertial ‘geo’ : geographic ‘gse’ : geocentric solar ecliptic ‘gsm’ : geocentric solar magnetospheric ‘sm ‘ : solar magnetic ‘mag’ : geomagnetic ‘mhd’ : global mhd simulation system, like ‘gse’ with

x and y axes mirrored

Parameters:

• date (np.datetime64) – The datetime at which to perform the transformation.

• cfr (str) – The coordinate system of the input coordinates.

• cto (str) – The coordinate system of the output coordinates.

• r1 (ArrayLike) – The input coordinates to transform. This should be a 1D array-like of length 3.

Returns:

The transformed coordinates as a numpy array of shape (3,).

Return type:

NDArray[Any]

ggcmpy.openggcm.cpcp(iof)

Calculate Cross Polar Cap Potential (CPCP) from an iof dataset.

Parameters:

iof (xarray.Dataset) – Input iof dataset – needs to contain ‘pot’ variable.

Returns:

Cross Polar Cap Potential (CPCP) as a DataArray.

Return type:

xarray.DataArray

ggcmpy.openggcm.decode_openggcm(ds)

Parameters:

ds (Dataset)

Return type:

Dataset

ggcmpy.openggcm.encode_openggcm(variables, attributes)

Parameters:

• variables (Mapping[str, Variable])

• attributes (Mapping[str, Any])

Return type:

tuple[Mapping[str, Variable], Mapping[str, Any]]

ggcmpy.openggcm.epoch1966(dt64)

Convert a numpy datetime64 to seconds since 1966-01-01T00:00:00.

This is the time representation used in OpenGGCM, and is implemented here via the Fortran routine epoch1966() in the f2py module ggcmpy._jrrle.f2py.

Parameters:

• dt (np.datetime64) – The datetime to convert.

• dt64 (datetime64)

Returns:

The number of seconds since 1966-01-01T00:00:00.

Return type:

float

ggcmpy.openggcm.parse_timestring(timestr)

Parameters:

timestr (str)

Return type:

dict[str, Any]

ggcmpy.openggcm.read_grid(filename)

Parameters:

filename (PathLike[Any] | str)

Return type:

dict[str, ndarray[tuple[Any, ...], dtype[Any]]]

ggcmpy.openggcm.read_grid2(filename)

Parameters:

filename (PathLike[Any] | str)

Return type:

dict[str, ndarray[tuple[Any, ...], dtype[Any]]]

ggcmpy.openggcm.timearray_to_dt64(time)

Parameters:

time (ndarray[tuple[Any, ...], dtype[Any]])

Return type:

datetime64