Skip to content

Commit

Permalink
[NESTED] guide: Exp implementation details, naming into Overview (#3006)
Browse files Browse the repository at this point in the history
* guide: bring exp implementation details and naming from ref.
per #2909 (review)

* guide: copy edits to exp naming info.
  • Loading branch information
jorgeorpinel authored Nov 17, 2021
1 parent af94248 commit dacaf85
Show file tree
Hide file tree
Showing 2 changed files with 36 additions and 28 deletions.
41 changes: 15 additions & 26 deletions content/docs/command-reference/exp/run.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,36 +32,25 @@ data and code updates, or <abbr>hyperparameter</abbr> tuning. For the latter,
you can use the `--set-param` (`-S`) option of this command to change
`dvc param` values on-the fly.

Each experiment creates and tracks a project variation based on your
<abbr>workspace</abbr> changes. Experiments will have an auto-generated name
like `exp-bfe64` by default, which can be customized using the `--name` (`-n`)
option.
📖 See [DVC Experiments Overview][exp-overview] for more information.

<details>

### ⚙️ How does DVC track experiments?

Experiments are custom
[Git references](https://git-scm.com/book/en/v2/Git-Internals-Git-References)
(found in `.git/refs/exps`) with a single commit based on `HEAD` (not checked
out by DVC). Note that these commits are not pushed to Git remotes by default
(see `dvc exp push`).

</details>

The results of the last `dvc exp run` can be seen in the workspace. To display
and compare multiple experiments, use `dvc exp show` or `dvc exp diff`
(`plots diff` also accepts experiment names as `revisions`). Use `dvc exp apply`
to restore the results of any other experiment instead.
Each experiment creates and tracks a project variation based on the changes in
your <abbr>workspace</abbr>. The results of the last `dvc exp run` will be
reflected in the workspace. Experiments will have an auto-generated ID like
`exp-bfe64` by default. A custom name can be given instead, using the `--name`
(`-n`) option

Successful experiments can be made [persistent] by committing them to the Git
repo. Unnecessary ones can be removed with `dvc exp remove`or `dvc exp gc` (or
abandoned).
To display and compare multiple experiments, use `dvc exp show` or
`dvc exp diff` (`plots diff` also accepts experiment names as `revisions`). Use
`dvc exp apply` to restore the results of any experiment, for example to [commit
them][persisting] to Git. Unnecessary experiments can be removed with
`dvc exp remove`or `dvc exp gc` (or abandoned).

> Note that experiment data will remain in the <abbr>cache</abbr> until you use
> regular `dvc gc` to clean it up.
> Note that experiment data will remain in the local <abbr>cache</abbr> until
> you use regular `dvc gc` to clean it up.
[persistent]: /doc/user-guide/experiment-management/persisting-experiments
[exp-overview]: /doc/user-guide/experiment-management/experiments-overview
[persisting]: /doc/user-guide/experiment-management/persisting-experiments

## Checkpoints

Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,29 @@
# DVC Experiments Overview

DVC Experiments are captures automatically by DVC when you [run them].
DVC Experiments are captures automatically by DVC when you [run them]. Each
experiment creates and tracks a project variation based on the changes in your
<abbr>workspace</abbr>. Experiments preserve the latest commit in the current
branch (Git `HEAD`) as their parent or _baseline_.

<details>

### ⚙️ How does DVC track experiments?

Experiments are custom [Git references] (found in `.git/refs/exps`) with a
single commit based on `HEAD` (not checked out by DVC). Note that these commits
are not pushed to Git remotes by default (see `dvc exp push`).

</details>

Experiments will have an auto-generated ID like `exp-bfe64` by default. A custom
name can be given instead (using the `--name`/`-n` option of `dvc exp run`).

> ID or name can be used to reference experiments with `dvc exp` subcommands.
[run them]: /doc/user-guide/experiment-management/running-experiments
[git references]: https://git-scm.com/book/en/v2/Git-Internals-Git-References

## Basic Workflow
## Basic workflow

`dvc exp` commands let you automatically track a variation to a committed
project version (baseline). You can create independent groups of experiments
Expand Down

0 comments on commit dacaf85

Please sign in to comment.