Closes #1861 
Closes #1783 

- arbor-build-catalogue (a-b-c) does no longer need to be in a fixed location
- nor do we statically fix the configuration for a-b-c
- instead, we rely on `arbor.config` to read the relevant default values
- each value can be overriden, if desired
- added many more values to the configuration
  - gpu type and arch
  - paths and prefix 
  - CXX
- report default settings for better diagnosis
- implement a fallback for prefix if that does not exist; in particular for the amazing skbuild.

In essence you can now use a-b-c as a standalone tool, as long as you have a properly 
configured py-arbor.

Example output after removing `_skbuild`
```
Warning: prefix '/Users/hater/src/arbor/_skbuild/macosx-11.0-x86_64-3.10/cmake-install' does not exist, falling back to '/Users/hater/src/arbor/.direnv/python-3.10.6'.
usage: arbor-build-catalogue catalogue_name mod_source_dir

Generate dynamic catalogue and build it into a shared object.

positional arguments:
  name              Catalogue name.
  modpfx            Directory name where *.mod files live.

options:
  --raw raw [raw ...]
                    Advanced: Raw mechanisms as C++ files. Per <name> the files <name>.hpp, <name>_cpu.cpp (if CPU
                    is enabled) must be present in the target directory and with GPU support also <name>_gpu.cpp and
                    <name>_gpu.cu.
  -v, --verbose     Verbose.
  -q, --quiet       Less output.
  --cpu CPU         Enable CPU support.
  --debug [path]    Don't clean up the generated temp cpp code. Can be a target path for the generated code.
  --gpu gpu         Enable GPU support
  --gpu-arch gpu_arch
                    Enable GPU support; default=-
  --cxx cxx         Use this C++ compiler; default=/usr/local/opt/llvm/bin/clang++.
  --prefix prefix   Arbor's install prefix; default=/Users/hater/src/arbor/.direnv/python-3.10.6.
  --bin bin         Look here for Arbor utils like modcc; relative to prefix, default=bin.
  --lib lib         Look here for Arbor's CMake config; relative to prefix, default=lib.
  --data data       Look here for Arbor supplementals like generate_catalogue; relative to prefix, default=lib
  -h, --help        Display this help and exit.
```

Add functionality, docs, and examples on editing the connection table.  This is a first, small PR
on the topic, further functionality will come as requested.

Teaser example
```cxx
    // This recipe -- omitted -- implements a mutable connection table 
    // and returns it via the `connections_on` callback. New entries are
    // added using `add_connection` which makes one link from a central 
    // `spike_source_cell` to the given `gid`
    auto rec = recipe();
    rec.add_connection(1);

    auto sim = arb::simulation(rec, ctx);

    // Record spikes
    std::vector<arb::spike> spikes;
    sim.set_local_spike_callback([&spikes](const auto& s) { spikes.insert(spikes.end(), s.begin(), s.end()); });

    // Run and print all spikes per gid
    sim.run(0.25, 0.025);
    show_spikes(spikes);

    // Add a new connection
    rec.add_connection(2);
    sim.update_connections(rec);

    // Run and print all spikes per gid
    sim.run(0.5, 0.025);
    show_spikes(spikes);
```

# Update July '22

- added re-wiring of Event Generators
- implemented a split between a recipe and a recipe-update (cheekily dubbed `topping` until further notice)
- `recipes` are `toppings` via inheritance

Encapsulates 80% of cases:
```cxx
 rec = recipe()
 ctx = make_context()
 dec = partition_load_balance(rec, ctx)
 sim = simulation(rec, dec, ctx)
```
is now written as
```cxx
 rec = recipe()
 sim = simulation(rec)
```
In python we use keyword args to allow
both to be specified separatly.

Partially fixes #1862 

* Pyarb specific.
* `proc_allocation_shim()` throws error if user sets threads to zero.
* `arbor.context` constructor accepts `threads` set to `"avail_threads"`, which sets the number of threads to `arbenv::thread_concurrency()`
  * This introduces a dependency on arbenv for Pyarb.
* Docs and tests added.

Fixes #1692 

* Substitute `std::optional<T>` for `arb::util::optional<T>` for non-reference types T.
* Remove reference-deducing `util::value_by_key`; replace usages with new function `util::ptr_by_key`.
* Add some missing header includes that were required but included only transitively.
* Remove `operator<<` overload for optional in python/strprintf.hpp; replace with utility wrapper class that catches `std::optional<T>`.
* Wrap some `std::optional` values with `to_string` in ostream output in python lib.

Fixes #1154.

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

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

Domain decomposition in python wrapper
* functions: `partition_load_balance`
*  types: `group_description` and `domain_decomposition`

Also includes
* remove comment that `gid` in a `group_description` must be sorted.
* a host of small clean ups of python wrapper

Fixes #761

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

Fixes #760

Wraps arbor recipe (without probes, i.e. num_probes, probe_info, get_probe) including 

- cell_connection, 
- gap_junction_connection, 
- recipe with
  - num_cells
  - cell_description
  - cell_kind
  - num_sources
  - num_targets
  - num_gap_junctions_sites
  - event_generators
  - connections_on
  - gap_junctions_on
  - global_properties
- enum cell_kind in `identifiers.cpp`

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

 + Included conversion from `pybind11::object()` to `arb::util::optional` for `arbor.proc_allocation().gpu_id` and exception handling for `arbor.context(mpi=comm)`.

+ cleaned-up `test_event_generator.py`

+ for discussion: How do we want to handle the strings? Include them in appropriate `.cpp` or collect them in `strings.c/hpp`?

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

Wrapped the following C++ features in Python: 
- Identifiers (`cell_member`) + according tests
- `event_generator` and schedules (`regular_schedule`, `explicit_schedule`, `poisson_schedule`) + according tests

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

First step towards the Python front end.

This commit sets up the structure of the python implementation
* directory structure
* git submodule for pybind11
* best practices for making bindings with pybind11
* unit testing for the python front end

It implements the following features in the Python front end
* execution contexts
* gpu detection
* thread count detection
* MPI initialization helpers.

Fixes #667.