tessl/pypi-spiceypy

A Python wrapper for the NAIF CSPICE Toolkit providing essential tools for spacecraft navigation and planetary science calculations

Overview

Eval results

Files

Time Systems

Name: tessl/pypi-spiceypy
Author: tessl

Comprehensive time conversion and manipulation functions supporting various time systems including UTC, ET (Ephemeris Time), TDB, and custom calendar formats. Time handling is fundamental to all SPICE computations as ephemeris data is indexed by time.

Capabilities

Time String to Ephemeris Time Conversion

Convert human-readable time strings to ephemeris time (ET), which is the standard time system used throughout SPICE.

def str2et(time: Union[str, Iterable[str]]) -> Union[float, ndarray]:
    """
    Convert time string(s) to ephemeris time.
    
    Parameters:
    - time: str or Iterable[str], time string(s) in various formats
    
    Returns:
    Union[float, ndarray]: ephemeris time in seconds past J2000 epoch
    
    Supported formats:
    - ISO: "2023-01-01T12:00:00"
    - Calendar: "Jan 1, 2023 12:00:00"
    - DOY: "2023-001T12:00:00"  
    - JD: "JD 2459945.5"
    """

Usage example:

import spiceypy as spice

# Single time conversion
et = spice.str2et("2023-01-01T12:00:00")
print(f"ET: {et} seconds past J2000")

# Multiple time conversions (vectorized)
times = ["2023-01-01", "2023-06-01", "2023-12-31"] 
ets = spice.str2et(times)
print(f"ETs: {ets}")

Ephemeris Time to UTC Conversion

Convert ephemeris time back to UTC strings in various formats.

def et2utc(et: Union[float, ndarray], format: str, prec: int) -> Union[str, List[str]]:
    """
    Convert ephemeris time to UTC string representation.
    
    Parameters:
    - et: Union[float, ndarray], ephemeris time(s)
    - format: str, output format ("C", "D", "ISO", "ISOC", "J")
    - prec: int, precision (digits after decimal point)
    
    Returns:
    Union[str, List[str]]: formatted UTC string(s)
    
    Format options:
    - "C": Calendar format "MON DD, YYYY HR:MN:SC.### ::UTC"
    - "D": DOY format "YYYY-DOY // HR:MN:SC.### ::UTC"  
    - "ISO": ISO format "YYYY-MM-DDTHR:MN:SC.###"
    - "ISOC": Compact ISO "YYYYMMDDTHRMNSC.###"
    - "J": Julian date "JD ###.######"
    """

def utc2et(utcstr: str) -> float:
    """
    Convert UTC string to ephemeris time.
    
    Parameters:
    - utcstr: str, UTC time string
    
    Returns:
    float: ephemeris time
    """

Usage example:

# Convert ET to various UTC formats
et = spice.str2et("2023-01-01T12:00:00")

utc_iso = spice.et2utc(et, "ISO", 3)      # "2023-01-01T12:00:00.000"
utc_cal = spice.et2utc(et, "C", 0)        # "JAN 01, 2023 12:00:00 ::UTC"
utc_doy = spice.et2utc(et, "D", 0)        # "2023-001 // 12:00:00 ::UTC"
utc_jd = spice.et2utc(et, "J", 6)         # "JD 2459945.500000"

Local Solar Time Conversion

Convert between ephemeris time and local solar time for planetary bodies.

def et2lst(et: Union[float, ndarray], body: Union[int, str], lon: float, type: str) -> Union[Tuple[int, int, int, str, str], List[Tuple[int, int, int, str, str]]]:
    """
    Convert ephemeris time to local solar time.
    
    Parameters:
    - et: Union[float, ndarray], ephemeris time(s)
    - body: Union[int, str], target body name or ID
    - lon: float, longitude in radians (positive east)
    - type: str, "PLANETOCENTRIC" or "PLANETOGRAPHIC"
    
    Returns:
    Union[Tuple, List[Tuple]]: (hr, mn, sc, time, ampm)
    - hr: int, hour (0-23)
    - mn: int, minute (0-59)  
    - sc: int, second (0-59)
    - time: str, formatted time string
    - ampm: str, "A.M." or "P.M."
    """

Time Parsing and Formatting

Advanced time parsing and custom formatting functions.

def tparse(string: str) -> Tuple[float, str]:
    """
    Parse a time string and return ephemeris time.
    
    Parameters:
    - string: str, time string to parse
    
    Returns:
    Tuple[float, str]: (et, error_message)
    """

def timout(et: float, pictur: str) -> str:
    """
    Format ephemeris time using a custom picture string.
    
    Parameters:
    - et: float, ephemeris time
    - pictur: str, format picture string
    
    Returns:
    str: formatted time string
    
    Picture format examples:
    - "MON DD, YYYY"  → "JAN 01, 2023"
    - "YYYY-MM-DD"    → "2023-01-01"
    - "HR:MN:SC.###"  → "12:00:00.000"
    """

def etcal(et: float) -> str:
    """
    Convert ephemeris time to calendar format.
    
    Parameters:
    - et: float, ephemeris time
    
    Returns:
    str: calendar format "YYYY MON DD HR:MN:SC.FFF"
    """

Time Constants and Utilities

Functions that return useful time-related constants and utilities.

def spd() -> float:
    """
    Return the number of seconds per day.
    
    Returns:
    float: 86400.0 (seconds per day)
    """

def rpd() -> float:
    """
    Return the number of radians per degree.
    
    Returns:
    float: π/180 (radians per degree)
    """

def dpr() -> float:
    """
    Return the number of degrees per radian.
    
    Returns:
    float: 180/π (degrees per radian)
    """

def j1900() -> float:
    """
    Return the Julian date of 1900 JAN 0.5.
    
    Returns:
    float: 2415020.0
    """

def j1950() -> float:
    """
    Return the Julian date of 1950 JAN 1.0.
    
    Returns:
    float: 2433282.5
    """

def j2000() -> float:
    """
    Return the Julian date of 2000 JAN 1.5.
    
    Returns:
    float: 2451545.0
    """

def j2100() -> float:
    """
    Return the Julian date of 2100 JAN 1.5.
    
    Returns:
    float: 2488070.0
    """

Time Differences and Light Time

Functions for computing time differences and light travel time corrections.

def deltet(epoch: float, eptype: str) -> float:
    """
    Return the difference TDB - TDT at a given epoch.
    
    Parameters:
    - epoch: float, epoch time
    - eptype: str, epoch type ("UTC", "ET", "TAI", "TDT", "TDB")
    
    Returns:
    float: TDB - TDT in seconds
    """

def ltime(obs: ndarray, dir: int, target: ndarray) -> Tuple[float, ndarray]:
    """
    Compute light time between observer and target.
    
    Parameters:
    - obs: ndarray, observer position vector
    - dir: int, direction (1 for transmission, -1 for reception)
    - target: ndarray, target position vector
    
    Returns:
    Tuple[float, ndarray]: (light_time, target_position_corrected)
    """

Common Usage Patterns

Basic Time Conversion Workflow

import spiceypy as spice

# Convert human-readable time to ET for SPICE computations
et = spice.str2et("2023-07-15T14:30:00")

# Use ET in SPICE functions
position, lt = spice.spkpos("MARS", et, "J2000", "LT+S", "EARTH")

# Convert back to human-readable format for output
utc_time = spice.et2utc(et, "ISO", 3)
print(f"Time: {utc_time}")

Working with Time Arrays

# Create a time series
start_time = spice.str2et("2023-01-01T00:00:00")
end_time = spice.str2et("2023-01-02T00:00:00") 
n_points = 25
dt = (end_time - start_time) / (n_points - 1)
times = [start_time + i * dt for i in range(n_points)]

# Convert time array to UTC strings for display
utc_times = spice.et2utc(times, "ISO", 0)
for utc in utc_times[:3]:  # Show first 3
    print(utc)

Local Solar Time on Mars

# Convert Earth UTC time to Mars local solar time
et = spice.str2et("2023-07-15T12:00:00")
mars_lon = spice.dpr() * 175.0  # 175 degrees east longitude

# Get Mars local solar time
hr, mn, sc, time_str, ampm = spice.et2lst(et, "MARS", mars_lon, "PLANETOCENTRIC")
print(f"Mars LST: {time_str} {ampm}")

Install with Tessl CLI