Initial Commit

README.md

@@ -0,0 +1,56 @@
+# Conformer-Rotamer Ensemble Sampling Tool
+
+[![Latest Version](https://img.shields.io/github/v/release/grimme-lab/crest)](https://github.com/grimme-lab/crest/releases/latest)
+[![DOI](https://img.shields.io/badge/DOI-10.1039%2Fc9cp06869d%20-blue)](http://dx.doi.org/10.1039/c9cp06869d)
+
+This is the offical repository of the `crest` program developed by the Grimme group in Bonn.
+
+`crest` is an extension to the [`xtb`](https://github.com/grimme-lab/xtb) program.
+It functions as an IO based OMP scheduler (*i.e.*, calculations are
+performed by the `xtb` program) and tool for the creation and analysation of
+structure ensembles.
+
+<div align="center">
+<img src="./assets/crest.png" alt="CREST" width="200">
+</div>
+
+## Installation
+
+We are currently preparing the source code and will be providing it in this repository
+with one of the upcoming releases.
+
+Until then please use the statically linked binaries (Intel Compiler 17.0.7)
+that can be found at the [release page](https://github.com/grimme-lab/crest/releases),
+of this repository.
+Simply unpack the binary and add it to your *PATH* variable.
+```bash
+tar -xvzf crest.tgz
+```
+
+Also make sure that you have correctly installed and sourced the [`xtb`](https://github.com/grimme-lab/xtb) program before attempting any calculations with `crest`.
+
+## Examples
+
+This repository contains several examples for default applications of `crest`.
+
+See [`examples`](examples). To test the installation please try to run [example 0](examples/expl-0).
+
+## Documentation
+
+The `crest` documentation is hosted at [read-the-docs](https://xtb-docs.readthedocs.io/en/latest/crest.html).
+
+## Citations
+
+1. P. Pracht, F. Bohle, S. Grimme, *Phys. Chem. Chem. Phys.*, **2020**, 22, 7169-7192.
+  DOI: [10.1039/C9CP06869D](https://dx.doi.org/10.1039/C9CP06869D)
+
+2. S. Grimme, *J. Chem. Theory Comput.*, **2019**, 155, 2847-2862.
+  DOI: [10.1021/acs.jctc.9b00143](https://dx.doi.org/10.1021/acs.jctc.9b00143)
+
+
+## License
+
+`crest` is distributed in the hope that it will be useful,
+but without any warranty; without even the implied warranty of
+merchantability or fitness for a particular purpose.
+

examples/README.md

@@ -0,0 +1,34 @@
+# Example applications of the CREST program
+
+This directory contains several examples for 
+standard applications of the `crest` program.
+
+Each example directory contains a input structure
+(typically called `struc.xyz`) and a bash script
+called `run.sh` that includes some information about
+the example and will execute the calculation upon
+execution.
+
+To run the example scripts simply go to the respective
+directory and execute it from the command line:
+```bash
+./run.sh
+```
+
+It is assumed that the `xtb` and `crest` binaries
+are present in the *PATH* variable as such.
+The `run.sh` scripts will check for this, however.
+
+
+## Examples
+
+0. *dry run* of the `crest` program
+1. default conformational search (iMTD-GC)
+2. example for different CMD settings
+3. sorting an ensemble file (CREGEN)
+4. constrained conformational sampling
+5. standalone optimization along a trajectory
+6. NCI sampling mode (iMTD-NCI)
+7. protonation site sampling
+8. modified protonation site sampling
+9. tautomer sampling

examples/expl-0/run.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+
+xtbin='xtb'
+crst='crest'
+
+command -v $xtbin >/dev/null 2>&1 || { echo >&2 "Cannot find xtb binary. Exit."; exit 1; }
+command -v $crst >/dev/null 2>&1 || { echo >&2 "Cannot find crest binary. Exit."; exit 1; }
+
+if [ $xtbin == 'xtb' ]
+ then
+    $crst struc.xyz -dry
+ else
+    $crst struc.xyz -dry -xnam $xtbin
+ fi
+
+# Before starting any calculation, settings
+# can be checked with the '-dry' flag.
+# This will only print a summary about the
+# selected settings and thresholds to the
+# consol and check for the xtb binary.
+#
+# Every time the input file (struc.xyz) is
+# something else than 'coord', a file called
+# 'coord' will be (over-)written, containing
+# the atomic coordinates in Bohr. CREST will
+# then continue to use and overwrite this
+# coord file for all further calculations.

examples/expl-0/struc.xyz

@@ -0,0 +1,14 @@
+12
+
+C          1.00510       -0.04436        0.07729
+C          2.52196       -0.10014        0.05638
+C          3.03386       -1.52959       -0.04885
+O          4.45512       -1.53382       -0.04957
+H          0.66450        0.99293        0.15400
+H          0.60392       -0.59767        0.93240
+H          0.58435       -0.47325       -0.83778
+H          2.92490        0.36854        0.96213
+H          2.90338        0.49174       -0.78421
+H          2.68484       -2.01184       -0.96764
+H          2.69552       -2.12845        0.80244
+H          4.74911       -1.01511       -0.81774

examples/expl-1/run.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+
+xtbin='xtb'
+crst='crest'
+
+command -v $xtbin >/dev/null 2>&1 || { echo >&2 "Cannot find xtb binary. Exit."; exit 1; }
+command -v $crst >/dev/null 2>&1 || { echo >&2 "Cannot find crest binary. Exit."; exit 1; }
+
+if [ $xtbin == 'xtb' ]
+ then
+    $crst struc.xyz -ewin 2.0
+ else
+    $crst struc.xyz -ewin 2.0 -xnam $xtbin
+ fi
+
+
+# This will execute a conformational search with default settings
+# for the 1-propanol molecule.
+# The energy window is set to 2.0 kcal/mol with the '-ewin' flag
+# (instead of the default 6.0 kcal/mol window)
+# Within this window there should be 4 conformers for 1-propanol
+# in the gas phase.
+# The 4 unique conformers can be found in the file 'crest_conformers.xyz'.
+# All degenerate conformers (rotamers, pseudo-enantiomers) of the 4 structures
+# can be found in the file 'crest_rotamers.xyz'
+
+

examples/expl-1/struc.xyz

@@ -0,0 +1,14 @@
+12
+
+C          1.00510       -0.04436        0.07729
+C          2.52196       -0.10014        0.05638
+C          3.03386       -1.52959       -0.04885
+O          4.45512       -1.53382       -0.04957
+H          0.66450        0.99293        0.15400
+H          0.60392       -0.59767        0.93240
+H          0.58435       -0.47325       -0.83778
+H          2.92490        0.36854        0.96213
+H          2.90338        0.49174       -0.78421
+H          2.68484       -2.01184       -0.96764
+H          2.69552       -2.12845        0.80244
+H          4.74911       -1.01511       -0.81774

examples/expl-2.5/run.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+xtbin='xtb'
+crst='crest'
+
+command -v $xtbin >/dev/null 2>&1 || { echo >&2 "Cannot find xtb binary. Exit."; exit 1; }
+command -v $crst >/dev/null 2>&1 || { echo >&2 "Cannot find crest binary. Exit."; exit 1; }
+
+if [ $xtbin == 'xtb' ]
+ then
+    $crst struc.xyz -ewin 2.0 -quick -prop ohess
+ else
+    $crst struc.xyz -ewin 2.0 -quick -prop ohess -xnam $xtbin
+ fi
+
+# Some further calculations can be added automatically
+# after the conformer search with the '-prop' command.
+# In the above example, after searching for the
+# conformers of 1-propanol, each conformer is optimized
+# again and frequencies are calculated (ohess).
+# The conformer ensemble is then re-ranked with free
+# energies from RRHO contributions.
+#
+# There are also some different 'quick'-modes to run
+# the conformational search with reduced settings.
+# With these modes the conformational space will be
+# explored less extensively, but it will speed up
+# the calculation. ('-quick','-squick','-mquick')
+

examples/expl-2.5/struc.xyz

@@ -0,0 +1,14 @@
+12
+
+C          1.00510       -0.04436        0.07729
+C          2.52196       -0.10014        0.05638
+C          3.03386       -1.52959       -0.04885
+O          4.45512       -1.53382       -0.04957
+H          0.66450        0.99293        0.15400
+H          0.60392       -0.59767        0.93240
+H          0.58435       -0.47325       -0.83778
+H          2.92490        0.36854        0.96213
+H          2.90338        0.49174       -0.78421
+H          2.68484       -2.01184       -0.96764
+H          2.69552       -2.12845        0.80244
+H          4.74911       -1.01511       -0.81774

examples/expl-2/run.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+xtbin='xtb'
+crst='crest'
+
+command -v $xtbin >/dev/null 2>&1 || { echo >&2 "Cannot find xtb binary. Exit."; exit 1; }
+command -v $crst >/dev/null 2>&1 || { echo >&2 "Cannot find crest binary. Exit."; exit 1; }
+
+if [ $xtbin == 'xtb' ]
+ then
+    $crst struc.xyz -ewin 2.0 -g h2o -gfn2 -T 4
+ else
+    $crst struc.xyz -ewin 2.0 -g h2o -gfn2 -T 4 -xnam $xtbin
+ fi
+
+
+# This will execute a conformational search with some manually changed
+# settings for the 1-propanol molecule.
+# The GBSA implicit solvation model for H2O is employed with the
+# '-g' flag.
+# Furthermore, the use of GFN2-xTB is requested explicitly ('-gfn2')
+# and the program is ordered to use 4 CPU threads ('-T').
+# For a 1-propanol the conformers in implicit solvation are the
+# same as in the gas phase, but the relative energies should
+# differ significantly.
+# Unique conformers can be found in the file 'crest_conformers.xyz'.
+# All degenerate conformers (rotamers, pseudo-enantiomers)
+# can be found in the file 'crest_rotamers.xyz'
+
+

examples/expl-2/struc.xyz

@@ -0,0 +1,14 @@
+12
+
+C          1.00510       -0.04436        0.07729
+C          2.52196       -0.10014        0.05638
+C          3.03386       -1.52959       -0.04885
+O          4.45512       -1.53382       -0.04957
+H          0.66450        0.99293        0.15400
+H          0.60392       -0.59767        0.93240
+H          0.58435       -0.47325       -0.83778
+H          2.92490        0.36854        0.96213
+H          2.90338        0.49174       -0.78421
+H          2.68484       -2.01184       -0.96764
+H          2.69552       -2.12845        0.80244
+H          4.74911       -1.01511       -0.81774

examples/expl-3/run.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+
+xtbin='xtb'
+crst='crest'
+
+command -v $xtbin >/dev/null 2>&1 || { echo >&2 "Cannot find xtb binary. Exit."; exit 1; }
+command -v $crst >/dev/null 2>&1 || { echo >&2 "Cannot find crest binary. Exit."; exit 1; }
+
+$crst struc.xyz -cregen xtb.trj -ewin 100.0
+
+
+# The sorting routine from the CREST conformational search can be
+# used as a standalone to sort any .xyz or .trj ensemble file.
+# The above command will sort the file xtb.trj according to
+# its energy and determine duplicate structures.
+# Two files are written analogous to 'crest_conformers.xyz'
+# and 'crest_rotamers.xyz'.
+# The new file 'crest_ensemble.xyz' will contain only unique
+# structures from xtb.trj, while the new file 'xtb.trj.sorted'
+# is just a sorted version of the original file (without the
+# -ewin flag the default 6.0 kcal/mol window will be used)
+# The routine requires a reference structure which is given
+# by 'struc.xyz'.
+

examples/expl-3/struc.xyz

@@ -0,0 +1,14 @@
+   12
+FINAL HEAT OF FORMATION =    -1.651323
+ C     1.625257    -0.262628    -0.323273
+ C     0.518221     0.706221    -0.335177
+ C    -0.859313    -0.005477    -0.327969
+ H    -1.683026     0.654493    -0.607965
+ H    -0.974493    -0.754480    -1.061658
+ O    -1.171503    -0.423846     1.012985
+ H    -0.837975     0.254126     1.683603
+ H     0.615912     1.428650     0.457852
+ H     0.597843     1.325129    -1.321583
+ H     1.504113    -0.866659     0.564875
+ H     2.639815     0.049302    -0.353007
+ H     1.502315    -1.001480    -1.109649