emulsim.actors.coupling.multicomponent_droplet module

Provides an actor coupling multicomponent droplets to background fields.

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

Bases: ActorBase

Actor coupling point-like multicomponent droplets to multiple field.

For simplicity, these droplets interact with the field only at one point (their position) using a simple linear exchange flux model. This model can be derived in the simple case of a Cahn-Hilliard equation with a mobility that scales with the fraction. The model is currently restricted to 1D and 3D systems.

The system describes \(N\) interacting components that are embedded in a solvent. The solvent is not described explicitly, but rather derived from the incompressibility condition.

Parameters Dictionary:

• boundary_conditions: Defines the boundary conditions on the field.Boundary conditions are generally given as a dictionary with one condition for

each axis side (default=’auto_periodic_neumann’)

• chis: Interaction parameters between all described components (default=array([[0.]]))

• chis_solvent: Interaction parameters between described components and the solvent (default=array(0))

• dissolve_fraction: Minimal total fraction in a droplet before it is considered dissolved (default=1e-06)

• dissolve_radius: Minimal radius before a droplet is considered dissolved (default=0.5)

• min_fraction: Minimal value fraction any fraction may attain (default=1e-08)

• mobility: Diffusive transport coefficients (default=array(1.))

• reactions: Function or expression to specify reactions in the system (default=None)

• surface_tension: Surface tension that determines the Laplace pressure, e.g., the additional pressure inside the droplets. (default=0.0)

• volume_relaxation_factor: This factor affects the relaxation of the volume as a response to pressure gradients (default=1.0)

Parameters:

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

Parameters of MulticomponentDropletActor:

chis

Interaction parameters between all described components. This parameter also determines the number of described components (Default value: array([[0.]]))

chis_solvent

Interaction parameters between described components and the solvent (Default value: array(0))

reactions

Function or expression to specify reactions in the system (Default value: None)

surface_tension

Surface tension that determines the Laplace pressure, e.g., the additional pressure inside the droplets. (Default value: 0.0)

mobility

Diffusive transport coefficients. This factor determines the diffusivities of molecules in the dilute phase and thus how fast droplets change size. The corresponding Onsager coefficient is the product of these mobilities and the fraction of the fields. A single number implies sets the same mobility for all components. (Default value: array(1.))

volume_relaxation_factor

This factor affects the relaxation of the volume as a response to pressure gradients. Since volume relaxation is dominated by solvent exchange, this factor can be interpreted as the ratio of the solvent mobility to the mobility of all other components. However, large values can lead to numerical instabilities. (Default value: 1.0)

boundary_conditions

Defines the boundary conditions on the field.Boundary conditions are generally given as a dictionary with one condition for each axis side. For periodic axes, only periodic boundary conditions are allowed (indicated by ‘periodic’ and ‘anti-periodic’). For non-periodic axes, different boundary conditions can be specified for the lower and upper end (using specific identifiers, like x- and y+). For instance, Dirichlet conditions enforcing a value NUM (specified by {‘value’: NUM}) and Neumann conditions enforcing the value DERIV for the derivative in the normal direction (specified by {‘derivative’: DERIV}) are supported. Note that the special value ‘auto_periodic_neumann’ imposes periodic boundary conditions for periodic axis and a vanishing derivative otherwise. More information can be found in the boundaries documentation. (Default value: 'auto_periodic_neumann')

dissolve_radius

Minimal radius before a droplet is considered dissolved. This cutoff is necessary since very small droplets can lead to numerical instabilities where the composition is no longer within [0, 1]. (Default value: 0.5)

dissolve_fraction

Minimal total fraction in a droplet before it is considered dissolved. This threshold ensures that large droplets that have the same composition as the background are removed. (Default value: 1e-06)

min_fraction

Minimal value fraction any fraction may attain. Fractions must not become zero since otherwise the logarithms appearing in the entropic contributions cannot be evaluated. The minimal fraction is strictly enforced, which can potentially lead to mass loss during a simulation. To control for this, we record the accumulated corrections applied to each component in the array diagnostics[‘amount_corrections’] (Default value: 1e-08)

property chis_full: ndarray

the full interaction matrix including solvent.

Type:

ndarray

element_classes: tuple[type[_ElementBase] | tuple[type[_ElementBase], ...], ...] | EllipsisType = (<class 'emulsim.elements.multicomponent_droplets.MulticomponentDropletsElement'>, <class 'emulsim.elements.fields.FieldCollectionElement'>)

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

evolve(elements: tuple[MulticomponentDropletsElement, FieldCollectionElement], 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

classmethod from_linear_reactions(parameters: dict[str, Any], rates: ndarray, production: ndarray | None = None) → MulticomponentDropletActor

Create functions suitable to describe linear reactions.

Parameters:

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

• rates (ndarray) – The rate matrix describing the conversion of all components

• production (ndarray, optional) – The zeroth-order production flux of all components

Returns:

a function that determines the reaction rates or None if no reactions are present (i.e., all inputs are zero)

Return type:

callable

get_droplet_fractions(elements: tuple[MulticomponentDropletsElement, FieldCollectionElement]) → ndarray

Calculates the fractions outside and inside of all droplets.

Parameters:

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

Returns:

the fractions outside and inside of all droplets for all components. This array has shape (num_drops, 2, num_comps), where the second axis distinguishes outside and inside.

Return type:

ndarray

get_thermodynamic_quantity(droplets: MulticomponentDropletsElement, fields: FieldCollectionElement, kind: str) → tuple[ndarray, FieldBase]

Return a thermodynamic quantity in the droplets and the background field.

Parameters:

• droplets (MulticomponentDropletsElement) – The element describing all the droplets

• fields (FieldCollectionElement) – The element describing all the background fields

• kind (str) – Determines which quantity to return. Possible choices are “free energy density”, “chemical potential”, and “pressure”

Returns:

tuple of ndarray (selected quantity for each droplet) and FieldBase (selected quantity for the background).

make_evolver_numba(elements: tuple[MulticomponentDropletsElement, FieldCollectionElement]) → 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, t: float, dt: float), evolving droplets_data and field_data

Return type:

callable

exception SolventFractionError

Bases: RuntimeError

Error indicating that the solvent fraction was not in [0, 1]