swiift ====== .. py:module:: swiift .. autoapi-nested-parse:: SWIIFT: Surface Waves Impact on sea Ice---Fracture Toolkit. Subpackages =========== There are three subpackages that need to be explicitly imported: :: api model lib Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/swiift/api/index /autoapi/swiift/lib/index /autoapi/swiift/model/index Classes ------- .. autoapisummary:: swiift.Experiment swiift.DiscreteSpectrum swiift.Floe swiift.Ice swiift.Ocean Functions --------- .. autoapisummary:: swiift.load_pickle swiift.load_pickles Package Contents ---------------- .. py:class:: Experiment Container holding geometry, fracture mechanism, and history. :param time: Time at start of experiment, in s. :type time: float :param domain: Domain instance supporting the experiment. :type domain: swiift.model.model.Domain :param history: History of the experiment. Keys correspond to time, values to geometry. :type history: dict[float, Step], optional :param fracture_handler: :type fracture_handler: swiift.model.fracture_handler._FractureHandler, :param default fh.BinaryFracture: Instance of a concrete class derived from _FractureHandler, that describes the fracture mechanism used for the experiment. .. attribute:: time Time from the beginning of the experiment, in s. :type: float .. attribute:: domain Domain instance supporting the experiment. :type: swiift.model.model.Domain .. attribute:: history History of the experiment. Keys correspond to time, values to geometry. :type: dict[float, Step] .. attribute:: fracture_handler Instance of a concrete class derived from _FractureHandler, that describes the fracture mechanism used for the experiment. :type: fh._FractureHandler .. py:method:: create(gravity, spectrum, ocean, growth_params = None, fracture_handler = None, attenuation_spec = None) :classmethod: Build an Experiment from existing spectrum and ocean. :param gravity: Acceleration of gravity, in m s^-2. :type gravity: float :param spectrum: DiscreteSpectrum object holding information on wave forcing. :type spectrum: DiscreteSpectrum :param ocean: Ocean object holding information on bearing fluid. :type ocean: Ocean :param growth_params: 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. :type growth_params: tuple, optional :param fracture_handler: Instance of a concrete class derived from _FractureHandler, describing the fracture mechanism used for the experiment. Defaults to binary fracture from energy criterion. :type fracture_handler: fh._FractureHandler, optional :param attenuation_spec: Attenuation parametrisation or specification. Defaults to PARAM_01. :type attenuation_spec: att.Attenuation, optional :rtype: Experiment .. seealso:: :mod:`swiift.model.fracture_handler` For details on how to specify the fracture handler. :mod:`swiift.lib.att` For details on how to specify attenuation. .. rubric:: Notes .. version-added:: next .. py:property:: timesteps :type: 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. :rtype: np.ndarray .. py:method:: add_floes(floes) Add floes to the domain. :param floes: 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. :type floes: md.Floe | Sequence[md.Floe] .. warning:: This method triggers writing to the history. This may lead to the loss of the history for the current timestep. .. py:method:: 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. :rtype: np.ndarray .. seealso:: :attr:`timesteps` .. py:method:: 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. :rtype: np.ndarray .. seealso:: :attr:`timesteps` .. py:method:: get_final_state() Return the final state of the experiment. :returns: The step corresponding to the last timestep. :rtype: Step .. py:method:: 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. :param delta_time: The time increment, in s. :type delta_time: float :param an_sol: 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. :type an_sol: bool, optional :param num_params: Optional parameters to pass to the numerical solver, if applicable. :type num_params: dict, optional .. py:method:: 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. :param times: Time, or sequence of times, in s. :type times: float | Sequence[float] :returns: A dictionary containing the closest steps to the input times. :rtype: dict[float, Step] .. seealso:: :meth:`get_states_strict` .. py:method:: get_states_strict(times) Return a subset of the history matching the given times. :param times: Time, or sequence of times, in s. :type times: float | Sequence[float] :returns: A dictionary containing the steps matching exactly the input times. :rtype: dict[float, Step] .. seealso:: :meth:`get_states` .. py:method:: 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. :param prefix: Prefix for the file name. Defaults to the ``id`` of the instance. :type prefix: str, optional :param dir_path: Directory where to store the history. Defaults to the current working directory. :type dir_path: str | pathlib.Path, optional .. py:method:: 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. :param time: Duration to run the experiment for, in s. :type time: float :param delta_time: Time step between iterations, in s. :type delta_time: float :param break_time: Time before stopping the experiment if no fracture occurs, in s. :type break_time: float, optional :param chunk_size: Number of steps before writing the results to a file. :type chunk_size: int, optional :param verbose: Verbosity level. If 1: Outputs for disk writes. If 2: Additional outputs for fractures. :type verbose: int, optional :param pbar: Progress bar monitoring the experiment. :type pbar: progress bar, optional :param path: Directory where files will be saved. Defaults to the current working directory. :type path: str | pathlib.Path, optional :param dump_final: Whether the results should be saved to disk at the end of the run by calling :meth:`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. :type dump_final: bool, optional :param dump_prefix: Prefix for the file names when saving chunks. Defaults to the ``id`` of the ``Experiment`` instance. :type dump_prefix: str, optional .. py:method:: from_discrete(gravity, spectrum, ocean, growth_params = None, fracture_handler = None, attenuation_spec = None) Build an Experiment from existing spectrum and ocean. :param gravity: Acceleration of gravity, in m s^-2. :type gravity: float :param spectrum: DiscreteSpectrum object holding wave forcing information. :type spectrum: md.DiscreteSpectrum :param ocean: Ocean object holding bearing fluid information. :type ocean: md.Ocean :param growth_params: 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. :type growth_params: tuple, optional :param fracture_handler: Instance of a concrete class derived from _FractureHandler, describing the fracture mechanism used for the experiment. Defaults to binary fracture from energy criterion. :type fracture_handler: fh._FractureHandler, optional :param attenuation_spec: Attenuation parametrisation or specification. Defaults to PARAM_01. :type attenuation_spec: att.Attenuation, optional :rtype: Experiment .. seealso:: :mod:`swiift.model.fracture_handler` For details on how to specify the fracture handler. :mod:`swiift.lib.att` For details on how to specify attenuation. .. rubric:: Notes .. version-deprecated:: next Use :meth:`create` instead. .. py:function:: load_pickle(fname) Load a pickle and return an :class:`Experiment`. :param fname: A file name or path object. :type fname: str | pathlib.Path :rtype: Experiment :raises FileNotFoundError: If no file matching ``fname`` can be found. .. py:function:: load_pickles(pattern, dir_path = None, recursive = False, **kwargs) Load pickles and assemble them into a single :class:`Experiment`. This function relies on :class:`pathlib.Path` :meth:`~pathlib.Path.glob` and :meth:`~pathlib.Path.rglob` methods. Files found matching the provided pattern are assembled into a single :class:`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. :param pattern: A pattern to glob upon. :type pattern: str :param dir_path: The directory in which files will be looked for. Defaults to the current working directory. :type dir_path: str | pathlib.Path, optional :param recursive: Whether to search for the pattern recursively from ``dir_path``. :type recursive: bool :param \*\*kwargs: Arguments passed to ``pathlib.Path.[r]glob``. :rtype: Experiment :raises FileNotFoundError: If no file matches the pattern. :raises ValueError: If a found file does not correspond to an instance of :class:`Experiment`. .. py:class:: DiscreteSpectrum(amplitudes, frequencies, phases = 0) Container for a discretised spectrum. This class allows for building a forcing from the linear superposition of harmonic waves. .. attribute:: amplitudes A 1D array of amplitudes, in m. :type: np.ndarray .. attribute:: frequencies A 1D array of frequencies, in Hz. :type: np.ndarray .. attribute:: phases A 1D array of phases, in rad. :type: np.ndarray .. py:class:: Floe Bases: :py:obj:`_Subdomain` An ice floe localised in space. :param ice: The mechanical properties of the floe :type ice: Ice .. py:class:: 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. :param density: Density, in kg m^-3. :type density: float :param frac_toughness: Fracture toughness, in Pa m^(1/2). :type frac_toughness: float :param poissons_ratio: Poisson's ratio. :type poissons_ratio: float :param strain_threshold: Critical flexural strain, in m m^-1. :type strain_threshold: float :param thickness: Ice thickness, in m. :type thickness: float :param youngs_modulus: Scalar Young's modulus, in Pa. :type youngs_modulus: float .. attribute:: quad_moment Quadratic moment of area, in m^3. :type: float .. attribute:: flex_rigidity Flexural rigidity in, N m. :type: float .. attribute:: frac_energy_rate Fracture energy release rate, in J m^-2. :type: float .. py:class:: Ocean The fluid bearing ice floes. This class encapsulates the properties of an incompressible ocean of constant depth and given density. :param depth: Ocean depth, in m. :type depth: float :param density: Ocean density, in kg m^-3. :type density: float