droplets.emulsions module
Classes describing collections of droplets, i.e. emulsions, and their temporal dynamics.
class representing a collection of droplets in a common system |
|
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) –
- property bbox: Cuboid
bounding box of the emulsion
- Type:
Cuboid
- 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:
- 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:
- 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 emulsioncopy (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_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 aGridBase
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:
- 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:
- 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.
- 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:
- 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
- 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:
- 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 backgroundimage_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
- class EmulsionTimeCourse(emulsions=None, times=None)[source]
Bases:
object
represents emulsions as a function of time
- Parameters:
- classmethod from_file(path, progress=True)[source]
create emulsion time course by reading file
- Parameters:
- Returns:
an instance describing the emulsion time course
- Return type:
- 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 instancesrefine (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:
- to_file(path, info=None)[source]
store data in hdf5 file
The data can be read using the classmethod
EmulsionTimeCourse.from_file()
.