Find_attitude package documentation

The find_atitude package contains functions for determining Chandra fine-attitude based only on the observed Y-angle, Z-angle, and magnitude of at least four ACA guide stars.

The recommended way for use of this in an operational situation is via the Kadi web site front end at http://kadi.cfa.harvard.edu/find_attitude. This requires being on the CfA network via VPN.

API docs

find_attitude.find_attitude.add_edge(graph, id0, id1, i0, i1, dist)[source]

Add an edge to the graph including metdata values i0, i1 and dist.

id0 and id1 are the AGASC (and node) ID of the edge that gets inserted.

The i0, i1 index values represent the index into the ACA stars catalog as taken from the ACA distance pair that matches the AGASC. These catalog index values are accumulated in a list because there may be multiple potential assignments for each distance.

Note that at this point there is no order to the identifcation, so it could be id0 <=> i0 or id0 <=> i1 (or none of the above).

Parameters:
  • graph – networkx graph

  • id0 – AGASC / node ID of one node of the edge

  • id1 – AGASC / node ID of the other node of the edge

  • i0 – ACA star catalog index of one node of the edge

  • i1 – ACA star catalog index of ther other node of the edge

  • dist – distance (arcsec) between nodes

Returns:

None

find_attitude.find_attitude.connected_agasc_ids(ap, min_stars)[source]

Return agacs_ids that occur at least 4 times.

Each occurrence indicates an edge containing that agasc_id node.

Parameters:

ap – table of AGASC pairs

Returns:

set of AGASC IDs

find_attitude.find_attitude.find_all_matching_agasc_ids(yags, zags, mags=None, agasc_pairs_file=None, dist_match_graph=None, tolerance=2.5, constraints=None)[source]

Given an input table of stars find the matching cliques.

These cliques are completely connected subgraphs in the agasc_pairs_file of pair distances. Do pair distance matching to within tolerance arcsec.

If g_dist_match is supplied then skip over reading the AGASC pairs and doing initial matching. This is mostly for development.

Parameters:
  • stars – table of up to 8 stars

  • agasc_pairs_file – name of AGASC pairs file created with make_distances.py

  • dist_match_graph – graph with matching distances (optional, for development)

  • tolerance – distance matching tolerance (arcsec)

  • constraints – Constraints object or None Attitude, normal sun, and date constraints if available

Returns:

list of possible AGASC-ID to star index maps

find_attitude.find_attitude.find_attitude_for_agasc_ids(yags, zags, agasc_id_star_map, constraints=None)[source]

Find the fine attitude for the given inputs.

Find the fine attitude for a given set of yags and zags and a map of AGASC ID to star index (i.e. index into yags and zags arrays).

Returns a dictionary with keys:

yags : input Y angles
zags : input Z angles
m_yags : best fit Y angles
m_zags : best fit Z angles
att_fit : best fit attitude quaternion (Quat object)
statval : final fit statistic
agasc_id_star_map : input AGASC ID to star index map
Parameters:
  • yags – np.array with star Y angles in arcsec

  • zags – np.array with star Z angles in arcsec

  • agasc_id_star_map – dict of AGASC ID to star index map

  • constraints – Constraints object or None Attitude, normal sun, and date constraints if available

Returns:

dict

find_attitude.find_attitude.find_attitude_solutions(stars, tolerance=2.5, constraints=None, log_level=None, sherpa_log_level='WARNING')[source]

Find attitude solutions given an input table of star data.

The input star table must have columns ‘YAG’ (arcsec), ‘ZAG’ (arcsec), and ‘MAG’. There must be at least four stars for the matching algorithm to succeed.

This relies on a pre-computed star pair distance file that is created with make_distances.py. This file is an HDF5 file with a table of pair distances that is computed for a particular star epoch.

The output is a list of solutions, where each solution is a dict with keys:

summary : copy of input stars table with new columns of useful info
yags : input Y angles
zags : input Z angles
m_yags : best fit Y angles
m_zags : best fit Z angles
agasc_ids : list of AGASC IDs corresponding to inputs
att_fit : best fit attitude quaternion (Quat object)
statval : final fit statistic
agasc_id_star_map : input AGASC ID to star index map
Parameters:
  • stars – table of star data

  • tolerance – matching tolerance (arcsec, default=2.5)

  • constraints – Constraints object or None Attitude, normal sun, and date constraints if available

  • log_level – logging level for find_attidue functions

  • sherpa_log_level – logging level for sherpa

Returns:

list of solutions, where each solution is a dict

find_attitude.find_attitude.find_matching_agasc_ids(aca_pairs, agasc_pairs_file, g_dist_match=None, tolerance=2.5, constraints=None) list[dict[int, int]][source]

Given an input table of stars find the matching cliques.

These cliques are completely connected subgraphs in the agasc_pairs_file of pair distances. Do pair distance matching to within tolerance arcsec.

At a minimum the stars table should include the following columns:

'AGASC_ID', 'RA', 'DEC', 'YAG', 'ZAG', 'MAG_ACA'

If g_dist_match is supplied then skip over reading the AGASC pairs and doing initial matching. This is mostly for development.

Output is a list of dictionaries where the keys are AGASC IDs and the values are indices into the input star table. For example:

[{876482752: 5, 876610304: 3, 876481760: 4, 876486456: 7, 876610432: 6}]
Parameters:
  • aca_pairs – table of distances between every star pair

  • agasc_pairs_file – name of AGASC pairs file created with make_distances.py

  • g_dist_match – graph with matching distances (optional, for development)

  • tolerance – distance matching tolerance (arcsec)

  • constraints – Constraints object or None Attitude, normal sun, and date constraints if available

Returns:

list of possible AGASC-ID to star index maps

find_attitude.find_attitude.get_distance_pairs(aca_pairs, agasc_pairs, tolerance, constraints) Table[source]

Get AGASC pairs that match ACA pair distances.

Output table has columns ‘dists’, ‘agasc_id0’, ‘agasc_id1’, ‘i0’, ‘i1’.

Parameters

aca_pairsTable

Table of pairwise distances for observed ACA star data

agasc_pairstables.table.Table

Table of pairwise distances for AGASC catalog stars from opened h5 object

tolerancefloat

Matching distance (arcsec)

constraintsConstraints object or None

Attitude, normal sun, and date constraints if available

Returns

Table

Table of AGASC pairs that match ACA pair distances

find_attitude.find_attitude.get_dists_yag_zag(yags, zags, mags=None)[source]

Get distances between every pair of stars with coordinates yags and zags.

Returns a Table with columns ‘dists’, ‘idx0’, ‘idx1’, ‘mag0’, ‘mag1’.

Parameters:
  • yags – np.array with star Y angles in arcsec

  • zags – np.array with star Z angles in arcsec

  • mags – np.array with star magnitudes (optional)

Returns:

Table with pair distances and corollary info

find_attitude.find_attitude.get_healpix_indices_within_annulus(ra: float, dec: float, *, radius0: float, radius1: float, nside: int = 64, order: str = 'nested')[source]

Get healpix indices within a range of radii from a given RA, Dec.

This is a much faster, somewhat approximate version of the astropy_healpix method cone_search_lonlat(). It works by computing the positions of the four corners of each pixels and checking if that is within the annulus. This requires that radius0 and radius1 are both much bigger than the healpix pixel size.

Parameters

rafloat

Right ascension in degrees

decfloat

Declination in degrees

radius0float

Inner radius in degrees

radius1float

Outer radius in degrees

nsideint

Healpix nside parameter (default=64)

orderstr

Healpix order parameter (default=’nested’)

Returns

healpix_indicesndarray

List of healpix indices

find_attitude.find_attitude.get_match_graph(aca_pairs: Table, agasc_pairs: Table, tolerance: float, constraints: Constraints | None = None) Graph[source]

Return network graph of all AGASC pairs that correspond to an ACA pair.

Given a table of aca_pairs representing the distance between every pair in the observed ACA centroid data, and the table of AGASC catalog pairs, assemble a network graph of all AGASC pairs that correspond to an ACA pair.

From this initial graph select only nodes that have at least 3 connected edges.

Parameters

aca_pairsTable

Table of pairwise distances for observed ACA star data

agasc_pairstables.table.Table

Table of pairwise distances for AGASC catalog stars from opened h5 object

tolerancefloat

Matching distance (arcsec)

constraintsConstraints object or None

Attitude, normal sun, and date constraints if available

Returns

nx.Graph

Networkx graph of distance-match pairs

find_attitude.find_attitude.get_min_stars(constraints)[source]

Minimum number of stars required for an attitude solution.

This is somewhat arbitrary, but the number of healpix indices corresponds to sky area and is a decent proxy for the number of stars that will be found in the matching process.

Parameters

constraintsConstraints object or None

Attitude, normal sun, and date constraints if available

find_attitude.find_attitude.get_slot_id_candidates(graph, nodes) list[dict[int, int]][source]

Get list of candidates which map node AGASC ID to ACA star catalog index number.

For a graph of nodes / edges that match the stars in distance, and a list of clique_nodes which form a complete subgraph, find a list of identification candidates which map node AGASC ID to ACA star catalog index number. This handles possible degenerate solutions and ensures that the outputs are topologically sensible.

This is one of the trickier bits of algorithm, hence the complete lack of code comments. It basically tries all permutations of star catalog index number and sees which ones end up as a complete graph (though it does this just by counting instead of making graphs).

Output is a list of dictionaries where the keys are AGASC IDs and the values are indices into the ACA star table. For example:

[{876482752: 5, 876610304: 3, 876481760: 4, 876486456: 7, 876610432: 6}]
Parameters:
  • graph – graph of distance-match pairs

  • nodes – list of nodes that form a complete subgraph

Returns:

list of dicts for plausible AGASC-ID to star index identifications

find_attitude.find_attitude.get_stars_from_maude(date: CxoTime | str | float | int | ndarray | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | complex | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, dt: float = 11.0, slots: list | None = None)[source]

Get star data from MAUDE for a given date.

This gets dt seconds of star data ending at date. If date is None then get the most recent star data. The star data are AOACYAN, AOACZAN, and AOACMAG for each of the 8 slots.

Parameters

dateCxoTimeLike

Date for which to get star data

dtfloat

Time interval (seconds) for which to get star data (default=11.0)

slotslist of int, optional

List of slots to get star data for (default is all 8 slots)

Returns

Table

Table of star data for tracked stars in the 8 slots. Columns are ‘slot’, ‘YAG’, ‘ZAG’, and ‘MAG_ACA’.

find_attitude.find_attitude.get_stars_from_text(text)[source]

Get stars table from text input.

This can be a hand-entered table or copy/paste from GRETA A_ACA_ALL. Minimal conforming examples are:

 MEAS      #   Flags   Functn  Flag        Y         Z        Mag
IMAGE 0  0     STAR    TRAK   STAR     -381.28    1479.95      7.2
IMAGE 1  1     STAR    TRAK   STAR     -582.55    -830.85      8.9
IMAGE 2  2     STAR    TRAK   STAR     2076.33   -2523.10      8.5
IMAGE 3  3     STAR    TRAK   STAR     -498.12    -958.33      5.0
IMAGE 4  4     STAR    TRAK   STAR     -431.68    1600.98      8.2
IMAGE 5  5     STAR    TRAK   STAR     -282.40     980.50      7.9
IMAGE 6  6     NULL    NONE   STAR    -3276.80   -3276.80     13.9
IMAGE 7  7     STAR    TRAK   STAR      573.25   -2411.70      7.1

or:

slot yag zag mag
3     223.33      55.83      9.7
4    -453.1      -2084.1     9.6
5   -1255.12     196.58      9.2
6     598.18    2287.97      9.6
7    2311.45    1140.60      9.8
Parameters:

text – text representation of input star table information.

Returns:

Table of star data

find_attitude.find_attitude.get_triangles(G)[source]

Get all the triangles in graph G

This code was taken from a google forum discussion posting by Daniel Schult. No license or attribution request was provided. https://groups.google.com/forum/#!topic/networkx-discuss/SHjKJFIFNtM

Parameters:

G – input networkx graph

Returns:

list of (node0, node1, node2) tuples