* Move label and s-expr parsing code and unit tests from Python to arbor C++ library.
* Update `locset` and `region` constructors that take string arguments to parse strings as s-expressions or "quoted" labels.
* Modify the input stream modifier used to parse asc files to use a lookup table for substitutions, renamed it transmogrifier.                                                             
* Replace `hopefully` type implemented in python headers with an `arb::util::expected`.
* Add `ARBDEV_COLOR` CMake option that forces gcc and clang to always output color output.
* Allow arbitrary strings in labels in region and locset expressions.
* Add `parse_region_expression` and `parse_locset_expression` functions alongside the existing `parse_label_expression` function for use when a region or locset is expected. These calls will promote a quoted string `"label"` to `(region "label")` or 
 `(locset "label")` respectively.
* Add user-defined string literals for labels so that the C++ interface can use `"soma"_lab` instead of awkward escaping `"\"soma\""`.
* Simplify Python wrapper code.

* Replace usages of `util::any` with `std::any`.
* Modify `util::any_cast` so that it forwards `std::any` arguments to `std::any_cast`; move into own header.
* Prevent `std::unique_any` from implicitly encapsulating `std::any` objects.
* Replace `test_any.cpp` unit tests with `test_any_cast.cpp` unit tests.
* Replace some usages of `std::is_same<X, Y>::value` with `std::is_same_v<X, Y>` as part of general C++17ification.
* Remove `util/variant.hpp`, `test_variant.cpp`.
* Replace occurrences of `util::variant` with `std::variant`.
* Replace `util::variant::get<N>` with `std::get<N>`.
* Replace `util::get_if<N>` with `std::get_if<N>`, passing a pointer to variant instead of a ref or value.
* Add some standard #includes where they were required in the source, but only included transitively.
* Some minor comment tidying and fix-ups.
* Update C++ API docs.

Fixes #1144.

* Make the members of `cable_cell_ion_data`  optional.
* Add separate methods for painting `init_int_concentration` , `init_ext_concentration` and `init_reversal_potential` on the cell.

* Remove spherical root/soma from morphology representations and logic.
* Replace `sample_tree` with `segment_tree`, which represents sample points in pairs and allows the representation of detached branches and cable segments.
* Remove sample point properties and predicates.
* Remove `cv_policy_flag::single_root_cv` as somata with a single attached dendrite will have a representation in the morphology of a single branch.
* Remove `arb::math::{volume/area}_sphere`, which are no longer being used.
* Remove spherical root special cases from `embed_pwlin` and `place_pwlin` objects.
* Add textual representation of `mnpos` in morphology exception text.
* Rename `sample_tree_from_swc` to `segement_tree_from_swc` and remove any special casing for one point somata.
* Remove `msample` and `mbranch` types.
* Update unit tests and python wrapper to reflect the changes.

Update core library:
* support derivation of named mechanisms in catalogue from a string description of the parent.
* fix bug in radois_ge region expression that was finding region_lt.
* fix test for radius_ge region expression

Add support for mechanism, global properties and catalogue shenanigans to python wrapper

Add a `restrict` locset expression type that returns all locations in a locset that are in a specified region.

Also allow region and locset names with hyphens.

Fixes #1031 
Fixes #1032 

This PR removes the requirement that all cover points are included in a region.
The motivation is to allow more flexible definion of regions, particularly the proximal and distal sets thereof.
The other motivation is that the author finds it much simpler to reason about, however others find the existing approach easier to reason about.

The changes:
 * `mextent` does not always include points on the cover at fork points.
   * it still enforces that its constituent cables have no intersections and are ordered.
 * a `super` region expression adds the cover points to a region.
 * update `most_proximal` to return the `minset` of the proximal points in a region's cables.
 * fix some cut and paste errors in comments and printing of locset expressions.

Add `cable_cell::concrete_region(region)` method that returns a the cable segments in a region.

This is required by the Arbor GUI #953 so that it can illustrate regions (and locsets) defined by users on a concrete cell morphology.

Note that the `concrete_region` and `concrete_locset` interfaces will need to be extended with random number seed information when we add full support for that, but shouldn't need to be replaced or changed otherwise.

Fixes #960.

Use locset names to set probe sites in single cell model.

1. Extend C++ cable_cell interface to provide a concrete list of locations associated with a locset on the cell.
2. Extend Python single_cell_model to allow placement of probes on locsets.
3. Remove "debug" output in Python ring example.

The single cell model maintains a trace callback for each probe location, and needs to know the explicit locations before starting the simulation. The first step is required to enumerate and record the locations associated with a locset when attaching probes.

Open issues: 

1. The extension to `cable_cell` won't sufficiently support locsets that rely on random number generators with global seeds (it would require passing additional meta data required to fully instantiate the locset)
2. Enhancing the probe recipe interface to be able to associate one `probe_id` with all locations in a locset (the number of which is not specified at the time the `probe_id` is created) would support the interface implemented for the `single_cell_model`.

Note: The richer interface on the C++ side will be implemented in time (see #957).

A big update that wraps over 90% of the public C++ API, with enough functionality to let Python users to perform useful modelling.

Key features
- wrapping of cable cell functionality
  - user-defined explicit compartmentalisation not supported
- `single_cell_model` abstraction unique to the Python wrapper that simplifies developing and testing single cell models
- one-dimensional cell builder for Python wrapper that simplfies building cells that 
  - in and of itself limited in scope, but a very useful example of mapping a richer morphology builder onto `sample_tree`s.
- parsing of region and location expressions from strings
  - implements a generic s-expression parser that we can use for other purposes later

Replace branch/cable-based cell representation and discretization with
free specification of control volumes over the cell morphology.

Implements functionality required for issues #859 and #732, and the
reworking of inter-CV conductance computation addresses issue #635,
although there is possible room for improvement by treating CV voltages
as averages rather than point estimates.

* Remove arbor/segment.hpp and segment-based representation in `cable_cell`.
* Add a new discretization policy `cv_policy_every_sample` that replaces
  the `compartments_from_discretization` flag in the `cable_cell`
  constructor.
* Remove use of `cable_cell::num_compartments()` in example code (see
  issue #940).
* Add command line argument to `single_cell` example to specify number
  of CVs per branch.
* Replace fvm layout `fvm_discretization` with new representation
  `fvm_cv_discretization`, which in turn wraps a `cv_geometry` object
  representing CVs as cables w...

* Make access to `segment`s in a `cable_cell` read only
* Change cell constructor to require morphology and label dictionary; `make_cable_cell` no longer required.
* Consolidate paint/place functionality on `cable_cell`.
* Add simple cell builder wrapping new API for use in unit tests.
* Remove validation test code: appropriate validation tests will need to be implemented in nsuite.

Fixes #871 

WIP on implementation of new cable cell API.

* Hide implementation and state using PIMPL
* Add consistent `place` methods for adding synapse, stimuls, gap junction site and spike detectors to `cable_cell`.
* Add default constructor for `region` and `locset` that create empty `nil` instances.

* Collect cable cell parameter setting structures into `include/cable_cell_param.hpp`.
* Restructure electrical specifications (axial resistance, membrane capacitance) and ionic concentrations and reversal potentials on cable cells, so that these can be specified with a global default, per-cell defaults, and per-segment values.
* Allow reversal potentials to be set by a mechanism of a new kind 'revpot', which are prohibited from maintaining state or writing to any shared state other than ionic reversal potentials.
* Specify reversal potential mechanisms as global defaults or per-cell. Reversal potential mechanisms may not be specified at the level of a segment in order to avoid non-linearities arising from the discretization.
* Supply default cable cell parameter data that matches NEURON values (this is _not_ used by default).
* Replace the d_lambda calculation with one that approximates more faithfully the effect of tapered segments, and which will ...

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 

Add full wrappers for

- `lif_cell`
- `spike_source_cell`
- `benchmark_cell

And an opaque wrapper for cable_cell with a helper function that generates a random morphology identical to the ones in the nsuite benchmarks.

Fixes #767.