Astro.Ephemeris.Downloader (Astro v2.5.0)

Copy Markdown View Source

Downloads JPL DE-series SPK binary ephemeris files from NASA NAIF.

A compact ephemeris covering 1900–2100 is bundled with the library (see Astro.Ephemeris.Subset), so no download is required for dates in that range.

Downloading is needed only to obtain the full de440s.bsp kernel (~32 MB), which extends coverage to 1849–2150. When present it takes precedence over the bundled ephemeris. It can be fetched with mix astro.download_ephemeris, and is otherwise downloaded on demand at application start and cached on disk for subsequent runs.

Cache location

By default the file is cached under the user cache directory as resolved by :filename.basedir(:user_cache, "astro"). If that directory cannot be created (for example, the OS user has no writable home directory — a common situation for service accounts in containers), Astro falls back to <System.tmp_dir!()>/astro and logs a warning. The cache location can be overridden by setting the :ephemeris application environment key:

config :astro,
  ephemeris: "/path/to/de440s.bsp"

When the configured path already contains a valid ephemeris file no download is performed. Setting an explicit path is the recommended approach for production deployments, since the user-cache fallback to tmp is ephemeral.

Source URL

The default download source is the NASA NAIF generic kernels archive:

https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/de440s.bsp

This can be overridden by setting the :ephemeris_url application environment key (for example, when mirroring the file inside an air-gapped environment).

Summary

Functions

download(path)

Downloads the ephemeris file to path.

ensure_ephemeris(path)

Ensures the ephemeris file is available on disk, downloading it if necessary.

ephemeris_path()

Returns the resolved ephemeris file path.

Functions

download(path)

@spec download(String.t()) :: {:ok, String.t()} | {:error, term()}

Downloads the ephemeris file to path.

The destination directory is created if it does not already exist. On HTTP error or network failure the partial file (if any) is removed.

Arguments

  • path is the destination file path.

Returns

  • {:ok, path} on success.

  • {:error, reason} if the download failed. reason is a tuple describing the failure, e.g. {:http_status, 404}, {:cache_dir_unwritable, dir, posix_reason}, or an :httpc error term.

ensure_ephemeris(path)

@spec ensure_ephemeris(String.t()) :: {:ok, String.t()} | {:error, term()}

Ensures the ephemeris file is available on disk, downloading it if necessary.

Arguments

  • path is the destination file path.

Returns

  • {:ok, path} if the file already exists or was downloaded successfully.

  • {:error, reason} if the file is missing and the download failed.

ephemeris_path()

@spec ephemeris_path() :: String.t()

Returns the resolved ephemeris file path.

Resolution order:

  • The :ephemeris application environment key, if set.

  • priv/de440s.bsp — the full JPL kernel, if it has been downloaded (used during library development and when running from a checkout, and by anyone wanting coverage beyond the bundled span).

  • priv/de440s-astro.bsp — the compact ephemeris bundled with the library, covering 1900–2100. Present in every hex install, so no download is required for dates in that span.

  • The user cache directory as resolved by :filename.basedir(:user_cache, "astro").

  • <System.tmp_dir!()>/astro if the user cache directory cannot be created.

Returns

  • A binary path string.