diff --git a/docs/fundamentals/task.md b/docs/fundamentals/task.md index 47ed2b3f..db795fba 100644 --- a/docs/fundamentals/task.md +++ b/docs/fundamentals/task.md @@ -157,7 +157,7 @@ Once a Task is created, the Task object can be accessed from anywhere in the cod If multiple Tasks need to be created in the same process (for example, for logging multiple manual runs), make sure to close a Task, before initializing a new one. To close a task simply call `task.close` -(see example [here](https://github.com/allegroai/clearml/blob/master/examples/advanced/multiple_tasks_single_process.py)). +(see example [here](../guides/advanced/multiple_tasks_single_process.md)). When initializing a Task, its project needs to be specified. If the project entered does not exist, it will be created. Projects can be divided into sub-projects, just like folders are broken into sub-folders. diff --git a/docs/guides/advanced/execute_remotely.md b/docs/guides/advanced/execute_remotely.md new file mode 100644 index 00000000..d9051461 --- /dev/null +++ b/docs/guides/advanced/execute_remotely.md @@ -0,0 +1,76 @@ +--- +title: Remote Execution +--- + +The [execute_remotely_example](https://github.com/allegroai/clearml/blob/master/examples/advanced/execute_remotely_example.py) +script demonstrates the use of the [`Task.execute_remotely`](../../references/sdk/task.md#execute_remotely/) method. + +:::note +Make sure to have at least one [ClearML Agent](../../clearml_agent.md) running and assigned to listen to the `default` queue +``` +clearml-agent daemon --queue default +``` +::: + +## Execution Flow + +The script trains a simple deep neural network on the PyTorch built-in MNIST dataset. The following describes the code's +execution flow: +1. The training runs for one epoch. +1. The code passes the `execute_remotely` method which terminates the local execution of the code and enqueues the task + to the `default` queue, as specified in the `queue_name` parameter. +1. An agent listening to the queue fetches the task and restarts task execution remotely. When the agent executes the task, + the `execute_remotely` is considered no-op. + +An execution flow that uses `execute_remotely` method is especially helpful when running code on a development machine for a few iterations +to debug and to make sure the code doesn't crash, or to set up an environment. After that, the training can be +moved to be executed by a stronger machine. + +During the execution of the example script, the code does the following: +* Uses ClearML's automatic and explicit logging. +* Creates an experiment named `remote_execution pytorch mnist train`, which is associated with the `examples` project. + + +## Scalars + +In the example script's `train` function, the following code explicitly reports scalars to **ClearML**: + +```python +Logger.current_logger().report_scalar( + "train", "loss", iteration=(epoch * len(train_loader) + batch_idx), value=loss.item()) +``` + +In the `test` method, the code explicitly reports `loss` and `accuracy` scalars. + +```python +Logger.current_logger().report_scalar( + "test", "loss", iteration=epoch, value=test_loss) +Logger.current_logger().report_scalar( + "test", "accuracy", iteration=epoch, value=(correct / len(test_loader.dataset))) +``` + +These scalars can be visualized in plots, which appear in the ClearML web UI, in the experiment's +page **>** **RESULTS** **>** **SCALARS**. + +![image](../../img/examples_pytorch_mnist_07.png) + +## Hyperparameters + +ClearML automatically logs command line options defined with `argparse`. They appear in **CONFIGURATIONS** **>** **HYPER PARAMETERS** **>** **Args**. + +![image](../../img/examples_pytorch_mnist_01.png) + +## Console + +Text printed to the console for training progress, as well as all other console output, appear in **RESULTS** **>** **CONSOLE**. + +![image](../../img/examples_pytorch_mnist_06.png) + +## Artifacts + +Model artifacts associated with the experiment appear in the info panel of the **EXPERIMENTS** tab and in +the info panel of the **MODELS** tab. + + +![image](../../img/examples_remote_execution_artifacts.png) + diff --git a/docs/guides/advanced/multiple_tasks_single_process.md b/docs/guides/advanced/multiple_tasks_single_process.md new file mode 100644 index 00000000..744b4b75 --- /dev/null +++ b/docs/guides/advanced/multiple_tasks_single_process.md @@ -0,0 +1,25 @@ +--- +title: Multiple Tasks in Single Process +--- + +The [multiple_tasks_single_process](https://github.com/allegroai/clearml/blob/master/examples/advanced/multiple_tasks_single_process.py) +script demonstrates the capability to log a single script in multiple ClearML tasks. + +In order to log a script in multiple tasks, each task needs to be initialized using the [`Task.init`](../../references/sdk/task.md#taskinit) +method with the `task_name` and `project_name` parameters input. Before initializing an additional task in the same script, the +previous task must be manually shut down with the [`close`](../../references/sdk/task.md#close) method. + +When the script is executed, it should return something like this: + +```text +ClearML Task: created new task id=5c4d2d3674a94e35b10f04d9d2180l62 +ClearML results page: https://app.community.clear.ml/projects/6835eb7316554c2b933b69638470fe02/experiments/5c4d2d3674a94e35b10f04d9d2180l62/output/log +... +ClearML Task: created new task id=28a84c17a6204b438e1e7a094a234a7f +ClearML results page: https://app.community.clear.ml/projects/7894eb7316554c4b933a79638473fe02/experiments/28a84c17a6204b438e1e7a094a234a7f/output/log +... +ClearML Task: created new task id=6d1e253ba0234d32a38sg85013185g46 +ClearML results page: https://app.community.clear.ml/projects/7895eb7316554c4b933a69638470fe02/experiments/6d1e253ba0234d32a38sg85013185g46/output/log +``` + +Notice that three separate tasks with distinct IDs are created, and a link is provided to view the results of each one. \ No newline at end of file diff --git a/docs/img/examples_remote_execution_artifacts.png b/docs/img/examples_remote_execution_artifacts.png new file mode 100644 index 00000000..fd73512f Binary files /dev/null and b/docs/img/examples_remote_execution_artifacts.png differ diff --git a/sidebars.js b/sidebars.js index 1fce8ba8..fb57f75b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -57,6 +57,7 @@ module.exports = { ], guidesSidebar: [ 'guides/guidemain', + {'Advanced': ['guides/advanced/execute_remotely', 'guides/advanced/multiple_tasks_single_process']}, {'Automation': ['guides/automation/manual_random_param_search_example', 'guides/automation/task_piping']}, {'Data Management': ['guides/data management/data_man_simple', 'guides/data management/data_man_folder_sync', 'guides/data management/data_man_cifar_classification']}, {'ClearML Task': ['guides/clearml-task/clearml_task_tutorial']},