emulsim 0.5.0__py3-none-any.whl

emulsim/__init__.py

@@ -0,0 +1,32 @@
+r"""The `emulsim` package provides classes for describing physical system that consists of
+multiple `elements`, which together describe the state of the system.
+
+The dynamical
+rules are encoded in `actors`, which either act on individual elements, encoding their
+autonomous dynamics, or on multiple elements, introducing couplings.
+"""
+
+# determine the package version
+try:
+    # try reading version from the automatically generated module
+    from ._version import __version__  # type: ignore
+except ImportError:
+    # determine version automatically from CVS information
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        __version__ = version("emulsim")
+    except PackageNotFoundError:
+        # package is not installed, so we cannot determine any version
+        __version__ = "unknown"
+    del PackageNotFoundError, version  # clean name space
+
+# make key classes from modelrunner available
+from modelrunner import Parameter
+
+# import key classes from emulsim package into general namespace
+from .actors import *
+from .elements import *
+from .simulation import Simulation
+from .state import State
+from .trackers import *

emulsim/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
+
+__commit_id__ = commit_id = None

emulsim/actors/__init__.py

@@ -0,0 +1,59 @@
+"""Provides actors that determine the dynamics of the simulation by modifying the state
+of elements during each time step. Actors are separated into several categories, which
+we describe separately below.
+
+**General actors** are classes that provide basic infrastructure to implement custom
+implementations:
+
+.. autosummary::
+   :nosignatures:
+
+
+   ~base.ActorBase
+   ~function.FunctionActor
+   ~function.NumbaFunctionActor
+
+
+**Autonomous actors** only affect a single element and thus describe the autonomous
+dynamics of this element when it is not coupled to other elements.
+
+.. autosummary::
+   :nosignatures:
+
+   ~autonomous.active_particles.ActiveParticleActor
+   ~autonomous.box.BoxActor
+   ~autonomous.brownian_motion.BrownianMotionActor
+   ~autonomous.coalescence.CoalescenceDropletActor
+   ~autonomous.emitters.EmittersActor
+   ~autonomous.fields.LocalReactionsActor
+   ~autonomous.fields.ScalarPDEActor
+   ~autonomous.fields.DiffusionActor
+   ~autonomous.fields.ReactionDiffusionActor
+   ~autonomous.fields.CollectionPDEActor
+
+
+**Coupling actors** affect several elements and thus describe a coupling between these
+elements.
+
+.. autosummary::
+   :nosignatures:
+
+   ~coupling.nucleation.DropletNucleationActor
+   ~coupling.fields.FieldCouplingActor
+   ~coupling.fields.FieldExchangeActor
+   ~coupling.fields.FieldBoundaryExchangeActor
+   ~coupling.point_droplet.PointDropletActor
+   ~coupling.spherical_droplet.SphericalDropletActor
+   ~coupling.multicomponent_droplet.MulticomponentDropletActor
+
+
+Use :func:`~base.find_actors` to discover actors that are compatible with a given list
+of elements.
+
+.. codeauthor:: David Zwicker <david.zwicker@ds.mpg.de>
+"""
+
+from .autonomous import *
+from .base import ActorBase, find_actors
+from .coupling import *
+from .function import FunctionActor, NumbaFunctionActor

emulsim/actors/autonomous/__init__.py

@@ -0,0 +1,31 @@
+"""Provides actors that affect single elements in a simulation.
+
+.. autosummary::
+   :nosignatures:
+
+   ~active_particles.ActiveParticleActor
+   ~box.BoxActor
+   ~brownian_motion.BrownianMotionActor
+   ~coalescence.CoalescenceDropletActor
+   ~emitters.EmittersActor
+   ~fields.LocalReactionsActor
+   ~fields.ScalarPDEActor
+   ~fields.DiffusionActor
+   ~fields.ReactionDiffusionActor
+   ~fields.CollectionPDEActor
+
+.. codeauthor:: David Zwicker <david.zwicker@ds.mpg.de>
+"""
+
+from .active_particles import ActiveParticleActor
+from .box import BoxActor
+from .brownian_motion import BrownianMotionActor
+from .coalescence import CoalescenceDropletActor
+from .emitters import EmittersActor
+from .fields import (
+    CollectionPDEActor,
+    DiffusionActor,
+    LocalReactionsActor,
+    ReactionDiffusionActor,
+    ScalarPDEActor,
+)

emulsim/actors/autonomous/active_particles.py

@@ -0,0 +1,128 @@
+"""
+.. codeauthor:: David Zwicker <david.zwicker@ds.mpg.de>
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numba as nb
+import numpy as np
+
+from pde.backends.numba.utils import jit
+
+from ... import Parameter
+from ...elements import ArrowsElement
+from ..base import ActorBase, ElementsType
+
+
+class ActiveParticleActor(ActorBase):
+    """Actor moving arrows according to their direction."""
+
+    parameters_default = [
+        Parameter(
+            "rotational_diffusion", 0.0, float, "The rotational diffusion strength"
+        )
+    ]
+
+    element_classes = (ArrowsElement,)
+
+    def estimate_dt(self, elements: ElementsType) -> float:
+        """Estimate the maximal time step for simulating this actor.
+
+        Args:
+            elements (tuple of :class:`~emulsim.elements.points.ArrowsElement`):
+                The element that is affected by the directed motion
+
+        Returns:
+            float: the maximal time step
+        """
+        return float("inf")
+
+    def make_evolver_numba(  # type: ignore
+        self, elements: ElementsType
+    ) -> Callable[[tuple[np.ndarray], float, float], None]:
+        """Return a function evolve the field state from time `t` to `t + dt`
+
+        Args:
+            elements (tuple of :class:`~emulsim.elements.points.ArrowsElement`):
+                The element that is affected by the directed motion
+
+        Returns:
+            callable: A function with signature
+                (state_data: :class:`~numpy.ndarray`, t: float, dt: float),
+                evolving `state_data`
+        """
+        dim = int(elements[0].dim)  # type: ignore
+
+        rot_diff = float(self.parameters["rotational_diffusion"])
+        if rot_diff > 0 and dim > 2:
+            raise NotImplementedError
+
+        @jit
+        def evolver(state_data: tuple[np.ndarray], t: float, dt: float) -> None:
+            """Evolve all points explicitly."""
+            points = state_data[0]
+
+            for i in nb.prange(len(state_data[0])):
+                # update the position
+                for j in range(dim):
+                    points[i].position[j] += dt * points[i].direction[j]
+
+                # apply rotational diffusion if requested
+                if rot_diff > 0:
+                    if dim == 1:
+                        # interpret rot_diff as rate of flipping
+                        if np.random.rand() < dt * rot_diff:
+                            points[i].direction[:] *= -1.0
+
+                    elif dim == 2:
+                        # rotate by angle chosen from normal distribution
+                        φ = np.random.normal(0, dt * rot_diff)
+                        cosφ, sinφ = np.cos(φ), np.sin(φ)
+                        dx, dy = points[i].direction
+                        points[i].direction[0] = cosφ * dx - sinφ * dy
+                        points[i].direction[1] = sinφ * dx + cosφ * dy
+
+                    else:
+                        # higher dimensions are not currently supported
+                        raise NotImplementedError
+
+        return evolver  # type: ignore
+
+    def evolve(self, elements: ElementsType, t: float, dt: float) -> None:
+        """Evolve the field state from time `t` to `t + dt`
+
+        Args:
+            elements (tuple of :class:`~emulsim.elements.points.ArrowsElement`):
+                The element that is affected by the directed motion
+            t (float):
+                The current time point
+            dt (float):
+                The time step
+        """
+        (points,) = elements  # extract single element
+
+        # update the position
+        points.positions += dt * points.directions  # type: ignore
+
+        # apply rotational diffusion if requested
+        rot_diff = self.parameters["rotational_diffusion"]
+        if rot_diff > 0:
+            if points.dim == 1:
+                # interpret rot_diff as rate of flipping
+                flip = np.random.rand(len(points.data)) < dt * rot_diff
+                points.directions[flip] *= -1  # type: ignore
+
+            elif points.dim == 2:
+                # rotate by angle chosen from normal distribution
+                φ = np.random.normal(0, dt * rot_diff, size=len(points.data))
+                rot_mat = np.array([[np.cos(φ), -np.sin(φ)], [np.sin(φ), np.cos(φ)]])
+                new_direction = np.einsum("pi,ijp->pj", points.directions, rot_mat)  # type: ignore
+                points.directions[:] = new_direction  # type: ignore
+
+            else:
+                raise NotImplementedError(
+                    "Rotational diffusion is not implemented for points with "
+                    f"{points.dim} dimensions."
+                )

emulsim/actors/autonomous/box.py

@@ -0,0 +1,177 @@
+"""
+.. codeauthor:: David Zwicker <david.zwicker@ds.mpg.de>
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+
+from pde.backends.numba.utils import jit
+from pde.grids.cartesian import CartesianGrid
+
+from ... import Parameter
+from ...elements import ArrowsElement, PointsElement, SphericalDropletsElement
+from ..base import ActorBase, ElementsType
+
+
+class BoxActor(ActorBase):
+    """Actor containing particles in a box."""
+
+    parameters_default = [
+        Parameter("bounds", [], np.array, "The bounds of the box"),
+        Parameter("periodic", False, np.array, "The bounds of the box"),
+        Parameter(
+            "point_like",
+            True,
+            bool,
+            "When False, the radius of the object is used in the distance calculation",
+        ),
+    ]
+
+    element_classes = ((PointsElement, ArrowsElement, SphericalDropletsElement),)
+
+    def __init__(self, parameters: dict[str, Any] | None = None):
+        """
+        Args:
+            parameters (dict):
+                Parameters affecting the actor. Call
+                :meth:`~BoxActor.show_parameters` for details.
+        """
+        super().__init__(parameters=parameters)
+
+        # convert periodicity information into useful format
+        periodic = self.parameters["periodic"]
+        if isinstance(periodic, np.ndarray) and periodic.size == 1:
+            periodic = periodic.item()
+
+        self._grid = CartesianGrid(self.parameters["bounds"], 1, periodic)
+
+    @classmethod
+    def from_grid(cls, grid: CartesianGrid):
+        """Create BoxActor from a Cartesian grid.
+
+        Args:
+            grid (:class:`pde.grids.cartesian.CartesianGrid`):
+                The Cartesian grid that defines the box
+        """
+        return cls({"bounds": grid.axes_bounds, "periodic": grid.periodic})
+
+    def estimate_dt(self, elements: ElementsType) -> float:
+        """Estimate the maximal time step for simulating this actor.
+
+        Args:
+            elements (tuple of :class:`~emulsim.elements.points.PointsElement`):
+                The element that is affected by the directed motion
+
+        Returns:
+            float: the maximal time step
+        """
+        return float("inf")
+
+    def make_evolver_numba(  # type: ignore
+        self, elements: ElementsType
+    ) -> Callable[[tuple[np.ndarray], float, float], None]:
+        """Return a function evolve the field state from time `t` to `t + dt`
+
+        Args:
+            elements (tuple of :class:`~emulsim.elements.points.PointsElement`):
+                The element that is affected by this actor
+
+        Returns:
+            callable: A function with signature
+                (state_data: :class:`~numpy.ndarray`, t: float, dt: float),
+                evolving `state_data`
+        """
+        (points_element,) = elements  # extract single element
+
+        num_points = len(points_element.data)
+        num_axes = self._grid.num_axes
+        periodic = np.array(self._grid.periodic)  # using a tuple led to a numba error
+        bounds = np.array(self._grid.axes_bounds)
+        midpoint = self._grid.cuboid.centroid
+        xmin = bounds[:, 0]
+        xmax = bounds[:, 1]
+        size = bounds[:, 1] - bounds[:, 0]
+
+        # figure out which axes need to be considered for flipping direction
+        if "direction" in points_element.data.dtype.fields:
+            flip_ax: np.ndarray = np.flatnonzero(np.logical_not(self._grid.periodic))
+        else:
+            flip_ax = np.empty((0,))
+        test_for_flipping = flip_ax.size > 0
+
+        point_like = self.parameters["point_like"]
+
+        @jit
+        def evolver(state_data: tuple[np.ndarray], t: float, dt: float) -> None:
+            """Evolve all points explicitly."""
+            points = state_data[0]  # data of the points
+            for i in range(num_points):
+                pos = points[i].position
+
+                if point_like:
+                    radius = 0
+                else:
+                    radius = points[i].radius
+
+                # flip direction if out of bound
+                if test_for_flipping:
+                    for ax in flip_ax:
+                        dist_norm = (pos[ax] - midpoint[ax]) / (size[ax] - 2 * radius)
+                        if (dist_norm - 0.5) % 2 - 1 < 0:
+                            points[i].direction[ax] *= -1
+                # TODO: this function's performance could be improved by calculating
+                # the distance only once
+
+                # move the points to inside the box
+                for ax in range(num_axes):
+                    if periodic[ax]:
+                        pos[ax] = (pos[ax] - xmin[ax]) % size[ax] + xmin[ax]
+                    else:
+                        dist_left = pos[ax] - (xmax[ax] - radius)
+                        size_red = size[ax] - 2 * radius
+                        arg = (dist_left) % (2 * size_red) - size_red
+                        pos[ax] = xmin[ax] + radius + abs(arg)
+
+        return evolver  # type: ignore
+
+    def evolve(self, elements: ElementsType, t: float, dt: float) -> None:
+        """Evolve the field state from time `t` to `t + dt`
+
+        Args:
+            elements (tuple of :class:`~emulsim.elements.points.PointsElement`):
+                The element that is affected by this actor
+            t (float):
+                The current time point
+            dt (float):
+                The time step
+        """
+        if not self.parameters["point_like"]:
+            raise NotImplementedError("numpy backend can only deal with point-objects")
+
+        (points,) = elements  # extract single element
+
+        if "direction" in points.data.dtype.fields:
+            # flip direction if out of bound
+            midpoint = self._grid.cuboid.centroid
+            size = np.array(self._grid.cuboid.size)
+            if not self.parameters["point_like"]:
+                size = size[:, np.newaxis] - 2 * points.radius[np.newaxis, :]  # type: ignore
+
+            for ax in range(points.dim):  # type: ignore
+                if self._grid.periodic[ax]:
+                    continue  # do nothing for periodic axes
+                dist_norm = (points.positions[..., ax] - midpoint[ax]) / size[ax]  # type: ignore
+                factor = np.sign((dist_norm - 0.5) % 2 - 1)
+                factor[factor == 0] = 1  # don't flip corner cases
+                points.directions[..., ax] *= factor  # type: ignore
+
+        # move the points to inside the box
+        # TODO: support extended objects, where `point_like` is False
+        points.positions[...] = self._grid.normalize_point(  # type: ignore
+            points.positions,  # type: ignore
+            reflect=True,
+        )

emulsim/actors/autonomous/brownian_motion.py

@@ -0,0 +1,135 @@
+"""
+.. codeauthor:: David Zwicker <david.zwicker@ds.mpg.de>
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+
+from pde.backends.numba.utils import jit
+from pde.tools.expressions import ScalarExpression
+
+from ... import Parameter
+from ...elements import ArrowsElement, PointsElement, SphericalDropletsElement
+from ..base import ActorBase, ElementsType
+
+
+class BrownianMotionActor(ActorBase):
+    """Actor moving objects according to Brownian motion."""
+
+    parameters_default = [
+        Parameter(
+            "diffusivity",
+            "1",
+            str,
+            "Expression that determines the strength of the Brownian motion of "
+            "droplets. The expression may depend on time and potentially on a radius "
+            "if this is defined for the element on which the actor acts",
+        ),
+    ]
+
+    element_classes = ((ArrowsElement, PointsElement, SphericalDropletsElement),)
+
+    def estimate_dt(self, elements: ElementsType) -> float:
+        """Estimate the maximal time step for simulating this actor.
+
+        Args:
+            elements (tuple of :class:`~emulsim.elements.droplets.SphericalDropletsElement`):
+                The element that is affected by the Brownian motion
+
+        Returns:
+            float: the maximal time step
+        """
+        return float("inf")
+
+    def _update_cache(self, elements: ElementsType) -> None:
+        """Prepare the simulation doing pre-calculations.
+
+        Args:
+            elements (tuple):
+                The state of all the droplets and of the field
+        """
+        fields = elements[0].data.dtype.fields
+        if "position" not in fields:
+            raise ValueError("Could not find field `positions` in element data")
+        self._cache["has_radius"] = "radius" in fields
+        if self._cache["has_radius"]:
+            self._cache["diffusivity"] = ScalarExpression(
+                self.parameters["diffusivity"], [["radius", "R"], ["time", "t"]]
+            )
+        else:
+            self._cache["diffusivity"] = ScalarExpression(
+                self.parameters["diffusivity"], [["time", "t"]]
+            )
+
+    def make_evolver_numba(  # type: ignore
+        self, elements: ElementsType
+    ) -> Callable[[tuple[np.ndarray], float, float], None]:
+        """Return a function evolve the field state from time `t` to `t + dt`
+
+        Args:
+            elements (tuple of :class:`~emulsim.elements.droplets.SphericalDropletsElement`):
+                The field element that is affected by the Brownian motion
+
+        Returns:
+            callable: A function with signature
+                (state_data: :class:`~numpy.ndarray`, t: float, dt: float),
+                evolving `state_data`
+        """
+        self._check_cache(elements)
+        diffusivity = self._cache["diffusivity"].get_function(backend="numba")
+        dim = int(elements[0].dim)  # type: ignore
+
+        if self._cache["has_radius"]:
+
+            @jit
+            def evolver(state_data: tuple[np.ndarray], t: float, dt: float):
+                """Evolve all points explicitly."""
+                (droplets_data,) = state_data
+                for droplet_data in droplets_data:
+                    if droplet_data.radius > 0:
+                        scale = np.sqrt(dt * diffusivity(droplet_data.radius, t))
+                        for i in range(dim):
+                            droplet_data.position[i] += scale * np.random.randn()
+
+        else:
+
+            @jit
+            def evolver(state_data: tuple[np.ndarray], t: float, dt: float):
+                """Evolve all points explicitly."""
+                (droplets_data,) = state_data
+                scale = np.sqrt(dt * diffusivity(t))
+                for droplet_data in droplets_data:
+                    for i in range(dim):
+                        droplet_data.position[i] += scale * np.random.randn()
+
+        return evolver  # type: ignore
+
+    def evolve(self, elements: ElementsType, t: float, dt: float) -> None:
+        """Evolve the state from time `t` to `t + dt`
+
+        Args:
+            elements (tuple of :class:`~emulsim.elements.droplets.SphericalDropletsElement`):
+                The element that is affected by the Brownian motion
+            t (float):
+                The current time point
+            dt (float):
+                The time step
+        """
+        self._check_cache(elements)
+        (objs,) = elements  # extract single element
+        diffusivity = self._cache["diffusivity"]
+        dim = objs.dim
+        if dim is None:
+            raise ValueError("`dim` must not be None")
+
+        if self._cache["has_radius"]:
+            for droplet in objs.droplets:  # type: ignore
+                if droplet.radius > 0:
+                    scale = np.sqrt(dt * diffusivity(droplet.radius, t))
+                    droplet.position += scale * np.random.randn(dim)
+        else:
+            scale = np.sqrt(dt * diffusivity(t))
+            objs.positions[...] += scale * np.random.randn(len(objs), objs.dim)  # type: ignore