Setting up CENSO

The easiest approach is to download a compiled CENSO binary from the release page: https://github.com/grimme-lab/CENSO/releases. There are two versions available censo and censo_w_cefine which contains the latest cefine version (for TURBOMOLE users). The compiled binaries are created with pyinstaller and are linked against GLIBC version 2.19 and will work for GLIBC version 2.19 and above.

Next make CENSO executable, create your global configuration file .censorc and adjust settings to your needs.

$ chmod u+x censo_w_cefine
$ mv censo_w_cefine ~/bin/censo

$ cd ~/path_to_project/
$ censo -newconfig
$ mv censorc_new ~/.censorc

Upon the first usage of CENSO a folder ~/.censo_assets/ will be created. It contains a file ~/.censo_assets/censo_solvents.json with information on all available solvents and solvent models. If a solvent is not available with a certain solvent model, the user can then choose a replacement solvent, e.g. if benzene is not available choose toluene. This file is directly used in censo and typos will cause the calculation with the repective solvent to crash. For further information see section Solvation.

Get additional Information:

Some information is already contained in censo and can be accessed by running:

Requirements

Note

CENSO interfaces to other codes (ORCA, TURBOMOLE, COSMOtherm). They are not part of CENSO!

CENSO needs other programs in certain versions and will not work properly without them:

xTB in version 6.4.0 or above
TM in version 7.5.x or above (when using r2scan-3c)
ORCA in version 4.x or above
cefine in the newest version, when using TURBOMOLE (or use censo_w_cefine)

Run CENSO on a cluster

When submitting a calculation on a cluster architecture the following points have to be considered:

Are the program paths in your .censorc file correct (ORCA, xTB, CREST, COSMO-RS)
Is the correct TURBOMOLE version sourced in your job-submission file and are the correct environment variables for parallelization set?
provide the correct number of available cores to CENSO (P, maxthreads) * (O,omp) = number of cores
CENSO will generate a lot of data for each conformer. This data is stored in the CONFX (X=number) folders. If you restart and resubmit a calculation to the cluster, you have to tell your submission script to copy these folders.

Hint

CENSO can not be parallelized over several nodes!

Example job-submission script

#!/bin/bash
# PBS Job
#PBS -V
#PBS -N JOB_NAME
#PBS -m ae
#PBS -q batch
#PBS -l nodes=1:ppn=28
#
cd $PBS_O_WORKDIR

### setup programs
## XTB
export OMP_NUM_THREADS=1
export MKL_NUM_THREADS=1
ulimit -s unlimited
export OMP_STACKSIZE=1000m

## TM
export PARA_ARCH=SMP
source /home/$USER/bin/.turbo751
export PARNODES=4  ## omp
export TM_PAR_FORK=1

### ORCA4.2.1
ORCAPATH="/tmp1/orca_4_2_1_linux_x86-64_openmpi216";
MPIPATH="/software/openmpi-2.1.5/bin";
MPILIB="/software/openmpi-2.1.5/lib64";
PATH=${ORCAPATH}:${MPIPATH}:$PATH
LD_LIBRARY_PATH=${ORCAPATH}:${MPILIB}:$LD_LIBRARY_PATH
LD_LIBRARY_PATH=/software/intel/parallel_studio_xe_2017.1/parallel_studio_xe_2017.4.056/compilers_and_libraries_2017/linux/compiler/lib/intel64_lin:$LD_LIBRARY_PATH
LD_LIBRARY_PATH=/software/intel/parallel_studio_xe_2017/mkl/lib/intel64:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH

## PATH
PATH=/home/$USER/bin:$PATH
export PATH
### end programs + PATH

export HOSTS_FILE=$PBS_NODEFILE
cat $HOSTS_FILE>hosts_file

TMP_DIR=/tmp1/$USER
DIR1=$PWD

mkdir -p $TMP_DIR/$PBS_JOBID

#check file system access
if [ ! -d $TMP_DIR/$PBS_JOBID ]; then
 echo "Unable to create $TMP_DIR/$PBS_JOBID  on $HOSTNAME. Must stop."
 exit
fi

#check current location
if [ "$PWD" == "$HOME" ]; then
 echo "Cowardly refusing to copy the whole home directory"
 exit
fi

#copy everything to node (will NOT copy directories for safety reasons.
#Add an 'r' only if absolutely sure what you are doing)
#bwlimit limits bandwidth to 5000 kbytes/sec

 rsync -q --bwlimit=5000 $DIR1/* $TMP_DIR/$PBS_JOBID/
 rsync -rq --ignore-missing-args --bwlimit=5000 $DIR1/CONF* $TMP_DIR/$PBS_JOBID/
 rsync -q --bwlimit=5000 $DIR1/.* $TMP_DIR/$PBS_JOBID/
 cd $TMP_DIR/$PBS_JOBID

####################################################################################
#Gettimings
start=$(date +%s)
#####################################################################################
#jobs start here (if you have no idea what this script does, only edit this part...)

echo "Calculation from $(date)" >> RUNTIME
export PYTHONUNBUFFERED=1

censo -inp inputfile.xyz -P 7 -O 4 > censo.out

#end of job      (....and stop editing here.)
#####################################################################################
#Print timings to file
end=$(date +%s)
secs=$(expr $end - $start)
printf '%dh:%dm:%02ds\n' $(($secs/3600)) $(($secs%3600/60)) $(($secs%60)) >> RUNTIME
#####################################################################################
#copy everything back that is smaller than 5 gbytes

 rsync -rq --bwlimit=5000 --max-size=5G $TMP_DIR/$PBS_JOBID/* $DIR1/
 rsync -q --bwlimit=5000 --max-size=5G $TMP_DIR/$PBS_JOBID/.* $DIR1/

#to be safe, get mos alpha and beta seperately.
#Note that the rsync syntax is strange; you need to first include everything,
#then exclude the rest ("*" includes subdirectories)

 rsync -rq --bwlimit=5000 --include="*/" --include="mos" --include="alpha" --include="beta" --exclude=* $TMP_DIR/$PBS_JOBID/* $DIR1/

#if you want the large files as well, comment in the following

#rsync -r --bwlimit=1000 --min-size=5G $TMP_DIR/$PBS_JOBID/* $DIR1/

 cd $DIR1
 rm -r $TMP_DIR/$PBS_JOBID

Hint

The program paths in your job-submission script have to be adjusted to your local environment