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.