Skip to content

Caching

Brahe automatically manages a local cache directory to store downloaded data such as Earth Orientation Parameters (EOP) and TLE data. The caching utilities provide functions to locate and manage these cache directories.

For complete API details, see the Caching API Reference.

Default Cache Location

By default, Brahe stores cache data in a platform-specific location:

  • Unix/Linux/macOS: ~/.cache/brahe
  • Windows: %LOCALAPPDATA%\brahe\cache

All cache directories are automatically created on first access, so you don't need to manually create them.

Environment Variable Override

You can customize the cache location by setting the BRAHE_CACHE environment variable:

1
export BRAHE_CACHE=/custom/path/to/cache

This is useful for:

  • Using a different storage location with more space
  • Sharing cache data across multiple users
  • Testing with isolated cache directories

Getting Cache Directories

Main Cache Directory

The main cache directory is the root location for all Brahe cache data:

1
2
3
# Get main cache directory
cache_dir = bh.get_brahe_cache_dir()
print(f"Main cache directory: {cache_dir}")

1
2
3
    // Get main cache directory
    let cache_dir = bh::utils::get_brahe_cache_dir().unwrap();
    println!("Main cache directory: {}", cache_dir);

EOP Cache Directory

Earth Orientation Parameters are stored in a dedicated subdirectory:

1
2
3
# Get cache subdirectory for EOP data
eop_cache = bh.get_eop_cache_dir()
print(f"EOP cache directory: {eop_cache}")

1
2
3
    // Get cache subdirectory for EOP data
    let eop_cache = bh::utils::get_eop_cache_dir().unwrap();
    println!("EOP cache directory: {}", eop_cache);

CelesTrak Cache Directory

Satellite TLE data downloaded from CelesTrak is stored in its own subdirectory:

1
2
3
# Get cache subdirectory for CelesTrak data
celestrak_cache = bh.get_celestrak_cache_dir()
print(f"CelesTrak cache directory: {celestrak_cache}")

1
2
3
    // Get cache subdirectory for CelesTrak data
    let celestrak_cache = bh::utils::get_celestrak_cache_dir().unwrap();
    println!("CelesTrak cache directory: {}", celestrak_cache);

Custom Subdirectories

You can create custom subdirectories within the cache for your own data:

1
2
3
# Get a custom subdirectory within the cache
custom_cache = bh.get_brahe_cache_dir_with_subdir("custom_data")
print(f"Custom cache subdirectory: {custom_cache}")

1
2
3
    // Get a custom subdirectory within the cache
    let custom_cache = bh::utils::get_brahe_cache_dir_with_subdir(Some("custom_data")).unwrap();
    println!("Custom cache subdirectory: {}", custom_cache);

Complete Example

Here's a complete example demonstrating all cache directory functions:

 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
27
28
29
import brahe as bh

bh.initialize_eop()

# Get main cache directory
cache_dir = bh.get_brahe_cache_dir()
print(f"Main cache directory: {cache_dir}")

# Get cache subdirectory for EOP data
eop_cache = bh.get_eop_cache_dir()
print(f"EOP cache directory: {eop_cache}")

# Get cache subdirectory for CelesTrak data
celestrak_cache = bh.get_celestrak_cache_dir()
print(f"CelesTrak cache directory: {celestrak_cache}")

# Get a custom subdirectory within the cache
custom_cache = bh.get_brahe_cache_dir_with_subdir("custom_data")
print(f"Custom cache subdirectory: {custom_cache}")

# Note: All directories are automatically created if they don't exist
# You can override the default location by setting the BRAHE_CACHE
# environment variable

# Expected output (paths will vary by system):
# Main cache directory: /home/USER/.cache/brahe
# EOP cache directory: /home/USER/.cache/brahe/eop
# CelesTrak cache directory: /home/USER/.cache/brahe/celestrak
# Custom cache subdirectory: /home/USER/.cache/brahe/custom_data

 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
27
28
29
30
31
use brahe as bh;

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

    // Get main cache directory
    let cache_dir = bh::utils::get_brahe_cache_dir().unwrap();
    println!("Main cache directory: {}", cache_dir);

    // Get cache subdirectory for EOP data
    let eop_cache = bh::utils::get_eop_cache_dir().unwrap();
    println!("EOP cache directory: {}", eop_cache);

    // Get cache subdirectory for CelesTrak data
    let celestrak_cache = bh::utils::get_celestrak_cache_dir().unwrap();
    println!("CelesTrak cache directory: {}", celestrak_cache);

    // Get a custom subdirectory within the cache
    let custom_cache = bh::utils::get_brahe_cache_dir_with_subdir(Some("custom_data")).unwrap();
    println!("Custom cache subdirectory: {}", custom_cache);

    // Note: All directories are automatically created if they don't exist
    // You can override the default location by setting the BRAHE_CACHE
    // environment variable

    // Expected output (paths will vary by system):
    // Main cache directory: /home/USER/.cache/brahe
    // EOP cache directory: /home/USER/.cache/brahe/eop
    // CelesTrak cache directory: /home/USER/.cache/brahe/celestrak
    // Custom cache subdirectory: /home/USER/.cache/brahe/custom_data
}

Cache Management

Automatic Cleanup

Brahe does not automatically clean up old cache files. If you need to free up disk space, you can manually delete files from the cache directory. Brahe will re-download any needed data on the next request.

Sharing Cache Between Users

If you're working on server with multiple users using Brahe, you can share the same cache directory by setting the BRAHE_CACHE environment variable to a common location. This avoids duplicate downloads of EOP and TLE data.

See Also