Ben Cumming authored 6 years ago and Sam Yates committed 6 years ago

Add some C++ API documentation.

* Create C++ API section in docs.
* Document `arb::recipe`: both a class reference along with more explanatory text and best practices guide.
* Add some class documentation of basic types required to understand recipe definition.
* Some in-code comment clean up.
* Change `arb::cell_kind` from a vanilla enum to a scoped enum.

Ben Cumming authored 6 years ago and Sam Yates committed 6 years ago

The name `arb::model` did not clearly describe the role of the class, while `arb::simulation` better captures that this is an instantiation of a model for the purpose of running a simulation, as distinct from the description of a model represented by an `arb::recipe` instance.

* Rename sources `model.{hpp,cpp}` to `simulation.{hpp,cpp}`.
* Rename class `arb::model` to `arb::simulation`.
* Update docs and tests to suit.

Ben Cumming authored 6 years ago and Sam Yates committed 6 years ago

Put all the SIMD docs in a single topic, to simplify the documentation tree.

Added an installation guide to the Read The Docs
Removed the outdated build/install information from README.md
Link from README to Read The Docs
Updated the splash page for Read The Docs

CUDA 9 introduced new, fine-grained, thread synchronization primitives.
In doing so, it introduced new forms of the warp intrinsics like __shfl_up, depricating the old symbols in the process.

It will be a while before we can use 9 as the default minimum, so we have to support compilers that expect the new and old behavior.

There are two options: wrap the intrinsics in question, or pass nvcc a flag to not issue warnings about depricated symbols. I go for the approach of wrapping, because I would rather keep the compiler warning turned on.

Fixes #379.

Padded vectors with run-time padding/alignment guarantees will form the basis of the storage class for the new CPU and SIMD generated mechanisms.

* Add `padded_allocator` that aligns and pads allocations.
* Make microbenchmark for `default_construct_adaptor` that overrides the allocator construct() to default- instead of value-initialization on values.
* Add `with_instrumented_malloc` class for tracking malloc, realloc, etc. calls.
* Add unit tests for `padded_allocator`.

fixes #446.

Intel compiler with default options does not guarantee correct fp behaviour with subnormals; it presumably sets the fp state to flush to zero.

Reordering a multiply and divide in the expm1 calculation avoids a transient subnormal value that was causing the routine to incorrectly return zero for very small, but normal, arguments.

This provides a bunch of SIMD intrinsic wrappers as a precursor to the SIMD printers.

The aim is that the SIMD printer can be agnostic regarding the particular vector architecture.

The design is based rather loosely on the proposal P0214R6 for C++ Parallelism TS 2. The transcendental function implementations are adapted from the existing SIMD architecture-specific code, which in turn are based on the Cephes library algorithms.

The custom CSS for the html documentation have been tweaked.

In some places our CMake scripts were attempting to check out git submodules when required, if they have not already been checked out. The code that does this was cut and pasted, and was getting unwieldy.

To minimise the responsibilities of CMake, this PR

removes calls to git
introduces a function check_git_submodule that can be used to test if a git submodule is installed, and print a helpful message that informs the user how to check it out if needed.
introduces a function add_error_target that makes a target that prints a message then quits with an error. This can be used to generate a proxy target when a problem is detected during CMake setup. This means that an error is only generated when building a target with a missing dependency, instead of an error during CMake setup.
refactors the CMake setup for the docs and ubenches targets to use these new features.

This replaces the CMake templates provided by TBB with a much more sane alternative!

The TBB CMake templates had a very strange workflow, that involved downloading the TBB source and compiling it, which made it impossible to configure the TBB build, and caused problems on systems without connection to the internet.

We replace this with a fork of the TBB repository maintained by Github user @wjakob:
https://github.com/wjakob/tbb
This fork provides a sane CMakeLists.txt that can be configured from our CMake setup.
It is added as a git submodule, so it can be downloaded with the rest of the repository, hence not requiring connection to the internet during CMake configuration.

It could be extended to use a user-provided build of TBB to use instead of building it.

fixes #332.

Ben Cumming authored 7 years ago and Sam Yates committed 7 years ago

Replace the profiler with a simpler design that works for nested multi-threaded regions.

* Replace hierarchical profiler accounting with strictly exclusive regions.
* Make tree grouping of profile data a presentation concern.
* Uncouple profiler semantics from Arbor classes such as `model`.
* Add thorough documentation for the new profiler to the library documentation.

Use type erasure tricks to remove abstract base class for `event_generator`.

This simplifies all the code that uses `event_generator`s (not radically, but it is simpler).

Added cell description to the Arbor namespace.

Two main contributions:

1) Implementation of LIF neuron model with no kernel and no external input (I_e=0)

The input current to each neuron is therefore just the sum of all the weights of incoming spikes. We integrate in jumps dt = min(t_final - t, t_event - t), since we know the exact solution of the differential equal describing the membrane potential.

2) Miniapp for simulating the Brunel network of LIF neurons. 

The network consists of 2 main populations: excitatory and inhibitory populations. Each neuron from the network receives a fixed number (proportional to the size of the population) of incoming connections from both of these groups. In addition to the input from excitatory and inhibitory populations, each neuron receives a fixed number of connections from the Poisson neurons producing the Poisson-like input that is integrated into the LIF cell group so that the communication of Poisson events is bypassed. 

Ben Cumming authored 7 years ago and Sam Yates committed 7 years ago

* Parallelize calls to `recipe::connections_on` in communicator constructor.
Fixes #442.

Add an example miniapp that demonstrates how to use event generators in a C++ recipe.

* Replace improper use of brace initialization of vectors of classes with a deleted move constructed with a sequence of `emplace_back` invocations.

There were two latent bugs in the event generation part of `model`.

1. A segmentation fault when initializing the `event_generators` in the `model` constructor caused by using an index variable after it had been incremented.
2. Events generated during the first epoch were not delivered on time.

The first issue was simple to fix, by ensuring that the coutning variable is incremented at the end of the loop.

The second issue required refactoring the event wrangling inside `model`. Events can be introduced into a model via three sources:

1. Generated by spike exchange
2. By calling the `model::inject_events()` interface
3. `event_generator`s attached to cells.

The refactoring was required to ensure that all three sources are handled correctly. There is further opportunities for refactoring the code to make it a bit cleaner, specifically putting the wrangling code in its own type that could be tested seperately, outside `model`, but that is beyond the scope of this fix. 

Ben Cumming authored 7 years ago and Sam Yates committed 7 years ago

* Enable `cell` copy constructor, remove special tag type used to guard `cell` cloning.
* Provide sane defaults for `recipe` methods.

Ben Cumming authored 7 years ago and Sam Yates committed 7 years ago

* Remove `cell_tree` wrapper around `tree`.
* Separate `tree` construction from tree reduction operation.
* Rename `make_parent_index` to `tree_reduce`.

Fixes #426.

A small script to compare files containing (gid, time) pairs. The list do not have to be sorted in time or gid order.
A details error is displayed on differences.

* Fix indirection in ion concentration write.
* Remove second indirection in ion write assignment.
* Extend ion write unit test to cover non-contiguous ion CV cases and verify correct ion concentration averaging.

Fixes #424.

Ben Cumming authored 7 years ago and Sam Yates committed 7 years ago

* Rename `miniapps` subdirectory to `example`.
* Have all example executables be built under `example` in the build directory.
* Update Travis CI to run miniapp from new path.

Ben Cumming authored 7 years ago and Sam Yates committed 7 years ago

* Add three new mechanisms: `nax.mod`, `kdrmt.mod` and `kamt.mod`.
* Add new built-in math operators to `modcc`: `min`, `max`, `abs` and `exprelr`. `exprelr` is defined as the reciprocal of the 'exprel' function, exprel(x)=x/(exp(x)-1), exprel(1)=1. This function occurs frequently in HH-style mechanisms, and having a built-in operator avoids the ad hoc `vtrap` functions found in NMODL files in the wild.
* Split Arbor SIMD intrinsics support into AVX2- and AVX512-specific files.
* Add unit tests for new maths operators for C++, SIMD and CUDA implementations.

Reduce differences between `util::optional` and `std::optional`.

* Rename `util::nothing` to `util::nullopt`.
* Replace `util::get()` by`util::optional::value()`.
* Add correct move semantics to `util::optional::value()`.
* Add `util::optional::value_or()` method.
* Remove unused monadic functionality from `util::optional` and `util::uninitialized`.
* Update code formatting to closer adhere to coding guidelines.
* Add convenience ""_s string constructor for unit tests.
* Update unit tests accordingly.

Fixes #419.

Ben Cumming authored 7 years ago and Sam Yates committed 7 years ago

* Fix various compiler warnings in `modcc` when using Apple Clang.

Implement generic `event_generator`, and some common generators that should be useful to users out of the box:
* poisson sequence                                                                                       
* uniform regular sequence
* from a user-prescribed sequence
* from a `std::vector` of post synaptic events.

Extend `recipe` API to provide an `recipe::event_generators(gid)` that returns a list of `event_generator`s attached to a cell with `gid`.

Update the `model` class and `merge_events` method to support event generators.

Fixes #401 

Fix bug in `rss_cell_group`s with more than one cell with different `dt` or `start_time` values.
Fixes #410.

Vasileios Karakasis authored 7 years ago and Sam Yates committed 7 years ago

Also removes vestigial `intitial` procedure generated from a MOD file with no INITIAL block.
Fixes #407. 

Restructure the miniapp in such a way that we have to option to have multiple parallel mini-applications.

Move the original miniapp directory to a miniapps directory.
Output executable also in a nested miniapps directory.
Update the Travis to point to the new executable location.

Ben Cumming authored 7 years ago and Sam Yates committed 7 years ago

* Add querying methods to modcc ion species type to simplify code generation.
* Add `WriteBack` type that records per-mechanism ion usage metadata.
* Add `write_back` implementation for C and CUDA printers that adds weighted concentration
  contributions to global concentration fields.
* Extend `uses_ion` interface to provide information about which concentration fields are modified by mechanisms.
* Update `update_ion_symbols` lambda that is responsible for adding metadata about interactions between mechanism fields and external ion species fields, creating a write-back when the mechanism field is a state variable or an indexed variable if it is a current/reversal potential, or else an error.
* Add `test_ca.mod` mechanism that writes calcium ion concentration for testing purposes.
* Add back-end callbacks that initialize concentration values.
* Update `mechanism::uses_ion()` to return information regarding mechanism ion concentration updates.
* Add `mechanism::write_back()` method.
* Update stimulus mechanism specialization to use new mechanism interface.
* Update `ion` type to calculate default concentration contributions in CVs where the concentration is only partially determined by mechanisms.
* Update `fvm_multicell` to calculate the default ion concentration weights.
* Add unit test for ion concentration weight determination.

Fixes #373 

* Remove optimization option (use SIMD options for vectorization).
* Remove arbor utility library dependencies from modcc (pending separation of utility lib from arbor lib source).
* Split target (cpu, gpu) specification from vectorization architecture (avx2, avx512).
* Remove `Options` singleton; replace with structure local to `modcc.cpp`.
* Tidy `modcc` option parsing and main function; allow a single invocation of `modcc` to generate code for multiple backends.
* Rename generated sources to include backend target in filename.
* Always run a constant simplification pass on generated procedures.
* Remove file i/o code from `Module` and `modcc` main function; move functionality to new functions in `io` namespace. (Note: in on-going mechanism revamp, other i/o utility code will reside in the `io` namespace and subdirectory.)
* Remove classes `ConstantFolderVisitor` and `ExpressionClassifierVisitor` that are no longer used.
* Modify CMakeLists.txt files, `backends/*/fvm.cpp` to reflect the new filenames of generated sources.
* Small formatting changes in `modcc` source to reflect coding guidelines (incomplete).

Fixes #399.

Update `test_printers.cpp`:
* Fix compilation and scope management issues, and re-include in CMakeLists.txt.
* Update to use `verbose_print` (run-time verbosity).
* Apply expected output tests to `CPrinter` and `CUDAPrinter` outputs.

Address binary operation rendering issue:
* Move C-style expression rendering common to `CPrinter` and `CUDAPrinter` to a specialized `Visitor`, `CExprRenderer`.
* Use operator associativity to determine need for parentheses around sub-expressions of a binary expression.

Ben Cumming authored 7 years ago and Sam Yates committed 7 years ago

* Properly iterate over all event queues in the case where a cell group has more than once cell (triggered in e.g. GPU miniapp).
* Update GPU unit test to use the new `cell_group::advance()` interface.

Ben Cumming authored 7 years ago and Sam Yates committed 7 years ago

Derivatives should only appear on the left hand side of expressions that describe the time evolution of state variables. Without this check `modcc` segfaulted when processing a derivative expression of a non-state variable.

* Specialize the semantic analysis of `DerivativeExpression` to enforce that derivatives are only applied to state variables.

Ben Cumming authored 7 years ago and Sam Yates committed 7 years ago

* Remove `cell_group::enqueue_events` interface: `cell_group::advance` is given the events to deliver in the next epoch directly.
* Implement event lane merging in `model` with stand-alone `merge_events` function.
* Ensure event-delivery order is preserved across differing domain decompositions by performing a lexicographic sort over all of the `postsynaptic_spike_event` fields: fixes #385. 
                                                                                                         
Fixes #378.

These classes aim to provide an alternative to `TextBuffer` in `modcc` printers.

* Implement a streambuf wrapper `prefixbuf` that prepends a prefix string to each line.
* Adds stream manipulators `setprefix`, `indent`, `popindent`, `settab` for manipulating the prefix in a `prefixbuf`.
* Provide a wrapper stream `pfxstringstream` around `std::stringbuf` with `std::ostringstream` semantics.

As implemented, a prefix string set with the `setprefix` is applied to the underlying streambuf, and is not a property of the stream. This behaviour may be surprising, so consider storing this prefix with the stream as a possible enhancement.