droplets.emulsions module

Classes describing collections of droplets, i.e. emulsions, and their temporal dynamics.

`Emulsion`	class representing a collection of droplets in a common system
`EmulsionTimeCourse`	represents emulsions as a function of time

class Emulsion(droplets=None, *, copy=True, dtype=None, force_consistency=False, grid=None)[source]

Bases: list

class representing a collection of droplets in a common system

Parameters:

droplets (Iterable[SphericalDroplet] | None) – A list or generator of instances of SphericalDroplet.
copy (bool, optional) – Whether to make a copy of the droplet or not
dtype (DTypeLike) – The dtype describing what droplets are stored in the emulsion. Providing this is usually only necessary for creating empty emulsions. Instead of a dtype, an array or an example droplet can also be supplied.
force_consistency (bool, optional) – Whether to ensure that all droplets are of the same type, i.e., their data is described by the same dtype and matches dtype if given.
grid (GridBase | None) –

append(droplet, *, copy=True, force_consistency=False)[source]

add a droplet to the emulsion

Parameters:

droplet (droplets.dropelts.SphericalDroplet) – Droplet to add to the emulsion
copy (bool, optional) – Whether to make a copy of the droplet or not
force_consistency (bool, optional) – Whether to ensure that all droplets are of the same type

Return type:

None

property bbox: Cuboid

bounding box of the emulsion

Type:: Cuboid

copy(min_radius=-1)[source]

return a copy of this emulsion

Parameters:: min_radius (float) – The minimal radius of the droplets that are retained. Droplets with exactly min_radius are removed, so min_radius == 0 can be used to filter vanished droplets.
Return type:: Emulsion

property data: ndarray

an array containing the data of the full emulsion

Warning

This requires all droplets to be of the same class. The returned array is a copy of all the data and writing to it will thus not change the underlying data.

Type:: ndarray

property dim: int | None

dimensionality of space in which droplets are defined

Type:: int

classmethod empty(droplet)[source]

create empty emulsion with particular droplet type

Parameters:: droplet (SphericalDroplet) – An example for a droplet, which defines the type of
Returns:: The empty emulsion
Return type:: Emulsion

extend(droplets, *, copy=True, force_consistency=False)[source]

add many droplets to the emulsion

Parameters:

droplet (list of droplets.dropelts.SphericalDroplet) – List of droplets to add to the emulsion
copy (bool, optional) – Whether to make a copy of the droplet or not
force_consistency (bool, optional) – Whether to ensure that all droplets are of the same type
droplets (Iterable[SphericalDroplet]) –

Return type:

None

classmethod from_file(path)[source]

create emulsion by reading file

Parameters:: path (str) – The path from which the data is read. This function assumes that the data was written as an HDF5 file using to_file().
Returns:: The emulsion read from the file
Return type:: Emulsion

classmethod from_random(num, grid_or_bounds, radius, *, remove_overlapping=True, droplet_class=<class 'droplets.droplets.SphericalDroplet'>, rng=None)[source]

Create an emulsion with random droplets

Parameters:

num (int) – The (maximal) number of droplets to generate
grid_or_bounds (GridBase or list of float tuples) – Determines the space in which droplets are placed. This is either a GridBase describing the geometry or a sequence of tuples with lower and upper bounds for each axes, so the length of the sequence determines the space dimension.
radius (float or tuple of float) – Radius of the droplets that are created. If two numbers are given, they specify the bounds of a uniform distribution from which the radius of each individual droplet is chosen.
remove_overlapping (bool) – Flag determining whether overlapping droplets are removed. If enabled, the resulting element might contain less thatn num droplets.
droplet_class (SphericalDroplet) – The class that is used to create droplets.
rng (Generator) – Random number generator (default: default_rng())

Returns:

The emulsion containing the random droplets

Return type:

Emulsion

get_linked_data()[source]

link the data of all droplets in a single array

Returns:

The array containing all droplet data. If entries in: this array are modified, it will be reflected in the droplets.

Return type:

ndarray

get_neighbor_distances(subtract_radius=False)[source]

calculates the distance of each droplet to its nearest neighbor

Warning

This function does not take periodic boundary conditions into account.

Parameters:: subtract_radius (bool) – Determines whether to subtract the radius from the distance, i.e., whether to return the distance between the surfaces instead of the positions
Returns:: a vector with a distance for each droplet
Return type:: ndarray

get_pairwise_distances(subtract_radius=False, grid=None)[source]

return the pairwise distance between droplets

Parameters:

subtract_radius (bool) – Determines whether to subtract the radius from the distance, i.e., whether to return the distance between the surfaces instead of the positions
grid (GridBase) – The grid on which the droplets are defined, which is necessary if periodic boundary conditions should be respected for measuring distances

Returns:

a matrix with the distances between all droplets

Return type:

ndarray

get_phasefield(grid, label=None)[source]

create a phase field representing a list of droplets

Parameters:

grid (pde.grids.base.GridBase) – The grid on which the phase field is created. If omitted, the grid associated with the emulsion is used.
label (str, optional) – Optional label for the returned scalar field

Returns:

the actual phase field

Return type:

ScalarField

get_size_statistics(incl_vanished=True)[source]

determine size statistics of the current emulsion

Parameters:: incl_vanished (bool) – Whether to include droplets with vanished radii
Returns:: a dictionary with various size statistics
Return type:: dict

property interface_width: float | None

the average interface width across all droplets

This averages the interface widths of the individual droplets weighted by their surface area, i.e., the amount of interface.

Type:: float

plot(field=None, image_args=None, repeat_periodically=True, color_value=None, cmap=None, norm=None, colorbar=True, *args, title=None, filename=None, action='auto', ax_style=None, fig_style=None, ax=None, **kwargs)[source]

plot the current emulsion together with a corresponding field

If the emulsion is defined in a 3d geometry, only a projection on the first two axes is shown.

Parameters:

title (str) – Title of the plot. If omitted, the title might be chosen automatically.
filename (str, optional) – If given, the plot is written to the specified file.
action (str) – Decides what to do with the final figure. If the argument is set to show, matplotlib.pyplot.show() will be called to show the plot. If the value is none, the figure will be created, but not necessarily shown. The value close closes the figure, after saving it to a file when filename is given. The default value auto implies that the plot is shown if it is not a nested plot call.
ax_style (dict) – Dictionary with properties that will be changed on the axis after the plot has been drawn by calling matplotlib.pyplot.setp(). A special item i this dictionary is use_offset, which is flag that can be used to control whether offset are shown along the axes of the plot.
fig_style (dict) – Dictionary with properties that will be changed on the figure after the plot has been drawn by calling matplotlib.pyplot.setp(). For instance, using fig_style={‘dpi’: 200} increases the resolution of the figure.
ax (matplotlib.axes.Axes) – Figure axes to be used for plotting. The special value “create” creates a new figure, while “reuse” attempts to reuse an existing figure, which is the default.
field (pde.fields.scalar.ScalarField) – provides the phase field that is shown as a background
image_args (dict) – additional arguments determining how the phase field in the background is plotted. Acceptable arguments are described in plot().
repeat_periodically (bool) – flag determining whether droplets are shown on both sides of periodic boundary conditions. This option can slow down plotting
color_value (callable) – Function used to determine the color of a droplet. The function is called with individual droplet objects and must return a single scalar value, which is then mapped to a color using the colormap given by cmap and a suitable normalization given by norm.
cmap (str or Colormap) – The colormap used to map normalized data values to RGBA colors.
norm (Normalize) – The normalizing object which scales data, typically into the interval [0, 1]. If None, norm defaults to a colors.Normalize object which maps the range of values obtained from color_value to [0, 1].
colorbar (bool or str) – Determines whether a colorbar is shown when color_value is supplied. If a string is given, it is used as a label for the colorbar.
**kwargs – Additional keyword arguments are passed to the function creating the patch that represents the droplet. For instance, to only draw the outlines of the droplets, you may need to supply fill=False.

Returns:

Information about the plot

Return type:

PlotReference

remove_overlapping(min_distance=0, grid=None)[source]

remove all droplets that are overlapping

If a pair of overlapping droplets was found, the smaller one of these is removed from the current emulsion. This method modifies the emulsion in place and thus does not return anything.

Parameters:

min_distance (float) – The minimal distance droplets need to be apart. The default value of 0 corresponds to just remove overlapping droplets. Larger values ensure that droplets keep a distance, while negative values allow for some overlap.
grid (GridBase) – The grid on which the droplets are defined, which is necessary if periodic boundary conditions should be respected for measuring distances

Return type:

None

remove_small(min_radius=-inf)[source]

remove droplets that are very small

The emulsions is modified in-place.

Parameters:: min_radius (float) – The minimal radius of the droplets that are retained. Droplets with exactly min_radius are removed, so min_radius == 0 can be used to filter vanished droplets. The default value does not remove any droplets
Return type:: None

to_file(path)[source]

store data in hdf5 file

The data can be read using the classmethod Emulsion.from_file().

Parameters:: path (str) – The path to which the data is written as an HDF5 file.
Return type:: None

property total_droplet_volume: float

the total volume of all droplets

Type:: float

class EmulsionTimeCourse(emulsions=None, times=None)[source]

Bases: object

represents emulsions as a function of time

Parameters:

emulsions (list) – List of emulsions that describe this time course
times (list) – Times associated with the emulsions

append(emulsion, time=None, copy=True)[source]

add an emulsion to the list

Parameters:

emulsions (Emulsion) – An Emulsion instance that is added to the time course
time (float) – The time point associated with this emulsion
copy (bool) – Whether to copy the emulsion
emulsion (Emulsion) –

Return type:

None

clear()[source]

removes all data stored in this instance

Return type:: None

classmethod from_file(path, progress=True)[source]

create emulsion time course by reading file

Parameters:

path (str) – The path from which the data is read. This function assumes that the data was written as an HDF5 file using to_file().
progress (bool) – Whether to show the progress of the process in a progress bar

Returns:

an instance describing the emulsion time course

Return type:

EmulsionTimeCourse

classmethod from_storage(storage, *, num_processes=1, refine=False, progress=None, **kwargs)[source]

create an emulsion time course from a stored phase field

Parameters:

storage (StorageBase) – The phase fields for many time instances
refine (bool) – Flag determining whether the droplet properties should be refined using fitting. This is a potentially slow procedure.
num_processes (int or "auto") – Number of processes used for the refinement. If set to “auto”, the number of processes is choosen automatically.
progress (bool) – Whether to show the progress of the process. If None, the progress is only shown when refine is True. Progress bars are only shown for serial calculations (where num_processes == 1).
**kwargs – All other parameters are forwarded to the locate_droplets().

Returns:

an instance describing the emulsion time course

Return type:

EmulsionTimeCourse

get_emulsion(time)[source]

returns the emulsion clostest to a specific time point

Parameters:: time (float) – The time point
Returns:: Emuslion
Return type:: Emulsion

items()[source]

iterate over all times and emulsions, returning them in pairs

Return type:: Iterator[tuple[float, Emulsion]]

to_file(path, info=None)[source]

store data in hdf5 file

The data can be read using the classmethod EmulsionTimeCourse.from_file().

Parameters:

path (str) – The path to which the data is written as an HDF5 file.
info (dict) – Additional data stored alongside the droplet track list

Return type:

None

tracker(interrupts=1, filename=None, *, interval=None)[source]

return a tracker that analyzes emulsions during simulations

Parameters:

interrupts (InterruptData) – {ARG_TRACKER_INTERRUPTS}
filename (str) – determines where the EmulsionTimeCourse data is stored

Return type:

DropletTracker