SSOXmatch v0.8
SSOXmatch implements the computation of cross-matches of Solar System bodies (asteroids, comets, planets and natural satellites) in astronomical images, and the ingestion of them into a database. Project is developed and copyrighted by Tomás Alonso Albi (registered in Spain under the designation M-010562/2025): the program and code cannot be used or distributed without the permission of the author. The project aimed to be a replacement of a previous pipeline used at ESA to compute the cross-matches, and later used in ESASky to overlay the trajectories of minor bodies in the images of the different space missions. More information is provided in the user manual and the SSOXmatch paper. This pipeline has the following improvements:
- Ephemerides generated with Java code, including planets and satellites. No need to compile/call Eproc and parse text files, as in a previous software.
- All steps performed from Java code, including the creation of the database tables, the download of orbital elements and kernels, and the ingestion into databases. The queries to get the list of observation are also executed from this software.
- Generic approach for all surveys, with the inclusion of the kernel SPK files for the different missions, read from Java code using a JNI library.
- Maximum speed optimization with the use of fast approximate trigonometric functions for the computation of the ephemerides, while keeping the maximum possible accuracy. The consistency level is usually around 1E-5 degrees respect Horizons.
- It is not necessary to release a new version to support a new mission, since the properties file contains all necessary input data for them, and a custom one can be loaded from the command-line. The input files (SPK, orbital elements, observations) can also be loaded from a local folder.
- Ephemerides of both asteroids and comets from numerical integration, using Lowell+cometpro or JPL databases, and with multiple options for the integrator. By default the integrator is a Bogacki-Shampine order 5 Runge-Kutta, and 16 asteroids are used as perturbers. The physical model is much more accurate and suitable for NEAs and colliding bodies. A table with close encounters is generated, as well as charts of each individual cross-match.
- Great performance and limited resources, designed to be executed directly from production environments with only few threads. Cross-matches are found by computing the positions directly for the observation interval times, no Healpix tesselation needed, or iterations to get all cross-matches during an interval of time.
- Possibility of performing local tests by means of two database configurations, one for local ingestions (for the properties file for local environment), and another configuration for the remote database (required to get the list of observations). In production environments both configurations would point to the same remote database.
The execution of the pipeline has three steps: update of elements, pre-integration, and calculation (and ingestion in database) of cross-matches. The last two steps can be done for both the JPL and Lowell sets of elements, and they can be run in parallel when possible. Here are some shell scripts that can be useful to perform these steps:
Update script
#!/bin/sh
main_dir="/home/talonso/documentos/referencia/SSO_asteroids/newPipeline/" # replace with the complete path to the jar file
program="java -jar $main_dir/SSOXmatch.jar" # if necessary, replace with the path to a specific JVM or the latest one
export dir="$(echo $main_dir | sed -e 's/\//\\\//g')" # / -> \/
export threads=0 # whatever number, 0 for automatic maximum possible value = nCores-1
# Update elements, kernels, and observations
$program -environment pre_integration > custom_update.properties
sed -i "s/log_file=@home@time\/log.txt/log_file=/g" custom_update.properties
sed -i "s/local_data=@home/local_data=${dir}/g" custom_update.properties
sed -i "s/cross_match_threads=0/cross_match_threads=${threads}/g" custom_update.properties
$program -Xmx15G -XX:+UseG1GC -environment custom_update.properties --update -action UpdateElements > update_elements.txt 2>&1
$program -Xmx15G -XX:+UseG1GC -environment custom_update.properties --update -action UpdateKernels generate > update_kernels.txt 2>&1
$program -Xmx15G -XX:+UseG1GC -environment custom_update.properties --update -action UpdateObservations > update_observations.txt 2>&1
Script for JPL elements
#!/bin/sh
# Before executing this, first execute the update script
main_dir="/home/talonso/documentos/referencia/SSO_asteroids/newPipeline/" # replace with the complete path to the jar file
program="java -jar $main_dir/SSOXmatch.jar" # if necessary, replace with the path to a specific JVM or the latest one
export dir="$(echo $main_dir | sed -e 's/\//\\\//g')" # / -> \/
export threads=0 # whatever number, 0 for automatic maximum possible value = nCores-1
export jpl_schema=sso_jpl # database name assumed to be sso (from properties)
# JPL
# Pre-integration
$program -environment pre_integration > custom_jpl.properties
sed -i "s/log_file=@home@time\/log.txt/log_file=/g" custom_jpl.properties
sed -i "s/local_data=@home/local_data=${dir}/g" custom_jpl.properties
sed -i "s/cross_match_threads=0/cross_match_threads=${threads}/g" custom_jpl.properties
sed -i "s/local_db_schema=sso/local_db_schema=${jpl_schema}/g" custom_jpl.properties
sed -i 's/use_jpl_databases=false/use_jpl_databases=true/g' custom_jpl.properties
$program -Xmx15G -XX:+UseG1GC -environment custom_jpl.properties -action PropagateOrbits > log_preIntegration_jpl.txt 2>&1
# Fix pre-integration. Use 1E-7 au as tolerance to replace PV vectors with a new pre-integration from an updated kernel of a body suffering a close encounter
$program -Xmx15G -XX:+UseG1GC -environment custom_jpl.properties -action CloseEncounter download > close_encounter_download_kernels.txt 2>&1
$program -Xmx15G -XX:+UseG1GC -environment custom_jpl.properties -action CloseEncounter fix 1E-7 > close_encounter_fix_pre_integration.txt 2>&1
# XMs
$program -environment cross_match > custom_jpl.properties
sed -i "s/log_file=@home@time\/log.txt/log_file=/g" custom_jpl.properties
sed -i "s/local_data=@home/local_data=${dir}/g" custom_jpl.properties
sed -i "s/cross_match_threads=0/cross_match_threads=${threads}/g" custom_jpl.properties
sed -i "s/local_db_schema=sso/local_db_schema=${jpl_schema}/g" custom_jpl.properties
sed -i 's/use_jpl_databases=false/use_jpl_databases=true/g' custom_jpl.properties
$program -Xmx18G -XX:+UseG1GC -environment custom_jpl.properties -action IngestAll > log_xm_jpl.txt 2>&1
Script for Lowell elements
#!/bin/sh
# Before executing this, first execute the update script
main_dir="/home/talonso/documentos/referencia/SSO_asteroids/newPipeline/" # replace with the complete path to the jar file
program="java -jar $main_dir/SSOXmatch.jar" # if necessary, replace with the path to a specific JVM or the latest one
export dir="$(echo $main_dir | sed -e 's/\//\\\//g')" # / -> \/
export threads=0 # whatever number, 0 for automatic maximum possible value = nCores-1
export lowell_schema=sso_lowell # database name assumed to be sso (from properties)
# Lowell
# Pre-integration
$program -environment pre_integration > custom_lowell.properties
sed -i "s/log_file=@home@time\/log.txt/log_file=/g" custom_lowell.properties
sed -i "s/local_data=@home/local_data=${dir}/g" custom_lowell.properties
sed -i "s/cross_match_threads=0/cross_match_threads=${threads}/g" custom_lowell.properties
sed -i "s/local_db_schema=sso/local_db_schema=${lowell_schema}/g" custom_lowell.properties
sed -i 's/use_jpl_databases=true/use_jpl_databases=false/g' custom_lowell.properties
$program -Xmx15G -XX:+UseG1GC -environment custom_lowell.properties -action PropagateOrbits > log_preIntegration_lowell.txt 2>&1
# XMs
$program -environment cross_match > custom_lowell.properties
sed -i "s/log_file=@home@time\/log.txt/log_file=/g" custom_lowell.properties
sed -i "s/local_data=@home/local_data=${dir}/g" custom_lowell.properties
sed -i "s/cross_match_threads=0/cross_match_threads=${threads}/g" custom_lowell.properties
sed -i "s/local_db_schema=sso/local_db_schema=${lowell_schema}/g" custom_lowell.properties
sed -i 's/use_jpl_databases=true/use_jpl_databases=false/g' custom_lowell.properties
$program -Xmx18G -XX:+UseG1GC -environment custom_lowell.properties -action IngestAll > log_xm_lowell.txt 2>&1
Packages
Package
Description
Main package with constants, utilities, logs, and the main command line program.
Actions package implementing general actions to be called from the command-line.
Package containing the classes that implements a complete web portal with services
to compute cross-matches and ephemerides.
Cross-match related actions and utilities.
Database package with classes for postgres queries and file reading formats for orbital elements.
Ephemeris package with utilities to compute the position of the bodies.
Moons package implementing analytical theories to compute the positions of natural moons.
This package implements the Solar System numerical integration model.