Merge branch 'main' into customized

docs/autobuild.sh

@@ -8,7 +8,7 @@ REPO="$( realpath "$DOCS/../" )"
 cd "$REPO/docs"
 
 # Build html documentation.
-make html
+make html || exit 1
 
 # Open documentation in browser.
 xdg-open "$DOCS/_build/html/index.html"

docs/downward.experiment.rst

@@ -1,14 +1,36 @@
+.. _downward-experiment:
+
 :mod:`downward.experiment` --- Fast Downward experiment
 =======================================================
+
+.. note::
+
+   The :class:`FastDownwardExperiment
+   <downward.experiment.FastDownwardExperiment>` class makes it easy to write
+   "standard" experiments with little boilerplate code, but it assumes a rigid
+   experiment structure: it only allows you to run each added algorithm on each
+   added task, and individual runs cannot easily be customized. An example for
+   this is the `2020-09-11-A-cg-vs-ff.py
+   <https://github.com/aibasel/lab/tree/main/examples/downward/2020-09-11-A-cg-vs-ff.py>`_
+   experiment. If you need more flexibility, you can use the
+   :class:`lab.experiment.Experiment` class instead and fill it by using
+   :class:`FastDownwardAlgorithm <downward.experiment.FastDownwardAlgorithm>`,
+   :class:`FastDownwardRun <downward.experiment.FastDownwardRun>`,
+   :class:`CachedFastDownwardRevision
+   <downward.cached_revision.CachedFastDownwardRevision>`, and :class:`Task
+   <downward.suites.Task>` objects. The `2020-09-11-B-bounded-cost.py
+   <https://github.com/aibasel/lab/tree/main/examples/downward/2020-09-11-B-bounded-cost.py>`_
+   script shows an example. All of these classes are documented below.
+
 .. autoclass:: downward.experiment.FastDownwardExperiment
    :members: add_algorithm, add_suite
 
 .. _downward-parsers:
 
-Built-in parsers
-----------------
+Bundled parsers
+---------------
 
-The following constants are paths to built-in parsers that can be passed
+The following constants are paths to default parsers that can be passed
 to :meth:`exp.add_parser() <lab.experiment.Experiment.add_parser>`. The
 "Used attributes" and "Parsed attributes" lists describe the
 dependencies between the parsers.
@@ -27,3 +49,26 @@ dependencies between the parsers.
 
 .. autoattribute:: downward.experiment.FastDownwardExperiment.PLANNER_PARSER
    :annotation:
+
+.. autoclass:: downward.experiment.FastDownwardAlgorithm
+   :members:
+   :undoc-members:
+   :inherited-members:
+
+.. autoclass:: downward.experiment.FastDownwardRun
+   :members:
+   :undoc-members:
+
+.. autoclass:: downward.cached_revision.CachedFastDownwardRevision
+   :members:
+   :undoc-members:
+   :inherited-members:
+
+:mod:`downward.suites` --- Select benchmarks
+--------------------------------------------
+
+.. autoclass:: downward.suites.Task
+   :members:
+   :undoc-members:
+
+.. autofunction:: downward.suites.build_suite

docs/downward.tutorial.rst

@@ -121,13 +121,12 @@ directories containing a ``.venv`` subdirectory.
 Run tutorial experiment
 -----------------------
 
-The files below are an experiment script for the example experiment, a
-``project.py`` module that bundles common functionality for all
-experiments related to the project, a parser script, and a script for
-collecting results and making reports. You can use the files as a basis
-for your own experiments. They are available in the `Lab repo
-<https://github.com/aibasel/lab/tree/master/examples/downward>`_. Copy the
-files into ``experiments/cg-vs-ff``.
+The files below are two experiment scripts, a ``project.py`` module that bundles
+common functionality for all experiments related to the project, a parser
+script, and a script for collecting results and making reports. You can use the
+files as a basis for your own experiments. They are available in the `Lab repo
+<https://github.com/aibasel/lab/tree/main/examples/downward>`_. Copy the files
+into ``experiments/my-exp-dir``.
 
 .. highlight:: bash
 
@@ -147,11 +146,28 @@ Run individual steps with ::
     ./2020-09-11-A-cg-vs-ff.py 2
     ./2020-09-11-A-cg-vs-ff.py 3 6 7
 
+The ``2020-09-11-A-cg-vs-ff.py`` script uses the
+:class:`downward.experiment.FastDownwardExperiment` class, which reduces the
+amount of code you need to write, but assumes a rigid structure of the
+experiment: it only allows you to run each added algorithm on each added task,
+and individual runs cannot be customized. If you need more flexibility, you can
+employ the :class:`lab.experiment.Experiment` class instead and fill it by using
+:class:`FastDownwardAlgorithm <downward.experiment.FastDownwardAlgorithm>`,
+:class:`FastDownwardRun <downward.experiment.FastDownwardRun>`,
+:class:`CachedFastDownwardRevision
+<downward.cached_revision.CachedFastDownwardRevision>`, and :class:`Task
+<downward.suites.Task>` objects. The ``2020-09-11-A-cg-vs-ff.py`` script shows
+an example. See the `Downward Lab API <downward.experiment.html>`_ for a
+reference on all Downward Lab classes.
+
 .. highlight:: python
 
 .. literalinclude:: ../examples/downward/2020-09-11-A-cg-vs-ff.py
    :caption:
 
+.. literalinclude:: ../examples/downward/2020-09-11-B-bounded-cost.py
+   :caption:
+
 .. literalinclude:: ../examples/downward/project.py
    :caption:
 
@@ -163,5 +179,5 @@ Run individual steps with ::
 
 The `Downward Lab API <downward.experiment.html>`_ shows you how to adjust
 this example to your needs. You may also find the `other example
-experiments <https://github.com/aibasel/lab/tree/master/examples/>`_
+experiments <https://github.com/aibasel/lab/tree/main/examples/>`_
 useful.

docs/faq.rst

@@ -64,7 +64,7 @@ How can I make reports and plots for results obtained without Lab?
 ------------------------------------------------------------------
 
 See `report-external-results.py
-<https://github.com/aibasel/lab/blob/master/examples/report-external-results.py>`_
+<https://github.com/aibasel/lab/blob/main/examples/report-external-results.py>`_
 for an example.
 
 
@@ -82,7 +82,7 @@ How can I contribute to Lab?
 
 If you'd like to contribute a feature or a bugfix to Lab or Downward Lab,
 please see `CONTRIBUTING.md
-<https://github.com/aibasel/lab/blob/master/CONTRIBUTING.md>`_.
+<https://github.com/aibasel/lab/blob/main/CONTRIBUTING.md>`_.
 
 
 How can I customize Lab?

docs/lab.experiment.rst

@@ -57,6 +57,15 @@ Custom command line arguments
    :exclude-members: build
 
 
+:class:`CachedRevision`
+-----------------------
+
+.. autoclass:: lab.cached_revision.CachedRevision
+   :members:
+   :undoc-members:
+   :inherited-members:
+
+
 .. _parsing:
 
 :class:`Parser`
@@ -73,6 +82,11 @@ Custom command line arguments
 --------------------
 
 .. autoclass:: lab.environments.Environment
+
+Lab supports several built-in environments below. Additionally, support for
+`HTCondor <https://htcondor.org/>`_ clusters is provided by a `third-party
+repository <https://github.com/Martin1887/lab-htcondor-environment>`_.
+
 .. autoclass:: lab.environments.LocalEnvironment
 .. autoclass:: lab.environments.SlurmEnvironment
 .. autoclass:: lab.environments.BaselSlurmEnvironment

docs/news.rst

@@ -1,6 +1,37 @@
 Changelog
 =========
 
+next (unreleased)
+-----------------
+
+Lab
+^^^
+* Provide support for HTCondor clusters in external repo and add link to docs (Martín Pozo).
+
+
+Downward Lab
+^^^^^^^^^^^^
+* no changes so far
+
+
+v7.4 (2023-08-18)
+-----------------
+
+Lab
+^^^
+* Require *revision_cache* parameter in :class:`CachedRevision <lab.cached_revision.CachedRevision>` constructor (Jendrik Seipp).
+* Add *subdir* option for :class:`CachedRevision <lab.cached_revision.CachedRevision>` to support solvers at deeper levels of a repo (Jendrik Seipp).
+* Add :meth:`CachedRevision.get_relative_exp_path() <lab.cached_revision.CachedRevision.get_relative_exp_path>` method to query where cache artefacts will land in the experiment directory (Jendrik Seipp).
+* Document :class:`CachedRevision <lab.cached_revision.CachedRevision>` class and stabilize its API (Jendrik Seipp).
+* Only use documented classes and functions in example experiments (Jendrik Seipp).
+
+Downward Lab
+^^^^^^^^^^^^
+* Add *subdir* option for :class:`CachedFastDownwardRevision <downward.cached_revision.CachedFastDownwardRevision>` to support Fast Downward checkouts at deeper levels of a repo (Jendrik Seipp).
+* Make :class:`FastDownwardAlgorithm <downward.experiment.FastDownwardAlgorithm>`, :class:`FastDownwardRun <downward.experiment.FastDownwardRun>` and :class:`CachedFastDownwardRevision <downward.cached_revision.CachedFastDownwardRevision>` classes part of the documented, stable API (Jendrik Seipp).
+* Describe :ref:`two main alternatives <downward-experiment>` for running Fast Downward experiments (Jendrik Seipp).
+
+
 v7.3 (2023-03-03)
 -----------------
 
@@ -624,9 +655,9 @@ Downward Lab
   (``build_successful``) is written in the cache directory. When
   the cached revision is requested later an error is shown if this
   file is missing.
-* Only use exit codes to reason about error reasons. Merge from FD master if your FD version does not produce meaningful exit codes.
+* Only use exit codes to reason about error reasons. Merge from FD main if your FD version does not produce meaningful exit codes.
 * Preprocess parser: only parse logs and never output files.
-* Never copy ``all.groups`` and ``test.groups`` files. Old Fast Downward branches need to merge from master.
+* Never copy ``all.groups`` and ``test.groups`` files. Old Fast Downward branches need to merge from main.
 * Always compress ``output.sas`` (also for ``compact=False``). Use ``xz`` for compressing.
 
 

downward/cached_revision.py

@@ -1,5 +1,3 @@
-import glob
-import os.path
 import subprocess
 
 from lab import tools
@@ -9,38 +7,48 @@
 class CachedFastDownwardRevision(CachedRevision):
     """This class represents Fast Downward checkouts.
 
-    It provides methods for caching and compiling given revisions.
+    It provides methods for caching compiled revisions, so they can be reused
+    quickly in different experiments.
+
     """
 
-    def __init__(self, repo, rev, build_options):
+    def __init__(self, revision_cache, repo, rev, build_options, subdir=""):
         """
+        * *revision_cache*: Path to revision cache.
         * *repo*: Path to Fast Downward repository.
         * *rev*: Fast Downward revision.
         * *build_options*: List of build.py options.
+        * *subdir*: relative path from *repo* to Fast Downward subdir.
         """
         CachedRevision.__init__(
-            self, repo, rev, ["./build.py"] + build_options, ["experiments", "misc"]
+            self,
+            revision_cache,
+            repo,
+            rev,
+            ["./build.py"] + build_options,
+            exclude=["experiments", "misc"],
+            subdir=subdir,
         )
+        # Store for easy retrieval by class users.
         self.build_options = build_options
 
     def _cleanup(self):
         # Only keep the bin directories in "builds" dir.
-        for path in glob.glob(os.path.join(self.path, "builds", "*", "*")):
-            if os.path.basename(path) != "bin":
+        for path in self.path.glob("builds/*/*"):
+            if path.name != "bin":
                 tools.remove_path(path)
 
         # Remove unneeded files.
-        tools.remove_path(os.path.join(self.path, "build.py"))
+        tools.remove_path(self.path / "build.py")
 
         # Strip binaries.
         binaries = []
-        for path in glob.glob(os.path.join(self.path, "builds", "*", "bin", "*")):
-            if os.path.basename(path) in ["downward", "preprocess"]:
+        for path in self.path.glob("builds/*/bin/*"):
+            if path.name in ["downward", "preprocess"]:
                 binaries.append(path)
-        subprocess.call(["strip"] + binaries)
+        subprocess.check_call(["strip"] + binaries)
 
         # Compress src directory.
-        subprocess.call(
-            ["tar", "-cf", "src.tar", "--remove-files", "src"], cwd=self.path
+        subprocess.check_call(
+            ["tar", "--remove-files", "--xz", "-cf", "src.tar.xz", "src"], cwd=self.path
         )
-        subprocess.call(["xz", "src.tar"], cwd=self.path)