Match2SSO

Python code to match single telescope detections to known solar system objects based on their position. To keep the matching accurate, only known objects with small orbital uncertainties are used in the matching. The maximum allowed uncertainty is set in set_match2SSO.py. Asteroid matching is done by default. Comet matching is only done when include_comets = True (in the settings file).

Match2SSO was created for the MeerLICHT & BlackGEM telescopes. The code is available as a Python script. It's compatible with MeerLICHT's image processing software (BlackBOX & ZOGY) version 1.0.0 and up. Telescope specific parameters are specified in the settings file, so the code should be relatively easy to adapt to run on the data from other telescopes.

Match2SSO makes grateful use of the lunar and jpl_eph repositories that were written by Bill Gray under Project Pluto. The core of Match2SSO is astcheck: a C++ script in the lunar repository that matches detections to known solar system objects.

Installation

• Install Python (code was tested on Python 3.8.10) and C++
• Create a new (software) folder to house repositories and files needed by Match2SSO
• Clone Bill Gray's lunar repository to a software folder (https://github.com/Bill-Gray/lunar) and build the library & executables as described in this repository's README file. Also build integrat by running make integrat.
• Add the lunar folder to PATH in your bash file
• Clone Bill Gray's jpl_eph repository to the software folder (https://github.com/Bill-Gray/jpl_eph) and build the library & executables as described in this repository's README file.
• Clone the Match2SSO repository (preferably to the software folder).
• Download JPL's DE ephemeris file to the software folder. (ftp://ssd.jpl.nasa.gov/pub/eph/planets/Linux/)
• Download MPC's Observatory codes list to the software folder. (https://www.minorplanetcenter.net/iau/lists/ObsCodes.html)
• Adjust the settings in set_match2SSO.py to use the paths and parameters corresponding to your telescope, user and system.

Input & output files

Input

Match2SSO runs on a FITS catalogue of detections. For MeerLICHT & BlackGEM, it is best run on the transient catalogues that were produced after difference imaging.

Other input files that the software needs are mentioned above under "Installation". In addition, Match2SSO uses MPCORB.DAT (MPC's asteroid database) and COMET.ELEMENTS (JPL's comet database), but these are downloaded when running the script and hence do not need to be pre-downloaded.

Output

• Solar Sytem Object (SSO) catalogue containing the matches between detections and known solar system objects (_sso.fits). SSO catalogue columns and header keywords are listed here: https://www.overleaf.com/read/zrhqwcbkfqns
• Prediction catalogue containing the solar system objects that are predicted to be in the FOV during the observation (_sso_predict.fits). Prediction catalogue columns and header keywords are listed in the overleaf document mentioned above. Prediction catalogues are only made if --savepredictions True.
• MPC report (_sso_report.txt), to allow easy reporting of all detections of known solar system objects to the Minor Planet Center. MPC reports are created if --makereports True, but are not automatically sent to the MPC.

Running Match2SSO

Run the match2SSO.py script from the command line. It can be run in three modes:

• Historic mode: run Match2SSO on existing data.
• Day mode: needs to be executed once before the start of an observing night, to allow the night mode to be run in real-time during that night. Allows speedy and parallelized processing in night mode.
• Night mode: run during the observing run (in real time) on a single detection catalogue. Needs the products made during the day mode.

More details on these modes are listed under "Code description" below.

Main command line parameters:

• --mode historic / night / day. Default is historic.
• --catalog Name of detection catalogue (including file path) to run the matching on.
• --date Run Match2SSO on all detection catalogues corresponding to this observing night.
• --catlist Run Match2SSO on all detection catalogues listed in this file.

Allowed combinations of the above-mentioned parameters are:

• Day mode
• Day mode + date
• Night mode + catalog
• Historic mode + catalog
• Historic mode + date
• Historic mode + catlist

Other command line parameters:

• --telescope (Abbreviated) telescope name. Allows dictionaries in the settings file set_match2SSO.py with different parameter values for different telescopes. Default is ML1 (for MeerLICHT data).
• --logname Name of the log file
• --redownload Boolean to indicate whether previously downloaded versions of the MPC asteroid database and JPL comet database may be used, or whether a new version is to be downloaded. Default is True. If redownload is False, by default the most recently downloaded known objects database will be used.
• --quick Boolean which is only relevant when --redownload False. Instead of using the most recently downloaded known objects database, with --quick True, the database with the reference epoch closest to the observation epoch is used. This speeds up the integration step (step 4 in the day/hist mode, see below). But beware: the database version used may not be the latest (most up-to-date) one. Default is False.
• --savepredictions Boolean to indicate whether prediction catalogues need to be made. (See output section above.) Default is False.
• --makereports Boolean to indicate whether MPC reports should be created for all SSO detections. (See output section above.) Default is True.
• --overwrite Boolean to indicate whether files may be overwritten. Default is False.

Multi-processing

Although multi-processing was not implemented within the code, efforts have been made to allow calling the code multiple times in parallel.

• Night mode: runs independently on a single catalogue. The steps in the code that make parallelization impossible have been moved to the day mode. Prepare for the night mode by running the day mode once before the start of an observing night. The night mode can be run on multiple catalogues of the same night in parallel without issues.
• Historic mode: parallelization is only possible for data that was not taken on the same night. Multiple nights can be processed in parallel easily by running the historic mode on those nights individually.

Code description

The steps Match2SSO performs in the different modes are:

• Day mode
  1. Creates a run directory in preparation of the nightly processing.
  2. Downloads asteroid and comet databases to the tmp folder.
  3. Rejects asteroids and comets with a large orbital runoff (uncertain orbits).
  4. Combines the comet and asteroid databases into a SOF-formatted known objects database.
  5. Integrates the known objects database to UTC midnight of the observation night
  6. Creates symbolic links in the run directory to the used databases and the observatory codes list.
  7. Runs astcheck on a fake detection in order to create the CHK files that astcheck will need for faster / parallel processing when running on observations.
  8. Removes the fake detection in- & output (but not the CHK files!). (Products of steps 1-5 are saved to the tmp folder, those of steps 6-7 to the run directory.)
• Night mode
  1. Converts the detection catalogue into an MPC-formatted text file.
  2. Runs astcheck on the central coordinates of the observation, to make predictions on the known solar system objects in the FOV. The number of bright SSOs in the FOV will later be written to the header of the SSO catalogue.
  3. [Optional] Makes a prediction catalogue of the known solar system objects in the FOV during the observation.
  4. Runs astcheck on the MPC-formatted text file, to find matches between the detections and known solar system objects.
  5. Makes an SSO catalogue containing the matches.
  6. [Optional] Makes an MPC report of the matches.
• Historic mode
  Runs on a single detection catalogue (observation), a night of observations or a list of observations. The observations are grouped and processed per observing night. The historic mode:
  1. Creates a run directory per observation night
  2. [Optional] Downloads asteroid and comet databases to the database folder. (If this step is skipped, the most recently downloaded version of the database will be used.)
  3. Rejects asteroids and comets with a large orbital runoff (uncertain orbits).
  4. Combines the comet and integrated asteroid databases into a SOF-formatted known objects database.
  5. Integrates the asteroid database to UTC midnight of the observation night.
  6. Creates symbolic links in the run directory to the used databases and the observatory codes list.
  7. Run the matching per detection catalogue:
     a. Converts the detection catalogue into an MPC-formatted text file.
     b. Runs astcheck on the central coordinates of the observation, to make predictions on the known solar system objects in the FOV. The number of bright SSOs in the FOV will later be written to the header of the SSO catalogue.
     c. [Optional] Makes a prediction catalogue of the known solar system objects in the FOV during the observation.
     d. Runs astcheck on the MPC-formatted text file, to find matches between the detections and known solar system objects.
     e. Makes an SSO catalogue containing the matches.
     f. [Optional] Makes an MPC report of the matches.
     
  8. [Optional] Removes the run directory, including files in it (SOF-formatted known objects database, symbolic links, MPC-formatted detection file, astcheck output text file). Also removes the integrated asteroid database.

License

Copyright 2022 Daniëlle Pieterse

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.