A support for Gitpod.io, a free automated
dev environment that makes contributing and generally working on GitHub
projects much easier. It allows anyone to start a ready-to-code dev
environment for any branch, issue and pull request with a single click.

* Implement std::variant workalike.
* Add util::variant and accessors util::get, util::get_if, util::visit,
mimicking C++17 std::variant, but with some missing functionality noted
in the `util/variant.hpp` header.
* variant.hpp` available through public header API.

This might be what is breaking zenodo for us.

Fix warning generated when `delay` and `weight` were accidentally swapped in #984 
Match `cell_connection` delay type to `connection` delay type

Fixed `mech_vec` to work with new API and re-enabled the benchmark. Had to disable some of the tests because of long run-times (function responsible for slow-down is `cv_geometry::location_cv`, called from `fvm_layout.cpp:721` and is probably related to unrealistically large cv counts). 

`model-init` run-times have been observed to be too high when running systems with many synapses.
 
The main culprit is the `sort_by` function (fvm_layout:723). When testing on a model with 1024 cells and 10000 synapses, 65% of model-init is spent in this function. 

Comparing two `std::map<std::string, double>` is really expensive. We can replace the string map `synapse_instance.param_value` with a sorted `std::vector<std::pair<unsigned, double>>`, and have an additional `std::map<std::string, unsigned> param_map`  to keep track of all the param_name -> unsigned mappings.

`model-init` run-time is 2.5x faster (tested on my 4 core  i7-7600U laptop):
```
10000 synapses/cell 
--------------------------------------------------------------------
|  num cells       | model-init before  (s) | model-init after (s) |
--------------------------------------------------------------------
|       1024       |          12            |       5              |
|       2048       |          25.5          |       10.8           |
|       4096       |          55.5          |       23.2           |
|       8192       |          121.8         |       49             |
--------------------------------------------------------------------
```

Provide canonical function for mextent that returns a reduced
mcable_list representation which excludes redundant zero-length
cables.

* Provide GPU aware `execution_contexts` to unit tests that run on the GPU.
* Provide multithreaded `execution_contexts` to unit tests that use `thread_private_spike_store`.
* Provide multithreaded `execution_contexts` to unit tests in `test_fvm_lowered.cpp` as a means to test the parallel implementation of `fvm_lowered_cell_impl::initialize`.

Addresses #982

* Change `time_type` to `double` to support time-step accuracy in longer running simulations.
* Change connection delay to `float` from `time_type` in order to avoid unnecessary memory overheads.

* Replace TCLAP with tinyopt, remove TCLAP from `ext/`.
* Replace `sup/tinyopt.hpp` with copy of external tinyopt, update use of `tinyopt` in unit tests and examples to suit.
* Use tinyopt's 'smallopt' interface in `modcc`, `brunel` example.
* Update tinyopt interface in `single` example.
 Fix our attributions and add HBP acknowledgement

Addresses #557 #695 #803 

* Use the task system to parallelize parts of the model initialization phase, namely cell building,`fvm_cv_discretize` and `fvm_build_mechanism_data`. 

Fixes #634 

Use a wrapper `mextent` around an `mcable_list` with a stronger invariant for the representation of thingified regions, with public intersection and union and intersection-testing operations. Creation of an `mextent` requires a morphology, but any further operations on one do not.

* Implement `mextent`, wrapping an `mcable_list` and enforcing an invariant: all cables on the same branch are distinct; and there is a cable in the extent for every branch that intersects with the region on the morphology tree described by the cable list.
* Recast region union and intersection operations on regions in terms of `mextent` objects.
* Use `mextent` objects as the concrete representation for regions in `mprovider`.
* Modify region/locset expression implementations to accommodate new representation.
* Add `region` ctors that wrap an explicit cable list or `mextent`.
* Add a lazy range-based merge view in `util/mergeview.hpp`.

Remove cell_stats from gap junction, dry run and ring examples.

Fixes #962

Add a `setup.py` for installing Arbor directly with pip/setuptools.

Implement a setuptools extension for CMake in `setup.py`. To be honest, I don't understand entirely how it works, but setuptools is obtuse enough that I don't feel at all guilty about this.

Define additional flags for optionally enabling GPUs, MPI, Vectorization and micro-architecture targets, for more adventurous users.

The documentation is updated with a "howto pip" for more casual users who don't want anything to do with CMake.

Fixes #958 .

* Add missing `#include <cstdint>` in `common_types.hpp`.

* Amend `size_t` type check in `mpi.hpp` to support 32-bit builds.

Replace deprecated `__ARM_NEON__` preprocessor define with `__ARM_NEON`, which should be defined by the compiler provided `ARB_ARCH` is set correctly, e.g. with `-DARB_ARCH=armv8-a+simd `

Improve the Python wrapper generation and installation:
  - install a proper module that can be extended with Python code;
  - give the user more control over where to install the module (e.g. as a user package or in a virtualenv).

During building, the following sub-directory is built in the build director (`CMAKE_BINARY_DIR`)
```
└── python
    └── arbor
            ├── __init__.py
            ├── arbor.so
            └── VERSION
```
This path can then be copied VERBATIM to the target installation path. By default this will be in `CMAKE_INSTALL_PREFIX/lib/python%d.%d/site-packages`.
An additional CMake parameter `ARB_PYTHON_PREFIX` can be used to specify an alternative destination for installing the Python module.

The Python part of the wrapper, implemented in `__init__.py` is currently very limited, only providing `__version__` and `__config__` variables.

The installation guide was updated to cover the Python installation.

* Replace serialized isnan(x) calls with cmp_eq(x,x) (changing sense of associated tests accordingly).

Replace `algorithms::sum` with `util::sum` in `test_matrix.cu`.

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.

- Reset the error of the semantic pass of an expression at the start of the function call. 
- Check the errors of sub-expressions after applying to them their semantic passes, and report errors if found. If the error could disrupt the rest of the original semantic pass, return.
- Check errors in functions/procedures before and after inlining, but not during. 

Fixes #931 

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).

- Rename z distance region definitions to refer to the root, not the soma.
- Also fix printing of some region expressions to s-expressions.

Fixes #947.

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

Also: add a couple more cases to fvm_discretize ubench.

Split out from Alex's PR for quicker inclusion into master.

* Supply `execution_context` deleter for `std::unique_ptr` via class, so
that a function does not have to be supplied as an argument at
construction.
* Supply `arb::basic_spike` by const reference to `ostream` writer.
* Add domain index to `connection` `ostream` writer.

* Provide (internal) locset wrapper for mlocation_list so as to avoid quadratic mlocation sum(...) behaviour.
* Add ubench for fvm_discretize, with lmorpho-generated test SWC.
* Rewire `cv_policy_every_sample` to produce a locset that thingifies faster.

Fixes #946 .

* Fix '==' vs '=' error in assignment.
* Use last element (index 2) not index 1 of parent area and ixa tile to start from on new branch.
* Expose cross-branch consistency via point-to-point integration functions for branch length and area.
* Extend unit tests to suit.

Extends the available locset/region expressions.

* Add `distal_interval` and `proximal_interval` expressions that return a region defined by an initial locset and a distance to extend in the distal or proximal directions respectively.
* Add `radius_lt`, `radius_le`, `radius_gt`, `radius_ge` region expressions describing the subset of the morphology with radius less than (or less than or equal to etc.) a given value.
* Add `z_dist_from_soma_lt`, `z_dist_from_soma_le`, `z_dist_from_soma_gt`, `z_dist_from_soma_ge` region expressions describing the subset of the morphology which is less than (resp. less than or equal to, etc.) the given distance along the z-axis from the root sample.
* Add `uniform` locset expression giving a uniformly sampled set of locations from a given region based on a supplied PRNG seed value and a closed interval [left, right] of elements from the corresponding pseudo-random sequence.
* Add `Random123` as a library to `ext` and `util::uniform` wrapper for use in the `uniform` locset expression.
* Add unit tests to suit.

Fixes #939 

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 within cells in a cell group.
* Provide `cv_geometry_from_ends` that produces `cv_geometry`
  discretization for a cell given a locset comprising CV boundary points.
* Provide interface and functionality for merging discretization
  structures `cv_geometry`, `fvm_cv_discretization`, `fvm_mechanism_data`
  from multiple cells, in order to support (in the future) parallelized
  discretization across a cell group.
* Provide complete reimplementation of `fvm_discretize(...)`.
* Remove now redundant `arbor/fvm_compartment.hpp`.
* Add new locset expression `on_branches`, representing a point on every
  branch at a given relative position.
* Fix implementation bug in `pw_elements` `zip` function.
* Add `util::equal` range-based analogue of `std::equal`.
* Remove the compartments_from_discretization argument from cable cell
  made in python module. (Does this need to begiven a discretization policy?
  It is not clear.)

* Add support for conditionals with the SIMD printer by using `where_expresssions` to mask assignments to range variables that happen inside if/else blocks. Assignments to non-range variables are executed non-masked when correctness is ensured. 

Fixes #836 

* Add implicit conversions from mlocation and mlocation_list to locset.
* Add implicit conversions from mcable and mcable_list to region.
* Change arguments for `ls::location` to `(branch, position)`.
* Extend unit tests to suit.
* Make locset and region wrapping less promiscuous by demanding that
expression implementation classes derive from locset_tag or region_tag
respectively.

Update cable() invocations in unit tests added in #934 to match new interface from #938.

* Make small changes to region/locset interfaces for ease of python interface implemenation.

Nora Abi Akar authored 5 years ago and Benjamin Cumming committed 5 years ago

Stop region intersection from returning extra zero length cables if the location it describes is in the cover of another region in the `cable_list`.