Singularity wrappers summary reworked.

docs.it4i/software/tools/singularity-it4i.md

 # Singularity on IT4Innovations
 
-On clusters, we have different versions of singularity images of operating systems. Below you can see the available operating systems singularity images.
-
-Our bootstrap for create image, wrappers, features are [here](https://code.it4i.cz/sccs/it4i-singularity).
+On our clusters, the singularity images of main linux distributions are prepared. List of available singularity images (05.04.2018):
 
 ```console
    Salomon                 Anselm
@@ -10,29 +8,25 @@ Our bootstrap for create image, wrappers, features are [here](https://code.it4i.
       │   ├── 6.9            │   ├── 6.9
       │   ├── 6.9-MIC        │   ├── 6.9-GPU
       │   ├── 7.4            │   ├── 7.4
-      │   └── 7.4-MIC        │   └── 7.4-GPU
+      │   └── 7.4-MIC        │   └── 7.4-GPU
       ├── Debian             ├── Debian
       │   └── 8.0            │   ├── 8.0
-      └── Ubuntu             │   └── 8.0-GPU
+      └── Ubuntu             │   └── 8.0-GPU
           └── 16.04          └── Ubuntu
                                  ├── 16.04
                                  └── 16.04-GPU
 ```
 
-For current information on available singularity images, refer to the `ml av` and see statement the `OS`
-
-## Available Operating Systems Images
+Current information about available singularity images can be obtained by the `ml av` command. The Images are listed in the `OS` section.
 
-* CentOS
-* Debian
-* Ubuntu
+The bootstrap scripts, wrappers, features, etc. are located [here](https://code.it4i.cz/sccs/it4i-singularity).
 
 !!! note
-    We support graphics cards for Anselm singularity image and support Intel Xeon Phi cards on Salomon singularity image. (OS/Version[none|-GPU|-MIC])
+    The images with graphic card support are marked as **-GPU** and images with Intel Xeon Phi support are marked as **-MIC**
 
-## IT4Innovations Wrappers
+## IT4Innovations Singularity Wrappers
 
-To use our singularity images we prepared special wrappers:
+For better user experience with singularity containers we prepared several wrappers:
 
 * image-exec
 * image-mpi
@@ -40,9 +34,41 @@ To use our singularity images we prepared special wrappers:
 * image-shell
 * image-update
 
-The latest version of the scripts is [here](https://code.it4i.cz/sccs/it4i-singularity/tree/master/bin)
+Listed wrappers helps you to use prepared singularity images loaded as modules. You can easily load singularity image like any other module on the cluster
+by `ml OS/version` command. After first module load, the prepared image is copied into your home folder and is prepared for use. When you load the module 
+next time, the version of image is checked and image update (if exists) is offered. Then you can update your copy of image by the `image-update` command.
+
+!!! warning
+    With image update, all user changes to the image will be overridden.
+    
+The runscript inside the singularity image can be run by the `image-run` command. This command automatically mounts the `/scratch` and `/apps` storage and
+invoke the image as writable, so user changes can be made.
+
+Very similar to `image-run` is the `image-exec` command. The only difference is that `image-exec` runs user-defined command instead of the runscript. In this case,
+the command to be run is specified as a parameter.
+
+For development is very useful to use interactive shell inside the singularity container. In this interactive shell you can make any changes to the image you want, 
+but be aware that you can not use the `sudo` privileged commands directly on the cluster. To invoke interactive shell easily just use the `image-shell` command.
+
+Another useful feature of the singularity is direct support of OpenMPI. For proper MPI function, you have to install the same version of OpenMPI as you use on cluster inside the
+image. OpenMPI/2.1.1 is installed in prepared images. The MPI must be started outside of the container. The easiest way to start the MPI is to use the `image-mpi` command. 
+This command has the same parameters as the `mpirun`. Thanks to that, there is no difference between running normal MPI application and MPI application in singularity container.
+
+## Examples
+
+In next examples, we will be use Singularity images on IT4Innovations clusters.
+
+### Load Image
+
+```console
+$ ml CentOS/6.9
+Your image of CentOS/6.9 is at location: /home/login/.singularity/images/CentOS-6.9_20180220133305.img
+```
+
+!!! tip
+    First usage module with singularity image, copy singularity image from /apps/all/OS/... to your /home (.singularity/images)
 
-**image-exec**
+### image-exec
 
 Open the image and run the command inside the image.
 
@@ -53,15 +79,15 @@ $ image-exec cat /etc/centos-release
 CentOS Linux release 7.3.1708 (Core)
 ```
 
-**image-mpi**
+### image-mpi
 
 MPI wrapper. More in the chapter [Examples MPI](#mpi).
 
-**image-run**
+### image-run
 
 Run the subscript inside image.
 
-**image-shell**
+### image-shell
 
 Start the shell inside image.
 
@@ -73,7 +99,7 @@ Singularity: Invoking an interactive shell within container...
 Singularity CentOS-7.3_20180220104046.img:~>
 ```
 
-**image-update**
+### Update image
 
 If a new image (version) exists, informs the user and offers an update image.
 
@@ -93,20 +119,6 @@ total size is 2.71G  speedup is 1.00
 New version is ready. (/home/login/.singularity/images/CentOS-6.9_20180220092823.img)
 ```
 
-## Examples
-
-In next examples, we will be use Singularity images on IT4Innovations clusters.
-
-### Load Image
-
-```console
-$ ml CentOS/6.9
-Your image of CentOS/6.9 is at location: /home/login/.singularity/images/CentOS-6.9_20180220133305.img
-```
-
-!!! tip
-    First usage module with singularity image, copy singularity image from /apps/all/OS/... to your /home (.singularity/images)
-
 ### Intel Xeon Phi Cards - MIC
 
 For example submit job `qsub -A PROJECT -q qprod -l select=1:mpiprocs=24:accelerator=true -I`