spacepy.pycdf.Library

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

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.

__init__(libpath=None, library=None)

Load the CDF C library.

Searches for the library in the order:

1. Appropriately-named file in CDF_LIB

2. Appropriately-named file in CDF_BASE

3. Standard library search path

@raise CDFError: BAD_DATA_TYPE if can’t map types properly

Methods

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
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
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
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
v_datetime_to_epoch(datetime)	A vectorized version of datetime_to_epoch.
v_datetime_to_epoch16(datetime)	A vectorized version of datetime_to_epoch16.
v_datetime_to_tt2000(datetime)	A vectorized version of datetime_to_tt2000.
v_epoch16_to_datetime(epoch)	A vectorized version of epoch16_to_datetime.
v_epoch16_to_tt2000(epoch16)	A vectorized version of epoch16_to_tt2000.
v_epoch_to_datetime(epoch)	A vectorized version of epoch_to_datetime.
v_epoch_to_tt2000(epoch)	A vectorized version of epoch_to_tt2000.
v_tt2000_to_datetime(tt2000)	A vectorized version of tt2000_to_datetime.
v_tt2000_to_epoch(tt2000)	A vectorized version of tt2000_to_epoch.
v_tt2000_to_epoch16(tt2000)	A vectorized version of tt2000_to_epoch16.

Attributes

libpath

supports_int8

version

call(*args, **kwargs)

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=())

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)

Converts a Python datetime to a CDF Epoch value

Parameters:

dtdatetime.datetime

date and time to convert

Returns:

outfloat

epoch corresponding to dt

See also

v_datetime_to_epoch

datetime_to_epoch16(dt)

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

See also

v_datetime_to_epoch16

datetime_to_tt2000(dt)

Converts a Python datetime to a CDF TT2000 value

Parameters:

dtdatetime.datetime

date and time to convert

Returns:

outint

tt2000 corresponding to dt

See also

v_datetime_to_tt2000

epoch16_to_datetime(epoch0, epoch1)

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

See also

v_epoch16_to_datetime

epoch16_to_epoch(epoch16)

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)

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

See also

v_epoch16_to_tt2000

epoch_to_datetime(epoch)

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.

See also

v_epoch_to_datetime

epoch_to_epoch16(epoch)

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)

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).

See also

matplotlib.dates.date2num, matplotlib.dates.num2date

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)

Converts a CDF EPOCH to a CDF TT2000 value

Parameters:

epochdouble

EPOCH to convert

Returns:

outint

tt2000 corresponding to epoch

See also

v_epoch_to_tt2000

get_minmax(cdftype)

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)

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. pycdf does not set backward compatible mode by default.

Changed in version 0.3.0: Before 0.3.0, pycdf set backward compatible mode on import.

Parameters:

backwardbool, optional

Set backward compatible mode if True; clear it if False. If not specified, will not change current setting.

Changed in version 0.5.0: Added ability to not change setting (previously defaulted to setting backward compatible).

Returns:

bool

Previous value of backward-compatible mode.

Added in version 0.5.0.

Raises:

ValueErrorif backward=False and underlying CDF library is V2

tt2000_to_datetime(tt2000)

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

See also

v_tt2000_to_datetime

tt2000_to_epoch(tt2000)

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

See also

v_tt2000_to_epoch

tt2000_to_epoch16(tt2000)

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

See also

v_tt2000_to_epoch16

v_datetime_to_epoch(datetime)

A vectorized version of datetime_to_epoch.

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.

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.

Takes a numpy array of datetimes as input and returns an array of TT2000.

v_epoch16_to_datetime(epoch)

A vectorized version of epoch16_to_datetime.

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.

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_epoch_to_datetime(epoch)

A vectorized version of epoch_to_datetime.

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.

Takes a numpy array of epochs as input and returns an array of tt2000s.

v_tt2000_to_datetime(tt2000)

A vectorized version of tt2000_to_datetime.

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.

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.

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.

supports_int8 = True

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

version = (0, 0, 0, '')

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