Merge pull request #927 from Make42/master

Improve the hyper_parameter example

clearml/backend_interface/task/task.py

@@ -674,18 +674,28 @@ class Task(IdObjectBase, AccessMixin, SetupUploadMixin):
     def mark_completed(self, ignore_errors=True, status_message=None, force=False):
         # type: (bool, Optional[str], bool) -> ()
         """
-        Use this function to close and change status of remotely executed tasks.
+        Use this method to close and change status of (remotely!) executed tasks.
 
-        Closes the current Task, changes its status to "Completed", and terminates the running Python process.
+        This method closes the task it is a member of,
-        This is in contrast to :meth:`Task.close`, which does the first two steps, but does not terminate the running Python process.
+        changes its status to "Completed", and
+        terminates the Python process that created the task.
+        This is in contrast to :meth:`Task.close`, which does the first two steps, but does not terminate any Python process.
 
+        Let's say that process A created the task and process B has a handle on the task, e.g., with :meth:`Task.get_task`.
+        Then, if we call :meth:`Task.mark_completed`, the process A is terminated, but process B is not.
+
+        However, if :meth:`Task.mark_completed` was called from the same process in which the task was created,
+        then - effectively - the process terminates itself.
         For example, in
-        ```
+
+        .. code-block:: py
+
+            task = Task.init(...)
             task.mark_completed()
             from time import sleep
             sleep(30)
             print('This text will not be printed!')
-        ```
+
         the text will not be printed, because the Python process is immediately terminated.
         
         :param bool ignore_errors: If True default), ignore any errors raised

clearml/task.py

@@ -1732,10 +1732,11 @@ class Task(_Task):
     def close(self):
         """
         Closes the current Task and changes its status to "Completed".
-        Enables you to manually shutdown the task.
+        Enables you to manually shut down the task from the process which opened the task.
-        This method does not terminate the current Python process, in contrast to :meth:`Task.mark_completed`.
 
-        After having :meth:`Task.close`d a task, the respective object cannot be used anymore and
+        This method does not terminate the (current) Python process, in contrast to :meth:`Task.mark_completed`.
+
+        After having :meth:`Task.close` -d a task, the respective object cannot be used anymore and
         methods like :meth:`Task.connect` or :meth:`Task.connect_configuration` will throw a `ValueError`.
         In order to obtain an object representing the task again, use methods like :meth:`Task.get_task`.
         

examples/reporting/configuration_including_hyperparameters.py

@@ -1,4 +1,9 @@
-# ClearML - example code, ArgumentParser parameter logging and dictionary parameter logging
+# ClearML - example code for logging into "CONFIGURATION":
+# - ArgumentParser parameter logging
+# - user properties logging
+# - logging of hyperparameters via dictionary
+# - logging of hyperparameters via TaskParameters
+# - logging of configuration objects via TaskParameters
 #
 from __future__ import absolute_import
 from __future__ import division
@@ -10,7 +15,24 @@ from enum import Enum
 
 
 from clearml import Task
+from clearml.task_parameters import TaskParameters, param, percent_param
 
+# Connecting ClearML with the current process,
+# from here on everything is logged automatically
+task = Task.init(project_name='FirstTrial', task_name='first_trial')
+
+
+# -----------------------------------------------
+#  Report user properties
+# -----------------------------------------------
+
+task.set_user_properties(custom1='great', custom2=True)
+task.set_user_properties(custom3=1, custom4=2.0)
+
+
+# -----------------------------------------------
+#  Report hyperparameters via dictionary
+# -----------------------------------------------
 
 class StringEnumClass(Enum):
     A = 'a'
@@ -22,10 +44,6 @@ class IntEnumClass(Enum):
     D = 2
 
 
-# Connecting ClearML with the current process,
-# from here on everything is logged automatically
-task = Task.init(project_name='examples', task_name='Hyper-parameters example')
-
 parameters = {
     'list': [1, 2, 3],
     'dict': {'a': 1, 'b': 2},
@@ -45,6 +63,36 @@ parameters['new_param'] = 'this is new'
 parameters['float'] = '9.9'
 print(parameters)
 
+
+# -----------------------------------------------
+#  Report hyperparameters via TaskParameters
+# -----------------------------------------------
+
+# Define a class that inherits from TaskParameters.
+# Note that TaskParameters inherits from _AttrsMeta;
+# because of `iterations` and `target_accuracy` do not need to be explicitly populated in an __init__ method.
+# Consult the documentation at https://www.attrs.org for more information.
+class MyTaskParameters(TaskParameters):
+
+    iterations = param(
+        type=int,
+        desc="Number of iterations to run",
+        range=(0, 100000),
+    )
+
+    target_accuracy = percent_param(
+        desc="The target accuracy of the model",
+    )
+
+
+my_task_parameters = MyTaskParameters(iterations=1000, target_accuracy=0.95)
+my_task_parameters = task.connect(my_task_parameters, name='from TaskParameters-like object')
+
+
+# -----------------------------------------------
+#  Report configuration objects via dictionary
+# -----------------------------------------------
+
 complex_nested_dict_configuration = {
     'list_of_dicts': [{'a': 1, 'b': 2}, {'c': 3, 'd': 4}, {'e': 5, 'f': 6}],
     'nested_dicts': {'nested': {'key': 'value', 'extra': 'value'}, 'number': 42},