Running a Simulation

In most cases, running a simulation is as simple as initializing the simulator with the init function (tfSimulator_initC in C), building the physical model, and running the simulation by calling the run function (or irun for interactive mode in Python). However, Tissue Forge provides many options for controlling the simulation during execution.

A running simulation has three key components: interacting with the operating system, handling events (both model-specific events and user input), and integrating the model in time (time stepping). Whenever the run (or irun in Python) is invoked, it automatically start time stepping the simulation. However, Tissue Forge provides additional functions to finely control displaying, time stepping and stopping a simulation. For example, calling the function show (tfShow in C) only displays the application window and starts the internals of Tissue Forge without performing any time stepping. The start, step, stop functions (tfStart, tfStep, tfStop in C) start the universe time evolution, perform a single time step, and stop the time evolution, respectively. If the universe is stopped, the start function can be called to continue where the universe was stopped. All functions to build and manipulate the universe are available either with the universe stopped or running.

When passing no arguments to run (when passing a negative value to tfRun in C), the main window opens, and the simulation runs and only returns when the window closes. When an argument is passed, the value is understood as the simulation time at which the simulation should stop, at which point the window closes. With irun in IPython, the main window opens, and the simulation runs and responds to user interactions with it and its objects in real time while it runs.

For convenience, all simulation control functions are aliased as top-level functions in Python,

import tissue_forge as tf   # import the package
tf.init()                   # initialize the simulator
# create the model here
...
tf.irun()                   # run in interactive mode (only for ipython console)
tf.run()                    # display the window and run
tf.close()                  # close the main window
tf.show()                   # display the window
tf.step()                   # time steps the simulation
tf.stop()                   # stops the simulation

In C++, the same functions are available through the TissueForge namespace in TissueForge.h,

#include <TissueForge.h>

using tf = TissueForge;

tf::Simulator::Config config;
tf::init(config);               // initialize Tissue Forge
// create the model here
...
tf::run();                      // display the window and run
tf::close();                    // close the main window
tf::show();                     // display the window
tf::step();                     // time steps the simulation
tf::stop();                     // stops the simulation

In C, the same functions are available in wraps/C/TissueForge_c.h,

#include <TissueForge_c.h>

struct tfSimulatorConfigHandle config;
tfSimulatorConfig_init(&config);
tfInitC(&config, NULL, 0);              // initialize Tissue Forge
// create the model here
...
tfRun();                                // display the window and run
tfClose();                              // close the main window
tfShow();                               // display the window
tfStep();                               // time steps the simulation
tfStop();                               // stops the simulation

Running Windowless

Many applications like massively-parallel execution of lots of simulations require running Tissue Forge without real-time visualization and interactivity, where Tissue Forge can execute simulations tens to hundreds of times faster. Tissue Forge supports such an execution mode, called Windowless, in which case all Tissue Forge functionality is the same, except that Tissue Forge does no rendering except when instructed to do so in the instructions of a scripted simulation.

Tissue Forge can be informed that a simulation should be executed in Windowless mode during initialization with the keyword argument windowless,

tf.init(windowless=True)

In C++, the same can be accomplished using Simulator::Config, and in C with function tfSimulatorConfig_setWindowless.

Execution of a simulation occurs through the function step (rather than run), where each call executes one simulation step,

num_steps = int(1E6)  # Number of steps to execute
for step_num in range(num_steps):
    tf.step()

Reproducible Simulations

Some features of Tissue Forge are stochastic (e.g., random forces). Tissue Forge uses a pseudo-random number generator to implement stochasticity. By default, Tissue Forge generates a different stream of random numbers on each execution of a simulation. However, in cases where results from a simulation with stochasticity need to be reproduced (e.g., when sharing results), Tissue Forge can use the same stream of random numbers when given the seed of the pseudo-random number generator. Tissue Forge accepts specification of the seed during initialization with the keyword argument seed, as well as at any time during simulation,

tf.init(seed=1)                 # Set the seed during initialization...
tf.set_seed(tf.get_seed() + 1)  # ... or after initialization.