From 5447e2a85890503d914598ca5f9a8682e0265bd1 Mon Sep 17 00:00:00 2001
From: Brent Huisman <brenthuisman@users.noreply.github.com>
Date: Tue, 2 Feb 2021 16:59:59 +0100
Subject: [PATCH] Clarify sample collection in distributed contexts. (#1331)
---
doc/python/simulation.rst | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/doc/python/simulation.rst b/doc/python/simulation.rst
index c162d1e9..cad11a46 100644
--- a/doc/python/simulation.rst
+++ b/doc/python/simulation.rst
@@ -135,6 +135,13 @@ over the local and distributed hardware resources (see :ref:`pydomdec`). Then, t
Retrieve a list of sample data associated with the given ``handle``.
There will be one entry in the list per probe associated with the probe id used when the sampling was set up.
+ For example, if a probe was placed on a locset describing three positions, the returned list will contain three elements.
+
+ An empty list will be returned if no output was recorded for the cell. For simulations
+ that are distributed using MPI, handles associated with non-local cells will return an
+ empty list.
+ It is the responsibility of the caller to gather results over the ranks.
+
Each entry is a pair ``(samples, meta)`` where ``meta`` is the probe metadata as would be returned by
``probe_metadata(probe_id)``, and ``samples`` contains the recorded values.
--
GitLab