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

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

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

    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)

    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

    See also

    `v_datetime_to_epoch`
  datetime_to_epoch16(dt)

    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

    See also

    `v_datetime_to_epoch16`
  datetime_to_tt2000(dt)

    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

    See also

    `v_datetime_to_tt2000`
  epoch_to_datetime(epoch)

    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.

    See also

    `v_epoch_to_datetime`
  epoch_to_epoch16(epoch)

    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)

    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 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
      epoch double

        EPOCH to convert

    Returns
      out int

        tt2000 corresponding to epoch

    See also

    `v_epoch_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
      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

    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
      out double

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

    See also

    `v_epoch16_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
      cdftype int

        CDF type number from `const`

    Returns
      out tuple

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

    Raises
      ValueError if 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
      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)

    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

    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
      tt2000 int

        TT2000 value from CDF

    Returns
      out double

        EPOCH corresponding to the TT2000 input time

    Raises
      EpochError if 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
      tt2000 int

        TT2000 value from CDF

    Returns
      out double, double

        EPOCH16 corresponding to the TT2000 input time

    Raises
      EpochError if input invalid

    See also

    `v_tt2000_to_epoch16`
  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)