---
# System prepended metadata

title: Untitled

---

## general principles

1. The default expname is taken from `PT_DEFAULT_EXP`.
    1. if the env var is not set, `pt run` defaults to petnames.
    2. if the env var is set, most other commands don't need to put an expname.
3. if an expname is given, it must exist.
4. if a non-existing exp name is given, it can be created with `-c`.
5. job names are taken from yaml by default.
6. job names can be overwritten on commandline.
7. job names have to be unique in an experiment.

## running single jobs
```bash
# run job "bert" in exp <random pet name>
pt run baselines.yml :bert

crazy-cow
|--bert

# job names have to be uniq in an experiment.
# this prompts to replace:
pt run baselines.yml :bert crazy-cow

# append job "bert" from yml as "bert2"
pt run baselines.yml :bert:bert2  crazy-cow # or alternatively:
pt run baselines.yml :bert=bert2  crazy-cow

crazy-cow
|--bert       # <-- this is the job from the 1st run
|--bert2      # <-- the renamed job from the 2nd run
```

## custom experiment names
```bash
# runs baselines jobs in experiment test
pt run baselines.yml :bert test

# append is the default.
pt run baselines.yml :bert:bert2 test   # or
pt run baselines.yml :bert=bert2 test
pt run baselines.yml :bert test  # <-- asks to replace
```

## running multiple jobs
```bash
# semantics are the same as before.
pt run baselines.yml :bert :gpt
pt run baselines.yml :bert=bert2 :gpt  # <-- renames only bert

# if any of the job names already exist, prompt before replacing. 
```

## running searches

basically like current pt, but append is the default if you spec a name.

```bash
# search requires an experiment name
pt run search.yml  # <-- runs search in crazy-cow exp
pt run search.yml expname  # <-- runs search in expname. Prompts if expname already exists.
```

## default experiments

we can set a default experiment name like so:
```bash 
# this remembers the default for the future (in the project settings):
pt run some.yml --set-default :bert crazy-cow  

pt run baselines.yml :bert    # <-- runs in crazy-cow now

# always confirm when appending searches (to crazy cows)
pt run search.yml   
pt status    # <-- shows crazy-cow exp
pt results :bert  # <-- downloads crazy-cow/bert
```

## renaming/moving stuff
```bash
# without default experiment
pt mv old-expname new-expname
pt mv old-expname :old-jobname=new-jobname
pt mv old-expname :old-jobname new-expname
pt mv old-expname :old-jobname=new-jobname new-expname
pt mv old-expname :job1 :job2 new-expname

# with default experiment
pt mv :old-jobname=new-jobname
pt mv :job1 :job2 new-exp
```

## description handling
1.  prompt once per `pt run`, copy description to jobs and experiments.
2.  add new `pt edit exp :job` that edits job description

## hyperdrive

1. An experiment name should always be specified for a hyperdrive experiment, hd-exp below.
2. The experiment contains a hyperdrive job (hd-job now), which is unmovable. So conceptually hd-exp = hd-job.
3. The runs created by hyperdrive are automatically appended to hd-exp upon any pt call that involves that experiment.
4. pt calls on real jobs from hd-exp are all valid, including mv.
5. pt calls on the hyperdrive job error out (the user does not even know it exists). It is not shown on pt status, nor pt show.
6. pt status should have a way to show that it is a hyperdrive experiment, and probably give the status of the experiment (e.g. running, etc).
7. Moving a job to a hyperdrive experiment should be discussed in more details, but it might be worth allowing, so people can compare runs.
