Particles and Clusters

class tissue_forge.Particle

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 ParticleHandle.

handle() → TissueForge::ParticleHandle *: Get a handle for this particle.

toString() → std::string: Get a JSON string representation

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

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) – constructor string, as returned by toString
Return type:: Particle
Returns:: unregistered particle

__reduce__(): Helper for pickle.

class tissue_forge.ParticleHandle(*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 volume: Particle volume

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() → TissueForge::Particle *

Gets the actual particle of this handle.

Return type:: Particle
Returns:: particle, if available

get() → TissueForge::Particle *

Gets the actual particle of this handle.

Alias for consistency with other objects.

type() → TissueForge::ParticleType *: Gets the particle type of this handle.

split(*args) → TissueForge::ParticleHandle *

Overload 1:

Splits a single particle into two and returns the new particle.

Return type:: ParticleHandle
Returns:: new particle

Overload 2:

Splits a single particle into two along a direction.

Parameters:: direction (FVector3) – direction along which the particle is split.
Return type:: ParticleHandle
Returns:: new particle

destroy() → HRESULT

Destroys the particle and removes it from inventory.

Subsequent references to a destroyed particle result in an error.

sphericalPosition(particle: Particle = None, origin: fVector3 = None) → TissueForge::FVector3

Calculates the particle’s coordinates in spherical coordinates.

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

Parameters:

particle (Particle) – a particle to use as the origin, optional
origin (FVector3) – a point to use as the origin, optional

virial(radius: FPTYPE * = None) → TissueForge::FMatrix3

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

Parameters:: radius (float) – A distance to define a neighborhood, optional

become(type: ParticleType) → HRESULT

Dynamically changes the type of an object. We can change the type of a ParticleType-derived object to anyther pre-existing ParticleType-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 (ParticleType) – new particle type

neighbors(distance=None, types=None)

Gets a list of nearby particles.

Parameters:

distance – optional search distance; default is simulation cutoff
types – optional list of particle types to search by; default is all types

Return type:

ParticleList

bonded_neighbors(): All bonded neighbor ids.

distance(_other: ParticleHandle) → FPTYPE

Calculates the distance to another particle

Parameters:: _other (ParticleHandle) – another particle.

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

__str__() → str: Return str(self).

__lt__(rhs) → bool: Return self<value.

__gt__(rhs) → bool: Return self>value.

__le__(rhs) → bool: Return self<=value.

__ge__(rhs) → bool: Return self>=value.

__eq__(rhs) → bool: Return self==value.

__ne__(rhs) → bool: Return self!=value.

class tissue_forge.ParticleTypeSpec

Interface for class-centric design of ParticleType

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: ParticleType
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: ParticleType
ptype.style.mapper = rendering.ColorMapper('rainbow', 0, 10)
ptype.style.mapper.set_map_particle_species(ptype, 'S1')

Valid entries for data mapping are as follows,

‘force’: ‘x’, ‘y’ or ‘z’ for x-, y- or z-component of force
‘position’: ‘x’, ‘y’ or ‘z’ for x-, y- or z-component of position
‘species’: Name of a species attached to a particle type
‘velocity’: ‘x’, ‘y’, ‘z’ or ‘speed’ for x-, y-, z-component or magnitude of velocity

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:: tissue_forge.ParticleType

class tissue_forge.ParticleType(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

property volume: Particle type volume

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) → TissueForge::Particle *

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

Parameters:: i (int) – index of particle to get

static particleTypeIds() → std::set< short,std::less< short >,std::allocator< short > >: Get all current particle type ids, excluding clusters

__str__(): Return str(self).

__getitem__(index: int)

__contains__(item)

__lt__(rhs) → bool: Return self<value.

__gt__(rhs) → bool: Return self>value.

__le__(rhs) → bool: Return self<=value.

__ge__(rhs) → bool: Return self>=value.

__eq__(rhs) → bool: Return self==value.

__ne__(rhs) → bool: Return self!=value.

__call__(*args, **kwargs)

Call self as a function.

Alias of _call

_call(*args) → TissueForge::ParticleHandle *

Overload 1:

Particle constructor.

Automatically updates when running on a CUDA device.

Parameters:

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

Return type:

ParticleHandle

Returns:

new particle

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:

ParticleHandle

Returns:

new particle

factory(nr_parts=0, positions=None, velocities=None, cluster_ids=None)

Particle factory constructor, for making lots of particles quickly.

At minimum, arguments must specify the number of particles to create, whether specified explicitly or through one or more vector arguments.

Parameters:

nr_parts – number of particles to create, optional
positions – initial particle positions, optional
velocities – initial particle velocities, optional
clusterIds – parent cluster ids, optional

Returns:

ids of created particles

newType(_name: char const *) → TissueForge::ParticleType *

Particle type constructor.

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

Parameters:: _name (string) – name of the new type
Return type:: ParticleType
Returns:: new particle type

registerType() → HRESULT

Registers a type with the engine.

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

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() → TissueForge::ParticleType *: Get the type engine instance

items() → TissueForge::ParticleList &: Get all particles of this type.

isCluster() → bool: Test whether the type is a cluster type

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

toString() → std::string: Get a JSON string representation

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

Create from a JSON string representation.

The returned type is automatically registered with the engine.

Parameters:: str (string) – a string, as returned by toString

__reduce__(): Helper for pickle.

class tissue_forge.Cluster

Bases: Particle

The cluster analogue to Particle.

class tissue_forge.ClusterParticleHandle(*args)

Bases: ParticleHandle

The cluster analogue to ParticleHandle.

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

property radius_of_gyration: Radius of gyration

property center_of_mass: Center of mass

property centroid: Centroid

property moment_of_inertia: Moment of inertia

property num_parts: number of particles that belong to this cluster.

property parts: particles that belong to this cluster.

items = <function ClusterParticleHandle.items>

has(*args) → bool

Overload 1: Test whether the cluster has an id

Overload 2: Test whether the cluster has a particle

__str__(): Return str(self).

__getitem__(index: int)

__contains__(item)

__lt__(rhs) → bool: Return self<value.

__gt__(rhs) → bool: Return self>value.

__le__(rhs) → bool: Return self<=value.

__ge__(rhs) → bool: Return self>=value.

__eq__(rhs) → bool: Return self==value.

__ne__(rhs) → bool: Return self!=value.

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

Call self as a function.

Alias of _call

_call(*args) → TissueForge::ParticleHandle *

Overload 1:

Constituent particle constructor.

The created particle will belong to this cluster.

Automatically updates when running on a CUDA device.

Parameters:

partType (ParticleType) – type of particle to create
position (FVector3) – position of new particle, optional
velocity (FVector3) – velocity of new particle, optional

Return type:

ParticleHandle

Returns:

ParticleHandle*

Overload 2:

Constituent particle constructor.

The created particle will belong to this cluster.

Automatically updates when running on a CUDA device.

Parameters:

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

Return type:

ParticleHandle

Returns:

ParticleHandle*

cluster() → TissueForge::Cluster *

Gets the actual cluster of this handle.

Return type:: Cluster
Returns:: Particle*

split(axis: fVector3 = None, random: bool * = None, time: FPTYPE * = None, normal: fVector3 = None, point: fVector3 = None) → TissueForge::ParticleHandle *

Split the cluster.

Parameters:

axis (FVector3) – 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 (FVector3) – normal vector of cleavage plane, optional
point (FVector3) – point on cleavage plane, optional

Return type:

ParticleHandle

Returns:

ParticleHandle*

class tissue_forge.ClusterTypeSpec

Bases: ParticleTypeSpec

Interface for class-centric design of ClusterParticleType

types = None: List of constituent types of the cluster, if any

class tissue_forge.ClusterParticleType(noReg: bool const & = False)

Bases: ParticleType

The cluster analogue to ParticleType.

types: list of particle types that belong to this type.

hasType(type: ParticleType) → bool

Tests where this cluster has a particle type.

Only tests for immediate ownership and ignores multi-level clusters.

Parameters:: type (ParticleType) – type to test
Return type:: boolean
Returns:: true if this cluster has the type

get() → TissueForge::ClusterParticleType *

Get the type engine instance

Return type:: ClusterParticleType
Returns:: ClusterParticleType*

has(*args) → bool

Overload 1: Test whether the type has a type id

Overload 2: Test whether the type has a type

Overload 3: Test whether the type has a particle

__str__(): Return str(self).

__getitem__(index: int)

__contains__(item)

__lt__(rhs) → bool: Return self<value.

__gt__(rhs) → bool: Return self>value.

__le__(rhs) → bool: Return self<=value.

__ge__(rhs) → bool: Return self>=value.

__eq__(rhs) → bool: Return self==value.

__ne__(rhs) → bool: Return self!=value.