Haddock3 online user manual

software/haddock2.5

@@ -0,0 +1 @@
+haddock2.4

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 meant 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,66 @@
+# 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
+
+- Ab-initio docking typically involves limited, if any, prior information on how the various chains involved should interact. As a result, producing good solutions relies heavily on a trial-and-error approach. Thus, to enhance the likelihood of generating good models, we strongly advise increasing the sampling at the `[rigidbody]` docking stage (by tuning the `sampling` parameter).
+- 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 generate restraints between the centers of masses of the different chains present in the system, and use these restraints 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.
+To calculate the upper distance limit for the restraints, the height, width, and depth of each molecule are first determined. Technically, each molecule is aligned along its principal (i.e. longest) components, and the x, y, and z dimensions are measured. Next:
+- If `cmtight=true`: The 'molecule distance' for each molecule is calculated as the average of the two smallest dimensions, each divided by 2. For example:
+```math
+Molecule Distance = \frac{1}{2} \left( \frac{\text{width}}{2} + \frac{\text{depth}}{2} \right)
+```
+- If `cmtight=false`: The 'molecule distance' is the average of all three half-dimensions:
+```math
+Molecule Distance = \frac{1}{3} \left( \frac{\text{height}}{2} + \frac{\text{width}}{2} + \frac{\text{depth}}{2} \right)
+```
+- For DNA, RNA, small ligands, or glycans: The 'molecule distance' is set to 0.  
+The effective upper distance limit for the center of mass distance restraint is defined as the sum of the molecule distances of all molecules involved.
+
+Lastly, the strength of the center of mass restraints can be controlled via the force constant (`kcm`)
+
+`cmrest`, `cmtight` and `kcm` parameters are accessible in `[rigidbody]`, `[flexref]` and `[mdref]` modules.
+
+Please note that setting `cmrest = true` is suitable for globular structures, but may deform other types of molecules, e.g. fibrous proteins, long bDNA etc., as restraint will be defined to the center of the molecule. 
+
+
+## Random Ambiguous Restraints
+
+Another solution for ab-initio docking is to generate random ambiguous restraints (AIRs).
+This is performed by turning **on** the `ranair` parameter (`ranair = true`) in the `[rigidbody]` module.
+When ranair is turned on:
+- During the rigid-body sampling, residues on the surface of each chain are randomly selected, along with surrounding ones, to define a patch.
+- Ambiguous restraints are then generated between these patches, and rigid-body minimization is performed.
+
+`ranair` parameter is limited to the docking of two chains only, and no other type of restraints will be considered, even if specified in the configuration file.
+
+__*Note*__ that during the later stages of the docking workflow (e.g., [flexref], [emref], [mdref]), it is advisable to enable the `contactairs = true` parameter to ensure the molecules remain held together at the interface. This setting defines restraints between thwe residues within a 5Å distance between molecules. However, be aware this may generate a large number of restraints, potentially slowing down computations.
+
+
+## Surface restraints
+
+An alternative solution for ab-initio docking is to turn **on** the `surfrest` parameter (`surfrest = true`).
+By doing so, surface residues are identified, and contact restraints between these residues across docking partners are generated on the fly.
+These restraints are defined as ambiguous distance restraints between all backbone atoms (CA, BB, or N1) of the two molecules. For small ligands, all atoms are considered.
+If fewer than 3 CA and P atoms are found, all atoms are selected instead.
+The upper distance limit is set to 7Å for standard molecules and 4.5Å for small ligands.
+
+Such restraints can be particularly useful in multi-body (N>2) docking to ensure that all molecules are in contact and thus promote compactness of the docking solutions.
+Similarly to 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 sufficient sampling of the random starting orientations, which significantly increases the number of structures generated by the rigid-body docking.
+
+__*Note*__ that this option is computationally more expensive than [center of mass restraints](#center-of-mass-restraints) and [random AIRs](#random-ambiguous-restraints), as the number of restraints grows exponentially with the number of residues 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 to control the strength of the surface restraints.

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 postdoctoral researchers for each of their contributions to the tool, as they have allowed us to continuously develop new methods and improve HADDOCK functionalities over the years.