statrl 1.2609__tar.gz

statrl-1.2609/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 statrl contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

statrl-1.2609/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: statrl
+Version: 1.2609
+Summary: The Statistical Reinforcement Learning Toolkit Library
+Author-email: Odalric-Ambrym Maillard <odalricambrym.maillard@inria.fr>
+License: MIT
+Project-URL: Homepage, https://github.com/StatisticalRL/statrl
+Project-URL: Repository, https://github.com/StatisticalRL/statrl
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gymnasium>=1.0
+Requires-Dist: numpy>=2.5
+Requires-Dist: joblib>=1.5
+Requires-Dist: matplotlib>=3.9
+Requires-Dist: scipy>=1.17
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Requires-Dist: mypy; extra == "lint"
+Dynamic: license-file
+
+# statrl
+
+[![Tests](https://github.com/StatisticalRL/statrl/actions/workflows/tests.yml/badge.svg)](https://github.com/StatisticalRL/statrl/actions/workflows/tests.yml)
+[![Lint](https://github.com/StatisticalRL/statrl/actions/workflows/lint.yml/badge.svg)](https://github.com/StatisticalRL/statrl/actions/workflows/lint.yml)
+[![Documentation](https://github.com/StatisticalRL/statrl/actions/workflows/docs.yml/badge.svg)](https://github.com/StatisticalRL/statrl/actions/workflows/docs.yml)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+The Statistical Reinforcement Learning Toolkit is a research library organised as a
+taxonomy of *settings*, each with a matching environment, agent, and interaction loop.
+
+📖 **[Documentation](https://statisticalrl.github.io/statrl/)**
+
+## Install
+
+Requires Python 3.9+. Not yet on PyPI (install from source):
+
+```bash
+git clone https://github.com/StatisticalRL/statrl.git
+cd statrl
+pip install -e .          # editable install for development
+```
+
+## Quickstart
+
+```python
+from statrl.settings.bandits.stochastic.anytime.envs.parametric import BernoulliBandit
+from statrl.settings.bandits.stochastic.anytime.agents.IMED import IMED
+from statrl.settings.bandits.stochastic.anytime.agents._Oracle import Oracle
+from statrl.settings.bandits.stochastic.anytime.interaction import BanditInteraction
+from statrl.settings.utils import klBern
+
+env = BernoulliBandit([0.2, 0.9, 0.5])
+interaction = BanditInteraction()
+
+scores = interaction.run(env, IMED(env.number_arms, klBern), horizon=2000)
+oracle_scores = interaction.run(env, Oracle(env), horizon=2000)
+
+print(f"regret after 2000 rounds: {oracle_scores[-1] - scores[-1]:.1f}")
+```
+
+## The protocol
+
+Every setting shares the same protocol:
+
+| Component   | Responsibility                                                                       |
+| ----------- | ------------------------------------------------------------------------------------ |
+| Environment | Holds the reward distributions; `step(arm)` samples a reward.                          |
+| Agent       | `reset()` starts a run; `select_arm()` chooses an arm; `update(arm, reward)` learns.    |
+| Interaction | `run(env, learner, horizon)` runs the loop and returns cumulative expected scores.      |
+
+## Implemented settings
+
+Under `statrl.settings`:
+
+BANDITS:
+- **`stochastic.anytime`**
+- **`stochastic.knownhorizon`** : horizon-aware wrapper over the anytime setting.
+- **`stochastic.batch`** : when considering batch schedule.
+- **`stochastic.kernel`** : RKHS structure on arms.
+- **`adversarial.lipschitz`** : an adversarial Lipschitz forecaster.
+
+MARKOV DECISION PROCESSES:
+- **`discrete_nostructure`**: Abstract discrete MDPs.
+- **`gridworld`**: Gridworld MDPs.
+
+## Running experiments
+
+`statrl.experiments` benchmarks agents: many replicates in parallel, regret against an
+oracle, and plots.
+
+```python
+from statrl.experiments.massiveruns import runLargeMulticoreExperiment
+
+runLargeMulticoreExperiment(
+    env, agents, oracle, interact,
+    timeHorizon=1000, nbReplicates=100, root_folder="results/",
+)
+```
+
+Results (per-replicate dumps, a logfile, regret plots) are written under `root_folder`.
+See [`examples/`](examples/) for complete runnable scripts.
+
+## Development
+
+```bash
+pip install -e ".[test,lint]"
+pytest                                    # tests
+pytest --doctest-modules src/statrl \
+       --ignore-glob='*_test.py'          # docstring examples
+ruff check src tests                      # lint
+mypy                                      # type-check
+```
+
+## Documentation
+
+Full docs (quickstart, user guide, API reference) live under `docs/`:
+
+```bash
+pip install -r docs/requirements.txt
+sphinx-build -b html -W --keep-going docs/source docs/_build/html
+sphinx-build -b doctest docs/source docs/_build/doctest
+xdg-open docs/_build/html/index.html
+```

statrl-1.2609/README.md

@@ -0,0 +1,104 @@
+# statrl
+
+[![Tests](https://github.com/StatisticalRL/statrl/actions/workflows/tests.yml/badge.svg)](https://github.com/StatisticalRL/statrl/actions/workflows/tests.yml)
+[![Lint](https://github.com/StatisticalRL/statrl/actions/workflows/lint.yml/badge.svg)](https://github.com/StatisticalRL/statrl/actions/workflows/lint.yml)
+[![Documentation](https://github.com/StatisticalRL/statrl/actions/workflows/docs.yml/badge.svg)](https://github.com/StatisticalRL/statrl/actions/workflows/docs.yml)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+The Statistical Reinforcement Learning Toolkit is a research library organised as a
+taxonomy of *settings*, each with a matching environment, agent, and interaction loop.
+
+📖 **[Documentation](https://statisticalrl.github.io/statrl/)**
+
+## Install
+
+Requires Python 3.9+. Not yet on PyPI (install from source):
+
+```bash
+git clone https://github.com/StatisticalRL/statrl.git
+cd statrl
+pip install -e .          # editable install for development
+```
+
+## Quickstart
+
+```python
+from statrl.settings.bandits.stochastic.anytime.envs.parametric import BernoulliBandit
+from statrl.settings.bandits.stochastic.anytime.agents.IMED import IMED
+from statrl.settings.bandits.stochastic.anytime.agents._Oracle import Oracle
+from statrl.settings.bandits.stochastic.anytime.interaction import BanditInteraction
+from statrl.settings.utils import klBern
+
+env = BernoulliBandit([0.2, 0.9, 0.5])
+interaction = BanditInteraction()
+
+scores = interaction.run(env, IMED(env.number_arms, klBern), horizon=2000)
+oracle_scores = interaction.run(env, Oracle(env), horizon=2000)
+
+print(f"regret after 2000 rounds: {oracle_scores[-1] - scores[-1]:.1f}")
+```
+
+## The protocol
+
+Every setting shares the same protocol:
+
+| Component   | Responsibility                                                                       |
+| ----------- | ------------------------------------------------------------------------------------ |
+| Environment | Holds the reward distributions; `step(arm)` samples a reward.                          |
+| Agent       | `reset()` starts a run; `select_arm()` chooses an arm; `update(arm, reward)` learns.    |
+| Interaction | `run(env, learner, horizon)` runs the loop and returns cumulative expected scores.      |
+
+## Implemented settings
+
+Under `statrl.settings`:
+
+BANDITS:
+- **`stochastic.anytime`**
+- **`stochastic.knownhorizon`** : horizon-aware wrapper over the anytime setting.
+- **`stochastic.batch`** : when considering batch schedule.
+- **`stochastic.kernel`** : RKHS structure on arms.
+- **`adversarial.lipschitz`** : an adversarial Lipschitz forecaster.
+
+MARKOV DECISION PROCESSES:
+- **`discrete_nostructure`**: Abstract discrete MDPs.
+- **`gridworld`**: Gridworld MDPs.
+
+## Running experiments
+
+`statrl.experiments` benchmarks agents: many replicates in parallel, regret against an
+oracle, and plots.
+
+```python
+from statrl.experiments.massiveruns import runLargeMulticoreExperiment
+
+runLargeMulticoreExperiment(
+    env, agents, oracle, interact,
+    timeHorizon=1000, nbReplicates=100, root_folder="results/",
+)
+```
+
+Results (per-replicate dumps, a logfile, regret plots) are written under `root_folder`.
+See [`examples/`](examples/) for complete runnable scripts.
+
+## Development
+
+```bash
+pip install -e ".[test,lint]"
+pytest                                    # tests
+pytest --doctest-modules src/statrl \
+       --ignore-glob='*_test.py'          # docstring examples
+ruff check src tests                      # lint
+mypy                                      # type-check
+```
+
+## Documentation
+
+Full docs (quickstart, user guide, API reference) live under `docs/`:
+
+```bash
+pip install -r docs/requirements.txt
+sphinx-build -b html -W --keep-going docs/source docs/_build/html
+sphinx-build -b doctest docs/source docs/_build/doctest
+xdg-open docs/_build/html/index.html
+```

statrl-1.2609/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "statrl"
+version = "1.2609"
+description = "The Statistical Reinforcement Learning Toolkit Library"
+authors = [{ name = "Odalric-Ambrym Maillard", email = "odalricambrym.maillard@inria.fr" }]
+readme = "README.md"
+license = { text = "MIT" }
+classifiers = ["License :: OSI Approved :: MIT License"]
+requires-python = ">=3.9"
+dependencies = [
+    "gymnasium>=1.0",
+    "numpy>=2.5",
+    "joblib>=1.5",
+    "matplotlib>=3.9",
+    "scipy>=1.17",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+lint = ["ruff", "mypy"]
+
+[project.urls]
+Homepage = "https://github.com/StatisticalRL/statrl"
+Repository = "https://github.com/StatisticalRL/statrl"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.mypy]
+files = ["src"]
+# Newer numpy stubs use PEP 695 `type` aliases, which need python_version >=
+# 3.12 to parse, even though the package itself still targets
+# requires-python = ">=3.9".
+python_version = "3.12"
+# gymnasium/scipy/joblib lack stubs, so don't error on their missing imports.
+ignore_missing_imports = true
+
+[tool.ruff]
+# src layout, so ruff resolves `settings`/`experiments` as first-party.
+src = ["src"]
+# target-version is inferred from project.requires-python.
+#packages = [
+#    "statrl",
+#    "statrl.experiments",
+#    "statrl.settings",
+#    "statrl.settings.bandits",
+#    "statrl.settings.bandits.stochastic",
+#    "statrl.settings.bandits.stochastic.anytime",
+#    "statrl.settings.bandits.stochastic.anytime.agents",
+#    "statrl.settings.bandits.stochastic.knownhorizon",
+#    "statrl.settings.bandits.stochastic.knownhorizon.wrappers",
+#    "statrl.settings.bandits.adversarial",
+#    "statrl.settings.bandits.adversarial.lipschitz",
+#    "statrl.settings.bandits.adversarial.lipschitz.agents",
+#]
+
+[tool.ruff.lint]
+# Pinned explicitly: ruff's own default rule set has grown well past this
+# selection in recent releases, and this project only wants pyflakes (F) plus
+# the pycodestyle error subset (E4/E7/E9).
+select = ["E4", "E7", "E9", "F"]

statrl-1.2609/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

statrl-1.2609/src/statrl/experiments/analyzeruns.py

@@ -0,0 +1,95 @@
+
+import pickle
+import time
+import numpy as np
+
+def computeScoreDiffs(names: list[str], dump_scores: list[list[str]], timeHorizon: int, envName: str, root_folder: str) -> tuple[list[np.ndarray], list[np.ndarray], list[np.ndarray],list[np.ndarray],list[np.ndarray], list[np.ndarray], list[int]]:
+    """Turn per-replicate score dumps into regret statistics over time.
+
+    Loads every dump, subtracts each agent's cumulative score from the
+    oracle's averaged one to obtain regret, and summarizes the replicates by
+    their mean, median, and four quantiles.
+
+    Parameters
+    ----------
+    names : list of str
+        Agent names, in the same order as ``dump_scores``. Used to name the
+        per-agent regret pickles.
+    dump_scores : list of list of str
+        One list of dump filenames per agent. **The last entry must be the
+        oracle's**, and it is what every other entry is compared against — the
+        function has no other way to tell which agent is the reference.
+    timeHorizon : int
+        Number of rounds each run played.
+    envName : str
+        Environment name, used in the output filenames.
+    root_folder : str
+        Directory the regret pickles are written to.
+
+    Returns
+    -------
+    mean, median : list of ndarray
+        Per-agent mean and median regret at each sampled time.
+    quantile1, quantile2, quantile3, quantile4 : list of ndarray
+        Per-agent regret quantiles at levels 0.1, 0.25, 0.75, and 0.9. The
+        plots shade 0.1-0.9 and 0.25-0.75 as nested bands.
+    times : list of int
+        Sampled time steps, shared by every returned series.
+
+    Notes
+    -----
+    Long runs are downsampled to at most ~1000 points
+    (``skip = timeHorizon // 1000``), which bounds both plot size and memory.
+    Each returned series therefore has ``len(times)`` entries, not
+    ``timeHorizon``.
+
+    The oracle's score is averaged across its replicates *before* the
+    subtraction, so the result is regret against mean oracle performance
+    rather than a paired difference per replicate.
+    """
+
+    median = []
+    mean = []
+    quantile1 = []
+    quantile2 = []
+    quantile3 = []
+    quantile4 = []
+    nbAlgs = len(dump_scores) - 1
+
+    #Downsample the times, especially in case timeHorizon is huge.
+    skip = max(1, (timeHorizon // 1000))
+    times = [t for t in range(0,timeHorizon,skip)]
+
+    #file_oracle = open(dump_scores[-1], 'rb')
+    #scores_oracle = pickle.load(file_oracle)
+    # Comment the following line for BatchMabs:
+    #scores_oracle = scores_oracle[0]
+    #file_oracle.close()
+
+    data_o = []
+    for oracle_file in dump_scores[-1]:
+        with open(oracle_file, 'rb') as file:
+            scores_oi = pickle.load(file)
+        data_o.append([scores_oi[t] for t in times])
+    scores_oracle = np.mean(data_o, axis=0)
+
+    for j in range(nbAlgs):
+        data_j = []
+        for alg_file in dump_scores[j]:
+            with open(alg_file, 'rb') as file:
+                scores_ij = pickle.load(file)
+            data_j.append([scores_oracle[k] - scores_ij[t] for k, t in enumerate(times)])
+
+        filename = f"{root_folder}regret_{envName}_{names[j]}_{timeHorizon}_{j}_{time.time()}"
+        with open(filename, 'wb') as out_file:
+            pickle.dump(data_j, out_file)
+
+        mean.append(np.mean(data_j, axis=0))
+        median.append(np.quantile(data_j, 0.5, axis=0))
+        quantile1.append(np.quantile(data_j, 0.1, axis=0))
+        quantile2.append(np.quantile(data_j, 0.25, axis=0))
+        quantile3.append(np.quantile(data_j, 0.75, axis=0))
+        quantile4.append(np.quantile(data_j, 0.9, axis=0))
+
+    return mean,median,quantile1,quantile2, quantile3, quantile4,times
+

statrl-1.2609/src/statrl/experiments/massiveruns.py

@@ -0,0 +1,124 @@
+
+
+import statrl.experiments.onerun as oR
+import statrl.experiments.parallelruns as pR
+import statrl.experiments.analyzeruns as aR
+import statrl.experiments.plotruns as plR
+from statrl.experiments.utils import clear_auxiliaryfiles
+
+import time
+import os
+from typing import Any
+ROOT="results/"
+
+
+def runLargeMulticoreExperiment(env: Any, agents: list[Any], oracle: Any, interact: Any, timeHorizon: int=1000, nbReplicates: int=100, root_folder: str=ROOT) -> None:
+    """Benchmark several agents on one environment and plot their regret.
+
+    For each agent it runs ``nbReplicates`` independent interactions in parallel, runs the oracle for
+    the same number, computes regret as the oracle's cumulative score minus each agent's, and writes 
+    a logfile and regret figures under ``root_folder``. 
+
+    Parameters
+    ----------
+    env : object
+        Environment to benchmark on. Must expose ``name``; an optional
+        ``displayname`` is used as the figure title when present.
+    agents : list of object
+        Agents to compare. Their ``name`` attributes must be distinct — dump
+        filenames and plot legends are keyed on them, so duplicates silently
+        merge two agents' results.
+    oracle : object
+        Reference agent defining zero regret, and the only one required to
+        expose a ``policy`` (it is written to the logfile). Must belong to the
+        same setting as ``agents``.
+    interact : statrl.experiments.onerun.Interaction
+        Interaction loop of the setting, shared by every agent in the run.
+    timeHorizon : int, default=1000
+        Number of rounds per interaction.
+    nbReplicates : int, default=100
+        Number of independent runs per agent. Regret quantiles are taken
+        across these, so a handful of replicates gives a very rough band.
+    root_folder : str, default='results/'
+        Output directory, created if absent. Must end with a separator.
+
+    Returns
+    -------
+    None
+        Everything is written to disk. ``root_folder`` receives a
+        ``logfile_*.txt``, one ``regret_*`` pickle per agent, and the figures
+        ``Regrets_*.png`` / ``.pdf`` in linear and log-y scale. The
+        intermediate ``aux_*`` dumps are deleted on the way out.
+
+    See Also
+    --------
+    statrl.experiments.parallelruns.multicoreRuns : The parallel layer underneath.
+    statrl.experiments.analyzeruns.computeScoreDiffs : Turns the dumps into regret statistics.
+    statrl.experiments.plotruns.plotScoreDiffs : Draws the figures.
+
+    Notes
+    -----
+    Cost grows as ``(len(agents) + 1) * nbReplicates * timeHorizon``. Start
+    small — the defaults already amount to 100 000 rounds per agent.
+
+    Examples
+    --------
+    >>> from statrl.settings.bandits.stochastic.anytime.envs.parametric import BernoulliBandit
+    >>> from statrl.settings.bandits.stochastic.anytime.agents.IMED import IMED
+    >>> from statrl.settings.bandits.stochastic.anytime.agents._Oracle import Oracle
+    >>> from statrl.settings.bandits.stochastic.anytime.agents._Random import Random
+    >>> from statrl.settings.bandits.stochastic.anytime.interaction import BanditInteraction
+    >>> from statrl.settings.utils import klBern
+    >>> env = BernoulliBandit([0.2, 0.9, 0.5])              # doctest: +SKIP
+    >>> runLargeMulticoreExperiment(                        # doctest: +SKIP
+    ...     env,
+    ...     agents=[IMED(env.number_arms, klBern), Random(env)],
+    ...     oracle=Oracle(env),
+    ...     interact=BanditInteraction(),
+    ...     timeHorizon=1000, nbReplicates=50,
+    ... )
+    """
+    os.makedirs(root_folder, exist_ok=True)
+
+    envName = env.name
+    learners = agents
+
+    print("-"*30+"Massive Multicore Experiment"+"-"*30)
+    print(f'Environment: {envName}')
+    print(f'Learners: {[learner.name for learner in learners]}')
+    print(f'[INFO] Run {nbReplicates} many interactions of length {timeHorizon} for each learner:')
+    dump_scores = []
+    names = []
+    meanelapsedtimes = []
+
+    for learner in learners:
+        names.append(learner.name)
+        dump_scores_learner, meanelapsedtime_learner = pR.multicoreRuns(env, learner, interact, nbReplicates, timeHorizon, oR.oneRunWithDump, root_folder=root_folder)
+        dump_scores.append(dump_scores_learner)
+        meanelapsedtimes.append(meanelapsedtime_learner)
+
+    dump_scoresopt, meanelapsedtime = pR.multicoreRuns(env, oracle, interact, nbReplicates, timeHorizon,
+                                                    oR.oneRunWithDump, root_folder=root_folder)
+    dump_scores.append(dump_scoresopt)
+
+    ## Report statistics and compute regret:
+    timestamp = str(time.time())
+    logfilename = f"{root_folder}logfile_{envName}_{timestamp}.txt"
+    with open(logfilename, 'w') as logfile:
+        logfile.write("Environment " + envName + "\n")
+        logfile.write("Optimal policy is: " + str(oracle.policy) + "\n")
+        logfile.write("Learners " + str([learner.name for learner in learners]) + "\n")
+        logfile.write("Time horizon is " + str(timeHorizon) + ", nb of replicates is " + str(nbReplicates) + "\n")
+        for name, meanelapsedtime in zip(names, meanelapsedtimes):
+            logfile.write(f"{name} average runtime is {meanelapsedtime}\n")
+        print("[INFO] A log-file has been generated in ", logfilename)
+        print("[INFO]  Compute Statistics...")
+        mean, median, quantile1, quantile2,quantile3,quantile4, times = aR.computeScoreDiffs(names, dump_scores, timeHorizon, envName, root_folder=root_folder)
+        print("[INFO]  Plot results...")
+
+        title = env.displayname if hasattr(env, "displayname") else envName
+        labelx,labely = interact.plotlabels
+        plR.plotScoreDiffs(names, envName, (title,labelx,labely), mean, median, quantile1, quantile2,quantile3,quantile4, times, timeHorizon, logfile=logfile, timestamp=timestamp, root_folder=root_folder)
+        print("[INFO]  Clean Auxiliary files...")
+    clear_auxiliaryfiles(env, root_folder)
+    print("[INFO]  Massive multicore experiment successfully completed.")

statrl-1.2609/src/statrl/experiments/onerun.py

@@ -0,0 +1,111 @@
+
+from statrl.experiments.utils import dump
+
+import time
+
+from abc import ABC, abstractmethod
+from typing import Any
+import numpy as np
+
+class Interaction(ABC):
+    """Base class for the interaction loop of a setting. 
+    """
+
+    @abstractmethod
+    def run(self, env: Any, learner: Any, horizon: int)-> np.ndarray:
+        """Run one interaction and return its cumulative expected score.
+
+        Parameters
+        ----------
+        env : object
+            Environment of the setting. Reset by the implementation.
+        learner : object
+            Agent of the setting. Reset by the implementation, so one instance
+            can serve many replicates.
+        horizon : int
+            Number of rounds to play.
+
+        Returns
+        -------
+        ndarray of shape (horizon,)
+            Cumulative *expected* reward. Implementations must return exactly
+            ``horizon`` entries — :func:`oneRunWithDump` asserts it.
+        """
+        return np.array([])
+
+
+    @abstractmethod
+    def renderrun(self, env: Any, learner: Any, horizon: int) -> None:
+        """Run one interaction with rendering enabled, returning no score.
+
+        Parameters
+        ----------
+        env : object
+            Environment of the setting; the implementation attaches renderers.
+        learner : object
+            Agent of the setting.
+        horizon : int
+            Number of rounds to play.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def plotlabels(self) -> tuple[str, str]:
+        """tuple of (str, str): Axis labels ``(x, y)`` for the regret plots.
+
+        Read by
+        :func:`~statrl.experiments.massiveruns.runLargeMulticoreExperiment`
+        and forwarded to
+        :func:`~statrl.experiments.plotruns.plotScoreDiffs`. Settings whose
+        rounds are not time steps override it — the batch setting labels its
+        x-axis by episode.
+        """
+        raise NotImplementedError
+
+
+
+
+def oneRunWithDump(env: Any, learner: Any, interact: Any, timeHorizon: int, root_folder: str) -> str:
+    """Run one replicate and pickle its score series to disk.
+
+    The unit of work handed to :mod:`joblib` by
+    :func:`~statrl.experiments.parallelruns.multicoreRuns`. Results travel
+    back through the filesystem rather than through the return value, because
+    returning full score series from every worker would serialize
+    ``nbReplicates x timeHorizon`` floats through the process pool.
+
+    Parameters
+    ----------
+    env : object
+        Environment for this replicate; already a private deep copy.
+    learner : object
+        Agent for this replicate; already a private deep copy.
+    interact : Interaction
+        The interaction loop of the setting.
+    timeHorizon : int
+        Number of rounds to play.
+    root_folder : str
+        Directory the dump is written to. Must end with a separator, and must
+        already exist.
+
+    Returns
+    -------
+    str
+        Path of the pickle written, of the form
+        ``{root_folder}aux_{env}_scores_{agent}_{horizon}_{timestamp}``. The
+        ``aux_`` prefix is what
+        :func:`~statrl.experiments.utils.clear_auxiliaryfiles` deletes once
+        the statistics have been computed.
+
+    Raises
+    ------
+    AssertionError
+        If the interaction returned fewer or more than ``timeHorizon`` scores.
+    """
+    scoretimeseries=interact.run(env,learner,timeHorizon)
+    assert len(scoretimeseries) == timeHorizon
+
+    tag = f"{env.name}_scores_{learner.name}_{timeHorizon}_{time.time()}"
+    filename = dump(scoretimeseries,"aux",tag,root_folder)
+    return filename