From recipe to simulation

To build a simulation the following concepts are needed:

  • An arb::recipe that describes the cells and connections in the model.

  • An arb::context used to execute the simulation.

The workflow to build a simulation is to first generate a arb::domain_decomposition that describes the distribution of the model over the local and distributed hardware resources (see Domain decomposition), then build the simulation.

#include <arbor/context.hpp>
#include <arbor/domain_decomposition.hpp>
#include <arbor/simulation.hpp>

// Get a communication context
arb::context context = make_context();

// Make a recipe of user defined type my_recipe.
my_recipe recipe;

// Get a description of the partition the model over the cores
// (and gpu if available) on node.
arb::domain_decomposition decomp = arb::partition_load_balance(recipe, context);

// Instantiate the simulation.
arb::simulation sim(recipe, decomp, context);

All the simulation’s constructor arguments are optional, except the recipe, and assume default values if not specified. In order to simplify construction of a simulation, the helper class arb::simulation_builder can be used to better control constrution arguments:

arb::simulation sim =                // implicit conversion to simulation
    arb::simulation::create(recipe)  // the recipe is always required
        .add_context(context)        // optionally add a context
        .add_decompostion(decomp)    // optionally add a decompostion
        .add_seed(42);               // optionally add a seed value

Class documentation

class simulation

The executable form of a model. A simulation is constructed from a recipe, and then used to update and monitor model state.

Simulations take the following inputs:

  • The constructor takes:

    • an arb::recipe that describes the model;

    • an arb::domain_decomposition that describes how the cells in the model are assigned to hardware resources;

    • an arb::context which is used to execute the simulation.

    • a uint64_t in order to seed the pseudo pandom number generator (optional)

  • Experimental inputs that can change between model runs, such as external spike trains.

Simulations provide an interface for executing and interacting with the model:

  • Advance model state from one time to another and reset model state to its original state before simulation was started.

  • I/O interface for sampling simulation state during execution (e.g. voltage and current) and spike output.


using spike_export_function = std::function<void(const std::vector<spike>&)>

User-supplied callback function used as a sink for spikes generated during a simulation. See set_local_spike_callback() and set_global_spike_callback().


simulation(const recipe &rec, const domain_decomposition &decomp, const context &ctx, std::uint64_t seed)

Static member functions:

simulation_builder create(const recipe &rec)

Returns a builder object to which the constructor arguments can be passed selectively (see also example above).

Experimental inputs:

void inject_events(const pse_vector &events)

Add events directly to targets. Must be called before calling run(), and must contain events that are to be delivered at or after the current simulation time.

Updating Model State:

void reset()

Reset the state of the simulation to its initial state.

time_type run(time_type tfinal, time_type dt)

Run the simulation from current simulation time to tfinal, with maximum time step size dt.


sampler_association_handle add_sampler(cell_member_predicate probeset_ids, schedule sched, sampler_function f)

Note: sampler functions may be invoked from a different thread than that which called run().

(see the Sampling API documentation.)

std::vector<probe_metadata> get_probe_metadata(const cell_address_type &probeset_id) const

Return probe metadata, one entry per probe associated with supplied probe id, or an empty vector if no local match for probe id. See the Sampling API documentation.

void remove_sampler(sampler_association_handle)

Remove a sampler. (see the Sampling API documentation.)

void remove_all_samplers()

Remove all samplers from probes. (see the Sampling API documentation.)

std::size_t num_spikes() const

The total number of spikes generated since either construction or the last call to reset().

void set_global_spike_callback(spike_export_function export_callback)

Register a callback that will periodically be passed a vector with all of the spikes generated over all domains (the global spike vector) since the last call. Will be called on the MPI rank/domain with id 0.

void set_local_spike_callback(spike_export_function export_callback)

Register a callback that will periodically be passed a vector with all of the spikes generated on the local domain (the local spike vector) since the last call. Will be called on each MPI rank/domain with a copy of the local spikes.