Documentation

.gitlab-ci.yml

-# IMPORTANT: running the pipeline for testing, keep in mind, re-building an existing package version fails! For testing, build for an old tag which does not have a package in the registry, yet. Delete the package after testing.
+# IMPORTANT: running the pipeline for testing, keep in mind, re-building an
+# existing package version fails! For testing, build for an old tag which does
+# not have a package in the registry, yet. Delete the package after testing.
 
 build-package:
   stage: deploy

README.md

@@ -111,6 +111,56 @@ output files ...), here are some things to consider:
 - if running on CPUs without GPU, avoid the `lii` nodes (`--exclude=lii[02-28]`)
 
 
+## Custom AF2 pipeline
+
+`run_af2` executes the default AlphaFold 2 pipeline. That is, in the end a
+script [`run_alphafold.py`](
+https://github.com/deepmind/alphafold/blob/main/run_alphafold.py) is run. For
+some studies, you may want to go by a modified version of `run_alphafold.py`.
+While `run_af2` is based on containerised software in its backyard, injecting
+your custom script inside the Singularity container is not terribly complicated.
+In the shell, you want to run your command in, simply create an environment
+variable `SINGULARITY_BINDPATH` with the mapping of your script to the original
+script inside the container:
+
+```terminal
+$ export SINGULARITY_BINDPATH="/PATH/TO/SCRIPT/run_alphafold.py:/app/alphafold/run_alphafold.py""
+```
+
+Where `/PATH/TO/SCRIPT/run_alphafold.py` points to your modified
+`run_alphafold.py`. After that, just run `run_af2` as described in
+[Default AF2 pipeline](#default-af2-pipeline).
+
+Please note, this method of altering the app executed by a container defies the
+main purpose of containers providing unaltered apps ready to go, out of the box.
+Also note, since this method relies on internals of the pipeline beyond the
+scope of af2@scicore, future updates of AF2 may break it.
+
+
+## Custom container
+
+`run_af2` uses the AlphaFold 2 pipeline as provided by DeepMind. That is, we
+build the vanilla Docker container as described in their [documentation](
+https://github.com/deepmind/alphafold). Simply run
+
+```terminal
+$ docker build -f docker/Dockerfile -t alphafold:2022-01-11 .
+```
+
+inside a checkout of the AF2 Git repository. That creates the container tagged
+with `2022-01-11`, which is the way `run_af2` indicates versions. It's simply
+the date of creation of the container from a fresh checkout of the Git repository.
+
+This Docker container is then turned into a Singularity container:
+
+```terminal
+$ singularity build alphafold-2022-01-11.sif docker-daemon://alphafold:2022-01-11
+```
+
+`alphafold-2022-01-11.sif` can then be used with the `--singularity-image` of
+`run_af2`.
+
+
 ## Interactive IPython notebook
 
 As an expert mode, we provide a notebook version of the default AF2 pipeline 
@@ -193,5 +243,5 @@ highly secure *my_password*.
 
 <!--  LocalWords:  AlphaFold sciCORE IPython ipynb GitLab PyPI af FASTA py rtx
  -->
-<!--  LocalWords:  alphafold sbatch
+<!--  LocalWords:  alphafold sbatch DeepMind
  -->