Ice Thermodynamics

API reference for the pygotm.icethm package. The package provides five ice/snow thermodynamics models dispatched through a unified Numba kernel. See Ice Thermodynamics for the full scientific description of each model.

Driver

Driver helpers for pyGOTM ice thermodynamics models.

pygotm.icethm.driver.init_ice(params, *, T_air_init, S_sfc_init)[source]

Initialize mutable ice state from immutable YAML-derived parameters.

Return type:

IceState

Parameters:
pygotm.icethm.driver.step_ice(model, T_w, S_w, T_air, h_sfc, dt, diff_t_up, Qsw, Ql, Qh, Qe, precip, ustar, winton_surface_flux_a, winton_surface_flux_b, Hice, Hsnow, Hfrazil, dHis, dHib, T1, T2, Tice_surface, fdd, ice_cover, Tf, albedo_ice, attenuation_ice, transmissivity, ocean_ice_flux, ocean_ice_heat_flux, ocean_ice_salt_flux, surface_ice_energy, bottom_ice_energy, melt_rate, T_melt, S_melt)[source]

Dispatch one ice-model step and return temperature flux and water T.

Return type:

tuple[float, float]

Parameters:
pygotm.icethm.driver.compute_diff_t_up_from_ice(state, *, diff_t_up, rho0, cp)[source]

Apply diagnosed ocean-ice heat flux to a pyGOTM temperature flux.

Return type:

float

Parameters:
pygotm.icethm.driver.outputs_to_buffers(state, reference_scalars, slot)[source]

Write ice scalar diagnostics into runtime reference scalar buffers.

Return type:

None

Parameters:

Parameters

Configuration parameters for ice thermodynamics models.

class pygotm.icethm.params.IceModelEnum(*values)[source]

Bases: IntEnum

Stable integer identifiers for Numba dispatch.

NO_ICE = 0
SIMPLE = 1
BASAL_MELT = 2
LEBEDEV = 3
MYLAKE = 4
WINTON = 5
class pygotm.icethm.params.IceParams(model, Hice_init=0.0, Hsnow_init=0.0, ocean_ice_flux_init=0.0)[source]

Bases: object

Immutable scalar parameters used to initialize and dispatch ice models.

Parameters:
model: IceModelEnum
Hice_init: float = 0.0
Hsnow_init: float = 0.0
ocean_ice_flux_init: float = 0.0
pygotm.icethm.params.canonical_ice_model(value, default='simple')[source]

Return the configured ice model enum.

Tokens accept the same hyphen/underscore normalization used by the GOTM YAML parser.

Return type:

IceModelEnum

Parameters:
pygotm.icethm.params.make_ice_params(*, model=IceModelEnum.SIMPLE, Hice_init=0.0, Hsnow_init=0.0, ocean_ice_flux_init=0.0)[source]

Build validated scalar ice parameters.

Return type:

IceParams

Parameters:
pygotm.icethm.params.make_ice_params_from_mapping(mapping)[source]

Create IceParams from a surface.ice YAML mapping.

Return type:

IceParams

Parameters:

mapping (dict[str, Any])

State

Mutable ice thermodynamics state.

Numba kernels mutate length-one np.float64 and np.int32 arrays for scalar state. This mirrors the rest of pyGOTM’s compiled runtime style while keeping all simulation state explicit and serializable from YAML-derived parameters.

class pygotm.icethm.state.IceState(Hice, Hsnow, Hfrazil, dHis, dHib, T1, T2, Tice_surface, fdd, ice_cover, Tf, albedo_ice, attenuation_ice, transmissivity, ocean_ice_flux, ocean_ice_heat_flux, ocean_ice_salt_flux, surface_ice_energy, bottom_ice_energy, melt_rate, T_melt, S_melt)[source]

Bases: object

Container for mutable scalar ice state arrays.

Parameters:
Hice: ndarray
Hsnow: ndarray
Hfrazil: ndarray
dHis: ndarray
dHib: ndarray
T1: ndarray
T2: ndarray
Tice_surface: ndarray
fdd: ndarray
ice_cover: ndarray
Tf: ndarray
albedo_ice: ndarray
attenuation_ice: ndarray
transmissivity: ndarray
ocean_ice_flux: ndarray
ocean_ice_heat_flux: ndarray
ocean_ice_salt_flux: ndarray
surface_ice_energy: ndarray
bottom_ice_energy: ndarray
melt_rate: ndarray
T_melt: ndarray
S_melt: ndarray
pygotm.icethm.state.make_ice_state()[source]

Return default no-ice state.

Defaults represent open water: no ice or snow, ocean albedo, full shortwave transmissivity, and zero ice-ocean fluxes.

Return type:

IceState

Constants

Constants for pyGOTM ice thermodynamics kernels.

Values in this module come from the model papers kept outside the package tree under the local papers/ directory:

  • Winton (2000), “A Reformulated Three-Layer Sea Ice Model”, for the three-layer sea-ice heat-capacity and optics constants.

  • Holland and Jenkins (1999), “Modeling Thermodynamic Ice-Ocean Interactions at the Base of an Ice Shelf”, for ice-ocean exchange and basal-melt constants.

  • McDougall and Jackett (2002), “Accurate and Computationally Efficient Algorithms for Potential Temperature and Density of Seawater”, for the potential-temperature freezing polynomial used by the basal-melt closure.

Sign convention: positive atmospheric heat flux means heat leaves the ocean; the ice modules report positive ocean_ice_heat_flux when ice extracts heat from the ocean. See Ice Thermodynamics for the full sign convention description.

Utilities

Shared scalar utilities for ice thermodynamics kernels.

pygotm.icethm._util.freezing_temperature(S)[source]

Return the linear seawater freezing point used by GOTM simple ice.

Return type:

float

Parameters:

S (float)

pygotm.icethm._util.freezing_temperature_winton(S)[source]

Return Winton’s linear seawater freezing point, Tf = -m S.

Return type:

float

Parameters:

S (float)

pygotm.icethm._util.clamp01(value)[source]

Clamp a scalar into the closed unit interval.

Return type:

float

Parameters:

value (float)

pygotm.icethm._util.safe_exp(value)[source]

Exponentiate after clipping to avoid overflow in pathological inputs.

Return type:

float

Parameters:

value (float)

pygotm.icethm._util.require_ice_state(state)[source]

Validate that an IceState has Numba-compatible scalar arrays.

Return type:

None

Parameters:

state (IceState)

Models

Simple

Simple GOTM ice limiter.

The simple model is a boundary-condition limiter rather than a prognostic ice model. It computes the linear freezing point Tf = -0.0575 S and suppresses warming temperature flux into water that is already at or below freezing.

pygotm.icethm.models.simple.step_simple(T_sfc, S_sfc, diff_t_up, Tf_out, Hice_out, ice_cover_out)[source]

Return the modified upward temperature diffusivity boundary flux.

Return type:

float

Parameters:

Lebedev

Lebedev freezing-degree-day ice growth model.

The model follows the empirical relation used by Lebedev (1938) and later lake ice applications: accumulated freezing degree days produce ice thickness Hice = 0.01 * fac * fdd**exp. The surface albedo is fixed and shortwave transmissivity decays exponentially with thickness.

pygotm.icethm.models.lebedev.step_lebedev(T_air, T_w, S_sfc, dt, fdd, Hice, ice_cover, albedo_ice, transmissivity, Tf)[source]

Advance empirical freezing-degree-day ice thickness by one timestep.

Return type:

None

Parameters:

Basal Melt

Ice-shelf basal melt closure translated from STIM stim_basal_melt.F90.

pygotm.icethm.models.basal_melt.basal_freezing_temperature(S_b, H_ice)[source]

Return the pressure-adjusted interface freezing temperature.

Return type:

float

Parameters:
pygotm.icethm.models.basal_melt.step_basal_melt(T_w, S_w, h_sfc, H_ice, ustar, melt_rate, T_melt, S_melt, ocean_ice_heat_flux, ocean_ice_salt_flux, Tf)[source]

Solve one basal-melt interface step for a single water column.

Return type:

None

Parameters:

MyLake

Compact MyLake-style lake-ice thermodynamics.

This implementation translates the STIM MyLake slab-ice routine used by GOTM-Lake. It preserves the same surface and basal growth diagnostics and mutates the surface-water temperature in the same places as the Fortran Tw argument.

pygotm.icethm.models.mylake.step_mylake(T_w, S_sfc, T_air, h_sfc, Qsw, Qh, Qe, Ql, dt, precip, Hice, Hfrazil, dHis, dHib, Tice_surface, ice_cover, albedo_ice, attenuation_ice, transmissivity, Tf, ocean_ice_flux, ocean_ice_heat_flux, ocean_ice_salt_flux, bottom_ice_energy)[source]

Advance a single-column MyLake ice slab and return updated water T.

Return type:

float

Parameters:

Winton

Winton three-layer sea-ice thermodynamics.

This module follows GOTM/STIM’s stim_winton.F90 and winton/ice_thm.F90 implementation. The model uses a zero heat-capacity snow layer over two sea-ice layers; the upper layer has the Winton brine heat-capacity term and the lower layer has fixed heat capacity.

pygotm.icethm.models.winton.ice_optics(hice, hsnow, Ts, albedo_ice, transmissivity)[source]

Update Winton albedo/transmissivity and return penetrating solar fraction.

Return type:

float

Parameters:
pygotm.icethm.models.winton.ice3lay_temp(Tf, dt, A_flux, B_flux, I_absorbed, Hice, Hsnow, T1, T2, Tice_surface, surface_energy, bottom_energy, ocean_ice_heat_flux)[source]

Advance ice temperatures using the GOTM/STIM Winton equations.

Return type:

None

Parameters:
pygotm.icethm.models.winton.ice3lay_resize(Tf, snow, frazil, evap, Hice, Hsnow, T1, T2, surface_energy, bottom_energy, ocean_ice_flux)[source]

Resize snow/ice layers using GOTM/STIM’s ice3lay_resize equations.

Return type:

None

Parameters:
pygotm.icethm.models.winton.step_winton(T_w, S_w, h_sfc, dt, Qsw, Ql, Qh, Qe, precip, surface_flux_a, surface_flux_b, Hice, Hsnow, Hfrazil, T1, T2, Tice_surface, ice_cover, albedo_ice, transmissivity, Tf, ocean_ice_heat_flux, ocean_ice_flux, ocean_ice_salt_flux, surface_ice_energy, bottom_ice_energy)[source]

Advance Winton three-layer ice state by one timestep.

Return type:

None

Parameters: