py-droplets

https://py-droplets.readthedocs.io/en/latest/
Admin
py-droplets is a Python package that provides methods and classes for studying phase separation...
Tokens:80,351
Snippets:638
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install py-droplets using pip

Source: https://py-droplets.readthedocs.io/en/latest/_sources/installation.rst.txt

Use this command to install the main py-droplets package from PyPI. This is the standard installation method.

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

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

### Install Optional Packages for py-droplets

Source: https://py-droplets.readthedocs.io/en/latest/installation.html

Install these optional packages to enable all features of the py-droplets package, such as h5py for HDF file support and pyfftw for faster Fourier transforms.

```bash
pip install h5py pyfftw

```

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

### Install optional packages for py-droplets

Source: https://py-droplets.readthedocs.io/en/latest/_sources/installation.rst.txt

Install these optional packages to enable all features of py-droplets. `h5py` is required for reading HDF files.

```bash
pip install h5py pyfftw
```

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

### Get Start, End, and Duration of DropletTrack

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplet_tracks.html

Provides properties to access the first time point (`start`), the last time point (`end`), and the total duration (`duration`) of a `DropletTrack`. Returns 0 for duration if the track is empty.

```python
@property
def start(self) -> float:
    """float: first time point"""
    return self.times[0]  # type: ignore

    @property
def end(self) -> float:
    """float: last time point"""
    return self.times[-1]  # type: ignore

    @property
def duration(self) -> float:
    """float: total duration of the track"""
    if len(self.times) > 0:
        return self.end - self.start
    return 0
```

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

### Create Empty Emulsion with Specific Droplet Type

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Creates an empty emulsion that will store droplets of a specific type. Pass an example droplet to define the expected type.

```python
empty_emulsion = Emulsion.empty(droplet_example)
```

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

### Create and Analyze Droplets

Source: https://py-droplets.readthedocs.io/en/latest/quickstart/examples.html

Demonstrates constructing and comparing basic droplet classes like SphericalDroplet and DiffuseDroplet, and analyzing their overlap within an Emulsion.

```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()
```

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

### Create EmulsionTimeCourse from File

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Creates an EmulsionTimeCourse by reading data from an HDF5 file. Assumes the file was written using the to_file method.

```python
import h5py

        obj = cls()
        with h5py.File(path, "r") as fp:
            # load the actual emulsion data and iterate in the right order
            for key in display_progress(
                sorted(fp.keys()), total=len(fp), enabled=progress
            ):
                dataset = fp[key]
                obj.append(
                    Emulsion._from_hdf_dataset(dataset), time=dataset.attrs["time"]
                )
        return obj
```

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

### Initialize DropletTracker

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Returns a DropletTracker instance for analyzing emulsions during simulations. Configurable with interrupt data and output filename.

```python
from .trackers import DropletTracker

        return DropletTracker(
            emulsion_timecourse=self, filename=filename, interrupts=interrupts
        )
```

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

### Initialize EmulsionTimeCourse

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Constructs an EmulsionTimeCourse object, optionally initializing it with existing emulsions and times. If times are not provided, they are generated sequentially.

```python
def __init__(
        self,
        emulsions: Iterable[Emulsion] | None = None,
        times: RealArray | Sequence[float] | None = None,
    ) -> None:
        """
        Args:
            emulsions (list): List of emulsions that describe this time course
            times (list): Times associated with the emulsions
        """
        if isinstance(emulsions, EmulsionTimeCourse):
            # extract data from given object; ignore `times`
            times = emulsions.times
            emulsions = emulsions.emulsions

        self.emulsions: list[Emulsion] = []
        self.times: list[float] = []

        # add all emulsions
        if emulsions is not None:
            for e in emulsions:
                self.append(Emulsion(e))

        # add all times
        if times is None:
            self.times = list(range(len(self.emulsions)))
        else:
            self.times = list(times)

        if len(self.times) != len(self.emulsions):
            msg = "Lists of emulsions and times must have same length"
            raise ValueError(msg)
```

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

### PerturbedDropletBase.amplitudes

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Gets or sets the perturbation amplitudes for the droplet.

```APIDOC
## PerturbedDropletBase.amplitudes

### Description
The perturbation amplitudes.

### Returns
:class:`~numpy.ndarray`: the perturbation amplitudes.
```

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

### PerturbedDropletBase.modes

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Gets the number of perturbation modes for the droplet.

```APIDOC
## PerturbedDropletBase.modes

### Description
Number of perturbation modes.

### Returns
int: number of perturbation modes
```

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

### EmulsionTimeCourse.from_file

Source: https://py-droplets.readthedocs.io/en/latest/packages/droplets.emulsions.html

Creates an EmulsionTimeCourse by reading data from an HDF5 file. Progress can be optionally displayed.

```APIDOC
## from_file

### 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()`.
- **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
```

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

### SphericalDroplet.bbox

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Property to get the bounding box of the droplet.

```APIDOC
## SphericalDroplet.bbox

### Description
Get the bounding box of the droplet.

### Method
`property`

### Returns
:class:`~pde.tools.cuboid.Cuboid`: bounding box of the droplet.
```

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

### SphericalDroplet.surface_area

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Property to get the surface area of the droplet.

```APIDOC
## SphericalDroplet.surface_area

### Description
Get the surface area of the droplet.

### Method
`property`

### Returns
float: surface area of the droplet
```

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

### PerturbedDropletBase.volume

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Abstract property to get the volume of the droplet. Setting this property is not implemented.

```APIDOC
## PerturbedDropletBase.volume

### Description
Volume of the droplet.

### Returns
float: The volume of the droplet.

### Raises
NotImplementedError: This property cannot be set.
```

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

### DropletTrackList.from_storage

Source: https://py-droplets.readthedocs.io/en/latest/packages/droplets.droplet_tracks.html

Creates a DropletTrackList from storage, with options for refinement and parallel processing.

```APIDOC
## DropletTrackList.from_storage

### Description
Creates a DropletTrackList from storage.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **storage**: The storage object to read from.
* **method** (str): The method used for tracking droplet identities. Possible methods are “overlap” and “distance”.
* **refine** (bool): Whether to refine the tracks.
* **num_processes** (int): The number of processes to use for parallel processing.
* **progress** (bool, optional): Whether to show progress.

### Returns
An instance describing the droplet track list.

### Return type
`DropletTrackList`
```

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

### SphericalDroplet.volume

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Property to get the volume of the droplet or set the radius based on a given volume.

```APIDOC
## SphericalDroplet.volume

### Description
Get the volume of the droplet or set the radius from a supplied volume.

### Method
`property`

### Returns
float: volume of the droplet

### Setter
*   **volume** (float): The new volume to set the droplet's radius from.
```

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

### Initialize DropletTracker

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/trackers.html

Initialize the DropletTracker to track droplets and determine their position, radii, and interfacial widths. `refine_args` can set flexible boundaries for droplet intensities.

```python
droplet_tracker = DropletTracker(
    1, refine=True, refine_args={"vmin": None, "vmax": None}
)
```

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

### volume (property)

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Gets or sets the volume of the droplet. When setting the volume, relative perturbations are maintained.

```APIDOC
## volume

### Description
Gets or sets the volume of the droplet. When setting the volume, relative perturbations are maintained.

### Type
float: volume of the droplet

### Setter
- **volume** (float): The new volume for the droplet.
```

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

### Initialize DropletTracker

Source: https://py-droplets.readthedocs.io/en/latest/packages/droplets.trackers.html

Initialize the `DropletTracker` to detect droplets and refine their coordinates. The `refine_args` parameter allows flexible boundary settings for droplet intensities.

```python
droplet_tracker = DropletTracker(
    1, refine=True, refine_args={"vmin": None, "vmax": None}
)

```

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

### Get Dtype for DiffuseDroplet

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Determines the structured dtype representing the DiffuseDroplet, including the interface width.

```python
dtype = super().get_dtype(**kwargs)
return [*dtype, ("interface_width", float)]
```

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

### Initialize Emulsion with Droplets

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Initializes an Emulsion object, optionally copying droplets and enforcing data type consistency. Use this to create an emulsion from an existing iterable of droplets.

```python
emulsion = Emulsion(droplets, copy=copy, force_consistency=force_consistency)
```

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

### Define Droplets with Different Classes

Source: https://py-droplets.readthedocs.io/en/latest/_sources/quickstart/examples.rst.txt

Demonstrates creating droplets using different classes, SphericalDroplet and DiffuseDroplet, and combining them into an emulsion for analysis.

```python
from droplets import droplets
from droplets.emulsions import Emulsion

# Create two droplets using different classes
droplet1 = droplets.SphericalDroplet(position=(0.1, 0.2), radius=0.05)
droplet2 = droplets.DiffuseDroplet(position=(0.3, 0.4), radius=0.07, interface_width=0.01)

# Combine droplets into an emulsion
emulsion = Emulsion([droplet1, droplet2])

# Further analysis can be performed on the emulsion object
```

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

### Get Emulsion at Specific Time

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Retrieves the emulsion data closest to a specified time point.

```python
idx = np.argmin(np.abs(np.asarray(self.times) - time))
        return self.emulsions[idx]
```

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

### Get Perturbation Amplitudes

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Retrieves the perturbation amplitudes as a numpy array. Ensures the output is at least 1-dimensional.

```python
@property
def amplitudes(self) -> RealArray:
        """ :class:`~numpy.ndarray`: the perturbation amplitudes."""
        return np.atleast_1d(self.data["amplitudes"])
```

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

### DropletTrackList.from_file

Source: https://py-droplets.readthedocs.io/en/latest/packages/droplets.droplet_tracks.html

Creates a DropletTrackList by reading data from an HDF5 file.

```APIDOC
## DropletTrackList.from_file

### Description
Create droplet track list by reading file. This function assumes the data was written using `to_file()`.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **path** (str): The path from which the data is read.
* **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`
```

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

### SphericalDroplet.__init__

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Initializes a SphericalDroplet with a given position and radius.

```APIDOC
## SphericalDroplet.__init__

### Description
Initializes a SphericalDroplet.

### Parameters
#### position (RealArray)
- **position**: Position of the droplet center.
#### radius (float)
- **radius**: Radius of the droplet.
```

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

### SphericalDroplet.radius

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Property to get or set the radius of the droplet. Setting the radius also checks the data validity.

```APIDOC
## SphericalDroplet.radius

### Description
Get or set the radius of the droplet.

### Method
`property`

### Returns
float: the radius of the droplet.

### Setter
*   **value** (float): The new radius for the droplet.
```

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

### SphericalDroplet.position

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Property to get or set the position of the droplet. The position must be a numpy array with the correct dimension.

```APIDOC
## SphericalDroplet.position

### Description
Get or set the position of the droplet.

### Method
`property`

### Returns
:class:`~numpy.ndarray`: the position of the droplet.

### Setter
*   **value** (RealArray): The new position for the droplet. Must have the same dimension as the droplet.
```

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

### Load Emulsion from File

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Class method to create an Emulsion by reading data from an HDF5 file. Assumes the file was written using the `to_file` method.

```python
import h5py

        with h5py.File(path, "r") as fp:
            if len(fp) != 1:
                msg = f"Multiple emulsions found in file `{path}`"
                raise RuntimeError(msg)

            # read the actual droplet data
            dataset = fp[next(iter(fp.keys()))]  # retrieve the only dataset
            obj = cls._from_hdf_dataset(dataset)

        return obj
```

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

### EmulsionTimeCourse.from_storage

Source: https://py-droplets.readthedocs.io/en/latest/packages/droplets.emulsions.html

Creates an EmulsionTimeCourse from stored phase field data. Supports optional refinement and parallel processing.

```APIDOC
## from_storage

### 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** - Additional keyword arguments are forwarded to the `locate_droplets()`.

### Returns
- an instance describing the emulsion time course

### Return type
EmulsionTimeCourse
```

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

### Get Droplet Space Dimension

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplet_tracks.html

Retrieves the spatial dimension of the droplets in the track. Returns None if the track is empty.

```python
def __init__(self):
    self.droplets = []
    self.times = []

@property
def dim(self) -> int | None:
    """Return the space dimension of the droplets."""
    try:
        return self.last.dim
    except IndexError:
        return None
```

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

### Get Droplet Volume

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Retrieves the volume of the droplet. The volume is calculated based on the droplet's radius and perturbation amplitudes.

```python
term = 1 + np.sum(self.amplitudes**2) / 2
return np.pi * self.radius**2 * term
```

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

### Create EmulsionTimeCourse from Frames

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Creates an EmulsionTimeCourse by processing frames. Uses multiprocessing for performance when multiple processes are specified.

```python
from concurrent.futures import ProcessPoolExecutor

        if num_processes == 1:
            # obtain the emulsion data for all frames in this process

            if progress is None:
                progress = refine  # show progress only when refining by default

            emulsions: Iterable[Emulsion] = (
                locate_droplets(frame, refine=refine, **kwargs)
                for frame in display_progress(storage, enabled=progress)
            )

        else:
            # use multiprocessing to obtain emulsion data
            from concurrent.futures import ProcessPoolExecutor

            _get_emulsion: Callable[[Emulsion], Emulsion] = functools.partial(
                locate_droplets, refine=refine, **kwargs
            )

            max_workers = None if num_processes == "auto" else num_processes
            with ProcessPoolExecutor(max_workers=max_workers) as executor:
                emulsions = list(executor.map(_get_emulsion, storage))

        return cls(emulsions, times=storage.times)
```

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

### Get Total Droplet Volume

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Calculates the sum of volumes of all droplets in the emulsion. This is a simple aggregation of individual droplet volumes.

```python
    @property
    def total_droplet_volume(self) -> float:
        """float: the total volume of all droplets"""
        return sum(droplet.volume for droplet in self)  # type: ignore
```

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

### Analyze Emulsion Images

Source: https://py-droplets.readthedocs.io/en/latest/quickstart/examples.html

Illustrates loading an image of an emulsion, locating droplets within the image using ScalarField and locate_droplets, and visualizing the detected droplets.

```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")
```

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

### Create EmulsionTimeCourse from Storage

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Loads an emulsion time course from a storage object, with options to refine droplet properties and control parallel processing and progress display.

```python
@classmethod
def from_storage(
        cls,
        storage: StorageBase,
        *,
        num_processes: int | Literal["auto"] = 1,
        refine: bool = False,
        progress: bool | None = None,
        **kwargs,
    ) -> EmulsionTimeCourse:
        r"""Create an emulsion time course from a stored phase field.

        Args:
            storage (:class:`~pde.storage.base.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 chosen 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

```

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

### Get Droplet Trajectory

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplet_tracks.html

Calculates and returns the time-evolution of a specified droplet attribute, such as position. Supports optional Gaussian smoothing.

```python
def get_trajectory(self, smoothing: float = 0, *, attribute: str = "position") -> RealArray:
    """Return a the time-evolution of a droplet attribute (e.g., the position)

    Args:
        smoothing (float):
            Determines the scale for some gaussian smoothing of the trajectory.
            The default value of zero disables smoothing.
        attribute (str):
            The attribute to consider (default: "position").

    Returns:
        :class:`~numpy.ndarray`: An array giving the position of the droplet at each
            time instance
    """
    trajectory = np.array([getattr(d, attribute) for d in self.droplets])
    if smoothing:
        ndimage.gaussian_filter1d(
            trajectory, output=trajectory, sigma=smoothing, axis=0, mode="nearest"
        )
    return trajectory
```

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

### Initialize LengthScaleTracker

Source: https://py-droplets.readthedocs.io/en/latest/packages/droplets.trackers.html

Initialize the `LengthScaleTracker` to store length scales measured during simulations. Specify the method for length scale determination and an optional filename for data storage.

```python
length_scale_tracker = LengthScaleTracker(
    method='structure_factor_mean', filename='length_scales.json'
)

```

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

### Get Number of Perturbation Modes

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Returns the number of perturbation modes for a perturbed droplet. Assumes amplitudes are stored in the data array.

```python
@property
def modes(self) -> int:
        """int: number of perturbation modes"""
        shape = self.data.dtype.fields["amplitudes"][0].shape  # type: ignore
        return int(shape[0]) if shape else 1
```

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

### DropletTracker Initialization

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/trackers.html

Initializes the DropletTracker with various parameters to control droplet detection and refinement.

```APIDOC
## DropletTracker

### Description
Initializes the droplet tracker with parameters for data handling, source extraction, and droplet refinement.

### Method
__init__

### Parameters
#### Arguments
- **interrupts** (InterruptData): Controls how the tracker handles simulation interruptions.
- **filename** (str, optional): Path to an HDF5 file for storing time course data.
- **emulsion_timecourse** (EmulsionTimeCourse, optional): An existing EmulsionTimeCourse instance to store data. If omitted, a new one is created.
- **source** (int or callable, optional): Determines how a field is extracted from `fields`. If `None`, `fields` is passed as is. Can be an integer for `FieldCollection` or a function.
- **threshold** (float or str): The threshold for binarizing the image. Supported values include floats, 'extrema', 'mean', 'otsu', and 'auto' (defaults to 'extrema').
- **minimal_radius** (float): Minimal radius of droplets to be retained.
- **refine** (bool): Flag to refine droplet coordinates using fitting. This can be a slow procedure.
- **refine_args** (dict, optional): Additional keyword arguments passed to `refine_droplet` when `refine=True`.
- **perturbation_modes** (int): Number of perturbation modes to consider when refining droplets. Only relevant if `refine=True`.

### Example
```python
droplet_tracker = DropletTracker(
    1, refine=True, refine_args={"vmin": None, "vmax": None}
)
```
```

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

### Get Data Bounds for DiffuseDroplet

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Returns the lower and upper bounds for the droplet's data, ensuring the interface width is non-negative.

```python
l, h = super().data_bounds
l[self.dim + 1] = 0  # interface width must be non-negative
return l, h
```

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

### Get Droplet Triangulation (3D)

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Obtains a triangulated shape of the droplet surface in 3D. Returns vertices and triangles defining the triangulation.

```python
if self.dim == 3:
            # estimate the number of triangles covering the surface
            try:
                surface_area = self.surface_area
            except (NotImplementedError, AttributeError):
                # estimate surface area from 3d spherical droplet
                surface_area = spherical.surface_from_radius(self.radius, dim=3)
            num_est = (4 * surface_area) / (np.sqrt(3) * resolution**2)
            tri = triangulated_spheres.get_triangulation(num_est)

            φ, θ = tri["angles"][:, 0], tri["angles"][:, 1]
            return {
                "vertices": self.interface_position(θ, φ),
                "triangles": tri["cells"],
            }
```

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

### Emulsion.from_file

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Creates an emulsion by reading data from an HDF5 file. The file is expected to have been written using the `to_file` method.

```APIDOC
## from_file

### Description
Create emulsion by reading file.

Args:
    path (str):
        The path from which the data is read. This function assumes that the
        data was written as an HDF5 file using :meth:`to_file`.

Returns:
    :class:`Emulsion`: The emulsion read from the file

```

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

### Emulsion Class Methods

Source: https://py-droplets.readthedocs.io/en/latest/packages/droplets.emulsions.html

Class methods for creating and initializing Emulsion objects.

```APIDOC
## Emulsion Class Methods

### empty(droplet)
Create empty emulsion with particular droplet type.

Parameters:
* **droplet** (SphericalDroplet) - An example for a droplet, which defines the type of emulsion.

Returns: The empty emulsion.

Return type: Emulsion

### from_file(path)
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

### from_random(num, grid_or_bounds, radius, *, remove_overlapping=True, droplet_class=<class 'droplets.droplets.SphericalDroplet'>, rng=None)
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) - 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 Droplet Triangulation (2D)

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Obtains a triangulated shape of the droplet surface in 2D. Returns vertices and lines defining the triangulation.

```python
if self.dim == 2:
            num = max(3, int(np.ceil(self.surface_area / resolution)))
            angles = np.linspace(0, 2 * np.pi, num + 1, endpoint=True)
            vertices = self.interface_position(angles)
            lines = np.c_[np.arange(num), np.arange(1, num + 1) % num]
            return {"vertices": vertices, "lines": lines}
```

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

### Load Droplet Tracks from File

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplet_tracks.html

Loads droplet track data from an HDF5 file. Requires the `h5py` library. Progress can be displayed during loading.

```python
import h5py

obj = cls()
with h5py.File(path, "r") as fp:
    # load the actual droplet track data and iterate in the right order
    for key in display_progress(
        sorted(fp.keys()), total=len(fp), enabled=progress
    ):
        dataset = fp[key]
        obj.append(DropletTrack._from_hdf_dataset(dataset))
return obj
```

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

### Get Linked Droplet Data

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Retrieves all droplet data as a single NumPy array. Modifications to this array are reflected in the individual droplets.

```python
data = self.data  # create an array with all the droplet data
        # link back to droplets
        for i, d in enumerate(self):
            d.data = data[i]
        return data
```

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

### Get Droplet Volumes Over Time

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplet_tracks.html

Returns an array of droplet volumes for each time point in the track. Supports optional Gaussian smoothing.

```python
def get_volumes(self, smoothing: float = 0) -> RealArray:
    """ :class:`~numpy.ndarray`: returns the droplet volume for each time point.

    Args:
        smoothing (float):
            Determines the volume scale for some gaussian smoothing of the
            trajectory. The default value of zero disables smoothing.
    """
    return self.get_trajectory(smoothing, attribute="volume")
```

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

### EmulsionTimeCourse Initialization

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Initializes an EmulsionTimeCourse object, which represents emulsions as a function of time. It can be initialized with a list of emulsions and their corresponding times, or by copying an existing EmulsionTimeCourse object.

```APIDOC
## EmulsionTimeCourse.__init__

### Description
Initializes an `EmulsionTimeCourse` object.

### Parameters
* `emulsions` (Iterable[Emulsion] | None): List of emulsions that describe this time course.
* `times` (RealArray | Sequence[float] | None): Times associated with the emulsions.

### Example
```python
from droplets import Emulsion, EmulsionTimeCourse

emulsion1 = Emulsion(...)
emulsion2 = Emulsion(...)
times = [0.0, 1.0]
time_course = EmulsionTimeCourse(emulsions=[emulsion1, emulsion2], times=times)
```
```

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

### DropletTrack.from_file

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplet_tracks.html

Creates a DropletTrack object by reading data from an HDF5 file.

```APIDOC
## DropletTrack.from_file

### Description
Creates droplet track by reading from file.

### Method
classmethod

### 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 :meth:`to_file`.
```

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

### Get Droplet Radii Over Time

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplet_tracks.html

Returns an array of droplet radii for each time point in the track. Supports optional Gaussian smoothing.

```python
def get_radii(self, smoothing: float = 0) -> RealArray:
    """ :class:`~numpy.ndarray`: returns the droplet radius for each time point.

    Args:
        smoothing (float):
            Determines the length scale for some gaussian smoothing of the
            trajectory. The default value of zero disables smoothing.
    """
    return self.get_trajectory(smoothing, attribute="radius")
```

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

### Get Dimensionality of DropletTrack

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplet_tracks.html

A property to retrieve the dimensionality of the droplets within the track. Returns `None` if the track is empty or dimensionality cannot be determined.

```python
@property
def dim(self) -> int | None:
    
```

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

### handle

Source: https://py-droplets.readthedocs.io/en/latest/packages/droplets.trackers.html

Handles data supplied to this tracker during the simulation.

```APIDOC
## handle

### Description
Handle data supplied to this tracker.

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

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

### Initialize LengthScaleTracker

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/trackers.html

Initializes the `LengthScaleTracker` with options for data storage and length scale calculation methods. The `source` parameter can specify how to extract a scalar field from simulation data.

```python
LengthScaleTracker(
    interrupts=1,
    filename=None,
    method="structure_factor_mean",
    source=None,
    verbose=False,
)
```

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

### Get Droplet Position at Time

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplet_tracks.html

Retrieves the position of a droplet at a specific time point. Handles both list and NumPy array for time indexing.

```python
def get_position(self, time: float) -> RealArray:
    """ :class:`~numpy.ndarray`: returns the droplet position at a specific time."""
    try:
        idx = self.times.index(time)
    except AttributeError:
        # assume that self.times is a numpy array
        idx = np.nonzero(self.times == time)[0][0]
    return self.droplets[idx].position  # type: ignore
```

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

### DropletTrackList Initialization

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplet_tracks.html

Customizes the behavior of a list of DropletTrack objects, ensuring that slicing operations return a DropletTrackList instance.

```python
class DropletTrackList(list):
    """A list of instances of :class:`DropletTrack`"""

    def __getitem__(self, key: int | slice):  # type: ignore
        """Return the droplets identified by the given index/slice."""
        result = super().__getitem__(key)
        if isinstance(key, slice):
            return self.__class__(result)
        return result
```

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

### Get Unstructured Data Array

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Returns the droplet's data as an unstructured NumPy array. This is useful for operations that require a flat array representation.

```python
@property
def _data_array(self) -> RealArray:
        """:class:`~numpy.ndarray`: the data of the droplet in an unstructured array."""
        return structured_to_unstructured(self.data)
```

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

### items

Source: https://py-droplets.readthedocs.io/en/latest/packages/droplets.emulsions.html

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

```APIDOC
## items()

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

### Returns
- Iterator[tuple[float, Emulsion]] - An iterator yielding pairs of time (float) and Emulsion objects.
```

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

### Get Triangulation of a Sphere

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Retrieves a triangulation of a sphere based on the approximate number of vertices. Loads data if not already loaded and finds the closest matching triangulation.

```python
def get_triangulation(self, num_est: int = 1) -> dict[str, Any]:
        """Get a triangulation of a sphere.

        Args:
            num_est (int): The rough number of vertices in the triangulation

        Returns:
            dict: A dictionary with information about the triangulation
        """
        if self.data is None:
            self._load()

        index = np.argmin((self.num_list - num_est) ** 2)
        return self.data[self.num_list[index]]  # type: ignore
```

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

### Get dtype field size

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Calculates the number of elements in a specific field of a structured NumPy array. Useful for understanding the memory layout of droplet data.

```python
def get_dtype_field_size(dtype: DTypeLike, field_name: str) -> int:
    """Return the number of elements in a field of structured numpy array.

    Args:
        dtype (list):
            The dtype of the numpy array
        field_name (str):
            The name of the field that needs to be checkedrm
    """
    shape = dtype.fields[field_name][0].shape  # type: ignore
    return np.prod(shape) if shape else 1  # type: ignore
```

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

### Initialize Triangulated Spheres

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Initializes the _TriangulatedSpheres class. This typically involves loading or preparing data structures for triangulations.

```python
triangulated_spheres = _TriangulatedSpheres()
```

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

### Plot Emulsion Visualization

Source: https://py-droplets.readthedocs.io/en/latest/_sources/quickstart/examples.rst.txt

Shows how to visualize an emulsion using the plot method. The emulsion can optionally track the space it occupies, such as a simulation grid.

```python
from droplets import droplets
from droplets.emulsions import Emulsion
from pde.grids.cartesian import CartesianGrid

# Example: Define droplets and an emulsion
droplet1 = droplets.SphericalDroplet(position=(0.1, 0.2), radius=0.05)
droplet2 = droplets.DiffuseDroplet(position=(0.3, 0.4), radius=0.07, interface_width=0.01)
emulsion = Emulsion([droplet1, droplet2])

# Example: Define a grid for the emulsion
grid = CartesianGrid([[0, 1], [0, 1]], spacing=0.01)
emulsion_with_grid = Emulsion([droplet1, droplet2], grid=grid)

# Plot the emulsion (without grid for simplicity in this example)
emulsion.plot()
```

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

### Get Bounding Box of Emulsion

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/emulsions.html

Calculates the bounding box of the entire emulsion by summing the bounding boxes of individual droplets. Raises a RuntimeError if the emulsion is empty.

```python
if len(self) == 0:
    msg = "Bounding box of empty emulsion is undefined"
    raise RuntimeError(msg)
return sum((droplet.bbox for droplet in self[1:]), self[0].bbox)
```

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

### DropletBase.__str__ and __repr__

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Provides a string representation of the droplet instance, showing its class name and data arguments.

```APIDOC
## DropletBase.__str__ and __repr__

### Description
Returns a string representation of the droplet instance.

### Returns
- **str**: A string representing the droplet, e.g., "ClassName(arg1=value1, arg2=value2)".
```

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

### Get Matplotlib Patch for Droplet

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Generates a matplotlib patch representing the droplet for plotting. Additional keyword arguments can be passed to customize the patch, such as `fill=False` to draw only the outline.

```python
import matplotlib as mpl

if dim is None:
    dim = self.dim

if dim != 2:
    msg = "Plotting is only implemented in 2d"
    raise NotImplementedError(msg)

φ = np.linspace(0, 2 * np.pi, endpoint=False)
xy = self.interface_position(φ)
return mpl.patches.Polygon(xy, closed=True, **kwargs)
```

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

### Get Droplet Track Data

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplet_tracks.html

Returns an NumPy array containing the data for the entire track, including time and droplet properties. Returns None if the track is empty.

```python
@property
def data(self) -> RealArray | None:
    """ :class:`~numpy.ndarray`: an array containing the data of the full track."""
    if len(self) == 0:
        return None
    d0 = self.first
    dtype = [("time", "f8"), *d0.data.dtype.descr]
    result = np.empty(len(self), dtype=dtype)
    for i in range(len(self)):
        result[i] = (self.times[i], *self.droplets[i].data.tolist())
    return result
```

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

### DropletTrackList.from_emulsion_time_course

Source: https://py-droplets.readthedocs.io/en/latest/packages/droplets.droplet_tracks.html

Creates a DropletTrackList from an emulsion time course using a specified tracking method.

```APIDOC
## DropletTrackList.from_emulsion_time_course

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

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **time_course** (`droplets.emulsions.EmulsionTimeCourse`): A collection of temporally arranged emulsions.
* **method** (str): The method used for tracking droplet identities. Possible methods are “overlap” and “distance”.
* **grid** (`GridBase`, optional): The grid on which the droplets are defined, necessary for periodic boundary conditions.
* **progress** (bool): Whether to show the progress of the process.
* **kwargs**: Additional parameters for the tracking algorithm (e.g., `max_dist` for the “distance” method).

### Returns
The resulting droplet tracks.

### Return type
`DropletTrackList`
```

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

### Plotting Emulsions

Source: https://py-droplets.readthedocs.io/en/latest/quickstart/examples.html

Shows how to create multiple random droplets, combine them into an emulsion, remove overlapping droplets, and visualize the result using the plot() method.

```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()
```

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

### Get Droplet Data Bounds

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Retrieves the lower and upper bounds for the droplet's parameters, specifically adjusting the bounds for relative perturbation amplitudes to be within [-1, 1].

```python
@property
def data_bounds(self) -> tuple[RealArray, RealArray]:
        """tuple: lower and upper bounds on the parameters"""
        l, h = super().data_bounds
        n = self.dim + 2
        # relative perturbation amplitudes must be between [-1, 1]
        l[n : n + self.modes] = -1
        h[n : n + self.modes] = 1
        return l, h
```

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

### DropletTrackList.from_file

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplet_tracks.html

Loads droplet track data from an HDF5 file. It can optionally display progress during loading.

```APIDOC
## DropletTrackList.from_file

### Description
Loads droplet track data from an HDF5 file. It can optionally display progress during loading.

### Method
classmethod

### Parameters
#### Path Parameters
- **path** (str) - Required - The path to the HDF5 file.
- **progress** (bool) - Optional - Whether to show a progress bar during loading. Defaults to True.

### Returns
- **DropletTrackList** - An instance describing the droplet track list.
```

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

### Get Droplet Phase Field Data

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplets.html

Creates an array representing the droplet phase field on a given grid. The data is scaled between vmin and vmax. Returns a ScalarField object.

```python
def get_phase_field(
        self,
        grid: GridBase,
        *,
        vmin: float = 0,
        vmax: float = 1,
        label: str | None = None,
    ) -> ScalarField:
        """Creates an image of the droplet on the `grid`

        Args:
            grid (:class:`~pde.grids.base.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:
            :class:`~pde.fields.ScalarField`: A scalar field
            representing the droplet
        """
        data = self._get_phase_field(grid)
        data = vmin + (vmax - vmin) * data  # scale data
        return ScalarField(grid, data=data, label=label)
```

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

### Handle Simulation Field Data

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/trackers.html

The `handle` method processes the current simulation field to extract scalar data, locate droplets using a specified threshold, and optionally refine their coordinates.

```python
from pde.visualization.plotting import extract_field

from .image_analysis import locate_droplets

# extract scalar field
scalar_field = extract_field(field, self.source, 0)
if not isinstance(scalar_field, ScalarField):
    self._logger.exception(
        "Field needs to be a scalar field. Use `source` parameter to select a " 
        "specific field of a FieldCollection."
    )

# locate droplets in scalar field
emulsion = locate_droplets(
    scalar_field,  # type: ignore
    threshold=self.threshold,
    refine=self.refine,

```

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

### Get First and Last Droplet in Track

Source: https://py-droplets.readthedocs.io/en/latest/_modules/droplets/droplet_tracks.html

Provides properties to access the first (`first`) and last (`last`) `SphericalDroplet` objects recorded in a `DropletTrack`. Raises an `IndexError` if the track is empty.

```python
@property
def first(self) -> SphericalDroplet:
    """SphericalDroplet: first droplet instance"""
    return self.droplets[0]  # type: ignore

    @property
def last(self) -> SphericalDroplet:
    """SphericalDroplet: last droplet instance"""
    return self.droplets[-1]  # type: ignore
```
Tokens:
Raw