Particles and Clusters

mechanica.Particle: alias of mechanica.mechanica.MxParticle

mechanica.ParticleHandle: alias of mechanica.mechanica.MxParticleHandle

class mechanica.MxParticle

The particle data structure.

Instance vars for each particle.

Note that the arrays for x, v and f are 4 entries long for proper alignment.

All particles are stored in a series of contiguous blocks of memory that are owned by the space cells. Each space cell has a array of particle structs.

If you’re building a model, you should probably instead be working with a MxParticleHandle.

py_particle() → MxParticleHandle *

Get a handle for this particle.

Return type: MxParticleHandle
Returns: struct MxParticleHandle*

toString() → std::string

Get a JSON string representation

Return type: string
Returns: std::string

static fromString(str: std::string const &) → MxParticle *

Create from a JSON string representation.

The returned particle is not automatically registered with the engine.

To properly register a particle from a string, pass the string to the particle constructor of the appropriate particle type or cluster.

Parameters: str (string) –
Return type: MxParticle
Returns: MxParticle*

__reduce__(): Helper for pickle.

class mechanica.MxParticleHandle(*args)

A handle to a particle.

The engine allocates particle memory in blocks, and particle values get moved around all the time, so their addresses change.

The partlist is always ordered by id, i.e. partlist[id] always points to the same particle, even though that particle may move from cell to cell.

This is a safe way to work with a particle.

property charge: Particle charge

property mass: Particle mass

property frozen: Particle frozen flag

property frozen_x: Particle frozen flag along x

property frozen_y: Particle frozen flag along y

property frozen_z: Particle frozen flag along z

property style: Particle style

property age: Particle age

property radius: Particle radius

property name: Particle name

property position: Particle position

property velocity: Particle velocity

property force: Net force acting on particle

property force_init: Persistent force acting on particle

property id: Particle id

property type_id: Particle type id

property cluster_id: Cluster particle id, if any; -1 if particle is not in a cluster

property species: Particle species

property bonds: Bonds attached to particle

property angles: Angles attached to particle

property dihedrals: Dihedrals attached to particle

part() → MxParticle *

Gets the actual particle of this handle.

Return type: MxParticle
Returns: MxParticle*

type() → MxParticleType *

Gets the particle type of this handle.

Return type: MxParticleType
Returns: MxParticleType*

split() → MxParticleHandle *

Splits a single particle into two. Returns the new particle.

Return type: MxParticleHandle
Returns: MxParticleHandle*

destroy() → HRESULT

Destroys the particle, and removes it from inventory.

Subsequent references to a destroyed particle result in an error.

Return type: int
Returns: HRESULT

sphericalPosition(particle: Optional[mechanica.mechanica.MxParticle] = None, origin: Optional[mechanica.mechanica.MxVector3f] = None) → mechanica.mechanica.MxVector3f

Calculates the particle’s coordinates in spherical coordinates.

By default, calculations are made with respect to the center of the universe.

Parameters

particle (MxParticle) – a particle to use as the origin, optional
origin (MxVector3f) – a point to use as the origin, optional

Return type

MxVector3f

Returns

MxVector3f

virial(radius: float * = None) → MxMatrix3f

Computes the virial tensor. Optionally pass a distance to include a neighborhood.

Parameters: radius (float) – A distance to define a neighborhood, optional
Return type: MxMatrix3f
Returns: MxMatrix3f

become(type: MxParticleType) → HRESULT

Dynamically changes the type of an object. We can change the type of a MxParticleType-derived object to anyther pre-existing MxParticleType-derived type. What this means is that if we have an object of say type A, we can change it to another type, say B, and and all of the forces and processes that acted on objects of type A stip and the forces and processes defined for type B now take over.

Parameters: type (MxParticleType) – new particle type
Return type: int
Returns: HRESULT

neighbors(distance: float const * = None, types: vectorParticleType = None) → MxParticleList *

Gets a list of nearby particles.

Parameters

distance (float) – optional search distance; default is simulation cutoff
types (std::vector< MxParticleType,std::allocator< MxParticleType > >) – optional list of particle types to search by; default is all types

Return type

MxParticleList

Returns

MxParticleList*

getBondedNeighbors() → MxParticleList *

Gets a list of all bonded neighbors.

Return type: MxParticleList
Returns: MxParticleList*

distance(_other: mechanica.mechanica.MxParticleHandle) → float

Calculates the distance to another particle

Parameters: _other (MxParticleHandle) – another particle.
Return type: float
Returns: float

to_cluster() → MxClusterParticleHandle *: Limits casting to cluster by type

class mechanica.ParticleType

Interface for class-centric design of MxParticleType

mass = None: Particle type mass

charge = None: Particle type charge

radius = None: Particle type radius

target_energy = None: Particle type target energy

minimum_radius = None: Particle type minimum radius

eps = None: Particle type nonbonded interaction parameter

rmin = None: Particle type nonbonded interaction parameter

dynamics = None: Particle type dynamics flag

frozen = None: Particle type frozen flag

name = None: Particle type name

name2 = None: Particle type second name

style = None

Particle type style dictionary specification.

Basic rendering details can be specified as a dictionary, like color and visibility,

style = {'color': 'CornflowerBlue', 'visible': False}

This declaration is the same as performing operations on a type after registration,

ptype: MxParticleType
ptype.style.setColor('CornflowerBlue')
ptype.style.setVisible(False)

Rendering instead by species and species amount uses specification for a color mapper,

style = {'colormap': {'species': 'S1', 'map': 'rainbow', 'range': (0, 10)}}

This declaration is the same as performing operations on a type after registration,

ptype: MxParticleType
ptype.style.newColorMapper(partType=ptype, speciesName='S1', name='rainbow', min=0, max=10)

species = None: Particle type list of species by name, if any. Species are automatically created and populated in the state vector of the type and all created particles.

classmethod get()

Get the engine type that corresponds to this class.

The type is automatically registered as necessary.

Returns: registered type instance
Return type: mechanica.MxParticleType

class mechanica.MxParticleType(noReg: bool const & = False)

Structure containing information on each particle type.

This is only a definition for a type of particle, and not an actual particle with position, velocity, etc. However, particles of this type can be created with one of these.

property frozen: Particle type frozen flag

property frozen_x: Particle type frozen flag along x

property frozen_y: Particle type frozen flag along y

property frozen_z: Particle type frozen flag along z

property temperature: Particle type temperature

property target_temperature: Particle type target temperature

id: ID of this type

mass: Default mass of particles

charge: Default charge of particles

radius: Default radius of particles

kinetic_energy: Kinetic energy of all particles of this type.

potential_energy: Potential energy of all particles of this type.

target_energy: Target energy of all particles of this type.

minimum_radius

Default minimum radius of this type.

If a split event occurs, resulting particles will have a radius at least as great as this value.

dynamics: Default dynamics of particles of this type.

name: Name of this particle type.

style: style pointer, optional.

species: optional pointer to species list. This is the metadata for the species

parts: list of particles that belong to this type.

particle(i: int) → MxParticle *

get the i’th particle that’s a member of this type.

Parameters: i (int) – index of particle to get
Return type: MxParticle
Returns: MxParticle*

static particleTypeIds() → std::set< short,std::less< short >,std::allocator< short > >

Get all current particle type ids, excluding clusters

Return type: std::set< short,std::less< short >,std::allocator< short > >
Returns: std::set<int>

__call__(*args, **kwargs)

Call self as a function.

Alias of _call

_call(*args) → MxParticleHandle *

Overload 1:

Particle constructor.

Automatically updates when running on a CUDA device.

Parameters

position (MxVector3f) – position of new particle, optional
velocity (MxVector3f) – velocity of new particle, optional
clusterId (int) – id of parent cluster, optional

Return type

MxParticleHandle

Returns

MxParticleHandle*

Overload 2:

Particle constructor.

Automatically updates when running on a CUDA device.

Parameters

str (string) – JSON string
clusterId (int) – id of parent cluster, optional

Return type

MxParticleHandle

Returns

MxParticleHandle*

newType(_name: char const *) → MxParticleType *

Particle type constructor.

New type is constructed from the definition of the calling type.

Parameters: _name (string) – name of the new type
Return type: MxParticleType
Returns: MxParticleType*

registerType() → HRESULT

Registers a type with the engine.

Note that this occurs automatically, unless noReg==true in constructor.

Return type: int
Returns: HRESULT

on_register() → void: A callback for when a type is registered

isRegistered() → bool

Tests whether this type is registered

Return type: boolean
Returns: true if registered

get() → MxParticleType *

Get the type engine instance

Return type: MxParticleType
Returns: MxParticleType*

items() → MxParticleList *

Get all particles of this type.

Return type: MxParticleList
Returns: MxParticleList*

isCluster() → bool

to_cluster() → MxClusterParticleType *: Limits casting to cluster by type

toString() → std::string

Get a JSON string representation

Return type: string
Returns: std::string

static fromString(str: std::string const &) → MxParticleType *

Create from a JSON string representation.

The returned type is automatically registered with the engine.

Parameters: str (string) –
Return type: MxParticleType
Returns: MxParticleType*

__reduce__(): Helper for pickle.

mechanica.Cluster: alias of mechanica.mechanica.MxCluster

mechanica.ClusterHandle: alias of mechanica.mechanica.MxClusterParticleHandle

class mechanica.MxCluster

Bases: mechanica.mechanica.MxParticle

The cluster analogue to MxParticle.

class mechanica.MxClusterParticleHandle(*args)

Bases: mechanica.mechanica.MxParticleHandle

The cluster analogue to MxParticleHandle.

These are special in that they can create particles of their constituent particle types, much like a MxParticleType.

property radius_of_gyration: Radius of gyration

property center_of_mass: Center of mass

property centroid: Centroid

property moment_of_inertia: Moment of inertia

items = <function MxClusterParticleHandle.items>

__call__(particle_type, *args, **kwargs)

Call self as a function.

Alias of _call

_call(*args) → MxParticleHandle *

Overload 1:

Constituent particle constructor.

The created particle will belong to this cluster.

Automatically updates when running on a CUDA device.

Parameters

partType (MxParticleType) – type of particle to create
position (MxVector3f) – position of new particle, optional
velocity (MxVector3f) – velocity of new particle, optional

Return type

MxParticleHandle

Returns

MxParticleHandle*

Overload 2:

Constituent particle constructor.

The created particle will belong to this cluster.

Automatically updates when running on a CUDA device.

Parameters

partType (MxParticleType) – type of particle to create
str (string) – JSON string

Return type

MxParticleHandle

Returns

MxParticleHandle*

cluster() → MxCluster *

Gets the actual cluster of this handle.

Return type: MxCluster
Returns: MxParticle*

split(axis: MxVector3f = None, random: bool * = None, time: float * = None, normal: MxVector3f = None, point: MxVector3f = None) → MxParticleHandle *

Split the cluster.

Parameters

axis (MxVector3f) – axis of split, optional
random (boolean) – divide by randomly and evenly allocating constituent particles, optional
time (float) – time at which to implement the split; currently not supported
normal (MxVector3f) – normal vector of cleavage plane, optional
point (MxVector3f) – point on cleavage plane, optional

Return type