experimaestro 1.3.5__tar.gz → 1.4.0__tar.gz

{experimaestro-1.3.5 → experimaestro-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: experimaestro
-Version: 1.3.5
+Version: 1.4.0
 Summary: "Experimaestro is a computer science experiment manager"
 Home-page: https://github.com/experimaestro/experimaestro-python
 License: GPL-3

{experimaestro-1.3.5 → experimaestro-1.4.0}/pyproject.toml

@@ -19,7 +19,7 @@ include = [
     "src/experimaestro/sphinx/static/experimaestro.css",
     "src/experimaestro/mkdocs/style.css"
 ]
-version = "1.3.5"
+version = "1.4.0"
 repository = "https://github.com/experimaestro/experimaestro-python"
 documentation = "https://experimaestro-python.readthedocs.io/"
 
@@ -124,7 +124,7 @@ warn_unused_ignores = true
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "1.3.5"
+version = "1.4.0"
 changelog_start_rev = "0.15.0"
 tag_format = "v$version"
 update_changelog_on_bump = true

{experimaestro-1.3.5 → experimaestro-1.4.0}/src/experimaestro/__main__.py

@@ -13,6 +13,7 @@ import subprocess
 from termcolor import colored, cprint
 
 import experimaestro
+from experimaestro.experiments.cli import experiments_cli
 import experimaestro.launcherfinder.registry as launcher_registry
 
 # --- Command line main options
@@ -74,6 +75,10 @@ def cli(ctx, quiet, debug, traceback):
     ctx.obj.traceback = traceback
 
 
+# Adds the run-experiment command
+cli.add_command(experiments_cli, "run-experiment")
+
+
 @cli.command(help="Get version")
 def version():
     print(experimaestro.__version__)

{experimaestro-1.3.5 → experimaestro-1.4.0}/src/experimaestro/core/context.py

@@ -36,13 +36,18 @@ class SerializedPath:
 
 
 class SerializationContext:
+    """Context when serializing experimaestro configurations"""
+
     save_directory: Optional[Path]
     var_path: List[str]
     serialized: Set[int]
 
-    """Context when serializing experimaestro configurations"""
-
     def __init__(self, *, save_directory: Optional[Path] = None):
+        """Creates a new serialization context
+
+        :param save_directory: Defines the directory where `SerializedPath` are
+            stored
+        """
         self.save_directory = save_directory
         self.var_path = []
         self.serialized = set()

experimaestro-1.4.0/src/experimaestro/experiments/__init__.py

@@ -0,0 +1,2 @@
+from .cli import experiments_cli, ExperimentHelper, ExperimentCallable  # noqa: F401
+from .configuration import configuration, ConfigurationBase  # noqa: F401

experimaestro-1.4.0/src/experimaestro/experiments/cli.py

@@ -0,0 +1,220 @@
+import inspect
+import json
+import logging
+import sys
+from pathlib import Path
+from typing import Any, List, Optional, Protocol, Tuple, Dict
+
+import click
+import omegaconf
+import yaml
+from experimaestro import LauncherRegistry, RunMode, experiment
+from experimaestro.experiments.configuration import ConfigurationBase
+from experimaestro.settings import get_workspace
+from omegaconf import OmegaConf, SCMode
+from termcolor import cprint
+
+
+class ExperimentHelper:
+    """Helper for experiments"""
+
+    # The experiment
+    xp: experiment
+
+    #: Run function
+    callable: "ExperimentCallable"
+
+    def __init__(self, callable: "ExperimentCallable"):
+        self.callable = callable
+
+    """Handles extra arguments"""
+
+    def run(self, args: List[str], configuration: ConfigurationBase):
+        assert len(args) == 0
+        self.callable(self, configuration)
+
+
+class ExperimentCallable(Protocol):
+    """Protocol for the run function"""
+
+    def __call__(self, helper: ExperimentHelper, configuration: Any):
+        ...
+
+
+def load(yaml_file: Path):
+    """Loads a YAML file, and parents one if they exist"""
+    if not yaml_file.exists() and yaml_file.suffix != ".yaml":
+        yaml_file = yaml_file.with_suffix(".yaml")
+
+    with yaml_file.open("rt") as fp:
+        _data = yaml.full_load(fp)
+    data = [_data]
+    if parent := _data.get("parent", None):
+        data.extend(load(yaml_file.parent / parent))
+
+    return data
+
+
+@click.option("--debug", is_flag=True, help="Print debug information")
+@click.option("--show", is_flag=True, help="Print configuration and exits")
+@click.option(
+    "--env",
+    help="Define one environment variable",
+    type=(str, str),
+    multiple=True,
+)
+@click.option(
+    "--host",
+    type=str,
+    default=None,
+    help="Server hostname (default to localhost,"
+    " not suitable if your jobs are remote)",
+)
+@click.option(
+    "--run-mode",
+    type=click.Choice(RunMode),
+    default=RunMode.NORMAL,
+    help="Sets the run mode",
+)
+@click.option(
+    "--xpm-config-dir",
+    type=Path,
+    default=None,
+    help="Path for the experimaestro config directory "
+    "(if not specified, use $HOME/.config/experimaestro)",
+)
+@click.option(
+    "--port",
+    type=int,
+    default=None,
+    help="Port for monitoring (can be defined in the settings.yaml file)",
+)
+@click.option(
+    "--file", "xp_file", help="The file containing the main experimental code"
+)
+@click.option(
+    "--workdir",
+    type=str,
+    default=None,
+    help="Working directory - if None, uses the default XPM " "working directory",
+)
+@click.option("--conf", "-c", "extra_conf", type=str, multiple=True)
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+@click.argument("yaml_file", metavar="YAML file", type=str)
+@click.command()
+def experiments_cli(
+    yaml_file: str,
+    xp_file: str,
+    host: str,
+    port: int,
+    xpm_config_dir: Path,
+    workdir: Optional[Path],
+    env: List[Tuple[str, str]],
+    run_mode: RunMode,
+    extra_conf: List[str],
+    args: List[str],
+    show: bool,
+    debug: bool,
+):
+    """Run an experiment"""
+    # --- Set the logger
+    logging.getLogger().setLevel(logging.DEBUG if debug else logging.INFO)
+    logging.getLogger("xpm.hash").setLevel(logging.INFO)
+
+    # --- Loads the YAML
+    yamls = load(Path(yaml_file))
+
+    # --- Get the XP file
+    if xp_file is None:
+        for data in yamls:
+            if xp_file := data.get("file"):
+                del data["file"]
+                break
+
+        if xp_file is None:
+            raise ValueError("No experiment file given")
+
+    # --- Set some options
+
+    if xpm_config_dir is not None:
+        assert xpm_config_dir.is_dir()
+        LauncherRegistry.set_config_dir(xpm_config_dir)
+
+    # --- Loads the XP file
+    xp_file = Path(xp_file)
+    if not xp_file.exists() and xp_file.suffix != ".py":
+        xp_file = xp_file.with_suffix(".py")
+    xp_file = Path(yaml_file).parent / xp_file
+
+    with open(xp_file, "r") as f:
+        source = f.read()
+    if sys.version_info < (3, 9):
+        the__file__ = str(xp_file)
+    else:
+        the__file__ = str(xp_file.absolute())
+
+    code = compile(source, filename=the__file__, mode="exec")
+    _locals: Dict[str, Any] = {}
+
+    sys.path.append(str(xp_file.parent.absolute()))
+    try:
+        exec(code, _locals, _locals)
+    finally:
+        sys.path.pop()
+
+    # --- ... and runs it
+    helper = _locals.get("run", None)
+    if helper is None:
+        raise ValueError(f"Could not find run function in {the__file__}")
+
+    if not isinstance(helper, ExperimentHelper):
+        helper = ExperimentHelper(helper)
+
+    parameters = inspect.signature(helper.callable).parameters
+    list_parameters = list(parameters.values())
+    assert len(list_parameters) == 2, (
+        "Callable function should only "
+        f"have two arguments (got {len(list_parameters)})"
+    )
+
+    schema = list_parameters[1].annotation
+    omegaconf_schema = OmegaConf.structured(schema())
+
+    configuration = OmegaConf.merge(*yamls)
+    if extra_conf:
+        configuration.merge_with(OmegaConf.from_dotlist(extra_conf))
+    if omegaconf_schema is not None:
+        try:
+            configuration = OmegaConf.merge(omegaconf_schema, configuration)
+        except omegaconf.errors.ConfigKeyError as e:
+            cprint(f"Error in configuration:\n\n{e}", "red", file=sys.stderr)
+            sys.exit(1)
+
+    # Move to an object container
+    configuration: schema = OmegaConf.to_container(
+        configuration, structured_config_mode=SCMode.INSTANTIATE
+    )
+
+    if show:
+        print(json.dumps(OmegaConf.to_container(configuration)))  # noqa: T201
+        sys.exit(0)
+
+    # Get the working directory
+    if workdir is None or not Path(workdir).is_dir():
+        workdir = get_workspace(workdir).path.expanduser().resolve()
+        logging.info("Using working directory %s", workdir)
+
+    # --- Runs the experiment
+    with experiment(
+        workdir, configuration.id, host=host, port=port, run_mode=run_mode
+    ) as xp:
+        # Set up the environment
+        for key, value in env:
+            xp.setenv(key, value)
+
+        # Run the experiment
+        helper.xp = xp
+        helper.run(list(args), configuration)
+
+        # ... and wait
+        xp.wait()

experimaestro-1.4.0/src/experimaestro/experiments/configuration.py

@@ -0,0 +1,32 @@
+from typing import Optional
+import attr
+
+try:
+    from typing import dataclass_transform
+except ImportError:
+    from typing_extensions import dataclass_transform
+
+
+@dataclass_transform(kw_only_default=True)
+def configuration(*args, **kwargs):
+    """Method to define keyword only dataclasses
+
+    Configurations are keyword-only
+    """
+
+    return attr.define(*args, kw_only=True, slots=False, hash=True, eq=True, **kwargs)
+
+
+@configuration()
+class ConfigurationBase:
+    id: str
+    """ID of the experiment"""
+
+    description: str = ""
+    """Description of the experiment"""
+
+    file: str = "experiment"
+    """qualified name (relative to the module) for the file containing a run function"""
+
+    parent: Optional[str]
+    """Relative path of a YAML file that should be merged"""

{experimaestro-1.3.5 → experimaestro-1.4.0}/src/experimaestro/scheduler/base.py

@@ -5,7 +5,7 @@ from pathlib import Path
 from shutil import rmtree
 import threading
 import time
-from typing import List, Optional, Set, TypeVar, Union, TYPE_CHECKING
+from typing import Any, List, Optional, Set, TypeVar, Union, TYPE_CHECKING
 import enum
 import signal
 import asyncio
@@ -482,7 +482,7 @@ class Scheduler:
 
         return None
 
-    async def aio_submit(self, job: Job) -> JobState:
+    async def aio_submit(self, job: Job) -> JobState:  # noqa: C901
         """Main scheduler function: submit a job, run it (if needed), and returns
         the status code
         """
@@ -693,14 +693,25 @@ ServiceClass = TypeVar("ServiceClass", bound=Service)
 
 
 class experiment:
-    """Experiment context"""
+    """Main experiment object
+
+    It is a context object, i.e. experiments is run with
+
+    ```py
+        with experiment(...) as xp:
+            ...
+    ```
+    """
 
     # Current experiment
     CURRENT: Optional["experiment"] = None
 
     @staticmethod
     def current() -> "experiment":
-        """Returns the current experiment, but checking first if set"""
+        """Returns the current experiment, but checking first if set
+
+        If there is no current experiment, raises an AssertError
+        """
         assert experiment.CURRENT is not None, "No current experiment defined"
         return experiment.CURRENT
 
@@ -718,9 +729,18 @@ class experiment:
         """
         :param env: an environment -- or a working directory for a local
             environment
-        :param port: the port for the web server (overrides environment port if
-            any). Use None to avoid running a web server (default when dry run).
+
+        :param name: the identifier of the experiment
+
         :param launcher: The launcher (if not provided, inferred from path)
+
+        :param host: The host for the web server (overrides the environment if
+            set)
+        :param port: the port for the web server (overrides the environment if
+            set). Use negative number to avoid running a web server (default when dry run).
+
+        :param run_mode: The run mode for the experiment (normal, generate run
+            files, dry run)
         """
 
         from experimaestro.server import Server
@@ -759,7 +779,7 @@ class experiment:
         self.scheduler = Scheduler(self, name)
         self.server = (
             Server(self.scheduler, settings.server)
-            if settings.server.port is not None
+            if (settings.server.port is not None and settings.server.port >= 0)
             and self.workspace.run_mode == RunMode.NORMAL
             else None
         )
@@ -842,7 +862,9 @@ class experiment:
         self.environment.setenv(name, value)
 
     def token(self, name: str, count: int):
-        """Returns a token for this experiment depending on the host"""
+        """Returns a token for this experiment
+
+        The token is the default token of the workspace connector"""
         return self.workspace.connector.createtoken(name, count)
 
     def __enter__(self):
@@ -928,8 +950,43 @@ class experiment:
                 self.server.stop()
 
     def add_service(self, service: ServiceClass) -> ServiceClass:
-        """Adds a service (e.g. tensorboard viewer) to the experiment"""
+        """Adds a service (e.g. tensorboard viewer) to the experiment
+
+        :param service: A service instance
+        :type service: Service
+        :return: The same service instance
+        """
         self.services[service.id] = service
         for listener in self.scheduler.listeners:
             listener.service_add(service)
         return service
+
+    def save(self, obj: Any, name: str = "default"):
+        """Serializes configurations.
+
+        Saves configuration objects within the experimental directory
+
+        :param obj: The object to save
+        :param name: The name of the saving directory (default to `default`)
+        """
+
+        if self.workspace.run_mode == RunMode.NORMAL:
+            from experimaestro import save
+
+            save_dir = self.workdir / "data" / name
+            save_dir.mkdir(exist_ok=True, parents=True)
+
+            save(obj, save_dir)
+
+    def load(self, reference: str, name: str = "default"):
+        """Serializes configurations.
+
+        Loads configuration objects from an experimental directory
+
+        :param reference: The name of the experiment
+        :param name: The name of the saving directory (default to `default`)
+        """
+        from experimaestro import load
+
+        path = self.workspace.experimentspath / reference / "data" / name
+        return load(path)

{experimaestro-1.3.5 → experimaestro-1.4.0}/src/experimaestro/scheduler/services.py

@@ -6,6 +6,8 @@ from typing import Set
 
 
 class ServiceListener:
+    """A service listener"""
+
     def service_state_changed(service):
         pass
 
@@ -18,6 +20,12 @@ class ServiceState(Enum):
 
 
 class Service:
+    """An experiment service
+
+    Services can be associated with an experiment. They send
+    notifications to service listeners.
+    """
+
     id: str
     _state: ServiceState = ServiceState.STOPPED
 
@@ -25,9 +33,17 @@ class Service:
         self.listeners: Set[ServiceListener] = set()
 
     def add_listener(self, listener: ServiceListener):
+        """Adds a listener
+
+        :param listener: The listener to add
+        """
         self.listeners.add(listener)
 
     def remove_listener(self, listener: ServiceListener):
+        """Removes a listener
+
+        :param listener: The listener to remove
+        """
         self.listeners.remove(listener)
 
     def description(self):
@@ -47,6 +63,8 @@ class Service:
 
 
 class WebService(Service):
+    """Web service"""
+
     def __init__(self):
         super().__init__()
         self.url = None