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: .. code-block:: bash 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. .. code-block:: python 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 .. code-block:: python 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: .. code-block:: python 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: .. code-block:: python # 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: .. code-block:: python # 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 ``.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 .. code-block:: python # 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: .. code-block:: python asteria.plot_distribution(G, xlabel="Thermal Inertia", log_bins=True, filename='TI.png')