running_a_sim.rst

.. py:currentmodule:: tissue_forge

Running a Simulation

In most cases, running a simulation is as simple as initializing the simulator with the :func:`init` function (:func:`tfSimulator_initC` in C), building the physical model, and running the simulation by calling the :func:`run` function (or :func:`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 :func:`run` (or :func:`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 :func:`show` (:func:`tfShow` in C) only displays the application window and starts the internals of Tissue Forge without performing any time stepping. The :func:`start`, :func:`step`, :func:`stop` functions (:meth:`tfStart`, :meth:`tfStep`, :meth:`tfStop` in C) start the :ref:`universe <universe>` time evolution, perform a single time step, and stop the time evolution, respectively. If the universe is stopped, the :meth:`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 :func:`run` (when passing a negative value to :func:`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 :func:`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 :func:`step` (rather than :func:`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 :ref:`forces <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 :ref:`sharing results <file_io>`), 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.