Skip to content

Star and orbit

The [star] section configures the host star model and spectral properties. The [orbit] section configures the planetary orbit, tidal evolution, and any satellite.

Submodule documentation: MORS | Obliqua. See also Model description.

Stellar model [star]

Parameter Type Default Description
module str or none "mors" Select star module to use. Choices: none, "mors", "dummy".
mass float 1.0 Stellar mass [M_sun]. Note that for Mors, it should be between 0.1 and 1.25 solar masses. Values outside of the valid range will be clipped. Must be > 0.
age_ini float 0.1 Stellar age at model initialisation, relative to stellar birthline [Gyr]. Must be > 0.
bol_scale float 1.0 Scale factor applied to bolometrically modulate the stellar fluxes. Must be >= 0.0.
bol_scale_duration float 0.0 Duration for which bol_scale is applied [Gyr]. Must be >= 0.0.
bol_scale_start float or none none Stellar age from which bol_scale is applied [Gyr]. 'None' to disable. Must be >= 0.0.

bol_scale only takes effect while the model's stellar age lies within the start-plus-duration interval. So, all three options should be set together. The scaling factor is applied uniformly to all stellar flux terms.

MORS stellar tracks [star.mors]

The MORS module interpolates stellar radius, effective temperature, luminosity, and XUV flux from pre-computed evolutionary tracks as a function of stellar age. Two track families are available: Spada 1 (solar-type) and Baraffe 2 (low-mass M-dwarfs). The phoenix_* parameters are used when spectrum_source = "phoenix": PHOENIX provides synthetic spectra on a grid of metallicity, alpha enhancement, and (optionally) effective temperature.

Parameter Type Default Description
age_now float 4.567 Observed estimated age of the star [Gyr].
star_name str or none none Name of the star, to find appropriate stellar spectrum. See documentation.
star_path str or none none Path to custom stellar spectra. If 'none', star_name will be used to find spectra in default locations.
rot_pcntle float or none 50.0 Rotation, as percentile of stellar population.
rot_period float or none none Rotation rate [days].
tracks str "spada" Stellar evolution track to be used. Choices: "spada", "baraffe".
spectrum_source str or none "phoenix" Source of stellar spectra. Choices: "solar", "muscles", "phoenix", none.
phoenix_FeH float 0.0 Stellar metallicity [Fe/H] to be used for PHOENIX synthetic spectra, if spectrum_source is 'phoenix'.
phoenix_alpha float 0.0 Alpha-element enhancement [alpha/Fe] to be used for PHOENIX synthetic spectra, if spectrum_source is 'phoenix'.
phoenix_radius float or none none Stellar radius [R_sun]. If 'none', radius will be calculated using mors' stellar tracks, if spectrum_source is 'phoenix'. Must be > 0.
phoenix_log_g float or none none Surface gravity [cgs]. If 'none', log g will be calculated will be calculated using mors' stellar tracks, if spectrum_source is 'phoenix'. Must be > 0.
phoenix_Teff float or none none Effective temperature [K]. If 'none', Teff will be calculated will be calculated using mors' stellar tracks, if spectrum_source is 'phoenix'. Must be > 0.

Dummy star [star.dummy]

A fixed-luminosity star with no temporal evolution. Useful for testing and parameter studies where stellar evolution is not relevant.

Parameter Type Default Description
Teff float 5772.0 Observed effective temperature [K].
radius float or none none Observed radius [R_sun].
calculate_radius bool false Calculate the radius using empirical mass-luminosity and mass-radius relation.

Orbital configuration [orbit]

Parameter Type Default Description
semimajoraxis float 1.0 Initial semi-major axis of the planet's orbit [AU]. Must be > 0.
eccentricity float 0.0 Initial Eccentricity of the planet's orbit. Must be >= 0 and < 1.
instellation_method str "distance" Whether to use the semi-major axis ('distance') or instellation flux ('inst') to define the planet's initial orbit. With 'inst' the semi-major axis follows the flux at every step, so a giant impact's semi-major axis change is not applied; its eccentricity change is. Choices: "distance", "inst".
instellationflux float 1.0 Instellation flux initially received by the planet in Earth units. Must be > 0.
zenith_angle float 48.19 Characteristic angle of incoming stellar radiation, relative to the zenith [deg]. Must be >= 0 and < 90.
s0_factor float 0.375 Scale factor applies to incoming stellar radiation to represent planetary rotation. Must be > 0.
star_planet_model str or none none Select star-planet orbit module to use. Choices: none, "none", "sp0d", "sp1d", "parameterized".
axial_period float or none none Planet initial day length [hours], will use orbital period if value is None. Must be None for sp0d and parameterized, which keep the spin locked to the orbit.
planet_satellite_model str or none none Select planet-satellite orbit module to use. Choices: none, "none", "ps0d", "ps1d", "ps1d_evec".
perturber str or none none Select perturber to induce tides on the planet. Options: 'none', 'star', 'satellite'. Choices: none, "none", "star", "satellite".
module str or none none Select tides module to use. Choices: none, "dummy", "lovepy", "obliqua".

Satellite [orbit.satellite]

Parameter Type Default Description
include_satellite bool false Whether to model a satellite orbiting the planet.
mass_sat float 0.012 Satellite mass [M_earth]. Must be > 0.
radius_sat float 0.273 Satellite radius [R_earth]. Must be > 0.
axial_period_sat float or none none Satellite initial day length [hours], will use orbital period if value is None.
semimajoraxis_sat float 3.5 Satellite initial semi-major axis [R_earth]. Must be > 0.
eccentricity_sat float 0.0 Satellite initial orbital eccentricity [dimensionless]. Must be >= 0.
evection_angle float 0.0 Satellite evection angle [deg]. Must be >= 0.
c_factor_sat float 0.4 Satellite tidal dissipation factor (<= 0.4) [dimensionless]. Must be > 0 and <= 0.4.
love_number_sat str or none none Satellite love number spectrum, provide absolute path to netCDF file containing forcing frequencies and complex Lovenumbers, and corresponding tidal degree in nmk format.

Solver [orbit.solver]

Shared numerical-solver settings for the orbital-evolution ODE models, used by both the star-planet models (sp0d, sp1d) and the planet- satellite models (ps0d, ps1d, ps1d_evec).

Parameter Type Default Description
method str "Radau" scipy.integrate.solve_ivp integration method. Choices: "RK45", "RK23", "DOP853", "Radau", "BDF", "LSODA".
rtol float 1e-06 Relative tolerance passed to solve_ivp. Must be > 0.
atol float 1e-09 Absolute tolerance passed to solve_ivp. Must be > 0.
dt0_yr float 0.0001 Initial adaptive-substep size [yr]. Must be > 0.
dt_max_yr float 2000.0 Maximum adaptive-substep size [yr]. Must be > 0.
growth float 1.15 Substep growth factor applied after an accepted step. Must be > 1.0.
shrink float 0.35 Substep shrink factor applied after a rejected step. Must be > 0 and < 1.
max_rel_da float 0.01 Maximum tolerated relative change in semi-major axis per substep. Must be > 0.
max_rel_de float 0.01 Maximum tolerated relative change in eccentricity per substep. Must be > 0.
max_rel_dOmega float 0.02 Maximum tolerated relative change in a spin rate per substep. Must be > 0.
de_floor float 0.05 Floor on the eccentricity-change-ratio denominator, so a small starting eccentricity does not make the ratio spuriously huge. Must be > 0.
max_substeps int 10000000 Maximum number of substeps attempted per call. Must be > 0.
resonance_margin_enter float 0.1 Evection-band entry margin (ps1d_evec only). Must be > 0.
resonance_margin_exit float 0.5 Evection-band exit margin (ps1d_evec only). Must be > 0.
resonance_margin_approach float 0.3 Wider, purely-diagnostic margin used to set a pre-emptive signal that the system is closing in on the band before the tighter resonance_margin_enter would declare capture. Must be > 0.
fine_csv_target_rel_dt float 0.01 Target storage-clock spacing for out-of-band fine samples, as a fraction of the requested call duration (ps1d_evec only). Must be > 0.

Parameterized migration [orbit.parameterized]

Prescribed migration track used by the parameterized star-planet model.

Parameter Type Default Description
sma_final float or none none Final semi-major axis [AU]. Must be > 0.
migration str "none" Type of orbital migration to apply. Choices: "none", "instant", "sigmoid", "high_ecc".
time_migration float 1000000.0 Time at which migration begins [yr]. Must be > 1.
tau_migration float 1000000000.0 Timescale of migration, used by the sigmoid and high_ecc laws [yr]. Must be > 0.

Dummy tides [orbit.dummy]

Fixed tidal heating rates, useful for parameter studies.

Parameter Type Default Description
H_tide float 0.0 Fixed global heating rate from tides [W kg-1]. Must be >= 0.0.
Phi_tide str "<0.3" Inequality which, if locally true, determines in which regions tides are applied.
Imk2 float 0.0 Imaginary part of k2 Love number, which is usually negative. Must be <= 0.0.

LovePy tides [orbit.lovepy]

Self-consistent tidal heating using viscoelastic Love numbers computed from the interior rheological profile.

Parameter Type Default Description
visc_thresh float 1000000000.0 Minimum viscosity required for heating [Pa s]. Must be > 0.
ncalc int 1000 Number of interpoltaed interior levels to use for solving tidal heating rates. Must be > 100.

Obliqua tides [orbit.obliqua]

Self-consistent, multi-phase tidal response computed from the interior's solid, mushy, and fluid layers, each handled by a dedicated sub-model. Valid for arbitrary eccentricity and tidal mode.

Parameter Type Default Description
store_3D bool false Whether to store 3D information for solid tides.
enforce_ec bool true Whether to enforce energy conservation between Lovenumbers and heating profile.
optimize_scales bool false Whether to optimize the non-dimensional scaling parameters for solid tides.
solid_shell bool true Whether to insert an infinitesimal solid shell around the core.
cap_LN bool false Whether to clamp each mode's Love number to a fixed multiple of the classical fluid limit for its degree.
min_frac float 0.02 Minimal segment radius fraction before smoothing. Must be > 0.
visc_lus float 500000.0 Liquidus viscosity [Pa s]. Must be > 0.
visc_sus float 500000.0 Solidus viscosity [Pa s]. Must be > 0.
n list [2] Power of the radial factor (r/a)^n.
m list [0, 2] Tidal harmonic (m=2 semidiurnal, m=1 diurnal).
k_min int or Literal "none" Minimum Fourier index in mean anomaly (adaptive spectrum).
k_max int or Literal "none" Maximum Fourier index in mean anomaly (adaptive spectrum).
evection_padding_factor float 2.0 Safety multiplier on the linear look-ahead eccentricity padding applied to Obliqua's own adaptive k-range selection. Must be >= 0.
material_mu str "andrade" Rheology model for complex shear modulus ("andrade" or "maxwell"). Choices: "andrade", "maxwell", "elastic".
material_k str "andrade" Rheology model for complex bulk modulus ("andrade" or "maxwell"). Choices: "andrade", "maxwell", "elastic".
alpha float 0.3 Andrade power-law exponent. Must be > 0.
verbosity int 1 Logging verbosity level (0=silent, 1=info, 2=debug). Choices: 0, 1, 2.
module_solid str "solid0d" Solid-tide module to use ("none", "solid0d", "solid1d", "solid1d-relax", "solid1d-mush", "solid1d-mush-relax", "solid1d-equil-relax"). Choices: "none", "solid0d", "solid1d", "solid1d-relax", "solid1d-mush", "solid1d-mush-relax", "solid1d-equil-relax".
module_mushy str "none" Mushy-tide module to use ("none", "interp"). Choices: "none", "interp".
module_fluid str "fluid0d" Fluid-tide module to use ("none", "fluid0d", "fluid1d"). Choices: "none", "fluid0d", "fluid1d".

Solid tides [orbit.obliqua.solid]

Parameter Type Default Description
ncalc int 1000 Number of interpolated interior levels to use for solving tidal heating rates (shooting method). Must be > 100.
dr_min int 300 Minimum radial grid spacing [m] (Henyey/relaxation method). Must be > 0.
dr_max int 3000 Maximum radial grid spacing [m] (Henyey/relaxation method). Must be > 0.
core str "liquid" Core solution vector ("liquid", "solid", "inertial-liquid", or "inertial"). Choices: "liquid", "solid", "inertial-liquid", "inertial".
core_props str "core" Core properties to use ("core" or "mantle"). Choices: "core", "mantle".
inertial_terms bool true Whether to include inertial terms in the solid-tide solution.
bulk_l float 1000000000.0 Bulk modulus of the liquid phase [Pa]. Must be > 0.
porosity_thresh float 0.03 Porosity threshold, hard cutoff below which melt fraction is set to zero [dimensionless]. Must be > 0.
dbulk_power float 0.5 Drained bulk modulus powerlaw scaling exponent [dimensionless]. Must be > 0.

Mushy tides [orbit.obliqua.mushy]

Parameter Type Default Description
b_width float 0.5 Scale width of the bottom heating decay profile [dimensionless]. Must be > 0.
t_width float 0.03 Scale width of the top heating decay profile [dimensionless]. Must be > 0.

Fluid tides [orbit.obliqua.fluid]

Parameter Type Default Description
sigma_R float 0.001 Rayleigh drag in the fluid-mush/solid boundary layers [1/s]. Must be > 0.
sigma_R_factor float 0.5 Rayleigh drag in the pure fluid as a fraction of the interface [dimensionless]. Must be > 0.
sigma_R_prf str "exp" Radial heating distribution profile [dimensionless]. Choices: "uniform", "exp", "linear", "quadratic", "dynamic", "dynamic_interp".
H_R float 10000.0 Scale height to be used by heating profile [m]. Must be > 0.
efficiency float 0.3 Rayleigh drag efficiency at core interface [dimensionless]. Must be > 0.

Constraints

Cross-field constraints enforced when the config file loads:

  • Instellation method 'inst' is only available with the dummy star module.
  • Orbital evolution cannot be combined with instellation method 'inst'.
  • The Obliqua tidal-response module requires an explicit perturber.
  • sp1d, ps1d, and ps1d_evec require at least Lovepy, but ideally the Obliqua tidal-response module: all three read the full per-mode spectrum in tides_o, which dummy never populates. sp0d/ps0d read the scalar Imk2 instead (which dummy does provide), so they are unrestricted here; see "Compatibility between orbit models and tidal modules" in docs/Explanations/orbit.md.
  • The parameterized model prescribes the orbit as a closed-form track and exchanges no energy with the interior, so no tides module can run alongside it; see "Star-planet models" in docs/Explanations/orbit.md.
  • The high-eccentricity law circularises at fixed orbital angular momentum, which can only shrink the orbit, so its final semi-major axis must not exceed the initial one, orbit.semimajoraxis.
  • Star-planet orbital evolution and the planet-satellite model are mutually exclusive.
  • sp0d's closed-form is by definition the n=2 Love number. Obliqua can compute arbitrary tidal degree(s), block the mismatch.
  • sp0d and parameterized evolve no spin, so the planet stays synchronous and orbit.axial_period must be unset; see "Star-planet models" in docs/Explanations/orbit.md.
  • A bolometric scaling other than 1 requires bol_scale_start and a positive duration.
  • Validate MORS settings: positive age, spectrum-source requirements, and rotation set by exactly one of percentile or period.
  • Dummy star requires a consistent radius specification and a valid Teff.

See also: Stellar module | Tidal evolution | Orbital evolution | Orbital dynamics and tides (full model overview)

  1. Spada, F., Demarque, P., Kim, Y.C. & Sills, A., The radius discrepancy in low-mass stars: single versus binaries, The Astrophysical Journal, 776, 87, 2013. SciX. ↩

  2. Baraffe, I., Homeier, D., Allard, F. & Chabrier, G., New evolutionary models for pre-main sequence and main sequence low-mass stars down to the hydrogen-burning limit, Astronomy & Astrophysics, 577, A42, 2015. SciX. ↩