Forces

Forces cause objects to move. In addition to forces that result from various processes (e.g., interactions via a potential), Tissue Forge also supports modeling explicit forces using a suite of built-in forces, as well as custom forces. An instance of any of the built-in forces can be created using static methods on the Force class, which can be bound to particles by particle type.

Creating Forces

Force objects are created simply by calling one of the static methods on the Force class. For example, a random force can be created for adding noise to the trajectory of particles,

import tissue_forge as tf
force = tf.Force.random(0.0, 1.0)

Custom forces can be created with the CustomForce class. A custom force requires a function that takes no arguments and returns a three-component container of floats that represent the current force whenever the function is called. Tissue Forge will convert the function into a force that acts on whatever particles are instructed in subsequent calls. For example, to create a time-varying force in Python,

import tissue_forge as tf
import numpy as np
...
force = tf.CustomForce(lambda: [0.3, 1 * np.sin(0.4 * tf.Universe.time), 0], 0.01)

A Force instance can also be created by adding two existing instances. Such operations can be arbitrarily performed to construct complicated forces consisting of multiple constituent forces,

force_noisy = tf.Force.random(0, 50)
force_tstat = tf.Force.berendsen_tstat(10)
force_noisy_tstat = force_noisy + force_tstat

Note

Changes to constituent forces during simulation are reflected in forces that have been constructed from them using summation operations.

Note

Tissue Forge uses force objects directly to allow modification to forces during simulation. This capability comes at the expense of that special care must be taken to not delete force objects from memory during simulation (e.g. when binding a force in a function call). In Python, deletion of force objects can be prevented by setting the force object attribute thisown to 0.

Built-in Forces

Presently, the following built-in forces are supported, with corresponding constructor method. For details on the parameters of each function, refer to the Tissue Forge API Reference.

Berendsen thermostat: Force.berendsen_tstat
Friction: Force.friction
Random: Force.random

Manipulating Forces on Particles

Aside from creating and applying forces on the basis of particle types, Tissue Forge also provides fine-grained access to manipulating forces on individual particles. The net force on each particle is accessible with the particle property force, which returns the current net force acting on the particle. While reading this property is valid, access to set the value of force is not provided, as Tissue Forge resets it at the beginning of each simulation step. However, Tissue Forge provides read and write access to the vector to which the force on a particle is reset at the beginning of each simulation step. The particle property force_init contains the vector value of the force on the particle before any processes acting on it are considered, which is added to all force calculations during the simulation step.

class MyParticleType(tf.ParticleTypeSpec):
    pass

ptype = MyParticleType.get()
# Make lots of particles, but apply a force to only one of them
parts = [ptype() for _ in range(100)]
parts[0].force_init = [1, 2, 3]