API Reference

class asteria.Simulation(sample_size: int = 10000, sma: float = None, ecc: float = None, inc: float = None, mean_H: float = None, std_H: float = 0.5, mean_pv: float = -1.0, std_pv: float = -1.0, mean_rho: float = -1.0, std_rho: float = -1.0, mean_D: float = -1.0, std_D: float = -1.0, mean_rhos: float = -1.0, std_rhos: float = -1.0, mean_gam: float = -1.0, std_gam: float = -1.0, mean_P: float = None, std_P: float = None, a_to_b: float = None, delta_m: float = None, mean_dadt: float = None, std_dadt: float = None, alpha: float = 1.0, C: float = 800.0, emissiv: float = 0.984, thermalCondMin: float = 1e-05, thermalCondMax: float = 10.0, method: str = 'circular', filename: str = 'asteria_output', max_iter: int = 100000, expo: float = 1.0, n_proc: int = 1)[source]

Bases: object

Monte Carlo simulation of Yarkovsky effect thermal parameters for a near-Earth asteroid.

The class wraps the ASTERIA Fortran core (_asteria) and exposes a Python-friendly interface for setting up, running, and reading the results of a thermal-parameter inversion based on a measured semi-major axis drift (da/dt).

The simulation proceeds in two stages driven by run():

  1. Distribution generation (gen_distrib) — draws sample_size realisations of all physical and orbital parameters from the supplied prior distributions.

  2. Monte Carlo inversion (gamma_est_mc) — iterates up to max_iter times to find thermal conductivity K and thermal inertia Gamma solutions consistent with the observed da/dt.

Physical parameters (albedo, density, diameter, surface density, obliquity) default to -1.0, which is a sentinel value meaning “draw from the built-in NEA population model”. Set both the mean and standard deviation to a positive value to use a Gaussian prior instead.

Parameters:

  • sample_size (int, optional) – Number of samples drawn for the a-priori distributions. Default 10 000.

  • sma (float) – Semi-major axis in au. Must be > 0.

  • ecc (float) – Eccentricity. Must satisfy 0 <= ecc < 1.

  • inc (float) – Inclination in degrees. Must satisfy 0 <= inc <= 180.

  • mean_H (float) – Mean absolute magnitude H. Must be >= 0.

  • std_H (float, optional) – 1-sigma uncertainty on H. Default 0.5 mag.

  • mean_pv (float) – Mean geometric albedo pv. Set to -1.0 to use the population model. Default -1.0.

  • std_pv (float) – 1-sigma uncertainty on pv. Ignored when mean_pv = -1.0. Default -1.0.

  • mean_rho (float) – Mean bulk density in kg/m^3. Set to -1.0 for the population model. Default -1.0.

  • std_rho (float) – 1-sigma uncertainty on bulk density in kg/m^3. Default -1.0.

  • mean_D (float) – Mean diameter in metres. Set to -1.0 to derive from H and pv via the population model. Default -1.0.

  • std_D (float) – 1-sigma uncertainty on diameter in metres. Default -1.0.

  • mean_rhos (float) – Mean surface (regolith) density in kg/m^3. Set to -1.0 for the population model. Default -1.0.

  • std_rhos (float) – 1-sigma uncertainty on surface density in kg/m^3. Default -1.0.

  • mean_gam (float) – Mean spin-axis obliquity in degrees. Set to -1.0 for the population model. Default -1.0.

  • std_gam (float) – 1-sigma uncertainty on obliquity in degrees. Default -1.0.

  • mean_P (float) – Mean rotation period in hours. Must be >= 0. Default None.

  • std_P (float) – 1-sigma uncertainty on rotation period in hours. Must be >= 0. Default None.

  • a_to_b (float) – Axis ratio a/b for the non-spherical correction (0 < a_to_b <= 1). Required when calling run(ns_corr=1). Default None.

  • delta_m (float) – Lightcurve peak-to-peak amplitude in magnitudes (>= 0). Used for the non-spherical correction when calling run(ns_corr=2). Default None.

  • mean_dadt (float) – Measured semi-major axis drift da/dt in au/My. Default None.

  • std_dadt (float) – 1-sigma uncertainty on da/dt in au/My. Must be >= 0. Default None.

  • alpha (float) – Solar radiation absorption coefficient. Default 1.0.

  • C (float) – Specific heat capacity in J/kg/K. Default 800.0.

  • thermalCondMin (float) – Lower bound of the thermal conductivity search range in W/m/K. Must be > 0. Default 1e-5.

  • thermalCondMax (float) – Upper bound of the thermal conductivity search range in W/m/K. Must be > 0. Default 10.0.

  • emissiv (float) – Bolometric thermal emissivity. Default 0.984.

  • method (str) –

    Yarkovsky model variant. One of:

    • 'circular' — circular-orbit approximation (fastest).

    • 'elliptic' — full elliptic orbit, single-layer model.

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

    Default 'circular'.

  • filename (str) – Base name (without extension) for the output text file. Default 'asteria_output'.

  • max_iter (int) – Maximum number of Monte Carlo iterations. Must be > 0. Default 100 000.

  • expo (float, optional) – Exponent governing how thermal inertia scales with heliocentric distance (Gamma proportional to r^expo). Default 1.0.

  • n_proc (int, optional) – Number of parallel CPU cores used by the Fortran core. Default 1.

sample_size: int = 10000
sma: float = None
ecc: float = None
inc: float = None
mean_H: float = None
std_H: float = 0.5
mean_pv: float = -1.0
std_pv: float = -1.0
mean_rho: float = -1.0
std_rho: float = -1.0
mean_D: float = -1.0
std_D: float = -1.0
mean_rhos: float = -1.0
std_rhos: float = -1.0
mean_gam: float = -1.0
std_gam: float = -1.0
mean_P: float = None
std_P: float = None
a_to_b: float = None
delta_m: float = None
mean_dadt: float = None
std_dadt: float = None
alpha: float = 1.0
C: float = 800.0
emissiv: float = 0.984
thermalCondMin: float = 1e-05
thermalCondMax: float = 10.0
method: str = 'circular'
filename: str = 'asteria_output'
max_iter: int = 100000
expo: float = 1.0
n_proc: int = 1
set_neocc_asteroid(astname)[source]

Populate orbital and physical parameters by fetching data from the ESA NEOCC database.

Downloads the .ke0 Keplerian orbit file for astname, parses it with read_neocc_orb(), and sets sma, ecc, inc, mean_H, mean_dadt, and std_dadt on this instance.

Parameters:

astname (str or int) – Asteroid designation or number as recognised by ESA NEOCC (e.g. "2024YR4", 101955).

Returns:

  • a (float) – Semi-major axis in au.

  • e (float) – Eccentricity.

  • i (float) – Inclination in degrees.

  • H (float) – Absolute magnitude.

  • dadt (float) – Semi-major axis drift da/dt in au/My.

  • dadt_std (float) – 1-sigma uncertainty on da/dt in au/My.

Raises:

  • ValueError – If the asteroid is not found (HTTP status other than 200).

  • ValueError – If the orbit file does not contain a measured A2 parameter.

Notes

Requires an active internet connection. The .ke0 file is saved to the current working directory.

set_jpl_asteroid(astname)[source]

Populate orbital and physical parameters by querying the JPL Small Body Database (SBDB) API.

Sends a request to https://ssd-api.jpl.nasa.gov/sbdb.api, extracts orbital elements, absolute magnitude H, and the non-gravitational parameter A2, then sets sma, ecc, inc, mean_H, mean_dadt, and std_dadt on this instance.

Parameters:

astname (str or int) – Asteroid name, designation, or SPK-ID accepted by JPL SBDB (e.g. "2024YR4", 469219).

Returns:

  • a (float) – Semi-major axis in au.

  • e (float) – Eccentricity.

  • inc (float) – Inclination in degrees.

  • H (float or None) – Absolute magnitude, or None if not in SBDB.

  • dadt (float) – Semi-major axis drift da/dt in au/My.

  • dadt_std (float) – 1-sigma uncertainty on da/dt in au/My.

Raises:

  • requests.HTTPError – If the SBDB API returns a non-2xx status code.

  • ValueError – If no orbital data are found for astname.

  • ValueError – If the entry does not contain a measured A2 parameter.

Notes

Requires an active internet connection.

print_simulation_parameters()[source]

Print a formatted summary of the simulation configuration to stdout.

Displays sample size, thermal conductivity search range, Yarkovsky model, thermal-inertia distance exponent, output filename, maximum iteration count, and CPU count.

print_asteroid_parameters()[source]

Print a formatted summary of the asteroid’s orbital and physical parameters to stdout.

Physical parameters whose mean is still -1.0 are reported as "Population" to indicate that the built-in NEA population model will be used during the simulation.

run(ns_corr=0)[source]

Execute the ASTERIA Monte Carlo thermal-parameter inversion.

Optionally applies a non-spherical shape correction to the observed da/dt, then calls the two-stage Fortran core: distribution generation (gen_distrib) followed by the Monte Carlo solver (gamma_est_mc). Results are written to <filename>.txt.

Parameters:

ns_corr ({0, 1, 2}, optional) –

Non-spherical shape correction flag:

  • 0 — No correction (spherical approximation).

  • 1 — Correct da/dt using the axis ratio a_to_b. Requires a_to_b to be set.

  • 2 — Correct da/dt using the lightcurve amplitude delta_m. Requires delta_m to be set.

The scale factor is xi = f^(-0.3), where f is either a_to_b or exp(delta_m / 2.5). Default is 0.

Raises:

  • ValueError – If ns_corr=1 and a_to_b is not set.

  • ValueError – If ns_corr=2 and delta_m is not set.

  • ValueError – If ns_corr is not 0, 1, or 2.

  • ValueError – If any required field (sma, ecc, inc, mean_H, mean_dadt, std_dadt, mean_P, std_P) is None.

Notes

The Fortran extension _asteria is imported lazily so the package can be imported without a compiled binary (e.g. during documentation builds).

read_output_data()[source]

Read and parse the Monte Carlo output file produced by run().

The 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 <unused> D gamma

Returns:

  • K (list of float) – Thermal conductivity solutions in W/m/K.

  • Gamma (list of float) – Thermal inertia solutions in J m^-2 K^-1 s^-0.5 (TIU).

  • rho (list of float) – Bulk density solutions in kg/m^3.

  • diam (list of float) – Diameter solutions in metres.

  • obli (list of float) – Spin-axis obliquity solutions in degrees.

Raises:

FileNotFoundError – If <filename>.txt does not exist in the working directory.

asteria.plot_distribution(data, bins=50, xlabel='', ylabel='Count', fontsize=13, figsize=(8, 5), log_bins=False, filename=None)[source]

Plot a normalized histogram of a 1D dataset.

Non-finite values (NaN, Inf) are silently removed before plotting. When log_bins=True, the histogram is weighted by bin center so that the plotted quantity approximates a log-space probability density (i.e. dN/d log x).

Parameters:

  • data (array-like) – Input data. Must contain at least one finite value.

  • bins (int, optional) – Number of histogram bins. Default is 50.

  • xlabel (str, optional) – Label for the x-axis. Default is an empty string.

  • ylabel (str, optional) – Label for the y-axis. Default is "Count".

  • fontsize (int or float, optional) – Font size for axis labels and tick labels. Default is 13.

  • figsize (tuple of (float, float), optional) – Width and height of the figure in inches. Default is (8, 5).

  • log_bins (bool, optional) – If True, bin edges are spaced logarithmically and the x-axis is shown on a log scale. All data values must be strictly positive. Default is False.

  • filename (str or None, optional) – If provided, the figure is saved to this path at 600 dpi before being displayed. Default is None.

Raises:

  • ValueError – If data is empty after removing non-finite values.

  • ValueError –