statrl 1.2609__py3-none-any.whl

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/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/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

statrl/experiments/parallelruns.py

@@ -0,0 +1,60 @@
+import time
+import copy
+from joblib import Parallel, delayed
+from typing import Any, Callable
+
+
+## Parallelization
+def multicoreRuns(env: Any, learner: Any, interact: Any, nbReplicates: int, timeHorizon: int, oneRunFunction: Callable[..., Any], root_folder: str) -> tuple[Any, float]:
+    """Run one agent for many independent replicates, spread across CPU cores.
+
+    Each replicate gets its own deep copy of the environment, agent, and
+    interaction.
+
+    Parameters
+    ----------
+    env : object
+        Environment to replicate.
+    learner : object
+        Agent to replicate.
+    interact : statrl.experiments.onerun.Interaction
+        Interaction loop of the setting.
+    nbReplicates : int
+        Number of independent runs.
+    timeHorizon : int
+        Number of rounds per run.
+    oneRunFunction : callable
+        Function executing one replicate, called as
+        ``oneRunFunction(env, learner, interact, timeHorizon, root_folder)``.
+        In practice :func:`~statrl.experiments.onerun.oneRunWithDump`.
+    root_folder : str
+        Directory the per-replicate dumps are written to.
+
+    Returns
+    -------
+    scores : list of str
+        One dump filename per replicate, in the order the jobs were created.
+    elapsed : float
+        Mean wall-clock seconds per replicate. Since the runs are concurrent
+        this is total elapsed time divided by ``nbReplicates``, so it measures
+        throughput rather than the cost of a single run.
+
+    Notes
+    -----
+    Uses all available cores (``n_jobs=-1``). Everything passed in must be
+    picklable, which is why
+    :class:`~statrl.settings.bandits.stochastic.batch.environment.BatchMAB` accepts a
+    plain list of batch sizes rather than only a callable.
+    """
+    #FIXME  Should be made more general? indep of gymnasium?
+        #envs.append(gymnasium.make(envRegisterName).unwrapped)
+    jobs = [
+        (copy.deepcopy(env), copy.deepcopy(learner), copy.deepcopy(interact), timeHorizon, root_folder)
+        for _ in range(nbReplicates)
+    ]
+
+    t0 = time.time()
+    scores = Parallel(n_jobs=-1)(delayed(oneRunFunction)(*job) for job in jobs)
+    elapsed = time.time() - t0
+
+    return scores, elapsed / nbReplicates

statrl/experiments/plotruns.py

@@ -0,0 +1,144 @@
+
+import pylab as pl
+import sys
+from typing import Any
+import numpy as np
+
+ROOT= "results/"
+def plotScoreDiffs(learnersName: list[str], envName: str, title, mean: list[np.ndarray], median: list[np.ndarray], quantile1: list[np.ndarray], quantile2: list[np.ndarray],quantile3: list[np.ndarray],quantile4: list[np.ndarray], times: list[int], timeHorizon: int, logfile: Any='', timestamp: Any=0, root_folder: str=ROOT) -> None:
+    """Draw the regret figures and record final regrets in the logfile.
+
+    Each agent gets a mean curve with markers, a dashed median, and two nested
+    shaded bands (0.1-0.9 and 0.25-0.75).  
+
+    Parameters
+    ----------
+    learnersName : list of str
+        Agent names, used as legend labels and in the output filename.
+    envName : str
+        Environment name, used in the output filename.
+    title : tuple of (str, str, str)
+        ``(figure_title, xlabel, ylabel)``. The two labels come from
+        :attr:`~statrl.experiments.onerun.Interaction.plotlabels`.
+    mean, median : list of ndarray
+        Per-agent mean and median regret over time.
+    quantile1, quantile2, quantile3, quantile4 : list of ndarray
+        Per-agent regret quantiles at levels 0.1, 0.25, 0.75, and 0.9.
+    times : list of int
+        Sampled time steps, shared by every series.
+    timeHorizon : int
+        Horizon of the runs, used for the x-limit and in the filename.
+    logfile : file-like, default=''
+        Where final regrets are written. The default empty string selects
+        :data:`sys.stdout`.
+    timestamp : str, default=0
+        Suffix making the filename unique across runs.
+    root_folder : str, default='results/'
+        Output directory. Must end with a separator.
+
+    Returns
+    -------
+    None
+        Writes ``Regrets_<agents>_<horizon>_<env>_<timestamp>`` as ``.png``
+        and ``.pdf``, plus an ``_ylog`` pair with a logarithmic ``y`` axis.
+
+    Notes
+    -----
+    Colours and markers cycle after 9 and 5 agents respectively, so beyond
+    that two agents become hard to tell apart.
+    """
+    if (logfile==''):
+        logfile=sys.stdout
+    nbFigure = pl.gcf().number+1
+    pl.figure(nbFigure)
+    fig, ax = pl.subplots(layout="constrained")
+    textfile = root_folder+"Regrets_"
+    #colors= ['black', 'blue','gray', 'green', 'red']#['black', 'purple', 'blue','cyan','yellow', 'orange', 'red', 'chocolate']
+    colors = ['#377eb8', '#ff7f00', '#4daf4a',
+     '#f781bf', '#a65628', '#984ea3',
+     '#999999', '#e41a1c', '#dede00']
+
+    style = ['o','v','s','d','<']
+    m,M=0,0
+
+    fig_title,fig_xlabel,fig_ylabel=title
+
+    ax.set_title(fig_title)
+
+
+    for i in range(len(median)):
+        m=min(m,min(quantile1[i]),min(mean[i]))
+        M=1.1*max(M,max(quantile4[i]),max(mean[i]))
+        ax.fill_between(
+            times,
+            quantile1[i],
+            quantile4[i],
+            color=colors[i% len(colors)],
+            alpha=0.18,
+            linewidth=0
+        )
+        ax.fill_between(
+            times,
+            quantile2[i],
+            quantile3[i],
+            color=colors[i % len(colors)],
+            alpha=0.18,
+            linewidth=0
+        )
+        ax.plot(
+            times,
+            median[i],
+            color=colors[i% len(colors)],
+            alpha=0.6,
+            linewidth=1.8,
+            linestyle='--'
+        )
+        ax.plot(
+            times,
+            mean[i],
+            style[i % len(style)],
+            markevery=0.15,
+            markersize=8,
+            color=colors[i% len(colors)],
+            linewidth=2.3,
+            linestyle='-',
+            label=learnersName[i]
+        )
+
+        #pl.plot(times, mean[i], style[i% len(style)], label=learnersName[i], color=colors[i % len(colors)], linewidth=2.0, linestyle='-.', markevery=0.05)
+        #pl.plot(times, median[i], style[i% len(style)], color=colors[i % len(colors)], linewidth=2.0, linestyle='--', markevery=0.05)
+        #pl.plot(times,quantile1[i], color=colors[i % len(colors)],linestyle=':',linewidth=0.6)
+        #pl.plot(times,quantile2[i], color=colors[i % len(colors)],linestyle=':',linewidth=0.6)
+
+        textfile += learnersName[i] + "_"
+        logfile.write(learnersName[i] + ' has regret ' + str(median[i][-1]) + ' after ' + str(timeHorizon) + ' time steps with quantiles ' +
+              str(quantile1[i][-1]) +' and '+ str(quantile2[i][-1])+"\n")
+
+    textfile+="_"+str(timeHorizon)+"_"+envName+"_"+timestamp
+    #fig.tight_layout()
+    ax.legend(loc=2)
+
+    ax.set_xlabel(fig_xlabel, fontsize=13, fontname = "Arial")
+    ax.set_ylabel(fig_ylabel, fontsize=13, fontname = "Arial")
+
+    ax.set_xlim(0,min(timeHorizon,len(mean[0]))-1)
+    #pl.xticks(times)
+    ax.ticklabel_format(axis='both', useMathText = True, useOffset = True, style='sci', scilimits=(0, 0))
+    ax.set_ylim([m,M])
+    fig.savefig(textfile+'.png')
+    fig.savefig(textfile+ '.pdf')
+    # pl.xscale('log')
+    # pl.savefig(textfile + '_xlog.png')
+    # pl.savefig(textfile + '_xlog.pdf')
+    # pl.ylim(1)
+    #if(timeHorizon>10):
+    ax.set_xscale('linear')
+    ax.set_yscale('log')
+    ax.set_ylim([max(m,1e-0),max(M,2e-0)])
+    fig.savefig(textfile + '_ylog.png')
+    fig.savefig(textfile + '_ylog.pdf')
+    fig.savefig(root_folder+"Regrets" + str(timeHorizon)+"_"+envName+'.pdf')
+    # pl.xscale('log')
+    # pl.savefig(textfile + '_loglog.png')
+    # pl.savefig(textfile + '_loglog.pdf')
+    logfile.write("\nPlots are depicted in files "+textfile + ".pdf/png, etc.")

statrl/experiments/utils.py

@@ -0,0 +1,140 @@
+import importlib.util
+import os
+import pickle
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def dump(values: Any, filename: str, tag: str, root_folder: str) -> str:
+    """Pickle a value to ``{root_folder}{filename}_{tag}``.
+
+    Parameters
+    ----------
+    values : object
+        Anything picklable; in practice a score time series.
+    filename : str
+        Filename prefix. ``"aux"`` marks a file
+        :func:`clear_auxiliaryfiles` may later delete.
+    tag : str
+        Suffix identifying the run, built from the environment, agent,
+        horizon, and a timestamp.
+    root_folder : str
+        Output directory. Must end with a separator and already exist.
+
+    Returns
+    -------
+    str
+        Path of the file written.
+    """
+    filenameM = f"{root_folder}{filename}_{tag}"
+    with open(filenameM, 'wb') as file:
+        pickle.dump(values, file)
+    return filenameM
+
+def clear_auxiliaryfiles(env: Any, root_folder: str) -> None:
+    """Delete the intermediate per-replicate dumps of one environment.
+
+    Removes every file in ``root_folder`` whose name starts with
+    ``aux_{env.name}``, i.e. the per-replicate score series, once the regret
+    statistics have been computed from them. The regret pickles, logfile, and
+    figures are kept.
+
+    Parameters
+    ----------
+    env : object
+        Environment whose dumps to remove, identified by its ``name``.
+    root_folder : str
+        Directory to clean. Must end with a separator.
+
+    Warnings
+    --------
+    Deletes files unconditionally. Anything of yours in ``root_folder`` named
+    ``aux_{env.name}*`` will be removed too.
+    """
+    for file in os.listdir(root_folder):
+        if file.startswith("aux_" + env.name):
+            os.remove(root_folder + file)
+
+#def load(filename):
+#    with open(filename, 'r') as file:
+#        return yaml.safe_load(file)
+def load(filename: str) -> dict:
+    """Read an ``environments.yaml`` registry.
+
+    Each entry maps an environment name to a spec with an ``entrypoint`` and
+    optional ``kwargs``. The spec's directory is recorded under ``_base_dir``
+    so :func:`make` can resolve the entrypoint relative to the YAML file
+    rather than the working directory.
+
+    Parameters
+    ----------
+    filename : str or path-like
+        Path to the YAML registry.
+
+    Returns
+    -------
+    dict
+        The parsed registry, each spec augmented with ``_base_dir``.
+
+    See Also
+    --------
+    make : Instantiates one of the returned specs.
+    """
+    path = Path(filename)
+
+    with path.open("r") as f:
+        envs = yaml.safe_load(f)
+
+    for spec in envs.values():
+        spec["_base_dir"] = path.parent
+
+    return envs
+
+def make(spec: dict) -> Any:
+    """Instantiate an environment from a registry spec.
+
+    Imports the module named by the spec's ``entrypoint`` from the file it
+    sits next to and calls the class it names with the spec's ``kwargs``.
+    Loading by file path rather than by import name is what lets a setting's
+    ``envs/`` directory be a plain folder, with no package or installation.
+
+    Parameters
+    ----------
+    spec : dict
+        A registry entry as returned by :func:`load`, with keys
+        ``entrypoint`` (``"module:Class"``), ``_base_dir``, and optionally
+        ``kwargs`` and ``displayname``.
+
+    Returns
+    -------
+    object
+        The constructed environment, carrying a ``displayname`` attribute —
+        the spec's if given, otherwise its ``name``. That value becomes the
+        title of the regret figures.
+
+    Raises
+    ------
+    ImportError
+        If the module named by the entrypoint cannot be loaded.
+
+    See Also
+    --------
+    load : Reads the registry this spec comes from.
+    """
+    module_name, class_name = spec["entrypoint"].split(":")
+    kwargs = spec.get("kwargs", {})
+
+    module_path = Path(spec["_base_dir"]) / f"{module_name}.py"
+
+    spec_module = importlib.util.spec_from_file_location(module_name, module_path)
+    if spec_module is None or spec_module.loader is None:
+        raise ImportError(f"cannot load module {module_name} from {module_path}")
+    module = importlib.util.module_from_spec(spec_module)
+    spec_module.loader.exec_module(module)
+
+    cls = getattr(module, class_name)
+    env = cls(**kwargs)
+    env.displayname = spec["displayname"] if "displayname" in spec else env.name
+    return env