Merge branch 'main' into z-plan-restraints

.github/pull_request_template.md

@@ -1,18 +1,17 @@
-You are about to submit a new Pull Request. Before continuing make sure you read the [contributing guidelines](CONTRIBUTING.md) and that you comply with the following criteria:
+ You are about to submit a new Pull Request. Before continuing make sure you read the [contributing guidelines](CONTRIBUTING.md).
 
-- [ ] You have sticked to Python. Please talk to us before adding other programming languages to HADDOCK3
-- [ ] Your PR is about CNS
-- [ ] Your code is well documented: proper docstrings and explanatory comments for those tricky parts
-- [ ] You structured the code into small functions as much as possible. You can use classes if there is a (state) purpose
-- [ ] Your code follows our coding style
-- [ ] You wrote tests for the new code
-- [ ] `tox` tests pass. *Run `tox` command inside the repository folder*
-- [ ] `-test.cfg` examples execute without errors. *Inside `examples/` run `python run_tests.py -b`*
-- [ ] PR does not add any dependencies, unless permission granted by the HADDOCK team
-- [ ] PR does not break licensing
-- [ ] Your PR is about writing documentation for already existing code :fire:
-- [ ] Your PR is about writing tests for already existing code :godmode:
+## Checklist
 
----
+- [ ] Tests added for the new code
+- [ ] Documentation added for the code changes
+- [ ] Does not break licensing
+- [ ] Does not add any dependencies, if it does please add a thorough explanation
 
-<!-- Carefully explain what changed you made to the code, make sure the title reflects the changes -->
+## Summary of the Pull Request  
+<!-- Describe what changes were made to the code, what was added, removed, etc. -->
+
+## Related Issue
+<!-- If this PR is related to an issue, please link it here -->
+
+## Additional Info
+<!-- Any additional information that might be helpful, if applicable -->

DISCLAIMER.md

@@ -0,0 +1,37 @@
+# HADDOCK3 DISCLAIMER
+
+The HADDOCK3 software is provided "as is" and without warranties.
+The authors of the software will not be held liable for any use of the HADDOCK3 package and derivatives/results. 
+
+Some of HADDOCK3 modules use the CNS software (<http://cns-online.org/v1.3/>) (Crystallography and NMR System) 
+as computational engine.
+
+While CNS is free of use for non-profit users, a proper license is required for commercial applications. 
+Biovia is handling those licenses (<https://www.3ds.com/how-to-buy/contact-sales>). 
+While they officially do not distribute CNS (CNX) anymore, they usually allow the use of the non-profit version 
+provided a proper license is purchased for some of their modelling software.
+
+The HADDOCK3 modules using CNS are:
+
+- topology modules:
+  - topoaa
+  - topocg
+
+- sampling modules:
+  - rigidbody
+
+- refinement modules:
+  - flexref
+  - emref
+  - mdref
+
+- scoring modules:
+  - emscoring
+  - mdscoring
+
+- analysis modules:
+  - alascan
+
+Commercial use of any of the above-mentioned modules in a HADDOCK3 workflow will thus require a proper CNS license.
+It is your responsibility as a user to make sure you have such a license.
+

README.md

@@ -1,7 +1,15 @@
-Welcome to the HADDOCK3-Beta version.
+# `haddock3`
 
-The `main` branch represents the latest state of HADDOCK v3. Currently,
-stable beta version.
+<!-- <p align="center">
+
+  <img src="docs/figs/HADDOCK3-logo.png" alt="haddock3-logo" style="vertical-align: middle;">
+</p>
+<src > -->
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10527751.svg)](https://doi.org/10.5281/zenodo.10527751)
+[![Research Software Directory](https://img.shields.io/badge/rsd-haddock3-00a3e3.svg)](https://research-software-directory.org/software/haddock3)
+[![fair-software.eu](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F-green)](https://fair-software.eu)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8844/badge)](https://www.bestpractices.dev/projects/8844)
 
 [![unit tests](https://github.com/haddocking/haddock3/workflows/tests/badge.svg?branch=main)](https://github.com/haddocking/haddock3/actions?workflow=tests)
 [![build](https://github.com/haddocking/haddock3/workflows/build/badge.svg?branch=main)](https://github.com/haddocking/haddock3/actions?workflow=build)
@@ -10,67 +18,77 @@ stable beta version.
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/e11e7f45400f4e8589cdf5941f95233a)](https://app.codacy.com/gh/haddocking/haddock3/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/e11e7f45400f4e8589cdf5941f95233a)](https://app.codacy.com/gh/haddocking/haddock3/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
 
+![haddock3-logo](docs/figs/HADDOCK3-logo.png)
 
-[![fair-software.eu](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F-green)](https://fair-software.eu)
-[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8844/badge)](https://www.bestpractices.dev/projects/8844)
-
-[![Research Software Directory](https://img.shields.io/badge/rsd-haddock3-00a3e3.svg)](https://research-software-directory.org/software/haddock3)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10527751.svg)](https://doi.org/10.5281/zenodo.10527751)
+## Introduction
 
-* * *
+HADDOCK, standing for **H**igh **A**mbiguity **D**riven protein-protein **DOCK**ing, is a widely used computational tool for the integrative modeling of biomolecular interactions. Developed by researchers at [Utrecht University](https://uu.nl) in the [BonvinLab](https://bonvinlab.org) for more than 20 years, it integrates various types of experimental data, biochemical, biophysical, bioinformatic prediction and knowledge to guide the docking process.
 
-# HADDOCK3
+## Installation
 
-## 1. Installation
+Please check the [INSTALL](docs/INSTALL.md) file for instructions.
 
-To install HADDOCK3 follow the instructions in the [INSTALL](docs/INSTALL.md)
-file.
+You might also want to check the following utilities:
 
-## 2. Documentation
+- [`haddock-restraints`](https://github.com/haddocking/haddock-restraints): Tool to generate restraints to be used in `haddock3`.
+- [`haddock-runner`](https://github.com/haddocking/haddock-runner): Tool to run large scale `haddock3` simulations using multiple input molecules in different scenarios
+- [`haddock-tools`](https://github.com/haddocking/haddock-tools): Set of useful utility scripts developed over the years by the BonvinLab group members
 
-HADDOCK3-beta documentation is hosted online at https://www.bonvinlab.org/haddock3/.
-The documentation is rendered and update at every commit to the `main` branch. So,
-you will always find the latest version in the link above.
+## Usage
 
-If you want to compile the HADDOCK3 documentation pages locally (offline),
-install HADDOCK3 and activate the `haddock3` python environment as explained in
-the [installation instructions](docs/INSTALL.md). Then, in your terminal
-window, run:
+The most basic usage is:
 
 ```bash
-tox -e docs
+haddock3 <configuration-file.toml>
 ```
 
-*Ignore any warning messages.* After, use your favorite browser to open the
-file `haddock3-docs/index.html`. This will open a local webpage with the
-complete HADDOCK3 documentation. Exactly the same you will find online.
-Navigate around, enjoy, and contribute.
+Check the [EXAMPLES](examples/README.md) page for more some usage examples and the [MANUAL]() (_coming soon!_) for a more detailed explanation of the configuration file.
+
+## Support
 
-## 3. Examples
+If you encounter any code-related issues, [please open an issue](https://github.com/haddocking/haddock3/issues/new/choose).
 
-### 3.1. Basic scoring of an ensemble of 5 structures:
+If you have any other questions or need help, please contact us at [ask.bioexcel.eu](https://ask.bioexcel.eu/).
 
-In the `examples/` folder you find several examples for you to test and
-learn HADDOCK3. Additional information is in the documentation pages.
+If you clone this repository and use `haddock3` for your research, please support us by signing up in [this form](https://forms.gle/LCUHiYHh1hE9rd8L6). This will allow us contact you when needed for `haddock3`-related issues, and also provide us a mean to demonstrate impact when reporting for grants - which grealty helps us to keep the project alive!
+
+## Cite us
+
+If you used `haddock3` for your research, please cite us:
+
+- **Research article**: (_coming soon!_)
+- **Cite this repository**: M.C. Teixeira, J., Vargas Honorato, R., Giulini, M., Bonvin, A., SarahAlidoost, Reys, V., Jimenez, B., Schulte, D., van Noort, C., Verhoeven, S., Vreede, B., SSchott, & Tsai, R. (2024). haddocking/haddock3: v3.0.0-beta.5 (Version 3.0.0-beta.5) [Computer software]. [https://doi.org/10.5281/zenodo.10527751](https://doi.org/10.5281/zenodo.10527751)
+
+## Useful resources
+
+- [User manual]() (_coming soon!_)
+- [Best practice guide](https://www.bonvinlab.org/software/bpg/)
+- [The HADDOCK2.4 web server: A leap forward in integrative modelling of biomolecular complexes. Nature Prot. 2024](https://www.nature.com/articles/s41596-024-01011-0)
+
+## Development
+
+🚧 _Coming soon! We are currently working on the development guide_ 🚧
+
+### Code Documentation
+
+The code documentation is automatically built and hosted at [bonvinlab.org/haddock3](https://www.bonvinlab.org/haddock3/).
+
+To build it locally (considering you have followed the installation instructions):
 
 ```bash
-cd examples/scoring/
-haddock3 emscoring-test.cfg
+tox -e docs
 ```
 
-## 4. Contribute
+> Warning messages are expected, but the documentation should be built successfully.
+
+The rendered documentation will be available at `haddock3-docs/index.html`. This will open a local webpage with the
+
+### Contributing
 
-If you want to contribute to HADDOCK3's development, read the
-[CONTRIBUTING](CONTRIBUTING.md) file for instructions.
+Check the [CONTRIBUTING](CONTRIBUTING.md) file for instructions on how to contribute with the project!
 
-## 5. Keep in contact and support us
+<!-- ---
 
-HADDOCK3 is an academic project supported by various grants, including the EU
-BioExcel Center of Excellence for Computational Biomolecular Research. HADDOCK3
-is fully open-source and free to download. If you clone this repository and use
-HADDOCK3 for your research, please support us by signing [this Google
-form][googleform] if you have not yet done so. This will allow us contact you
-when needed for HADDOCK3-related issues, and also provide us a mean to
-demonstrate impact when reporting for grants.
+Happy HADDOCking!
 
-[googleform]: https://docs.google.com/forms/d/e/1FAIpQLScDcd0rWtuzJ_4nftkDAHoLVwr1IAVwNJGhbaZdTYZ4vWu25w/viewform
+<img src="https://www.bonvinlab.org/images/bio-haddock.png" alt="haddock" width="50px"> -->

docs/examples.md

@@ -62,7 +62,7 @@ A protein-glycan docking example making use of the knowledge of the binding site
 
 1) 1000 rigidbody docking models, RMSD clustering to select 50 clusters, flexible refinement of the top 5 models of each cluster, final RMSD clustering for cluster-based scoring ([docking-protein-glycan-full.cfg](../examples/docking-protein-glycan/docking-protein-glycan-full.cfg)). The RMSD clustering assumes a good knowledge of the interface, as the user has to define the residues involved in the binding site by means of the resdic_ parameter.
 2) 1000 rigidbody docking models, interface-ligand-RMSD (`ilrmsd`) clustering to select 50 clusters, flexible refinement of the top 5 models of each cluster, final ilRMSD clustering for cluster-based scoring ([docking-protein-glycan-ilrmsd-full.cfg](../examples/docking-protein-glycan/docking-protein-glycan-ilrmsd-full.cfg)). The interface-ligand-RMSD clustering is a more general approach, as it does not require the user to define the residues involved in the binding site. The interface is automatically defined by the residues involved in the protein-glycan interaction in the input models.
-3) 500 flexible docking runs + final RMSD clustering for cluster-based scoring [docking-flexref-protein-glycan-full.cfg](../examples/docking-protein-glycan/docking-flexref-protein-glycan-full.cfg). In this case, the rigidbody docking is skipped and the docking is performed at the flexible refinement level. In this case the flexible refinement has more steps than usual (`mdsteps_rigid = 5000`, `mdsteps_cool1 = 5000` and so on) and the glycan is defined as fully flexible (`nfle2 = 1` and associated parameters).
+3) 500 flexible docking runs + final RMSD clustering for cluster-based scoring [docking-flexref-protein-glycan-full.cfg](../examples/docking-protein-glycan/docking-flexref-protein-glycan-full.cfg). In this case, the rigidbody docking is skipped and the docking is performed at the flexible refinement level. In this case the flexible refinement has more steps than usual (`mdsteps_rigid = 5000`, `mdsteps_cool1 = 5000` and so on) and the glycan is defined as fully flexible (`fle_sta_1`, `fle_end_1`, `fle_seg_1`).
 
 __Note__ the modified weight of the van der Waals energy term for the scoring of the rigidbody docking models (`w_vdw = 1.0`), as in the [protein-ligand example](#docking-protein-ligand).
 
@@ -113,7 +113,7 @@ Three different workflows are illustrated:
 2) 3000 rigidbody docking models, selection of top400 and flexible refinement + final refinement in explicit solvent (water) of those ([docking-protein-peptide-mdref-full.cfg](../examples/docking-protein-peptide/docking-protein-peptide-mdref-full.cfg)
 3) 3000 rigidbody docking models, FCC clustering and selection of max 20 models per cluster followed by flexible refinement and EM ([docking-protein-peptide-cltsel-full.cfg](../examples/docking-protein-peptide/docking-protein-peptide-cltsel-full.cfg)).
 
-__Note__ how the peptide is defined as fully flexible for the refinement phase (`nfle2 = 1` and associated parameters) and dihedral angle restraints are automatically defined to maintain secondary structure elements (`ssdihed = "alphabeta"`)
+__Note__ how the peptide is defined as fully flexible for the refinement phase (`fle_sta_1`, `fle_end_1`, `fle_seg_1`) and dihedral angle restraints are automatically defined to maintain secondary structure elements (`ssdihed = "alphabeta"`)
 
 The `caprieval` module is called at various stages during the workflow to assess the quality of the models with respect to the known reference structure.
 

examples/compare_runs.py

@@ -67,6 +67,7 @@
     ("docking-antibody-antigen"    , "docking-antibody-antigen-CDR-NMR-CSP-test.cfg"),  # noqa: E203, E501
     ("docking-protein-DNA"         , "docking-protein-DNA-test.cfg"),  # noqa: E203, E501
     ("docking-protein-DNA"         , "docking-protein-DNA-mdref-test.cfg"),  # noqa: E203, E501
+    ("docking-protein-DNA"         , "docking-protein-DNA-cmrest-test.cfg"),  # noqa: E203, E501
     ("docking-protein-homotrimer"  , "docking-protein-homotrimer-test.cfg"),  # noqa: E203, E501
     ("docking-protein-glycan"      , "docking-protein-glycan-test.cfg"),  # noqa: E203, E501
     ("docking-protein-glycan"      , "docking-protein-glycan-ilrmsd-test.cfg"),  # noqa: E203, E501
@@ -81,6 +82,7 @@
     ("docking-multiple-ambig"      , "docking-multiple-tbls-test.cfg"),  # noqa: E203, E501
     ("docking-protein-protein"     , "docking-exit-test.cfg"),  # noqa: E203, E501
     ("refine-complex"              , "refine-complex-test.cfg"),  # noqa: E203, E501
+    ("peptide-cyclisation"         , "cyclise-peptide-test.cfg"),  # noqa: E203, E501
     ("scoring"                     , "emscoring-test.cfg"),  # noqa: E203, E501
     ("scoring"                     , "mdscoring-test.cfg"),  # noqa: E203, E501
     ("scoring"                     , "emscoring-mdscoring-test.cfg"),  # noqa: E203, E501

examples/docking-protein-DNA/data/cro_air.tbl

@@ -38,12 +38,12 @@ assign ( resid 33  and segid A)
 !
 ! HADDOCK AIR restraints for 2nd partner
 !
-assign ( resid 3  and segid B and (name O1P or name O2P or name OP1 or name OP2))
+assign ( resid 3  and segid B and (name OP1 or name OP2))
        (
         ( resid 10  and segid A)
        )  2.0 2.0 0.0
 !
-assign ( resid 4  and segid B and (name O1P or name O2P or name OP1 or name OP2))
+assign ( resid 4  and segid B and (name OP1 or name OP2))
        (
         ( resid 10  and segid A)
        )  2.0 2.0 0.0
@@ -63,7 +63,7 @@ assign ( resid 6  and segid B and (name N1 or name N3 or name N7 or name H61 or
         ( resid 29  and segid A)
        )  2.0 2.0 0.0
 !
-assign ( resid 30  and segid B and (name O1P or name O2P or name OP1 or name OP2))
+assign ( resid 30  and segid B and (name OP1 or name OP2))
        (
         ( resid 40  and segid A)
      or
@@ -72,7 +72,7 @@ assign ( resid 30  and segid B and (name O1P or name O2P or name OP1 or name OP2
         ( resid 42  and segid A)
        )  2.0 2.0 0.0
 !
-assign ( resid 31  and segid B and (name O1P or name O2P or name OP1 or name OP2))
+assign ( resid 31  and segid B and (name OP1 or name OP2))
        (
         ( resid 40  and segid A)
      or