{"id":10251,"library":"spiceypy","title":"SpiceyPy","description":"SpiceyPy is a Python wrapper for NASA's NAIF CSPICE Toolkit, providing tools for computing ephemeris, attitude, event finding, and geometry for spacecraft and celestial bodies. It enables Python users to leverage the powerful CSPICE library. The library is actively maintained with frequent releases, currently at version 8.1.0, and often includes performance enhancements and new features.","status":"active","version":"8.1.0","language":"en","source_language":"en","source_url":"https://github.com/AndrewAnnex/SpiceyPy","tags":["astronomy","space","naif","spice","celestial mechanics","ephemeris","satellite","geometry","numpy"],"install":[{"cmd":"pip install spiceypy","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for array operations and numerical data handling within SPICE functions.","package":"numpy"}],"imports":[{"symbol":"spiceypy","correct":"import spiceypy as spice"},{"note":"Introduced in v7.0.0 for C-accelerated SPICE functions. Use `cyice` functions for performance-critical applications.","symbol":"Cyice","correct":"from spiceypy import cyice"}],"quickstart":{"code":"import spiceypy as spice\nimport os\n\n# A simple kernel file for demonstration\n# In a real application, you would download these from NAIF\n# For local testing, ensure naif0012.tls is in the script's directory\n# or specify its full path.\nkernel_path = os.path.join(os.path.dirname(__file__), 'naif0012.tls')\nif not os.path.exists(kernel_path):\n    # This is a dummy for demonstration. You would fetch a real kernel.\n    print(f\"Warning: '{kernel_path}' not found. Please download from NAIF if this isn't a test.\")\n    # Example: You'd typically download like this (replace with actual URL and process)\n    # import urllib.request\n    # url = 'https://naif.jpl.nasa.gov/pub/naif/generic_kernels/lsk/naif0012.tls'\n    # urllib.request.urlretrieve(url, kernel_path)\n\n# Load a leap second kernel (LSK) to define Ephemeris Time (ET)\ntry:\n    spice.furnsh(kernel_path)\nexcept spice.exceptions.SpiceyPyError as e:\n    print(f\"Failed to load kernel: {e}. Skipping calculations.\")\n    exit()\n\n# Convert a UTC string to Ephemeris Time (ET)\nutc_time = '2023-01-01 T00:00:00'\net = spice.str2et(utc_time)\nprint(f\"UTC: {utc_time} -> ET: {et}\")\n\n# Get position of Earth relative to the Sun\n# Observer: SUN, Target: EARTH, Reference Frame: J2000, Aberration Correction: NONE\npos, lt = spice.spkpos('EARTH', et, 'J2000', 'NONE', 'SUN')\nprint(f\"Position of Earth relative to Sun (km): {pos}\")\n\n# Unload all kernels\nspice.unload(kernel_path)\n# Alternatively, spice.kclear() clears all loaded kernels\n","lang":"python","description":"This quickstart demonstrates loading a leap second kernel (LSK) using `spice.furnsh()`, converting a UTC time string to Ephemeris Time (ET) with `spice.str2et()`, and then calculating the position of Earth relative to the Sun using `spice.spkpos()`. It's crucial to download and correctly point to actual SPICE kernel files (LSK, PCK, SPK, FK, IK, CK) from the NAIF website for real applications. The example includes a placeholder for a kernel path."},"warnings":[{"fix":"Always call `spice.furnsh()` with paths to the required kernel files before performing any SPICE computations. Use `spice.kclear()` to unload all kernels or `spice.unload()` for specific ones when done.","message":"Failing to load necessary SPICE kernels (e.g., Leap Seconds, PCK, SPK) via `spice.furnsh()` is the most common pitfall. Many SPICE functions will fail with cryptic errors or return incorrect results without the required data loaded into the kernel pool.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review error handling logic for SPICE functions that return a `found` flag. Ensure your code correctly handles both `NotFound` exceptions and the `found` flag where applicable. The intent is improved robustness, so existing code *should* ideally become more stable, but edge cases might require adaptation.","message":"The order of `NotFound` exception checks and error handling was swapped in v8.0.0. This change aims to prevent spurious `NotFound` exceptions but might subtly alter error propagation for code that previously relied on the exact timing or order of these checks.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"For performance-critical code, consider explicitly importing and using `cyice` functions (`from spiceypy import cyice`). If installation issues arise, ensure you have a C compiler (e.g., GCC, MSVC) and `numpy` installed, or look for pre-built wheels for your specific Python version and OS.","message":"SpiceyPy v7.0.0 introduced `cyice`, a Cython-accelerated submodule for performance. While largely 'drop-in', functions called via `cyice.function_name` are C-extensions. Debugging or introspection might differ slightly from the `ctypes`-based `spiceypy` functions. Installation on unusual platforms or without appropriate build tools can also be more complex without pre-built wheels.","severity":"gotcha","affected_versions":">=7.0.0"},{"fix":"Always convert your input times to ET using `spice.str2et()` or similar functions before passing them to SPICE routines. Convert results back to UTC or `datetime` as needed for display or further processing using `spice.et2utc()`.","message":"SPICE functions typically operate using Ephemeris Time (ET), which is seconds past J2000 epoch. Direct use of Python's `datetime` objects or UTC strings often requires conversion via functions like `spice.str2et()` and `spice.et2utc()`. Incorrectly mixing time systems is a common source of errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Before calling SPICE functions, ensure all necessary kernels are loaded: `spice.furnsh('/path/to/my_kernel.bsp')`, `spice.furnsh('/path/to/my_lsk.tls')`, etc. Consult NAIF documentation to understand which kernels are needed for your specific calculation.","cause":"A required SPICE kernel (e.g., an SPK for ephemeris, or PCK for planetary constants) has not been loaded using `spice.furnsh()`.","error":"SPICE(NOKERNELDATA): No kernel data available for object/frame 'EARTH' at time..."},{"fix":"Verify that the kernel file exists at the specified path and that the path is spelled correctly. Use absolute paths or ensure the file is in a location accessible by your script.","cause":"The file path provided to `spice.furnsh()` does not exist or is incorrect.","error":"FileNotFoundError: [Errno 2] No such file or directory: '/path/to/missing_kernel.bsp'"},{"fix":"Ensure inputs match the expected type. For functions expecting an array, pass a `numpy.array([value])` even for single values. Consult the function's docstring for expected input types and shapes.","cause":"A SPICEyPy function expected an array-like input (e.g., a NumPy array or list of numbers) but received a scalar value.","error":"TypeError: argument of type 'int' is not iterable"}]}