Finish round three of review

doc/concepts/units.rst

@@ -7,7 +7,7 @@ Units in Arbor
 
    This is a work in progress. The near goal term is to make this coverage
    complete, but expect some exceptions. Notably, the interfaces of individual
-   mechanis are not yet integrate, since NMODL files -- despite explicitly
+   mechanism are not yet integrated, since NMODL files -- despite explicitly
    specifying units -- do not make good use of the feature.
 
 A large part of the interface of Arbor -- both in C++ and Python -- is covered
@@ -89,6 +89,26 @@ the catalogue of units via the underlying units library.
     centi           1e-2
    =============   =======   =============   =======
 
+Parameters are passed into Arbor via a ``quantity``, which comprise a value and
+a unit. We construct a quantity by multiplication of a scalar value by a unit.
+Multiplication of two quantities will result in the pointwise product of the
+values and units; like one would expect.
+
+.. code-block:: python
+
+    # two kilometers, dimension is length
+    l = 2 * km
+
+    # three kilometers, but with the scaling factored out
+    s = 3 * kilo * m
+
+    # multiplication of two lengths gives an area
+    a = l * s
+    # is now 6 square kilometers
+
+Units and quantities work intuitively and largely the same across C++ and
+Python, but we provide some details below.
+
 C++
 ---
 

doc/tutorial/calcium_stdp_curve.rst

@@ -128,12 +128,11 @@ Our cell and cell properties can then later be used to create a simple recipe:
    :language: python
    :lines: 74-98
 
-Note, that the recipe takes a cell, cell properties and a list of event
-generators as constructor arguments and returns them with its corresponding
-methods. Furthermore, the recipe also returns a list of probes which contains
-only one item: A query for our mechanism's state variable :math:`\rho`. Since we
-placed a number of these mechanisms on our cell, we will receive a vector of
-values when probing.
+Note, that the recipe takes a cell and a list of time offsets as constructor
+arguments, which are used to create the cells of the ensemble. Furthermore, the
+recipe also returns a list of probes which contains only one item: A query for
+our mechanism's state variable :math:`\rho`. Since we placed a number of these
+mechanisms on our cell, we will receive a vector of values when probing.
 
 Next we set up the simulation logic:
 

doc/tutorial/single_cell_detailed.rst

@@ -55,7 +55,7 @@ insertion order below, but different orders will produce the same morphology.
     tree = arbor.segment_tree()
 
     # The root of the tree has no parent
-    root = A.mnpos
+    root = arbor.mnpos
 
     # The root segment: a cylindrical soma with tag 1
     # NOTE: append returns the added segment's id, which we can use to
@@ -89,7 +89,7 @@ insertion order below, but different orders will produce the same morphology.
     axon = tree.append(axon, (-70.0, 0.0, 0.0, 0.4), (-100.0, 0.0, 0.0, 0.4), tag=2)
 
     # Turn segment tree into a morphology.
-    morph = A.morphology(tree);
+    morph = arbor.morphology(tree);
 
 The same morphology can be represented using an SWC file (interpreted according
 to :ref:`Arbor's specifications <morph-formats>`). We can save the following in
@@ -257,14 +257,14 @@ This will generate the following 2 locsets when applied to the previously define
 
    .. code-block:: python
 
-       decor.paint('(all)', A.density("pas"))
+       decor.paint('(all)', arbor.density("pas"))
 
    is perfectly acceptable, as is
 
    .. code-block:: python
 
        all = '(all)'
-       decor.paint(all, A.density("pas"))
+       decor.paint(all, arbor.density("pas"))
 
 
 The decorations

python/example/probe_lfpykit.py

@@ -93,7 +93,10 @@ def probes(self, _):
     .discretization(A.cv_policy_fixed_per_branch(3))
 )
 
-p = A.place_pwlin(morphology)
+# place_pwlin can be queried with region/locset expressions to obtain
+# geometrical objects, like points and segments, essentially recovering
+# geometry from morphology.
+ppwl = A.place_pwlin(morphology)
 cell = A.cable_cell(morphology, decor)
 
 # instantiate recipe with cell
@@ -169,7 +172,7 @@ def __init__(self, p, cables):
         CV_ind = np.array([], dtype=int)  # tracks which CV owns segment
         for i, m in enumerate(cables):
             segs = p.segments([m])
-            for j, seg in enumerate(segs):
+            for seg in segs:
                 x = np.row_stack([x, [seg.prox.x, seg.dist.x]])
                 y = np.row_stack([y, [seg.prox.y, seg.dist.y]])
                 z = np.row_stack([z, [seg.prox.z, seg.dist.z]])
@@ -232,7 +235,7 @@ def get_transformation_matrix(self):
 
 
 # create ``ArborCellGeometry`` instance
-cell_geometry = ArborCellGeometry(p, I_m_meta)
+cell_geometry = ArborCellGeometry(ppwl, I_m_meta)
 
 # define locations where extracellular potential is predicted in vicinity
 # of cell.
@@ -400,7 +403,7 @@ def colorbar(
 ax.add_collection(get_segment_outlines(cell_geometry))
 
 # add marker denoting clamp location
-point = p.at(clamp_location)
+point = ppwl.at(clamp_location)
 ax.plot(point.x, point.y, "ko", ms=10, label="stimulus")
 
 ax.legend()

python/example/single_cell_allen.py

@@ -81,7 +81,7 @@ def make_cell(base, swc, fit):
     morphology = A.load_swc_neuron(base / swc)
 
     # (2) Label the region tags found in the swc with the names used in the parameter fit file.
-    # In addition, label the midpoint of the somA.
+    # In addition, label the midpoint of the soma.
     labels = A.label_dict().add_swc_tags()
     labels["midpoint"] = "(location 0 0.5)"
 

python/schedule.cpp

@@ -29,8 +29,8 @@ std::ostream& operator<<(std::ostream& o, const explicit_schedule_shim& e) {
 }
 
 std::ostream& operator<<(std::ostream& o, const poisson_schedule_shim& p) {
-    return o << "<arbor.poisson_schedule: tstart " << arb::units::to_string(p.tstart) << " ms"
-             << ", tstop " << arb::units::to_string(p.tstop) << " ms"
+    return o << "<arbor.poisson_schedule: tstart " << arb::units::to_string(p.tstart)
+             << ", tstop " << arb::units::to_string(p.tstop)
              << ", freq " << arb::units::to_string(p.freq)
              << ", seed " << p.seed << ">";
 }
@@ -100,6 +100,7 @@ std::vector<arb::time_type> regular_schedule_shim::events(arb::time_type t0, arb
 
 explicit_schedule_shim::explicit_schedule_shim(const std::vector<arb::units::quantity>& seq) {
     std::vector<arb::time_type> ts;
+    ts.reserve(seq.size());
     for (const auto t: seq) ts.push_back(t.value_as(arb::units::ms));
     set_times_ms(std::move(ts));
 }