Update Trial's doc and move HowToDebug to Tutorial (#887)

* Add output_dir in trial's doc
microsoft · Apr 1, 2019 · 8fa633c · 8fa633c
1 parent dbace00
commit 8fa633c
Show file tree

Hide file tree

Showing 3 changed files with 31 additions and 3 deletions.
diff --git a/docs/en_US/Contribution.rst b/docs/en_US/Contribution.rst
@@ -4,5 +4,4 @@ Contribute to NNI
 
 ..  toctree::
     Development Setup<SetupNNIDeveloperEnvironment>
-    Contribution Guide<CONTRIBUTING>
-    Debug HowTo<HowToDebug>
+    Contribution Guide<CONTRIBUTING>
diff --git a/docs/en_US/Trials.md b/docs/en_US/Trials.md
@@ -125,6 +125,34 @@ In the YAML configure file, you need to set *useAnnotation* to true to enable NN
 useAnnotation: true
 ```
 
+
+## Where are my trials?
+
+### Local Mode
+
+In NNI, every trial has a dedicated directory for them to output their own data. In each trial, an environment variable called `NNI_OUTPUT_DIR` is exported. Under this directory, you could find each trial's code, data and other possible log. In addition, each trial's log (including stdout) will be re-directed to a file named `trial.log` under that directory.
+
+If NNI Annotation is used, trial's converted code is in another temporary directory. You can check that in a file named `run.sh` under the directory indicated by `NNI_OUTPUT_DIR`. The second line (i.e., the `cd` command) of this file will change directory to the actual directory where code is located. Below is an example of `run.sh`:
+```shell
+#!/bin/bash
+cd /tmp/user_name/nni/annotation/tmpzj0h72x6 #This is the actual directory
+export NNI_PLATFORM=local
+export NNI_SYS_DIR=/home/user_name/nni/experiments/$experiment_id$/trials/$trial_id$
+export NNI_TRIAL_JOB_ID=nrbb2
+export NNI_OUTPUT_DIR=/home/user_name/nni/experiments/$eperiment_id$/trials/$trial_id$
+export NNI_TRIAL_SEQ_ID=1
+export MULTI_PHASE=false
+export CUDA_VISIBLE_DEVICES=
+eval python3 mnist.py 2>/home/user_name/nni/experiments/$experiment_id$/trials/$trial_id$/stderr
+echo $? `date +%s000` >/home/user_name/nni/experiments/$experiment_id$/trials/$trial_id$/.nni/state
+```
+
+### Other Modes
+
+When runing trials on other platform like remote machine or PAI, the environment variable `NNI_OUTPUT_DIR` only refers to the output directory of the trial, while trial code and `run.sh` might not be there. However, the `trial.log` will be transmitted back to local machine in trial's directory, which defaults to `~/nni/experiments/$experiment_id$/trials/$trial_id$/`
+
+For more information, please refer to [HowToDebug](HowToDebug.md)
+
 <a name="more-examples"></a>
 ## More Trial Examples
 

diff --git a/docs/en_US/Tutorials.rst b/docs/en_US/Tutorials.rst
@@ -12,4 +12,5 @@ Tutorials
     WebUI
     Training Platform<training_services>
     How to use docker<HowToUseDocker>
-    advanced
+    advanced
+    Debug HowTo<HowToDebug>