User Guide

This is the software user manual for the pyAsteria python package. This section contains user instructions for setting up thermal inertia estimations with the ASTERIA code, and run the simulations. Full documentation of the APIs are also provided.

Installation

The python package can be installed through pip:

pip install pyasteria

Quickstart

For a simple analysis, the following steps can be followed: 1) load ASTERIA into python; 2) get orbital parameters for the asteroid; 3) set rotation period; 4) run the simulation. The code for these steps, for asteroid (499998) 2011 PT, is reported below as an example.

import asteria

# Initialize simulation
sim = asteria.Simulation()

# Get parameters for asteroid (49998) 2011 PT
sim.set_neocc_asteroid('499998')

# Set rotation period
sim.mean_P = 0.1833
sim.std_P = 0.001

# Print on screen asteroid parameters and simulation parameters
sim.print_asteroid_parameters()
sim.print_simulation_parameters()

# Run thermal inertia estimation
sim.run()

# Read output files
K, G, rho, D, obli = sim.read_output_data()

asteria.plot_distribution(G, xlabel="Thermal Inertia", log_bins=True, filename='TI.png')

Setting asteroid parameters

The estimation for the thermal inertia of a near-Earth asteroid (NEA) with the ASTERIA method requires some setting of parameters of the model. All the parameters of the asteroid and of the ASTERIA method are set in a class definied in the pyAsteria python package. The class for a sepecific asteroid is initialyzed by

import asteria

# Initialize simulation
sim = asteria.Simulation()

Orbital parameters

The orbital parameters to set are: the semi-major axis sim.sma (in au), the eccentricity sim.ecc, and the inclination sim.inc (in deg). In addition, the measurement of the semi-major axis drift in au/Myr needs to be provided for the ASTERIA method to work. The nominal value is stored in sim.mean_dadt and the error is stored in sim.std_dadt. Manual values can be set as follows:

sim = asteria.Simulation()
sim.sma = 1.001
sim.ecc = 0.1
sim.inc = 10.0
sim.mean_dadt = -0.0001
sim.std_dadt  =  0.00001

Retrieval from ESA NEOCC and NASA JPL

The package also offers routine to retrieve orbital data of asteroids from the NEO Coordination Centre (NEOCC) of the European Space Agency (ESA) or from the Small Body Database by NASA. The routines require either the number of the asteroid (if it is numbered), or the provisional designation (if is is not numbered). The routines can be called as follows:

# Set orbital data from NEOCC database
sim.set_neocc_asteroid('469219')

# Set orbital data from SBDB database
sim.set_jpl_asteroid('469219')

Note that these routines will set also the values of the absolute magnitude.

Physical parameters

Some physical parameters are also needed for the ASTERIA code. User defined values can be given for nominal value and standard deviations of:

  • sim.mean_H, sim.std_H — absolute magnitude; default value for the standard deviation is 0.5.

  • sim.mean_pv, sim.std_pv — albedo.

  • sim.mean_rho, sim.std_rho — density in kg/m^3.

  • sim.mean_D, sim.std_D — diameter, in m.

  • sim.mean_rhos, sim.std_rhos — density of surface material, in kg/m^3.

  • sim.mean_gam, sim.std_gam — obliquity, in deg.

  • sim.mean_P, sim.std_P — rotation period, in hours.

Non-spherical shape also influences the Yarkovsky effect modeling. To take into account these possibility, the user can set either one of these two following parameters:

  • sim.a_to_b — ratio between longer and shorter axes.

  • sim.delta_m — lighcturve amplitude.

Additional values for the absorption coefficient, the heat capacity, and the emissivity can be specified by setting sim.alpha, sim.C, and sim.emissiv, respectively.

Population priors

A priori distributions for albedo, density, diameter, and obliquity are also available. These distributions are based on statistical properties of the whole NEA population. A priori distributions are activated by default when the Simuation class is created, and they are generally activated by seting to -1 the parameters sim.mean_pv, sim.mean_rho, sim.mean_D, sim.mean_rhos, sim.mean_gam Override them by setting both the mean and standard deviation to positive values.

Setting simulation parameters

Choosing a Yarkovsky model

The model for the computation of the Yarkovky drift can be set trough the sim.method variable. Three method options are available, in increasing complexity:

  • 'circular' — fastest; assumes a circular orbit.

  • 'elliptic' — full elliptic orbit with a single thermal layer.

  • 'elliptic_2l' — full elliptic orbit with a two-layer thermal model.

If not specified, the circular model is used as a default.

The variable sim.expo defines the exponent for the depenency of the thermal inertia variation with the heliocentric distance. This variable is set to 1 as a default, and it means that the thermal inertia is kept constant along the orbit. The value can be modified to take into account thermal inertia variability.

Monte Carlo and other settings

Some settings for the Monte Carlo simulations can be adjusted by the user:

  • sim.sample_size — the size of the sample from the a-priori distrition, default set to 10.000.

  • sim.max_iter — the number of iterations of ASTERIA, set to 100.000 as a default.

  • sim.n_proc — the number of processors to use for the ASTERIA estimation, default to 1.

  • sim.thermalCondMin — minimum thermal conductivity to search for Yarkovsky equation solutions, default to 1e-5 W/m/K.

  • sim.thermalCondMax — maximum thermal conductivity to search for Yarkovsky equation solutions, default to 10 W/m/K.

  • sim.filename — name of the output file containing results of the estimation.

Running thermal inertia estimation

Once all the simulation settings are configured, the thermal inertia estimation can be launched with:

# Set orbital data from NEOCC database
sim.run()

Optionally, the run routine takes in input an integer argument to activate a correction of the Yarkovsky effect due to non-spherical shape. Admissible values for this parameter are:

  • 0 — No correction in Yarkovsky drift, assumed as default if not provided.

  • 1 — Correct da/dt using the axis ratio a_to_b.

  • 2 — Correct da/dt using the lightcurve amplitude delta_m.

Analyzing the results

A routine for reading the output data from the Monte Carlo estimation is provided. The output file <filename>.txt contains one accepted solution per line. Column layout depends on method:

  • 'circular' / 'elliptic': K Gamma rho D gamma

  • 'elliptic_2l': K Gamma rho rho_surface D gamma

The routine can be called by

# Read output files
K, G, rho, D, obli = sim.read_output_data()

The python package also offers a routine for plotting the distribution of the parameters. An example call is:

asteria.plot_distribution(G, xlabel="Thermal Inertia", log_bins=True, filename='TI.png')