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
set_backward([backward]) Set backward compatibility mode for new CDFs
supports_int8
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
v_datetime_to_epoch16
v_datetime_to_tt2000
v_epoch_to_datetime
v_epoch_to_tt2000
v_epoch16_to_datetime
v_epoch16_to_tt2000
v_tt2000_to_datetime
v_tt2000_to_epoch
v_tt2000_to_epoch16
libpath
version Version information for NetworkX, created during installation.
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:

args : various, see ctypes

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

Returns:

out : int

CDF status from the library

Other Parameters:
 

ignore : sequence 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:

CDFError : if CDF library reports an error

Warns:

CDFWarning : if CDF library reports a warning

check_status(status, ignore=())[source]

Raise exception or warning based on return status of CDF call

Parameters:

status : int

status returned by the C library

Returns:

out : int

status (unchanged)

Other Parameters:
 

ignore : sequence 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:

CDFError : if status < CDF_WARN, indicating an error

Warns:

CDFWarning : if CDF_WARN <= status < CDF_OK, indicating a warning.

datetime_to_epoch(dt)[source]

Converts a Python datetime to a CDF Epoch value

Parameters:

dt : datetime.datetime

date and time to convert

Returns:

out : float

epoch corresponding to dt

datetime_to_epoch16(dt)[source]

Converts a Python datetime to a CDF Epoch16 value

Parameters:

dt : datetime.datetime

date and time to convert

Returns:

out : list of float

epoch16 corresponding to dt

datetime_to_tt2000(dt)[source]

Converts a Python datetime to a CDF TT2000 value

Parameters:

dt : datetime.datetime

date and time to convert

Returns:

out : int

tt2000 corresponding to dt

epoch_to_datetime(epoch)[source]

Converts a CDF epoch value to a datetime

Parameters:

epoch : float

epoch value from CDF

Returns:

out : datetime.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:

epoch : double

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:

epoch : double

EPOCH to convert. Lists and numpy arrays are acceptable.

Returns:

out : double

Floating point number representing days since 0001-01-01.

epoch_to_tt2000(epoch)[source]

Converts a CDF EPOCH to a CDF TT2000 value

Parameters:

epoch : double

EPOCH to convert

Returns:

out : int

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:

epoch0 : float

epoch16 value from CDF, first half

epoch1 : float

epoch16 value from CDF, second half

Returns:

out : datetime.datetime

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

Raises:

EpochError : if 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:

out : double

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:

epoch0 : float

epoch16 value from CDF, first half

epoch1 : float

epoch16 value from CDF, second half

Returns:

out : long

TT2000 corresponding to epoch.

Raises:

EpochError : if input invalid

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:

backward : boolean

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

Raises:

ValueError : if 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:

tt2000 : int

TT2000 value from CDF

Returns:

out : datetime.datetime

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

Raises:

EpochError : if 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:

tt2000 : int

TT2000 value from CDF

Returns:

out : double

EPOCH corresponding to the TT2000 input time

Raises:

EpochError : if 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:

tt2000 : int

TT2000 value from CDF

Returns:

out : double, double

EPOCH16 corresponding to the TT2000 input time

Raises:

EpochError : if 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)