ergo Documentation


Introduction

ErgoSCF.org is the home of Ergo, a quantum chemistry program for large-scale self-consistent field calculations.

Key features of the Ergo program: Linear response calculations of polarizabilities and excitation energies are possible for the restricted reference density, although complete linear scaling is in the current implementation not achieved since full dense matrices are still used in parts of the linear response implementation.


License

Ergo, version 3.2, a program for linear scaling electronic structure
calculations.
Copyright (C) 2012 Elias Rudberg, Emanuel H. Rubensson, and Pawel Salek.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program 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.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Primary academic reference:
Kohn−Sham Density Functional Theory Electronic Structure Calculations 
with Linearly Scaling Computational Time and Memory Usage,
Elias Rudberg, Emanuel H. Rubensson, and Pawel Salek,
J. Chem. Theory Comput. 7, 340 (2011),
<http://dx.doi.org/10.1021/ct100611z>

For further information about Ergo, see <http://www.ergoscf.org>.


How to run ergo

The executable "ergo" is the new interface to the Ergo project which is meant to be scriptable.
Usage: ergo [args...]
args can be: input file name
             -e "input line"
             -m molecule file name
             -h help message that lists also all the available variables.
The statements in the input file are divided in two classes: variable assignments and executable statements (commands). Currently, following commands are recognized:

run - runs an SCF calculation:

run "HF"
molecule_inline - defines a molecule
molecule_inline
C 0 0 0
O 0 0 2.3
EOF
molecule - reads the molecule file in a MOLECULE/Dalton or XYZ file format
molecule "../nh3.mol"

get_excited_state - computes a set of excited states

get_excited_state "CAMB3LYP" 4

get_polarisability - computes a polarizability for given frequency.

get_polarisability "PBE" "X" 0.2

system - executes a system command

system "rm density.old; mv density.bin density.old"

Example of a simplest input file:

basis= "6-31Gs"
molecule_inline
O     0 0 0
H     1.2 1.2 0
H    -1.2 1.2 0
EOF
get_polarisability "HF" "Y" 0.01


How to generate this documentation

Run doxygen without arguments in the ergo directory. This will generate html documentation which can be browsed via ergo/documentation/html/main.html


How to write comments

See the Doxygen manual http://www.stack.nl/~dimitri/doxygen/manual.html on how to get started writing Doxygen comments.
Comments should be written in JavaDoc style, i.e. using the @ comment prefix rather than \ and using
 /**
  *
  */
 
rather than
 /*!
  *
  */
 
for doxygen comments.

We will possibly add latex doc generation in the future so please keep this in mind and use @htmlonly for all html specific commands.

File comments

Each file should begin with a header in the following style:

 /** @file filename.h Brief description
  *  @author Author1 <em>responsible</em>
  *  @author Author2
  *  @version 1.0
  *  @date    March 2006
  */
which will result in the following:
Brief description
Author:
Author1 responsible

Author2

Version:
1.0
Date:
March 2006

Installation

Usual configuration

./configure && make

Options can be passed - see Configuration examples for more information.

Correctness test

make check

Verbose variant: make check VERBOSE=1

Configuration examples

How to install on different machines and libraries (this should probably be updated)

on dallas, if you want to link with LAPACK
env LIBS=-llapack ./configure

on etorofu:
env CFLAGS="-O4 -march=x86-64 -ffast-math -fexpensive-optimizations -funroll-loops -std=c99" ./configure

on juliana (lenngren):
module add i-compilers
env CC=icc CFLAGS='-O2 -xP -ip -restrict' ./configure

on juliana (lenngren), if you want to link with LAPACK:
env CC=icc CFLAGS='-O2 -xP -ip -restrict' LIBS='-L/pdc/vol/mkl/7.2.0-008/lib/em64t -lmkl_lapack -lmkl_em64t -lguide -lpthread -Wl,--rpath,/pdc/vol/mkl/7.2.0-008/lib/em64t' ./configure

on juliana (lenngren), using gcc 4.2 and openmp
module add gcc/4.2.pre20070501
env CC=gcc CXX=g++ CXXFLAGS='-O2 -fopenmp' LDFLAGS='-fopenmp' LIBS='-L/pdc/vol/mkl/7.2.0-008/lib/em64t -lmkl_lapack -lmkl_em64t -lguide -lpthread -Wl,--rpath,/pdc/vol/mkl/7.2.0-008/lib/em64t' ./configure

on juliana (lenngren), using MPI compiler
module add i-compilers scampi
env CC='mpicc -ccl icc' CFLAGS='-O2 -xP -ip -restrict' ./configure

on juliana (lenngren), using MPI compiler and LAPACK
module add i-compilers scampi
env CC='mpicc -ccl icc' CFLAGS='-O2 -xP -ip -restrict' LIBS='-L/pdc/vol/mkl/7.2.0-008/lib/em64t -lmkl_lapack -lmkl_em64t -lguide -lpthread -Wl,--rpath,/pdc/vol/mkl/7.2.0-008/lib/em64t' ./configure

on juliana (lenngren), using pg compiler
env CC=pgcc CXX=pgCC CFLAGS='-fastsse' CXXFLAGS='-fastsse' LIBS='-L/pdc/vol/mkl/7.2.0-008/lib/em64t -lmkl_lapack -lmkl_em64t -lguide -lpthread -Wl,--rpath,/pdc/vol/mkl/7.2.0-008/lib/em64t' ./configure

on sarek.hpc2n.umu.se, linking with LAPACK:
env LIBS='-L/usr/lib/atlas -llapack -lblas' ./configure

on sarek.hpc2n.umu.se with pgi compiler, linking with LAPACK:
module add pgi
env CC=pgcc CXX=pgcpp CFLAGS='-fast' CXXFLAGS='-fast' LIBS='-L/usr/lib/atlas -llapack -lblas' ./configure

on sarek.hpc2n.umu.se with pathscale compiler, using goto blas:
module add psc
env CC=pathcc CFLAGS=-O3 CXX=pathCC CXXFLAGS=-O3 LIBS='-lgoto -llapack -lgoto' ./configure --disable-critical-warnings

on akka.hpc2n.umu.se using gcc with openmp and goto blas:
env CXXFLAGS='-O3 -fopenmp' LDFLAGS='-fopenmp' LIBS='/home/e/elias/ergosvn/ergo/goto/GotoBLAS2/libgoto2_penryn-r1.11p1.a -lgfortran' ./configure

on akka.hpc2n.umu.se using icc version 10.1 with openmp and goto blas:
module load intel-compiler/10.1
Change 2010-09-12: now it seems to work with the latest icpc (11.1) also:
module load intel-compiler
env CXX=icpc CXXFLAGS='-O3 -openmp' CC=icc CFLAGS='-O3 -openmp' LDFLAGS='-openmp' LIBS='/home/e/elias/ergosvn/ergo/goto/GotoBLAS2/libgoto2_penryn-r1.11p1.a -lgfortran' ./configure

on sgi3k, to get 1e-33 precision:
env CC=c99 ./configure --with-precision=l

on sgi3k, linking with LAPACK
env CC=c99 LIBS=-lcomplib.sgimath ./configure

on mozart.nsc.liu.se, with LAPACK
env LIBS="-L$MKL_ROOT -lmkl_lapack" ./configure

on mozart.nsc.liu.se, using "home-made" gcc 4.2 with openmp
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/y_eliru/gcc/installdir/lib
env CC=/home/y_eliru/gcc/installdir/bin/gcc CFLAGS='-O3 -fopenmp' CXX=/home/y_eliru/gcc/installdir/bin/g++ CXXFLAGS='-O3 -fopenmp' LDFLAGS='-fopenmp' LIBS="-lm -lmkl_lapack -lmkl -lpthread -L/usr/local/intel/mkl/8.0.1/lib/64 -lmkl_lapack -L/home/y_eliru/gcc/installdir/lib" ./configure

on AIX/OSX:
CC=xlc CFLAGS="-O3 -qstrict -qlanglvl=stdc99" ./configure

to choose precision: (choices are short, double, long)
./configure --with-precision=l

on zeta (athlon, gcc-4.1)
LDFLAGS="-static  -L/home/pawsa/archive/Linux_HAMMER64SSE2_2/lib" LIBS="/usr/lib64/liblapack.a -lpthread -lblas -lgfortran" CFLAGS="-O3 -ftree-vectorize -std=c99" CXXFLAGS=-O3 ./configure

To get all compiler warnings both for c and c++ code:
env CC='gcc -Wall' CXX='g++ -Wall' ./configure

on 32GB mem Itanium computer at PDC (luc2):
module add i-compilers/9.1.042
env CC=icc CFLAGS='-O2 -ip -restrict' LIBS='-L/pdc/vol/mkl/7.2.0-008/lib/64 -lmkl_lapack -lmkl -lguide -lpthread -Wl,--rpath,/pdc/vol/mkl/7.2.0-008/lib/64' ./configure

on 32GB mem Itanium computer at PDC (luc2), using gcc version 4.2 with OpenMP:
module add gcc/4.2.pre20070501
env CC=gcc CFLAGS='-O3 -fopenmp' CXX=g++ CXXFLAGS='-O3 -fopenmp' LDFLAGS='-fopenmp' LIBS='-lm -lmkl_lapack -lmkl -lpthread -L/pdc/vol/mkl/8.0.019/lib/64 -lmkl_lapack -lpthread -Wl,--rpath,/pdc/vol/mkl/8.0.019/lib/64 -Wl,-rpath -Wl,/pdc/vol/gcc/4.2.pre20070501/lib -lgomp' ./configure

on neolith.nsc.liu.se using gcc v 4.1.1 with OpenMP:
env CC=gcc CFLAGS='-fopenmp -O3' CXX=g++ CXXFLAGS='-fopenmp -O3' LDFLAGS='-fopenmp' LIBS='-lm -L/software/intel/cmkl/9.1/lib/em64t -lmkl_lapack -lmkl -Wl,-rpath=/software/intel/cmkl/9.1/lib/em64t' ./configure

on neolith.nsc.liu.se using icc v 9.1:
module add icc/9.1.051
env CC=icc CFLAGS='-O3' CXX=icpc CXXFLAGS='-O3' LIBS='-lpthread -L/software/intel/cmkl/9.1/lib/em64t -lmkl_lapack -lmkl -Wl,-rpath=/software/intel/cmkl/9.1/lib/em64t' ./configure

on neolith.nsc.liu.se using icc v 10.1 and MKL:
module load icc/10.1
module load mkl
env CC='icc -Nmkl' CFLAGS='-openmp' CXX='icpc -Nmkl' CXXFLAGS='-openmp' ./configure

on kappa.nsc.liu.se using icc v 12.0 and MKL (this worked 2011-07-21):
module load icc/12.0.3
module load mkl/10.3.3.174
env CC='icc -Nmkl' CFLAGS='-openmp' CXX='icpc -Nmkl' CXXFLAGS='-openmp' LDFLAGS='-lmkl_intel_lp64 -lmkl_sequential -lmkl_core' ./configure --disable-critical-warnings

on 256 GB mem Itanium computer at PDC (key) using icc and OpenMP:
module add i-compilers/10.1.2008-02-07
env CC=icc CFLAGS='-O2 -ip -restrict -openmp' CXX=icpc CXXFLAGS='-O2 -ip -restrict -openmp' LIBS='-L/pdc/vol/mkl/7.2.0-008/lib/64 -lmkl_lapack -lmkl -lguide -lpthread -Wl,--rpath,/pdc/vol/mkl/7.2.0-008/lib/64' ./configure

on juliana (lenngren), using icc 10.1, openmp and mkl 8.0. 
env CC=icc CFLAGS='-O2 -ip -restrict -openmp' CXX=icpc CXXFLAGS='-O2 -ip -restrict -openmp' LIBS='-L/pdc/vol/mkl/8.0.019/lib/em64t -lmkl_lapack -lmkl_em64t -lguide -lpthread -Wl,--rpath,/pdc/vol/mkl/8.0.019/lib/em64t' ./configure

on isis.uppmax.uu.se, using gcc version 4.3.2 and own downloaded ACML:
env CC=gcc CXX=g++ CFLAGS='-fopenmp -O3' CXXFLAGS='-fopenmp -O3' LIBS='-L/bubo/home/h20/eliasr/acml/installation/gfortran64/lib -static -lacml -lgfortran' ./configure

on kalkyl.uppmax.uu.se using gcc 4.4.2 with OpenMP and Goto BLAS:
module load gcc
env CXXFLAGS='-O3 -fopenmp' LDFLAGS='-fopenmp' LIBS='/bubo/home/h20/eliasr/goto/GotoBLAS2/libgoto2.a -lgfortran' ./configure
(Not so good performance for OpenMP matrix stuff, probably due to gcc openmp having much initilization overhead.)

on kalkyl.uppmax.uu.se using icc 10.1 with OpenMP and Goto BLAS (Goto compiled with gcc 4.4.2):
module load intel/10.1
Change 2010-09-12: now it seems to work with the latest icpc (11.1) also:
module load intel
env CXX=icpc CXXFLAGS='-O3 -openmp' LDFLAGS='-openmp' LIBS='/bubo/home/h20/eliasr/goto/GotoBLAS2/libgoto2.a -lgfortran' ./configure
(Better performance for OpenMP matrix stuff, probably due to icc openmp having less initilization overhead.)

on kalkyl using MKL:
module load intel 
env CXX=icpc CXXFLAGS='-O3 -openmp' LDFLAGS='-openmp -mkl' ./configure --disable-critical-warnings
( we should really fix it so the --disable-critical-warnings is not needed. )

on lindgren (Cray machine at PDC) with Intel compiler
module swap PrgEnv-pgi PrgEnv-intel
module load xt-libsci fftw
env CC=cc CFLAGS=-openmp CXX=CC CXXFLAGS=-openmp ./configure --disable-critical-warnings
(with module load perftools this gives internal compiler error)

on lindgren (Cray machine at PDC) with gnu compiler and profiling
module swap PrgEnv-pgi/3.0.20 PrgEnv-gnu/3.0.20
module swap gcc/4.5.0 gcc/4.4.3
env CC=cc CFLAGS='-fopenmp -O3' CXX=CC CXXFLAGS='-fopenmp -O3' LDFLAGS=-fopenmp ./configure --disable-critical-warnings --enable-linalgebra-templates
module load perftools
make clean && make

on ferlin.pdc.kth.se
module load i-compilers/11.1 mkl/11.1
env CC=icc CFLAGS='-O2 -ip -restrict -openmp' CXX=icpc CXXFLAGS='-O2 -ip -restrict -openmp' LDFLAGS='-L/pdc/vol/i-compilers/11.1/icc/mkl/lib/em64t -lmkl_intel_lp64 -lmkl_sequential -lmkl_core -lpthread -Wl,--rpath,/pdc/vol/i-compilers/11.1/icc/mkl/lib/em64t' ./configure --disable-critical-warnings

on a machine with gcc as default compiler and where blas+lapack are installed, with OpenMP:
env CXXFLAGS='-O3 -fopenmp' LDFLAGS='-fopenmp' ./configure


Known bugs

When configured with --enable-linalgebra-templates the code does not work if threads are used in the matrix library. It seems that the linalg template code is not thread safe. This should be fixed.
Generated on Mon Sep 17 14:30:39 2012 for ergo by  doxygen 1.4.7