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¶

API documentation
- Full catalog
- Acquisition
- Guide
- Fid
- Core
- Diff

Unit Testing¶

Unit tests
- Catalog
- Acquisition
- Guide
- Fid
- Core

Proseco¶

Getting Started¶

Arguments¶

Examples¶

Monitor stars¶

Data requirements¶

Environment Variables¶

API docs¶

Unit Testing¶

Page Contents

Next topic

This Page

Navigation

Proseco¶

Getting Started¶

Arguments¶

Examples¶

Monitor stars¶

Data requirements¶

Environment Variables¶

API docs¶

Unit Testing¶