spacepy.pycdf.Library

class spacepy.pycdf.Library(libpath=None, library=None)[source]

Abstraction of the base CDF C library and its state.

Not normally intended for end-user use. An instance of this class is created at package load time as the lib variable, providing access to the underlying C library if necessary. The CDF library itself is described in section 2.1 of the CDF user’s guide, as well as the CDF C reference manual.

Calling the C library directly requires knowledge of ctypes.

Instantiating this object loads the C library, see pycdf - Python interface to CDF files docs for details.

call(*args, **kwargs)

Call the CDF internal interface

check_status(status[, ignore])

Raise exception or warning based on return status of CDF call

datetime_to_epoch(dt)

Converts a Python datetime to a CDF Epoch value

datetime_to_epoch16(dt)

Converts a Python datetime to a CDF Epoch16 value

datetime_to_tt2000(dt)

Converts a Python datetime to a CDF TT2000 value

epoch_to_datetime(epoch)

Converts a CDF epoch value to a datetime

epoch_to_epoch16(epoch)

Converts a CDF EPOCH to a CDF EPOCH16 value

epoch_to_num(epoch)

Convert CDF EPOCH to matplotlib number.

epoch_to_tt2000(epoch)

Converts a CDF EPOCH to a CDF TT2000 value

epoch16_to_datetime(epoch0, epoch1)

Converts a CDF epoch16 value to a datetime

epoch16_to_epoch(epoch16)

Converts a CDF EPOCH16 to a CDF EPOCH value

epoch16_to_tt2000(epoch0, epoch1)

Converts a CDF epoch16 value to TT2000

get_minmax(cdftype)

Find minimum, maximum possible value based on CDF type.

set_backward([backward])

Set backward compatibility mode for new CDFs

tt2000_to_datetime(tt2000)

Converts a CDF TT2000 value to a datetime

tt2000_to_epoch(tt2000)

Converts a CDF TT2000 value to a CDF EPOCH

tt2000_to_epoch16(tt2000)

Converts a CDF TT2000 value to a CDF EPOCH16

call(*args, **kwargs)[source]

Call the CDF internal interface

Passes all parameters directly through to the CDFlib routine of the CDF library’s C internal interface. Checks the return value with check_status().

Terminal NULL is automatically added to args.

Parameters
argsvarious, see ctypes

Passed directly to the CDF library interface. Useful constants are defined in the const module.

Returns
outint

CDF status from the library

Other Parameters
ignoresequence of CDF statuses

sequence of CDF statuses to ignore. If any of these is returned by CDF library, any related warnings or exceptions will not be raised.

Raises
CDFErrorif CDF library reports an error
Warns
CDFWarningif CDF library reports a warning
check_status(status, ignore=())[source]

Raise exception or warning based on return status of CDF call

Parameters
statusint

status returned by the C library

Returns
outint

status (unchanged)

Other Parameters
ignoresequence of ctypes.c_long

CDF statuses to ignore. If any of these is returned by CDF library, any related warnings or exceptions will not be raised. (Default none).

Raises
CDFErrorif status < CDF_WARN, indicating an error
Warns
CDFWarningif CDF_WARN <= status < CDF_OK, indicating a warning.
datetime_to_epoch(dt)[source]

Converts a Python datetime to a CDF Epoch value

Parameters
dtdatetime.datetime

date and time to convert

Returns
outfloat

epoch corresponding to dt

datetime_to_epoch16(dt)[source]

Converts a Python datetime to a CDF Epoch16 value

Parameters
dtdatetime.datetime

date and time to convert

Returns
outlist of float

epoch16 corresponding to dt

datetime_to_tt2000(dt)[source]

Converts a Python datetime to a CDF TT2000 value

Parameters
dtdatetime.datetime

date and time to convert

Returns
outint

tt2000 corresponding to dt

epoch_to_datetime(epoch)[source]

Converts a CDF epoch value to a datetime

Parameters
epochfloat

epoch value from CDF

Returns
outdatetime.datetime

date and time corresponding to epoch. Invalid values are set to usual epoch invalid value, i.e. last moment of year 9999.

epoch_to_epoch16(epoch)[source]

Converts a CDF EPOCH to a CDF EPOCH16 value

Parameters
epochdouble

EPOCH to convert. Lists and numpy arrays are acceptable.

Returns
out(double, double)

EPOCH16 corresponding to epoch

epoch_to_num(epoch)[source]

Convert CDF EPOCH to matplotlib number.

Same output as date2num() and useful for plotting large data sets without converting the times through datetime.

Parameters
epochdouble

EPOCH to convert. Lists and numpy arrays are acceptable.

Returns
outdouble

Floating point number representing days since matplotlib epoch (usually 0001-01-01 as day 1, or 1970-01-01 as day 0).

Notes

This number is not portable between versions of matplotlib. The returned value is for the installed version of matplotlib. If matplotlib is not found, the returned value is for matplotlib 3.2 and earlier.

epoch_to_tt2000(epoch)[source]

Converts a CDF EPOCH to a CDF TT2000 value

Parameters
epochdouble

EPOCH to convert

Returns
outint

tt2000 corresponding to epoch

epoch16_to_datetime(epoch0, epoch1)[source]

Converts a CDF epoch16 value to a datetime

Note

The call signature has changed since SpacePy 0.1.2. Formerly this method took a single argument with two values; now it requires two arguments (one for each value). To convert existing code, replace epoch16_to_datetime(epoch) with epoch16_to_datetime(*epoch).

Parameters
epoch0float

epoch16 value from CDF, first half

epoch1float

epoch16 value from CDF, second half

Returns
outdatetime.datetime

date and time corresponding to epoch. Invalid values are set to usual epoch invalid value, i.e. last moment of year 9999.

Raises
EpochErrorif input invalid
epoch16_to_epoch(epoch16)[source]

Converts a CDF EPOCH16 to a CDF EPOCH value

Parameters
epoch16(double, double)

EPOCH16 to convert. Lists and numpy arrays are acceptable. LAST dimension should be 2: the two pairs of EPOCH16

Returns
outdouble

EPOCH corresponding to epoch16

epoch16_to_tt2000(epoch0, epoch1)[source]

Converts a CDF epoch16 value to TT2000

Note

Because TT2000 does not support picoseconds, the picoseconds value in epoch is ignored (i.e., truncated.)

Parameters
epoch0float

epoch16 value from CDF, first half

epoch1float

epoch16 value from CDF, second half

Returns
outlong

TT2000 corresponding to epoch.

Raises
EpochErrorif input invalid
get_minmax(cdftype)[source]

Find minimum, maximum possible value based on CDF type.

This returns the processed value (e.g. datetimes for Epoch types) because comparisons to EPOCH16s are otherwise difficult.

Parameters
cdftypeint

CDF type number from const

Returns
outtuple

minimum, maximum value supported by type (of type matching the CDF type).

Raises
ValueErrorif can’t match the type
set_backward(backward=True)[source]

Set backward compatibility mode for new CDFs

Unless backward compatible mode is set, CDF files created by the version 3 library can not be read by V2.

Parameters
backwardboolean

Set backward compatible mode if True; clear it if False.

Raises
ValueErrorif backward=False and underlying CDF library is V2
supports_int8

True if this library supports INT8 and TIME_TT2000 types; else False.

tt2000_to_datetime(tt2000)[source]

Converts a CDF TT2000 value to a datetime

Note

Although TT2000 values support leapseconds, Python’s datetime object does not. Any times after 23:59:59.999999 will be truncated to 23:59:59.999999.

Parameters
tt2000int

TT2000 value from CDF

Returns
outdatetime.datetime

date and time corresponding to epoch. Invalid values are set to usual epoch invalid value, i.e. last moment of year 9999.

Raises
EpochErrorif input invalid
tt2000_to_epoch(tt2000)[source]

Converts a CDF TT2000 value to a CDF EPOCH

Note

Although TT2000 values support leapseconds, CDF EPOCH values do not. Times during leapseconds are rounded up to beginning of the next day.

Parameters
tt2000int

TT2000 value from CDF

Returns
outdouble

EPOCH corresponding to the TT2000 input time

Raises
EpochErrorif input invalid
tt2000_to_epoch16(tt2000)[source]

Converts a CDF TT2000 value to a CDF EPOCH16

Note

Although TT2000 values support leapseconds, CDF EPOCH16 values do not. Times during leapseconds are rounded up to beginning of the next day.

Parameters
tt2000int

TT2000 value from CDF

Returns
outdouble, double

EPOCH16 corresponding to the TT2000 input time

Raises
EpochErrorif input invalid
v_datetime_to_epoch(datetime)

A vectorized version of datetime_to_epoch() which takes a numpy array of datetimes as input and returns an array of epochs.

v_datetime_to_epoch16(datetime)

A vectorized version of datetime_to_epoch16() which takes a numpy array of datetimes as input and returns an array of epoch16.

v_datetime_to_tt2000(datetime)

A vectorized version of datetime_to_tt2000() which takes a numpy array of datetimes as input and returns an array of TT2000.

v_epoch_to_datetime(epoch)

A vectorized version of epoch_to_datetime() which takes a numpy array of epochs as input and returns an array of datetimes.

v_epoch_to_tt2000(epoch)

A vectorized version of epoch_to_tt2000() which takes a numpy array of epochs as input and returns an array of tt2000s.

v_epoch16_to_datetime(epoch0, epoch1)

A vectorized version of epoch16_to_datetime() which takes a numpy array of epoch16 as input and returns an array of datetimes. An epoch16 is a pair of doubles; the input array’s last dimension must be two (and the returned array will have one fewer dimension).

v_epoch16_to_tt2000(epoch16)

A vectorized version of epoch16_to_tt2000() which takes a numpy array of epoch16 as input and returns an array of tt2000s. An epoch16 is a pair of doubles; the input array’s last dimension must be two (and the returned array will have one fewer dimension).

v_tt2000_to_datetime(tt2000)

A vectorized version of tt2000_to_datetime() which takes a numpy array of tt2000 as input and returns an array of datetimes.

v_tt2000_to_epoch(tt2000)

A vectorized version of tt2000_to_epoch() which takes a numpy array of tt2000 as input and returns an array of epochs.

v_tt2000_to_epoch16(tt2000)

A vectorized version of tt2000_to_epoch16() which takes a numpy array of tt2000 as input and returns an array of epoch16.

libpath

The path where pycdf found the CDF C library, potentially useful in debugging. If this contains just the name of a file (with no path information), then the system linker found the library for pycdf. On Linux, ldconfig -p may be useful for displaying the system’s library resolution.

version

Version of the CDF library, (version, release, increment, subincrement)