From d84ccda748defa2996592ff68dbe69d480af2b6c Mon Sep 17 00:00:00 2001 From: Alexey Guseynov Date: Fri, 13 May 2022 08:11:21 -0700 Subject: [PATCH] Improve Experiment docstring. PiperOrigin-RevId: 448498076 Change-Id: Iddd08c55966b2d5a786d76e1bebf81f14969c9f3 GitOrigin-RevId: ac584502bae3dc1a49864c1dd720beb60a889fb4 --- xmanager/xm/core.py | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/xmanager/xm/core.py b/xmanager/xm/core.py index 11fd01f..8bdf010 100644 --- a/xmanager/xm/core.py +++ b/xmanager/xm/core.py @@ -529,11 +529,28 @@ async def launch_job(job: Any) -> None: class Experiment(abc.ABC): - """Experiment contains a family of jobs run on the same snapshot of code. + """Experiment is the core unit of research in XManager. - Experiment also implements the behavior of how to add and execute jobs. - Attempting to add jobs that contain Executables with unsupported types will - fail. + An experiment typically involves running a computation (e.g. training a model) + in different hyperparameter configurations. Experiments are made up of work + units, which do the computation(s) in question, and auxiliary units which + perform other functions like TensorBoard. It can have associated metadata, + such as title or source code commit from which it has been compiled. + + XManager API provides multiple implementations of the Experiment class which + use different backends to start jobs. Types of supported Executables may vary + between these implementations. Usually experiments woulbe be created by though + xm_.create_experiment() functions. + + While experiment metadata and statuses can accessed and altered directly, + adding work or auxiliary units requires entering experiment context: + + with xm_foo.create_experiment(...) as experiment: + experiment.add(xm.Job(...)) + + This context would spawn background event pool to support asynchronous + operations and ensure that they all are completed on exit. It also may mark + experiment as failed if an exception is thrown. """ # An event loop in which job generators would be run.