src.spyice.models.sea_ice_model#

Overview#

The SeaIceModel module implements the full numerical framework for simulating thermodynamic and biogeochemical evolution of sea ice.

It includes:

  • Ice–ocean interface tracking

  • Convergence iteration loops

  • Phase change handling (Stefan problem)

  • Radiation and salinity source terms

  • Algae and biogeochemical coupling

  • Residual tracking and mushy layer diagnostics

  • Results storage and export

Functions#

locate_ice_ocean_interface#

spyice.models.sea_ice_model.locate_ice_ocean_interface(phi, dz, nz, **kwargs)[source]#

Locate ice ocean interface, based on liquid fraction equivalent ice thickness

Parameters:

  • phi (array-like) – Liquid fraction [-]

  • dz (float) – Spatial discretization [m]

  • nz (int) – Number of computational nodes

  • **kwargs – Additional keyword arguments Stefan (bool): Validation with Stefan problem (default: True)

Returns:

A tuple containing:

  • if_depth (float): Location of the ice-water interface/sea ice total thickness [m]

  • if_depth_index (int): Index of the ‘transition cell’ from ice to ocean (freezing) or water to ice (melting)

Return type:

tuple

Classes#

SeaIceModel#

class spyice.models.sea_ice_model.SeaIceModel[source]#

Bases: object

SeaIceModelClass represents a class that models the behavior of sea ice.

Parameters:

  • dataclass (PreprocessData) – The preprocessed data for the model.

  • user_dataclass (UserInput) – The user input data for the model.

__init__(dataclass, user_dataclass)[source]#
Parameters:

  • dataclass (PreprocessData) – The preprocessed data for the model.

  • user_dataclass (UserInput) – The user input data for the model.

bc_neumann(phi_k, nz, bc_condition=None)[source]#

Apply Neumann boundary condition to the sea ice model.

Parameters:

  • phi_k (float) – The value of phi at the k-th layer.

  • nz (int) – The number of layers in the sea ice model.

  • bc_condition (str, optional) – The type of boundary condition to apply. Defaults to None.

Returns:

None

set_boundary_condition_type(critical_depth, bc_type='Neumann')[source]#

Sets the boundary condition type for the model. This method sets the boundary condition type for the model. It calculates the temperature gradient based on the given critical depth and boundary condition type. If the boundary condition type is “Neumann”, the temperature gradient is calculated using the formula: temp_grad = dz * (temperature_melt - boundary_top_temperature) / critical_depth If the boundary condition type is not “Neumann”, the temperature gradient is set to None.

Parameters:

  • critical_depth (float) – The critical depth value.

  • bc_type (str, optional) – The type of boundary condition. Defaults to “Neumann”.

Example

model.set_boundary_condition_type(10.0, “Neumann”)

t_running(fig, ax1, t_stefan, t_k, t_k_buffo=None, count=0)[source]#

Plot the temperature profile against depth.

Parameters:

  • fig (matplotlib.figure.Figure) – The figure object to plot on.

  • ax1 (matplotlib.axes.Axes) – The axes object to plot on.

  • t_stefan (numpy.ndarray) – The temperature profile obtained analytically.

  • t_k (numpy.ndarray) – The temperature profile obtained numerically.

  • t_k_buffo (numpy.ndarray, optional) – The temperature profile obtained using Buffo method. Defaults to None.

  • count (int, optional) – The count value. Defaults to 0.

Returns:

None

track_mush_for_parameter(phi_k_, param, param_iterlist)[source]#

Track the mush for a given parameter.

Parameters:

  • phi_k – numpy array representing the values of phi_k

  • param – numpy array representing the parameter values

  • param_iterlist – list to store the tracked mush values for the parameter

  • parameter (Updated list with the tracked mush values for the)

phi_all_mush_list(phi_k_, phi_all_mush_list)[source]#

Calculates the number of elements in phi_k_ that fall within the mush_lowerbound and mush_upperbound range.

Parameters:

  • phi_k (numpy.ndarray) – The input array containing the values to be checked.

  • phi_all_mush_list (list) – The list to which the count of elements within the range will be appended.

Returns:

The updated phi_all_mush_list with the count of elements within the range appended.

Return type:

list

convergence_loop_iteration(t, t_km1, s_km1, brine_velocity_km1, nutrient_cn_km1, phi_km1, thickness_index, source_term_temperature, source_term_salinity, x_wind_temperature, x_wind_salinity, buffo=False, stefan=False, voller=False, temp_grad=None, salinity_equation=False, diffusiononly_equation=False, algae_equation=False)[source]#

Performs a single iteration of the convergence loop by first resetting the parameters to their previous time step values and then running the convergence loop until convergence is reached. :param t: Current temperature. :type t: float :param t_km1: Temperature at the previous time step. :type t_km1: float :param s_km1: Salinity at the previous time step. :type s_km1: float :param phi_km1: Porosity at the previous time step. :type phi_km1: float :param buffo: Flag indicating whether to use the buffo method. Defaults to False. :type buffo: bool, optional :param stefan: Flag indicating whether to use the Stefan method. Defaults to False. :type stefan: bool, optional :param temp_grad: Temperature gradient. Defaults to None. :type temp_grad: float, optional

Methods called:

  • reset_iteration_parameters: Resets the iteration parameters for the sea ice model with values at previous time steps.

  • run_while_convergence_iteration: Runs the convergence loop until convergence is reached.

Returns:

A tuple containing the following values:

  • t_k (float): Current temperature.

  • t_prev (float): Temperature at the previous time step.

  • s_k (float): Current salinity.

  • s_prev (float): Salinity at the previous time step.

  • phi_k (float): Current porosity.

  • phi_prev (float): Porosity at the previous time step.

  • h_k (float): Current heat flux.

  • h_solid (float): Heat flux at the solid-liquid interface.

  • thickness (float): Current thickness.

  • thickness_index (int): Index of the thickness.

  • t_km1 (float): Temperature at the previous time step.

  • s_km1 (float): Salinity at the previous time step.

  • phi_km1 (float): Porosity at the previous time step.

  • temperature_liquidus (float): Liquidus temperature.

  • temperature_solidus (float): Solidus temperature.

Return type:

tuple

run_while_convergence_iteration(t, t_initial, s_initial, brine_velocity_initial, nutrient_cn_initial, phi_initial, thickness_index, buffo, stefan, voller, t_err, s_err, phi_err, source_term_temperature, source_term_salinity, x_wind_temperature, x_wind_salinity, counter, _is_salinity_equation=False, _is_diffusiononly_equation=False, _is_algae_equation=False)[source]#

Runs the convergence loop until convergence is reached.

Parameters:

  • t – Time step

  • t_km1 – Previous temperature array

  • s_km1 – Previous salinity array

  • phi_km1 – Previous phi array

  • buffo – Flag for Buffo

  • stefan – Flag for Stefan

  • t_err – Temperature error

  • s_err – Salinity errorhatch

  • phi_err – Phi error

  • t_initial – Initial temperature

  • phi_initial – Initial phi

  • source_term – RHS Source term of PDE equation

  • counter – Iteration counter

Methods called:

  • initialise_previous_statevariables: Defines the previous state variables for convergence iteration (temperature,salinity, liquid_fraction).

  • update_state_variables: Update the state variables (Enthalpy, Enthalpy Solid, Liquid Fraction, Temperature, Salinity).

  • locate_ice_ocean_interface: Locate the ice-ocean interface based on the liquid fraction.

  • overwrite_statevariables:

  • track_mush_for_parameter

  • phi_all_mush_list

  • check_convergence: computes error for convergence

Returns:

A tuple containing the following values:

  • t_km1 (float): Temperature at the previous time step.

  • s_km1 (float): Salinity at the previous time step.

  • phi_km1 (float): Liquid fraction at the previous time step.

  • t_prev (float): Temperature at the previous time step.

  • s_prev (float): Salinity at the previous time step.

  • phi_prev (float): Liquid fraction at the previous time step.

  • h_k (float): Current heat flux.

  • h_solid (float): Heat flux at the solid-liquid interface.

  • phi_k (float): Liquid fraction at the current time step.

  • t_k (float): Current temperature.

  • s_k (float): Current salinity.

  • thickness (float): Current thickness.

  • thickness_index (int): Index of the thickness

Return type:

tuple

check_convergence(t, counter, t_prev, s_prev, phi_prev, phi_k, t_k, s_k, t_initial, phi_initial, s_initial, voller=False, **kwargs)[source]#
record_mushy_layer_data(t, t_km1, stefan, phi_k, residual_voller, s_prev)[source]#

Records the mushy layer data for temperature and phi values at time iterations t at specific time steps corresponding to initial stages, middle and final stages of the process.

reset_iteration_parameters(t, tkm1, s_km1, brine_velocity_km1, nutrient_cn_km1, phi_km1, source_term_temperature, source_term_salinity)[source]#

Reset the iteration parameters for the sea ice model.

Parameters:

  • t (float) – Current temperature.

  • tkm1 (float) – Temperature at the previous time step.

  • s_km1 (float) – Salinity at the previous time step.

  • phi_km1 (float) – Liquid fraction at the previous time step.

Returns:

A tuple containing the following iteration parameters:

  • t_km1 (float): Temperature at the previous time step.

  • s_km1 (float): Salinity at the previous time step.

  • phi_km1 (float): Liquid fraction at the previous time step.

  • temp_grad (float): Temperature gradient.

  • t_err (float): Temperature error.

  • s_err (float): Salinity error.

  • phi_err (float): Liquid fraction error.

  • t_initial (float): Initial temperature.

  • s_initial (float): Initial salinity.

  • phi_initial (float): Initial liquid fraction.

  • source_term_array (ndarray): Array of source-term values.

  • counter (int): Iteration counter.

Return type:

tuple

check_and_reset_any_iteration_data(parameter_list, parameter_all_list)[source]#

Check the iteration data for temperature and phi values. This method appends the temperature and phi values from the current iteration to the respective arrays. The arrays are used to store the iteration data for further analysis.

Parameters:

  • parameter_list (list) – The list of parameter values.

  • parameter_all_list (list) – The list of all parameter values.

Returns:

None

Return type:

None

record_iteration_data()[source]#

Records the iteration data for temperature and phi values. This method appends the temperature and phi values from the current iteration to the respective arrays. The arrays are used to store the iteration data for further analysis.

Parameters:

None

Returns:

None

initialize_state_variables(t, t_km1, s_km1, phi_km1)[source]#

Initializes the state variables for the sea ice model.

Parameters:

  • t (int) – The current time step.

  • t_km1 (float) – The temperature at the previous time step.

  • s_km1 (float) – The salinity at the previous time step.

  • phi_km1 (float) – The liquid fraction at the previous time step.

Returns:

A tuple containing the initialized state variables:

  • t_initial (float): The initial temperature.

  • t_km1 (float): The temperature at the previous time step.

  • s_km1 (float): The salinity at the previous time step.

  • phi_initial (float): The initial liquid fraction.

  • phi_km1 (float): The liquid fraction at the previous time step.

  • temp_grad (float): The temperature gradient.

Return type:

tuple

choose_phase_type_iteration(t)[source]#

Choose the phase type iteration based on the one-phase and two-phase generalised Stefan Probem.

Parameters:

t (int) – The time index.

Returns:

A tuple containing the following values:

  • t_stefan (float): The Stefan temperature.

  • error_depth_t (float): The error in depth.

  • depth_stefan_t (float): The depth at time t.

Return type:

tuple

Raises:

InvalidPhaseError – If the phase type is invalid (not 1 or 2).

run_sea_ice_model()[source]#

Runs the sea ice model.

This function iterates over a specified number of time steps and performs calculations to simulate the behavior of sea ice. It updates the results and saves a temperature profile plot at the end.

Parameters:

None

Returns:

None

calculate_source_terms(carbon_cc, thickness_index, t, t_k, s_k, nutrient_cn_k, phi_k, thickness, salinity_equation=False, algae_equation=False, radiation_equation=False, **kwargs)[source]#
add_new_parameter_results()[source]#
Return type:

None

classmethod get_results(dataclass, user_dataclass)[source]#

Runs the sea ice model and returns the results.

Parameters:

  • cls (class) – The class object.

  • dataclass (PreprocessData) – The dataclass containing preprocessed data.

  • user_dataclass (UserInput) – The dataclass containing user input.

Returns:

The results dataclass object generated by running the sea ice model.

Return type:

Results

set_dataclass(_dataclass)[source]#

Sets the dataclass attributes of the object.

Parameters:

_dataclass – An instance of the dataclass.

Returns:

None

Main Methods#

The most important high-level methods are:

run_sea_ice_model()

Executes the full time-stepping simulation.

convergence_loop_iteration()

Performs a full nonlinear convergence iteration for a given timestep.

run_while_convergence_iteration()

Core iterative solver loop until tolerance is met.

calculate_source_terms()

Computes radiation, salinity, and algae-related source terms.

choose_phase_type_iteration()

Selects between one-phase and two-phase Stefan problem.

get_results()

Class method to run the model and return a ResultsParams object.

Dependencies#

This module relies on:

  • spyice.models.algae_model

  • spyice.models.radiative_model

  • spyice.models.stefan_problem

  • spyice.statevariables

  • spyice.update_physical_values

  • spyice.utils.helpers

Notes#

  • Convergence is controlled by user-defined tolerances.

  • A ConvergenceError is raised if iteration exceeds the counter limit.

  • An InvalidPhaseError is raised if an unsupported Stefan phase type is selected.

  • Mushy layer diagnostics are recorded during Stefan validation runs.

  • Results are stored incrementally at each timestep.

SeaIceModel.get_results(...) is the recommended entry point for external use.