Py Droplets

https://github.com/zwicker-group/py-droplets
Admin
Python package for describing and analyzing droplets in experiments and simulations.
Tokens:24,010
Snippets:213
Trust Score:9.1
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Optional Dependencies with pip

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/installation.md

Install these optional packages alongside py-droplets to enable all features, such as HDF5 file support.

```bash
pip install h5py pyfftw
```

--------------------------------

### Install py-droplets using pip

Source: https://github.com/zwicker-group/py-droplets/blob/master/README.md

Install the py-droplets package using pip. This is the standard method for installing Python packages.

```bash
pip install py-droplets
```

--------------------------------

### start

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplet_tracks.md

Retrieves the first time point of the droplet track.

```APIDOC
## start

### Description
first time point

### Type
float
```

--------------------------------

### Create an Emulsion and get statistics

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Creates an emulsion from a list of droplets and retrieves size statistics.

```python
emulsion = droplets.Emulsion([drop1, drop2])
emulsion.get_size_statistics()
```

--------------------------------

### Install py-droplets using conda

Source: https://github.com/zwicker-group/py-droplets/blob/master/README.md

Install the py-droplets package using conda from the conda-forge channel. This is an alternative installation method.

```bash
conda install -c conda-forge py-droplets
```

--------------------------------

### Create and Plot Emulsion

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/examples/plot_emulsion.md

This snippet initializes random droplets, forms an emulsion, removes overlaps, and visualizes the result. Ensure the 'droplets' library is installed.

```python
import numpy as np

from droplets import DiffuseDroplet, Emulsion

# create 10 random droplets
droplets = [
    DiffuseDroplet(
        position=np.random.uniform(0, 100, 2),
        radius=np.random.uniform(5, 10),
        interface_width=1,
    )
    for _ in range(10)
]

# remove overlapping droplets in emulsion and plot it
emulsion = Emulsion(droplets)
emulsion.remove_overlapping()
emulsion.plot()
```

--------------------------------

### Emulsion.bbox

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Get the bounding box of the emulsion.

```APIDOC
## Emulsion.bbox

### Description
Bounding box of the emulsion.

### Type
`Cuboid`
```

--------------------------------

### Create and Plot Emulsion with Droplets

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/examples/plot_emulsion_properties.md

Generates random droplets, removes overlaps within an emulsion, and plots the resulting emulsion, coloring droplets by their radius. Ensure the droplets library and numpy are installed.

```python
import numpy as np

from droplets import DiffuseDroplet, Emulsion

# create 10 random droplets
droplets = [
    DiffuseDroplet(
        position=np.random.uniform(0, 100, 2),
        radius=np.random.uniform(5, 10),
        interface_width=1,
    )
    for _ in range(10)
]

# remove overlapping droplets in emulsion and plot it
emulsion = Emulsion(droplets)
emulsion.remove_overlapping()
emulsion.plot(color_value=lambda droplet: droplet.radius, colorbar="Droplet radius")
```

--------------------------------

### Get size statistics of located droplets

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Calculates and returns the size statistics for droplets identified in the simulation data.

```python
emulsion.get_size_statistics()
```

--------------------------------

### Get phase field of an emulsion

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Generates and plots the phase field for an entire emulsion on a specified grid.

```python
emulsion.get_phasefield(grid).plot(title="An emulsion");
```

--------------------------------

### Emulsion.dim

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Get the dimensionality of the space in which droplets are defined.

```APIDOC
## Emulsion.dim

### Description
Dimensionality of space in which droplets are defined

### Type
int | None
```

--------------------------------

### Get pairwise distances in an emulsion

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Calculates and returns the distances between all pairs of droplets in an emulsion.

```python
emulsion.get_pairwise_distances()
```

--------------------------------

### Emulsion.data

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Get an array containing the data of the full emulsion. This requires all droplets to be of the same class.

```APIDOC
## Emulsion.data

### Description
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`
```

--------------------------------

### Get phase field for a droplet

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Generates and plots the phase field representation of a droplet on a given grid.

```python
grid = pde.CartesianGrid([[0, 10], [0, 10]], 64)
field1 = drop1.get_phase_field(grid)
field1.plot(colorbar=True)
```

--------------------------------

### Get phase field for a diffuse droplet

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Generates and plots the phase field representation of a diffuse droplet on a given grid.

```python
field2 = drop2.get_phase_field(grid)
field2.plot(colorbar=True)
```

--------------------------------

### Run a Cahn-Hilliard simulation

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Sets up and solves a Cahn-Hilliard Partial Differential Equation to simulate phase separation.

```python
# run a numerical simulation
grid = pde.UnitGrid([64, 64], periodic=True)
field = pde.ScalarField.random_uniform(grid, -1, 0)
eq = pde.CahnHilliardPDE()

final = eq.solve(field, t_range=1e2, dt=0.01);
```

--------------------------------

### Import necessary packages

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Imports the required libraries for numerical operations, PDE solving, and droplet simulations.

```python
import numpy as np

# import necessary packages
import pde

import droplets
```

--------------------------------

### Run and Analyze Emulsion Simulation

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/examples/analyze_simulation.md

This snippet demonstrates how to set up and run a Cahn-Hilliard simulation for emulsions using `py-droplets`. It initializes a scalar field, defines the PDE, and then solves it while tracking the emulsion's evolution. Finally, it prints the size statistics of the last recorded state.

```python
from pde import CahnHilliardPDE, ScalarField, UnitGrid

from droplets.emulsions import EmulsionTimeCourse

field = ScalarField.random_uniform(UnitGrid([32, 32]), -1, 1)
pde = CahnHilliardPDE()

etc = EmulsionTimeCourse()
pde.solve(field, t_range=10, backend="numpy", tracker=etc.tracker())

print(etc[-1].get_size_statistics())
```

--------------------------------

### Emulsion.dtype

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Get or set the data type of the droplets in the emulsion.

```APIDOC
## Emulsion.dtype

### Description
Type of the data, which determines the type of droplets in the emulsion.

### Type
dtype[Any] | None | type[Any] | _SupportsDType[dtype[Any]] | str | tuple[Any, int] | tuple[Any, SupportsIndex | Sequence[SupportsIndex]] | list[Any] | _DTypeDict | tuple[Any, Any]
```

--------------------------------

### Emulsion.from_file

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Create an emulsion by reading data from a file.

```APIDOC
## Emulsion.from_file

### Description
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()`](#droplets.emulsions.Emulsion.to_file).

### Returns
The emulsion read from the file

### Return type
[`Emulsion`](#droplets.emulsions.Emulsion)
```

--------------------------------

### Create DropletTrackList from time course

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Constructs a `DropletTrackList` object from the recorded emulsion data over time.

```python
track_list = droplets.DropletTrackList.from_emulsion_time_course(tracker.data)
```

--------------------------------

### Get interface width of refined droplets

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Retrieves the interface width parameter for the refined droplets.

```python
emulsion.interface_width
```

--------------------------------

### Track droplets during simulation

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Initializes a `DropletTracker` and solves the PDE, saving droplet data at specified intervals.

```python
tracker = droplets.DropletTracker(interrupts=50)
final = eq.solve(field, t_range=1e3, dt=0.01, tracker=["progress", tracker]);
```

--------------------------------

### EmulsionTimeCourse.from_storage

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Creates an EmulsionTimeCourse from a stored phase field, with options for refinement and parallel processing.

```APIDOC
## EmulsionTimeCourse.from_storage(storage, *, num_processes='auto', refine=False, progress=None, **kwargs)

### Description
Create an emulsion time course from a stored phase field.

### Parameters
#### Path Parameters
- **storage** (StorageBase) - Required - The phase fields for many time instances
- **refine** (bool) - Optional - Flag determining whether the droplet properties should be refined
  using fitting. This is a potentially slow procedure.
- **num_processes** (int or "auto") - Optional - Number of processes used for the refinement. If set to “auto”, the
  number of processes is chosen automatically.
- **progress** (bool) - Optional - 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** - Optional - All other parameters are forwarded to the
  [`locate_droplets()`](droplets.image_analysis.md#droplets.image_analysis.locate_droplets).

### Returns
an instance describing the emulsion time course

### Return type
EmulsionTimeCourse
```

--------------------------------

### get_pairwise_distances

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Computes the pairwise distances between all droplets in the emulsion. Optionally, radii can be subtracted to get surface-to-surface distances.

```APIDOC
## get_pairwise_distances(subtract_radius=False, grid=None)

### Description
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`
```

--------------------------------

### EmulsionTimeCourse.from_file

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Creates an EmulsionTimeCourse by reading data from an HDF5 file previously saved with to_file.

```APIDOC
## EmulsionTimeCourse.from_file(path, *, progress=True)

### Description
Create emulsion time course by reading file.

### Parameters
#### Path Parameters
- **path** (str) - Required - The path from which the data is read. This function assumes that the
  data was written as an HDF5 file using [`to_file()`](#droplets.emulsions.EmulsionTimeCourse.to_file).
- **progress** (bool) - Optional - Whether to show the progress of the process in a progress bar

### Returns
an instance describing the emulsion time course

### Return type
EmulsionTimeCourse
```

--------------------------------

### handle

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.trackers.md

Handles the data supplied to this tracker at a specific point in time.

```APIDOC
## handle(field, t)

### Description
Handle data supplied to this tracker.

### Parameters
* **field** (`FieldBase`) – The current state of the simulation
* **t** (*float*) – The associated time
```

--------------------------------

### Get last emulsion state from tracker

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Retrieves the emulsion state from the last recorded data point of the `DropletTracker`.

```python
emulsion_last = tracker.data[-1]
emulsion_last.get_size_statistics()
```

--------------------------------

### DropletTrackList.from_file

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplet_tracks.md

Creates a droplet track list by reading data from an HDF5 file. This method assumes the data was previously saved using the `to_file` method.

```APIDOC
## DropletTrackList.from_file

### Description
Create droplet track list by reading file.

### Method Signature
`from_file(path, *, progress=True)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### 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()`](#droplets.droplet_tracks.DropletTrackList.to_file).
* **progress** (*bool*) – Whether to show the progress of the process in a progress bar

### Returns
an instance describing the droplet track list

### Return type
[`DropletTrackList`](#droplets.droplet_tracks.DropletTrackList)
```

--------------------------------

### Plot final phase field from simulation

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Visualizes the final state of the phase field after the simulation.

```python
final.plot(title="Final phase field");
```

--------------------------------

### Locate and Visualize Droplets in an Image

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/examples/analyze_image.md

Load an image, locate droplets using ScalarField, and visualize the detected droplets overlaid on the original field. Ensure the 'emulsion.png' resource is available.

```python
from pathlib import Path

from pde.fields import ScalarField

from droplets.image_analysis import locate_droplets

img_path = Path(__file__).parent / "resources" / "emulsion.png"
field = ScalarField.from_image(img_path)
emulsion = locate_droplets(field)

# visualize the result
emulsion.plot(field=field, fill=False, color="w")
```

--------------------------------

### DropletTrack.from_file

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplet_tracks.md

Creates a DropletTrack object by reading data from a specified file path.

```APIDOC
## from_file(path)

### Description
Create droplet track by reading from 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()`](#droplets.droplet_tracks.DropletTrack.to_file).

### Return type
[*DropletTrack*](#droplets.droplet_tracks.DropletTrack)
```

--------------------------------

### Create a SphericalDroplet

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Initializes a spherical droplet with a specified position and radius. Access its volume property.

```python
drop1 = droplets.SphericalDroplet(position=[3, 4], radius=2)
drop1.volume
```

--------------------------------

### Emulsion.extend

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Add multiple droplets to the emulsion.

```APIDOC
## Emulsion.extend

### Description
Add many droplets to the emulsion.

### Parameters
* **droplet** (list of [`droplets.droplets.SphericalDroplet`](droplets.droplets.md#droplets.droplets.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*](droplets.droplets.md#droplets.droplets.SphericalDroplet) *]*) 

### Return type
None
```

--------------------------------

### Create a DiffuseDroplet

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Initializes a diffuse droplet with position, radius, and interface width. Access its volume property.

```python
drop2 = droplets.DiffuseDroplet(position=[6, 8], radius=2, interface_width=0.3)
drop2.volume
```

--------------------------------

### EmulsionTimeCourse.to_file

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Stores the EmulsionTimeCourse data to an HDF5 file, which can be later read using EmulsionTimeCourse.from_file.

```APIDOC
## EmulsionTimeCourse.to_file(path, info=None)

### Description
Store data in hdf5 file.

The data can be read using the classmethod [`EmulsionTimeCourse.from_file()`](#droplets.emulsions.EmulsionTimeCourse.from_file).

### Parameters
#### Path Parameters
- **path** (str) - Required - The path to which the data is written as an HDF5 file.
- **info** (dict) - Optional - Additional data stored alongside the droplet track list

### Return type
None
```

--------------------------------

### Emulsion.append

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Add a droplet to the emulsion.

```APIDOC
## Emulsion.append

### Description
Add a droplet to the emulsion.

### Parameters
* **droplet** ([`droplets.droplets.SphericalDroplet`](droplets.droplets.md#droplets.droplets.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
```

--------------------------------

### EmulsionTimeCourse.tracker

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Returns a DropletTracker for analyzing emulsions during simulations.

```APIDOC
## EmulsionTimeCourse.tracker(interrupts, filename=None)

### Description
Return a tracker that analyzes emulsions during simulations.

### Parameters
#### Path Parameters
- **interrupts** (InterruptData) - Required - {ARG_TRACKER_INTERRUPTS}
- **filename** (str) - Optional - determines where the EmulsionTimeCourse data is
  stored

### Return type
DropletTracker
```

--------------------------------

### Create and clean an emulsion

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Generates an emulsion with randomly placed droplets and removes any overlapping droplets.

```python
data = [
    droplets.SphericalDroplet(
        position=np.random.uniform(0, 100, 2), radius=np.random.uniform(5, 10)
    )
    for _ in range(30)
]

emulsion = droplets.Emulsion(data)
emulsion.remove_overlapping()
emulsion.plot(title=f"{len(emulsion)} droplets");
```

--------------------------------

### EmulsionTimeCourse.items

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Iterates over all times and emulsions, yielding them as pairs.

```APIDOC
## EmulsionTimeCourse.items()

### Description
Iterate over all times and emulsions, returning them in pairs.

### Return type
Iterator[tuple[float, Emulsion]]
```

--------------------------------

### Droplet Methods

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplets.md

Methods for creating, checking, and manipulating Droplet objects.

```APIDOC
## Droplet Methods

### Description
Provides methods for creating droplets from volumes, checking data validity, generating phase field representations, obtaining triangulations, calculating interface positions, and checking for overlaps with other droplets.

### Methods
#### `check_data()`
Method that checks the validity and consistency of self.data.

#### `from_volume(position, volume, **kwargs)`
Construct a droplet from given volume instead of radius.

* **Parameters:**
  * **position** (`ndarray`) – Center of the droplet
  * **volume** (*float*) – Volume of the droplet
  * **&&kwargs** – Additional arguments are forwarded to the class initializer. This can
    for instance be used to set the interfacial width.

#### `get_dtype(**kwargs)`
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:**
  `numpy.dtype`

#### `get_phase_field(grid, *, vmin=0, vmax=1, label=None)`
Creates an image of the droplet on the grid.

* **Parameters:**
  * **grid** (`GridBase`) – The grid used for discretizing the droplet phase field
  * **vmin** (*float*) – Minimal value the phase field will attain (far away from droplet)
  * **vmax** (*float*) – Maximal value the phase field will attain (inside the droplet)
  * **label** (*str*) – The label associated with the returned scalar field
* **Returns:**
  A scalar field representing the droplet
* **Return type:**
  `ScalarField`

#### `get_triangulation(resolution=1)`
Obtain a triangulated shape of the droplet surface.

* **Parameters:**
  **resolution** (*float*) – The length of a typical triangulation element. This affects the
  resolution of the triangulation.
* **Returns:**
  A dictionary containing information about the triangulation. The exact
  details depend on the dimension of the problem.
* **Return type:**
  dict

#### `interface_position(*args)`
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, π]$) and the polar angle φ (in
  $[0, 2π]$) need to be specified.
* **Returns:**
  An array with the coordinates of the interfacial
  points associated with each angle given by φ.
* **Return type:**
  `ndarray`
* **Raises:**
  **ValueError** – If the dimension of the space is not 2

#### `overlaps(other, grid=None)`
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`](#droplets.droplets.SphericalDroplet)) – instance of the other droplet
  * **grid** (`GridBase`) – grid that determines how distances are measured, which is for instance
    important to respect periodic boundary conditions. If omitted, an
    Euclidean distance is assumed.
* **Returns:**
  whether the droplets overlap or not
* **Return type:**
  bool
```

--------------------------------

### DropletTrack.first

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplet_tracks.md

Returns the first droplet instance in the track.

```APIDOC
## property first

### Description
first droplet instance

### Type
[SphericalDroplet](droplets.droplets.md#droplets.droplets.SphericalDroplet)
```

--------------------------------

### to_file

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplet_tracks.md

Stores droplet track data in an HDF5 file.

```APIDOC
## to_file(path, info=None)

### Description
Store data in hdf5 file. The data can be read using the classmethod DropletTrackList.from_file().

### Parameters
#### Path Parameters
- **path** (str) - Required - The path to which the data is written as an HDF5 file.
- **info** (dict) - Optional - Additional data stored alongside the droplet track list.

### Returns
- None
```

--------------------------------

### DropletTrackList.from_emulsion_time_course

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplet_tracks.md

Obtains droplet tracks from a time course of emulsions. It supports different tracking methods and optional grid configurations for periodic boundary conditions.

```APIDOC
## DropletTrackList.from_emulsion_time_course

### Description
Obtain droplet tracks from an emulsion time course.

### Method Signature
`from_emulsion_time_course(time_course, *, method='overlap', grid=None, progress=False, **kwargs)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **time_course** ([`droplets.emulsions.EmulsionTimeCourse`](droplets.emulsions.md#droplets.emulsions.EmulsionTimeCourse)) – A collection of temporally arranged emulsions
* **method** (*str*) – The method used for tracking droplet identities. Possible methods are
  “overlap” (adding droplets that overlap with those in previous frames)
  and “distance” (matching droplets to minimize center-to-center
  distances).
* **grid** (`GridBase`) – The grid on which the droplets are defined, which is necessary if
  periodic boundary conditions should be respected for measuring distances
* **progress** (*bool*) – Whether to show the progress of the process.
* **kwargs** – Additional parameters for the tracking algorithm. Currently, one can
  only specify a maximal distance (using max_dist) for the “distance”
  method.

### Returns
the resulting droplet tracks

### Return type
[`DropletTrackList`](#droplets.droplet_tracks.DropletTrackList)
```

--------------------------------

### Emulsion.to_file

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Stores the emulsion data to an HDF5 file, which can be later read using Emulsion.from_file.

```APIDOC
## Emulsion.to_file(path)

### Description
Store data in hdf5 file.

The data can be read using the classmethod [`Emulsion.from_file()`](#droplets.emulsions.Emulsion.from_file).

### Parameters
#### Path Parameters
- **path** (str) - Required - The path to which the data is written as an HDF5 file.

### Return type
None
```

--------------------------------

### EmulsionTimeCourse.append

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Adds an Emulsion instance to the time course at a specified time point.

```APIDOC
## EmulsionTimeCourse.append(emulsion, time=None, copy=True)

### Description
Add an emulsion to the list.

### Parameters
#### Path Parameters
- **emulsion** (Emulsion) - Required - An [`Emulsion`](#droplets.emulsions.Emulsion) instance that is added to the time course
- **time** (float) - Optional - The time point associated with this emulsion
- **copy** (bool) - Optional - Whether to copy the emulsion

### Return type
None
```

--------------------------------

### Plot last emulsion state with field and linewidth

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Visualizes the last recorded emulsion state, overlaid on the final phase field, with specified line width.

```python
emulsion_last.plot(field=final, linewidth=3)
```

--------------------------------

### Locate and refine droplets

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Identifies droplets in the simulation data and refines their positions by fitting.

```python
emulsion = droplets.locate_droplets(final, refine=True)
emulsion[0]
```

--------------------------------

### volume_from_radius

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.tools.spherical.md

Calculates the volume of a sphere given its radius and the dimension of the space.

```APIDOC
## volume_from_radius(radius, dim)

### Description
Return the volume of a sphere with a given radius.

### Parameters
* **radius** (float or `ndarray`) – Radius of the sphere
* **dim** (*int*) – Dimension of the space

### Returns
Volume of the sphere

### Return type
float or `ndarray`
```

--------------------------------

### from_random

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Creates an emulsion with a specified number of randomly placed droplets. Overlapping droplets can be optionally removed.

```APIDOC
## from_random(num, grid_or_bounds, radius, *, remove_overlapping=True, droplet_class=<class 'droplets.droplets.SphericalDroplet'>, rng=None)

### Description
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 than num droplets.
* **droplet_class** ([`SphericalDroplet`](droplets.droplets.md#droplets.droplets.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`](#droplets.emulsions.Emulsion)
```

--------------------------------

### surface_from_radius

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.tools.spherical.md

Calculates the surface area of a sphere given its radius and the dimension of the space.

```APIDOC
## surface_from_radius(radius, dim)

### Description
Return the surface area of a sphere with a given radius.

### Parameters
* **radius** (float or `ndarray`) – Radius of the sphere
* **dim** (*int*) – Dimension of the space

### Returns
Surface area of the sphere

### Return type
float or `ndarray`
```

--------------------------------

### Plot simulation result with tracker

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Displays the final phase field from a simulation that used a tracker.

```python
final.plot();
```

--------------------------------

### Plot emulsion phase field on a high-resolution grid

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Generates and plots the phase field of an emulsion on a high-resolution grid.

```python
emulsion.get_phasefield(pde.UnitGrid([100, 100])).plot(title="An emulsion");
```

--------------------------------

### make_surface_from_radius_compiled(dim)

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.tools.spherical.md

Returns a compiled function that calculates the surface area of a sphere given its radius and dimension.

```APIDOC
## make_surface_from_radius_compiled(dim)

### Description
Return a function calculating the surface area of a sphere.

### Parameters
#### Path Parameters
- **dim** (int) - Required - Dimension of the space

### Returns
A function that takes a radius and returns the surface area.

### Return type
function
```

--------------------------------

### DropletTrack.items

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplet_tracks.md

Iterates over all recorded time points and corresponding droplet states.

```APIDOC
## items()

### Description
Iterate over all times and droplets, returning them in pairs.
```

--------------------------------

### make_volume_from_radius_nd_compiled()

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.tools.spherical.md

Returns a compiled function that calculates the volume of a sphere given its radius and dimension.

```APIDOC
## make_volume_from_radius_nd_compiled()

### Description
Return a function calculating the volume of a sphere with a given radius.

### Returns
A function that calculates the volume using a radius and dimension.

### Return type
function
```

--------------------------------

### DropletTrackList.from_storage

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplet_tracks.md

Obtains droplet tracks from stored scalar field data. This method first determines an emulsion time course and then collects tracks by tracking droplets.

```APIDOC
## DropletTrackList.from_storage

### Description
Obtain droplet tracks from stored scalar field data.

### Method Signature
`from_storage(storage, *, method='overlap', refine=False, num_processes=1, progress=None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **storage** (`StorageBase`) – The phase fields for many time instances
* **method** (*str*) – The method used for tracking droplet identities. Possible methods are
  “overlap” (adding droplets that overlap with those in previous frames)
  and “distance” (matching droplets to minimize center-to-center
  distances).
* **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 chosen automatically.
* **progress** (*bool*) – Whether to show the progress of the process. If None, the progress is
  not shown, except for the first step if refine is True.

### Returns
the resulting droplet tracks

### Return type
[`DropletTrackList`](#droplets.droplet_tracks.DropletTrackList)
```

--------------------------------

### DropletTrackList.to_file

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplet_tracks.md

Stores droplet track data in an HDF5 file. The stored data can be later retrieved using the `DropletTrack.from_file` classmethod.

```APIDOC
## DropletTrackList.to_file

### Description
Store data in hdf5 file.

### Method Signature
`to_file(path, info=None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### 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

### Returns
None
```

--------------------------------

### Emulsion.empty

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Create an empty emulsion with a specified droplet type.

```APIDOC
## Emulsion.empty

### Description
Create empty emulsion with particular droplet type.

### Parameters
* **droplet** ([`SphericalDroplet`](droplets.droplets.md#droplets.droplets.SphericalDroplet)) – An example for a droplet, which defines the type of

### Returns
The empty emulsion

### Return type
[`Emulsion`](#droplets.emulsions.Emulsion)
```

--------------------------------

### make_volume_from_radius_compiled(dim)

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.tools.spherical.md

Returns a compiled function that calculates the volume of a sphere given its radius and dimension.

```APIDOC
## make_volume_from_radius_compiled(dim)

### Description
Return a function calculating the volume of a sphere with a given radius.

### Parameters
#### Path Parameters
- **dim** (int) - Required - Dimension of the space

### Returns
A function that takes a radius and returns the volume.

### Return type
function
```

--------------------------------

### Combine and plot phase fields

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Combines the phase fields of two droplets and plots the resulting field.

```python
(field1 + field2).plot();
```

--------------------------------

### Plot droplet trajectories

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Visualizes the overall trajectories of the droplets based on the tracked data.

```python
track_list.plot()
```

--------------------------------

### Print droplet count per time step

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Iterates through the tracked emulsion data and prints the number of droplets at each recorded time step.

```python
for t, emulsion in zip(tracker.data.times, tracker.data, strict=False):
    print(f"t={round(t)}: {len(emulsion)} droplets")
```

--------------------------------

### Emulsion.copy

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Return a copy of this emulsion, optionally filtering by minimum radius.

```APIDOC
## Emulsion.copy

### Description
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*](#droplets.emulsions.Emulsion)
```

--------------------------------

### Locate droplets in simulation data

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Identifies and extracts droplet information from a phase field using `locate_droplets`.

```python
emulsion = droplets.locate_droplets(final)
emulsion[0]
```

--------------------------------

### radius_from_surface(surface, dim)

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.tools.spherical.md

Calculates the radius of a sphere given its surface area and dimension.

```APIDOC
## radius_from_surface(surface, dim)

### Description
Return the radius of a sphere with a given surface area.

### Parameters
#### Path Parameters
- **surface** (float or ndarray) - Required - Surface area of the sphere
- **dim** (int) - Required - Dimension of the space

### Returns
Radius of the sphere.

### Return type
float or ndarray
```

--------------------------------

### volume

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplets.md

Retrieves the volume of the droplet.

```APIDOC
## volume

### Description
Gets the volume of the droplet.

### Type
float
```

--------------------------------

### Plot droplet positions over time

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Generates a plot showing the positions of individual droplets at different time points.

```python
track_list.plot_positions()
```

--------------------------------

### Define and Overlap Droplets

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/examples/define_droplets.md

Construct two droplets, a SphericalDroplet and a DiffuseDroplet, and check if they overlap. Ensure the droplets library is imported.

```python
from droplets import DiffuseDroplet, Emulsion, SphericalDroplet

# construct two droplets
drop1 = SphericalDroplet(position=[0, 0], radius=2)
drop2 = DiffuseDroplet(position=[6, 8], radius=3, interface_width=1)

# check whether they overlap
print(drop1.overlaps(drop2))  # prints False

# construct an emulsion and query it
e = Emulsion([drop1, drop2])
e.get_size_statistics()
```

--------------------------------

### Plot an emulsion

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Visualizes the droplets within an emulsion.

```python
emulsion.plot()
```

--------------------------------

### make_radius_from_volume_nd_compiled()

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.tools.spherical.md

Returns a compiled function that calculates the radius of a sphere given its volume and dimension.

```APIDOC
## make_radius_from_volume_nd_compiled()

### Description
Return a function calculating the radius of a sphere with a given volume.

### Returns
A function that calculate the radius from a volume and dimension.

### Return type
function
```

--------------------------------

### DropletTracker Class

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.trackers.md

Detects droplets in a scalar field during simulations. It stores less information than full scalar field tracking, making it efficient when only droplet parameters are needed. The data can be saved to a file and loaded later.

```APIDOC
## class DropletTracker

### Description
Detects droplets in a scalar field during simulations. This tracker is useful when only the parameters of actual droplets are needed, since it stores considerably less information compared to the full scalar field. The file written when filename is supplied can be read in later using `from_file()`.

### Parameters
* **interrupts** (InterruptData) – Determines when the tracker interrupts the simulation. A single numbers determines an interval (measured in the simulation time unit) of regular interruption. A string is interpreted as a duration in real time assuming the format ‘hh:mm:ss’. A list of values is taken as explicit simulation time points. More fine-grained control is possible by passing an instance of classes defined in `interrupts`.
* **filename** (str, optional) – Determines the path to the HDF5 file to which the `EmulsionTimeCourse` data is written.
* **emulsion_timecourse** (EmulsionTimeCourse, optional) – Can be an instance of `EmulsionTimeCourse` that is used to store the data. If omitted, an empty class is initiated.
* **source** (int or callable, optional) – Determines how a field is extracted from fields. If None, fields is passed as is, assuming it is already a scalar field. This works for the simple, standard case where only a single ScalarField is treated. Alternatively, source can be an integer, indicating which field is extracted from an instance of `FieldCollection`. Lastly, source can be a function that takes fields as an argument and returns the desired field.
* **threshold** (float or str) – The threshold for binarizing the image. If a value is given it is used directly. Otherwise, the following algorithms are supported: extrema: take mean between the minimum and the maximum of the data, mean: take the mean over the entire data, otsu: use Otsu’s method implemented in `threshold_otsu()`. The special value auto currently defaults to the extrema method.
* **minimal_radius** (float) – Minimal radius of droplets that will be retained.
* **refine** (bool) – Flag determining whether the droplet coordinates should be refined using fitting. This is a potentially slow procedure.
* **refine_args** (dict) – Additional keyword arguments passed on to `refine_droplet()`. Only has an effect if refine=True.
* **perturbation_modes** (int) – An option describing how many perturbation modes should be considered when refining droplets. Only has an effect if refine=True.

### Attributes
* **data** (`EmulsionTimeCourse`) – Contains the data of the tracked droplets after the simulation is done.

### Methods
#### finalize(info=None)
Finalize the tracker, supplying additional information.

* **Parameters**:
  * **info** (dict) – Extra information from the simulation
* **Return type:**
  None

#### handle(field, t)
Handle data supplied to this tracker.

* **Parameters**:
  * **field** (`FieldBase`) – The current state of the simulation
  * **t** (*float*) – The associated time
* **Return type:**
  None
```

--------------------------------

### interface_width

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

A property that returns the average interface width across all droplets, weighted by their surface area.

```APIDOC
## interface_width

### Description
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
```

--------------------------------

### spherical_harmonic_real_k

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.tools.spherical.md

Computes the real spherical harmonics using a combined index k.

```APIDOC
## spherical_harmonic_real_k(k, θ, φ)

### Description
Real spherical harmonics described by mode k.

### Parameters
* **k** (*int*) – Combined index determining the degree and order of the spherical harmonics
* **θ** (*float*) – Azimuthal angle (in $[0, \pi]$) at which function is evaluated.
* **φ** (*float*) – Polar angle (in $[0, 2\pi]$) at which function is evaluated.

### Returns
The value of the spherical harmonics

### Return type
float
```

--------------------------------

### EmulsionTimeCourse.clear

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.emulsions.md

Removes all data stored within the EmulsionTimeCourse instance.

```APIDOC
## EmulsionTimeCourse.clear()

### Description
Removes all data stored in this instance.

### Return type
None
```

--------------------------------

### Plot located droplets on simulation field

Source: https://github.com/zwicker-group/py-droplets/blob/master/examples/tutorial/Using the py-droplets package.ipynb

Visualizes the located droplets overlaid on the simulation's final phase field.

```python
emulsion.plot(field=final);
```

--------------------------------

### plot

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplets.md

Plots the droplet with various customization options for titles, filenames, styles, and axes.

```APIDOC
## plot(value=None, *args, title=None, filename=None, action='auto', ax_style=None, fig_style=None, ax=None, **kwargs)

### Description
Plots the droplet with customizable appearance and output options.

### 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. Options include 'show', 'none', and 'close'. Defaults to 'auto'.
* **ax_style** (*dict*) – Dictionary with properties to modify the axis after plotting, using `matplotlib.pyplot.setp()`. Includes 'use_offset' flag.
* **fig_style** (*dict*) – Dictionary with properties to modify the figure after plotting, using `matplotlib.pyplot.setp()`. For example, `{'dpi': 200}`.
* **ax** (`matplotlib.axes.Axes`) – Figure axes to be used for plotting. Can be 'create' for a new figure or 'reuse' (default) for an existing one.
* **value** (*callable*) – Sets the color of the droplet. Accepts a matplotlib color or a function returning a color.
* **kwargs** – Additional keyword arguments passed to the patch creation class, e.g., `fill=False` for outlines.

### Returns
Information about the plot.

### Return type
`PlotReference`
```

--------------------------------

### make_radius_from_volume_compiled(dim)

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.tools.spherical.md

Returns a compiled function that calculates the radius of a sphere given its volume and dimension.

```APIDOC
## make_radius_from_volume_compiled(dim)

### Description
Return a function calculating the radius of a sphere with a given volume.

### Parameters
#### Path Parameters
- **dim** (int) - Required - Dimension of the space

### Returns
A function that takes a volume and returns the radius.

### Return type
function
```

--------------------------------

### plot

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplet_tracks.md

Plots the time evolution of all droplets based on a specified attribute.

```APIDOC
## plot(attribute='radius', *args, title=None, filename=None, action='auto', ax_style=None, fig_style=None, ax=None, **kwargs)

### Description
Plots the time evolution of all droplets.

### Parameters
#### Path Parameters
- **attribute** (str) - Required - The attribute to plot. Typical values include radius and volume, but others might be defined on the droplet class.
- **args** - Variable length argument list.
- **title** (str) - Optional - 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) - Optional - Decides what to do with the final figure. Options: 'show', 'none', 'close'. Defaults to 'auto'.
- **ax_style** (dict) - Optional - Dictionary with properties to change on the axis after plotting.
- **fig_style** (dict) - Optional - Dictionary with properties to change on the figure after plotting.
- **ax** (matplotlib.axes.Axes) - Optional - Figure axes to be used for plotting. Defaults to 'reuse'.
- **kwargs** - Additional keyword arguments passed to the matplotlib plot function.

### Returns
- **PlotReference** - Information about the plot
```

--------------------------------

### position

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplets.md

Retrieves the position of the droplet.

```APIDOC
## position

### Description
Gets the position of the droplet.

### Type
`ndarray`
```

--------------------------------

### DropletTrack.get_volumes

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplet_tracks.md

Retrieves the volumes of the droplet at each time point, with optional Gaussian smoothing.

```APIDOC
## get_volumes(smoothing=0)

### Description
`ndarray`: returns the droplet volume for each time point.

### Parameters
* **smoothing** (*float*) – Determines the volume scale for some gaussian smoothing of the
  trajectory. The default value of zero disables smoothing.

### Return type
RealArray
```

--------------------------------

### DropletTrack.data

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplet_tracks.md

Provides access to the full track data as a NumPy array.

```APIDOC
## property data

### Description
an array containing the data of the full track.

### Type
`ndarray`
```

--------------------------------

### plot_positions

Source: https://github.com/zwicker-group/py-droplets/blob/master/docs/source/packages/droplets.droplet_tracks.md

Plots all droplet tracks.

```APIDOC
## plot_positions(*args, title=None, filename=None, action='auto', ax_style=None, fig_style=None, ax=None, **kwargs)

### Description
Plots all droplet tracks.

### Parameters
#### Path Parameters
- **args** - Variable length argument list.
- **title** (str) - Optional - 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) - Optional - Decides what to do with the final figure. Options: 'show', 'none', 'close'. Defaults to 'auto'.
- **ax_style** (dict) - Optional - Dictionary with properties to change on the axis after plotting.
- **fig_style** (dict) - Optional - Dictionary with properties to change on the figure after plotting.
- **ax** (matplotlib.axes.Axes) - Optional - Figure axes to be used for plotting. Defaults to 'reuse'.
- **kwargs** - Additional keyword arguments passed to the matplotlib plot function.

### Returns
- **PlotReference** - Information about the plot
```
Tokens:
Raw