Ux/units

[thorstenhater]

The core issue here is to add units to the user facing API. I decided on using the LLNL/units
library, which offers conversion and checking at runtime. Runtime is a requirement -- as much
as I love static guarantees --, but keeping the interface uniform between Python and C++ is a
must.

While setting this up, I noticed the severe lack of IDE/LSP support for Arbor, so I added typing
stubs using https:/sizmailov/pybind11-stubgen. The conjunction of typing and units
exposed misuse of pybind11 in several places, so next I had to massage the ordering of bindings,
adjust the specification of default arguments, and add the odd missing binding.

The schedule/event generator interface was tightened up, hiding the *_impl structs and exposing
only the type erased schedule object. That in turn required de-generification of the Poisson
schedule. Now, Mersenne twister is the only choice and I will remove that later on for the CBRNG
we are already using elsewhere.

Currently, units are used for:

• simulation
• schedule/generator
• paintables
• placeables
  • iclamp
  • threshold
• connections
• gap junctions

Adding units to mechanism interfaces is interesting but requires more work and thought, so
I'll defer that to a later point in time. We'd need to adjust modcc to expose and check units
and devise a scheme to handle missing units.

Generic TODOs; some might spin off into separate issues.

• rename py::iclamp OR cpp::i_clamp for consistency covered by Consistency in Naming #2239
• use scale/base for iexpr paintables for consistency with scaled_mech
• Use CBRNG for Poisson schedule covered by Use CBRNG for Schedules #2243
• Automate stub generation. A wishlist item, requires installing extra software.
• Properly integrate units w/ spack. NB. Units doesn't have a spackage.

Closes #1983
Closes #2032

[thorstenhater]

Note to reviewer: Spack is broken on stable for some reason out of my control; Develop works fine, though.

[boeschf]

First round, haven't looked at everything yet. Massive PR, lots of work! thanks for tackling this.
Have you noticed any appreciable performance hits due to runtime unit conversion and checking?

[thorstenhater]

Note about performance: This is only at the outer most 'shell' of our API. Everything below is
not unit-tagged. For that, I'd use -- if at all -- a compile time library (some choices available).
Here, we cannot, as we need to support Python's dynamic typing.

So, it comes down to constructing a class per such API call, some math ops, and a check. The most
expensive is explicit_schedule. All that is bounded by place, paint, and generators and runs at
model description time (not even construction inside Arbor).

[boeschf]

So this is the second round. Expect the Python stuff in round 3. A couple general remarks:

• what type is the expression1*U::ms converted to? It should be quantity but I'm unsure
• the reformatting of many files makes the review tedious. we should start thinking about an automated way (clang-format, git pre-commit hooks, CI checks etc) in order to minimize changes

[boeschf]

Suggested change

	constexpr static auto default_seed = engine_type::default_seed;
	inline constexpr auto default_seed = engine_type::default_seed;

[boeschf]

what about adding a function which generates a random seed value, possibly using std::random_device?

[thorstenhater]

Hm. I am unsure whether I like that. The next step here should be to eradicate std::random and use r123 everywhere. Then seeding should be a function of cell gid and the relevant item's index. For example one would seed an event_generator with gid*100 + lid where lid is the running count of the generator in the list. We might consider giving users a convenience function/helper thing there to partially automate this.

In general, I refrain from this for reasons of reproducibility, since all kinds of ordering or reentrancy (word!) come into play. Thus, even now, I'd suggest using the gid + some offset as a seed in recipes.

[thorstenhater]

So this is the second round. Expect the Python stuff in round 3. A couple general remarks:

* what type is the expression`1*U::ms` converted to? It should be `quantity` but I'm unsure

Yes, it's a simple way to get a quantity from a unit.

* the reformatting of  many files makes the review tedious. we should start thinking about an automated way (clang-format, git pre-commit  hooks, CI checks etc) in order to minimize changes

Agreed, ten times over. I am also on record about not really caring about the actual style, just about consistency and automation.

[boeschf]

round 3

[boeschf]

cscs-ci run daint-gpu

[boeschf]

Very nice, thanks