<commit_before>Assuming that you have already a [project](projects) created and initialized,
and you uploaded your code consisting of a single file `train.py` that accepts 2 parameters

  * learning rate `lr`
  * batch size `batch_size`

## Updating the polyaxonfile.yml

The first thing that you need to do is to update the default `polyaxonfile.yml` that was generated.

We will start first by adding the `run` section. For example if the code requires `tensorflow` and `sklearn`,
the polyaxonfile.yml `run` section could look something like this

```yaml
---
...

run:
  image: tensorflow/tensorflow:1.4.1-py3
  steps:
    - pip install scikit-learn
  cmd: python3 train.py --batch-size={{ batch_size }} --lr={{ lr }}
```

If the code requires many python dependencies, Polyaxon provides an elegant way to install these requirements,
instead of specifying every single library in the `steps` part of the `run` section,
we can create a requirements file with the name `polyaxon_requirements.txt` and just create one command in the steps `pip install -r polyaxon_requirements.txt`
and Polyaxon will automatically detect it and install the requirements.

Polyaxon also allows you to specify a `polyaxon_setup.sh` file, and a command to execute that file `./polyaxon_setup.sh`.

Let's create a `polyaxon_requirements.txt` to demonstrate this process.

```bash
$ vi polyaxon_requirements.txt
...
```

And modify the polyaxonfile.yml to install our requirements


```yaml
---
version: 1

project:
  name: mnist

declarations:
  lr: 0.01
  batch_size: 128

run:
  image: tensorflow/tensorflow:1.4.1-py3
  steps:
    - pip install -r polyaxon_requirements.txt
  cmd: python3 train.py --batch-size={{ batch_size }} --lr={{ lr }}
```

!!! Tip
    The declarations section was not completely necessary,
    we could have also just passed the value directly `--batch-size=128 --lr=0.01`

    For more information please visite the [declarations section](/polyaxonfile_specification/sections#declarations) reference.

!!! info "More details"
    For more details about the `run section` check the [run section reference](/polyaxonfile_specification/sections#run)


To make sure that the polyaxon file is valid, you can run the following command,

```bash
$ polyaxon check -f polyaxonfile.yml -m

Polyaxonfile valid

This file has one independent experiment.
```

This command validate the polyaxon file, and the option `-m` returns the matrix space,
in this case we have only one independent experiment. This option is important when we want
to check a polyaxonfile with a matrix section having an [experiment group](experiment_groups)

## Running an experiment

To run this polyaxonfile execute

```bash
$ polyaxon run

Creating an independent experiment.

Experiment was created.
```

!!! info "More details"
    For more details about this command please run `polyaxon run --help`,
    or check the [command reference](/polyaxon_cli/commands/run)

## Checking the experiments of a project

We can check that the project has now an independent experiment created.
For that we can use Polyaxon dashboard or Polyaxon CLI,

```bash
$ polyaxon project experiments

Experiments for project `admin/mnist`.


Navigation:

-----  -
count  1
-----  -

Experiments:

  sequence  unique_name       user    project_name    experiment_group_name    last_status    created_at         is_clone      num_jobs  finished_at    started_at
----------  ----------------  ------  --------------  -----------------------  -------------  -----------------  ----------  ----------  -------------  ------------
        1  admin.mnist.1      admin   admin.mnist                              Created        a few seconds ago  False                0

```

You should notice that the column experiment group is empty,
which means that this experiment is running independently of a group.


## Running the experiment with different parameters

After running this experiment, we can imagine that you were not satisfied with the result and
that you wanted to try another learning rate `0.5`.
If you hardcoded the value and passed it directly `--lr=0.01`, you would be obliged to updated the polyaxonfile.yml.
Of course we can do that also now, but since we declared the `lr` in the declarations sections,
we can create instead another file `polyaxonfile_override.yml` to override just that section:

!!! Tip "You can call your polyaxonfiles anything you want"
    By default polyaxon commands look for files called `polyaxonfile.yml`.
    If you call your files differently or want to override values, you need to use the option `-f`

```bash
$ vi polyaxonfile_override.yml
```

And past the new declarations section.

```yaml
---
version: 1

declarations:
  lr: 0.5
```

and run again

```bash
$ polyaxon run -f polyaxonfile.yml -f polyaxonfile_override.yml

Creating an independent experiment.

Experiment was created.
```

You can repeat this process as much as you wish until you are satisfied with the performance of your model.
Polyaxon will create a new experiment for you each time. However, if the space of values you want to try is large,
modifying the values manually and executing `polyaxon run` is not optimal,
what you can do instead is create an [experiment group](experiment_groups).

## Stopping an experiment

To stop experiment 2 for example, run

```bash
$ polyaxon experiment -xp 2 stop
```

!!! caution
    There's another command `delete`, the difference between `stop` and `delete`,
    is that delete will remove the experiment completely from your database.

## Distributed Runs

!!! caution
    This section is oriented for users who want to run experiments with multiple jobs
    based on Tensorflow.

After modifying our `train.py` we want to run the experiment with 1 master 4 workers and 1 parameter server.
We also want to customize the resources of the each node.

First let's upload the new version of the code

```bash
$ polyaxon upload
```

!!! tip
    You can also execute `run` with `-u` option, to upload before resuming the run the command,
    In that case `polyaxon upload is not necessary`

    ```bash
    $ polyaoxn run -f polyaxonfile.yml -u
    ```

In order to customize the resources of our jobs we need to introduce a new section [environment]().

Let's create a new `polyaxonfile_resources.yml` override file that will allow us to achieve that

```yaml
---<commit_msg>Add restart command to experimentation workflow<commit_after>Assuming that you have already a [project](projects) created and initialized,
and you uploaded your code consisting of a single file `train.py` that accepts 2 parameters

  * learning rate `lr`
  * batch size `batch_size`

## Updating the polyaxonfile.yml

The first thing that you need to do is to update the default `polyaxonfile.yml` that was generated.

We will start first by adding the `run` section. For example if the code requires `tensorflow` and `sklearn`,
the polyaxonfile.yml `run` section could look something like this

```yaml
---
...

run:
  image: tensorflow/tensorflow:1.4.1-py3
  steps:
    - pip install scikit-learn
  cmd: python3 train.py --batch-size={{ batch_size }} --lr={{ lr }}
```

If the code requires many python dependencies, Polyaxon provides an elegant way to install these requirements,
instead of specifying every single library in the `steps` part of the `run` section,
we can create a requirements file with the name `polyaxon_requirements.txt` and just create one command in the steps `pip install -r polyaxon_requirements.txt`
and Polyaxon will automatically detect it and install the requirements.

Polyaxon also allows you to specify a `polyaxon_setup.sh` file, and a command to execute that file `./polyaxon_setup.sh`.

Let's create a `polyaxon_requirements.txt` to demonstrate this process.

```bash
$ vi polyaxon_requirements.txt
...
```

And modify the polyaxonfile.yml to install our requirements


```yaml
---
version: 1

project:
  name: mnist

declarations:
  lr: 0.01
  batch_size: 128

run:
  image: tensorflow/tensorflow:1.4.1-py3
  steps:
    - pip install -r polyaxon_requirements.txt
  cmd: python3 train.py --batch-size={{ batch_size }} --lr={{ lr }}
```

!!! Tip
    The declarations section was not completely necessary,
    we could have also just passed the value directly `--batch-size=128 --lr=0.01`

    For more information please visite the [declarations section](/polyaxonfile_specification/sections#declarations) reference.

!!! info "More details"
    For more details about the `run section` check the [run section reference](/polyaxonfile_specification/sections#run)


To make sure that the polyaxon file is valid, you can run the following command,

```bash
$ polyaxon check -f polyaxonfile.yml -m

Polyaxonfile valid

This file has one independent experiment.
```

This command validate the polyaxon file, and the option `-m` returns the matrix space,
in this case we have only one independent experiment. This option is important when we want
to check a polyaxonfile with a matrix section having an [experiment group](experiment_groups)

## Running an experiment

To run this polyaxonfile execute

```bash
$ polyaxon run

Creating an independent experiment.

Experiment was created.
```

!!! info "More details"
    For more details about this command please run `polyaxon run --help`,
    or check the [command reference](/polyaxon_cli/commands/run)

## Checking the experiments of a project

We can check that the project has now an independent experiment created.
For that we can use Polyaxon dashboard or Polyaxon CLI,

```bash
$ polyaxon project experiments

Experiments for project `admin/mnist`.


Navigation:

-----  -
count  1
-----  -

Experiments:

  sequence  unique_name       user    project_name    experiment_group_name    last_status    created_at         is_clone      num_jobs  finished_at    started_at
----------  ----------------  ------  --------------  -----------------------  -------------  -----------------  ----------  ----------  -------------  ------------
        1  admin.mnist.1      admin   admin.mnist                              Created        a few seconds ago  False                0

```

You should notice that the column experiment group is empty,
which means that this experiment is running independently of a group.


## Running the experiment with different parameters

After running this experiment, we can imagine that you were not satisfied with the result and
that you wanted to try another learning rate `0.5`.
If you hardcoded the value and passed it directly `--lr=0.01`, you would be obliged to updated the polyaxonfile.yml.
Of course we can do that also now, but since we declared the `lr` in the declarations sections,
we can create instead another file `polyaxonfile_override.yml` to override just that section:

!!! Tip "You can call your polyaxonfiles anything you want"
    By default polyaxon commands look for files called `polyaxonfile.yml`.
    If you call your files differently or want to override values, you need to use the option `-f`

```bash
$ vi polyaxonfile_override.yml
```

And past the new declarations section.

```yaml
---
version: 1

declarations:
  lr: 0.5
```

and run again

```bash
$ polyaxon run -f polyaxonfile.yml -f polyaxonfile_override.yml

Creating an independent experiment.

Experiment was created.
```

You can repeat this process as much as you wish until you are satisfied with the performance of your model.
Polyaxon will create a new experiment for you each time. However, if the space of values you want to try is large,
modifying the values manually and executing `polyaxon run` is not optimal,
what you can do instead is create an [experiment group](experiment_groups).

## Stopping an experiment

To stop experiment 2 for example, run

```bash
$ polyaxon experiment -xp 2 stop
```

!!! caution
    There's another command `delete`, the difference between `stop` and `delete`,
    is that delete will remove the experiment completely from your database.

## Restarting an experiment

To restart experiment 2 for example, run

```bash
$ polyaxon experiment -xp 2 restart
```

It will create a new experiment based on experiment 2 last saved checked point.

## Distributed Runs

!!! caution
    This section is oriented for users who want to run experiments with multiple jobs
    based on Tensorflow.

After modifying our `train.py` we want to run the experiment with 1 master 4 workers and 1 parameter server.
We also want to customize the resources of the each node.

First let's upload the new version of the code

```bash
$ polyaxon upload
```

!!! tip
    You can also execute `run` with `-u` option, to upload before resuming the run the command,
    In that case `polyaxon upload is not necessary`

    ```bash
    $ polyaoxn run -f polyaxonfile.yml -u
    ```

In order to customize the resources of our jobs we need to introduce a new section [environment]().

Let's create a new `polyaxonfile_resources.yml` override file that will allow us to achieve that

```yaml
---
{'fraction_non_alphanumeric': 0.09160187822338542, 'fraction_numerical': 0.006542991301670387, 'mean_word_length': 3.3847451906851163, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1775361', 'n_tokens_mistral': 3673, 'n_tokens_neox': 3387, 'n_words': 1683}