"NRG Ljubljana" is a flexible framework for performing large scale numerical
renormalization group (NRG) calculations for quantum impurity problems. It
is highly extensible without sacrificing numerical efficiency.

Copyright (C) 2006, 2007 Rok Zitko


Framework "NRG Ljubljana" is a set of interrelated computer codes for
performing numerical renormalization group (NRG) calculations for
quantum impurity problems, described by models such as the Kondo
exchange (s-d) model or the Anderson single impurity model, and their
multi-impurity and multi-channel generalizations. It also contains a
number of tools for analyzing results (thermodynamic properties, such
as magnetic and charge susceptibility, entropy and heat capacity;
expectation values of arbitrary operators; spectral functions). It is
user friendly, in the sense that it is easy to set up new types of
problems (Hamiltonians, perturbation terms, etc.) and the output is
formatted and annotated for easy interpretation, parsing and
plotting. Currently it handles problems with the following symmetries:

    * Well defined charge, Q, and spin projection, Sz, quantum
numbers, i.e. U(1)xU(1) symmetry suitable for problems in the presence
of magnetic field.

    * Well defined charge, Q, and total spin, S, quantum numbers,
i.e. U(1)xSU(2) symmetry for problems in the absence of magnetic
field.

    * Well defined isospin (axial charge), I, and total spin, S,
quantum numbers, i.e. SU(2)xSU(2) symmetry for problems at the
particle-hole symmetric point in models with bipartite lattice.

    * In addition, for two-channel quantum impurity problems with
mirror (left-right) symmetry, that are common in the problems related
to the impurity models of clusters of coupled quantum dots (such as
double quantum dots and triple quantum dots embedded between a source
and drain electrodes), the Z2 relection symmetry (parity) is also
taken into account to further accelerate the calculation.

To achieve a high degree of flexibility without sacrificing numerical
efficiency, "NRG Ljubljana" is composed of a hierarchy of modules:
high level modules are written in a mixture of functional and
procedural Mathematica code, while the low level numerically intensive
parts are programmed in the object oriented approach in the C++
language. The foundation of the framework is a Mathematica package for
performing calculations with non-commutative second quantisation
operators, SNEG. Next layer is a Mathematica program which defines the
Hamiltonian, the basis of states, and the physical operators of
interest: with the help of SNEG, Hamiltonian and operators can be
defined using the familiar second-quantization expressions. This
program performs the diagonalization of the initial Hamiltonian and
prepares the input for the NRG iteration proper.

For efficiency, NRG iteration is performed by a separate C++ program:
for a typical problem, most of the time (90%) is spent in the LAPACK
dsyev routine which solves the eigenvalue problem. There is very
little housekeeping overhead due to the tasks required by the NRG
iteration; "NRG Ljubljana" is thus suitable for performing large scale
NRG calculations on computer clusters.



1. Features

- all parameters configurable at run-time, no need to recompile
  for different runs
- (Q,S_z), (Q,S), (I,S), (Q,S_z,P), (Q,S,P), (I,S,P) subspaces
- DM-NRG in (Q,S) and (Q,S_z) subspaces
- sum-rule conserving spectral function calculations (full density
matrix NRG, FDM-NRG, or complete Fock space NRG, CFS-NRG)
- self-energy trick for (Q,S)
- arbitrary number of channels, currently 1 or 2, but easily expandable
- flexibility in definition of the Hamiltonian, which is simply
  written using a second-quantization operator expression
- automatic exact diagonalisation of the initial Hamiltonian with
  automagic generation of the (Q,S) (or some other) basis
- flexibility in the choice of operators whose thermodynamical averages
  are computed, they can be expressed using operators of second
  quantization
- dynamic spin susceptibility, dynamic charge susceptibility, etc.
- multiple logarithmic discretization schemes (Wilson/Krishnamurthy,
  Yoshida/Whitaker/Oliveira, Campo/Oliveira)
- support for non-flat bands (i.e. cosine band that arrises from
  tight-binding description of leads in quantum transport problems,
  or arbitrary hybridization as needed in DMFT), see dmft.m
- heavily commented code with reference to original publications of
  formulas and approaches used
- object-oriented code for easy maintenance and expandability
- FAST!: very high numeric efficiency with optimized-for loops in the most
  numerically demanding parts of the code (chiefly the recalculation
  of irreducible matrix elements of operators)
- N/N+2 trick in calculation of spectral densities
- amount of verbosity in log files is configurable
- mixed spectral densities (i.e. out-of-diagonal elements of retarded 
  Green's functions)
- automatic recording of time elapsed in various parts of the program
- monitoring of memory use
- formated output files for easy interpretation of the results
  (for example, headers with parameters and heading lines in tables
  with operator names)
- internal consistency checks, assertions, parameter compatibility
  and reasonableness checks that reduce the possibility of undetected
  bugs
  


2. Applications

The "NRG Ljubljana" was used for NRG calculations that led to the
publication of the following papers:

    * Correlation effects in side-coupled quantum dots
      R. Zitko, J. Bonca
      J. Phys.: Condens. Matter 19 255205 (2007)
    * Spin-charge separation and simultaneous spin and charge Kondo effect 
      R. Zitko, J. Bonca
      Phys. Rev. B 74, 224411 (2006).
    * Spin qubits in double quantum dots - entanglement versus the Kondo effect
      A. Ramsak, J. Mravlje, R. Zitko, J. Bonca
      Phys. Rev. B 74, 241305(R) (2006).
    * Fermi-liquid versus non-Fermi-liquid behavior in triple quantum dots
      R. Zitko, J. Bonca
      cond-mat/0606287. Accepted in Phys. Rev. Lett.
    * Multi-impurity Anderson model for quantum dots coupled in parallel
      R. Zitko, J. Bonca
      Phys. Rev. B 74, 045312 (2006).
    * Enhanced conductance through side-coupled double quantum dots
      R. Zitko, J. Bonca
      Phys. Rev. B 73, 035332 (2006).

If you use "NRG Ljubljana" in research, let us know of the relevant
published works to include them in this list.



3. Documentation

PDF versions of the manual is included in the distribution. See directory
doc/.

Check regression/ for sample calculations (tests).
A number of examples can be found in the directory examples/.


4. License

   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 2 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, write to the Free Software
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

The full text of the GPL General Public License can be found
in file LICENSE.


5. Compiling and dependencies

Currently, "NRG Ljubljana" had been used only on Linux workstations and
clusters. Distributions, where it had been tested, are Red Hat Linux 9, Red
Hat Enterprise Linux 3, Ubuntu 5.10 and Ubuntu 6.06. It should work on any
modern Linux distribution and, with some tweaking, on any Unix or Unix-like
operating system with a good standards-compliant C++ compiler.

The following libraries are required to compile the C++ part of the
NRG code:

    * LAPACK and BLAS linear algebra libraries - tested with (free)
Atlas, version 3.0, and (commercial) Intel's Math Kernel Library
(MKL), version 8.0.
    * MathLink library for interfacing C program with Mathematica
program - this library is a part of the (commerical) Mathematica
distribution. The version included in Mathematica 5.1 for Linux had
been used.
    * boost C++ libraries, in particular the uBLAS library - versions
1.32 and 1.33 are known to work
    * glib 2 - usually included with every Linux distribution (tested
with Ubuntu 5.10, Ubuntu 6.06 and RedHat 9) - parameter parsing and
timing routines from this library are used. [Version 2.6+ required!]
    * GNU scientific library (GSL) - version 1.6 is known to work.

Due to the heavy use of template metaprogramming (in particular in the
uBLAS library), a high-quality standards-compliant C++ compiler must
be used. GNU Compiler Collection (gcc) g++ version 4.0.2 and Intel C++
Compiler 9.0 (20051020) are known to successfully compile the
code. Binaries produced by Intel's compiler are significantly faster
(by up to 40%, depending on the problem considered and the
optimisations used in the compilation). Likewise, the Intel MKL
library is faster than the Atlas library.

Wolfram Reasearch Mathematica must be installed for running the
Mathematica part of the NRG code. Versions 5.0, 5.1 and 5.2 have been
tested. Mathematica is only required for the initialization of the
problem (basis construction, diagonalisation of the initial
Hamiltonian, transformations of the operator matrices, etc.) which is
relatively fast. When "NRG Ljubljana" is used on a cluster, it is
therefore sufficient to have Mathematica installed on a single
computer (for example on the cluster host computer), while the
numerically demanding (C++) part of the program can be ran on the
cluster nodes.


5.1. Required Ubuntu packages

If Ubuntu is used, the required libraries are provided by the following
packages (apt-get install <package names>):

- build-essential
- atlas3-base, atlas3-base-dev, atlas3-headers
- libgsl0
- libboost-dev
- libglib2.0-dev

Instead of atlas3, you might use lapack3, lapack3-dev, refblas3,
refblas3-dev.

Other recommended packages are:

- atlas3-doc, atlas3-test, atlas3-sse | atlas3-sse2
- libgsl0-dbg
- libboost-doc

The same package names (probably) apply for Debian GNU/Linux as well.


5.2. Quick start

a) ./configure --with-mathlink=<dir>
   where <dir> is the path to the directory where MathLink is located.
   Mathematica comes with a copy of MathLink. My is located under
   /usr/local/Wolfram/Mathematica/5.1/AddOns/MathLink/DeveloperKit/Linux/CompilerAdditions.
   Alternatively, you can grab a copy of MathLink for Wolfram's web site
   and install it locally in your home directory.

a1) If required libraries are missing, configure will detect this. Install
    them (see 5.1) and try running configure again until it finds everything.

b) make
   This will produce executables in directory src/.
 
c) Open initial.m in an editor and modify modulespath if necessary.
 
d) make quicktest
   This will run a NRG calculation and compare results with known results.
   Note that it is possible that due to numerical roundoff errors and
   different implementations of dsyev and dsyevr routines (for example,
   atlas versus Intel MKL) slightly different result will be found.
   This is expected and quite normal.

If you get stuck at some step, contact me via e-mail (rok.zitko@ijs.si) and
I will try to assist you.


5.3 Using custom glib-2

If you compiled and installed custom glib-2 under your home directory, you
will have to ensure that pkg-config finds the newest version by adding
~/lib/pkgconfig directory to PKG_CONFIG_PATH environment variable.
If using bash as a shell, you can make this permanent by adding the
following two lines to your .bash_profile:

PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$HOME/lib/pkgconfig
export PKG_CONFIG_PATH


6. Contributing to "NRG Ljubljana"

If you make improvements to "NRG Ljubljana", you are encouraged to
share them with other users. Bug reports (and fixes) are very welcome
as well.  The contact information is in the next section.

Interesting directions for possible further extensions are the direct
computation of self-energies; full Fock space NRG and time-dependent NRG;
optimizations in the most time consuming parts of the program
(diagonalization); improved documentation.



7. Contact information:

"NRG Ljubljana" home-page: http://nrgljubljana.ijs.si/

Rok Zitko
"Jozef Stefan" Institute
F5 - Condensed matter physics
Jamova 39
SI-1000 Ljubljana
Slovenia

rok.zitko@ijs.si


8. Acknowledgements 

The "NRG Ljubljana" framework is being developed during author's PhD
studies at the Faculty for mathematics and physics of the University
of Ljubljana, and the "Jozef Stefan" Institute, Ljubljana,
Slovenia. Discussions and collaboration with prof. Janez Bonca,
prof. Anton Ramsak, Jernej Mravlje and dr. Tomaz Rejec from the F1,
Theoretical Physics department are acknowledged.
