Gas-giant extension API¶

EvoAtmosphereGasGiant extends EvoAtmosphere with initialization and domain-management tools for gas-rich planets. It initializes composition from chemical equilibrium along a supplied climate profile, manages the deeper photochemical domain, and provides helpers for saving and restoring model state.

EvoAtmosphereGasGiant ¶

EvoAtmosphereGasGiant(
    mechanism_file,
    stellar_flux_file,
    planet_mass,
    planet_radius,
    nz=100,
    photon_scale_factor=1.0,
    solar_zenith_angle=60.0,
    P_ref=1000000.0,
    thermo_file=None,
    data_dir=None,
)

Bases: EvoAtmosphere

Photochemical workflow for modeling gas-rich planets.

The constructor configures static photochemical data. Call initialize_to_climate_equilibrium_PT before integrating, or restore a previously saved state with initialize_from_dict.

Attributes:

Name	Type	Description
`gdat`	`GasGiantData`	Gas-giant configuration and saved climate-grid profiles.
`dat, var, wrk`		Live views inherited from photochem.EvoAtmosphere.

Configure a gas-giant photochemical model.

Parameters:

Name	Type	Description	Default
`mechanism_file`	`str`	Path to the file describing the reaction mechanism	required
`stellar_flux_file`	`str`	Path to the file describing the stellar UV flux.	required
`planet_mass`	`float`	Planet mass in grams	required
`planet_radius`	`float`	Planet radius in cm	required
`nz`	`int`	The number of layers in the photochemical model, by default 100	`100`
`photon_scale_factor`	`float`	Factor multiplying the input stellar photon flux, by default 1.	`1.0`
`solar_zenith_angle`	`float`	Solar zenith angle in degrees, by default 60.	`60.0`
`P_ref`	`float`	Pressure corresponding to `planet_radius`, by default 1e6 dyn/cm^2.	`1000000.0`
`thermo_file`	`str`	Optionally include a dedicated thermodynamic file.	`None`
`data_dir`	`str`	Path to the data directory containing photolysis cross sections and other data needed to run the model. The packaged data are used by default.	`None`

Notes

Construction does not initialize an atmosphere. The pressure, temperature, eddy-diffusion, and composition profiles are supplied by a subsequent initialization method.

initialize_to_climate_equilibrium_PT ¶

initialize_to_climate_equilibrium_PT(
    P_in,
    T_in,
    Kzz_in,
    metallicity,
    CtoO,
    rainout_condensed_atoms=True,
)

Initialize from a climate profile and equilibrium composition.

Input arrays must be one-dimensional, equal in length, and ordered from highest pressure (deepest) to lowest pressure. The initialized photochemical domain begins below the estimated quench levels and ends at var.toa_pressure_maintenance.target_pressure.

Parameters:

Name	Type	Description	Default
`P_in`	`(ndarray, shape(nprofile))`	Climate-grid pressure in dyn/cm^2, decreasing with index.	required
`T_in`	`(ndarray, shape(nprofile))`	Climate-grid temperature in K.	required
`Kzz_in`	`(ndarray, shape(nprofile))`	Climate-grid eddy diffusion in cm^2/s.	required
`metallicity`	`float`	Metallicity relative to solar.	required
`CtoO`	`float`	C/O ratio relative to solar. So CtoO = 1 is solar C/O ratio. CtoO = 2 is twice the solar C/O ratio.	required
`rainout_condensed_atoms`	`bool`	Remove condensed atoms during equilibrium calculations, by default True.	`True`

reinitialize_to_new_climate_PT ¶

reinitialize_to_new_climate_PT(P_in, T_in, Kzz_in, mix)

Reinitialize from updated climate profiles and composition.

This method requires a prior call to initialize_to_climate_equilibrium_PT, and P_in must match that original climate pressure grid.

Parameters:

Name	Type	Description	Default
`P_in`	`(ndarray, shape(nprofile))`	Climate-grid pressure in dyn/cm^2, decreasing with index.	required
`T_in`	`(ndarray, shape(nprofile))`	Climate-grid temperature in K.	required
`Kzz_in`	`(ndarray, shape(nprofile))`	Climate-grid eddy diffusion in cm^2/s.	required
`mix`	`dict[str, ndarray]`	Mixing-ratio profile for every gas species. Each value has shape `(nprofile,)`.	required

return_atmosphere_climate_grid ¶

return_atmosphere_climate_grid()

Return prescribed profiles and composition on the climate grid.

Temperature and eddy diffusion are the saved climate inputs. Species mixing ratios are log-interpolated or constant-extrapolated from the photochemical result.

Returns:

Type	Description
`dict[str, ndarray]`	`pressure` (dyn/cm^2), `temperature` (K), `Kzz` (cm^2/s), and a mixing-ratio array for each modeled species.

return_atmosphere ¶

return_atmosphere(
    include_deep_atmosphere=True,
    equilibrium=False,
    rainout_condensed_atoms=True,
)

Return atmospheric profiles on the photochemical pressure grid.

Parameters:

Name	Type	Description	Default
`include_deep_atmosphere`	`bool`	Prepend the deeper prescribed atmosphere, evaluated in chemical equilibrium, by default True.	`True`
`equilibrium`	`bool`	Return equilibrium rather than photochemical mixing ratios on the photochemical grid, by default False.	`False`
`rainout_condensed_atoms`	`bool`	Remove condensed atoms in equilibrium calculations, by default True.	`True`

Returns:

Type	Description
`dict[str, ndarray]`	`pressure` (dyn/cm^2), `temperature` (K), `Kzz` (cm^2/s), and a mixing-ratio array for each modeled species.

robust_step ¶

robust_step()

Take one shared robust step and optionally report gas-giant progress.

Stepping, recovery, convergence, restart, limit, and TOA-maintenance policy are implemented by EvoAtmosphere. This override only retains the extension's compact progress display.

Returns:

Type	Description
`tuple`	Two booleans `give_up, reached_steady_state` from the shared robust stepper.

model_state_to_dict ¶

model_state_to_dict()

Serialize the initialized gas-giant atmospheric state.

Returns:

Type	Description
`dict`	State accepted by initialize_from_dict.

initialize_from_dict ¶

initialize_from_dict(out)

Restore a state produced by model_state_to_dict.

Any active stepper and pressure-profile prescription are replaced.

Parameters:

Name	Type	Description	Default
`out`	`dict`	Serialized gas-giant state.	required

The inherited photochemical methods and dat, var, and wrk state views are documented in the Photochem API. Gas-giant-specific configuration and saved climate profiles are stored in pc.gdat.

GasGiantData ¶

GasGiantData(
    planet_radius, planet_mass, P_ref, thermo_file
)

Configuration and saved climate profiles for a gas-giant model.

An instance is created as EvoAtmosphereGasGiant.gdat. Pressure is in dyn/cm^2, temperature in K, eddy diffusion in cm^2/s, radius in cm, and mass in g. Attributes ending in _clima_grid retain the user's climate grid; P_desired, T_desired, and Kzz_desired contain the profile extended or truncated for photochemical initialization.