Finding and Accessing Objects
One of the more common activities is finding, accessing and interacting with model, simulation and system objects after their creation. Tissue Forge provides a number of ways to retrieve various objects, from particles that are created dynamically, to objects like the universe that are created automatically when initializing Tissue Forge.
Finding Particles
Tissue Forge methods that return a list of particles often return a
specialized list called a ParticleList
.
ParticleList
is a special list that contains particles
and has a number of convenience methods for dealing with spatial
information (e.g., calculating the center of mass of this list).
In cases where a function returns a more basic container
(e.g., a Python list) of particles (or requires a ParticleList
as argument), a ParticleList
can be easily constructed from most
basic containers by simply passing the container to the
ParticleList
constructor.
Each ParticleType
-derived particle type instance has a method
ParticleType.items
that returns a
list of all of the particles of that type:
import tissue_forge as tf
class MyType(tf.ParticleTypeSpec):
...
# make ten particles...
my_type = MyType.get()
[my_type() for _ in range(10)]
# get all the instances of that type:
parts = my_type.parts
for p in parts:
print(f'{my_type}' has particle {p}')
All particles currently in a simulation are also accessible from the
universe via the property particles
.
Likewise, all particles constituting a cluster can be accessed
with the cluster method items
.
Each particle is aware if its neighbors, and we can get a list of
all the neghbors of an object by calling the particle method
neighbors
.
The neighbors
method accepts two
optional arguments, distance
and types
. Distance is the distance away
from the surface of the present particle to search for neighbors, and types
is a list of particle types to restrict the search to.
# Make a particle and find its nearby A- and B-type neighbors
p = my_type()
nbrs = p.neighbors(distance=1, types=[A, B])
print(f'Particle has {len(nbrs)} neighbors')
# Test if another particle is a neighbor
print('Particle 2 is a neighbor:', tf.ParticleHandle(2) in nbrs)
Tissue Forge also provides the ability to organize all the particles into a
discretized grid, for example, to display some quantity as a function of
spatial position. The universe method
grid
returns a three-dimensional container of all
particle lists with dimensions according to the shape passed to
grid
. The ordering of the passed shape is the same
as for position in space. The list at each index of the returned container
corresponds to the particles in each subspace of the discretized space according
to a regular lattice. For example, when discretizing space into a 8x9x10 grid,
the particles in the first subspace along the first dimension, second subspace
along the second dimension, and third subspace along the third dimension is
readily accessible,
parts = Universe.grid([8, 9, 10])
parts_ss = parts[0][1][2]
print('Subspace velocities:', parts_ss.velocities)
Finding Bonds
Like particles, bonds and bond-like objects
can be dynamically created and destroyed, and Tissue Forge provides a number
of ways to retrieve them. All bonds and bond-like objects attached to a
particle can be retrieved using the property bonds
and comparable,
# Get all bond and bond-like objects attached to particle "p"
bonds = p.bonds
angles = p.angle
Likewise all bond and bond-like objects currently in the simulation
All bonds and bond-like objects currently in a simulation are also
accessible from the universe using the property
bonds
and comparable,
# Get all bond and bond-like objects in the universe
all_bonds = Universe.bonds
all_angles = Universe.angle