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

AddForce This plugin will add constant force \(\mathbf{F}_{extra}\) to each particle of a specific PV every time-step.
AddTorque This plugin will add constant torque \(\mathbf{T}_{extra}\) to each object of a specific OV every time-step.
Average3D 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 (LINK) format with HDF5 (LINK) backend.
AverageRelative3D This plugin acts just like the regular flow dumper, with one difference.
ExchangePVSFluxPlane This plugin exchanges particles from a particle vector crossing a given plane to another particle vector.
ImposeProfile 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.
ImposeVelocity 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.
MagneticOrientation This plugin gives a magnetic moment \(\mathbf{M}\) to every rigid objects in a given RigidObjectVector.
MembraneExtraForce This plugin adds a given external force to a given membrane.
MeshPlugin This plugin will write the meshes of all the object of the specified Object Vector in a PLY format (LINK).
ObjPositions This plugin will write the coordinates of the centers of mass of the objects of the specified Object Vector.
ParticleSenderPlugin This plugin will dump positions, velocities and optional attached data of all the particles of the specified Particle Vector.
ParticleWithMeshDumperPlugin Postprocess side plugin of ParticleWithMeshSenderPlugin.
ParticleWithMeshSenderPlugin This plugin will dump positions, velocities and optional attached data of all the particles of the specified Object Vector, as well as connectivity information.
PinObject This plugin will impose given velocity as the center of mass velocity (by axis) of all the objects of the specified Object Vector.
PostprocessPlugin Base postprocess plugin class
SimulationPlugin Base simulation plugin class
SimulationStats 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.
Temperaturize This plugin changes the velocity of each particles from a given ParticleVector.
VelocityControl This plugin applies a uniform force to all the particles of the target PVS in the specified area (rectangle).
WallRepulsion This plugin will add force on all the particles that are nearby a specified wall.
XYZPlugin This plugin will dump positions of all the particles of the specified Particle Vector in the XYZ format.

Creation functions

createAddForce(name, pv, force, float, float]) Create AddForce plugin
createAddTorque(name, ov, torque, float, float]) Create AddTorque plugin
createDumpAverage(name, pvs, sample_every, …) Create Average3D plugin
createDumpAverageRelative(name, pvs, …) Create AverageRelative3D plugin
createDumpMesh(name, ov, dump_every, path) Create MeshPlugin plugin
createDumpObjectStats(name, ov, dump_every, path) Create ObjPositions plugin
createDumpParticles(name, pv, dump_every, …) Create ParticleSenderPlugin plugin
createDumpParticlesWithMesh(name, ov, …) Create ParticleWithMeshSenderPlugin plugin
createDumpXYZ(name, pv, dump_every, path) Create XYZPlugin plugin
createExchangePVSFluxPlane(name, pv1, pv2, …) Create ExchangePVSFluxPlane plugin
createImposeProfile(name, pv, low, float, …) Create ImposeProfile plugin
createImposeVelocity(name, pvs, every, low, …) Create ImposeVelocity plugin
createMagneticOrientation(name, rov, moment, …) Create MagneticOrientation plugin
createMembraneExtraForce(name, pv, forces) Create MembraneExtraForce plugin
createPinObject(name, ov, dump_every, path, …) Create PinObject plugin
createStats(name, filename, every) Create SimulationStats plugin
createTemperaturize(name, pv, kbt, keepVelocity) Create Temperaturize plugin
createVelocityControl(name, filename, pvs, …) Create VelocityControl plugin
createWallRepulsion(name, pv, wall, C, h, …) Create WallRepulsion plugin

Details

class AddForce

Bases: _ymero.Plugins.SimulationPlugin

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.

class AddTorque

Bases: _ymero.Plugins.SimulationPlugin

This plugin will add constant torque \(\mathbf{T}_{extra}\) to each object of a specific OV every time-step.

class Average3D

Bases: _ymero.Plugins.SimulationPlugin

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 (LINK) format with HDF5 (LINK) 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.

Note

This plugin is inactive if postprocess is disabled

class AverageRelative3D

Bases: _ymero.Plugins.SimulationPlugin

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

class ExchangePVSFluxPlane

Bases: _ymero.Plugins.SimulationPlugin

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

class ImposeProfile

Bases: _ymero.Plugins.SimulationPlugin

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.

class ImposeVelocity

Bases: _ymero.Plugins.SimulationPlugin

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.

set_target_velocity(arg0: Tuple[float, float, float]) → None
class MagneticOrientation

Bases: _ymero.Plugins.SimulationPlugin

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 float (time) as input and output a tuple of three floats (magnetic field).

class MembraneExtraForce

Bases: _ymero.Plugins.SimulationPlugin

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.

class MeshDumper

Bases: _ymero.Plugins.PostprocessPlugin

Postprocess side plugin of MeshPlugin. Responsible for performing the data reductions and I/O.

class MeshPlugin

Bases: _ymero.Plugins.SimulationPlugin

This plugin will write the meshes of all the object of the specified Object Vector in a PLY format (LINK).

Note

This plugin is inactive if postprocess is disabled

class ObjPositions

Bases: _ymero.Plugins.SimulationPlugin

This plugin will write the coordinates of the centers of mass of the objects of the specified Object Vector. If the objects are rigid bodies, also will be written: COM velocity, rotation, angular velocity, force, torque.

The file format is the following:

<object id> <simulation time> <COM>x3 [<quaternion>x4 <velocity>x3 <angular velocity>x3 <force>x3 <torque>x3]

Note

Note that all the written values are instantaneous

Note

This plugin is inactive if postprocess is disabled

class ObjPositionsDumper

Bases: _ymero.Plugins.PostprocessPlugin

Postprocess side plugin of ObjPositions. Responsible for performing the I/O.

class ParticleDumperPlugin

Bases: _ymero.Plugins.PostprocessPlugin

Postprocess side plugin of ParticleSenderPlugin. Responsible for performing the I/O.

class ParticleSenderPlugin

Bases: _ymero.Plugins.SimulationPlugin

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.

class ParticleWithMeshDumperPlugin

Bases: _ymero.Plugins.PostprocessPlugin

Postprocess side plugin of ParticleWithMeshSenderPlugin. Responsible for performing the I/O.

class ParticleWithMeshSenderPlugin

Bases: _ymero.Plugins.SimulationPlugin

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.

class PinObject

Bases: _ymero.Plugins.SimulationPlugin

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, rotatation may be restricted with this plugin as well. The time-averaged force and/or torque required to impose the velocities and rotations are reported.

Note

This plugin is inactive if postprocess is disabled

class PostprocessPlugin

Bases: object

Base postprocess plugin class

class PostprocessStats

Bases: _ymero.Plugins.PostprocessPlugin

Postprocess side plugin of SimulationStats. Responsible for performing the data reductions and I/O.

class PostprocessVelocityControl

Bases: _ymero.Plugins.PostprocessPlugin

Postprocess side plugin of VelocityControl. Responsible for performing the I/O.

class ReportPinObject

Bases: _ymero.Plugins.PostprocessPlugin

Postprocess side plugin of PinObject. Responsible for performing the I/O.

class SimulationPlugin

Bases: object

Base simulation plugin class

class SimulationStats

Bases: _ymero.Plugins.SimulationPlugin

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

class Temperaturize

Bases: _ymero.Plugins.SimulationPlugin

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.

class UniformCartesianDumper

Bases: _ymero.Plugins.PostprocessPlugin

Postprocess side plugin of Average3D or AverageRelative3D. Responsible for performing the I/O.

get_channel_view(arg0: str) → array
class VelocityControl

Bases: _ymero.Plugins.SimulationPlugin

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.

class WallRepulsion

Bases: _ymero.Plugins.SimulationPlugin

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{\nabla}_{sdf} \cdot \begin{cases} 0, & sdf < -h\\ \min(F_{max}, C (sdf + h)), & sdf \geqslant -h\\ \end{cases}\end{split}\]
class XYZDumper

Bases: _ymero.Plugins.PostprocessPlugin

Postprocess side plugin of XYZPlugin. Responsible for the I/O part.

class XYZPlugin

Bases: _ymero.Plugins.SimulationPlugin

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

createAddForce(name: str, pv: ParticleVectors.ParticleVector, force: Tuple[float, float, float]) → Tuple[Plugins.AddForce, Plugins.PostprocessPlugin]

Create AddForce plugin

Parameters:
  • name – name of the plugin
  • pvParticleVector that we’ll work with
  • force – extra force
createAddTorque(name: str, ov: ParticleVectors.ParticleVector, torque: Tuple[float, float, float]) → Tuple[Plugins.AddTorque, Plugins.PostprocessPlugin]

Create AddTorque plugin

Parameters:
  • name – name of the plugin
  • ovObjectVector that we’ll work with
  • torque – extra torque (per object)
createDumpAverage(name: str, pvs: List[ParticleVectors.ParticleVector], sample_every: int, dump_every: int, bin_size: Tuple[float, float, float] = (1.0, 1.0, 1.0), channels: List[Tuple[str, str]], path: str = 'xdmf/') → Tuple[Plugins.Average3D, Plugins.UniformCartesianDumper]

Create Average3D plugin

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 pairs name - type. Name is the channel (per particle) name. Always available channels are:

    • ’velocity’ with type “float8”
    • ’force’ with type “float4”

    Type is to provide the type of quantity to extract from the channel. Type can also define a simple transformation from the channel internal structure to the datatype supported in HDF5 (i.e. scalar, vector, tensor) Available types are:

    • ’scalar’: 1 float per particle
    • ’vector’: 3 floats per particle
    • ’vector_from_float4’: 4 floats per particle. 3 first floats will form the resulting vector
    • ’vector_from_float8’ 8 floats per particle. 5th, 6th, 7th floats will form the resulting vector.
      This type is primarity made to be used with velocity since it is stored together with the coordinates as 8 consecutive float numbers: (x,y,z) coordinate, followed by 1 padding value and then (x,y,z) velocity, followed by 1 more padding value
    • ’tensor6’: 6 floats per particle, symmetric tensor in order xx, xy, xz, yy, yz, zz
createDumpAverageRelative(name: str, pvs: List[ParticleVectors.ParticleVector], relative_to_ov: ParticleVectors.ObjectVector, relative_to_id: int, sample_every: int, dump_every: int, bin_size: Tuple[float, float, float] = (1.0, 1.0, 1.0), channels: List[Tuple[str, str]], path: str = 'xdmf/') → Tuple[Plugins.AverageRelative3D, Plugins.UniformCartesianDumper]

Create AverageRelative3D plugin

The arguments are the same as for createDumpAverage() with a few additions

Parameters:
  • 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(name: str, ov: ParticleVectors.ObjectVector, dump_every: int, path: str) → Tuple[Plugins.MeshPlugin, Plugins.MeshDumper]

Create MeshPlugin plugin

Parameters:
  • name – name of the plugin
  • ovObjectVector 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(name: str, ov: ParticleVectors.ObjectVector, dump_every: int, path: str) → Tuple[Plugins.ObjPositions, Plugins.ObjPositionsDumper]

Create ObjPositions plugin

Parameters:
  • name – name of the plugin
  • ovObjectVector 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.txt
createDumpParticles(name: str, pv: ParticleVectors.ParticleVector, dump_every: int, channels: List[Tuple[str, str]], path: str) → Tuple[Plugins.ParticleSenderPlugin, Plugins.ParticleDumperPlugin]

Create ParticleSenderPlugin plugin

Parameters:
  • name – name of the plugin
  • pvParticleVector that we’ll work with
  • dump_every – write files every this many time-steps
  • 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 pairs name - type. Name is the channel (per particle) name. The “velocity” channel is always activated by default. Type is to provide the type of quantity to extract from the channel. Available types are:

    • ’scalar’: 1 float per particle
    • ’vector’: 3 floats per particle
    • ’tensor6’: 6 floats per particle, symmetric tensor in order xx, xy, xz, yy, yz, zz
createDumpParticlesWithMesh(name: str, ov: ParticleVectors.ObjectVector, dump_every: int, channels: List[Tuple[str, str]], path: str) → Tuple[Plugins.ParticleWithMeshSenderPlugin, Plugins.ParticleWithMeshDumperPlugin]

Create ParticleWithMeshSenderPlugin plugin

Parameters:
  • name – name of the plugin
  • ovObjectVector that we’ll work with
  • dump_every – write files every this many time-steps
  • 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 pairs name - type. Name is the channel (per particle) name. The “velocity” channel is always activated by default. Type is to provide the type of quantity to extract from the channel. Available types are:

    • ’scalar’: 1 float per particle
    • ’vector’: 3 floats per particle
    • ’tensor6’: 6 floats per particle, symmetric tensor in order xx, xy, xz, yy, yz, zz
createDumpXYZ(name: str, pv: ParticleVectors.ParticleVector, dump_every: int, path: str) → Tuple[Plugins.XYZPlugin, Plugins.XYZDumper]

Create XYZPlugin plugin

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(name: str, pv1: ParticleVectors.ParticleVector, pv2: ParticleVectors.ParticleVector, plane: Tuple[float, float, float, float]) → Tuple[Plugins.ExchangePVSFluxPlane, Plugins.PostprocessPlugin]

Create ExchangePVSFluxPlane plugin

Parameters:
  • name – name of the plugin
  • pv1ParticleVector source
  • pv2ParticleVector destination
  • plane – 4 coefficients for the plane equation ax + by + cz + d >= 0
createImposeProfile(name: str, pv: ParticleVectors.ParticleVector, low: Tuple[float, float, float], high: Tuple[float, float, float], velocity: Tuple[float, float, float], kbt: float) → Tuple[Plugins.ImposeProfile, Plugins.PostprocessPlugin]

Create ImposeProfile plugin

Parameters:
  • name – name of the plugin
  • pvParticleVector 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(name: str, pvs: List[ParticleVectors.ParticleVector], every: int, low: Tuple[float, float, float], high: Tuple[float, float, float], velocity: Tuple[float, float, float]) → Tuple[Plugins.ImposeVelocity, Plugins.PostprocessPlugin]

Create ImposeVelocity plugin

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
createMagneticOrientation(name: str, rov: ParticleVectors.RigidObjectVector, moment: Tuple[float, float, float], magneticFunction: Callable[[float], Tuple[float, float, float]]) → Tuple[Plugins.MagneticOrientation, Plugins.PostprocessPlugin]

Create MagneticOrientation plugin

Parameters:
  • name – name of the plugin
  • rovRigidObjectVector with which the magnetic field will interact
  • moment – magnetic moment per object
  • magneticFunction – a function that depends on time and returns a uniform (float3) magnetic field
createMembraneExtraForce(name: str, pv: ParticleVectors.ParticleVector, forces: List[List[float[3]]]) → Tuple[Plugins.MembraneExtraForce, Plugins.PostprocessPlugin]

Create MembraneExtraForce plugin

Parameters:
  • name – name of the plugin
  • pvParticleVector to which the force should be added
  • forces – array of forces, one force (3 floats) per vertex in a single mesh
createPinObject(name: str, ov: ParticleVectors.ObjectVector, dump_every: int, path: str, velocity: Tuple[float, float, float], angular_velocity: Tuple[float, float, float]) → Tuple[Plugins.PinObject, Plugins.ReportPinObject]

Create PinObject plugin

Parameters:
  • name – name of the plugin
  • ovObjectVector 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.txt
  • velocity – 3 floats, each component is the desired object velocity. If the corresponding component should not be restricted, set this value to PinObject::Unrestricted
  • angular_velocity – 3 floats, each component is the desired object angular velocity. If the corresponding component should not be restricted, set this value to PinObject::Unrestricted
createStats(name: str, filename: str = '', every: int) → Tuple[Plugins.SimulationStats, Plugins.PostprocessStats]

Create SimulationStats plugin

Parameters:
  • name – name of the plugin
  • filename – the stats will also be recorded to that file in a computer-friendly way
  • every – report to standard output every that many time-steps
createTemperaturize(name: str, pv: ParticleVectors.ParticleVector, kbt: float, keepVelocity: bool) → Tuple[Plugins.Temperaturize, Plugins.PostprocessPlugin]

Create Temperaturize plugin

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.
createVelocityControl(name: str, filename: str, pvs: List[ParticleVectors.ParticleVector], low: Tuple[float, float, float], high: Tuple[float, float, float], sample_every: int, tune_every: int, dump_every: int, target_vel: Tuple[float, float, float], Kp: float, Ki: float, Kd: float) → Tuple[Plugins.VelocityControl, Plugins.PostprocessVelocityControl]

Create VelocityControl plugin

Parameters:
  • name – name of the plugin
  • filename – dump file name
  • 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
createWallRepulsion(name: str, pv: ParticleVectors.ParticleVector, wall: Walls.Wall, C: float, h: float, max_force: float) → Tuple[Plugins.WallRepulsion, Plugins.PostprocessPlugin]

Create WallRepulsion plugin

Parameters:
  • name – name of the plugin
  • pvParticleVector that we’ll work with
  • wallWall that defines the repulsion
  • C\(C\)
  • h\(h\)
  • max_force\(F_{max}\)