Plugins¶
Plugins are used to add specific data processing or to modify the regular pipeline in certain way. However, the functionality they provide is not considered essential.
If the simulation is started without postprocess part (see Overview), most of the plugins are disabled.
Summary¶
Classes¶
PinObject |
Contains the special value Unrestricted for unrestricted axes in createPinObject . |
PostprocessPlugin |
Base postprocess plugin class |
SimulationPlugin |
Base simulation plugin class |
Creation functions¶
createAddForce (state, name, pv, force) |
This plugin will add constant force \(\mathbf{F}_{extra}\) to each particle of a specific PV every time-step. |
createAddForceField (*args, **kwargs) |
Overloaded function. |
createAddFourRollMillForce (state, name, pv, …) |
This plugin will add a force \(\mathbf{f} = (A \sin x \cos y, A \cos x \sin y, 0)\) to each particle of a specific PV every time-step. |
createAddPotentialForce (*args, **kwargs) |
Overloaded function. |
createAddReversePoiseuilleForce (state, name, …) |
This plugin will add constant force \(\mathbf{F}_{extra}\) to each particle of a specific PV every time-step. |
createAddSinusoidalForce (state, name, pv, …) |
This plugin will add sinusoidal force \(\mathbf{F}(\mathbf{r}) = A \sin\left( 2\pi k r_y / L_y\right)\) to each particle of a specific PV every time-step, where \(L_y\) is the dimension of the domain along :math`y`. |
createAddTorque (state, name, ov, torque) |
This plugin will add constant torque \(\mathbf{T}_{extra}\) to each object of a specific OV every time-step. |
createAnchorParticles (state, name, pv, …) |
This plugin will set a given particle at a given position and velocity. |
createBerendsenThermostat (state, name, pvs, …) |
Berendsen thermostat. |
createDensityControl (state, name, file_name, …) |
This plugin applies forces to a set of particle vectors in order to get a constant density. |
createDensityOutlet (state, name, pvs, …) |
This plugin removes particles from a set of ParticleVector in a given region if the number density is larger than a given target. |
createDumpAverage (state, name, pvs, …) |
This plugin will project certain quantities of the particle vectors on the grid (by simple binning), perform time-averaging of the grid and dump it in XDMF format with HDF5 backend.The quantities of interest are represented as channels associated with particles vectors.Some interactions, integrators, etc.and more notable plug-ins can add to the Particle Vectors per-particles arrays to hold different values.These arrays are called channels.Any such channel may be used in this plug-in, however, user must explicitely specify the type of values that the channel holds.Particle number density is used to correctly average the values, so it will be sampled and written in any case into the field “number_densities”.. |
createDumpAverageRelative (state, name, pvs, …) |
This plugin acts just like the regular flow dumper, with one difference. |
createDumpMesh (state, name, ov, dump_every, path) |
This plugin will write the meshes of all the object of the specified Object Vector in a PLY format. |
createDumpObjectStats (state, name, ov, …) |
This plugin will write the coordinates of the centers of mass of the objects of the specified Object Vector. |
createDumpParticles (state, name, pv, …) |
This plugin will dump positions, velocities and optional attached data of all the particles of the specified Particle Vector. |
createDumpParticlesWithMesh (state, name, ov, …) |
This plugin will dump positions, velocities and optional attached data of all the particles of the specified Object Vector, as well as connectivity information. |
createDumpParticlesWithPolylines (state, …) |
This plugin will dump positions, velocities and optional attached data of all the particles of the specified ChainVector, as well as connectivity information representing polylines. |
createDumpXYZ (state, name, pv, dump_every, path) |
This plugin will dump positions of all the particles of the specified Particle Vector in the XYZ format. |
createExchangePVSFluxPlane (state, name, pv1, …) |
This plugin exchanges particles from a particle vector crossing a given plane to another particle vector. |
createExpMovingAverage (state, name, pv, …) |
Compute the exponential moving average (EMA) of the given channel of a ParticleVector and stores it in the new channel “ema_channel_name”. |
createExternalMagneticTorque (state, name, …) |
This plugin gives a magnetic moment \(\mathbf{M}\) to every rigid objects in a given RigidObjectVector . |
createForceSaver (state, name, pv) |
This plugin creates an extra channel per particle inside the given particle vector named ‘forces’. |
createImposeProfile (state, name, pv, low, …) |
This plugin will set the velocity of each particle inside a given domain to a target velocity with an additive term drawn from Maxwell distribution of the given temperature. |
createImposeVelocity (state, name, pvs, …) |
This plugin will add velocity to all the particles of the target PV in the specified area (rectangle) such that the average velocity equals to desired. |
createMagneticDipoleInteractions (state, …) |
This plugin computes the forces and torques resulting from pairwise dipole-dipole interactions between rigid objects. |
createMembraneExtraForce (state, name, pv, forces) |
This plugin adds a given external force to a given membrane. |
createMsd (state, name, pv, start_time, …) |
This plugin computes the mean square displacement of th particles of a given ParticleVector . |
createParticleChannelAverager (state, name, …) |
This plugin averages a channel (per particle data) inside the given particle vector and saves it to a new channel. |
createParticleChannelSaver (state, name, pv, …) |
This plugin creates an extra channel per particle inside the given particle vector with a given name. |
createParticleChecker (state, name, check_every) |
This plugin will check the positions and velocities of all particles in the simulation every given time steps. |
createParticleDisplacement (state, name, pv, …) |
This plugin computes and save the displacement of the particles within a given particle vector. |
createParticleDrag (state, name, pv, drag) |
This plugin will add drag force \(\mathbf{f} = - C_d \mathbf{u}\) to each particle of a specific PV every time-step. |
createPinObject (state, name, ov, dump_every, …) |
This plugin will impose given velocity as the center of mass velocity (by axis) of all the objects of the specified Object Vector. |
createPinRodExtremity (state, name, rv, …) |
This plugin adds a force on a given segment of all the rods in a RodVector . |
createPlaneOutlet (state, name, pvs, plane) |
This plugin removes all particles from a set of ParticleVector that are on the non-negative side of a given plane. |
createRateOutlet (state, name, pvs, …) |
This plugin removes particles from a set of ParticleVector in a given region at a given mass rate. |
createRdf (state, name, pv, max_dist, nbins, …) |
Compute the radial distribution function (RDF) of a given ParticleVector . |
createRmacf (state, name, cv, start_time, …) |
This plugin computes the mean Rouse mode autocorrelation over time from a given ChainVector . |
createShearField (state, name, pv, shear, …) |
This plugin computes the shear velocity field at every particle’s position and stores it in a channel vector. |
createSinusoidalField (state, name, pv, …) |
This plugin computes a sinusoidal velocity field at every particle’s position and stores it in a channel vector. |
createStats (state, name, every, pvs, filename) |
This plugin will report aggregate quantities of all the particles in the simulation: total number of particles in the simulation, average temperature and momentum, maximum velocity magnutide of a particle and also the mean real time per step in milliseconds. |
createTemperaturize (state, name, pv, kBT, …) |
This plugin changes the velocity of each particles from a given ParticleVector . |
createVacf (state, name, pv, start_time, …) |
This plugin computes the mean velocity autocorrelation over time from a given ParticleVector . |
createVelocityControl (state, name, filename, …) |
This plugin applies a uniform force to all the particles of the target PVS in the specified area (rectangle). |
createVelocityInlet (state, name, pv, …) |
This plugin inserts particles in a given ParticleVector . |
createVirialPressurePlugin (state, name, pv, …) |
This plugin computes the virial pressure from a given ParticleVector . |
createWallForceCollector (state, name, wall, …) |
This plugin collects and averages the total force exerted on a given wall. |
createWallRepulsion (state, name, pv, wall, …) |
This plugin will add force on all the particles that are nearby a specified wall. |
Details¶
-
class
PinObject
¶ Bases:
mmirheo.Plugins.SimulationPlugin
Contains the special value Unrestricted for unrestricted axes in
createPinObject
.
-
class
PostprocessPlugin
¶ Bases:
object
Base postprocess plugin class
-
class
SimulationPlugin
¶ Bases:
object
Base simulation plugin class
-
createAddForce
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, force: real3) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will add constant force \(\mathbf{F}_{extra}\) to each particle of a specific PV every time-step. Is is advised to only use it with rigid objects, since Velocity-Verlet integrator with constant pressure can do the same without any performance penalty.
Parameters: - name – name of the plugin
- pv –
ParticleVector
that we’ll work with - force – extra force
-
createAddForceField
(*args, **kwargs)¶ Overloaded function.
createAddForceField(state: MirState, name: str, pv: ParticleVectors.ParticleVector, force_field: Callable[[real3], real3], h: real3) -> Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]
Add a force to each particle of a specific PV every time-step.
- Args:
name: name of the plugin pv:
ParticleVector
that we’ll work with force_field: force field h: grid spacing used to discretize the force field
createAddForceField(state: MirState, name: str, pv: ParticleVectors.ParticleVector, force_field_filename: str, h: real3) -> Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]
Add a force to each particle of a specific PV every time-step.
- Args:
name: name of the plugin pv:
ParticleVector
that we’ll work with force_field_filename: file that contains the force field on a cartesian grid. Same format as Sdf for walls but with 4 components per grid point (only the first three are used). h: grid spacing used to discretize the force field
-
createAddFourRollMillForce
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, intensity: float) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will add a force \(\mathbf{f} = (A \sin x \cos y, A \cos x \sin y, 0)\) to each particle of a specific PV every time-step.
Parameters: - name – name of the plugin
- pv –
ParticleVector
that we’ll work with - intensity – The intensity of the force
-
createAddPotentialForce
(*args, **kwargs)¶ Overloaded function.
createAddPotentialForce(state: MirState, name: str, pv: ParticleVectors.ParticleVector, potential_field: Callable[[real3], float], h: real3) -> Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]
Add a force \(\mathbf{F}_{extra}\) to each particle of a specific PV every time-step. The force is the negative gradient of a potential field at the particle position.
- Args:
name: name of the plugin pv:
ParticleVector
that we’ll work with potential_field: potential field h: grid spacing used to discretize the potential field
createAddPotentialForce(state: MirState, name: str, pv: ParticleVectors.ParticleVector, potential_field_filename: str, h: real3) -> Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]
Add a force \(\mathbf{F}_{extra}\) to each particle of a specific PV every time-step. The force is the negative gradient of a potential field at the particle position.
- Args:
name: name of the plugin pv:
ParticleVector
that we’ll work with potential_field_filename: file that contains the potential field on a cartesian grid. Same format as Sdf for walls. h: grid spacing used to discretize the potential field
-
createAddReversePoiseuilleForce
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, force: real3, flip_direction: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will add constant force \(\mathbf{F}_{extra}\) to each particle of a specific PV every time-step. The force is flipped if the position is in the upper half along the flip_direction.
Parameters: - name – name of the plugin
- pv –
ParticleVector
that we’ll work with - force – extra force
- flip_direction – either x, y or z. The direction along with the sign of the force changes.
-
createAddSinusoidalForce
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, magnitude: float, wave_number: int) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will add sinusoidal force \(\mathbf{F}(\mathbf{r}) = A \sin\left( 2\pi k r_y / L_y\right)\) to each particle of a specific PV every time-step, where \(L_y\) is the dimension of the domain along :math`y`.
Parameters: - name – name of the plugin
- pv –
ParticleVector
that we’ll work with - magnitude – coefficient \(A\)
- wave_number – mode \(k\) (integer)
-
createAddTorque
(state: MirState, name: str, ov: ParticleVectors.ParticleVector, torque: real3) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will add constant torque \(\mathbf{T}_{extra}\) to each object of a specific OV every time-step.
Parameters: - name – name of the plugin
- ov –
ObjectVector
that we’ll work with - torque – extra torque (per object)
-
createAnchorParticles
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, positions: Callable[[float], List[real3]], velocities: Callable[[float], List[real3]], pids: List[int], report_every: int, path: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will set a given particle at a given position and velocity.
Parameters: - name – name of the plugin
- pv –
ParticleVector
that we’ll work with - positions – positions (at given time) of the particles
- velocities – velocities (at given time) of the particles
- pids – global ids of the particles in the given particle vector
- report_every – report the time averaged force acting on the particles every this amount of timesteps
- path – folder where to dump the stats
-
createBerendsenThermostat
(state: MirState, name: str, pvs: List[ParticleVectors.ParticleVector], tau: float, kBT: float, increaseIfLower: bool=True) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ Berendsen thermostat.
On each time step the velocities of all particles in given particle vectors are multiplied by the following factor:
\[\lambda = \sqrt{1 + \frac{\Delta t}{\tau} \left( \frac{T_0}{T} - 1 \right)}\]where \(\Delta t\) is a time step, \(\tau\) relaxation time, \(T\) current temperature, \(T_0\) target temperature.
Reference: Berendsen et al. (1984)
Parameters: - name – name of the plugin
- pvs – list of
ParticleVector
objects to apply the thermostat to - tau – relaxation time \(\tau\)
- kBT – target thermal energy \(k_B T_0\)
- increaseIfLower – whether to increase the temperature if it’s lower than the target temperature
-
createDensityControl
(state: MirState, name: str, file_name: str, pvs: List[ParticleVectors.ParticleVector], target_density: float, region: Callable[[real3], float], resolution: real3, level_lo: float, level_hi: float, level_space: float, Kp: float, Ki: float, Kd: float, tune_every: int, dump_every: int, sample_every: int) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin applies forces to a set of particle vectors in order to get a constant density.
Parameters: - name – name of the plugin
- file_name – output filename
- pvs – list of
ParticleVector
that we’ll work with - target_density – target number density (used only at boundaries of level sets)
- region – a scalar field which describes how to subdivide the domain. It must be continuous and differentiable, as the forces are in the gradient direction of this field
- resolution – grid resolution to represent the region field
- level_lo – lower level set to apply the controller on
- level_hi – highest level set to apply the controller on
- level_space – the size of one subregion in terms of level sets
- Ki, Kd (Kp,) – pid control parameters
- tune_every – update the forces every this amount of time steps
- dump_every – dump densities and forces in file
filename
- sample_every – sample to average densities every this amount of time steps
-
createDensityOutlet
(state: MirState, name: str, pvs: List[ParticleVectors.ParticleVector], number_density: float, region: Callable[[real3], float], resolution: real3) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin removes particles from a set of
ParticleVector
in a given region if the number density is larger than a given target.Parameters: - name – name of the plugin
- pvs – list of
ParticleVector
that we’ll work with - number_density – maximum number_density in the region
- region – a function that is negative in the concerned region and positive outside
- resolution – grid resolution to represent the region field
-
createDumpAverage
(state: MirState, name: str, pvs: List[ParticleVectors.ParticleVector], sample_every: int, dump_every: int, bin_size: real3=real3(1.0, 1.0, 1.0), channels: List[str], path: str='xdmf/') → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will project certain quantities of the particle vectors on the grid (by simple binning), perform time-averaging of the grid and dump it in XDMF format with HDF5 backend. The quantities of interest are represented as channels associated with particles vectors. Some interactions, integrators, etc. and more notable plug-ins can add to the Particle Vectors per-particles arrays to hold different values. These arrays are called channels. Any such channel may be used in this plug-in, however, user must explicitely specify the type of values that the channel holds. Particle number density is used to correctly average the values, so it will be sampled and written in any case into the field “number_densities”.
Note
This plugin is inactive if postprocess is disabled
Parameters: - name – name of the plugin
- pvs – list of
ParticleVector
that we’ll work with - sample_every – sample quantities every this many time-steps
- dump_every – write files every this many time-steps
- bin_size – bin size for sampling. The resulting quantities will be cell-centered
- path – Path and filename prefix for the dumps. For every dump two files will be created: <path>_NNNNN.xmf and <path>_NNNNN.h5
- channels – list of channel names. See Reserved names.
-
createDumpAverageRelative
(state: MirState, name: str, pvs: List[ParticleVectors.ParticleVector], relative_to_ov: ParticleVectors.ObjectVector, relative_to_id: int, sample_every: int, dump_every: int, bin_size: real3=real3(1.0, 1.0, 1.0), channels: List[str], path: str='xdmf/') → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin acts just like the regular flow dumper, with one difference. It will assume a coordinate system attached to the center of mass of a specific object. In other words, velocities and coordinates sampled correspond to the object reference frame.
Note
Note that this plugin needs to allocate memory for the grid in the full domain, not only in the corresponding MPI subdomain. Therefore large domains will lead to running out of memory
Note
This plugin is inactive if postprocess is disabled
The arguments are the same as for createDumpAverage() with a few additions:
Parameters: - name – name of the plugin
- pvs – list of
ParticleVector
that we’ll work with - sample_every – sample quantities every this many time-steps
- dump_every – write files every this many time-steps
- bin_size – bin size for sampling. The resulting quantities will be cell-centered
- path – Path and filename prefix for the dumps. For every dump two files will be created: <path>_NNNNN.xmf and <path>_NNNNN.h5
- channels – list of channel names. See Reserved names.
- relative_to_ov – take an object governing the frame of reference from this
ObjectVector
- relative_to_id – take an object governing the frame of reference with the specific ID
-
createDumpMesh
(state: MirState, name: str, ov: ParticleVectors.ObjectVector, dump_every: int, path: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will write the meshes of all the object of the specified Object Vector in a PLY format.
Note
This plugin is inactive if postprocess is disabled
Parameters: - name – name of the plugin
- ov –
ObjectVector
that we’ll work with - dump_every – write files every this many time-steps
- path – the files will look like this: <path>/<ov_name>_NNNNN.ply
-
createDumpObjectStats
(state: MirState, name: str, ov: ParticleVectors.ObjectVector, dump_every: int, filename: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will write the coordinates of the centers of mass of the objects of the specified Object Vector. Instantaneous quantities (COM velocity, angular velocity, force, torque) are also written. If the objects are rigid bodies, also will be written the quaternion describing the rotation. The type id field is also dumped if the objects have this field activated (see
MembraneWithTypeId
).The file format is the following:
<object id> <simulation time> <COM>x3 [<quaternion>x4] <velocity>x3 <angular velocity>x3 <force>x3 <torque>x3 [<type id>]
Note
Note that all the written values are instantaneous
Note
This plugin is inactive if postprocess is disabled
Parameters: - name – Name of the plugin.
- ov –
ObjectVector
that we’ll work with. - dump_every – Write files every this many time-steps.
- filename – The name of the resulting csv file.
-
createDumpParticles
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, dump_every: int, channel_names: List[str], path: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will dump positions, velocities and optional attached data of all the particles of the specified Particle Vector. The data is dumped into hdf5 format. An additional xdfm file is dumped to describe the data and make it readable by visualization tools. If a channel from object data or bisegment data is provided, the data will be scattered to particles before being dumped as normal particle data.
Parameters: - name – name of the plugin
- pv –
ParticleVector
that we’ll work with - dump_every – write files every this many time-steps
- channel_names – list of channel names to be dumped.
- path – Path and filename prefix for the dumps. For every dump two files will be created: <path>_NNNNN.xmf and <path>_NNNNN.h5
-
createDumpParticlesWithMesh
(state: MirState, name: str, ov: ParticleVectors.ObjectVector, dump_every: int, channel_names: List[str], path: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will dump positions, velocities and optional attached data of all the particles of the specified Object Vector, as well as connectivity information. The data is dumped into hdf5 format. An additional xdfm file is dumped to describe the data and make it readable by visualization tools.
Parameters: - name – name of the plugin
- ov –
ObjectVector
that we’ll work with - dump_every – write files every this many time-steps
- channel_names – list of channel names to be dumped.
- path – Path and filename prefix for the dumps. For every dump two files will be created: <path>_NNNNN.xmf and <path>_NNNNN.h5
-
createDumpParticlesWithPolylines
(state: MirState, name: str, cv: ParticleVectors.ChainVector, dump_every: int, channel_names: List[str], path: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will dump positions, velocities and optional attached data of all the particles of the specified ChainVector, as well as connectivity information representing polylines. The data is dumped into hdf5 format. An additional xdfm file is dumped to describe the data and make it readable by visualization tools.
Parameters: - name – name of the plugin.
- cv –
ChainVector
to be dumped. - dump_every – write files every this many time-steps.
- channel_names – list of channel names to be dumped.
- path – Path and filename prefix for the dumps. For every dump two files will be created: <path>_NNNNN.xmf and <path>_NNNNN.h5
-
createDumpXYZ
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, dump_every: int, path: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will dump positions of all the particles of the specified Particle Vector in the XYZ format.
Note
This plugin is inactive if postprocess is disabled
Parameters: - name – name of the plugin
- pvs – list of
ParticleVector
that we’ll work with - dump_every – write files every this many time-steps
- path – the files will look like this: <path>/<pv_name>_NNNNN.xyz
-
createExchangePVSFluxPlane
(state: MirState, name: str, pv1: ParticleVectors.ParticleVector, pv2: ParticleVectors.ParticleVector, plane: real4) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin exchanges particles from a particle vector crossing a given plane to another particle vector. A particle with position x, y, z has crossed the plane if ax + by + cz + d >= 0, where a, b, c and d are the coefficient stored in the ‘plane’ variable
Parameters: - name – name of the plugin
- pv1 –
ParticleVector
source - pv2 –
ParticleVector
destination - plane – 4 coefficients for the plane equation ax + by + cz + d >= 0
-
createExpMovingAverage
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, alpha: float, src_channel_name: str, ema_channel_name: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ Compute the exponential moving average (EMA) of the given channel of a
ParticleVector
and stores it in the new channel “ema_channel_name”.Parameters: - name – name of the plugin
- pv –
ParticleVector
source - alpha – EMA coefficient. must be in [0, 1].
- src_channel_name – The name of the source channel.
- ema_channel_name – The name of the new EMA channel.
-
createExternalMagneticTorque
(state: MirState, name: str, rov: ParticleVectors.RigidObjectVector, moment: real3, magneticFunction: Callable[[float], real3]) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin gives a magnetic moment \(\mathbf{M}\) to every rigid objects in a given
RigidObjectVector
. It also models a uniform magnetic field \(\mathbf{B}\) (varying in time) and adds the induced torque to the objects according to:\[\mathbf{T} = \mathbf{M} \times \mathbf{B}\]The magnetic field is passed as a function from python. The function must take a real (time) as input and output a tuple of three reals (magnetic field).
Parameters: - name – name of the plugin
- rov –
RigidObjectVector
with which the magnetic field will interact - moment – magnetic moment per object
- magneticFunction – a function that depends on time and returns a uniform (real3) magnetic field
-
createForceSaver
(state: MirState, name: str, pv: ParticleVectors.ParticleVector) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin creates an extra channel per particle inside the given particle vector named ‘forces’. It copies the total forces at each time step and make it accessible by other plugins. The forces are stored in an array of real3.
Parameters: - name – name of the plugin
- pv –
ParticleVector
that we’ll work with
-
createImposeProfile
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, low: real3, high: real3, velocity: real3, kBT: float) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will set the velocity of each particle inside a given domain to a target velocity with an additive term drawn from Maxwell distribution of the given temperature.
Parameters: - name – name of the plugin
- pv –
ParticleVector
that we’ll work with - low – the lower corner of the domain
- high – the higher corner of the domain
- velocity – target velocity
- kBT – temperature in the domain (appropriate Maxwell distribution will be used)
-
createImposeVelocity
(state: MirState, name: str, pvs: List[ParticleVectors.ParticleVector], every: int, low: real3, high: real3, velocity: real3) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will add velocity to all the particles of the target PV in the specified area (rectangle) such that the average velocity equals to desired.
Parameters: - name – name of the plugin
- pvs – list of
ParticleVector
that we’ll work with - every – change the velocities once in every timestep
- low – the lower corner of the domain
- high – the higher corner of the domain
- velocity – target velocity
-
createMagneticDipoleInteractions
(state: MirState, name: str, rov: ParticleVectors.RigidObjectVector, moment: real3, mu0: float, periodic: bool=True) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin computes the forces and torques resulting from pairwise dipole-dipole interactions between rigid objects. All rigid objects are assumed to be the same with a constant magnetic moment in their frame of reference.
Parameters: - name – name of the plugin
- rov –
RigidObjectVector
with which the magnetic field will interact - moment – magnetic moment per object
- mu0 – magnetic permeability of the medium
- periodic – if True, compute the interactions from the closest periodic image of each object.
-
createMembraneExtraForce
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, forces: List[real3]) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin adds a given external force to a given membrane. The force is defined vertex wise and does not depend on position. It is the same for all membranes belonging to the same particle vector.
Parameters: - name – name of the plugin
- pv –
ParticleVector
to which the force should be added - forces – array of forces, one force (3 reals) per vertex in a single mesh
-
createMsd
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, start_time: float, end_time: float, dump_every: int, path: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin computes the mean square displacement of th particles of a given
ParticleVector
. The reference position` is that of the givenParticleVector
at the given start time.Parameters: - name – Name of the plugin.
- pv – Concerned
ParticleVector
. - start_time – Simulation time of the reference positions.
- end_time – End time until which to compute the MSD.
- dump_every – Report MSD every this many time-steps.
- path – The folder name in which the file will be dumped.
-
createParticleChannelAverager
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, channelName: str, averageName: str, updateEvery: float) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin averages a channel (per particle data) inside the given particle vector and saves it to a new channel. This new channel (containing the averaged data) is updated every fixed number of time steps.
Parameters: - name – name of the plugin
- pv –
ParticleVector
that we’ll work with - channelName – The name of the source channel.
- averageName – The name of the average channel.
- updateEvery – reinitialize the averages every this number of steps.
-
createParticleChannelSaver
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, channelName: str, savedName: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin creates an extra channel per particle inside the given particle vector with a given name. It copies the content of an extra channel of pv at each time step and make it accessible by other plugins.
Parameters: - name – name of the plugin
- pv –
ParticleVector
that we’ll work with - channelName – the name of the source channel
- savedName – name of the extra channel
-
createParticleChecker
(state: MirState, name: str, check_every: int) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will check the positions and velocities of all particles in the simulation every given time steps. To be used for debugging purpose.
Parameters: - name – name of the plugin
- check_every – check every this amount of time steps
-
createParticleDisplacement
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, update_every: int) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin computes and save the displacement of the particles within a given particle vector. The result is stored inside the extra channel “displacements” as an array of real3.
Parameters: - name – name of the plugin
- pv –
ParticleVector
that we’ll work with - update_every – displacements are computed between positions separated by this amount of timesteps
-
createParticleDrag
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, drag: float) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will add drag force \(\mathbf{f} = - C_d \mathbf{u}\) to each particle of a specific PV every time-step.
Parameters: - name – name of the plugin
- pv –
ParticleVector
that we’ll work with - drag – drag coefficient
-
createPinObject
(state: MirState, name: str, ov: ParticleVectors.ObjectVector, dump_every: int, path: str, velocity: real3, angular_velocity: real3) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will impose given velocity as the center of mass velocity (by axis) of all the objects of the specified Object Vector. If the objects are rigid bodies, rotation may be restricted with this plugin as well. The time-averaged force and/or torque required to impose the velocities and rotations are reported in the dumped file, with the following format:
<object id> <simulation time> <force>x3 [<torque>x3]
Note
This plugin is inactive if postprocess is disabled
Parameters: - name – name of the plugin
- ov –
ObjectVector
that we’ll work with - dump_every – write files every this many time-steps
- path – the files will look like this: <path>/<ov_name>.csv
- velocity – 3 reals, each component is the desired object velocity.
If the corresponding component should not be restricted, set this value to
PinObject::Unrestricted
- angular_velocity – 3 reals, each component is the desired object angular velocity.
If the corresponding component should not be restricted, set this value to
PinObject::Unrestricted
-
createPinRodExtremity
(state: MirState, name: str, rv: ParticleVectors.RodVector, segment_id: int, f_magn: float, target_direction: real3) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin adds a force on a given segment of all the rods in a
RodVector
. The force has the form deriving from the potential\[E = k \left( 1 - \cos \theta \right),\]where \(\theta\) is the angle between the material frame and a given direction (projected on the concerned segment). Note that the force is applied only on the material frame and not on the center line.
Parameters: - name – name of the plugin
- rv –
RodVector
that we’ll work with - segment_id – the segment to which the plugin is active
- f_magn – force magnitude
- target_direction – the direction in which the material frame tends to align
-
createPlaneOutlet
(state: MirState, name: str, pvs: List[ParticleVectors.ParticleVector], plane: real4) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin removes all particles from a set of
ParticleVector
that are on the non-negative side of a given plane.Parameters: - name – name of the plugin
- pvs – list of
ParticleVector
that we’ll work with - plane – Tuple (a, b, c, d). Particles are removed if ax + by + cz + d >= 0.
-
createRateOutlet
(state: MirState, name: str, pvs: List[ParticleVectors.ParticleVector], mass_rate: float, region: Callable[[real3], float], resolution: real3) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin removes particles from a set of
ParticleVector
in a given region at a given mass rate.Parameters: - name – name of the plugin
- pvs – list of
ParticleVector
that we’ll work with - mass_rate – total outlet mass rate in the region
- region – a function that is negative in the concerned region and positive outside
- resolution – grid resolution to represent the region field
-
createRdf
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, max_dist: float, nbins: int, basename: str, every: int) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ Compute the radial distribution function (RDF) of a given
ParticleVector
. For simplicity, particles that are less that max_dist from the subdomain border are not counted.Parameters: - name – Name of the plugin.
- pv – The
ParticleVector
that we ant to compute the RDF from. - max_dist – The RDF will be computed on the interval [0, max_dist]. Must be strictly less than half the minimum size of one subdomain.
- nbins – The RDF is computed on nbins bins.
- basename – Each RDF dump will be dumped in csv format to <basename>-XXXXX.csv.
- every – Computes and dump the RDF every this amount of timesteps.
-
createRmacf
(state: MirState, name: str, cv: ParticleVectors.ChainVector, start_time: float, end_time: float, dump_every: int, path: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin computes the mean Rouse mode autocorrelation over time from a given
ChainVector
. The reference modes are that of theChainVector
at the given start time.Parameters: - name – Name of the plugin.
- cv – Concerned
ChainVector
. - start_time – Simulation time of the reference velocities.
- end_time – End time until which to compute the RMACF.
- dump_every – Report the RMACF every this many time-steps.
- path – The folder name in which the file will be dumped.
-
createShearField
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, shear: List[float[9]], origin: real3, sf_channel_name: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin computes the shear velocity field at every particle’s position and stores it in a channel vector.
Parameters: - name – Name of the plugin.
- pv – Concerned
ParticleVector
. - shear – Shear tensor.
- origin – Point in space with zero velocity.
- sf_channel_name – Name of the channel that will contain the shear field.
-
createSinusoidalField
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, magnitude: float, wave_number: int, sf_channel_name: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin computes a sinusoidal velocity field at every particle’s position and stores it in a channel vector.
Parameters: - name – Name of the plugin.
- pv – Concerned
ParticleVector
. - magnitude – Maximum velocity along x.
- wave_number – Number of periods along y.
- sf_channel_name – Name of the channel that will contain the sinusoidal field.
-
createStats
(state: MirState, name: str, every: int, pvs: List[ParticleVectors.ParticleVector]=[], filename: str='') → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will report aggregate quantities of all the particles in the simulation: total number of particles in the simulation, average temperature and momentum, maximum velocity magnutide of a particle and also the mean real time per step in milliseconds.
Note
This plugin is inactive if postprocess is disabled
Parameters: - name – Name of the plugin.
- every – Report to standard output every that many time-steps.
- pvs – List of pvs to compute statistics from. If empty, will use all the pvs registered in the simulation.
- filename – The statistics are saved in this csv file. The name should either end with .csv or have no extension, in which case .csv is added.
-
createTemperaturize
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, kBT: float, keepVelocity: bool) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin changes the velocity of each particles from a given
ParticleVector
. It can operate under two modes: keepVelocity = True, in which case it adds a term drawn from a Maxwell distribution to the current velocity; keepVelocity = False, in which case it sets the velocity to a term drawn from a Maxwell distribution.Parameters: - name – name of the plugin
- pv – the concerned
ParticleVector
- kBT – the target temperature
- keepVelocity – True for adding Maxwell distribution to the previous velocity; False to set the velocity to a Maxwell distribution.
-
createVacf
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, start_time: float, end_time: float, dump_every: int, path: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin computes the mean velocity autocorrelation over time from a given
ParticleVector
. The reference velocity v0 is that of the givenParticleVector
at the given start time.Parameters: - name – Name of the plugin.
- pv – Concerned
ParticleVector
. - start_time – Simulation time of the reference velocities.
- end_time – End time until which to compute the VACF.
- dump_every – Report the VACF every this many time-steps.
- path – The folder name in which the file will be dumped.
-
createVelocityControl
(state: MirState, name: str, filename: str, pvs: List[ParticleVectors.ParticleVector], low: real3, high: real3, sample_every: int, tune_every: int, dump_every: int, target_vel: real3, Kp: float, Ki: float, Kd: float) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin applies a uniform force to all the particles of the target PVS in the specified area (rectangle). The force is adapted bvia a PID controller such that the velocity average of the particles matches the target average velocity.
Parameters: - name – Name of the plugin.
- filename – Dump file name. Must have a csv extension or no extension at all.
- pvs – List of concerned
ParticleVector
. - high (low,) – boundaries of the domain of interest
- sample_every – sample velocity every this many time-steps
- tune_every – adapt the force every this many time-steps
- dump_every – write files every this many time-steps
- target_vel – the target mean velocity of the particles in the domain of interest
- Ki, Kd (Kp,) – PID controller coefficients
-
createVelocityInlet
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, implicit_surface_func: Callable[[real3], float], velocity_field: Callable[[real3], real3], resolution: real3, number_density: float, kBT: float) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin inserts particles in a given
ParticleVector
. The particles are inserted on a given surface with given velocity inlet. The rate of insertion is governed by the velocity and the given number density.Parameters: - name – name of the plugin
- pv – the
ParticleVector
that we ll work with - implicit_surface_func – a scalar field function that has the required surface as zero level set
- velocity_field – vector field that describes the velocity on the inlet (will be evaluated on the surface only)
- resolution – grid size used to discretize the surface
- number_density – number density of the inserted solvent
- kBT – temperature of the inserted solvent
-
createVirialPressurePlugin
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, regionFunc: Callable[[real3], float], h: real3, dump_every: int, path: str) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin computes the virial pressure from a given
ParticleVector
. Note that the stress computation must be enabled with the corresponding stressName. This returns the total internal virial part only (no temperature term). Note that the volume is not devided in the result, the user is responsible to properly scale the output.Parameters: - name – name of the plugin
- pv – concerned
ParticleVector
- regionFunc – predicate for the concerned region; positive inside the region and negative outside
- h – grid size for representing the predicate onto a grid
- dump_every – report total pressure every this many time-steps
- path – the folder name in which the file will be dumped
-
createWallForceCollector
(state: MirState, name: str, wall: Walls.Wall, pvFrozen: ParticleVectors.ParticleVector, sample_every: int, dump_every: int, filename: str, detailed_dump: bool=False) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin collects and averages the total force exerted on a given wall. The result has 2 components:
- bounce back: force necessary to the momentum change
- frozen particles: total interaction force exerted on the frozen particles
Parameters: - name – name of the plugin
- wall – The
Wall
to collect forces from - pvFrozen – corresponding frozen
ParticleVector
- sample_every – sample every this number of time steps
- dump_every – dump every this number of time steps
- filename – output filename (csv format)
- detailed_dump – if True, will dump separately the bounce contribution and the rest. If False, only the sum is dumped.
-
createWallRepulsion
(state: MirState, name: str, pv: ParticleVectors.ParticleVector, wall: Walls.Wall, C: float, h: float, max_force: float) → Tuple[Plugins.SimulationPlugin, Plugins.PostprocessPlugin]¶ This plugin will add force on all the particles that are nearby a specified wall. The motivation of this plugin is as follows. The particles of regular PVs are prevented from penetrating into the walls by Wall Bouncers. However, using Wall Bouncers with Object Vectors may be undesirable (e.g. in case of a very viscous membrane) or impossible (in case of rigid objects). In these cases one can use either strong repulsive potential between the object and the wall particle or alternatively this plugin. The advantage of the SDF-based repulsion is that small penetrations won’t break the simulation.
The force expression looks as follows:
\[\begin{split}\mathbf{F}(\mathbf{r}) = \mathbf{\nabla}S(\mathbf{r}) \cdot \begin{cases} 0, & S(\mathbf{r}) < -h,\\ \min(F_\text{max}, C (S(\mathbf{r}) + h)), & S(\mathbf{r}) \geqslant -h,\\ \end{cases}\end{split}\]where \(S\) is the SDF of the wall, \(C\), \(F_\text{max}\) and \(h\) are parameters.
Parameters: - name – name of the plugin
- pv –
ParticleVector
that we’ll work with - wall –
Wall
that defines the repulsion - C – \(C\)
- h – \(h\)
- max_force – \(F_{max}\)