home.md

@@ -4,7 +4,7 @@
 
 HRU delin used to work with grass6 only. This version brings compatibility with grass7 (and looses compatibility with grass6).
 
-## Differences with HRU delin v5
+# Differences with HRU delin v5
 
 * Grass7 compatibility
 * Parallelized process in step2, step3 and step4
@@ -17,9 +17,9 @@ HRU delin used to work with grass6 only. This version brings compatibility with
 * No more system calls (to awk, grep, sed...) -> code is now portable to Windows
 * Use pipes between grass tools to avoid some hard disk access (avoid writing some intermediate files)
 
-## Install
+# Install
 
-### Dependencies
+## Dependencies
 
 You'll need some Python3 modules to be able to run HRU delin.
 
@@ -37,7 +37,7 @@ If you don't have administrator rights but still have pip3 installed:
 pip3 install --user pandas dbf tqdm
 ```
 
-### HRU delin
+## HRU delin
 
 Get the release archive and extract it somewhere. Then make sure the `bin` directory is in your `PATH` environment variable. Here is an example procedure:
 ``` bash
@@ -45,12 +45,72 @@ Get the release archive and extract it somewhere. Then make sure the `bin` direc
 cd
 # extract the archive (adapt the path to the archive)
 tar xvf Downloads/hru-delin-v7.tar.bz2
-cd hru-delin
 # add bin directory to your PATH variable
+cd hru-delin
 echo 'export PATH='`pwd`/bin':$PATH' >> ~/.bashrc
 ```
-That's is, now every **new** terminal will be able to run HRU delin. To check if everything is fine, open a new terminal and type
+That's it! From now on, every **new** terminal will be able to run HRU delin. To check if everything is fine, open a new terminal and type
 ``` bash
 which hru-delin_step1.sh
 ```
-It should display something like `/home/myname/hru-delin/bin/hru-delin_step1.sh`. If not, there's something wrong.
\ No newline at end of file
+It should display something like `/home/myname/hru-delin/bin/hru-delin_step1.sh`. If not, there's something wrong.
+
+# Usage
+
+## Basic
+
+Create a config file (.cfg) the same way you did with HRU delin v5 and previous versions. You can name it as you wish.
+
+If you are in the same directory than the config file and its name is my_hrudelin_project.cfg, you can run:
+``` bash
+hru-delin_step1.sh my_hrudelin_project.cfg
+hru-delin_step2.sh my_hrudelin_project.cfg
+hru-delin_step3.sh my_hrudelin_project.cfg
+hru-delin_step4.sh my_hrudelin_project.cfg
+```
+to launch each HRU delin step.
+
+You can also do it with:
+``` bash
+hru-delin_all-steps.sh my_hrudelin_project.cfg
+```
+
+If you name your config file `hrudelin_config.cfg`, and you're placed in the same directory, you can call HRU delin scripts without arguments:
+``` bash
+hru-delin_all-steps.sh
+```
+
+## Advanced
+
+### Working directory
+
+You don't need to be in the same directory than the config file, so you can run things like:
+``` bash
+hru-delin_all-steps.sh ./projects/hydro/my_hrudelin_project.cfg
+```
+and HRU delin will run just fine, producing outputs near the config file.
+
+### Number of parallel process
+
+You can set the number of parallel process with `-p` option in all launch scripts. HRU delin will use the number of cores by default. You might want to use a smaller number to avoid using all your computer's resources.
+
+Examples:
+``` bash
+# run all steps with 2 parallel processes
+hru-delin_all-steps.sh my_hrudelin_project.cfg -p 2
+# run step4 with 8 parallel processes
+hru-delin_step4.sh my_hrudelin_project.cfg -p 8
+```
+
+### Multiple executions
+
+As HRU delin builds a specific grass environment each time it is launched, you can run it multiple times simultaneously. Each HRU delin instance won't mess with the others.
+
+For example, let's consider you have 8 cores and you want HRU delin to only use half of your processor's resources:
+``` bash
+# in one terminal
+hru-delin_all-steps.sh projects/rhone/rhone.cfg -p 2
+# and in another one
+hru-delin_all-steps.sh projects/danube/danube.cfg -p 2
+```
+This way you'll have one HRU delin using 2 cores and another one using 2 cores as well.
\ No newline at end of file