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, T1, T2, Tice_surface, fdd, ice_cover, Tf, albedo_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 the surface temperature flux.

Return type:

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, T1, T2, Tice_surface, fdd, ice_cover, Tf, albedo_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
T1: ndarray
T2: ndarray
Tice_surface: ndarray
fdd: ndarray
ice_cover: ndarray
Tf: ndarray
albedo_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 follows the MyLake family of slab-ice ideas used by Saloranta and Andersen (2007): supercooling first creates frazil ice, frazil consolidates into solid ice, conductive Stefan growth acts through the ice slab, and positive surface or basal energy melts existing ice. The kernel exposes the same state variables as the other pyGOTM ice models for shared diagnostics.

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

Advance a single-column MyLake-style ice slab by one timestep.

Return type:

None

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: