ethz_snow package

Submodules

ethz_snow.constants module

Calculate derived constants and shortcut definitions.

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

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)[source]

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 “Stochastic shelf-scale modeling framework for the freezing stage in freeze-drying processes”, Deck, Ochsenbein, and Mazzotti (2022), Int J Pharm, 613, 121276, https://doi.org/10.1016/j.ijpharm.2021.121276.

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[source]

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)[source]

Bases: object

A class to handle multiple Stochastic Nucleation of Water simulation.

More information regarding the equations and their derivation can be found in “Stochastic shelf-scale modeling framework for the freezing stage in freeze-drying processes”, Deck, Ochsenbein, and Mazzotti (2022), Int J Pharm, 613, 121276, https://doi.org/10.1016/j.ijpharm.2021.121276 as well as in 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[source]

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[source]

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')[source]

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')[source]

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[source]

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[source]

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(k: dict = {'ext': 20, 'int': 20, 's0': 20, 's_sigma_rel': 0.1}, N_vials: Tuple[int, int, int] = (7, 7, 1), initialStates: Optional[dict] = {'sigma': None, 'temp': None}, storeStates: Optional[Union[str, Sequence[str], Sequence[int]]] = None, solidificationThreshold: float = 0.9, dt: float = 2, seed: int = 2021, opcond: ethz_snow.operatingConditions.OperatingConditions = OperatingConditions([t_tot: 20000.0, Cooling: 20 to -50 with rate 0.01, No Holds, Controlled Nucleation: OFF, configPath: Optional[str] = None, initIce: str = 'indirect')[source]

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 “Stochastic shelf-scale modeling framework for the freezing stage in freeze-drying processes”, Deck, Ochsenbein, and Mazzotti (2022), Int J Pharm, 613, 121276, https://doi.org/10.1016/j.ijpharm.2021.121276.

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.

  • initIce (str, optional) – Which formulation for the initial amount of ice formed to use (see docs). Can be ‘direct’ or ‘indirect’. Defaults to ‘indirect’.

  • 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.).

  • T_k_0 (float) – Initial temperature of vials.

  • 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[source]

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. Can be “corner”, “edge”, “side”, “core”, “all”. 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', 'core'])
array([False, False, False, False])
nucleationTemperatures(group: Union[str, Sequence[str]] = 'all', fromStates: bool = False) numpy.ndarray[source]

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[source]

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)[source]

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()[source]

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[source]

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[source]

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]][source]

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