Merge pull request #723 from jeffriley/docsfixes

Changes to online documentation for issues #695 and #680

Author: jeffriley

docs/online-docs/pages/User guide/Program options/program-options-ranges.rst

@@ -32,6 +32,10 @@ where `range-specifier` is defined as:
         `start` and `increment` must be the same data type as option-name. |br|
         `count` must be a positive integer value.
 
+There should be no spaces inside the brackets ([]). Spaces on the command line are interpreted as argument delimiters
+by the shell parser before passing the command-line arguments to the COMPAS executable, so if spaces are present inside
+the brackets the shell parser breaks the range specification into multiple command-line arguments.
+
 To specify a range of values for the ``--metallicity`` option, a user, if running COMPAS from the command line
 and with no grid file, would type any of the following::
 
@@ -51,3 +55,9 @@ type::
     ./COMPAS --metallicity [0.0001,10,0.0013] --common-envelope-alpha [0.1,5,0.2]
 
 and COMPAS would evolve a grid of 50 binaries using the 10 metallicity values and 5 common envelope alpha values.
+
+Note that when a range is, or ranges are, specified on the command line, the ``--number-of-systems`` command-line option is ignored.
+This is to avoid multiple systems with identical initial values being evolved.  Ranges and sets can be mixed with grid files, and
+in that case ranges and sets specified on the command line will be played out for each grid file line.
+
+   

docs/online-docs/pages/User guide/Program options/program-options-sets.rst

@@ -28,6 +28,10 @@ where `set-specifier` is defined as:
 
         `set-identifier` is mandatory for `set-specifier`. |br|
         `value`:sub:`i` must be the same data type as `option-name`.
+        
+There should be no spaces inside the brackets ([]). Spaces on the command line are interpreted as argument delimiters
+by the shell parser before passing the command-line arguments to the COMPAS executable, so if spaces are present inside
+the brackets the shell parser breaks the set specification into multiple command-line arguments.
 
 Valid values for boolean options are {1|0, TRUE|FALSE, YES|NO, ON|OFF}, and all set values must be of
 the same type (i.e. all 1|0, or all YES|NO etc.).
@@ -44,3 +48,9 @@ command line and with no grid file, would type any of the following::
 
 In each of the examples above the user has specified, by the use of the `set-specifier`, that three binary stars
 should be evolved, using the eccentricity distributions ’THERMALISED’, ’FIXED’, and ’FLAT’.
+
+Note that when a set is, or sets are, specified on the command line, the ``--number-of-systems`` command-line option is ignored.
+This is to avoid multiple systems with identical initial values being evolved.  Ranges and sets can be mixed with grid files, and
+in that case ranges and sets specified on the command line will be played out for each grid file line.
+
+   

docs/online-docs/pages/User guide/Running COMPAS/running-via-docker-running.rst

@@ -13,9 +13,11 @@ To run COMPAS via a ``pythonSubmit.py`` file, type::
     docker run                                                  \
         --rm                                                    \
         -it                                                     \
+        -v $(pwd)/compas-input:/app/COMPAS/config               \
         -v $(pwd)/compas-logs:/app/COMPAS/logs                  \
         -v $(pwd)/pythonSubmit.py:/app/starts/pythonSubmit.py   \
         -e COMPAS_EXECUTABLE_PATH=/app/COMPAS/bin/COMPAS        \
+        -e COMPAS_INPUT_DIR_PATH=/app/COMPAS/config             \
         -e COMPAS_LOGS_OUTPUT_DIR_PATH=/app/COMPAS/logs         \
         teamcompas/compas                                       \
         python3 /app/starts/pythonSubmit.py                     
@@ -35,8 +37,9 @@ short for [-i and -t] - provides an interactive terminal\ [#f2]_.
 **-v <path-on-host>:<path-in-container>** |br|
 mount ``<path-on-host>`` to ``<path-in-container>``\ [#f3]_. |br|
 
-This time we not only want to get the output from COMPAS on the host machine, we also want to supply a ``pythonSubmit.py`` to the 
-container from the host machine.
+This time we not only want to read the COMPAS input files (i.e. grid file and/or logfile-definitions file) on the
+host from the container, and get the output from COMPAS in the container onto the host machine, we also want to 
+supply a ``pythonSubmit.py`` to the container from the host machine.
 
 **-e VAR_NAME=value** |br|
 set the environment variable ``VAR_VAME`` to `value`\ [#f4]_.
@@ -53,13 +56,14 @@ via the command line
 
 To run the COMPAS executable from the command line (i.e. without ``pythonSubmit.py``), type::
 
-    docker run                                  \
-        --rm                                    \
-        -it                                     \
-        -v $(pwd)/compas-logs:/app/COMPAS/logs  \
-        teamcompas/compas                       \
-        bin/COMPAS                              \
-        --number-of-systems=5                  \
+    docker run                                      \
+        --rm                                        \
+        -it                                         \
+        -v $(pwd)/compas-input:/app/COMPAS/config   \
+        -v $(pwd)/compas-logs:/app/COMPAS/logs      \
+        teamcompas/compas                           \
+        bin/COMPAS                                  \
+        --number-of-systems=5                       \
         --output-path=/app/COMPAS/logs
 
 
@@ -77,7 +81,9 @@ short for [-i and -t] - provides an interactive terminal\ [#f2]_.
 **-v <path-on-host>:<path-in-container>** |br|
 mount ``<path-on-host>`` to ``<path-in-container>``\ [#f3]_. |br|
 
-In this instance, make it so `$(pwd)/compas-logs` on my machine is the same as `/app/COMPAS/logs` inside the container.
+In this instance, make it so |br|
+   `$(pwd)/compas-input` on my machine is the same as `/app/COMPAS/config` inside the container. |br|
+   `$(pwd)/compas-logs` on my machine is the same as `/app/COMPAS/logs` inside the container.
 
 **teamcompas/compas** |br|
 the image to run.
@@ -102,7 +108,7 @@ environment, and are non-breaking changes (i.e. benign to other environments).
 ``COMPAS_EXECUTABLE_PATH`` specifies where ``pythonSubmit.py`` looks for the COMPAS executable. This override exists purely for 
 ease-of-use from the command line.
 
-`COMPAS_LOGS_OUTPUT_DIR_PATH` specifies where COMPAS output log filess are created. The override exists because the mounted directory 
+`COMPAS_LOGS_OUTPUT_DIR_PATH` specifies where COMPAS output log files are created. The override exists because the mounted directory 
 (option `-v`) is created before COMPAS runs. COMPAS sees that the directory where it's supposed to put logs already exists, so it 
 creates a different (i.e. non-mapped) directory for the output log files.
 
@@ -143,3 +149,4 @@ to get the container id of interest, then type::
 .. [#f5] https://docs.docker.com/engine/reference/run/
 .. [#f6] https://docs.docker.com/engine/reference/run/#detached--d
 
+