emulsim.actors.coupling.spherical_droplet module

Provides a coupling of extended spherical droplets to a field.

This module also provides a class for managing a collection of spherical shells with different subdivisions into spherical sectors. Each sector is defined by a unit vector pointing to its center and an associated weight, which captures is local size compared to all other shell sectors. These shell sectors are used to connect the diffusive fluxes right outside droplets to the background field; see the publication for details: A. Kulkarni, E. Vidal-Henriquez, and D. Zwicker, Sci. Rep. 13, 733.

ShellSectors	Class representing the sectors of a single shell.
ShellCollection	Class representing a collection of shells.
SphericalDropletActor	Actor coupling spherical droplets to a field.

class PointsOnSphere(points)

Bases: object

Class representing points on an n-dimensional unit sphere.

Parameters:

points (ndarray) – The list of points on the unit sphere

get_area_weights(balance_axes: bool = True)

Return the weight of each point associated with the unit cell size.

Parameters:

balance_axes (bool) – Flag determining whether the weights should be chosen such that the weighted average of all points is the zero vector.

Returns:

The weight associated with each point

Return type:

ndarray

get_distance_matrix()

Calculate the (spherical) distances between each point.

Returns:

The distance of each point to each other

Return type:

ndarray

get_mean_separation() → float

float: calculates the mean distance to the nearest neighbor

classmethod make_uniform(dim: int, num_points: int | None = None)

Create uniformly distributed points on a sphere.

Parameters:

• dim (int) – The dimension of space

• num_points (int, optional) – The number of points to generate. Note that for one-dimensional spheres (intervals), only exactly two points can be generated.

write_to_xyz(path: Path | str, comment: str = '', symbol: str = 'S') → None

Write the point coordinates to a xyz file.

Parameters:

• path (str) – Location of the file where data is written

• comment (str, optional) – Comment that is written to the second line

• symbol (str, optional) – Denotes the symbol used for the atoms

class ShellCollection(shells: Sequence[ShellSectors], max_radii: Sequence[float], info_dict: dict[str, Any] | None = None)

Bases: object

Class representing a collection of shells.

Parameters:

• shells (list) – List of shells

• max_radii (ndarray) – The maximal sphere radius that each shell should be used for

• info_dict (dict, optional) – A dictionary into which extra information will be stored

classmethod from_dictlist(dictlist: Sequence[dict[str, Any]], info_dict: dict[str, Any] | None = None) → ShellCollection

Create shell collection from a list of dictionaries.

Parameters:

• dictlist (list of dicts) – a list of shells, where each shell is characterized by a dictionary with entries ‘vectors’, ‘weights’, and ‘radius_threshold’.

• info_dict (dict, optional) – A dictionary into which extra information will be stored

Returns:

ShellCollection

classmethod generate(dim: int, sector_size_max: float = 1, radius_max: float = inf, info_dict: dict[str, Any] | None = None) → ShellCollection

Generate a ShellCollection for a simulation.

Parameters:

• dim (int) – The dimension of space

• sector_size_max (float) – Maximal linear size of sectors associated with shell points

• radius_max (float, optional) – The maximal radius of the sphere that needs to be considered

• info_dict (dict, optional) – A dictionary into which extra information will be stored

Note

One-dimensional shells are special in that there can only be exactly two sectors. Consequently, max_sector_size and radius_max are not used in this case.

Returns:

ShellCollection

get_shell(radius: float) → ShellSectors

Return shell corresponding to droplet of given radius.

Parameters:

radius (float) – The radius of the droplet

Returns:

The shell associated with this radius

Return type:

ShellSectors

make_shell_data_getter() → Callable[[float], tuple[ndarray, ndarray]]

Returns a function for obtaining a shell.

Returns:

A function that is called with a radius and returns a

tuple (numpy.ndarray, numpy.ndarray) of the shell vectors and the associated weights. The shell vectors are unit vectors pointing from the droplet center to the shell center. The weights give the fraction of the droplet surface that is covered by the respective shell, so that the sum of all weights is unity

Return type:

callable

max_sector_count: int = 512

class ShellSectors(vectors: ndarray, weights: ndarray | None = None)

Bases: object

Class representing the sectors of a single shell.

Parameters:

• vectors (list) – (Unit) vectors defining the position of the centers of the shell sectors

• weights (list) – List of weights for each shell sector determining the fraction of the droplet surface that is covered by the respective sector. The sum of all weights must be one.

property dim: int

dimension of the space this shell is defined for

Type:

int

classmethod generate(dim: int, sector_count: int = 1) → ShellSectors

Generate a ShellSectors for a simulation.

Parameters:

• dim (int) – The dimension of space

• sector_count (int) – Number of sectors to generate (ignored when dim==1)

Note

One-dimensional shells are special in that there can only be exactly two sectors. Consequently, sector_count is not used in this case.

Returns:

ShellSectors

get_shell(radius: float) → ShellSectors

Return shell corresponding to droplet of given radius.

Parameters:

radius (float) – The radius of the droplet

Returns:

The shell associated with this radius

Return type:

ShellSectors

make_shell_data_getter() → Callable[[float], tuple[ndarray, ndarray]]

Returns a function for obtaining a shell.

Returns:

A function that is called with a radius and returns a

tuple (numpy.ndarray, numpy.ndarray) of the shell vectors and the associated weights. The shell vectors are unit vectors pointing from the droplet center to the shell center. The weights give the fraction of the droplet surface that is covered by the respective shell, so that the sum of all weights is unity

Return type:

callable

property sector_count: int

number of sectors

Type:

int

class SphericalDropletActor(parameters: dict[str, Any] | None = None)

Bases: ActorBase

Actor coupling spherical droplets to a field.

Parameters Dictionary:

• background_correction: Flag determining whether the reaction flux in the droplet is corrected to ensure material conservation in the case where the reaction dynamics are first-order rate laws (default=False)

• diffusivity: Diffusivity in the shell surrounding the droplets (default=1.0)

• drift_enabled: Flag determining whether droplets can move (default=True)

• equilibrium_concentration: Expression for the equilibrium concentration (default=’1e-5 / radius’)

• mean_reaction_inside: Mean reaction rate inside the droplet, which determines the production of droplet material per unit volume (default=’automatic’)

• num_threads: The number of threads to use in the parallel update of the droplets (default=1)

• reaction_outside: Reaction rate outside the droplet, which determines the production of droplet material per unit volume in the shell region (default=’0’)

• shell_sector_count: The number of shell sectors when shell_sector_method == “count” (default=6)

• shell_sector_method: Determines the method that is used to determine the shell sector size (default=’size’)

• shell_sector_size: The typical azimuthal size of a shell sector (default=’dx’)

• shell_thickness: The thickness of the shell around droplets (default=’dx’)

Parameters:

parameters (dict) – Parameters defining the behavior of the actor. Call show_parameters() for details.

Parameters of SphericalDropletActor:

equilibrium_concentration

Expression for the equilibrium concentration. This expression can contain the variables position, radius, and id denoting the droplet radius, its position vector, and its identity (the index in the list of droplets), respectively. Alternatively, the value can also be an instance defining a __call__ method that returns the equilibrium concentration and a get_function method that returns a numba compiled function for calculating it. These functions must have the signature (position, radius, i). (Default value: '1e-5 / radius')

diffusivity

Diffusivity in the shell surrounding the droplets (Default value: 1.0)

reaction_outside

Reaction rate outside the droplet, which determines the production of droplet material per unit volume in the shell region. This can be an expression that depends on position, the local concentration value c outside the droplet, or the droplets identity id (the index in the list of droplets). (Default value: '0')

mean_reaction_inside

Mean reaction rate inside the droplet, which determines the production of droplet material per unit volume. This can be an expression that depends on the droplet radius R, its location position, or its identity id (the index in the list of droplets). Use negative values to destroy droplet material inside the droplet. The special value automatic will determine this rate by using the parameter reaction_outside evaluated at droplet_concentration specified by the droplets. (Default value: 'automatic')

background_correction

Flag determining whether the reaction flux in the droplet is corrected to ensure material conservation in the case where the reaction dynamics are first-order rate laws. Since we do not fully understand the implications of this correction at this point, we disabled it by default. (Default value: False)

drift_enabled

Flag determining whether droplets can move (Default value: True)

shell_thickness

The thickness of the shell around droplets. This can be either a length in non-dimensional units or an expression that can be parsed with sympy. In the latter case, the grid discretization is available as the variable dx (Default value: 'dx')

shell_sector_method

Determines the method that is used to determine the shell sector size. Possible values are size and count. (Default value: 'size')

shell_sector_size

The typical azimuthal size of a shell sector. This can be either a length in non-dimensional units or an expression that can be parsed with sympy. In the latter case, the grid discretization is available as the variable dx. This value is only used when shell_sector_method == “size” (Default value: 'dx')

shell_sector_count

The number of shell sectors when shell_sector_method == “count” (Default value: 6)

num_threads

The number of threads to use in the parallel update of the droplets. This can either be a positive integer or auto, in which case the number of threads are based on the value of numba.config.NUMBA_NUM_THREADS. (Default value: 1)

element_classes: tuple[type[_ElementBase] | tuple[type[_ElementBase], ...], ...] | EllipsisType = (<class 'emulsim.elements.spherical_droplets.SphericalDropletsElement'>, (<class 'emulsim.elements.fields.ReservoirElement'>, <class 'emulsim.elements.fields.FieldElementBase'>))

defines the elements this actor handles and in what order they need to be supplied. An ellipsis (…) indicates that all elements and lists of elements are accepted. Setting this attribute allows internal consistency checks.

Type:

tuple

estimate_dt(elements: tuple[SphericalDropletsElement, FieldElementBase]) → float

Estimate the maximal time step for simulating this actor.

The time step is based on the time scale of diffusion in the shell. In the special case of large shells (for instance in mean-field coarsening simulations) the defining length scale is the mean droplet radius instead. This estimate is based on the growth rate of droplets, dR/dt ∝ D/R, where D is the diffusivity and R is the mean droplet radius. Therefore, ΔR/Δt ∝ D/R and ΔR/R = ε implies Δt = ε * R**2 / D, where we chose ε=0.1.

Parameters:

elements (tuple) – The state of all the droplets and of the field

Returns:

the maximal time step

Return type:

float

evolve(elements: tuple[SphericalDropletsElement, FieldElementBase], t: float, dt: float) → None

Evolve the state from time t to t + dt

Parameters:

• elements (tuple) – The state of all the droplets and of the field

• t (float) – The current time point

• dt (float) – The time step

get_equilibrium_concentrations(droplets: SphericalDropletsElement) → ndarray

Returns the equilibrium concentration outside each droplet.

Parameters:

droplets (SphericalDropletsElement) – The state of all the droplets

Returns:

The equilibrium concentration for each

droplet with non-zero radius.

Return type:

ndarray

get_flux_outside(radius: float, c_far: float, cEqOut: float, droplet_id: int) → float

Returns the integrated outwards flux at the droplet surface given some imposed concentration value at the outer shell.

Note

We assume that the flux is integrated over the entire spherical surface, so that it needs to be multiplied by the surface fraction when only a sector is considered. The fluxes are calcuated by solving the ReactionDiffusion or the Diffusion equation inside each shell sector. Detailed documentation for calculating the material fluxes (both inside and outside the droplets) is located at /emulsim/docs/methods.

Parameters:

• radius (float) – The current droplet radius

• c_far (float) – The concentration at the outer side of the shell sector

• cEqOut (float) – The concentration right at the inner side of the shell sector, right at the droplet surface.

• droplet_id (int) – The id of the droplet, i.e., its position in the internal droplet list. This is ignored in the standard implementation given here, but is required by the interface since it is useful in other situations.

Returns:

the integrated flux in the outward normal direction.

Return type:

float

make_evolver_numba(elements: tuple[SphericalDropletsElement, FieldElementBase]) → Callable[[tuple[ndarray, ...], float, float], None]

Return a function evolve the state from time t to t + dt

Parameters:

elements (tuple) – The state of all the droplets and of the field

Returns:

A function with signature

(droplets_data: ndarray, field_data: ndarray, t: float, dt: float), evolving droplets_data and field_data

Return type:

callable

plot_shell_points(droplets: SphericalDropletsElement, background: FieldElementBase, state_style: dict[str, Any] | None = None, point_style: dict[str, Any] | None = None, shell_style: dict[str, Any] | None = None, *args, title: str | None = None, filename: str | None = None, action: Literal['auto', 'close', 'none', 'sca', 'show'] = 'auto', ax_style: dict[str, Any] | None = None, fig_style: dict[str, Any] | None = None, ax=None, **kwargs) → PlotReference

Plot all shell points around the droplets of a given state.

Parameters:

• title (str) – Title of the plot. If omitted, the title might be chosen automatically.

• filename (str, optional) – If given, the plot is written to the specified file.

• action (str) – Decides what to do with the final figure. If the argument is set to show, matplotlib.pyplot.show() will be called to show the plot. If the value is none, the figure will be created, but not necessarily shown. The value close closes the figure, after saving it to a file when filename is given. The default value auto implies that the plot is shown if it is not a nested plot call.

• ax_style (dict) – Dictionary with properties that will be changed on the axis after the plot has been drawn by calling matplotlib.pyplot.setp(). A special item i this dictionary is use_offset, which is flag that can be used to control whether offset are shown along the axes of the plot.

• fig_style (dict) – Dictionary with properties that will be changed on the figure after the plot has been drawn by calling matplotlib.pyplot.setp(). For instance, using fig_style={‘dpi’: 200} increases the resolution of the figure.

• ax (matplotlib.axes.Axes) – Figure axes to be used for plotting. The special value “create” creates a new figure, while “reuse” attempts to reuse an existing figure, which is the default.

• droplets (SphericalDropletsElement or Emulsion) – Information about all the droplets

• background (FieldElementBase or ScalarField) – Information about the background field

• state_style (dict, optional) – Dictionary with keyword arguments that are used in the AgentState.plot() call. This affects the style of the background and the actual droplets.

• point_style (dict, optional) – Dictionary with keyword arguments that are used in the matplotlib.pyplot.plot() call. This affects the style of the shell points.

• shell_style (dict, optional) – Dictionary with keyword arguments that are used in the matplotlib.patches.Wedge() call that is responsible for drawing the shell area.

reaction_rate_tolerance: float = 1e-10

tolerance determining when a simpler expression for reactions is used

Type:

float

get_spherical_polygon_area(vertices: ndarray, radius: float = 1) → float

Calculate the surface area of a polygon on the surface of a sphere. Based on equation provided here: http://mathworld.wolfram.com/LHuiliersTheorem.html Decompose into triangles, calculate excess for each

Adapted from https://github.com/tylerjereddy/spherical-SA-docker-demo Licensed under MIT License (see copy in root of this project)

Parameters:

• vertices (ndarray) – List of vertices (using Cartesian coordinates) that describe the corners of the polygon. The vertices need to be oriented.

• radius (float) – Radius of the sphere

haversine_distance(point1: ndarray, point2: ndarray) → ndarray

Calculate the haversine-based distance between two points on the surface of a sphere. Should be more accurate than the arc cosine strategy. See, for example: https://en.wikipedia.org/wiki/Haversine_formula

Adapted from https://github.com/tylerjereddy/spherical-SA-docker-demo Licensed under MIT License (see copy in root of this project)

Parameters:

• point1 (ndarray) – First point(s) on the sphere (given in Cartesian coordinates)

• point2 (ndarray) – Second point on the sphere Second point(s) on the sphere (given in Cartesian coordinates)

Returns:

The distances between the points

Return type:

ndarray