carmapy.Carma

class carmapy.Carma(name, is_2d=False)

An object representing a CARMA simulation.

Parameters:

• name (str) – A name identifier for the CARMA simulation. This name is used for output directories and file prefixes.

• is_2d (bool, optional) – If True, sets the simulation in 2D mode (longitude x vertical). Defaults to False (1D vertical column). Note: `is_2d=True` is not currently supported.

Examples

>>> carma = Carma("new_carma")

Methods

add_P(…)	Sets pressure levels and centers.
add_T(…)	Sets temperature levels and centers.
add_coag(…)	Adds self coagulation of the given group to the simulation.
add_gas(…)	Adds a gas to the simulation.
add_het_group(…)	Adds a heterogeneously nucleating group to the simulation.
add_hom_group(…)	Adds a heterogeneously nucleating group to the simulation.
add_kzz(…)	Sets eddy diffusion levels.
add_vertical_winds(…)	Sets the vertical wind speeds as a function of altitude.
add_z(…)	Sets altitude levels and centers.
calc_scale_height(…)	Calculates the atmospheric scale height.
calculate_z(…)	Calculate and set the altitude structure in the proper format for the version of carma (1D or 2D) used.
extend_atmosphere(…)	Extends the atmospheric structure to deeper pressures.
read_results(…)	Reads in results of the carma simulation.
run(…)	Runs the CARMA Simulation.
set_atmospheric_parameters(…)	Sets the atmospheric viscosity and thermal conductivity
set_atmospheric_parameters_from_defaults(…)	Sets the atmospheric viscosity and thermal conductivity from a default profile.
set_cloud_boundary(…)	Sets the boundary conditions for the group.
set_cloud_boundary_type(…)	Sets the type of boundary conditions on the cloud particle concentration.
set_gas_boundary(…)	Sets the boundary conditions for the gas.
set_gas_boundary_type(…)	Sets type of boundary conditions on the gas concentration.
set_nmr(…)	Sets the gas number mixing ratios of the simulation
set_physical_params(…)	Modifies the physical parameters of the simulation.
set_stepping(…)	Modifies the simulation timestepping behavior.

Attributes

coags	List of the coagulation pathways enabled in the sim
dt	Simulation timestep [s]
elems	Dictionary of the element objects indexed by elem name used in the sim
gases	Dictionary of the gas objects, indexed by gas name, used in the sim
groups	Dictionary of group objects indexed by group name used in the sim
growth	List of the microphysical growth pathways enabled in the sim
iappend	1 if and only if a restarted run should add to existing files (default 0)
is_2d	If true, the simulation is a 2D Carma sim, otherwise 1D
kzz_levels	Eddy diffusion coefficient levels [cm²/s].
log_metallicity	Log10 Solar Metallicity (Default 0)
n_tstep	Total number of timesteps
name	The name of the directory the carma object is saved / loaded from
NBIN	Number of particle radius bins (default 80).
NLONGITUDE	Number of longitude bins (used only in 2D mode).
nucs	List of the nucleation pathways enabled in the sim
NZ	Number of vertical layers in the atmospheric grid.
output_gap	Number of timesteps between each simulation output
P_centers	Pressure center values (between levels) [barye].
P_levels	Pressure levels starting from bottom of atmosphere [barye].
r_planet	Planet radius [cm] (Defaults to 1 Jovian radius); ignored in 1D mode.
restart	If true, continues the simulation from a previously stored state (Default False)
surface_grav	Surface gravity of the planet / brown dwarf [cm/s²]
T_centers	Temperature center values (between levels) [K].
T_levels	Temperature levels [K].
velocity_avg	Mean longitudinal wind speed at the equator [cm/s]; ignored in 1-D mode
wt_mol	Mean molecular weight of the atmosphere [dimentionless]
z_centers	Altitude center values (between levels) [cm].
z_levels	Altitude levels where z=0 is bottom of atmosphere [cm].

Carma.add_P(levels)

Sets pressure levels and centers. Uses provided levels to calculate the pressure centers and checks to see if the provided levels are compatible in array shape with the other inputs already provided to carma. If NZ is not set, sets NZ. The first element of the levels array should correspond to the bottom of the atmosphere.

Parameters:

levels (TypeAliasType) – Pressure values at the boundaries of the atmospheric cells [barye]

Return type:

None

Carma.add_T(levels)

Sets temperature levels and centers. Uses provided levels to calculate the temperature centers and checks to see if the provided levels are compatible in array shape with the other inputs already provided to carma. If NZ is not set, sets NZ. The first element of the levels array should correspond to the bottom of the atmosphere.

Parameters:

levels (TypeAliasType) – Temperature values at the boundaries of the atmospheric cells [K]. For 1-D CARMApy should be of shape (NZ,). For 2-D CARMApy should be of shape (NZ, NLONGITUDE)

Return type:

None

Carma.add_coag(group)

Adds self coagulation of the given group to the simulation.

Parameters:

group (Union[str, Group]) – Group object or name of group to add self-coagulation to

Return type:

None

Carma.add_gas(gas, **kwargs)

Adds a gas to the simulation.

If a string is passed gas then if the gas does not already exist in the simulation, the carmapy default properties of that gas will be used. Passes **kwargs to the Gas constructor if a new gas is created.

Parameters:

gas (Union[str, Gas]) – Gas object or name of the carmapy default gas to be added to the simulation

Returns:

The gas which was added to the simulation.

Return type:

Gas

Carma.add_het_group(gas, seed_group, rmin, mucos=None, add_coag=False, T_ref=1000)

Adds a heterogeneously nucleating group to the simulation. Assumes the gas nucleates on the seed particle. If a string is passed to gas, will use the carmapy default parameters for that gas if that gas does not already exist in the simulation. Additionally adds the gas and any created elements, nuc objects, growth objects, and coag objects to the simulation.

Parameters:

• gas (Union[str, Gas]) – Gas object, name of already created gas, or name of the default carmapy gas that nucleates on the seed particle

• seed_group (Union[str, Group]) – Group object, name of group, or name of gas that formed the group which serves as the seed particle for the condensate

• rmin (float) – Minimum radius of the condensate [cm]

• mucos (float) – Cosine of the contact angle between the gas and the seed particle, if not provided defaults to carmapy defaults

• add_coag (bool) – If true, allows coagulation of this particle onto itself, by default False

• T_ref (float) – If a mucos is not provided, will use Young’s equation to calculate the mucos at this temperature

Returns:

The created group consisting of the gas nucleated onto the seed particle

Return type:

Group

Carma.add_hom_group(gas, rmin, add_coag=False)

Adds a heterogeneously nucleating group to the simulation. Assumes the gas homogeneously nucleates. If a string is passed to gas, will use the carmapy default parameters for that gas if that gas does not already exist in the simulation. Additionally adds the gas and any created elements, nuc objects, growth objects, and coag objects to the simulation.

Parameters:

• gas (Union[str, Gas]) – Gas object, name of already created gas, or name of the default carmapy gas that homogeneously nucleates

• rmin (float) – Minimum radius of the condensate [cm]

• add_coag (bool) – If true, allows coagulation of this particle onto itself, by default False

Returns:

The created group consisting of the homogeneously nucleated gas

Return type:

Group

Carma.add_kzz(levels)

Sets eddy diffusion levels. Checks to see if the provided levels are compatible in array shape with the other inputs already provided to carma. If NZ is not set, sets NZ. The first element of the levels array should correspond to the bottom of the atmosphere.

Parameters:

levels (TypeAliasType) – Eddy diffusion coefficient values at the boundaries of the atmospheric cells [cm²/s]

Return type:

None

Carma.add_vertical_winds(wind_centers)

Sets the vertical wind speeds as a function of altitude. Note that unlike most other functions, this one requires wind speeds on the centers, not the levels, of the atmosphere

Parameters:

wind_centers (TypeAliasType) – The vertical wind speed at each altitude center [cm/s]

Carma.add_z(levels)

Sets altitude levels and centers. Uses provided levels to calculate the altitude centers and checks to see if the provided levels are compatible in array shape with the other inputs already provided to carma. If NZ is not set, sets NZ. z=0 should be the first element in the levels array which corresponds to the bottom of the atmosphere.

Parameters:

levels (TypeAliasType) – Altitude values at the boundaries of the atmospheric cells [cm]

Return type:

None

Carma.calc_scale_height(calc_centers=False)

Calculates the atmospheric scale height.

Parameters:

calc_centers (bool, optional) – if True calculates scale height at centers, otherwise calculates it at levels, by default False

Returns:

The scale height of the atmosphere at each center/level point

Return type:

ndarray

Carma.calculate_z(wt_mol=None)

Calculate and set the altitude structure in the proper format for the version of carma (1D or 2D) used. Uses P and T levels to calculate the altitude structure using scale heights.

Parameters:

wt_mol (float | TypeAliasType) – Mean molecular weight of the atmosphere. If an array, must be the same length as “levels” arrays, if not provided instead uses the mean molecular weight stored in the simulation.

Return type:

None

Carma.extend_atmosphere(max_P, wt_mol=None, method='adiabatic')

Extends the atmospheric structure to deeper pressures. Modifies the pressure, temperature, and eddy diffusion levels and requires that they have previously been set. If max_P is less than the current maximum pressure, this method does nothing

Parameters:

• max_P (float) – The pressure to which the atmosphere is extended

• wt_mol (ArrayLike, optional) – The mean molecular weight of the atmosphere. If an array, each entry corresponds to one altitude level. Defaults to the mean molecular weight stored in the carma object

• method (string, optional) – The method to extend the atmosphere. Options are “adiabatic” and “isothermal”

Return type:

None

Notes

Atmosphere is extended adiabatically using the fit from Parmentier et al. (2015) [1] to the equation of state described in Saumon (1995) [2]. k_zz is assumed to be proportional to the cube root of the scale height

References

[1]

Parmentier, V., Guillot, T., Fortney, J. J., & Marley, M. S. 2015, A&A, 574, A35

[2]

Saumon, D., Chabrier, G., & van Horn, H. M. 1995, The Astrophysical Journal Supplement Series, 99 (IOP), 713

Carma.read_results(read_diag=False)

Reads in results of the carma simulation.

Parameters:

• fraction. (If true reads in the microphysical rates and core mass)

• False. (Defaults to)

Return type:

None

See also

carmapy.Results

Return type:

None

Carma.run(suppress_output=False, error_on_warn=True)

Runs the CARMA Simulation.

Creates a directory at the path described by the name of the simulation and populates it with the input files required to run the CARMA executable. Runs and print the stdout from the CARMA executable unless suppress_output is true. The carma executable will also write to output files in the created directory.

Parameters:

• suppress_output (bool, optional) – If true, will not print stdout from the CARMA executable, by default False

• error_on_warn (bool, optional) – If true will throw an error if carmapy’s common sense checks fail (NOT YET IMPLEMENTED)

Return type:

None

Carma.set_atmospheric_parameters(rmu_0, rmu_t0, rmu_c, thcond_0, thcond_1, thcond_2, cp)

Sets the atmospheric viscosity and thermal conductivity

Notes

1. Atmospheric viscosity, rmu, is set by the following formula (the Sutherland equation): rmu = rmu_0 * ((rmu_t0 + tmu_c)/(T + rmu_t0)) * (T/rmu_t0) ** 1.5 where T is the local atmospheric temperature

2. Atmosphgeric thermal conductivity, thcond is set by the following formula: thcond = thcond_0 + thcond_1*T + thcond_2 * T**2

Parameters:

• rmu_0 (float) – Viscosoty scaling term [Poise]

• rmu_t0 (float) – Viscosity reference temp [K]

• rmu_c (float) – Viscosity Sutherland constant [K]

• thcond_0 (float) – Consant thermal conductivity term [ergs/s/cm/K]

• thcond_1 (float) – Coefficient to linear thermal conductivity term [ergs/s/cm/K^2]

• thcond_2 (float) – Coefficient to quadratic thermal conductivity term [ergs/s/cm/K^3]

• cp (float) – Specific heat capacity of the atmosphere [erg/g/K]

Return type:

None

Carma.set_atmospheric_parameters_from_defaults(default)

Sets the atmospheric viscosity and thermal conductivity from a default profile. Currently available defaults are:

• “Pure H2”

Parameters:

default (str) – The name of the default profile to use

Return type:

None

Carma.set_cloud_boundary(group, bot_conc=0.0, top_conc=0.0, bot_flux=0.0, top_flux=0.0)

Sets the boundary conditions for the group. Throws an error if used on a multi-element group (ex. a heterogeneously nucleated group)

Parameters:

• group (Union[str, Group]) – The group to set the boundary conditions for

• bot_conc (ArrayLike, optional) – Either 0 or an array of NBIN elements describing the concentration of each bin in the group at the bottom of the atmosphere. Only used if the bottom cloud boundary condition is set to “fixed_conc”. [particles/cm^3]. By default 0 for all bins

• top_conc (ArrayLike, optional) – Either 0 or an array of NBIN elements describing the concentration of the group at the top of the atmosphere for each bin. Only used if the top cloud boundary condition is set to “fixed_conc”. [particles/cm^3]. By default 0 for all bins

• bot_flux (ArrayLike, optional) – Either 0 or an array of NBIN elements describing the upwards flux of the group at the bottom of the atmosphere for each bin. Only used if the bottom cloud boundary condition is set to “fixed_flux”. [particles/cm^2/s]. By default 0 for all bins

• top_flux (ArrayLike, optional) – Either 0 or an array of NBIN elements describing the concentration of the group at the bottom of the atmosphere for each bin. Only used if the cloud boundary condition is set to “fixed_conc”. [particles/cm^3]. By default 0 for all bins.

Return type:

None

Carma.set_cloud_boundary_type(top_boundary_type, bottom_boundary_type)

Sets the type of boundary conditions on the cloud particle concentration. Note that the same boundary condition type must be used for all cloud species (although different types can be chosen for the bottom of the atmosphere vs the top)

Parameters:

• top_boundary_type (str) – Which type of boundary condtion to use at the top of the atmosphere. Options are “fixed_conc”, “fixed_flux”, or “zero_grad”

• bottom_boundary_type (str) – Which type of boundary condtion to use at the bottom of the atmosphere. Options are “fixed_conc”, “fixed_flux”, or “zero_grad”

Return type:

None

Carma.set_gas_boundary(gas, bot_conc=None, top_conc=None, bot_flux=None, top_flux=None)

Sets the boundary conditions for the gas. Will leave any unspecified boundary conditions unchanged, potentially remaining with the default behavior for the gas (see Gas).

Parameters:

• gas (Union[str, Group]) – gas group to set the boundary conditions for

• bot_conc (float, optional) – The number mixing ratio of the gas at the bottom of the atmosphere. Only used if the bottom gas boundary condition is set to “fixed_conc”. [particles/particles].

• top_conc (float, optional) – The number mixing ratio of the gas at the top of the atmosphere Only used if the top gas boundary condition is set to “fixed_conc”. [particles/particles].

• bot_flux (float, optional) – The upwards flux of the gas at the bottom of the atmosphere for. Only used if the bottom gas boundary condition is set to “fixed_flux”. [particles/cm^2/s].

• top_flux (ArrayLike, optional) – The concentration of the gas at the bottom of the atmosphere. Only used if the cloud boundary condition is set to “fixed_conc”. [particles/cm^3].

Return type:

None

Carma.set_gas_boundary_type(top_boundary_type, bot_boundary_type)

Sets type of boundary conditions on the gas concentration. Note that the same boundary condition type must be used for all cloud species (although different types can be chosen for the bottom of the atmosphere vs the top)

Parameters:

• top_boundary_type (str) – Which type of boundary condtion to use at the top of the atmosphere. Options are “fixed_conc”, “fixed_flux”, or “zero_grad”

• bot_boundary_type (str) – Which type of boundary condtion to use at the bottom of the atmosphere. Options are “fixed_conc”, “fixed_flux”, or “zero_grad”

Return type:

None

Carma.set_nmr(nmr_dict)

Sets the gas number mixing ratios of the simulation

Parameters:

nmr_dict (dict[str, TypeAliasType]) – The number mixing ratio for each species. The dictionary keys should be the name of gases in the simulation. The dictionary values should either be a float representing the mixing ratio at the bottom of the atmosphere or an array representing the mixing ratio at each atmospheric center

Return type:

None

Carma.set_physical_params(surface_grav=None, wt_mol=None, log_metallicity=None, r_planet=None, velocity_avg=None, use_jovian_radius=False)

Modifies the physical parameters of the simulation. Can be used to set the surface gravity, the mean molecular weight, the log metallicity of the planet, the planetary radius, and the average longitudinal equatorial wind speed velocity. Will leave as-is any parameter not provided

Parameters:

• surface_grav (float) – Surface gravity [cm/s²], left as is if not provided

• wt_mol (float) – Mean molecular weight [dimensionless], left as is if not provided

• log_metallicity (float) – Log 10 metallicity relative to solar ([Fe/H]), left as is if not provided

• r_planet (float) – The planetary radius [cm (or R_J if use_jovian_radius is true)], left as is if not provided

• velocity_avg (float) – The average longitudinal wind speed at the equator, left as is if not provided

• use_jovian_radius (bool) – Set to true to provide planetary radius in Jovian radii, by default False

Return type:

None

Carma.set_stepping(dt=None, output_gap=None, n_tstep=None)

Modifies the simulation timestepping behavior. Specifically, sets the simulation timestep, gap between outputs, and total number of timesteps. Will leave as-is any parameter not provided

Parameters:

• dt (float | None) – Simulation timestep [s], left as is if not provided

• output_gap (int | None) – Gap between simulation outputs, left as is if not provided

• n_tstep (int | None) – Total number of timesteps to run the simulation for, left as is if not provided

Return type:

None