first draft of README

README.rst

+MPSD Software installation
+==========================
+
+.. 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>`__.
+
+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
+the same software environment, for example to debug a problem.
+
+Note that this tool is under development, and the recommended way to install and
+use as well as the user interface may change. This document will be kept
+up-to-date in any case.
+
+Quick start
+-----------
+
+To install, for example, the ``foss2022a-serial`` toolchain:
+
+1. Clone this repository to the place where you want to install the software environment::
+
+     git clone https://gitlab.gwdg.de/mpsd-cs/mpsd-software-environments.git
+
+2. ``cd mpsd-software-environments``
+
+3. Execute the script to install the toolchain::
+
+     $> ./mpsd-software.py install dev-23a --toolchain foss2022a-serial
+
+   This will take some time.
+
+4. To see the installation status, and the required ``module use`` command line
+   to activate the created modules, try the ``status`` command::
+
+     $> ./mpsd-software status dev-23a
+
+     Installed toolchains (dev-23a):
+
+     - cascadelake
+         foss2022a-serial
+         [module use /home/fangohr/git/mpsd-software-environments/dev-23a/cascadelake/lmod/Core]
+
+
+
+Documentation
+-------------
+
+Package sets and toolchains
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Package sets are a combination of particular versions of multiple software
+  packages (such as anaconda3, or gcc and fftw). In the way the SSU
+  Computational Science provides software on the MPSD HPC cluster and for the
+  Octopus continuous integration services, these package sets are compiled
+  together (using Spack).
+
+- Toolchains are a particular type of package sets:
+
+  - the choice of software packages (typically a compiler and scientific
+    computing libraries) and their versions follows the Easybuild toolchains
+    (such as the `FOSS toolchains
+    <https://docs.easybuild.io/common-toolchains/#common_toolchains_foss>`__).
+
+  - all packages grouped together in a toolchain can be loaded together using
+    the `module load` command.
+
+    Example: the `foss2022a-serial` tool chain provides (in spack notation)::
+
+      - gcc@11.3.0
+      - binutils@2.38+headers+ld
+      - fftw@3.3.10+openmp~~mpi
+      - openblas@0.3.20
+
+   - in addition to the Easybuild-driven choice of packages, there are
+     additional packages included in each package which support the build of
+     Octopus within these toolchains. For `foss2022a-serial` these packages
+     include::
+
+      - libxc@5.2.3       # octopus-dependencies:
+      - gsl@2.7.1
+      - sparskit@develop  # 2021.06.01
+      - nlopt@2.7.0
+      - libgd@2.2.4       # 2.3.1
+      - libvdwxc@0.4.0~~mpi
+      - nfft@3.2.4
+      - berkeleygw@2.1~~mpi~scalapack
+      - python@3.9.5
+      - cgal@5.0.3  # 5.2
+      - hdf5@1.12.2~mpi
+      - etsf-io@1.0.4
+
+
+MPSD software releases
+~~~~~~~~~~~~~~~~~~~~~~
+
+As `explained in the MPSD HPC documentation
+<https://computational-science.mpsd.mpg.de/docs/mpsd-hpc.html#software>`__, we
+label software releases available on the HPC using a naming scheme of the year
+(such as ``23``) and a letter starting from ``a``. There is an exception that
+the first available software version is ``dev-23a`` (starting with ``dev-`` to
+indicate this was a development prototype).
+
+At the moment (June 2023), there is only one release (that is ``dev-23a``).
+
+For each MPSD software release, multiple toolchains and package sets are available::
+
+    $> ./mpsd-software.py available dev-23a
+
+    MPSD software release dev-23a, AVAILABLE for installation are
+    Toolchains: 
+        foss2021a-cuda-mpi
+        foss2021a-mpi
+        foss2021a-serial
+        foss2022a-cuda-mpi
+        foss2022a-mpi
+        foss2022a-serial
+    Package sets:
+        global (octopus@12.1, octopus@12.1)
+        global_generic (anaconda3@2022.10)
+
+
+Prerequisites
+~~~~~~~~~~~~~
+
+What needs to be installed for the installation to succeed?
+
+Probably an ongoing topic of work. We know the following tools need to be available:
+
+- XXX TODO, add, requirements in container from CI might be best. Things like rsync, git, buildtools, Linux-headers,
+
+
+
+
+