Complete doc for python API

src/orion/client/__init__.py

@@ -61,26 +61,55 @@ def create_experiment(name, version=None, space=None, algorithms=None,
                       working_dir=None):
     """Create an experiment
 
-    TODO: Explain Workflow
+    There is 2 main scenarios
 
-    New experiment. What must be defined
+    1) The experiment is new
 
-    Already existing experiment.
-    What happens if arguments omitted.
-    What happens if arguments passed and the same.
-    What happens if arguments passed and different.
+    ``name`` and ``space`` arguments are required, otherwise ``NoConfigurationError`` will be raised.
 
-    All arguments except `name` can be omitted if experiment already exists.
+    All other arguments (``algorithms``, ``strategy``, ``max_trials``, ``storage``, ``branching`` and
+    ``working_dir``) will be replaced by system's defaults if ommited. The system's defaults can
+    also be overriden in global configuration file as described for the database
+    in :ref:`Database Configuration`. We do not recommand overriding the algorithm configuration
+    using system's default, but overriding the storage configuration can be very convenient if the
+    same storage is used for all your experiments.
+
+    2) The experiment exist in the database.
+
+    We can break down this scenario in two sub-scenarios for clarity.
+
+    2.1) Only experiment name is given.
+
+    The configuration will be fetched from database.
+
+    2.2) Some other arguments than the name are given.
+
+    The configuration will be fetched from database and given arguments will override them.
+    ``max_trials`` may be overwritten in DB, but any other changes will lead to a branching. Instead
+    of creating the experiment ``(name, version)``, it will create a new experiment
+    ``(name, version+1)`` which will have the same configuration than ``(name, version)`` except for the
+    differing arguments given by user. This new experiment will have access to trials of
+    ``(name, version)``, adapted according to the differences between ``version`` and ``version+1``.
+    A previous version can be accessed by specifying the ``version`` argument.
+
+    Causes of experiment branching are:
+    - Change of search space
+        - New dimension
+        - Different prior
+        - Missing dimension
+    - Change of algorithm
+    - Change of strategy (Not implemented yet)
+    - Change of code version (Only supported by commandline API for now)
 
     Parameters
     ----------
     name: str
         Name of the experiment
     version: int, optional
-        Version of the experiment. Defaults to last existing version for a given `name`
+        Version of the experiment. Defaults to last existing version for a given ``name``
         or 1 for new experiment.
     space: dict, optional
-        Optimization space of the algorithm. Should have the form `dict(name='<prior>(args)')`.
+        Optimization space of the algorithm. Should have the form ``dict(name='<prior>(args)')``.
     algorithms: str or dict, optional
         Algorithm used for optimization.
     strategy: str or dict, optional
@@ -97,11 +126,11 @@ def create_experiment(name, version=None, space=None, algorithms=None,
 
         branch_to: str, optional
             Name of the experiment to branch to. The parent experiment will be the one specified by
-            `(name, version)`, and the child will be `(branch_to, 1)`.
+            ``(name, version)``, and the child will be ``(branch_to, 1)``.
         branch_from: str, optional
             Name of the experiment to branch from.
             The parent experiment will be the one specified by
-            `(branch_from, last version)`, and the child will be `(name, 1)`.
+            ``(branch_from, last version)``, and the child will be ``(name, 1)``.
         manual_resolution: bool, optional
             Starts the prompt to resolve manually the conflicts. Defaults to False.
         algorithm_change: bool, optional
@@ -133,8 +162,8 @@ def create_experiment(name, version=None, space=None, algorithms=None,
     `ValueError`
         The configuration is different than the corresponding one in DB and the branching cannot be
         solved automatically. This usually happens if the version=x is specified but the experiment
-        `(name, x)` already has a child `(name, x+1)`. If you really need to branch from version x,
-        give it a new name to branch to with `branching={'branch_to': <new_name>}`.
+        ``(name, x)`` already has a child ``(name, x+1)``. If you really need to branch from version x,
+        give it a new name to branch to with ``branching={'branch_to': <new_name>}``.
     `NotImplementedError`
         If the algorithm, storage or strategy specified is not properly installed.
 

src/orion/core/io/experiment_builder.py

@@ -116,7 +116,6 @@
 # Functions to build experiments
 ##
 
-# TODO: branch_from cannot be passed from build_from_cmdargs, must add --branch-from argument
 def build(name, version=None, branching=None, **config):
     """Build an experiment object
 

src/orion/core/worker/experiment.py

@@ -409,7 +409,6 @@ class ExperimentView(object):
                         ["fetch_trials", "fetch_trials_by_status", "get_trial"])
 
     def __init__(self, experiment):
-        """TODO"""
         self._experiment = experiment
         self._experiment._storage = ReadOnlyStorageProtocol(experiment._storage)
 

tests/unittests/core/io/test_experiment_builder.py

@@ -21,19 +21,6 @@ def count_experiments():
     return len(get_storage().fetch_experiments({}))
 
 
-# TODO: Remove and use OrionState instead
-@pytest.fixture
-def init_storage(clean_db, test_config):
-    """Create the storage singleton."""
-    experiment_builder.setup_storage(
-        storage={
-            'type': 'legacy',
-            'database': {
-                'type': 'mongodb',
-                'name': 'orion_test',
-                'host': 'mongodb://user:pass@localhost'}})
-
-
 @pytest.fixture
 def space():
     """Build a space definition"""
@@ -43,7 +30,6 @@ def space():
 @pytest.fixture()
 def python_api_config():
     """Create a configuration without the cli fluff."""
-    # TODO: replace metadata[priors] by space when space in DB
     new_config = dict(
         name='supernaekei',
         version=1,
@@ -631,10 +617,9 @@ def test_new_child_with_branch(self):
         """Check that experiment is not incremented when branching with a new name."""
         name = 'parent'
         space = {'x': 'uniform(0, 10)'}
-        metadata = {'priors': space}  # TODO: remove when space in db
 
         with OrionState(experiments=[], trials=[]):
-            parent = experiment_builder.build(name=name, space=space, metadata=metadata)
+            parent = experiment_builder.build(name=name, space=space)
 
             assert parent.name == name
             assert parent.version == 1
@@ -659,10 +644,9 @@ def test_no_increment_when_child_exist(self):
         """Check that experiment cannot be incremented when asked for v1 while v2 exists."""
         name = 'parent'
         space = {'x': 'uniform(0,10)'}
-        metadata = {'priors': space}  # TODO: remove when space in db
 
         with OrionState(experiments=[], trials=[]):
-            parent = experiment_builder.build(name=name, space=space, metadata=metadata)
+            parent = experiment_builder.build(name=name, space=space)
             child = experiment_builder.build(name=name, space={'x': 'loguniform(1,10)'})
             assert child.name == parent.name
             assert parent.version == 1
@@ -678,10 +662,9 @@ def test_race_condition_wout_version(self, monkeypatch):
         """
         name = 'parent'
         space = {'x': 'uniform(0,10)'}
-        metadata = {'priors': space}  # TODO: remove when space in db
 
         with OrionState(experiments=[], trials=[]):
-            parent = experiment_builder.build(name, space=space, metadata=metadata)
+            parent = experiment_builder.build(name, space=space)
             child = experiment_builder.build(name=name, space={'x': 'loguniform(1,10)'})
             assert child.name == parent.name
             assert parent.version == 1
@@ -754,10 +737,9 @@ def test_race_condition_w_version(self, monkeypatch):
         """
         name = 'parent'
         space = {'x': 'uniform(0,10)'}
-        metadata = {'priors': space}  # TODO: remove when space in db
 
         with OrionState(experiments=[], trials=[]):
-            parent = experiment_builder.build(name, space=space, metadata=metadata)
+            parent = experiment_builder.build(name, space=space)
             child = experiment_builder.build(name=name, space={'x': 'loguniform(1,10)'})
             assert child.name == parent.name
             assert parent.version == 1

tests/unittests/core/test_producer.py

@@ -51,13 +51,6 @@ def producer(hacked_exp, random_dt, exp_config, categorical_values):
     """Return a setup `Producer`."""
     # make init done
 
-    # TODO: Remove this commented out if test pass
-    # hacked_exp.configure(exp_config[0][3])
-    # # insert fake point
-    # fake_point = ('gru', 'rnn')
-    # assert fake_point in hacked_exp.space
-    # hacked_exp.algorithms.algorithm.value = fake_point
-
     hacked_exp.pool_size = 1
     hacked_exp.algorithms.algorithm.possible_values = categorical_values
     hacked_exp.algorithms.seed_rng(0)