ethz_snow package — ethz_snow 1.0.0 documentation

# ethz_snow package

## Submodules

## ethz_snow.constants module

Calculate derived constants and shortcut definitions.

ethz_snow.constants.calculateDerived(fpath: Optional[str] = None) → dict

  Compute the constants needed for Snowflake. Derive where needed.

  Parameters

    fpath (Optional[str], optional) – The filepath of the custom config file. Defaults to None.

  Raises

    NotImplementedError – Vial geometry is not cubic.

  Returns

    A dictionary of constants.

  Return type

    dict

## ethz_snow.operatingConditions module

Implement OperatingConditions class.

This module contains the OperatingConditions class used to store information regarding the operating conditions in freezing processes.

class ethz_snow.operatingConditions.OperatingConditions(t_tot: float = 20000.0, cooling: dict = {'end': - 50, 'rate': 0.008333333333333333, 'start': 20}, holding: Optional[Union[Iterable[dict], dict]] = None, cnTemp: Optional[Union[float, int]] = None)

  Bases: `object`

  A class to handle a single Stochastic Nucleation of Water simulation.

  More information regarding the equations and their derivation can be found in XXX, Deck et al. (2021).

  Parameters

    - cnt (float) – Controlled nucleation time.

    - controlledNucleation (bool) – Controlled nucleation on/off.

    - cooling (dict) – A dictionary describing the cooling profile.

    - holding (dict) – A dictionary describing the holding step.

    - t_tot (float) – The total process time.

  property cnt: float

    Return the time when controlled nucleation should trigger.

    Raises

      NotImplementedError – If holding is not defined don’t know how to calculate cnt.

    Returns

      The time of controlled nucleation

        (inf if no controlled nucleation applied).

    Return type

      float

  property holding: Iterable[dict]

    Get holding property.

  tempProfile(dt: float) → numpy.ndarray

    Return temperature profile.

    Compute temperature profile with or without holding step. :param dt: The time step size. :type dt: float

    Returns

      The temperature profile.

    Return type

      np.ndarray

## ethz_snow.snowfall module

Implement Snowfall class.

This module contains the Snowfall class used to run repeated (!) simulations of water nucleation in vials. It makes use of class Snowflake for the individual simulations.

class ethz_snow.snowfall.Snowfall(Nrep: int = 5, pool_size: Optional[int] = None, **kwargs)

  Bases: `object`

  A class to handle multiple Stochastic Nucleation of Water simulation.

  More information regarding the equations and their derivation can be found in XXX, Deck et al. (2021) as well as the Snowflake class documentation.

  Parameters

    - Nrep (int) – Number of repetitions.

    - pool_size (int) – Size of worker pool for parallelization.

    - stats (dict) – Statistics for each simulation.

    - stats_df (pd.DataFrame) – Long-form table of all statistics.

    - simulationStatus (int) – Status of simulation (0 = not run, 1 = run).

  nucleationTemperatures(group: Union[str, Sequence[str]] = 'all', seed: Optional[Union[int, Sequence[int]]] = None) → numpy.ndarray

    Return nucleation temperatures.

    Parameters

      - group (Union[str, Sequence[str]], optional) – Subgroup to return. Defaults to “all”.

      - seed (Union[int, Sequence[int], None], optional) – Seed(s) to return. Defaults to None.

    Returns

      The nucleation temperatures.

    Return type

      np.ndarray

  nucleationTimes(group: Union[str, Sequence[str]] = 'all', seed: Optional[Union[int, Sequence[int]]] = None) → numpy.ndarray

    Return nucleation times.

    Parameters

      - group (Union[str, Sequence[str]], optional) – Subgroup to return. Defaults to “all”.

      - seed (Union[int, Sequence[int], None], optional) – Seed(s) to return. Defaults to None.

    Returns

      The nucleation times.

    Return type

      np.ndarray

  plot(what: str = 't_nucleation', kind: str = 'box', seed: Optional[Union[int, Sequence[int]]] = None, group: Union[str, Sequence[str]] = 'all')

    Create plots for Snowfall object.

    Parameters

      - kind (str, optional) – Any sns.catplot ‘kind’ input is allowed. Defaults to “box”.

      - what (str, optional) – What to plot, i.e., keys of the stats dict. Valid options are t_nucleation, T_nucleation, t_solidification. Defaults to “t_nucleation”.

      - seed (Union[int, Sequence[int], None], optional) – Seed(s) to return. Defaults to None.

      - group (Union[str, Sequence[str]], optional) – Subgroup to return. Defaults to “all”.

  run(how='async')

    Run all the Snowflake simulations.

    Parameters

      how (str, optional) – How to perform runs. Valid options are ‘async’, ‘sync’, and ‘sequential’ (no parallelization). Defaults to “async”.

  property simulationStatus: int

    Return simulation status of instance.

    Returns

      Simulation status. 0 = not run, 1 = run.

    Return type

      int

  solidificationTimes(group: Union[str, Sequence[str]] = 'all', seed: Optional[Union[int, Sequence[int]]] = None) → numpy.ndarray

    Return solidification times.

    Parameters

      - group (Union[str, Sequence[str]], optional) – Subgroup to return. Defaults to “all”.

      - seed (Union[int, Sequence[int], None], optional) – Seed(s) to return. Defaults to None.

    Returns

      The solidification times.

    Return type

      np.ndarray

  to_frame() → pandas.core.frame.DataFrame

    Save statistics as pandas dataframe.

    Raises

      ValueError – Simulation needs to run first.

    Returns

      The statistics in long form.

    Return type

      pd.DataFrame

## ethz_snow.snowflake module

Implement Snowflake class.

This module contains the Snowflake class used to run simulations of water nucleation in vials.

class ethz_snow.snowflake.Snowflake

  Bases: `object`

  A class to handle a single Stochastic Nucleation of Water simulation.

  More information regarding the equations and their derivation can be found in XXX, Deck et al. (2021).

  Parameters

    - configPath (Optional[str]) – The path of the (optional) custom config yaml.

    - const (dict) – A dictionary of constants to be used.

    - dt (float) – Time step.

    - H_ext (np.ndarray) – External heat transfer vector.

    - H_int (csr_matrix) – Internal heat transfer matrix.

    - H_shelf (np.ndarray) – Shelf heat transfer vector.

    - k (dict) – Heat transfer coefficients.

    - N_vials (tuple) – Number of vials in each dimension.

    - N_vials_total (int) – Total number of vials.

    - opcond (OperatingConditions) – Operating conditions of run.

    - seed (int) – Seed to be used in rng.

    - simulationStatus (int) – Status of simulation (0 = not run, 1 = run).

    - solidificationThreshold (float) – What sigma value constitutes a ‘solid’.

    - stats (dict) – Run statistics (nucleation time, etc.).

    - X_sigma (np.ndarray) – Sigma state over time.

    - X_T (np.ndarray) – Temperature state over time.

  property H_ext: numpy.ndarray

    Return the external heat transfer vector.

    Returns

      The external heat transfer vector.

    Return type

      np.ndarray

  property H_int: scipy.sparse.csr.csr_matrix

    Return the internal heat transfer matrix.

    Returns

      The internal heat transfer matrix.

    Return type

      csr_matrix

  property H_shelf: numpy.ndarray

    Return the shelf heat transfer vector.

    Returns

      The shelf heat transfer vector.

    Return type

      np.ndarray

  property N_vials_total: int

    Return total number of vials in system.

  property X_T: numpy.ndarray

    Get the temperature states.

    Returns

      An array containing the vial temperatures over time.

        This is just a slice of _X!

    Return type

      np.ndarray

  property X_sigma: numpy.ndarray

    Get the sigma states.

    Returns

      An array containing the vial sigmas over time.

        This is just a slice of _X!

    Return type

      np.ndarray

  property configPath: Optional[str]

    Get configPath property.

  getVialGroup(group: Union[str, Sequence[str]] = 'all') → numpy.ndarray

    Return mask for given group.

    mask[i] = True iff vial[i] is in G where G can be a list of groups.

    Parameters

      group (Union[str, Sequence[str]], optional) – Subgroup to return. Defaults to “all”.

    Raises

      ValueError – Group is not known.

    Returns

      A boolean mask of size (N_vials_tot,).

    Return type

      np.ndarray

    Examples

        >>> S = Snowflake(N_vials = (2, 2, 1))
        >>> S.getVialGroup('corner')
        array([True, True, True, True])

        >>> S.getVialGroup(['edge', 'center'])
        array([False, False, False, False])

  nucleationTemperatures(group: Union[str, Sequence[str]] = 'all', fromStates: bool = False) → numpy.ndarray

    Return array of nucleation temperatures.

    Parameters

      - group (Union[str, Sequence[str]], optional) – Subgroup to return. Defaults to “all”.

      - fromStates (bool, optional) – Whether or not to calculate from states directly. Defaults to False.

    Returns

      The nucleation temperatures.

    Return type

      np.ndarray

  nucleationTimes(group: Union[str, Sequence[str]] = 'all', fromStates: bool = False) → numpy.ndarray

    Return array of nucleation times.

    Parameters

      - group (Union[str, Sequence[str]], optional) – Subgroup to return. Defaults to “all”.

      - fromStates (bool, optional) – Whether or not to calculate from states directly. Defaults to False.

    Returns

      The nucleation times.

    Return type

      np.ndarray

  plot(kind: str = 'box', what: str = 't_nucleation', group: Union[str, Sequence[str]] = 'all', context: bool = True)

    Create plots for Snowflake object.

    Parameters

      - kind (str, optional) – Type of plot to print. If input is ‘trajectories’ will print temperature or sigma profile. Otherwise will print from stats dict. In that case, any sns.catplot ‘kind’ input is allowed. Defaults to “box”.

      - what (str, optional) – What to plot. For trajectories valid inputs are sigma or temperature. Otherwise, it’s the keys of the stats dict. I.e., t_nucleation, T_nucleation, t_solidification. Defaults to “temperature”.

      - group (Union[str, Sequence[str]], optional) – Subgroup to return. Defaults to “all”.

      - context (bool, optional) – Whether or not to print additional context in the figure. Mainly used to add shelf temperature.

  run()

    Run the simulation.

  property seed: int

    Get or set the random seed.

    Setting the seed value will initialize a new rng under the hood.

    Returns

      The seed of the Snowflake.

    Return type

      int

  sigmaCounter(time: Union[Sequence[float], float], threshold: Optional[float] = None, fromStates: bool = False) → numpy.ndarray

    Return counter of vials satisfying sigma>threshold at time.

    Parameters

      - time (Union[Sequence[float], float]) – The time(s) for which to return the counter.

      - threshold (Optional[float], optional) – The threshold to apply. Defaults to self.solidificationThreshold.

      - fromStates (bool, optional) – Whether or not to calculate from states directly. Defaults to False.

    Raises

      - ValueError – Simulation needs to be run first.

      - ValueError – fromStates is False and threshold is neither 0 or self.solidificationThreshold.

    Returns

      [description]

    Return type

      np.ndarray

  property simulationStatus: int

    Return simulation status of instance.

    Returns

      Simulation status. 0 = not run, 1 = run.

    Return type

      int

  solidificationTimes(group: Union[str, Sequence[str]] = 'all', threshold: Optional[float] = None, fromStates: bool = False) → numpy.ndarray

    Return array of solidification times.

    Parameters

      - group (Union[str, Sequence[str]], optional) – Subgroup to return. Defaults to “all”.

      - threshold (Optional[float], optional) – The threshold used to define ‘solidified’. Defaults to self.solidificationThreshold.

      - fromStates (bool, optional) – Whether or not to calculate from states directly. Defaults to False.

    Returns

      The solidification times.

    Return type

      np.ndarray

  to_frame(n_timeSteps: int = 250) → Tuple[pandas.core.frame.DataFrame, Optional[pandas.core.frame.DataFrame]]

    Save statistics (and states) as pandas dataframe.

    Parameters

      n_timeSteps (int, optional) – For states a reduced representation is stored. This defines the number of subsamples. Defaults to 250.

    Raises

      ValueError – Simulation needs to run first.

    Returns

      The statistics and if available

        the states over time (both in long form).

    Return type

      Tuple[pd.DataFrame, Optional[pd.DataFrame]]

## Module contents