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.

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.

• Install Python (code was tested on Python 3.8.10) and C++
• 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.
• 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)

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.

• 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 were 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 submission of all detections of known solar system objects to the Minor Planet Center. MPC reports are created if --makereports True, but are not submitted automatically to the MPC.

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

• Historic mode: run 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.

• --mode Historic, night or day mode
• --catalog Name of detection catalogue to run the matching on
• --date Run match2SSO run 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

• --telescope (Abbreviated) telescope name. Allows dictionaries in the settings file set_match2SSO.py with different parameter values for different telescopes.
• --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.
• --savepredictions Boolean to indicate whether prediction catalogues need to be made. (See output section above.)
• --makereports Boolean to indicate whether MPC reports should be created for all SSO detections. (See output section above.)
• --overwrite Boolean to indicate whether files may be overwritten

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.

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. Combines the comet and asteroid databases into a SOF-formatted known objects database.
  4. Integrates the known objects database to midnight of the observation night
  5. Creates symbolic links in the run directory to the used databases and the observatory codes list.
  6. 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.
  7. Removes the fake detection in- & output (but not the CHK files!). (Products of steps 1-4 are saved to the tmp folder, those of steps 5-6 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. Combines the comet and integrated asteroid databases into a SOF-formatted known objects database.
  4. Integrates the asteroid database to midnight of the observation night.
  5. Creates symbolic links in the run directory to the used databases and the observatory codes list.
  6. 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.
     
  7. [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.

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.