NAIF Ephemeris Kernels¶

NAIF (Navigation and Ancillary Information Facility) is NASA JPL's archive for planetary ephemeris data. Brahe provides functions to download DE (Development Ephemeris), satellite ephemeris, and lunar-orientation kernels from the NAIF archive.

Supported Kernels¶

Brahe supports downloading the following kernel files, enumerated by SPICEKernel (Rust). The Python bh.datasets.naif.download_spice_kernel(name, ...) function and the Rust brahe::datasets::naif::download_spice_kernel(kernel, ...) function both accept any of these — by name (str) in Python, by SPICEKernel variant in Rust:

Caching Behavior¶

DE kernels are large files that do not change over time. Brahe implements permanent caching:

• Cache location: ~/.cache/brahe/naif/ (or $BRAHE_CACHE/naif/ if set)
• Cache duration: Permanent (kernels are stable long-term products)
• Cache check: Simple file existence check - no age validation

Once a kernel is downloaded, it remains cached indefinitely and subsequent calls return the cached file path without re-downloading.

Usage¶

Basic Download¶

Download a kernel and use the cached location:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

import brahe as bh

# Initialize EOP data
bh.initialize_eop()

# Download de440s kernel (smaller variant, ~33MB)
# This will download once and cache for future use
kernel_path = bh.datasets.naif.download_spice_kernel("de440s")

print(f"Kernel cached at: {kernel_path}")

# Subsequent calls use the cached file - no re-download
kernel_path_again = bh.datasets.naif.download_spice_kernel("de440s")
print(f"Retrieved from cache: {kernel_path_again}")

# Optionally copy to a specific location
output_path = "/tmp/my_kernel.bsp"
copied_path = bh.datasets.naif.download_spice_kernel("de440s", output_path)
print(f"Copied to: {copied_path}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

use brahe as bh;

fn main() {
    bh::initialize_eop().unwrap();

    // Download de440s kernel (smaller variant, ~33MB)
    // This will download once and cache for future use
    let kernel_path =
        bh::datasets::naif::download_spice_kernel(bh::spice::SPICEKernel::DE440s, None).unwrap();

    println!("Kernel cached at: {}", kernel_path.display());

    // Subsequent calls use the cached file - no re-download
    let kernel_path_again =
        bh::datasets::naif::download_spice_kernel(bh::spice::SPICEKernel::DE440s, None).unwrap();
    println!("Retrieved from cache: {}", kernel_path_again.display());

    // Optionally copy to a specific location
    let output_path = std::path::PathBuf::from("/tmp/my_kernel.bsp");
    let copied_path = bh::datasets::naif::download_spice_kernel(
        bh::spice::SPICEKernel::DE440s,
        Some(output_path),
    )
    .unwrap();
    println!("Copied to: {}", copied_path.display());
}

1

1

The first call downloads and caches the kernel. Subsequent calls immediately return the cached file path.

Error Handling¶

The Python binding takes a kernel name as a string and validates it before attempting a download; invalid names raise an error immediately:

1
2
3
4
5

try:
    bh.datasets.naif.download_spice_kernel("de999")
except RuntimeError as e:
    print(e)
    # "Unsupported kernel name 'de999'. Supported kernels: de430, de432s, ..."

In Rust, download_spice_kernel takes a SPICEKernel enum value directly rather than a string, so an unsupported kernel name cannot be passed at all — the enum only has the 16 valid variants. To validate a name obtained at runtime (e.g. from user input), resolve it through SPICEKernel::from_name first:

1
2
3
4
5
6
7

match bh::spice::SPICEKernel::from_name("de999") {
    Some(kernel) => {
        let path = bh::datasets::naif::download_spice_kernel(kernel, None).unwrap();
        println!("Downloaded to {}", path.display());
    }
    None => println!("Unsupported kernel name 'de999'"),
}

See Also¶

• SPICE Kernels - Loading, querying, and PCK orientation
• NAIF SPICE System - Full SPICE toolkit documentation
• DE Kernel Details - Detailed descriptions of each DE version
• Library API Reference - Complete function documentation