droplets.droplets module
Classes representing (perturbed) droplets in various dimensions
The classes differ in what features of a droplet they track. In the simplest case, only the position and radius of a spherical droplet are stored. Other classes additionally keep track of the interfacial width or shape perturbations (of various degrees).
Represents a single, spherical droplet |
|
Represents a single, spherical droplet with a diffuse interface |
|
Represents a single droplet in two dimensions with a perturbed shape |
|
Represents a single droplet in three dimensions with a perturbed shape |
|
Represents a droplet axisymmetrically perturbed shape in three dimensions |
Inheritance structure of the classes:
The details of the classes are explained below:
- class DiffuseDroplet(position, radius, interface_width=None)[source]
Bases:
SphericalDropletRepresents a single, spherical droplet with a diffuse interface
- Parameters:
- class PerturbedDroplet2D(position, radius, interface_width=None, amplitudes=None)[source]
Bases:
PerturbedDropletBaseRepresents a single droplet in two dimensions with a perturbed shape
The shape is described using the distance \(R(\phi)\) of the interface from the position, which is a function of the polar angle \(\phi\). This function is expressed as a truncated series of harmonics:
\[R(\phi) = R_0 + R_0\sum_{n=1}^N \left[ \epsilon^{(1)}_n \sin(n \phi) + \epsilon^{(2)}_n \cos(n \phi) \right]\]where \(N\) is the number of perturbation modes considered, which is given by half the length of the amplitudes array. Consequently, amplitudes should always be an even number, to consider both sin and cos terms.
- Parameters:
position (
ndarray) – Position of the droplet centerradius (float) – Radius of the droplet
interface_width (float, optional) – Width of the interface
amplitudes (
ndarray) – (dimensionless) perturbation amplitudes \(\{\epsilon^{(1)}_1, \epsilon^{(2)}_1, \epsilon^{(1)}_2, \epsilon^{(2)}_2, \epsilon^{(1)}_3, \epsilon^{(2)}_3, \dots \}\). The length of the array needs to be even to capture perturbations of the highest mode consistently.
- dim = 2
- interface_curvature(φ)[source]
calculates the mean curvature of the interface of the droplet
For simplicity, the effect of the perturbations are only included to linear order in the perturbation amplitudes \(\epsilon^{(1/2)}_n\).
- Parameters:
φ (float or
ndarray) – The angle in the polar coordinate system that describing the interface- Returns:
Array with curvature at the interfacial points associated with each angle φ
- Return type:
- interface_distance(φ)[source]
calculates the distance of the droplet interface to the origin
- Parameters:
φ (float or
ndarray) – The angle in the polar coordinate system that describing the interface- Returns:
Array with distances of the interfacial points associated with each angle φ
- Return type:
- interface_position(φ)[source]
calculates the position of the interface of the droplet
- Parameters:
φ (float or
ndarray) – The angle in the polar coordinate system that describing the interface- Returns:
Array with coordinates of interfacial points associated with each angle φ
- Return type:
- class PerturbedDroplet3D(position, radius, interface_width=None, amplitudes=None)[source]
Bases:
PerturbedDropletBaseRepresents a single droplet in three dimensions with a perturbed shape
The shape is described using the distance \(R(\theta, \phi)\) of the interface from the origin as a function of the azimuthal angle \(\theta\) and the polar angle \(\phi\). This function is developed as a truncated series of spherical harmonics \(Y_{l,m}(\theta, \phi)\):
\[R(\theta, \phi) = R_0 \left[1 + \sum_{l=1}^{N_l}\sum_{m=-l}^l \epsilon_{l,m} Y_{l,m}(\theta, \phi) \right]\]where \(N_l\) is the number of perturbation modes considered, which is deduced from the length of the amplitudes array.
- Parameters:
position (
ndarray) – Position of the droplet centerradius (float) – Radius of the droplet
interface_width (float, optional) – Width of the interface
amplitudes (
ndarray) – Perturbation amplitudes \(\epsilon_{l,m}\). Note that the zero-th mode, which would only change the radius, is skipped. Consequently, the length of the array needs to be 0, 3, 8, 15, 24, … to capture perturbations of the highest mode consistently.
- dim = 3
- interface_curvature(θ, φ=None)[source]
calculates the mean curvature of the interface of the droplet
For simplicity, the effect of the perturbations are only included to linear order in the perturbation amplitudes \(\epsilon_{l,m}\).
- Parameters:
θ (float or
ndarray) – Azimuthal angle (in \([0, \pi]\))φ (float or
ndarray) – Polar angle (in \([0, 2\pi]\)); 0 if omitted
- Returns:
Array with curvature at the interfacial points associated with the angles
- Return type:
np.ndarray
- interface_distance(θ, φ=None)[source]
calculates the distance of the droplet interface to the origin
- Parameters:
θ (float or
ndarray) – Azimuthal angle (in \([0, \pi]\))φ (float or
ndarray) – Polar angle (in \([0, 2\pi]\)); 0 if omitted
- Returns:
Array with distances of the interfacial points associated with the angles
- Return type:
np.ndarray
- interface_position(θ, φ=None)[source]
calculates the position of the interface of the droplet
- Parameters:
θ (float or
ndarray) – Azimuthal angle (in \([0, \pi]\))φ (float or
ndarray) – Polar angle (in \([0, 2\pi]\)); 0 if omitted
- Returns:
Array with coordinates of the interfacial points associated with the angles
- Return type:
np.ndarray
- class PerturbedDroplet3DAxisSym(position, radius, interface_width=None, amplitudes=None)[source]
Bases:
PerturbedDropletBaseRepresents a droplet axisymmetrically perturbed shape in three dimensions
The shape is described using the distance \(R(\theta)\) of the interface from the origin as a function of the azimuthal angle \(\theta\), while polar symmetry is assumed. This function is developed as a truncated series of spherical harmonics \(Y_{l,m}(\theta, 0)\):
\[R(\theta) = R_0 \left[1 + \sum_{l=1}^{N_l} \epsilon_{l} Y_{l,0}(\theta, 0) \right]\]where \(N_l\) is the number of perturbation modes considered, which is deduced from the length of the amplitudes array.
- Parameters:
- dim = 3
- interface_curvature(θ)[source]
calculates the mean curvature of the interface of the droplet
For simplicity, the effect of the perturbations are only included to linear order in the perturbation amplitudes \(\epsilon_{l,m}\).
- Parameters:
θ (float or
ndarray) – Azimuthal angle (in \([0, \pi]\))- Returns:
Array with curvature at the interfacial points associated with the angles
- Return type:
- class SphericalDroplet(position, radius)[source]
Bases:
DropletBaseRepresents a single, spherical droplet
- Parameters:
- property bbox: Cuboid
bounding box of the droplet
- Type:
Cuboid
- classmethod from_volume(position, volume)[source]
Construct a droplet from given volume instead of radius
- classmethod get_dtype(**kwargs)[source]
determine the dtype representing this droplet class
- Parameters:
position (
ndarray) – The position vector of the droplet, determining space dimension.- Returns:
the (structured) dtype associated with this class
- Return type:
- get_phase_field(grid, *, vmin=0, vmax=1, label=None)[source]
Creates an image of the droplet on the grid
- Parameters:
- Returns:
A scalar field representing the droplet
- Return type:
ScalarField
- interface_position(*args)[source]
calculates the position of the interface of the droplet
- Parameters:
*args (float or
ndarray) – The angles identifying the interface points. For 2d droplets, this is simply the angle in polar coordinates. For 3d droplets, both the azimuthal angle θ (in \([0, \pi]\)) and the polar angle φ (in \([0, 2\pi]\)) need to be specified.- Returns:
An array with the coordinates of the interfacial points associated with each angle given by φ.
- Return type:
- Raises:
ValueError – If the dimension of the space is not 2
- overlaps(other, grid=None)[source]
determine whether another droplet overlaps with this one
Note that this function so far only compares the distances of the droplets to their radii, which does not respect perturbed droplets correctly.
- Parameters:
other (
SphericalDroplet) – instance of the other dropletgrid (
GridBase) – grid that determines how distances are measured, which is for instance important to respect periodic boundary conditions. If omitted, an Eucledian distance is assumed.
- Returns:
whether the droplets overlap or not
- Return type:
- plot(value=None, *args, title=None, filename=None, action='auto', ax_style=None, fig_style=None, ax=None, **kwargs)[source]
Plot the droplet
- 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.value (callable) – Sets the color of the droplet. This could be either a matplotlib color or a function that takes the droplet instance and returns a color in which this droplet is drawn. If given, it overwrites the color argument.
**kwargs – Additional keyword arguments are passed to the class that creates 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