Skip to content

Utility Functions

Data-file management lives here. The short version — see Data Files for the full search order per platform:

  • Frames and gravity need no data files: the IERS nutation tables and the gravity models are compiled in.
  • The JPL ephemeris is downloaded on first use (SHA-256 verified) into datadir() — the platform user-data directory, or SATKIT_DATA / set_datadir() if given. Nothing is ever written next to the extension module or inside site-packages.
  • Files are looked up across data_search_dirs(), which includes an installed satkit-data package and /usr/share/satkit-data (read-only), so an offline bundle is picked up automatically.
  • update_datafiles() provisions everything up front and refreshes the daily Earth-orientation / space-weather files.
  • SATKIT_OFFLINE=1 forbids downloads (a missing file raises RuntimeError naming its sources); SATKIT_DATA_URL names a mirror; SATKIT_JPLEPHEM_FILE selects the ephemeris.

utils

Utility functions for SatKit

update_datafiles(**kwargs)

Download & store data files needed for "satkit" computations

Not required for normal use: the IERS nutation tables and gravity models are compiled into satkit, the JPL ephemeris is downloaded on first use, and the Earth-orientation / space-weather files are fetched on first use. Call this to provision everything up front (a container image, a machine that will later be offline) or to refresh the daily files. Raises RuntimeError if SATKIT_OFFLINE=1 is set.

Keyword Args:

overwrite (bool): Re-download static files even when a verified copy is already present dir(string): Target directory for files. Uses datadir() if not specified

Static files are fetched according to the data manifest compiled into satkit (data/manifest.json): each is tried from SATKIT_DATA_URL (if set), then the GitHub release asset, the origin server, and the legacy bucket, and is only kept when its size and SHA-256 match the manifest. Files already present with the right hash are skipped.

Notes

  • Files include:

    • EGM96.gfc : EGM-96 Gravity Model Coefficients
    • JGM3.gfc : JGM-3 Gravity Model Coefficients
    • JGM2.gfc : JGM-2 Gravity Model Coefficients
    • ITU_GRACE16.gfc : ITU Grace 16 Gravity
    • tab5.2a.txt : Coefficients for GCRS to GCRF conversion
    • tab5.2b.txt : Coefficients for GCRS to GCRF conversion
    • tab5.2d.txt : Coefficients for GCRS to GCRF conversion
    • SW-ALL.csv : Space weather data, updated daily
    • predicted-solar-cycle.json : NOAA/SWPC solar cycle forecast (~5 years of predicted F10.7)
    • leap-seconds.list : Leap seconds (UTC vs TAI); reference only — the runtime table is compiled in
    • EOP-All.csv : Earth orientation parameters, updated daily
    • linux_p1550p2650.440 : JPL Ephemeris version 440 (~ 100 MB)

  • The space weather and earth orientation parameters files are updated daily and will always be downloaded regardless of the overwrite flag

Example 
# Download all data files to the default data directory
satkit.utils.update_datafiles()

# Force re-download of all files
satkit.utils.update_datafiles(overwrite=True)

datadir()

Directory where downloaded data files are written

The core data (IERS nutation tables, gravity models to degree 70) is compiled into satkit, so a data directory is only needed for the JPL ephemeris (downloaded on first use, SHA-256 verified) and the regularly refreshed Earth-orientation / space-weather files.

Files are looked up across several locations (see data_search_dirs), but downloads go to exactly one place — SATKIT_DATA if set, else the directory given to set_datadir, else the platform user-data directory:

  • macOS: ~/Library/Application Support/satkit-data
  • Linux: $XDG_DATA_HOME/satkit-data (default ~/.local/share/satkit-data)
  • Windows: %LOCALAPPDATA%\satkit-data

satkit never writes next to its own extension module or inside site-packages. Set SATKIT_OFFLINE=1 to forbid downloads entirely (a missing file then raises RuntimeError naming its sources), and SATKIT_DATA_URL to fetch from a mirror.

Returns:

Type Description
str | None

str | None: directory downloads are written to (created on first use),
str | None

or None if none could be determined
Example 
print(satkit.utils.datadir())
# /Users/user/Library/Application Support/satkit-data

data_search_dirs()

Directories searched for data files, in order

A file is used from the first directory that contains it; any of these may be read-only (a system-wide directory, the optional satkit-data package inside site-packages). Downloads go only to datadir().

  1. SATKIT_DATA (environment; also the write location)
  2. the directory given to set_datadir (also the write location)
  3. directories added with add_search_dir
  4. <dir of the satkit extension>/satkit-data
  5. <site-packages>/satkit_data/data (the satkit-data pip package)
  6. the platform user-data directory (the default write location)
  7. ~/.satkit-data (legacy)
  8. /usr/share/satkit-data (not on Windows)
  9. macOS: /Library/Application Support/satkit-data

Returns:

Type Description
list[str]

list[str]: search directories in order

add_search_dir(path)

Add a read-only directory to the data-file search list

Tried after SATKIT_DATA / set_datadir and before the platform locations. Downloads are never written here. The satkit package uses this itself to register the optional satkit_data bundle.

Parameters:

Name Type Description Default
path str

Directory to search

 required

set_offline(enabled)

Forbid (or re-allow) downloads for this process

Offline mode blocks downloads only: the explicit update_datafiles() and every lazy first-use fetch (the JPL ephemeris, the Earth-orientation and space-weather refresh, any non-embedded file). It does not change where files are searched, and the compiled-in core data (IERS nutation tables, gravity models) is unaffected. A blocked download raises RuntimeError naming the file and its sources — the same error a build without the download feature gives.

Precedence: the last call to set_offline wins; if it was never called, the SATKIT_OFFLINE environment variable is consulted (1/anything except 0, false or empty means offline).

Parameters:

Name Type Description Default
enabled bool

True to forbid downloads, False to allow them

 required

is_offline()

Whether downloads are currently forbidden

Reflects set_offline if it was ever called, else the SATKIT_OFFLINE environment variable.

Returns:

Name Type Description
bool bool

True if downloads are forbidden

set_datadir(datadir)

Set the data directory

The directory becomes the first search location (after SATKIT_DATA) and the location downloads are written to.

Parameters:

Name Type Description Default
datadir str

Path to the data directory

 required

Raises:

Type Description
RuntimeError

If the directory does not exist

datafiles_exist()

Check whether a JPL ephemeris file is present in any search directory

The ephemeris is the only data satkit needs that is neither compiled in nor refreshed daily, so its presence marks a provisioned data location. Everything else (frames, gravity, SGP4, time, Kepler, Lambert) works without any data files.

Returns:

Name Type Description
bool bool

True if an ephemeris file is found, False otherwise

dylib_path()

Return path to the compiled satkit library

Returns:

Name Type Description
str str

Path to the compiled library

githash()

Return git hash of this satkit build

Returns:

Name Type Description
str str

Git hash of this satkit build

build_date()

Return build date of this satkit library as a string

Returns:

Name Type Description
str str

Build date of this satkit library

version()

Return version of this satkit library as a string

Returns:

Name Type Description
str str

Version of this satkit library