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
Inheritance diagram of mmirheo.ParticleVectors.ChainVector, mmirheo.ParticleVectors.DataManager, mmirheo.ParticleVectors.LocalObjectVector, mmirheo.ParticleVectors.LocalParticleVector, mmirheo.ParticleVectors.MembraneVector, mmirheo.ParticleVectors.ObjectVector, mmirheo.ParticleVectors.ParticleVector, mmirheo.ParticleVectors.RigidCapsuleVector, mmirheo.ParticleVectors.RigidCylinderVector, mmirheo.ParticleVectors.RigidEllipsoidVector, mmirheo.ParticleVectors.RigidObjectVector, mmirheo.ParticleVectors.RodVector

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
  • meshMembraneMesh 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
  • meshMesh 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