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: 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) → 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: 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) → 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) → 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) → 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() → 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: ~typing.Tuple[int, int, int] = (7, 7, 1), initialStates: ~typing.Optional[dict] = {'sigma': None, 'temp': None}, storeStates: ~typing.Optional[~typing.Union[str, ~typing.Sequence[str], ~typing.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: ~typing.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: ndarray

Return the external heat transfer vector.

Returns

The external heat transfer vector.

Return type

np.ndarray

property H_int: csr_matrix

Return the internal heat transfer matrix.

Returns

The internal heat transfer matrix.

Return type

csr_matrix

property H_shelf: 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: 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: 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') → 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) → 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) → 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) → 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) → 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[DataFrame, Optional[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]]

ethz_snow.snowing module

Implementation of the SNOWing class.

This module contains the SNOWing class used to run the single vial simulation with spatial information.

class ethz_snow.snowing.Snowing(k: dict = {'ext': 0, 'int': 0, 's0': 50, 's_sigma_rel': 0}, opcond: ~ethz_snow.operatingConditions.OperatingConditions = OperatingConditions([t_tot: 20000.0, Cooling: 20 to -50 with rate 0.01, No Holds, Controlled Nucleation: OFF, Nrep: int = 1, configPath: ~typing.Optional[str] = None)[source]

Bases: object

A class to handle a single SNOWing (Stochastic Nucleation of Water

with INternal Gradients) simulation.

More information regarding the equations and their derivation can be found in https://doi.org/10.1016/j.cej.2024.148660, Deck et al. (2024).

Parameters

  • k (dict) – Heat transfer coefficients.

  • opcond (OperatingConditions) – Operating conditions of the run.

  • temperature (str) – Model dimensionality.

  • configuration (str) – Freezing configuration.

  • plotting (bool) – Whether evolutions are plotted or not.

  • Nrep (int) – Number of repetitions.

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

property configPath: Optional[str]

Get configPath property.

property iceMassFraction: ndarray

Return ice mass fraction evolution in simulation of instance.

Returns

Ice mass fraction evolution (no units).

Return type

np.ndarray

plot(what: str = 't_nuc', kind: str = 'box')[source]

Create categorical plots for Snowing object.

Parameters

  • what (str, optional) – What to plot, i.e., keys of the stats dict. Valid options are t_nuc, T_nuc, t_sol, t_fr. Defaults to “t_nuc”. Also accepting t_nucleation, T_nucleation and t_solidification.

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

plot_cdf(what: str = 't_nuc', comp: bool = False)[source]

Create CDF plots for Snowing object.

Parameters

  • what (str, optional) – What to plot, i.e., keys of the stats dict. Valid options are t_nuc, T_nuc, t_sol, t_fr. Defaults to “t_nuc”. Also accepting t_nucleation, T_nucleation and t_solidification.

  • comp (bool, optional) – If complementary CDF is plotted. Defaults to False.

  • what – What to plot, i.e., keys of the stats dict. Valid options are t_nuc, T_nuc, t_sol, t_fr. Defaults to “t_nuc”. Also accepting t_nucleation, T_nucleation and t_solidification.

Raises

NotImplementedError – This plot not available for single vial simulation.

plot_evolution(what: str = 'temperature')[source]

Function to plot the spatial evolution of temperature or ice mass fractions.

Parameters

what (str, optional) – Quantity to be plotted. Defaults to “temperature”.

Raises

  • NotImplementedError – This plotting functionality is only implemented for single simulations (when Nrep = 1), otherwise, an error is raised.

  • ValueError – Raises error if quantity for plotting is incorrectly specified.

property results: dict
Return minimum, mean, kinetic mean and maximum nucleation temperature

in simulation of instance.

Returns

4 values of nucleation temperature (minimum, kinetic mean, mean and maximum). Irrelevant for homogeneous model simulation.

Return type

dict

run(how='async')[source]
property shelfTemp: ndarray

Return shelf temperature evolution in the simulation of instance.

Returns

Shelf temperature evolution in °C.

Return type

np.ndarray

property simulationStatus: int

Return simulation status of instance.

Returns

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

Return type

int

property temp: ndarray

Return temperature evolution in the simulation of instance.

Returns

Temperature evolution in °C.

Return type

np.ndarray

property time: ndarray

Return time array in the simulation of instance.

Returns

Time array in hours.

Return type

np.ndarray

ethz_snow.utils module

ethz_snow.utils.colormap(z)[source]

A function to create a colormap used to plot the time evolutions of temperature and ice mass fractions with respect to vertical positions in the vial.

Parameters

z (np.ndarray) – Discretized spatial domain in the vertical direction.

ethz_snow.utils.vapour_flux(kappa, m_water, k_B, p_vac, p_vap, T_l, T_v)[source]

A function to compute the water vapour flux at the top surface, which is exposed to vacuum during VISF.

Parameters

  • kappa (float) – Evaporation efficiency.

  • m_water (float) – Mass of a water molecule.

  • k_B (float) – Boltzmann constant.

  • p_vac (np.ndarray) – Chamber vacuum pressure.

  • p_vap (np.ndarray) – Vapour pressure.

  • T_l (np.ndarray) – Product temperature.

  • T_v (np.ndarray) – Vapour temperature.

Returns

Flux of water vapour at the top surface of the frozen or liquid product

Return type

np.ndarray

ethz_snow.utils.vapour_pressure_liquid(T_liq)[source]

A function to compute the water vapour pressure above the liquid product in a vial based on the product surface temperature.

Parameters

T_liq (np.ndarray) – Liquid product temperature at the surface.

Returns

Water vapour pressure above the product surface.

Return type

np.ndarray

ethz_snow.utils.vapour_pressure_solid(T_sol)[source]

A function to compute the water vapour pressure above the frozen product in a vial based on the frozen product surface temperature.

Parameters

T_sol (np.ndarray) – Frozen product temperature at the surface.

Returns

Water vapour pressure above the product surface.

Return type

np.ndarray

Module contents