Running a Thermal Model with acis_thermal_check

acis_thermal_check models are adapted to each use case and run from the command line. This section provides a brief description on how to run the models, including what the various options are.

Where to Run the Models From

These models are run from a “Ska” Python stack. It can be one already installed or it can be one you installed yourself.

To run as acisdude on the HEAD LAN, simply issue the command setska in the terminal. If you want to run as yourself and you do not have this alias, you can set it up in your startup file:

# for csh/tsch

alias setska 'eval `/proj/sot/ska3/flight/bin/flt_envs -shell tcsh -ska`'

# for bash/zsh

alias setska='eval `/proj/sot/ska3/flight/bin/flt_envs -shell bash -ska`'

The ACIS Ops Ska stack often has versions of acis_thermal_check that are more up-to-date than in flight Ska. To use the ACIS Ops Ska stack as acisdude, issue the command acisska in the terminal. If you want to run as yourself and you do not have this alias, you can set it up in your startup file:

# for csh/tcsh

alias acisska 'source /data/acis/mambaforge/etc/profile.d/conda.csh; \
    setenv SKA /proj/sot/ska; conda activate ska'

# for bash

alias acisska='eval "$(/data/acis/mambaforge/bin/conda shell.bash hook)"; \
    export SKA=/proj/sot/ska; conda activate ska'

# for zsh

alias acisska='eval "$(/data/acis/mambaforge/bin/conda shell.zsh hook)"; \
    export SKA=/proj/sot/ska; conda activate ska’

In either case, all commands (e.g. dpa_check, dea_check, etc.) should be in your path after running one of the two aliases.

Base Command-Line Arguments

The following is a brief description of the base collection of command-line arguments accepted by a model using acis_thermal_check. Additional arguments may be added by individual models in the call to, as further detailed in Developing a New Thermal Model for Use with acis_thermal_check.

-h, --help            show this help message and exit
--outdir OUTDIR       Output directory. If it does not exist it will be created. Default: 'out'
--backstop_file BACKSTOP_FILE
                      Path to the backstop file. If a directory, the backstop file will be searched for within this directory.
                      Default: None
--oflsdir OFLSDIR     Path to the directory containing the backstop file (legacy argument). If specified, it will override the value
                      of the backstop_file argument. Default: None
--model-spec MODEL_SPEC
                      Model specification file. Defaults to the one included with the model package.
--pred_days PRED_DAYS
                      Days of prediction. Not used if a backstop file is supplied.
--days DAYS           Days of validation data. Default: 21
--run-start RUN_START
                      Reference time to replace run start time for regression testing. The default is to use the current time.
                      Default: None
--interrupt           Set this flag if this is an interrupt load.
--traceback           Enable tracebacks. Default: True
--pred-only           Only make predictions. Default: False
--val-only            Only run the validation check. Default: False
--set_time_now SET_TIME_NOW
                      Override what the current time is for testing purposes. Default: None
--verbose VERBOSE     Verbosity (0=quiet, 1=normal, 2=debug)
--T-init T_INIT       Starting temperature (degC). Default is to compute it from telemetry.
--state-builder STATE_BUILDER
                      StateBuilder to use (kadi|acis). Default: kadi
--nlet_file NLET_FILE
                      Full path to the Non-Load Event Tracking file that should be used for this model run. Only used with the 'acis'
                      StateBuilder.
--non_load_events NON_LOAD_EVENTS
                      ASCII text file containing non-load command events to use in case of an anomaly or other non-load situations.
                      Only used with the 'kadi' StateBuilder.
--version             Print version

Running Thermal Models: Examples

The most common application for any model based on acis_thermal_check is to run the model for a load. In this case, the minimum command-line arguments are the path to the backstop file and the output directory for the files:

[~]$ dpa_check --backstop_file=/data/acis/LoadReviews/2017/OCT1617/ofls --outdir=dpa_oct1617

In this case, we only supplied the directory containing the backstop file, assuming that there is only one present. If the load being reviewed is a return to science from a shutdown, or a replan due to a TOO, or any other interrupt, the thermal model should be run with the --interrupt flag to ensure that the continuity is properly handled:

[~]$ psmc_check --backstop_file=/data/acis/LoadReviews/2017/AUG3017/ofls --interrupt --outdir=psmc_aug3017

By default, the initial temperature for the model will be set using an average of telemetry in a few minutes around the run start time. However, the model can be started with a specific temperature value using the --T-init argument, which is assumed to be in degrees C:

[~]$ acisfp_check --backstop_file=/data/acis/LoadReviews/2017/OCT1617/ofls --outdir=acisfp_oct1617 --T-init=22.0

If necessary, thermal model runs can be run for a particular load for predictions only, using the --pred-only flag:

[~]$ dea_check --backstop_file=/data/acis/LoadReviews/2017/AUG3017/ofls --outdir=dea_aug3017 --pred-only

Or, if you want to run with validation only, use the --val-only flag:

[~]$ dea_check --backstop_file=/data/acis/LoadReviews/2017/AUG3017/ofls --outdir=dea_aug3017 --val-only

Finally, if one wishes to run validation without prediction for a specific load, simply omit the backstop_file argument. It may make sense here to supply a run_start argument, if one wants a different time than the current time to validate:

[~]$ dpa_check --run-start=2019:300:12:50:00 --outdir=validate_dec2019

A page describing how to use these options if something goes wrong with the model runs performed by the ACIS Ops lr script can be found at What to Do When Something Goes Wrong?.

Running Thermal Models in Case of a Radiation Shutdown

If a radiation shutdown has occurred and SCS-107 has been run as a result, the science loads will be halted but the vehicle loads will continue to execute. If a new science load needs to be reviewed which has a vehicle load as its continuity, the thermal model scripts can be run in the same way as above. Similarly, if there is a need to run a second set of vehicle loads which have to be approved at a load review, the thermal model scripts can also be run in the same way as above, as the new vehicle loads will not contain any science commands but the rest of the commands will be picked up appropriately.

Running Thermal Models in Case of an Anomaly

If a spacecraft anomaly has occurred, ACIS has (hopefully) safed itself and we are either in a Normal Sun Mode (NSM) or a Bright Star Hold (BSH). In this circumstance, both the science and vehicle loads are halted. After we have come up on comm and the time and nature of the safing action has been determined, it will be entered into the Chandra Command Events Sheet. From this point on, one can determine the thermal prediction for a given temperature by running the corresponding thermal model script without a backstop file or OFLS directory:

[~]$ dpa_check --outdir=bright_star_hold

By default, this run will predict temperatures forward in time assuming the same states and projected ephemeris for 5 days. If you want to change the number of days it predicts forward, choose a different value for the --pred_days argument:

[~]$ dpa_check --outdir=bright_star_hold --pred_days=3.5

Running Thermal Models with Non-Load Events Files

Suppose, however, that non-load commands are executed before a new science load is reviewed. This may take the form of a slew to a new attitude, or a long ECS measurement. Once these commands are approved, they will appear in the Chandra Command Events Sheet. However, if you want to determine the thermal prediction ahead of time for these types of events, you can construct an ASCII text file which includes them.

Note

An interactive Non-Load Events Builder web page is available for constructing this file without having to hand-edit the text format. It lets you add “MAN”, “ECS”, and “OBSID” events through a form, converts between attitude quaternions and RA/Dec/Roll, validates values (e.g. ECS duration, obsid range, quaternion normalization) as you go, and generates the finished file for copying.

Three types of events are supported by this file:

  • “MAN” events: this is an event where a manuever to a specified attitude quaternion is executed at a particular time.

  • “ECS” events: this is an event where a long ECS measurement is executed, starting at a particular time.

  • “OBSID” events: this is an event where a change to a specified obsid occurs at a particular time.

The format of the non-load events file is a simple text file which begins by specifying a line with the following columns:

# event_type        date    params

To include a “MAN” event, specify the event type as “MAN”, add a time in the YYY:DOY:HH:MM:SS.ddd format, and specify the attitude quaternion as a set of 4 floats, separated by commas. It should look like this:

# event_type        date    params
MAN     2024:025:12:59:00.000   -0.34908674,-0.72584198,-0.59196114,0.02956150

If you wanted to add an “ECS” event to it, specify the event time as “ECS”, add a time in the YYY:DOY:HH:MM:SS.ddd format, and specify the “CAP identifier” you will use as well as the number of hours that the ECS measurement will run, comma-separated. The available CAP identifiers are:

  • “2”: A 2-CCD ECS measurement, corresponding to “CAPXXXX_acis_2_RTS_ECS_SCS_v18.doc”

  • “3A”: A 3-CCD ECS measurement, corresponding to “CAPXXXX_aciss_3A_RTS_ECS_SCS_v18.doc”

  • “3B”: A 3-CCD ECS measurement, corresponding to “CAPXXXX_acisi_3B_RTS_ECS_SCS_v18.doc”

  • “4”: A 4-CCD ECS measurement, corresponding to, “CAPXXXX_acisi_4_RTS_ECS_SCS_v18.doc”

  • “4ALT”: A 4-CCD ECS measurement, corresponding to “CAPXXXX_aciss_4ALT_RTS_ECS_SCS_v18.doc”

  • “5”: A 5-CCD ECS measurement, corresponding to “CAPXXXX_acisi_5_RTS_ECS_SCS_v18.doc”

  • “6”: A 6-CCD ECS measurement, corresponding to “CAPXXXX_acisi_6_RTS_ECS_SCS_v18.doc”

If we were to add a line for a “3B” ECS measurement running for 24 hours to the previous maneuver line above, the non-load events file would look like this:

# event_type        date    params
MAN     2024:025:12:59:00.000   -0.34908674,-0.72584198,-0.59196114,0.02956150
ECS     2024:025:19:00:00.000   3B,24

To include an “OBSID” event, specify the event type as “OBSID”, add a time in the YYY:DOY:HH:MM:SS.ddd format, and specify the OBSID. If you were to add it to the two lines above, it would look like this:

# event_type        date    params
MAN     2024:025:12:59:00.000   -0.34908674,-0.72584198,-0.59196114,0.02956150
ECS     2024:025:19:00:00.000   3B,24
OBSID   2024:025:19:03:46.739   62620

Once you have created the file, save it to your chosen name, and then point whatever thermal model script you are running to that file using the --non_load_events argument:

[~]$ dpa_check --outdir=bright_star_hold --non_load_events=non_load_events.txt

Running Multiple Thermal Models at Once

If you want to run several thermal models together against the same backstop file or other command-line options, use multi_model_check. It runs each of the models (currently dpa_check, dea_check, psmc_check, and acisfp_check) with the arguments you give it, placing each model’s full set of outputs into its own subdirectory of a single output directory (out_dpa, out_dea, out_psmc, and out_fptemp, respectively). It then writes a combined index.html in that output directory showing each model’s prediction plot, linked to that model’s own report page.

Any argument accepted by the individual model scripts (e.g. --backstop_file, --interrupt, --state-builder, --non_load_events) can be passed to multi_model_check and will be forwarded, unchanged, to every model that is run, with the exception of --outdir, which instead controls where the per-model subdirectories and the combined index page are written:

[~]$ multi_model_check --backstop_file=/data/acis/LoadReviews/2017/OCT1617/ofls --outdir=multi_oct1617

--T-init is handled specially, since passing a single starting temperature to every model is rarely correct. A bare value is used as the default starting temperature for any model that doesn’t have its own override, and a MODEL=TEMP entry sets the starting temperature for just that one model (choices for MODEL are dpa, dea, psmc, and acisfp). Models with no value at all, and no default given, compute their starting temperature from telemetry as usual. For example, to give all models a starting temperature of -50 degC except for acisfp, which should start at -105 degC:

[~]$ multi_model_check --backstop_file=/data/acis/LoadReviews/2017/OCT1617/ofls --outdir=multi_oct1617 --T-init -50.0 acisfp=-105.0

If any individual model fails, multi_model_check still runs the rest, marks the failed model(s) as such on the combined index page, and exits with a non-zero status once all of the models have finished.

Passing --web instead writes the output to ACIS Ops’ web-accessible test area, /proj/web-cxc/htdocs/acis/Thermal/tests/<year>/<outdir>, and prints the URL where the combined report will be visible once it has been published.