This document describes the set of plugins that provide exo-atmosphere source (sun and moon) position calculations in DIRSIG5.

Ephemeris plugins are explicitly supplied in a JSIM file via the plugin list. When using a DIRSIG4 era XML simulation description, the ephemeris plugin is automatically configured via the options available inside the .atm file.

Important The ephemeris plugins are called for every temporal state change in DIRSIG5. That means every unique capture time (e.g. array read out) will get an updated Sun and/or Moon position. Unlike in DIRSIG4, there is no temporal quantization in these ephemeris updates. However, each ephemeris plugin is in charge of it’s own console notifications and some will limit the number notifications to avoid overwhelming the output.

SPICE Ephemeris

The "SPICE" ephemeris model is the primary and preferred plugin to position the Sun and Moon. It is a wrapper around NASA’s SPICE observation geometry information system. This code and set of supporting databases is used extensively by NASA for planning observations of exo-atmospheric objects and in computing the trajectories of spacecraft leaving Earth and heading to various objects in the solar system and beyond.

Input Kernel Files

This plugin is dependent upon a set of input kernel files that are available from the SPICE website, but are packaged with DIRSIG for convenience. This includes a simplified copy of the DE430 database (includes only the Sun and Moon), a leap second definition file and a planetary constants file. These files are located in the lib/data/spice folder inside the DIRSIG installation.

There are a set of optional inputs for the SPICE plugin that allow you to override the supplied/default SPICE kernel files:

spk_filename

This optional variable contains the path to a SPICE SPK (ephemeris) kernel file.

pck_filename

This optional variable contains the path to a SPICE PCK (planetary constants) kernel file.

lsk_filename

This optional variable contains the path to a SPICE LSK (leap second) kernel file.

Update Notifications

The solar and lunar state are update for every temporal state change, but this plugin does not output a console notification for every update by default. In the case of a continuous read-out focal plane (video, pushbroom scanner, etc.), a large number of ephemeris update messages would be generated. To avoid flooding the output with these notifications, the plugin tracks the internal simulation date/time for when the last notification message was generated. When a plugin update request is made during a state change, the requested date/time will be compared to this last date/time. If those internal simulation times differ by a temporal threshold, a new notification message will be generated and the last date/time updated. By default, that threshold is 60.0 seconds, which means a simulation with tasks spanning less than 60 seconds (internal simulation time) will only see a single notification. However, this temporal threshold can be overridden by providing the update_delta variable in the JSON inputs for the plugin.

Tip If you want to get a notification message for every update, set the update_delta to 0.0.

Example Configuration

The following configuration example includes an override for the LSK (leap second) kernel file and to set the notification update threshold to 0.2 seconds:

  "plugin_list": [
    ...
    {
      "name" : "SpiceEphemeris",
      "inputs" : {
        "lsk_filename" : "/home/joeuser/naif0011_modified.tls",
        "update_delta" : 0.2
      }
    },
    ...
  }
Important As a reminder, the solar and lunar state will be updated for every temporal state change. The update_state variable only controls how often this plugin writes a notification message to the output.

Simple Solar Ephemeris

This is a simple solar-only prediction plugin that is based on the SunCalc JavaScript code written by Vladimir Agafonkin. The JS version of the calculations are released under a BSD license. Original code (c) 2011-2013, Vladimir Agafonkin.

Example Configuration

There are no inputs for the Simple Solar plugin at this time:

  "plugin_list": [
    ...
    {
      "name" : "SimpleSolarEphemeris",
      "inputs" : {
      }
    },
    ...
  }
Note This plugin does not support moon positioning.

Fixed Ephemeris

The "fixed" ephemeris model is used when the user wants to directly supply fixed (static) positions of the Sun and Moon. This is frequently used to setup specific illumination conditions for testing, verification and validation.

Note Remember that the position of the Sun and Moon are fixed (static) as a function of time, making the position of these objects independent of the time of day.

The Sun and Moon position are defined in terms of zenith (degrees, declination) and azimuth (degrees, East of North) angles. The moon phase is described in terms of fraction, with 0 being a new moon condition and 1 being a full moon condition.

Example Configuration

The parameters are directly supplied in the JSIM inputs for the plugin:

  "plugin_list": [
    ...
    {
      "name" : "FixedEphemeris",
      "inputs" : {
         "solar_zenith" : 45,
         "solar_azimuth" : 90,
         "lunar_zenith" : 45,
         "lunar_azimuth" : 270,
         "lunar_fraction" : 0.5
      }
    },
    ...
  }

Data-Driven Ephemeris

The "data-driven" ephemeris model is used when the user wants to directly supply the position of the Sun and Moon as a function of time. This is frequently used to setup specific illumination conditions for testing, verification and validation.

Example Configuration

The data is supplied in an external, ASCII/Text file that is referenced in the JSIM inputs for the plugin:

  "plugin_list": [
    ...
    {
      "name" : "DataDrivenEphemeris",
      "inputs" : {
         "filename" : "ephemeris_data.txt"
      }
    },
    ...
  }

The external ASCII/Text file is formatted as a series of lines defining the sun and moon state as a function of time. Each line contains 6 fields:

  1. The date/time as an ISO-8601 string

  2. The solar zenith angle (degrees, declination)

  3. The solar azimuth angle (degrees, East of North)

  4. The lunar zenith angle (degrees, declination)

  5. The lunar azimuth angle (degrees, East of North)

  6. The lunar phase fraction (fraction, 0 → 1).

The moon phase is described in terms of fraction, with 0 being a new moon condition and 1 being a full moon condition.

Positions are not interpolated for times between entries. The plugin will choose the entry with the date/time closest to the requested state date/time but without going over. Consider the following input file:

2000-08-01T12:59:50.0000-05:00 55.0 178.0 120.0 0.0 0.0
2000-08-01T13:00:00.0000-05:00 60.0 180.0 120.0 0.0 0.0
2000-08-01T14:00:00.0000-05:00 55.0 182.0 120.0 0.0 0.0

For the following date/time scenarios:

2000-08-01T12:00:00.0000-05:00

This time is before the first entry. The first entry will be used.

2000-08-01T12:59:50.0000-05:00

This time is equal to the first entry. The first entry will be used.

2000-08-01T12:59:55.0000-05:00

This time is greater than the first entry, but less than the second entry. The first entry will be used.

2000-08-01T13:00:00.0000-05:00

This time is equal to the second entry. The second entry will be used.

2000-08-01T13:30:00.0000-05:00

This time is greater than the second entry, but less than the third entry. The second entry will be used.

2000-08-01T15:00:00.0000-05:00

This time is beyond to the last (third) entry. The third (last) entry will be used.