Merge branch 'improve-readme' into 'main'

Improve readme

See merge request !76

README.rst

@@ -4,8 +4,8 @@ MPSD Software manager
 .. contents::
 
 This repository provides the ``mpsd-software`` tool which is used to install
-package sets and toolchains on the `MPSD HPC cluster
-<https://computational-science.mpsd.mpg.de/docs/mpsd-hpc.html>`__.
+package sets and toolchains on the
+`MPSD HPC cluster <https://computational-science.mpsd.mpg.de/docs/mpsd-hpc.html>`__.
 
 It can also be used to install the software on other machines, such as Linux
 laptops and desktops. This can be useful to work - on a local machine - with
@@ -28,21 +28,23 @@ To install, for example, the ``foss2022a-serial`` toolchain:
 
 
 2. Navigate to the location in your file system where you would like to store
-   the compiled software. (Once compiled, the location cannot be changed.) For
-   example::
+   your "MPSD software instance" that contains the compiled software. Once
+   compiled, the location cannot be changed. For example::
 
      $ cd /home/user/mpsd-software
 
+   Future calls of the `mpsd-software` command need to be executed from this
+   "mpsd-software-root" directory.
 
 .. comment:
     3. Initiate the installation at this location using::
-    
+
          $ mpsd-software init
-    
+
        (This creates a hidden file ``.mpsd-software-root`` to tag the location for
        as the root of the installation. All compiled files, logs etc are written in
        or below this subdirectory.)
-    
+
 3. From the same directory, run the command to install the ``foss2022a-serial``
    toolchain::
 
@@ -61,6 +63,17 @@ To install, for example, the ``foss2022a-serial`` toolchain:
          foss2022a-serial
          [module use /home/user/mpsd-software/dev-23a/cascadelake/lmod/Core]
 
+5. To compile Octopus, source the provided configure script, for example ``foss2022a-serial-config.sh``, as
+   `explained here <https://computational-science.mpsd.mpg.de/docs/mpsd-hpc.html#loading-a-toolchain-to-compile-octopus>`__).
+   The configure scripts are located in ``dev-23a/spack-environments/octopus``::
+
+     $ ls -1 dev-23a/spack-environments/octopus
+
+     foss2021a-cuda-mpi-config.sh
+     foss2021a-mpi-config.sh
+     foss2021a-serial-config.sh
+     foss2022a-cuda-mpi-config.sh
+     foss2022a-mpi-config.sh
 
 
 Documentation
@@ -163,6 +176,8 @@ The ``mpsd-software-manager`` python package.
 
 - The installation is only expected to work for x86 architectures at the moment.
 
+- The installation is only expected to work on Linux at the moment (i.e. not on OSX).
+
 Requirements for particular toolchains and package sets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -181,4 +196,56 @@ Octopus) using the ``foss2022a-serial`` toolchain.
 
 
 
+Frequently asked questions
+--------------------------
+
+- Can I install the ``mpsd-software-manager`` package in a python virtual environment?
+
+  Yes. ``pipx`` is probably more convenient, but you can create your own Pyton
+  virtual environment and install the ``mpsd-software-manager`` in that as a
+  regular python package::
+
+    python3 -m venv venv
+    . venv/bin/activate
+    pip install git+https://gitlab.gwdg.de/mpsd-cs/mpsd-software-manager
+
+  You just need to activate that python virtual environment before being able to
+  use the tool.
+
+- Does the command write anything outside the mpsd-software-root directory?
+
+  No. All changes to disk take place in and below the mpsd-software-root
+  directory (which is the one in which the ``mpsd-software`` command is called).
+
+- How can I uninstall the mpsd-software?
+
+  For now, the easiest is to delete the ``mpsd-software-root`` directory. You
+  can probably delete just a release subdirectory (such as ``dev-23a``) if you
+  have multiple release subdirectories installed and you only want to delete
+  one. (Untested.)
+
+- How long does the compilation take?
+
+  This depends on the hardware. A few hours are typical per toolchain. If a
+  second toolchain is compiled in the same MPSD software instance is likely to
+  be faster, in particular if the same compiler is used (and thus the compiler
+  does not need to be re-compiled for the second toolchain).
+
+- How much disk storage do I need?
+
+  A toolchain needs of the order of 5GB on disk. The second or third toolchain
+  (in the same MPSD software instance) will use less additional space, as
+  libraries and tools are re-used where possible.
+
+- Can I have more than one MPSD software instance?
+
+  Yes.
+
+  We call "MPSD software instance" all the compiled software that is stored
+  in and below a "mpsd-software-root" directory (see instructions above).
+
+  It is possible to install multiple MPSD software instances on the same
+  computer (just in different (not nested) directories. This makes it possible
+  to experiment with toolchains etc.
+