Py feature simulation (#778)

Wrap `arb::simulation` type and interface for running `run()`, resetting `reset()`, and `set_binning_policy(policy, bin_interval)`. 

Wrap `enum binning_kind`, used to set event binning on `simulation` API.

Fixes #763 

python/CMakeLists.txt

@@ -24,6 +24,7 @@ add_library(pyarb MODULE
     mpi.cpp
     pyarb.cpp
     recipe.cpp
+    simulation.cpp
     schedule.cpp
 )
 

python/domain_decomposition.cpp

@@ -28,7 +28,6 @@ std::string dd_string(const arb::domain_decomposition& d) {
       << d.num_domains << ", "
       << d.num_local_cells << "/" << d.num_global_cells << " loc/glob cells, "
       << d.groups.size() << " groups>";
-
     return s.str();
 }
 

python/identifiers.cpp

@@ -59,6 +59,15 @@ void register_identifiers(pybind11::module& m) {
             "Use GPU backend.")
         .value("multicore", arb::backend_kind::multicore,
             "Use multicore backend.");
+
+    pybind11::enum_<arb::binning_kind>(m, "binning_kind",
+        "Enumeration for event time binning policy.")
+        .value("none", arb::binning_kind::none,
+            "No binning policy.")
+        .value("regular", arb::binning_kind::regular,
+            "Round time down to multiple of binning interval.")
+        .value("following", arb::binning_kind::following,
+            "Round times down to previous event if within binning interval.");
 }
 
 } // namespace pyarb

python/pyarb.cpp

@@ -13,6 +13,7 @@ void register_event_generators(pybind11::module& m);
 void register_identifiers(pybind11::module& m);
 void register_recipe(pybind11::module& m);
 void register_schedules(pybind11::module& m);
+void register_simulation(pybind11::module& m);
 
 #ifdef ARB_MPI_ENABLED
 void register_mpi(pybind11::module& m);
@@ -33,4 +34,5 @@ PYBIND11_MODULE(arbor, m) {
     #endif
     pyarb::register_recipe(m);
     pyarb::register_schedules(m);
+    pyarb::register_simulation(m);
 }

python/simulation.cpp

+#include <pybind11/pybind11.h>
+
+#include <arbor/simulation.hpp>
+
+#include "context.hpp"
+#include "recipe.hpp"
+
+namespace pyarb {
+
+void register_simulation(pybind11::module& m) {
+    using namespace pybind11::literals;
+
+    // Simulation
+    pybind11::class_<arb::simulation> simulation(m, "simulation",
+        "The executable form of a model.\n"
+        "A simulation is constructed from a recipe, and then used to update and monitor model state.");
+    simulation
+        // A custom constructor that wraps a python recipe with
+        // arb::py_recipe_shim before forwarding it to the arb::recipe constructor.
+        .def(pybind11::init(
+            [](std::shared_ptr<py_recipe>& rec, const arb::domain_decomposition& decomp, const context_shim& ctx) {
+                return new arb::simulation(py_recipe_shim(rec), decomp, ctx.context);
+            }),
+            // Release the python gil, so that callbacks into the python
+            // recipe don't deadlock.
+            pybind11::call_guard<pybind11::gil_scoped_release>(),
+            "Initialize the model described by a recipe, with cells and network distributed\n"
+            "according to the domain decomposition and computational resources described by a context.",
+            "recipe"_a, "domain_decomposition"_a, "context"_a)
+        .def("reset", &arb::simulation::reset,
+            pybind11::call_guard<pybind11::gil_scoped_release>(),
+            "Reset the state of the simulation to its initial state.")
+        .def("run", &arb::simulation::run,
+            pybind11::call_guard<pybind11::gil_scoped_release>(),
+            "Run the simulation from current simulation time to tfinal, with maximum time step size dt.",
+            "tfinal"_a, "dt"_a)
+        .def("set_binning_policy", &arb::simulation::set_binning_policy,
+            "Set event binning policy on all our groups.",
+            "policy"_a, "bin_interval"_a)
+        .def("__str__", [](const arb::simulation&){ return "<arbor.simulation>"; })
+        .def("__repr__", [](const arb::simulation&){ return "<arbor.simulation>"; });
+}
+
+} // namespace pyarb