docs: include a README with basic instructions

README.md

+# Parallel Coupling Infrastructure for AWI-ESM 2.2
+
+This project contains source code and infrastructure settings to enable a
+coupled run consisting of multiple models.
+
+## Getting a copy
+
+The project can be downloaded via git. Several preliminary steps may be needed.
+
+1. On ollie, you need:
+```
+module load git
+```
+On mistral, the git version is already new enough.
+
+2. Since there are several files included which use the [git "large file storage"](https://git-lfs.github.com) (`git lfs`), you might need to initialize that first. Run the following to do that:
+```shell
+git lfs install
+```
+3. It is probably a good idea to store your password, as otherwise you will need to enter it over and over until everything finishes downloading. You have two options:
+
+**A**. Use a [`.netrc` file](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html). In your home directory, create a file with permissions 600:
+```shell
+# Creates an empty file if not already there:
+touch ${HOME}/.netrc
+# Gives only you read/write permission, everyone else has nothing
+chmod 600 ${HOME}/.netrc
+```
+In this file, you can place your login credentials for *both* gitlab.awi.de and gitlab.dkrz.de:
+```
+machine gitlab.awi.de login pgierz password <PUT YOUR PASSWORD>
+machine gitlab.dkrz.de login a270077 password <PUT YOUR PASSWORD>
+```
+The example above has Paul's account details, but of course you should use your own.
+
+**B.** Cache [your `git` credentials](https://git-scm.com/docs/git-credential-cache). In this example, we save the password for 1 hour for each account you use:
+```
+git config --global credential.helper 'cache --timeout=3600'
+```
+
+4. Now you can download everything. We need to extend the standard clone command to ensure you download actual binary files rather than just checksums
+and pointers. Furthermore, some parts are within git submodules, particularly the climate model code and boundary conditions, we need to add options to get that as well:
+
+```shell
+git lfs clone --depth 1 --recurse-submodules https://gitlab.awi.de/paleodyn/awiesm-2.2-dev/parallel-coupling.git
+```
+
+Note that the `lfs` portion of `git lfs clone` **could** also just be `git
+clone`. Including `lfs` allows the program to download the large files in
+parallel, thus significantly decreasing the time you need to get your first
+copy. Newer versions of git [do that by
+default](https://stackoverflow.com/questions/48392440/git-lfs-clone-vs-git-clone).
+
+If you run into any problems, there are likely permissions errors. Please let
+Paul know and he will help to fix it.
+
+5. Install a virtual environment
+
+This project works best if you install a virtual environment. To do that, run the following in your shell to set up Python:
+
+```shell
+python -m venv .venv
+```
+
+Next you also need to set up [direnv](https://direnv.net). That will allow for the automatic activation of the virtual environment whenever you change into the directory. A copy of direnv is available on mistral on Paul's account:
+
+```
+PATH=${PATH}:/pf/a/a270077/.local/bin/direnv
+```
+
+You may also need to adapt your shell login scripts. Please see the readme in the link above for that.
+
+
+6. [Install the esm-tools](https://esm-tools.readthedocs.io/en/latest/installation.html#installing). This will be used to compile your model and control your runs. A copy is given to you in the `./software` folder.
+
+For each part in `./software`, go to the folder and run `pip install .` within your virtual environment. That will ensure that you use the same versions for your jobs.
+
+7. Compile your model. To do that, go into the `./model_codes/` folder and run `esm_master comp-awiesm-2.2`
+```
+cd ./model_codes
+esm_master comp-awiesm-2.2
+```
+
+
+## Updating
+
+You can update the project by running the following in the top level:
+```shell
+git pull
+```
+
+This should pull both the main files, as well as any boundary conditions that
+may have been updated.