Usage

Available Cloud Species

The cloud structures are based on the vapour pressures and nucleation rates of the cloud forming materials. The data and their sources are stored in nimbus/data/chem/cloud_material.csv and can be adjusted to your need. If you have requests for further species, contact me (kiefersv.mail@gmail.com). Currently, the following materials are available:

Al2O3
C
CaTiO3
CH4
Cr
CsCl
Fe
FeO
H2O
H2S
KCl
MgSiO3
Mg2SiO4
MnS
NaCl
Na2S
NH3
NH4Cl
NH4SH
S2
S8
SiO
SiO2
TiO2
ZnS

Main Nimbus functions

Nimbus comes with multiple setting options for the atmospheric structure and the numerical evaluation. Here we go quickly through each function, explaining the different settings available. The main object of Nimbus is defined via the following function which sets general evaluation parameters:

[ ]:

nimb = Nimbus(working_dir='.', create_analytic_plots=False, verbose=False)

working_dir: Directory to store all outputs and default search location for inputs.
create_analytic_plots: If True, analytic plots of the intermediate outputs are created. This significantly slows down calculation but allows for additional insights and debugging.
verbose: If True, additional information is printed. This affects runtime as a progress bar is enabled.

The atmospheric structure is defined via the following function (which also performs all the structure calculations):

[ ]:

nimb.set_up_atmosphere(temperature, pressure, kzz, mmw, gravity, species,
                       deep_mmr, fsed=1, metalicity=1)

temperature: Temperature structure of the atmosphere [K]
pressure: Pressure structure of the atmosphere [bar]. Must have same dimension as temperature.
kzz: Mixing strength coefficient of the atmosphere [cm\(^2\)/s]. Must have same dimension as temperature.
mmw: Mean molecular weight of the atmosphere [amu]. Singular value for the whole atmosphere.
gravity: Gravity of the planet [cm/s\(^2\)]. Singular value for the whole atmosphere.
species: Name of the cloud material. Only one material can be given.
deep_mmr: Mass mixing ratio of the cloud below the cloud deck.
fsed: Initial guess of the particle size, given as settling parameter. Default value is typically sufficient.
metallicity: Gas-phase metallicity relative to solar used for the vapour pressure calculations of some cloud materials.

To simulate the cloud structure, the compute function is called. Here, general settings about how the cloud structure should be calculated can be set:

[ ]:

nimb.compute(typ='convergence', rel_dif_in_mmr=1e-3, max_iterations=None,
             save_file=None)

typ: Determines the type of evaluation. Possibilities are
- ‘convergence’: Iterates over fixed cloud particle radii until the maximum difference is below rel_dif_in_mmr.
- ‘iterate’: Use a fixed number of iterations (particularly useful for retrival tasks)
- ‘full’: Full evaluation of the underlying ODEs (no fixed radius assumption)
rel_dif_in_mmr: If type=’convergence’, the iteration will stop if the maximum difference is below this value.
max_iterations: If type=’iterate’, the iteration will stop after this number of repetitions.
save_file: If a string is given, the run will be saved under the given name in the working_dir.

Additional Nimbus Settings

In addition to the main settings, these functions allow for more detailed control over the Nimbus run. In general, it is not expected that you will need to adjust any of these variables. The following function can be used to adjust settings for the ODE solver:

[ ]:

 nimb.set_solver_settings(
     initial_time_for_solver=None, end_time_for_solver=None,
     evaluation_steps_for_solver=None, degree_of_radius_polinomial=None,
     rtol=None, atol=None, ode_minimum_mmr=None
 )

initial_time_for_solver: This sets the start time of the solver (only relevant for the diagnostic output)
end_time_for_solver: The maximum evaluation time of the solver. It is important to set this valeu large enough for the cloud model to be able to reach a static solution. Default value is 1e15 seconds.
evaluation_steps_for_solver: Number of evaluation points (only relevant for the diagnostic output)
degree_of_radius_polinomial: Degree of the polynomial used for radius smoothing. Default is 8.
rtol: Relative tolarance of the solver. Default is 1e-6.
atol: Absolute tolerance of the solver. Default is 1e-25.
ode_minimum_mmr: Lower limit for the solver, everything lower is considered to be 0 (should be lower than atol).

The cloud physics parameters can be set via the following function:

[ ]:

nimb.set_cloud_settings(minimum_cloud_particle_radius=None, molecular_cross_section=None)

minimum_cloud_particle_radius: Lower size limit of the cloud particles, considered to be the CCN radius. Default is 1e-7 cm.
molecular_cross_section: Molecular cross-section. Default is set for an H\(_2\) gas and is 2e-15 cm\(^2\).

In addition, you might want to add some additional factors to certain parts of the equations. Some of these tweaks (or fudges) are predefined. The default for all values is 1.

[ ]:

nimb.set_fudge_settings(
    nucleation_rate_fudge=None, accreation_rate_fudge=None,
    sticking_coefficient=None
)

nucleation_rate_fudge: Multiplicative factor to the nucleation rate to study how uncertainties in the nucleation rate affect the cloud structure.
accreation_rate_fudge: Decrypted, same as sticking_coefficient.
sticking_coefficient: Chance of a collisional limited accretion reaction to result in the growth of the cloud particle.

Spectra calculations

To generate spectra from cloud models, Nimbus connects to VIRGA and PICASO. Before a spectrum can be produced, the calculations need to be set up:

[ ]:

nimb.set_up_spectra_calculation(mass_planet, radius_planet, temperature_star,
                                radius_star, metalicity_star, logg_star,
                                path_to_opacities=None)

mass_planet: Mass of the planet [M_jup]
radius_planet: Radius of the planet [R_jup]
temperature_star: Temperature of the star [K]
radius_star: Radius of the star [R_sun]
metalicity_star: Metalicity of the star relative to the sun.
logg_star: Gravity of the star [log(cm/s\(^2\))]
path_to_opacities: Nimbus has its own cloud opacities. However, here you can provide another path to your own opacity files (needs to be in the same format as the Nimbus opacity files).

After the cloud structure is set up, the spectrum can be calculated with PICASO. There are multiple intrinsic assumptions within this function and it is advised to adapt this function outside of Nimbus to fit your needs.

[ ]:

nimb.plot_spectrum(chem_data=None, data=None, typ='transmission', tag='last_run',
                   plot=True, cloud_less=False)

chem_data:Dictionary with all abundances for all pressures. Takes the form: chem_data = {‘H2O’: np.asarray([0.1, 0.2, 0.1, 0.1]), ‘CO’: np.asarray([0.004, 0.003, 0.002, 0.001])}
data: Observational data as a 2D array in the form [wavelengths, data, error]
typ: Can be ‘transmission’ or ‘emission’ depending on the use case.
tag: Tag of the model to be calculated. Default is the last run.
plot: Create a diagnostic (but ugly) plot.
cloud_less: If True, ignore cloud structures and calculate a cloud less spectra.

DataStorage

The DataStorage class is an internal functionality that handles the data used by Nimbus. You can also use this class to access the data of Nimbus.

[ ]:

from nimbus import DataStorage

ds = DataStorage(data_file=None)

The datafile can be used to give a self written database. The default file is located at nimbus/data/chem/cloud_material.csv. The following (self explenatory) functions are available:

[ ]:

m_s = ds.monomer_mass(species)  # [g]
R_spec_s = ds.specific_gas_constant(species)  # [erg/g/K]
r_s = ds.monomer_radius(species)  # [cm]
mu_s = ds.molecular_weight(species)  # [amu]
rho_s = ds.solid_density(species)  # [g/cm3]
sigam_s = ds.surface_tension(species, temp)  # [erg/cm2]
G_s = ds.gibbs_free_energy(species, temp)  # [erg]
p_vap_s = ds.vapor_pressures(species, temp, metalicity=1)  # [dyn/cm$^2$]