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(
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.
Climate-profile initialization uses periodic P-T-Kzz synchronization by
default. Pass mode=1 to select continuous synchronization.
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 |
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(
P_in,
T_in,
Kzz_in,
metallicity,
CtoO,
rainout_condensed_atoms=True,
**initialize_kwargs
)
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
|
**initialize_kwargs
|
Additional keyword arguments forwarded to |
{}
|
reinitialize_to_new_climate_PT(
P_in, T_in, Kzz_in, mix, **initialize_kwargs
)
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
|
required |
**initialize_kwargs
|
Additional keyword arguments forwarded to |
{}
|
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]
|
|
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]
|
|
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 |
model_state_to_dict()
Save atmospheric profiles for gas-giant reinitialization.
The returned arrays are independent copies. This is not a full model checkpoint: solver history, time, callbacks, and most numerical settings are omitted. The destination must use the same mechanism, layer count, planet mass, reference radius, and reference pressure. The exact installed pressure-temperature-eddy prescription is saved separately from the climate-grid metadata.
Returns:
| Type | Description |
|---|---|
dict
|
State accepted by initialize_from_dict. |
initialize_from_dict(out)
Reinitialize a fresh or previously initialized gas-giant model.
The atmosphere and particle radii are restored, gas lower boundaries are set to the saved partial pressures, and the prescribed P-T-Kzz profile is resynchronized immediately. This can change saved temperature, Kzz, and bottom-layer densities, particularly in periodic mode. TOA-maintenance enablement and profile tolerances are restored. The exact installed prescription is restored independently of the saved climate-grid metadata, including profiles replaced through the base API.
Solver history and integration time are not restored. Other numerical settings and callbacks retain the destination's configuration. Input validation occurs before modifying the model; a runtime initialization failure can still leave it partially reinitialized.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
out
|
dict
|
State from model_state_to_dict. All saved keys are required. The mechanism, layer count, planet mass, reference radius, and reference pressure must match the source. |
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(
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.