empyrean.initialize

initialize(*, data_dir=None, de440_path=None, gm_path=None, refresh=True)[source]

Initialize empyrean with SPICE kernel data.

On first call, loads ephemeris data into a global context. Subsequent calls are no-ops — including their refresh, so the first call in a process is the one that decides whether the network is reachable.

If the B612 Foundation data packages (naif-de440, jpl-small-bodies-de441-n16, naif-eop-high-prec, naif-eop-historical, naif-eop-predict, mpc-obscodes) are installed and no explicit paths are provided, empyrean stages a symlinked cache under the platform XDG data directory ($XDG_DATA_HOME/empyrean/data/ on Linux, ~/Library/Application Support/empyrean/data/ on macOS, %APPDATA%\empyrean\data\ on Windows; honors EMPYREAN_DATA_DIR) and uses that as the data directory — zero network access required. Falls back to data_dir (default: the same XDG .../empyrean/data/ location) plus download_data() otherwise.

Parameters:

  • data_dir (str | Path | None) – Directory containing kernel files. Overrides B612 detection.

  • de440_path (str | Path | None) – Explicit path to de440.bsp. Overrides B612 detection.

  • gm_path (str | Path | None) – Explicit path to gm_de440.tpc.

  • refresh (bool) –

    Whether initialization may reach the network. True (default) downloads any required kernel that is missing and re-downloads any whose upstream copy moved. False is strict offline: kernels are resolved from the data directory alone and initialization fails, naming every absent file, if any is missing. There is no try-the-network-and-tolerate path and no degrade-to-a-lower-tier path.

    Passing both de440_path and gm_path loads exactly those two files and never reaches the network on either value, so refresh=False is already satisfied on that branch.

    Setting the environment variable EMPYREAN_OFFLINE=1 acts as a floor: it downgrades refresh=True to False and says so on stderr. It can never turn False into True, so an operator asserting “this machine must not reach the network” cannot have that reversed by a library call.

Raises:

  • FileNotFoundError – Under refresh=False when the data directory is missing a required kernel. The exception carries a missing_data_files attribute — the list of absent filenames — so a caller can fetch or report exactly that set without re-parsing the message.

  • RuntimeError – Any other initialization failure.

Return type:

None

Examples

>>> empyrean.initialize(refresh=False)  # air-gapped / reproducible run
Return type:

None

Parameters: