From 75e21a3c641b6137aa788905a5b01a2e96df71ba Mon Sep 17 00:00:00 2001 From: Peter Rowlands Date: Tue, 5 Jul 2022 15:03:49 +0900 Subject: [PATCH] ref: update `exp run` reference for queue changes --- content/docs/command-reference/exp/remove.md | 8 +++++-- content/docs/command-reference/exp/run.md | 20 ++++++++-------- content/docs/command-reference/queue/start.md | 4 ++++ .../running-experiments.md | 23 ++++++++++--------- 4 files changed, 33 insertions(+), 22 deletions(-) diff --git a/content/docs/command-reference/exp/remove.md b/content/docs/command-reference/exp/remove.md index a3cf7d35a6..b504ff86b6 100644 --- a/content/docs/command-reference/exp/remove.md +++ b/content/docs/command-reference/exp/remove.md @@ -27,8 +27,12 @@ With `--queue`, the list of experiments awaiting execution is cleared instead. - `--queue` - remove all experiments that haven't been run yet (defined via `dvc exp run --queue`). -- `-A`, `--all` - remove all experiments that have been run. Use `--queue` to - remove queued ones. + > ⚠️ `dvc exp remove --queue` is now an alias for `dvc queue remove --queued`. + > The `--queue` option will likely be deprecated and removed in a future DVC + > release. Refer to the `dvc queue` documentation for more details. + +- `-A`, `--all` - remove all experiments that have been run. Use + `dvc queue remove` to remove queued experiment tasks. - `--rev ` - remove experiments derived from the specified `` as baseline. diff --git a/content/docs/command-reference/exp/run.md b/content/docs/command-reference/exp/run.md index a1a4a142c6..2fccdfcb47 100644 --- a/content/docs/command-reference/exp/run.md +++ b/content/docs/command-reference/exp/run.md @@ -34,13 +34,9 @@ Use the `--set-param` (`-S`) option as a shortcut to change parameter values [on-the-fly] before running the experiment. It's possible to [queue experiments] for later execution with the `--queue` -flag. To actually run them, use `dvc exp run --run-all`. Queued experiments are -run sequentially by default, but can be run in parallel using the `--jobs` -option. - -> ⚠️ Parallel runs are experimental and may be unstable. Make sure you're using -> a number of jobs that your environment can handle (no more than the CPU -> cores). +flag. Queued experiments can be run using `dvc queue start`, refer to th +`dvc queue` documentation for more information on managing the experiment task +queue. It's also possible to run special [checkpoint experiments] that log the execution progress (useful for deep learning ML). The `--rev` and `--reset` @@ -82,8 +78,7 @@ committing them to the Git repo. Unnecessary ones can be [cleared] with runs. - `--queue` - place this experiment at the end of a line for future execution, - but don't actually run it yet. Use `dvc exp run --run-all` to process the - queue. + but don't actually run it yet. Use `dvc queue start` to process the queue. > For checkpoint experiments, this implies `--reset` unless a `--rev` is > provided. @@ -100,6 +95,13 @@ committing them to the Git repo. Unnecessary ones can be [cleared] with > stages may sometimes be executed several times depending on the state of the > [run-cache] at that time. + > ⚠️ `dvc exp run --run-all [--jobs]` is now a shortcut for + > `dvc queue start [--jobs]` followed by `dvc queue logs -f`. The `--run-all` + > and `--jobs` options will likely be deprecated and removed in a future DVC + > release. It is recommended to migrate your workflows to use + > `dvc queue start` and `dvc queue logs`. Refer to the `dvc queue` + > documentation for more details. + - `-r `, `--rev ` - resume an experiment from a specific checkpoint name or hash (`commit`) in `--queue` or `--temp` runs. diff --git a/content/docs/command-reference/queue/start.md b/content/docs/command-reference/queue/start.md index f16432fec1..855b8e254d 100644 --- a/content/docs/command-reference/queue/start.md +++ b/content/docs/command-reference/queue/start.md @@ -28,6 +28,10 @@ the `--jobs` option. > a number of jobs that your environment can handle (no more than the CPU > cores). +> Note that since queued experiments are run isolated from each other, common +> stages may sometimes be executed several times depending on the state of the +> [run-cache] at that time. + ## Options - `-j `, `--` - start up to this number of workers in parallel. diff --git a/content/docs/user-guide/experiment-management/running-experiments.md b/content/docs/user-guide/experiment-management/running-experiments.md index 7269573e8e..806b1da2c5 100644 --- a/content/docs/user-guide/experiment-management/running-experiments.md +++ b/content/docs/user-guide/experiment-management/running-experiments.md @@ -116,23 +116,23 @@ Queued experiment '4109ead' for future execution. ### How are experiments queued? -Queued experiments are created similar to -[Git stash](https://www.git-scm.com/docs/git-stash). The last experiment queued -is found in `.git/refs/exps`, and earlier ones are in its [reflog]. +Queued experiments are managed using [dvc-task] and [Celery]. -[reflog]: - https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefreflogareflog +[dvc-task]: https://github.com/iterative/dvc-task +[celery]: https://docs.celeryq.dev/en/stable/index.html -Run them all with the `--run-all` flag: +Run them all with `dvc queue start`: ```dvc -$ dvc exp run --run-all +$ dvc queue start ... ``` -> Note that the order of execution is independent of their creation order. +> Note that in most cases, experiment tasks will be executed in the order that +> they were added to the queue (First In, First Out), but this order is not +> guaranteed due to Celery limitations. Their execution happens outside your workspace in temporary directories for isolation, so each experiment is derived from the workspace at @@ -164,10 +164,11 @@ committing unwanted files into Git (e.g. once successful experiments are -💡 To clear the experiments queue and start over, use `dvc exp remove --queue`. +💡 To clear the experiments queue and start over, use +`dvc queue remove --queued`. -> 📖 See the `dvc exp run` reference for more options related to experiments -> queue, such as running them in parallel with `--jobs`. +> 📖 See the `dvc exp run` and `dvc queue` references for more options related +> to the experiments queue, such as running them in parallel with `--jobs`. ## Checkpoint experiments