Chandra commanded states database

Warning

the commanded states database and package described here is

discontinued and no longer supported. Instead use the

Kadi commands and states package.

This suite of tools provides the interface for creation and maintenance of the Chandra commanded states database. This database provides the commanded state of Chandra from 2002 through to the end of all approved command loads that are ingested to the OFLS database. The database thus contains both the definitive state and a predictive state at any time.

A commanded state is an interval of time over which certain parameters of interest (obsid, SIM-Z position, commanded attitude, ACIS power configuration, etc) are invariant. This database is useful for several reasons:

  1. It goes out into the future to the extent of approved load products

  2. It is extremely fast and the commanded states for the entire mission can be retrieved in a few seconds.

  3. It takes care of the difficult task of tracking which command loads and mission planning products actually ran on the spacecraft.

  4. It provides a path from each command back to the mission planning products responsible for that command.

Note: only a select set of commands that affect the commanded state are tracked.

Database access

A convenient linux command line tool to access the commanded states database is available via the get_cmd_states tool. For example:

% get_cmd_states --start 2012:121 --stop 2012:122 --vals obsid,simpos
datestart             datestop              tstart        tstop         obsid simpos
2012:121:10:32:46.375 2012:121:13:17:43.375 452169232.559 452179129.559 54646 -99616
2012:121:13:17:43.375 2012:121:15:08:21.375 452179129.559 452185767.559 14212 75624
2012:121:15:08:21.375 2012:121:16:04:07.192 452185767.559 452189113.376 13331 75624
2012:121:16:04:07.192 2012:123:11:23:20.985 452189113.376 452345067.169 13847 75624

To access the commanded states database from within a Python script use the fetch_states() function. For instance:

>>> from chandra_cmd_states import fetch_states
>>> states = fetch_states('2011:100', '2011:101')
>>> states[['datestart', 'datestop', 'obsid', 'simpos']]
array([('2011:100:11:53:12.378', '2011:101:00:23:01.434', 13255, 75624),
       ('2011:101:00:23:01.434', '2011:101:00:26:01.434', 13255, 91272),
       ('2011:101:00:26:01.434', '2011:102:13:39:07.421', 12878, 91272)],
      dtype=[('datestart', '|S21'), ('datestop', '|S21'), ('obsid', '<i8'), ('simpos', '<i8')])

cmd_states table

The main table is the cmd_states table with the following columns:

Name

Type

Size

datestart

varchar

21

datestop

varchar

21

obsid

int

4

power_cmd

varchar

11

si_mode

varchar

8

pcad_mode

varchar

6

vid_board

bit

1

clocking

bit

1

fep_count

int

4

ccd_count

int

4

simpos

int

4

simfa_pos

int

4

pitch

float

8

ra

float

8

dec

float

8

roll

float

8

q1

float

8

q2

float

8

q3

float

8

q4

float

8

trans_keys

varchar

60

hetg

varchar

4

letg

varchar

4

dither

varchar

4

cmds table

In addition the cmds table maintains a history (definitive and predictive) of every on-board command that will affect the commanded state. The command parameter values are stored in secondary tables. In addition to commands from the mission loads there are also “non-load” commands which result from autonomous or ground commanding (e.g. SCS107, Normal Sun Mode transitions, anomaly recovery, etc).

name

type

length

id (PK)

int

4

timeline_id

int

4

date

char

21

time

float

8

cmd

varchar

12

tlmsid

varchar

10

msid

varchar

8

vcdu

int

4

step

int

4

scs

int

4

cmd_intpars and cmd_fltpars

name

type

length

cmd_id (FK)

int

4

timeline_id (FK)

int

4

name

varchar

15

value

int/float

8

Note that unlike the commanded states table, the cmds tables are only available on Sybase on the HEAD network.

Tools

chandra_cmd_states functions

The following key functions within the chandra_cmd_states module are available for users.

get_cmds

chandra_cmd_states.get_cmds(datestart='1998:001:00:00:00.000', datestop='2099:001:00:00:00.000', db=None, update_db=None, timeline_loads=None, mp_dir='/Users/aldcroft/ska/data/mpcrit1/mplogs')

Get all commands with datestart < date <= datestop using DBI object db. This includes both commands already in the database and new commands. If update_db is True then update the database cmds table to reflect new and/or deleted commands.

Use datestart < date instead of <= because in typical ussage datestart is the start date of a state and one wants commands after those that generated the original state transition.

The timeline_loads table is relied upon as the final authority of which commands were (will be) run on-board. The timeline_load values can change in the database in the event of an autonomous or ground-commanded load segment interrupt. The strategy is to regenerate the list of commands that were (will be) run on-board using commands already in the database supplemented by backstop commands found in the SOTMP repository of load products.

Parameters:

  • datestart – start date (Chandra.Time ‘date’ str) (default=1998:001)

  • datestop – stop date (default=2099:001)

  • db – Ska.DBI.DBI object (required)

  • update_db – update the ‘cmds’ table

Returns:

cmds

Return type:

list of dicts

fetch_states

chandra_cmd_states.fetch_states(start=None, stop=None, vals=None, allow_identical=False, dbi='hdf5', server=None, user='aca_read', database='aca')

Get Chandra commanded states over a range of time as a structured array.

Examples:

# Get commanded states using the default HDF5 table
>>> from chandra_cmd_states import fetch_states
>>> states = fetch_states('2011:100:12:00:00', '2011:101:12:00:00', vals=['obsid', 'simpos'])
>>> states[['datestart', 'datestop', 'obsid', 'simpos']]
array([('2011:100:11:53:12.378', '2011:101:00:23:01.434', 13255, 75624),
       ('2011:101:00:23:01.434', '2011:101:00:26:01.434', 13255, 91272),
       ('2011:101:00:26:01.434', '2011:102:13:39:07.421', 12878, 91272)],
      dtype=[('datestart', '|S21'), ('datestop', '|S21'), ('obsid', '<i8'), ('simpos', '<i8')])

# Get same states from Sybase (25 times slower)
>>> states2 = fetch_states('2011:100:12:00:00', '2011:101:12:00:00', vals=['obsid', 'simpos'], dbi='sybase')
>>> states2 == states
array([ True,  True,  True], dtype=bool)
Parameters:

  • start – start date (default=Now-10 days)

  • stop – stop date (default=None)

  • vals – list of state columns for output

  • allow_identical – Allow identical states from cmd_states table

  • dbi – database interface (default=hdf5)

  • server – DBI server or HDF5 file (default=None)

  • user – sybase database user (default=’aca_read’)

  • database – sybase database (default=Ska.DBI default)

get_states

chandra_cmd_states.get_states(state0, cmds, exclude=None)

Get states resulting from the spacecraft commands cmds starting from an initial state0.

State keys in the exclude list or set will be excluded from causing a transition. This is useful if a state parameter (e.g. simfa_pos) is not of interest. An excluding parameter will have incorrect values in the returned states.

A state is a dict with key values corresponding to the following database schema:

Name

Type

Size

datestart

varchar

21

datestop

varchar

21

obsid

int

4

power_cmd

varchar

11

si_mode

varchar

8

pcad_mode

varchar

6

vid_board

bit

1

clocking

bit

1

fep_count

int

4

ccd_count

int

4

simpos

int

4

simfa_pos

int

4

pitch

float

8

ra

float

8

dec

float

8

roll

float

8

q1

float

8

q2

float

8

q3

float

8

q4

float

8

trans_keys

varchar

60

letg

varchar

4

hetg

varchar

4

dither

varchar

4

The input commands must be a list of dicts including keys date, vcdu, cmd, params, time. See also Ska.ParseCM.read_backstop().

Parameters:

  • state0 – initial state.

  • cmds – list of commands

  • ignore – list or set of state keys to ignore

Returns:

recarray of states starting with state0 (which might be modified)

interpolate_states

chandra_cmd_states.interpolate_states(states, times)

Interpolate states np.recarray at given times.

Parameters:

  • states – states (np.recarray)

  • times – times (np.array or list)

Returns:

states view at times

reduce_states

chandra_cmd_states.reduce_states(states, cols, allow_identical=True)

Reduce the input states so that only transitions in the cols columns are noticed.

Parameters:

  • states – numpy recarray of states

  • cols – notice transitions in this list of columns

  • allow_identical – allow null transitions between apparently identical states

Returns:

numpy recarray of reduced states

API docs

The full API docs for chandra_cmd_states are available here: