Proseco

Proseco is a Python package to allow for selection of acquisition stars, guide stars, and fiducial lights for the Chandra ACA star tracker during operations.

For acquisition stars and fid lights, proseco uses a probabilistic evalation of the catalog to minimize the chance of a safing event and loss of science. For guide stars, proseco uses a staged approach to select optimal stars.

Getting Started

From a top-level perspective the main interface into proseco is a single function get_aca_catalog().

Arguments

As can be seen from the docstring, get_aca_catalog() takes a long list of arguments which are required to fully specify:

Required

Argument

Description

obsid
obsid (default=0)

OR

att

attitude (any object that can initialize Quat)

n_acq

desired number of acquisition stars (default=8)

n_fid

desired number of fid lights (req’d unless obsid spec’d)

n_guide

desired number of guide stars + monitor windows (see note below)

man_angle

maneuver angle (deg)

t_ccd_acq

ACA CCD temperature for acquisition (degC)

t_ccd_guide

ACA CCD temperature for guide (degC)

date

date of acquisition (any DateTime-compatible format)

dither_acq

acq dither size (2-element sequence (y, z), arcsec)

dither_guide

guide dither size (2-element sequence (y, z), arcsec)

detector

‘ACIS-S’ | ‘ACIS-I’ | ‘HRC-S’ | ‘HRC-I’

Optional

Argument

Description

target_name

Target name, e.g. from the OR list (str)

duration

Observation duration (secs)

man_angle_next

Manvr angle to next attitude after observation (deg, default=180)

sim_offset

SIM translation offset from nominal [steps] (default=0)

focus_offset

SIM focus offset [steps] (default=0)

target_offset

target offset including dynamical offset (y, z, deg)

include_ids_acq

int or list of AGASC IDs of stars to include in acq catalog

include_halfws_acq

int or list of acq halfwidths corresponding to include_ids

exclude_ids_acq

int or list of AGASC IDs of stars to exclude from acq catalog

include_ids_guide

int or list of AGASC IDs of stars to include in guide catalog

exclude_ids_guide

int or list of AGASC IDs of stars to exclude from guide catalog

include_ids_fid

int or list of fid IDs to include from fid catalog

exclude_ids_fid

int or list of fid IDs to exclude from fid catalog

img_size_guide

readout window size for guide stars (6, 8, or None)

stars

table of AGASC stars (will be fetched from agasc if None)

monitors

N x 5 array of monitor star specifications (see Monitor stars)

t_ccd_eff_acq

ACA CCD effective temperature for acquisition (degC)

t_ccd_eff_guide

ACA CCD effective temperature for guide (degC)

dark

1024x1024 dark image (e-/sec, default=None => auto-fetch)

dark_date

date of dark cal (str)

The input n_guide parameter represents the number of slots available for the combination of guide stars and monitor windows (including both fixed and tracking monitor windows). In most normal situations, n_guide is equal to 8 - n_fid. The n_guide parameter is confusingly named but this is because the actual number of guide stars is not known in advance in the case of auto-conversion from a monitor request to a guide star. In actual practice, what is normally known is how many slots are available for the combination of guide stars and monitor windows, so this makes the call to catalog creation simpler.

Within the include_halfws_acq list, one can supply the value 0 for a star instead of a typical legal value such as 60 or 120. In that case proseco will run the normal optimization and choose the best halfwidth for that included star. If the include_halfws_acq argument is not supplied or set to [] then all halfwidths will be chosen by proseco.

The two optional effective temperatures are normally not supplied and will be computed based on the current ACA penalty limit. Likewise, the dark_date is normally derived as the date of the most recent dark cal before date. However, for reproducing catalog selection it may be required to provide all of those arguments.

Debug

Argument

Description

optimize

optimize star catalog after initial selection (default=True)

verbose

provide extra logging info (mostly calc_p_safe) (default=False)

print_log

print the run log to stdout (default=False)’

raise_exc

raise exception if it occurs in processing (default=True)

Examples

For generating a catalog corresponding to an actual scheduled observation, the easiest strategy is to simply provide the obsid as a parameter. Proseco will then fetch all necessary data via the mica.starcheck archive. This requires installation of the cmd_states.db3 and starcheck.db3 data files into the correct locations. See Data requirements for details.

>>> from proseco.catalog import get_aca_catalog
>>> aca = get_aca_catalog(19387)
>>> aca
<ACACatalogTable length=11>
 slot  idx     id    type  sz   p_acq    mag    maxmag   yang     zang    dim   res  halfw
int64 int64  int64   str3 str3 float64 float64 float64 float64  float64  int64 int64 int64
----- ----- -------- ---- ---- ------- ------- ------- -------- -------- ----- ----- -----
    0     1        2  FID  8x8   0.000    7.00    8.00  -773.20 -1742.03     1     1    25
    1     2        4  FID  8x8   0.000    7.00    8.00  2140.23   166.63     1     1    25
    2     3        5  FID  8x8   0.000    7.00    8.00 -1826.28   160.17     1     1    25
    3     4 38280776  BOT  6x6   0.985    8.77   10.27 -2254.09 -2172.43    20     1   160
    4     5 37879960  BOT  6x6   0.984    9.20   10.70  -567.34  -632.27    20     1    80
    5     6 37882072  BOT  6x6   0.956   10.16   11.66  2197.62  1608.89    20     1    80
    6     7 37879992  ACQ  6x6   0.933   10.41   11.91   318.47 -1565.92    20     1    60
    7     8 37882416  ACQ  6x6   0.901   10.41   11.91   481.80  2204.44    20     1    80
    0     9 37880176  ACQ  6x6   0.584   10.62   12.12   121.33 -1068.25    20     1    60
    1    10 37881728  ACQ  6x6   0.057   10.76   12.26  2046.89  1910.79    20     1   100
    2    11 37880376  ACQ  6x6   0.084   10.80   12.30 -1356.71  1071.32    20     1   100

The catalog represented by the aca object is the “merged” version of the acquisition, guide, and fid catalogs. It corresponds to the uplinked catalog and what is reviewed in starcheck.

The component catalogs are available in acqs, guides, and fids attributes:

>>> aca.acqs
<AcqTable length=8>
   id        ra       dec      yang     zang     row   ...  slot  maxmag  dim   sz   res
 int32    float64   float64  float64  float64  float64 ... int64 float32 int64 str3 int64
-------- ---------- -------- -------- -------- ------- ... ----- ------- ----- ---- -----
38280776 188.538857 3.077618 -2254.09 -2172.43  460.83 ...     3   10.27    20  6x6     1
37879960 188.579307 2.444460  -567.34  -632.27  119.53 ...     4   10.70    20  6x6     1
37882072 188.584100 1.455829  2197.62  1608.89 -436.73 ...     5   11.66    20  6x6     1
37879992 188.222720 2.414842   318.47 -1565.92  -58.45 ...     6   11.91    20  6x6     1
37882416 189.011634 1.723922   481.80  2204.44  -90.05 ...     7   11.91    20  6x6     1
37880176 188.364941 2.371052   121.33 -1068.25  -18.64 ...     0   12.12    20  6x6     1
37881728 188.675737 1.435994  2046.89  1910.79 -406.36 ...     1   12.26    20  6x6     1
37880376 189.086022 2.319189 -1356.71  1071.32  278.91 ...     2   12.30    20  6x6     1

>>> aca.guides
<GuideTable length=3>
   id        ra       dec      yang     zang     row   ...  maxmag p_acq  dim   res  halfw  sz
 int32    float64   float64  float64  float64  float64 ... float32 int64 int64 int64 int64 str3
-------- ---------- -------- -------- -------- ------- ... ------- ----- ----- ----- ----- ----
38280776 188.538857 3.077618 -2254.09 -2172.43  460.83 ...   10.27 0.000     1     1    25  6x6
37879960 188.579307 2.444460  -567.34  -632.27  119.53 ...   10.70 0.000     1     1    25  6x6
37882072 188.584100 1.455829  2197.62  1608.89 -436.73 ...   11.66 0.000     1     1    25  6x6

>>> aca.fids
<GuideTable length=3>
   id        ra       dec      yang     zang     row   ...  maxmag p_acq  dim   res  halfw  sz
 int32    float64   float64  float64  float64  float64 ... float32 int64 int64 int64 int64 str3
-------- ---------- -------- -------- -------- ------- ... ------- ----- ----- ----- ----- ----
38280776 188.538857 3.077618 -2254.09 -2172.43  460.83 ...   10.27 0.000     1     1    25  6x6
37879960 188.579307 2.444460  -567.34  -632.27  119.53 ...   10.70 0.000     1     1    25  6x6
37882072 188.584100 1.455829  2197.62  1608.89 -436.73 ...   11.66 0.000     1     1    25  6x6

Each of the individual catalogs also has a warnings attribute that is a list of any warnings which occurred in processing:

>>> aca.guides.warnings
['WARNING: Selected only 3 guide stars versus requested 5']

Finally, in the event of an unhandled exception within the acq, guide, and fid selection code, there is an exception attribute on the top-level aca object. If an exception occurs then the output table will have zero length with a single id column:

>>> aca = get_aca_catalog(19387, detector='FAIL')
>>> len(aca['id'])
0

>>> print(aca.exception)
Traceback (most recent call last):
  File "/Users/aldcroft/git/proseco/proseco/catalog.py", line 43, in get_aca_catalog
    aca = _get_aca_catalog(obsid=obsid, **kwargs)
  File "/Users/aldcroft/git/proseco/proseco/catalog.py", line 102, in _get_aca_catalog
    aca.fids = get_fid_catalog(acqs=aca.acqs, **fid_kwargs)
  File "/Users/aldcroft/git/proseco/proseco/fid.py", line 51, in get_fid_catalog
    fids.meta['cand_fids'] = fids.get_fid_candidates()
  File "/Users/aldcroft/git/proseco/proseco/fid.py", line 258, in get_fid_candidates
    self.meta['sim_offset'])
  File "/Users/aldcroft/git/proseco/proseco/fid.py", line 416, in get_fid_positions
    ypos = FID.fidpos[detector][:, 0]
KeyError: 'FAIL'

Monitor stars

Monitor stars in a catalog are specified withe the monitors keyword. This can accept a list of lists (or 2-d array of floats) in the form:

[
  [coord0, coord1, coord_type, mag, function],  # Monitor window 1 (req'd)
  [coord0, coord1, coord_type, mag, function],  # Monitor windows 2, 3, ... N (optional)
  ..
]

If passed as a list of lists, the input will be converted to a numpy 2-d array (np.array(monitors)) which will have shape (N, 5) where N is the number of monitor windows. Enumeration codes related to the monitors keyword are defined in the module proseco.characteristics:

class MonFunc:
    AUTO = 0
    GUIDE = 1
    MON_TRACK = 2
    MON_FIXED = 3

class MonCoord:
    RADEC = 0
    ROWCOL = 1
    YAGZAG = 2

The 5 values [coord0, coord1, coord_type, mag, function] in a monitor window specification are:

  • coord0: first coordinate: RA (deg), row (pixel), or Y angle (arcsec))

  • coord1: second coordinate: Dec (deg), column (pixel), or Z angle (arcsec)

  • coord_type:

    • MonCoord.RADEC: RA/Dec (deg)

    • MonCoord.ROWCOL: row/column (pixel)

    • MonCoord.YAGZAG: Y/Z angle (arcsec)

  • mag: star magnitude (used for commanded MAXMAG for monitor window requests)

  • function:

    • MonFunc.AUTO: Schedule as a guide star if it meets requirements and does not introduce critical warnings, otherwise schedule as a monitor window that tracks the brightest star.

    • MonFunc.GUIDE: Schedule as a guide star if a corresponding star is found in the AGASC within 2 arcsec, otherwise raise an exception.

    • MonFunc.MON_TRACK: Schedule as monitor window that tracks the brightest star.

    • MonFunc.MON_FIXED: Schedule as monitor window that is fixed on the CCD

      with no tracking.

The typical use cases are as follows:

  • OR-specified monitor target with function=MonFunc.AUTO

    • This is the most common configuration and lets proseco decide how to schedule the OR.

    • Coordinates provided as RA, Dec.

  • OR-specified monitor target function=MonFunc.GUIDE

    • Force scheduling as a guide star in a case where proseco would normally schedule as a monitor window.

    • For instance a star where the observer provides information on mag or variability that is different from the AGASC (e.g. brighter).

  • OR-specified monitor target function=MonFunc.MON_TRACK

    • Force scheduling as a monitor window in a case where proseco would normally schedule as a guide star.

    • For instance a star where the observer provides information on mag or variability that is different from the AGASC (e.g. fainter or more variable).

  • Fixed-location ER monitor window function=MonFunc.MON_FIXED

    • Used for engineering investigation, e.g. looking at a specific flickering pixel.

    • coord0,1 as Y/Z angle or (most commonly) row/column.

Data requirements

Required data files are:

$SKA/data/agasc/proseco_agasc_<latest>.h5
$SKA/data/mica/archive/aca_dark/<YYYYddd>/image.fits
$SKA/data/mica/archive/aca_dark/<YYYYddd>/properties.json

The following optional data files are needed for specifying only an obsid in the call to get_aca_catalog():

$SKA/data/cmd_states/cmd_states.db3
$SKA/data/mica/archive/starcheck/starcheck.db3

See Syncing Ska data for details on automatically syncing these files for a standalone linux or Mac environment. For Matlab tools on Windows a separate mechanism will be provided.

Environment Variables

The following environment variables are used by proseco:

  • AGASC_DIR: path to AGASC directory for getting AGASC star data. This overrides the default value of $SKA/data/agasc.

  • AGASC_HDF5_FILE: path to AGASC HDF5 file for getting AGASC star data. This overrides the default value of <default_agasc_dir>/proseco_agasc_<latest>.h5, where <default_agasc_dir> = $AGASC_DIR or $SKA/data/agasc. If this is a relative path then it is relative to <default_agasc_dir>.

  • AGASC_SUPPLEMENT_ENABLED: set to "False" to disable using the AGASC

    supplement. This is for testing and should not be used in production.

  • PROSECO_DISABLE_OVERLAP_PENALTY: if set to "True" then disable the overlap penalty in the acq star selection. This is for testing and should not be used in production.

  • PROSECO_ENABLE_FID_OFFSET: controls application of time and temperature dependent fid light position offsets (from the ACA drift model) in ~proseco.fid.get_fid_positions: - Not set: apply offsets if time and temperature are provided (as is done in proseco fid

    selection since version 5.12.0)

    • "True": require that time and temperature be provided and apply offsets.

    • "False": do not apply offsets (typically used in regression testing not production).

  • PROSECO_IGNORE_MAXAGS_CONSTRAINTS: if set then do not update maxmag in the catalog to prevent search hits clipping.

  • PROSECO_OR_IMAGE_SIZE: override the default OR image size of 8x8. Can be one of “4”, “6”, or “8”.

  • PROSECO_PRINT_OBC_CAT: if set then create and print a debug catalog while doing catalog merging.

  • SKA: root directory that contains ‘data’ directory

API docs

Unit Testing