probe id -> probeset id, and clarification in docs

arbor/arbexcept.cpp

@@ -44,9 +44,9 @@ zero_thread_requested_error::zero_thread_requested_error(unsigned nbt):
     nbt(nbt)
 {}
 
-bad_probe_id::bad_probe_id(cell_member_type probe_id):
-    arbor_exception(pprintf("bad probe id {}", probe_id)),
-    probe_id(probe_id)
+bad_probeset_id::bad_probeset_id(cell_member_type probeset_id):
+    arbor_exception(pprintf("bad probe id {}", probeset_id)),
+    probeset_id(probeset_id)
 {}
 
 gj_unsupported_lid_selection_policy::gj_unsupported_lid_selection_policy(cell_gid_type gid, cell_tag_type label):

arbor/benchmark_cell_group.cpp

@@ -95,7 +95,7 @@ void benchmark_cell_group::clear_spikes() {
 }
 
 void benchmark_cell_group::add_sampler(sampler_association_handle h,
-                                   cell_member_predicate probe_ids,
+                                   cell_member_predicate probeset_ids,
                                    schedule sched,
                                    sampler_function fn,
                                    sampling_policy policy) {}

arbor/benchmark_cell_group.hpp

@@ -28,7 +28,7 @@ class benchmark_cell_group: public cell_group {
 
     void clear_spikes() override;
 
-    void add_sampler(sampler_association_handle h, cell_member_predicate probe_ids, schedule sched, sampler_function fn, sampling_policy policy) override;
+    void add_sampler(sampler_association_handle h, cell_member_predicate probeset_ids, schedule sched, sampler_function fn, sampling_policy policy) override;
 
     void remove_sampler(sampler_association_handle h) override {}
 

arbor/fvm_lowered_cell.hpp

@@ -188,9 +188,9 @@ struct probe_association_map {
         return data.size();
     }
 
-    // Return range of fvm_probe_data values associated with probe_id.
-    auto data_on(cell_member_type probe_id) const {
-        return util::transform_view(util::make_range(data.equal_range(probe_id)), util::second);
+    // Return range of fvm_probe_data values associated with probeset_id.
+    auto data_on(cell_member_type probeset_id) const {
+        return util::transform_view(util::make_range(data.equal_range(probeset_id)), util::second);
     }
 };
 

arbor/fvm_lowered_cell_impl.hpp

@@ -620,11 +620,11 @@ fvm_initialization_data fvm_lowered_cell_impl<Backend>::initialize(
                 D, mech_data, fvm_info.target_handles, mechptr_by_name);
 
             if (!probe_data.empty()) {
-                cell_member_type probe_id{gid, i};
-                fvm_info.probe_map.tag[probe_id] = pi.tag;
+                cell_member_type probeset_id{gid, i};
+                fvm_info.probe_map.tag[probeset_id] = pi.tag;
 
                 for (auto& data: probe_data) {
-                    fvm_info.probe_map.data.insert({probe_id, std::move(data)});
+                    fvm_info.probe_map.data.insert({probeset_id, std::move(data)});
                 }
             }
         }

arbor/include/arbor/arbexcept.hpp

@@ -67,9 +67,9 @@ struct ARB_SYMBOL_VISIBLE bad_global_property: arbor_exception {
     cell_kind kind;
 };
 
-struct ARB_SYMBOL_VISIBLE bad_probe_id: arbor_exception {
-    explicit bad_probe_id(cell_member_type id);
-    cell_member_type probe_id;
+struct ARB_SYMBOL_VISIBLE bad_probeset_id: arbor_exception {
+    explicit bad_probeset_id(cell_member_type id);
+    cell_member_type probeset_id;
 };
 
 struct ARB_SYMBOL_VISIBLE gj_kind_mismatch: arbor_exception {

arbor/include/arbor/simulation.hpp

@@ -34,7 +34,7 @@ class ARB_ARBOR_API simulation {
     // Note: sampler functions may be invoked from a different thread than that
     // which called the `run` method.
 
-    sampler_association_handle add_sampler(cell_member_predicate probe_ids,
+    sampler_association_handle add_sampler(cell_member_predicate probeset_ids,
         schedule sched, sampler_function f, sampling_policy policy = sampling_policy::lax);
 
     void remove_sampler(sampler_association_handle);
@@ -43,7 +43,7 @@ class ARB_ARBOR_API simulation {
 
     // Return probe metadata, one entry per probe associated with supplied probe id,
     // or an empty vector if no local match for probe id.
-    std::vector<probe_metadata> get_probe_metadata(cell_member_type probe_id) const;
+    std::vector<probe_metadata> get_probe_metadata(cell_member_type probeset_id) const;
 
     std::size_t num_spikes() const;
 

arbor/lif_cell_group.cpp

@@ -59,7 +59,7 @@ void lif_cell_group::clear_spikes() {
 }
 
 // TODO: implement sampler
-void lif_cell_group::add_sampler(sampler_association_handle h, cell_member_predicate probe_ids,
+void lif_cell_group::add_sampler(sampler_association_handle h, cell_member_predicate probeset_ids,
                                     schedule sched, sampler_function fn, sampling_policy policy) {}
 void lif_cell_group::remove_sampler(sampler_association_handle h) {}
 void lif_cell_group::remove_all_samplers() {}

arbor/mc_cell_group.cpp

@@ -94,7 +94,7 @@ void mc_cell_group::set_binning_policy(binning_kind policy, time_type bin_interv
 
 struct sampler_call_info {
     sampler_function sampler;
-    cell_member_type probe_id;
+    cell_member_type probeset_id;
     probe_tag tag;
     unsigned index;
     const fvm_probe_data* pdata_ptr;
@@ -151,7 +151,7 @@ void run_samples(
        sample_records.push_back(sample_record{time_type(raw_times[i]), &raw_samples[i]});
     }
 
-    sc.sampler({sc.probe_id, sc.tag, sc.index, p.get_metadata_ptr()}, n_sample, sample_records.data());
+    sc.sampler({sc.probeset_id, sc.tag, sc.index, p.get_metadata_ptr()}, n_sample, sample_records.data());
 }
 
 void run_samples(
@@ -181,7 +181,7 @@ void run_samples(
         sample_records.push_back(sample_record{time_type(raw_times[offset]), &ctmp[j]});
     }
 
-    sc.sampler({sc.probe_id, sc.tag, sc.index, p.get_metadata_ptr()}, n_sample, sample_records.data());
+    sc.sampler({sc.probeset_id, sc.tag, sc.index, p.get_metadata_ptr()}, n_sample, sample_records.data());
 }
 
 void run_samples(
@@ -211,7 +211,7 @@ void run_samples(
         sample_records.push_back(sample_record{time_type(raw_times[offset]), &csample_ranges[j]});
     }
 
-    sc.sampler({sc.probe_id, sc.tag, sc.index, p.get_metadata_ptr()}, n_sample, sample_records.data());
+    sc.sampler({sc.probeset_id, sc.tag, sc.index, p.get_metadata_ptr()}, n_sample, sample_records.data());
 }
 
 void run_samples(
@@ -254,7 +254,7 @@ void run_samples(
         sample_records.push_back(sample_record{time_type(raw_times[offset]), &csample_ranges[j]});
     }
 
-    sc.sampler({sc.probe_id, sc.tag, sc.index, p.get_metadata_ptr()}, n_sample, sample_records.data());
+    sc.sampler({sc.probeset_id, sc.tag, sc.index, p.get_metadata_ptr()}, n_sample, sample_records.data());
 }
 
 void run_samples(
@@ -301,7 +301,7 @@ void run_samples(
         sample_records.push_back(sample_record{time_type(raw_times[offset]), &csample_ranges[j]});
     }
 
-    sc.sampler({sc.probe_id, sc.tag, sc.index, p.get_metadata_ptr()}, n_sample, sample_records.data());
+    sc.sampler({sc.probeset_id, sc.tag, sc.index, p.get_metadata_ptr()}, n_sample, sample_records.data());
 }
 
 void run_samples(
@@ -375,7 +375,7 @@ void run_samples(
         sample_records.push_back(sample_record{time_type(raw_times[offset]), &csample_ranges[j]});
     }
 
-    sc.sampler({sc.probe_id, sc.tag, sc.index, p.get_metadata_ptr()}, n_sample, sample_records.data());
+    sc.sampler({sc.probeset_id, sc.tag, sc.index, p.get_metadata_ptr()}, n_sample, sample_records.data());
 }
 
 // Generic run_samples dispatches on probe info variant type.
@@ -476,7 +476,7 @@ void mc_cell_group::advance(epoch ep, time_type dt, const event_lane_subrange& e
             sample_size_type n_times = sample_times.size();
             max_samples_per_call = std::max(max_samples_per_call, n_times);
 
-            for (cell_member_type pid: sa.probe_ids) {
+            for (cell_member_type pid: sa.probeset_ids) {
                 auto cell_index = gid_index_map_.at(pid.gid);
 
                 probe_tag tag = probe_map_.tag.at(pid);
@@ -555,13 +555,13 @@ void mc_cell_group::advance(epoch ep, time_type dt, const event_lane_subrange& e
     }
 }
 
-void mc_cell_group::add_sampler(sampler_association_handle h, cell_member_predicate probe_ids,
+void mc_cell_group::add_sampler(sampler_association_handle h, cell_member_predicate probeset_ids,
                                 schedule sched, sampler_function fn, sampling_policy policy)
 {
     std::lock_guard<std::mutex> guard(sampler_mex_);
 
     std::vector<cell_member_type> probeset =
-        util::assign_from(util::filter(util::keys(probe_map_.tag), probe_ids));
+        util::assign_from(util::filter(util::keys(probe_map_.tag), probeset_ids));
 
     if (!probeset.empty()) {
         auto result = sampler_map_.insert({h, sampler_association{std::move(sched), std::move(fn), std::move(probeset), policy}});
@@ -579,21 +579,21 @@ void mc_cell_group::remove_all_samplers() {
     sampler_map_.clear();
 }
 
-std::vector<probe_metadata> mc_cell_group::get_probe_metadata(cell_member_type probe_id) const {
+std::vector<probe_metadata> mc_cell_group::get_probe_metadata(cell_member_type probeset_id) const {
     // Probe associations are fixed after construction, so we do not need to grab the mutex.
 
-    std::optional<probe_tag> maybe_tag = util::value_by_key(probe_map_.tag, probe_id);
+    std::optional<probe_tag> maybe_tag = util::value_by_key(probe_map_.tag, probeset_id);
     if (!maybe_tag) {
         return {};
     }
 
-    auto data = probe_map_.data_on(probe_id);
+    auto data = probe_map_.data_on(probeset_id);
 
     std::vector<probe_metadata> result;
     result.reserve(data.size());
     unsigned index = 0;
     for (const fvm_probe_data& item: data) {
-        result.push_back(probe_metadata{probe_id, *maybe_tag, index++, item.get_metadata_ptr()});
+        result.push_back(probe_metadata{probeset_id, *maybe_tag, index++, item.get_metadata_ptr()});
     }
 
     return result;

arbor/mc_cell_group.hpp

@@ -52,14 +52,14 @@ class ARB_ARBOR_API mc_cell_group: public cell_group {
         spikes_.clear();
     }
 
-    void add_sampler(sampler_association_handle h, cell_member_predicate probe_ids,
+    void add_sampler(sampler_association_handle h, cell_member_predicate probeset_ids,
                      schedule sched, sampler_function fn, sampling_policy policy) override;
 
     void remove_sampler(sampler_association_handle h) override;
 
     void remove_all_samplers() override;
 
-    std::vector<probe_metadata> get_probe_metadata(cell_member_type probe_id) const override;
+    std::vector<probe_metadata> get_probe_metadata(cell_member_type probeset_id) const override;
 
 private:
     // List of the gids of the cells in the group.

arbor/sampler_map.hpp

@@ -18,7 +18,7 @@ namespace arb {
 struct sampler_association {
     schedule sched;
     sampler_function sampler;
-    std::vector<cell_member_type> probe_ids;
+    std::vector<cell_member_type> probeset_ids;
     sampling_policy policy;
 };
 

arbor/simulation.cpp

@@ -96,7 +96,7 @@ class simulation_state {
 
     time_type run(time_type tfinal, time_type dt);
 
-    sampler_association_handle add_sampler(cell_member_predicate probe_ids,
+    sampler_association_handle add_sampler(cell_member_predicate probeset_ids,
         schedule sched, sampler_function f, sampling_policy policy = sampling_policy::lax);
 
     void remove_sampler(sampler_association_handle);
@@ -450,15 +450,15 @@ time_type simulation_state::run(time_type tfinal, time_type dt) {
 }
 
 sampler_association_handle simulation_state::add_sampler(
-        cell_member_predicate probe_ids,
+        cell_member_predicate probeset_ids,
         schedule sched,
         sampler_function f,
         sampling_policy policy)
 {
     sampler_association_handle h = sassoc_handles_.acquire();
 
     foreach_group(
-        [&](cell_group_ptr& group) { group->add_sampler(h, probe_ids, sched, f, policy); });
+        [&](cell_group_ptr& group) { group->add_sampler(h, probeset_ids, sched, f, policy); });
 
     return h;
 }
@@ -477,9 +477,9 @@ void simulation_state::remove_all_samplers() {
     sassoc_handles_.clear();
 }
 
-std::vector<probe_metadata> simulation_state::get_probe_metadata(cell_member_type probe_id) const {
-    if (auto linfo = util::value_by_key(gid_to_local_, probe_id.gid)) {
-        return cell_groups_.at(linfo->group_index)->get_probe_metadata(probe_id);
+std::vector<probe_metadata> simulation_state::get_probe_metadata(cell_member_type probeset_id) const {
+    if (auto linfo = util::value_by_key(gid_to_local_, probeset_id.gid)) {
+        return cell_groups_.at(linfo->group_index)->get_probe_metadata(probeset_id);
     }
     else {
         return {};
@@ -529,12 +529,12 @@ time_type simulation::run(time_type tfinal, time_type dt) {
 }
 
 sampler_association_handle simulation::add_sampler(
-    cell_member_predicate probe_ids,
+    cell_member_predicate probeset_ids,
     schedule sched,
     sampler_function f,
     sampling_policy policy)
 {
-    return impl_->add_sampler(std::move(probe_ids), std::move(sched), std::move(f), policy);
+    return impl_->add_sampler(std::move(probeset_ids), std::move(sched), std::move(f), policy);
 }
 
 void simulation::remove_sampler(sampler_association_handle h) {
@@ -545,8 +545,8 @@ void simulation::remove_all_samplers() {
     impl_->remove_all_samplers();
 }
 
-std::vector<probe_metadata> simulation::get_probe_metadata(cell_member_type probe_id) const {
-    return impl_->get_probe_metadata(probe_id);
+std::vector<probe_metadata> simulation::get_probe_metadata(cell_member_type probeset_id) const {
+    return impl_->get_probe_metadata(probeset_id);
 }
 
 std::size_t simulation::num_spikes() const {

arbor/spike_source_cell_group.hpp

@@ -31,7 +31,7 @@ class ARB_ARBOR_API spike_source_cell_group: public cell_group {
 
     void clear_spikes() override;
 
-    void add_sampler(sampler_association_handle h, cell_member_predicate probe_ids, schedule sched, sampler_function fn, sampling_policy policy) override;
+    void add_sampler(sampler_association_handle h, cell_member_predicate probeset_ids, schedule sched, sampler_function fn, sampling_policy policy) override;
 
     void remove_sampler(sampler_association_handle h) override {}
 

doc/concepts/probe_sample.rst

@@ -3,8 +3,55 @@
 Cable cell probing and sampling
 ===============================
 
-.. TODO::
-    WIP!
+Definitions
+***********
+
+.. glossary::
+
+    probe
+        A measurement that can be performed on a cell. Each cell kind will have its own sorts of probe;
+        Cable cells (:py:attr:`arbor.cable_probe`) allow the monitoring of membrane voltage, total membrane
+        current, mechanism state, and a number of other quantities, measured either over the whole cell,
+        or at specific sites (see :ref:`pycablecell-probesample`).
+
+    probeset
+        A set of probes. Probes are placed on locsets, and therefore may describe more than one probe.
+
+    probeset address
+        Probesets are located at a probeset address, and the collection of probeset addresses for a given cell is
+        provided by the :py:class:`recipe` object. One address may correspond to more than one probe:
+        as an example, a request for membrane voltage on a cable cell at sites specified by a location
+        expression will generate one probe for each site in that location expression.
+
+        See :ref:`pycablecell-probesample` for a list of objects that return a probeset address.
+
+    probeset id
+        A designator a probeset as specified by a recipe. The *probeset id* is a
+        :py:class:`cell_member` referring to a specific cell by gid, and the index into the list of
+        probeset addresses returned by the recipe for that gid.
+
+    metadata
+        Each probe has associated metadata describing, for example, the location on a cell where the
+        measurement is being taken, or other such identifying information. Metadata for the probes
+        associated with a :term:`probeset id` can be retrieved from the simulation object, and is also provided
+        along with any recorded samples.
+
+    sampler
+        A sampler is something that receives probeset data. It amounts to setting a particular :term:`probeset` to a
+        particular measuring schedule, and then having a :term:`handle` with which to access the recorded probeset data later on.
+
+    sample
+        A record of data corresponding to the value at a specific *probe* at a specific time.
+
+    handle
+        A handle for reaching sampling data associated to a sampler, which is associated to a probeset.
+        Setting a sampler (through :py:func:`simulation.sample`) returns handles. Sampled data can be retrieved
+        by passing the handle associated to a sampler (associated to a probeset) to :py:func:`simulation.samples`.
+
+    schedule
+        An object representing a series of monotonically increasing points in time, used for determining
+        sample times (see :ref:`pyrecipe`).
+
 
 API
 ---