Haddock3 online user manual

software/haddock3/README.md

@@ -0,0 +1,19 @@
+# Contribute to the book
+
+The book source code is located in `haddock3/src/`.
+From here, consider only relative paths for things to be functional.
+
+# Compile the book
+
+This manual is ment to be compiled by `mdbook`.
+
+To generate it, mdbook must be installed (see [how to install mdbook](https://rust-lang.github.io/mdBook/index.html)).
+
+
+Then run the following command, once in the `software/haddock3/` directory:
+
+```bash
+mdbook build haddock3-manual --dest-dir ../manual
+# or
+/Applications/mdbook build haddock3-manual --dest-dir ../manual
+```

software/haddock3/haddock3-manual/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["BonvinLab", "HADDOCK", "Computational Structural Biology", "Utrecht University"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Haddock3 User Manual"

software/haddock3/haddock3-manual/src/SUMMARY.md

@@ -0,0 +1,77 @@
+# Summary
+
+- [Introduction](./intro_manual.md)
+  - [HADDOCK - High Ambiguity Docking](./haddocking.md)
+  - [Haddock3 modularity](./haddock3.md)
+
+- [Installation](./install.md)
+  - [Virtual environments (conda / venv)](./virtual-environments.md)
+  - [Obtaining HADDOCK](./download-haddock3.md)
+  - [CNS](./install-cns.md)
+
+- [Command Line Interfaces](./clis.md)
+
+- [Preparing input files](./structure_requirements.md)
+  - [Haddock3 requirements](./structure_requirements.md)
+  - [Tools to manipulate structures](./pdbtools.md)
+
+- [Generating restraints for HADDOCK](./intro_restraints.md)
+  - [haddock3-restraints](./restraints_cli.md)
+  - [Automated restraints generation](./automated_restraints.md)
+    - [Symmetry restraints](./automated_restraints.md)
+    - [DNA & RNA restraints](./automated_restraints.md)
+  - [Ab-initio docking mode](./abinitio_docking.md)
+  - [Flexibility](./flexibility.md)
+
+- [Generating a docking protocol](./config_file.md)
+  - [Global parameters](./global_parameters.md)
+  - [Concept of modules / parameters](./modules_parameters.md)
+  - [Notable parameters](./important_parameters.md)
+
+- [Available modules](./modules.md)
+  - [Topology](./modules/topology.md)
+  - [Sampling](./modules/sampling.md)
+  - [Refinement](./modules/refinement.md)
+  - [Scoring](./modules/scoring.md)
+  - [Analysis](./modules/analysis.md)
+
+- [Docking scenarios](./docking_scenarios.md)
+  - [Protein-protein docking](./docking_scenarios/prot-prot.md)
+  - [Protein-peptide docking](./docking_scenarios/prot-peptide.md)
+  - [Protein-DNA docking](./docking_scenarios/prot-DNA.md)
+  - [Antibody-antigen docking](./docking_scenarios/antibody-antigen.md)
+  - [Protein-glycan docking](./docking_scenarios/prot-glycan.md)
+  - [Small-molecule docking](./docking_scenarios/prot-ligand.md)
+  - [Complexes refinement protocols](./docking_scenarios/refinement-protocols.md)
+  - [Building cyclic peptide](./docking_scenarios/cyclic-peptides.md)
+  - [Scoring workflow](./docking_scenarios/scorings.md)
+  - [Analysis pipelines](./docking_scenarios/analyses.md)
+
+- [Getting support / How to ask for help](./info.md)
+  - [Getting support / How to ask for help](./info.md)
+  - [FAQ](./faq.md)
+
+- [Tutorials](./tutorials.md)
+  - [Access to various tutorials](./tutorials.md)
+  - [Best practice guide](./bpg.md)
+    - [Structure preparation](./bpg/structures.md)
+    - [Generating restraints](./bpg/restraints.md)
+    - [Small-molecules / Ligands](./bpg/small_mol.md)
+    - [Glycans](./bpg/glycans.md)
+    - [Peptides](./bpg/peptides.md)
+    - [DNA / RNA](./bpg/dna.md)
+    - [Proteins](./bpg/proteins.md)
+    - [Clustering complexes](./bpg/clustering.md)
+    - [Analysing results](./bpg/analysis.md)
+
+- [Haddock3 eco-system](./eco_system.md)
+
+- [Online lectures](./online_lectures.md)
+
+- [Haddock3 source code](./source_code_organisation.md)
+
+- [How to cite haddock3](./citing.md)
+  - [Citing haddock3](./citing.md)
+  - [Haddock3-related publications](./publications.md)
+
+- [Acknowledgements](./acknowledgements.md)

software/haddock3/haddock3-manual/src/abinitio_docking.md

@@ -0,0 +1,61 @@
+# Ab-initio / naive docking protocols
+
+While HADDOCK is meant to use information from experiments, literature, or bioinformatic predictions to guide the sampling during the docking, sometimes such data is not available.
+For these reasons, dedicated parameters can be turned **on** to perform *ab-initio* docking.
+
+Three different ways of doing *ab-initio* docking in haddock3 are discussed below.
+
+### Prior considerations
+
+- As ab-initio docking contains very loose information on how the various chains involved should interact, we strongly advise increasing the sampling at `[rigidbody]` docking stage (using the `sampling` parameter) as finding a good solution mostly relies on trials and errors.
+- The next three *ab-initio* docking solutions described below are incompatible with each other, and you should not turn **on** multiple of them at the same time.
+
+
+## Center of mass restraints
+
+Turning **on** the center of mass restraints parameter (`cmrest = true`), will automatically generates restraints between the center of masses of the different chains present in the system, and use those during the docking.
+
+This parameter goes together with the `cmtight` parameter, which controls how the upper limit distance is defined for the center of mass restraints between molecules.
+Each molecule is oriented along its principle components and the x, y, and z dimensions are calculated.
+If `cmtight=true`, the molecule distance (size) is set to the average of its smallest two-half dimensions.
+If `cmtight=false`, the molecule distance (size) is set to the average of its three half dimensions.
+In the case of DNA, RNA, small ligands, or glycans, the molecule distance (size) is set to 0.
+The effective upper distance limit for the center of mass distance restraint is the sum of the two molecule distances.
+
+`cmrest` and `cmtight` parameters are accessible in `[rigidbody]` and `[flexref]` modules.
+
+This parameter goes together with its force constant (`kcm`), which can be tuned as well.
+
+Please note that setting `cmrest = true` is more suited for globular structures.
+As for example, for a long bDNA structure, the restraint will be defined to the center of the DNA.
+
+
+## Random Ambiguous Restraints
+
+Another solution is to generate random ambiguous restraints.
+This is performed by turning **on** the `ranair` parameter (`ranair = true`) in the `[rigidbody]` module.
+
+By doing so, for each rigid-body sampling performed, residues on the surface of each chain will be randomly picked together with surrounding ones to define a patch.
+Ambiguous restraints will then be generated between all the patches and rigid-body minimization performed.
+
+We suggest turning on `contactairs = true` parameters in later stages of the workflow for CNS modules (`[flexref]`, `[emref]`, `[mdref]`).
+
+__*Note*__ that `ranair` is limited to the docking of two chains only, and no other type of restraints will be considered (even tho specified in the configuration file).
+
+
+## Surface restraints
+
+An alternative solution is to turn **on** the `surfrest` parameter (`surfrest = true`).
+By doing so, surface residues are first detected and contact restraints between molecules are generated on the fly.
+These are defined as an ambiguous distance restraint between all backbone (CA, BB or N1) atoms of two molecules (for small ligands all atoms are considered).
+If less than 3 CA and P atoms are found, all atoms will be selected instead.
+The upper limit is set to 7A (or 4.5A in the case of small ligands).
+
+Such restraints can be useful in multi-body (N>2) docking to ensure that all molecules are in contact and thus promote compactness of the docking solutions.
+As for the [random AIRs](#random-ambiguous-restraints), surface contact restraints can be used in *ab-initio* docking; in such a case it is important to have enough sampling of the random starting orientations and this significantly increases the number of structures for rigid-body docking.
+
+Note that this option is computationally more expensive than the [center of mass restraints](#center-of-mass-restraints) and [random AIRs](#random-ambiguous-restraints), as the number of restraints is increasing by the power of the number of residues present in the system.
+Also, because of the high number of restraints, the physico-chemical components of the scoring function can be masked by the noise of the AIRs component.
+Therefore setting the weight of the AIR component to 0 (`w_air = 0`) could help the scoring function to better decipher between model conformations.
+
+This parameter goes along with its force constant `ksurf`, which can be tuned.

software/haddock3/haddock3-manual/src/acknowledgements.md

@@ -0,0 +1,29 @@
+## Fundings
+
+The development of Haddock3 is made possible thanks to the financial support from Horizon 2020, projects [BioExcel](https://www.bioexcel.eu) [823830](https://cordis.europa.eu/project/id/823830) and [101093290](https://cordis.europa.eu/project/id/101093290), EGI-ACE [101017567](https://cordis.europa.eu/project/id/101017567), and from the Netherlands e-Science Center (027.020.G13), that provided and still provides substantial fundings for software development.
+This allows the HADDOCK team to ensure software quality, improvements, maintenance, and user support.
+
+<figure style="text-align: center;">
+<img width="30%" src="./images/Bioexcel_logo.png" alt="bioexcel">
+</figure>
+
+
+## User driven developments
+
+In Haddock3, not only do we try to provide a powerful docking tool that can handle a variety of biomolecular entities, but we are also developing new modules and functionalities based on user requests.
+On a yearly basis, we ask users to fill out a survey, allowing us to focus on several different directions to improve the tool and make it more suitable for the community.
+Feature requests can also be performed directly from our [GitHub repository issues](https://github.com/haddocking/haddock3/issues/new/choose).
+
+
+## 20 years of HADDOCK
+
+Haddock3 is the newest version of HADDOCK, an original idea initially developed by [Dominguez, C., Boelens, R. & Bonvin, A. M. J. J. in 2003](https://pubs.acs.org/doi/10.1021/ja026939x).
+For more than 20 years now, HADDOCK has been improved, going from its first description to several milestones, namely Haddock2.2, Haddock2.4, and now Haddock3.
+
+In November 2023, we celebrated the 20-year anniversary of HADDOCK, where most of the incredible scientists who contributed to its development attended.
+
+<figure style="text-align: center;">
+<img width="75%" src="./images/20-years-haddock.png" alt="photo 20 years haddock3">
+</figure>
+
+We wish to thank all the students, PhD candidates, and Post-doctoral researchers for each of their contributions to the tool, as it allowed us to continuously develop new methods and improve HADDOCK functionalities over the years.