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 following:

  • AlbedoData

  • AtmosphereData

  • DentonGEO

  • EphemerisData

  • LocalGravData

  • MagneticField

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,
    ...
}

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().