* Fix pybind11 issues.

* Retract suspicious fix.

* Address comments.

Major changes in Python library and documentation:

* Add global state (immutable after initialization) for the Python module that
  manages the mapping between probe metadata types and the method by which the
  corresponding [sample data can be collected and presented as Python objects.
  This is necessary for decoupling the implementation of the simulation wrapper
  from that of the various cable cell probe types.

* Wrap each of the C++ cable cell probe types with a Python function that
  returns a `probe_info` object.

* Add code for converting and accumulating C++ probe metadata and sample
  data, registered in the module global state against the metadata type info.

* Make the `arbor.simulator` object responsible for recording all spike and
  sample data, with corresponding new methods.

* Use NumPy arrays and structured datatypes for returning spike and
  sample data.

* Place Python schedule proxies under an abstract interface so that consumers
  of the proxies can be made generic over schedule types.

* Add unit tests for the `arbor.simulator` class and its new functionality,
  including distributed spike collection.

* Rework all Python API documentation concerning probes, sampling, and spike
  recording; add information on newly exposed cable cell probe addresses.

* Add new python example `single_cell_recipe.py` which is a generic recipe
  version of `single_cell_model.py`.

* Adjust other code in the wrapper and examples to accommodate these changes.

Minor changes in Python library:

* Add equality tests for `arbor.location` and `arbor.cable` Python classes.

* Use the `py::` namespace shorthand more often in the Python wrapping sources.

* Add an implicit conversion for a pair of numbers to `arbor.cell_member`, so
  that e.g. probe ids can be specified simply as `(gid, index)`.

* Add an implicit conversion from a tuple to `arbor.mpoint` so that a
  morphological point can be specified simply as `(x, y, z, radius)`.

* Modify the interface to `arbor.regular_schedule` so that the overloads
  correspond more closely to the C++ API. In particular,
  `arbor.regular_schedule(dt)` now describes a schedule with times 0, dt, 2*dt,
  etc.

Minor changes in C++ library:

* Change test in FVM lowered cell implementation and exception message for
  `bad_source_description`: assert number of detectors is exactly the number
  of sources promised by the recipe.

* Add comment describing `probe_metadata` object in `sampling.hpp` which
  asserts that the type and value of probe-specific metadata completely
  determines the correct interpretation of sampled data provided to a callback.

akuesters authored 5 years ago and Benjamin Cumming committed 5 years ago

Ensure that errors in Python callbacks that are called from multithreaded C++ code propogate the correct Python error back to the parent Python callback site, and that no callbacks are called from other threads if an error has already ocurred.
- protects each recipe callback with a mutex, stores python exception, catches and throws python exception if occured
- methods calling recipe (in simulation and partition_load_balance) are protected as well by try catch, resets and rethrows python exception (if occured) or else throws C++ exception

fixes #792

Adds

* to `recipe.cpp`: 
`num_probes` and `get_probe` with helper function `cable_probe(kind, id, location)`
* `sample.cpp`: 
`sample` type with attributes `time` and `value`; a `sampler` with `samples()` and `clear()` and helper functions `attach_sampler(sim, dt)` for adding all probes as well as `attach_sampler(sim, dt, probe_id)` for adding one probe
* `morphology.cpp`: 
`location` as `arb::mlocation` with `branch` and `position` 
* corresponding docs and example
* update to new cable cell semantics in c++ validation test

fixes #762

akuesters authored 5 years ago and Benjamin Cumming committed 5 years ago

Add docs for Python wrapper to ReadTheDocs:

- Overview, Common Types, Hardware Management, Recipes, Domain Decomposition, Simulations, Metering
- Installing Arbor: Optional Requirements (Python), Buidling and Installing (Python Frontend), and Installation (Python Module)

Missing (, since not implemented yet): 

- probes
- arbor-sup 
- hint maps in domain_decomposition
- reset, events, empty schedule in event_generator
Also does not cover unit testing (since doc is user-centric).

Makes also defaults and units in wrapper consistent.

Fixes  #766

Support for recording spikes generated by a simulation in the Python wrapper
* Implement a `spike_recorder` that holds a shared pointer to a `std::vector` of spikes, and a callback for the `arb::simulation` spike recording API.
* Add `python/example/ring.py` that creates a ring network, then records and prints spikes.
* Some fixes to get the full `recipe` -> `domain_decomposition` -> `simulation` -> `spikes` workflow to work
  * always use default `global_parameters`: user customization of global parameters for cable cells can wait until the ion species interface is finished.
  * change the Python recipe interface for `recipe::connections_on` to use `pybind11::objects` because of shim.
* Some small improvements to error and help messages.

Fixes #764 

Fixes #782 
* consistent formatting of strings returned by `__repr__` and `__str__` for wrapped types
* rename enum wrappers to be less verbose, where it makes sense.

akuesters authored 5 years ago and Benjamin Cumming committed 5 years ago

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