Particle Vectors

A ParticleVector (or PV) is a collection of particles in the simulation with identical properties. PV is the minimal unit of particles that can be addressed by most of the processing utilities, i.e. it is possible to specify interactions between different (or same) PVs, apply integrators, plugins, etc. to the PVs.

Each particle in the PV keeps its coordinate, velocity and force. Additional quantities may also be stored in a form of extra channels. These quantities are usually added and used by specific handlers, and can in principle be written in XDMF format (createDumpParticles), see more details in the Developer documentation.

A common special case of a ParticleVector is an ObjectVector (or OV). The OV is a Particle Vector with the particles separated into groups (objects) of the same size. For example, if a single cell membrane is represented by say 500 particles, an object vector consisting of the membranes will contain all the particles of all the membranes, grouped by membrane. Objects are assumed to be spatially localized, so they always fully reside within a single MPI process. OV can be used in most of the places where a regular PV can be used, and more

Reserved names

A list of name are reserved by Mirheo. When a user provides a custom channel name, it needs to be different than these reserved fields:

• Reserved particle channel fields:

  • “ids”
  • “positions”
  • “velocities”
  • “__forces”
  • “stresses”
  • “densities”
  • “old_positions”
  • “Q”
  • “dQdt”

• Reserved object channel fields:

  • “ids”
  • “motions”
  • “old_motions”
  • “com_extents”
  • “area_volumes”
  • “membrane_type_id”
  • “areas”
  • “mean_curvatures”
  • “len_theta_tot”

• Reserved bisegment channel fields:

  • “states”
  • “energies”
  • “biseg_kappa”
  • “biseg_tau_l”

Summary

ChainVector()	Object Vector representing chain of particles.
DataManager()	A collection of channels in pinned memory.
LocalObjectVector()	Object vector local data storage, additionally contains object channels.
LocalParticleVector()	Particle local data storage, composed of particle channels.
MembraneMesh()	Internally used class for desctibing a triangular mesh that can be used with the Membrane Interactions.
MembraneVector()	Membrane is an Object Vector representing cell membranes.
Mesh()	Internally used class for describing a simple triangular mesh
ObjectVector()	Basic Object Vector.
ParticleVector()	Basic particle vector, consists of identical disconnected particles.
RigidCapsuleVector()	RigidObjectVector specialized for capsule shapes.
RigidCylinderVector()	RigidObjectVector specialized for cylindrical shapes.
RigidEllipsoidVector()	RigidObjectVector specialized for ellipsoidal shapes.
RigidObjectVector()	Rigid Object is an Object Vector representing objects that move as rigid bodies, with no relative displacement against each other in an object.
RodVector()	Rod Vector is an ObjectVector which reprents rod geometries.
getReservedBisegmentChannels()	Return the list of reserved channel names per bisegment fields
getReservedObjectChannels()	Return the list of reserved channel names for object fields
getReservedParticleChannels()	Return the list of reserved channel names for particle fields

Details

class ChainVector

Bases: mmirheo.ParticleVectors.ObjectVector

Object Vector representing chain of particles.

__init__(name: str, mass: float, chain_length: int) → None

Parameters:

• name – name of the created PV
• mass – mass of a single particle
• chain_length – number of particles per chain

getCoordinates(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of coordinate for every of the N particles Return type:A list of \(N \times 3\) reals

getForces(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of force for every of the N particles Return type:A list of \(N \times 3\) reals

getVelocities(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of velocity for every of the N particles Return type:A list of \(N \times 3\) reals

get_indices(self: ParticleVectors.ParticleVector) → List[int]

Returns:A list of unique integer particle identifiers

halo

The halo LocalObjectVector instance, the storage of halo objects.

local

The local LocalObjectVector instance, the storage of local objects.

setCoordinates(coordinates: List[real3]) → None

Parameters:coordinates – A list of \(N \times 3\) reals: 3 components of coordinate for every of the N particles

setForces(forces: List[real3]) → None

Parameters:forces – A list of \(N \times 3\) reals: 3 components of force for every of the N particles

setVelocities(velocities: List[real3]) → None

Parameters:velocities – A list of \(N \times 3\) reals: 3 components of velocity for every of the N particles

class DataManager

Bases: object

A collection of channels in pinned memory.

__init__()

Initialize self. See help(type(self)) for accurate signature.

class LocalObjectVector

Bases: mmirheo.ParticleVectors.LocalParticleVector

Object vector local data storage, additionally contains object channels.

__init__()

Initialize self. See help(type(self)) for accurate signature.

per_object

The DataManager that contains the object channels.

per_particle

The DataManager that contains the particle channels.

class LocalParticleVector

Bases: object

Particle local data storage, composed of particle channels.

__init__()

Initialize self. See help(type(self)) for accurate signature.

per_particle

The DataManager that contains the particle channels.

class MembraneMesh

Bases: mmirheo.ParticleVectors.Mesh

Internally used class for desctibing a triangular mesh that can be used with the Membrane Interactions. In contrast with the simple Mesh, this class precomputes some required quantities on the mesh, including connectivity structures and stress-free quantities.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(off_filename: str) -> None

   Create a mesh by reading the OFF file. The stress free shape is the input initial mesh

   Args:

   off_filename: path of the OFF file

2. __init__(off_initial_mesh: str, off_stress_free_mesh: str) -> None

   Create a mesh by reading the OFF file, with a different stress free shape.

   Args:

   off_initial_mesh: path of the OFF file : initial mesh off_stress_free_mesh: path of the OFF file : stress-free mesh)

3. __init__(vertices: List[real3], faces: List[int3]) -> None

   Create a mesh by giving coordinates and connectivity

   Args:

   vertices: vertex coordinates faces: connectivity: one triangle per entry, each integer corresponding to the vertex indices

4. __init__(vertices: List[real3], stress_free_vertices: List[real3], faces: List[int3]) -> None

   Create a mesh by giving coordinates and connectivity, with a different stress-free shape.

   Args:

   vertices: vertex coordinates stress_free_vertices: vertex coordinates of the stress-free shape faces: connectivity: one triangle per entry, each integer corresponding to the vertex indices

getFaces(self: ParticleVectors.Mesh) → List[List[int[3]]]

returns the vertex indices for each triangle of the mesh.

getVertices(self: ParticleVectors.Mesh) → List[List[float[3]]]

returns the vertex coordinates of the mesh.

class MembraneVector

Bases: mmirheo.ParticleVectors.ObjectVector

Membrane is an Object Vector representing cell membranes. It must have a triangular mesh associated with it such that each particle is mapped directly onto single mesh vertex.

__init__(name: str, mass: float, mesh: ParticleVectors.MembraneMesh) → None

Parameters:

• name – name of the created PV
• mass – mass of a single particle
• mesh – MembraneMesh object

getCoordinates(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of coordinate for every of the N particles Return type:A list of \(N \times 3\) reals

getForces(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of force for every of the N particles Return type:A list of \(N \times 3\) reals

getVelocities(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of velocity for every of the N particles Return type:A list of \(N \times 3\) reals

get_indices(self: ParticleVectors.ParticleVector) → List[int]

Returns:A list of unique integer particle identifiers

halo

The halo LocalObjectVector instance, the storage of halo objects.

local

The local LocalObjectVector instance, the storage of local objects.

setCoordinates(coordinates: List[real3]) → None

Parameters:coordinates – A list of \(N \times 3\) reals: 3 components of coordinate for every of the N particles

setForces(forces: List[real3]) → None

Parameters:forces – A list of \(N \times 3\) reals: 3 components of force for every of the N particles

setVelocities(velocities: List[real3]) → None

Parameters:velocities – A list of \(N \times 3\) reals: 3 components of velocity for every of the N particles

class Mesh

Bases: object

Internally used class for describing a simple triangular mesh

__init__(*args, **kwargs)

Overloaded function.

1. __init__(off_filename: str) -> None

   Create a mesh by reading the OFF file

   Args:

   off_filename: path of the OFF file

2. __init__(vertices: List[real3], faces: List[int3]) -> None

   Create a mesh by giving coordinates and connectivity

   Args:

   vertices: vertex coordinates faces: connectivity: one triangle per entry, each integer corresponding to the vertex indices

getFaces(self: ParticleVectors.Mesh) → List[List[int[3]]]

returns the vertex indices for each triangle of the mesh.

getVertices(self: ParticleVectors.Mesh) → List[List[float[3]]]

returns the vertex coordinates of the mesh.

class ObjectVector

Bases: mmirheo.ParticleVectors.ParticleVector

Basic Object Vector. An Object Vector stores chunks of particles, each chunk belonging to the same object.

Warning

In case of interactions with other ParticleVector, the extents of the objects must be smaller than a subdomain size. The code only issues a run time warning but it is the responsibility of the user to ensure this condition for correctness.

__init__()

Initialize self. See help(type(self)) for accurate signature.

getCoordinates(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of coordinate for every of the N particles Return type:A list of \(N \times 3\) reals

getForces(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of force for every of the N particles Return type:A list of \(N \times 3\) reals

getVelocities(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of velocity for every of the N particles Return type:A list of \(N \times 3\) reals

get_indices(self: ParticleVectors.ParticleVector) → List[int]

Returns:A list of unique integer particle identifiers

halo

The halo LocalObjectVector instance, the storage of halo objects.

local

The local LocalObjectVector instance, the storage of local objects.

setCoordinates(coordinates: List[real3]) → None

Parameters:coordinates – A list of \(N \times 3\) reals: 3 components of coordinate for every of the N particles

setForces(forces: List[real3]) → None

Parameters:forces – A list of \(N \times 3\) reals: 3 components of force for every of the N particles

setVelocities(velocities: List[real3]) → None

Parameters:velocities – A list of \(N \times 3\) reals: 3 components of velocity for every of the N particles

class ParticleVector

Bases: object

Basic particle vector, consists of identical disconnected particles.

__init__(name: str, mass: float) → None

Parameters:

• name – name of the created PV
• mass – mass of a single particle

getCoordinates(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of coordinate for every of the N particles Return type:A list of \(N \times 3\) reals

getForces(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of force for every of the N particles Return type:A list of \(N \times 3\) reals

getVelocities(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of velocity for every of the N particles Return type:A list of \(N \times 3\) reals

get_indices(self: ParticleVectors.ParticleVector) → List[int]

Returns:A list of unique integer particle identifiers

halo

The halo LocalParticleVector instance, the storage of halo particles.

local

The local LocalParticleVector instance, the storage of local particles.

setCoordinates(coordinates: List[real3]) → None

Parameters:coordinates – A list of \(N \times 3\) reals: 3 components of coordinate for every of the N particles

setForces(forces: List[real3]) → None

Parameters:forces – A list of \(N \times 3\) reals: 3 components of force for every of the N particles

setVelocities(velocities: List[real3]) → None

Parameters:velocities – A list of \(N \times 3\) reals: 3 components of velocity for every of the N particles

class RigidCapsuleVector

Bases: mmirheo.ParticleVectors.RigidObjectVector

RigidObjectVector specialized for capsule shapes. The advantage is that it doesn’t need mesh and moment of inertia define, as those can be computed analytically.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(name: str, mass: float, object_size: int, radius: float, length: float) -> None

   Args:

   name: name of the created PV mass: mass of a single particle object_size: number of frozen particles per object radius: radius of the capsule length: length of the capsule between the half balls. The total height is then “length + 2 * radius”

2. __init__(name: str, mass: float, object_size: int, radius: float, length: float, mesh: ParticleVectors.Mesh) -> None

   Args:

   name: name of the created PV mass: mass of a single particle object_size: number of frozen particles per object radius: radius of the capsule length: length of the capsule between the half balls. The total height is then “length + 2 * radius” mesh: Mesh object representing the shape of the object. This is used for dump only.

getCoordinates(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of coordinate for every of the N particles Return type:A list of \(N \times 3\) reals

getForces(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of force for every of the N particles Return type:A list of \(N \times 3\) reals

getVelocities(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of velocity for every of the N particles Return type:A list of \(N \times 3\) reals

get_indices(self: ParticleVectors.ParticleVector) → List[int]

Returns:A list of unique integer particle identifiers

halo

The halo LocalObjectVector instance, the storage of halo objects.

local

The local LocalObjectVector instance, the storage of local objects.

setCoordinates(coordinates: List[real3]) → None

Parameters:coordinates – A list of \(N \times 3\) reals: 3 components of coordinate for every of the N particles

setForces(forces: List[real3]) → None

Parameters:forces – A list of \(N \times 3\) reals: 3 components of force for every of the N particles

setVelocities(velocities: List[real3]) → None

Parameters:velocities – A list of \(N \times 3\) reals: 3 components of velocity for every of the N particles

class RigidCylinderVector

Bases: mmirheo.ParticleVectors.RigidObjectVector

RigidObjectVector specialized for cylindrical shapes. The advantage is that it doesn’t need mesh and moment of inertia define, as those can be computed analytically.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(name: str, mass: float, object_size: int, radius: float, length: float) -> None

   Args:

   name: name of the created PV mass: mass of a single particle object_size: number of frozen particles per object radius: radius of the cylinder length: length of the cylinder

2. __init__(name: str, mass: float, object_size: int, radius: float, length: float, mesh: ParticleVectors.Mesh) -> None

   Args:

   name: name of the created PV mass: mass of a single particle object_size: number of frozen particles per object radius: radius of the cylinder length: length of the cylinder mesh: Mesh object representing the shape of the object. This is used for dump only.

getCoordinates(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of coordinate for every of the N particles Return type:A list of \(N \times 3\) reals

getForces(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of force for every of the N particles Return type:A list of \(N \times 3\) reals

getVelocities(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of velocity for every of the N particles Return type:A list of \(N \times 3\) reals

get_indices(self: ParticleVectors.ParticleVector) → List[int]

Returns:A list of unique integer particle identifiers

halo

The halo LocalObjectVector instance, the storage of halo objects.

local

The local LocalObjectVector instance, the storage of local objects.

setCoordinates(coordinates: List[real3]) → None

Parameters:coordinates – A list of \(N \times 3\) reals: 3 components of coordinate for every of the N particles

setForces(forces: List[real3]) → None

Parameters:forces – A list of \(N \times 3\) reals: 3 components of force for every of the N particles

setVelocities(velocities: List[real3]) → None

Parameters:velocities – A list of \(N \times 3\) reals: 3 components of velocity for every of the N particles

class RigidEllipsoidVector

Bases: mmirheo.ParticleVectors.RigidObjectVector

RigidObjectVector specialized for ellipsoidal shapes. The advantage is that it doesn’t need mesh and moment of inertia define, as those can be computed analytically.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(name: str, mass: float, object_size: int, semi_axes: real3) -> None

   Args:

   name: name of the created PV mass: mass of a single particle object_size: number of frozen particles per object semi_axes: ellipsoid principal semi-axes

2. __init__(name: str, mass: float, object_size: int, semi_axes: real3, mesh: ParticleVectors.Mesh) -> None

   Args:

   name: name of the created PV mass: mass of a single particle object_size: number of frozen particles per object radius: radius of the cylinder semi_axes: ellipsoid principal semi-axes mesh: Mesh object representing the shape of the object. This is used for dump only.

getCoordinates(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of coordinate for every of the N particles Return type:A list of \(N \times 3\) reals

getForces(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of force for every of the N particles Return type:A list of \(N \times 3\) reals

getVelocities(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of velocity for every of the N particles Return type:A list of \(N \times 3\) reals

get_indices(self: ParticleVectors.ParticleVector) → List[int]

Returns:A list of unique integer particle identifiers

halo

The halo LocalObjectVector instance, the storage of halo objects.

local

The local LocalObjectVector instance, the storage of local objects.

setCoordinates(coordinates: List[real3]) → None

Parameters:coordinates – A list of \(N \times 3\) reals: 3 components of coordinate for every of the N particles

setForces(forces: List[real3]) → None

Parameters:forces – A list of \(N \times 3\) reals: 3 components of force for every of the N particles

setVelocities(velocities: List[real3]) → None

Parameters:velocities – A list of \(N \times 3\) reals: 3 components of velocity for every of the N particles

class RigidObjectVector

Bases: mmirheo.ParticleVectors.ObjectVector

Rigid Object is an Object Vector representing objects that move as rigid bodies, with no relative displacement against each other in an object. It must have a triangular mesh associated with it that defines the shape of the object.

__init__(name: str, mass: float, inertia: real3, object_size: int, mesh: ParticleVectors.Mesh) → None

Parameters:

• name – name of the created PV
• mass – mass of a single particle
• inertia – moment of inertia of the body in its principal axes. The principal axes of the mesh are assumed to be aligned with the default global OXYZ axes
• object_size – number of frozen particles per object
• mesh – Mesh object used for bounce back and dump

getCoordinates(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of coordinate for every of the N particles Return type:A list of \(N \times 3\) reals

getForces(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of force for every of the N particles Return type:A list of \(N \times 3\) reals

getVelocities(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of velocity for every of the N particles Return type:A list of \(N \times 3\) reals

get_indices(self: ParticleVectors.ParticleVector) → List[int]

Returns:A list of unique integer particle identifiers

halo

The halo LocalObjectVector instance, the storage of halo objects.

local

The local LocalObjectVector instance, the storage of local objects.

setCoordinates(coordinates: List[real3]) → None

Parameters:coordinates – A list of \(N \times 3\) reals: 3 components of coordinate for every of the N particles

setForces(forces: List[real3]) → None

Parameters:forces – A list of \(N \times 3\) reals: 3 components of force for every of the N particles

setVelocities(velocities: List[real3]) → None

Parameters:velocities – A list of \(N \times 3\) reals: 3 components of velocity for every of the N particles

class RodVector

Bases: mmirheo.ParticleVectors.ObjectVector

Rod Vector is an ObjectVector which reprents rod geometries.

__init__(name: str, mass: float, num_segments: int) → None

Parameters:

• name – name of the created Rod Vector
• mass – mass of a single particle
• num_segments – number of elements to discretize the rod

getCoordinates(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of coordinate for every of the N particles Return type:A list of \(N \times 3\) reals

getForces(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of force for every of the N particles Return type:A list of \(N \times 3\) reals

getVelocities(self: ParticleVectors.ParticleVector) → List[List[float[3]]]

Returns:3 components of velocity for every of the N particles Return type:A list of \(N \times 3\) reals

get_indices(self: ParticleVectors.ParticleVector) → List[int]

Returns:A list of unique integer particle identifiers

halo

The halo LocalObjectVector instance, the storage of halo objects.

local

The local LocalObjectVector instance, the storage of local objects.

setCoordinates(coordinates: List[real3]) → None

Parameters:coordinates – A list of \(N \times 3\) reals: 3 components of coordinate for every of the N particles

setForces(forces: List[real3]) → None

Parameters:forces – A list of \(N \times 3\) reals: 3 components of force for every of the N particles

setVelocities(velocities: List[real3]) → None

Parameters:velocities – A list of \(N \times 3\) reals: 3 components of velocity for every of the N particles

getReservedBisegmentChannels() → List[str]

Return the list of reserved channel names per bisegment fields

getReservedObjectChannels() → List[str]

Return the list of reserved channel names for object fields

getReservedParticleChannels() → List[str]

Return the list of reserved channel names for particle fields