add FAQ

README.md

@@ -60,3 +60,61 @@ The only requirement is that you set up a Python environment and provide a `conf
 - [Path-integral molecular dynamics](https://github.com/molmod/psiflow/examples/water_path_integral_md.py) | **water**: demonstration of the impact of nuclear quantum effects on the variance in O-H distance in liquid water. Path-integral molecular dynamics simulations with increasing number of beads (1, 2, 4, 8, 16) approximate the proton delocalization, and lead to systematically larger variance in O-H distance.
 
 - [Machine learning potential training](https://github.com/molmod/psiflow/examples/water_train_validate.py) | **water**: simple training and validation script for MACE on a small dataset of water configurations.
+
+# FAQ
+
+**Where do I start?**
+Take a brief look at the [examples](https://github.com/molmod/psiflow/examples/) or the
+[documentation](https://molmod.github.io/psiflow) to get an idea for psiflow's
+capabilities. Next, head over to the [setup & configuration](https://molmod.github.io/psiflow/configuration/) section of the docs to get started!
+
+**Is psiflow a workflow manager?**
+Absolutely not! Psiflow is a Python library which allows you to perform complex molecular simulations and scale them towards large numbers of compute nodes automatically.
+It does not have 'fixed' workflow recipes, it does not require you to set up 'databases'
+or 'server daemons'. The only thing it does is expose a concise and powerful API to
+perform arbitrarily complex calculations in a highly efficiently manner.
+
+**Is it compatible with my cluster?**
+Most likely yes. Check which resource scheduling system your cluster uses (probably either
+SLURM/PBSPro/SGE). If you're not sure, ask your system administrators or open an issue
+
+**Can I use VASP with it?**
+You cannot automate VASP calculations with it, but in 99% of cases there is either no need
+to use VASP, or it's very easy to quickly perform the VASP part manually, outside of psiflow,
+and do everything else (data generation, ML potential training, sampling) with psiflow.
+Open an issue if you're not sure how to do this.
+
+**I would like to have feature X**
+Psiflow is continuously in development; if you're missing a feature feel free to open an
+issue or pull request!
+
+**I have a bug. Where is my error message and how do I solve it?**
+Psiflow covers essentially all major aspects of computational molecular simulation (most
+notably including the executation and parallelization), so there's bound to be some bug
+once in a while. Debugging can be challenging, and we recommend to follow the following steps in
+order:
+
+1. Check the stderr/stdout of the main Python process (i.e. the `python main.py
+ config.yaml` one). See if there are any clues. If it has contents which you don't
+ understand, open an issue. If there's seemingly nothing there, go to step 2.
+2. Check Parsl's log file. This can be found in the current working directory, under
+ `psiflow_internal/parsl.log`. If it's a long file, search for any errors using `error`,
+ `Error`, `ERROR`, ... If you find anything suspicious but do not know how to solve it,
+ open an issue.
+3. Check the output files of individual ML training, QM singlepoints, or i-PI molecular
+ dynamics runs. These can be found under `psiflow_internal/000/task_logs/*`.
+ Again, if you find an error but do not exactly know why it happens or how to solve it,
+ feel free to open an issue. Most likely, it will be useful to other people as well
+4. Check the actual 'jobscripts' that were generated and which were submitted to the
+ cluster. Quite often, there can be a spelling mistake in e.g. the compute project you
+ are using, or you are requesting a resource on a partition that is not available.
+ These jobscripts (and there output and error) can be found under
+ `psiflow_internal/000/submit_scripts/`.
+
+**Where do these container images come from?**
+They were generated using Docker based on the recipes in this repository, and were then
+converted to `.sif` format using `apptainer`
+
+**Can I run psiflow locally for small runs or debug purposes?**
+Of course! If you do not provide a `config.yaml`, psiflow will just use your local
+workstation for its execution. See e.g. [this](https://github.com/molmod/psiflow/blob/main/configs/threadpool.yaml) or [this](https://github.com/molmod/psiflow/blob/main/configs/wq.yaml) config used for testing.