Adding Support Data Files

This page explains how to correctly add new files to the supportData directory so they integrate with Basilisk’s Pooch-based data management system and are versioned on GitHub.

Basilisk does not ship supportData files inside the wheel. Instead, all files are registered and fetched on demand.

When you add or update support data files, three major parts may need updating:

  1. supportData/ directory (the files themselves)

  2. makeRegistry.py (to regenerate the MD5 registry)

  3. dataFetcher.py (to map the file into enums/category paths)

Folder Layout

Files must live inside:

basilisk/supportData/<CategoryName>/<file>

Where <CategoryName> must match one of the folder names listed in Support Data Files. If you add a new sub-category, you must also add it to dataFetcher.py (explained in Step 4).

Step 1 — Add the File to supportData/

Place your file under the appropriate category, e.g.:

basilisk/supportData/AtmosphereData/NewMarsAtmosphere2025.csv

Make sure the file is not covered by any ignore patterns (see makeRegistry.py).

Step 2 — Ensure makeRegistry.py will include the file

The registry generator ignores certain patterns:

IGNORE_PATTERNS = (
    "__pycache__",
    ".pyc",
    "__init__.py",
    "*.bsp",
)

If your file accidentally matches a pattern, remove or update the entry.

Step 3 — Regenerate the registrySnippet.py file

From the project root, run:

python src/utilities/supportDataTools/makeRegistry.py > src/utilities/supportDataTools/registrySnippet.py

This writes a dictionary of:

  • file to MD5 hash

  • symbols used by Pooch to verify downloads

Commit the changed registrySnippet.py.

Step 4 — Update dataFetcher.py (Enums and Base Paths)

In dataFetcher.py, each category has:

  1. An Enum listing files

  2. A base path value

  3. A mapping in CATEGORY_BASE_PATHS

For example, adding NewMarsAtmosphere2025.csv requires:

  1. Add to the correct Enum:

class AtmosphereData(Enum):
    NewMarsAtmosphere2025 = "NewMarsAtmosphere2025.csv"

  1. Ensure the base path exists:

ATMOSPHERE_DATA_BASE_PATH = "supportData/AtmosphereData/"

  1. Ensure the category name → base path map includes it:

CATEGORY_BASE_PATHS = {
    "AtmosphereData": ATMOSPHERE_DATA_BASE_PATH,
    ...
}

Configuring the Cache Directory

By default, Pooch stores downloaded files in the OS-specific user cache directory (e.g. ~/.cache/bsk_support_data on Linux). You can override this by setting the BSK_SUPPORT_DATA_CACHE environment variable to any writable path:

export BSK_SUPPORT_DATA_CACHE=/path/to/my/cache

This is useful for:

  • CI pipelines — point the cache at a workspace-relative directory that can be saved and restored between runs.

  • Shared installations — redirect all users on a system to a common pre-populated cache directory.

  • Testing — isolate the cache to a temporary directory.

When BSK_SUPPORT_DATA_CACHE is set, the LOCAL_SUPPORT shortcut (files already present in a cloned repo’s supportData/ directory) still takes priority for any file that exists there.

External Data Sources

Some kernel files are not in the Git repo and should not be hashed:

EXTERNAL_KERNEL_URLS = {
    "supportData/EphemerisData/de430.bsp": "https://naif.jpl.nasa.gov/...",
    ...
}

These entries automatically override registry hashes:

for key in EXTERNAL_KERNEL_URLS:
    REGISTRY[key] = None

This prevents MD5 failures when NAIF updates files.

Note: Even for external files, an entry must still exist in ``dataFetcher.py`` (Enums + category base path). This allows Pooch to download the file on demand and return a local path via get_path().