swiift

SWIIFT: Surface Waves Impact on sea Ice—Fracture Toolkit.

Subpackages

There are three subpackages that need to be explicitly imported:

api
model
lib

Submodules

Classes

Experiment

Container holding geometry, fracture mechanism, and history.

DiscreteSpectrum

Container for a discretised spectrum.

Floe

An ice floe localised in space.

Ice

A container for ice mechanical properties.

Ocean

The fluid bearing ice floes.

Functions

load_pickle(fname)

Load a pickle and return an Experiment.

load_pickles(pattern[, dir_path, recursive])

Load pickles and assemble them into a single Experiment.

Package Contents

class swiift.Experiment

Container holding geometry, fracture mechanism, and history.

Parameters:

  • time (float) – Time at start of experiment, in s.

  • domain (swiift.model.model.Domain) – Domain instance supporting the experiment.

  • history (dict[float, Step], optional) – History of the experiment. Keys correspond to time, values to geometry.

  • fracture_handler (swiift.model.fracture_handler._FractureHandler,)

  • fh.BinaryFracture (default) – Instance of a concrete class derived from _FractureHandler, that describes the fracture mechanism used for the experiment.

time

Time from the beginning of the experiment, in s.

Type:

float

domain

Domain instance supporting the experiment.

Type:

swiift.model.model.Domain

history

History of the experiment. Keys correspond to time, values to geometry.

Type:

dict[float, Step]

fracture_handler

Instance of a concrete class derived from _FractureHandler, that describes the fracture mechanism used for the experiment.

Type:

fh._FractureHandler

classmethod create(gravity, spectrum, ocean, growth_params=None, fracture_handler=None, attenuation_spec=None)

Build an Experiment from existing spectrum and ocean.

Parameters:

  • gravity (float) – Acceleration of gravity, in m s^-2.

  • spectrum (DiscreteSpectrum) – DiscreteSpectrum object holding information on wave forcing.

  • ocean (Ocean) – Ocean object holding information on bearing fluid.

  • growth_params (tuple, optional) – Parameters parametrising wave growth, that is transition from fluid at rest to developed wave, at the beginning of the experiment. If None, the forcing is considered fully developed accross the domain.

  • fracture_handler (fh._FractureHandler, optional) – Instance of a concrete class derived from _FractureHandler, describing the fracture mechanism used for the experiment. Defaults to binary fracture from energy criterion.

  • attenuation_spec (att.Attenuation, optional) – Attenuation parametrisation or specification. Defaults to PARAM_01.

Return type:

Experiment

See also

swiift.model.fracture_handler

For details on how to specify the fracture handler.

swiift.lib.att

For details on how to specify attenuation.

Notes

Added in version next.

property timesteps: numpy.ndarray

The experiment timesteps.

These can be used to index self.history. This method only returns the keys to the current history, not timesteps that might have been dumped previously.

Returns:

1D array containing the existing timesteps, in s.

Return type:

np.ndarray

add_floes(floes)

Add floes to the domain.

Parameters:

floes (md.Floe | Sequence[md.Floe]) – Floe, or sequence of floes to be added to the domain. The domain may already contain floes: the new floes must not overlap with those.

Warning

This method triggers writing to the history. This may lead to the loss of the history for the current timestep.

get_pre_fracture_times()

Timesteps corresponding to states immediately before fracture.

These can be used to index self.history.

Returns:

1D array of existing timesteps, in s.

Return type:

np.ndarray

See also

timesteps

get_post_fracture_times()

Timesteps corresponding to states immediately after fracture.

These can be used to index self.history. Note: in these states, the waves have been advected, compared to the corresponding pre-fracture states.

Returns:

1D array of existing timesteps, in s.

Return type:

np.ndarray

See also

timesteps

get_final_state()

Return the final state of the experiment.

Returns:

The step corresponding to the last timestep.

Return type:

Step

step(delta_time, an_sol=None, num_params=None)

Move the experiment forward in time.

One step is a succession of events. First, the current floes are scanned for fractures. The domain is then updated with the newly formed fragments, replacing the fractured floes. Then, the actual time progression happens, by advecting the wave (thus updating the wave phases at the edge of every individual floe). Finally, this new state is saved to the history, at the index corresponding to the updated time.

Parameters:

  • delta_time (float) – The time increment, in s.

  • an_sol (bool, optional) – Whether to force the use of a numerical or analytical solution for the deflection of the floes. When not provided, analytical solutions are used when waves are fully developed, numerical solutions are used otherwise.

  • num_params (dict, optional) – Optional parameters to pass to the numerical solver, if applicable.

get_states(times)

Return a subset of the history matching the given times.

If the provided times are not found, their closest matches are returned instead.

Parameters:

times (float | Sequence[float]) – Time, or sequence of times, in s.

Returns:

A dictionary containing the closest steps to the input times.

Return type:

dict[float, Step]

See also

get_states_strict()

get_states_strict(times)

Return a subset of the history matching the given times.

Parameters:

times (float | Sequence[float]) – Time, or sequence of times, in s.

Returns:

A dictionary containing the steps matching exactly the input times.

Return type:

dict[float, Step]

See also

get_states()

dump_history(prefix=None, dir_path=None)

Write the results to disk and clear the history.

The whole object is pickled, before emptying the current history from memory. The filename is constructed with the prefix passed as argument, the package version number, and the time interval covered by the history.

Parameters:

  • prefix (str, optional) – Prefix for the file name. Defaults to the id of the instance.

  • dir_path (str | pathlib.Path, optional) – Directory where to store the history. Defaults to the current working directory.

run(time: float, delta_time: float, break_time: float | None = ..., chunk_size: int | None = ..., verbose: None = ..., pbar: _ProgressBarProtocol | None = ..., path: str | pathlib.Path | None = ..., dump_final: bool = ..., dump_prefix: str | None = ...)
run(time: float, delta_time: float, break_time: float | None = ..., chunk_size: int | None = ..., verbose: int = ..., pbar: _VerboseProgressBarProtocol | None = ..., path: str | pathlib.Path | None = ..., dump_final: bool = ..., dump_prefix: str | None = ...)

Run the experiment for a specified duration.

The experiment is run from its current time for a duration corresponding to time, with states regularly spaced with step delta_time. If time is not an integer multiple of delta_time, the number of steps will be rounded up. The experiment can optionally be stopped before time, if no fracture happens for break_time, and at least one fracture has occured.

The current object can be saved at regularly spaced step intervals, as specified by chunk_size.

Optional messages can be printed to stdout, with a verbosity level controlled by verbose.

A progress bar can be passed as an optional parameter to monitor the experiment. The implementation expect an objects that behaves as a tqdm bar; in particular, it needs to expose update and close method. If used conjonctly with verbose, it also needs to expose a write method.

Parameters:

  • time (float) – Duration to run the experiment for, in s.

  • delta_time (float) – Time step between iterations, in s.

  • break_time (float, optional) – Time before stopping the experiment if no fracture occurs, in s.

  • chunk_size (int, optional) – Number of steps before writing the results to a file.

  • verbose (int, optional) –

    Verbosity level.

    If 1:

    Outputs for disk writes.

    If 2:

    Additional outputs for fractures.

  • pbar (progress bar, optional) – Progress bar monitoring the experiment.

  • path (str | pathlib.Path, optional) – Directory where files will be saved. Defaults to the current working directory.

  • dump_final (bool, optional) – Whether the results should be saved to disk at the end of the run by calling dump_history(), thus clearing the history from memory. If False, at the end of the run, the instance maintains its history which is thus not saved.

  • dump_prefix (str, optional) – Prefix for the file names when saving chunks. Defaults to the id of the Experiment instance.

from_discrete(gravity, spectrum, ocean, growth_params=None, fracture_handler=None, attenuation_spec=None)

Build an Experiment from existing spectrum and ocean.

Parameters:

  • gravity (float) – Acceleration of gravity, in m s^-2.

  • spectrum (md.DiscreteSpectrum) – DiscreteSpectrum object holding wave forcing information.

  • ocean (md.Ocean) – Ocean object holding bearing fluid information.

  • growth_params (tuple, optional) – Parameters parametrising wave growth, that is transition from fluid at rest to developed wave, at the beginning of the experiment. If None, the forcing is considered fully developed accross the domain.

  • fracture_handler (fh._FractureHandler, optional) – Instance of a concrete class derived from _FractureHandler, describing the fracture mechanism used for the experiment. Defaults to binary fracture from energy criterion.

  • attenuation_spec (att.Attenuation, optional) – Attenuation parametrisation or specification. Defaults to PARAM_01.

Return type:

Experiment

See also

swiift.model.fracture_handler

For details on how to specify the fracture handler.

swiift.lib.att

For details on how to specify attenuation.

Notes

Deprecated since version next: Use create() instead.

swiift.load_pickle(fname)

Load a pickle and return an Experiment.

Parameters:

fname (str | pathlib.Path) – A file name or path object.

Return type:

Experiment

Raises:

FileNotFoundError – If no file matching fname can be found.

swiift.load_pickles(pattern, dir_path=None, recursive=False, **kwargs)

Load pickles and assemble them into a single Experiment.

This function relies on pathlib.Path glob() and rglob() methods. Files found matching the provided pattern are assembled into a single Experiment object; histories are thus concatenated, which implies that duplicated keys (timestep entries) are lost. This function is therefore intended to be used on files that the user knows have no overlap between their time axes.

Parameters:

  • pattern (str) – A pattern to glob upon.

  • dir_path (str | pathlib.Path, optional) – The directory in which files will be looked for. Defaults to the current working directory.

  • recursive (bool) – Whether to search for the pattern recursively from dir_path.

  • **kwargs – Arguments passed to pathlib.Path.[r]glob.

Return type:

Experiment

Raises:
class swiift.DiscreteSpectrum(amplitudes, frequencies, phases=0)

Container for a discretised spectrum.

This class allows for building a forcing from the linear superposition of harmonic waves.

amplitudes

A 1D array of amplitudes, in m.

Type:

np.ndarray

frequencies

A 1D array of frequencies, in Hz.

Type:

np.ndarray

phases

A 1D array of phases, in rad.

Type:

np.ndarray

class swiift.Floe

Bases: _Subdomain

An ice floe localised in space.

Parameters:

ice (Ice) – The mechanical properties of the floe

class swiift.Ice

A container for ice mechanical properties.

Ice is modelled as an elastic thin plate, with prescribed density, thickness, Poisson’s ratio and Young’s modulus. Its fracture under bending is considered either through the lens of Griffith’s fracture mechanics, or through the framework of strain failure commonly used in the sea ice modelling community. The fracture toughness is relevant to the former, while the strain threshold is relevant to the latter. Ice is considered translationally invariant in one horizontal direction, so that its quadratic moment of area is given per unit length in that direction.

Parameters:

  • density (float) – Density, in kg m^-3.

  • frac_toughness (float) – Fracture toughness, in Pa m^(1/2).

  • poissons_ratio (float) – Poisson’s ratio.

  • strain_threshold (float) – Critical flexural strain, in m m^-1.

  • thickness (float) – Ice thickness, in m.

  • youngs_modulus (float) – Scalar Young’s modulus, in Pa.

quad_moment

Quadratic moment of area, in m^3.

Type:

float

flex_rigidity

Flexural rigidity in, N m.

Type:

float

frac_energy_rate

Fracture energy release rate, in J m^-2.

Type:

float

class swiift.Ocean

The fluid bearing ice floes.

This class encapsulates the properties of an incompressible ocean of constant depth and given density.

Parameters:

  • depth (float) – Ocean depth, in m.

  • density (float) – Ocean density, in kg m^-3.