C++QEDv2 depends on a number of open-source libraries:
provide indispensable extensions to the C++ standard, and are de facto standard by their own right. The framework depends on a number of them, the most notable ones being Fusion, Lambda, MPL, Operators, and Preprocessor. On many systems, (a selection of) the Boost libraries are available. They are packaged for Debian and Mac OS X. Alternatively, they can be downloaded and installed from the main Boost portal. Although version 1.43 is in principle sufficient for the framework, it is advisable to use as new a version as possible, since experience has shown that there can be clashes between old versions of Boost and new versions of compilers, especially when template metaprogramming is concerned.
All the Boost libraries necessary for the framework are header-only (except when using serialization that requires the binary Boost.Serialization). Therefore, we also provide an alternative package in which the Boost dependencies are placed in a subdirectory under utils/include. When using this package, no separate Boost libraries need to be installed. Cf. Sec. Boost integration.
For many systems, optimized versions of these libraries exist and are even preinstalled. As a fallback, the reference implementation can always be used, which is packaged e.g. for Ubuntu.
On using the framework without these, cf. Compiling with or without FLENS.
These three are best installed on system level.
The following two libraries are stable, but under more or less steady development.
provides the fundamental data structure. It hence performs a lot of numerics and lies at the absolute heart of the framework. Blitz++ lives up to its name, as it provides near-Fortran performance in spite of the very high-level abstractions used in the library. This is achieved by TMP, which was discovered in prototype during the development of this very library. More on the Blitz++ homepage.
The present release of Blitz++ is 0.10, and I try to keep the framework compatible with this.
is a very impressive effort to wrap BLAS-LAPACK functions in a high-level C++ interface. FLENS in turn depends on BLAS-LAPACK (ATLAS). More on the FLENS homepage. BLAS-LAPACK funcionality is accessed only through this library in the framework.
The use of FLENS (and hence, BLAS-LAPACK) is optional because only a very small tract of the framework depends on it. Cf. the section Compiling with or without FLENS.
At the corresponding websites, instructions for installing the libraries can be found, while below I have given guidelines concerning installation on an Ubuntu system, cf. also the getLibs.sh script in directory utils. This will download the Mercurial/CVS versions of both libraries into the subdirectories blitz and FLENS-lite, respectively, and will also compile them.
I will very much appreciate all feedback regarding also the installation of the framework.
The following is a rudimentary list of prerequisite packages on Ubuntu 12.04 (on Ubuntu 10.04 use libatlas-headers instead of libatlas-dev, on other distributions install equivalent packages):
% sudo apt-get install cmake libboost-all-dev autoconf automake libtool libgsl0-dev liblapack-dev \
liblapack-pic liblapack3gf libblas-dev libblas3gf libatlas-dev libatlas3gf-base bzr
This will install the first three libraries listed above on system level.
The following steps to install the remaining two libraries constitute also the script utils/getLibs.sh. Calling the script will install the libraries beneath /usr/local (using sudo). You can also install the libraries locally by calling the script as utils/getLibs.sh local.
Either download the Blitz 0.10 tarball from the SourceForge website followed by
tar -xzf blitz-0.10.tar.gz
cd blitz-0.10
or obtain the Mercurial version
hg clone http://blitz.hg.sourceforge.net:8000/hgroot/blitz/blitz
cd blitz
autoreconf -fiv
In both cases use
./configure --with-pic [--enable-serialization]
make lib
sudo make install
Under Debian- or Redhat-like operating systems, instead of the last line one can use:
sudo checkinstall -D --install=no --pkgname blitz-mercurial --pkgversion 0.10.0-20120613-hg-1 --provides blitz-mercurial --replaces blitz-cvs make install
Note
The use of FLENS is optional because only a very small tract of the framework depends on it. Cf. the section Compiling with or without FLENS.
cvs -d:pserver:anonymous@flens.cvs.sourceforge.net:/cvsroot/flens login
Hit enter when prompted for password.
cvs -z3 -d:pserver:anonymous@flens.cvs.sourceforge.net:/cvsroot/flens co -P FLENS-lite
cd FLENS-lite
cp config.ubuntu config
Now you have to edit the config file adding to CXXFLAGS the flag -DGSL_CBLAS which instructs FLENS to use the CBLAS interface provided by GSL. This is good because hence you don’t need a separate package for this. You may also need to remove the flag -latlas from LDFLAGS.
make
sudo make install
If the last command issues the error message:
Makefile.common:19: /config: No such file or directory
you have to edit Makefile.common replacing the variable $(PWD) with the path of the current directory.
Alternatively, again:
sudo checkinstall -D ... make install
Note
By default, FLENS gets installed as a shared library under /usr/local/lib. If this was not in the dynamic loader’s path previously, the ldconfig utility has to be used as superuser.
There are two ways, the first being to download the latest package from http://sourceforge.net/projects/cppqed/files/. This is only recommended if the package is not too old.
The other is to use the Bazaar version:
bzr checkout bzr://cppqed.bzr.sourceforge.net/bzrroot/cppqed C++QED
Where the last argument can be replaced with the name of the directory for the code to appear in. Alternately, an existing checkout can be updated as:
bzr pull bzr://cppqed.bzr.sourceforge.net/bzrroot/cppqed
Be aware that C++QED is under development, so changes in the Bazaar version may change the API of certain modules in such a way as breaks your applications. It is advisable to follow the ChangeLog of the project. Alternately, the Bazaar option -r date:<date> can be used to retrieve the most recent revision no later than <date>. E.g.:
bzr pull -r date:2010-02-14 bzr://cppqed.bzr.sourceforge.net/bzrroot/cppqed
To obtain the package with the necessary Boost libraries integrated, download the package file with ...BoostIntegration... in its name. To get the development version, the corresponding Bazaar branch is to be used:
bzr checkout bzr://cppqed.bzr.sourceforge.net/bzrroot/cppqed/BoostIntegration C++QED
In this version, binary i/o is not possible.
Since the CVS version of Blitz++ is expected to be around for quite some while yet, we provided a (frozen) branch
bzr://cppqed.bzr.sourceforge.net/bzrroot/cppqed/BlitzCVS_compatibility
which remains compatible with this Blitz++ version. This branch corresponds to main trunk #218, and binary i/o is not possible (because Boost.Serialization compliance is not included in this Blitz++ version).
For users this is the preferred way to compile the framework. CMake is a cross-platform build system which checks the system for the location of required and optional dependencies and enables/disables features based on what is found. It is similar to the usual GNU autotools (aka ./configure; make; make install) and furthermore offers easy integration into popular IDE‘s, e.g. Eclipse, kdevelop or Xcode.
Make sure CMake is installed on your system (at least version 2.6-patch4 is required). Under the top level C++QED directory, create a build directory (e.g. build)
mkdir build; cd build
Next, configure the build system by invoking cmake
cmake -DCMAKE_BUILD_TYPE=<type> ..
where <type> is either debug or release. In debugging mode, a lot of runtime checks are compiled into the framework, which come from Blitz++, FLENS, and C++QED proper. Every time a new script is added it should be compiled and tested in this way because this can detect a lot of errors. When we are absolutely sure that everything is all right, for data collection we may compile in release mode, where all the checks are omitted and optimisations are used, making the programs about an order of magnitude faster. To switch the build type create a new build directory or call cmake again with different <type> parameter.
Warning
Maximum efficiency is achieved only if the build system is configured with
cmake -DCMAKE_BUILD_TYPE=release ..
If CMake fails to locate a dependency, it will inform the user about the disabled feature or fail if the library was required. If some libraries are installed in non-standard locations, the user has to specify the directory with -DCMAKE_PREFIX_PATH="/some/path;/some/other/path". This will look for libraries in /some/path/lib, /some/other/path/lib and for include files in /some/path/include, /some/other/path/include. It is also possible to specify additional library paths and include paths separately with -DCMAKE_LIBRARY_PATH= and -DCMAKE_INCLUDE_PATH=.
Note
CMake caches all detected library locations. If you want to be sure that the library checks are performed, you have to delete the file CMakeCache.txt before calling cmake again.
Note
Every time a new script is added to the scripts directory, cmake needs to be invoked to create the target for the new script.
Note
On Mac OS X be sure to set the environment variable CXX to g++, otherwise cmake might pick up the clang compiler:
CXX=g++ cmake ...
The configuration step will generate all necessary Makefiles beneath the build directory. In order to compile the whole framework and all scripts, type
make
For parallel compilation use the option -j n to have n simultaneous compilation threads. Every script in the scripts directory has its own target, so it is possible to call
make <script-name-without-extension>
to compile only a single script.
Using an IDE can make the development of scripts much more convenient. CMake has generators for project files of several popular IDE‘s, check the CMake man page to see which are supported on your system. For example, to generate an Eclipse CDT project, call
cmake -G "Eclipse CDT4 - Unix Makefiles"
in the C++QED root directory (add -DCMAKE_PREFIX_PATH if needed). This will generate the necessary Eclipse project files, afterwards you can import the project into Eclipse by choosing “File->Import->Existing Project into workspace”. See the CMake wiki for details.
For kdevelop3 use the -G Kdevelop3 generator. For kdevelop4 you can just open the top level CMakeLists.txt file as a project.
Under Mac OS X the -G Xcode generator will create a project which can be opened by Xcode.
This is the compilation method intended mostly for developers. On Ubuntu 12.04 Boost.Build is installed together with libboost-all-dev, on Ubuntu 10.04 you have to install the package bjam. Typing
bjam
in the main directory will compile and link the whole framework in debugging mode, creating separate executables from the highest-level programs residing in directory scripts. Typing
bjam <script-name-without-extension>
will compile only the given script.
The default compilation mode is debugging mode, meaning that in this case a lot of runtime checks are compiled into the framework, which come from Blitz++, FLENS, and C++QED proper. Every time a new script is added it should be compiled and tested in this way because this can detect a lot of errors. When we are absolutely sure that everything is all right, for data collection we may compile with bjam release, where all the checks are omitted and optimisations are used, making the programs about an order of magnitude faster.
Warning
Maximum efficiency is achieved only if the framework is compiled with
bjam release
or
bjam <script-name-without-extension> release
bjam will put the compiled files into the directories bin and utils/bin. These directories are the roots of directory structures which mirror the structure of the distribution.
Boost.Build, just like make, supports parallel compilation, which can make a significant difference for projects of the magnitude of C++QEDv2. For starting n threads of compilation use
bjam -j n ...
If you have libraries and include files in non-standard directories, you can point bjam to the location by adding something like this to your ~/user-config.jam (create the file if it doesn’t exist) or /etc/site-config.jam file:
local PREFIX = /some/library/prefix/path ;
project genconfig : requirements
<include>$(PREFIX)/include
<library-path>$(PREFIX)/lib
<include>/some/other/include/path
<library-path>/some/other/library/path
;
C++QEDv2 is in principle cross-platform. It has been successfully compiled on several Linux platforms and Mac OS X (cf. section below) with the GNU C++ Compiler. It also compiles with the clang++ compiler and Intel compiler version 12.1.
Without FLENS, those parts of the framework that rely on FLENS are discreetly disabled. Most notable is the calculation of the negativity of partially transposed density operators, cf. Assessing entanglement. The file utils/src/DrivenDampedHarmonicOscillator.cc is also basically disabled, so that DrivenDampedHarmonicOscillator becomes unusable.
Note
Scripts depending directly on FLENS will not compile in this case.
CMake compiles the framework with FLENS support automatically if the library is detected. To override this behavior, call CMake with the -DFLENS=off option.
There is a compilation feature that can be supplied to Boost.Build:
bjam with-flens=no <all the rest as before>
This toggles the possibility of binary state-output for MCWF_Trajectory, and, in turn, binary dependence on Boost.Serialization. This requires two things:
- The presence of this library in shared-object form at a place search by ld (or at a place where CMake will find it).
- Blitz++ must be configured with the --enable-serialization switch (this is present in the 0.10 release and the Mercurial version, but not in the CVS version).
Note
This compilation feature is not present either in the BoostIntegration branch, where header-only dependence on Boost is strictly observed, or in the BlitzCVS_compatibility.
CMake will automatically enable binary i/o support if Boost.Serialization is available and if Blitz++ was configured with --enable-serialization. To override this behavior, call CMake with the -DSERIALIZATION=off option.
To enable binary i/o, call bjam with the compilation feature
bjam enable-binary-output=yes <all the rest as before>
With Boost.Build, profiling (e.g. with gprof) will never work in release mode because in this mode it automatically adds the --strip-all option to ld, which removes the symbols necessary for profiling.
Therefore, for profiling, the profile variant has to be used. Type:
bjam profile <script-name-without-extension>
The Makefile also provides the pertaining option. Type:
make profiling=yes <script-name-without-extension>
Note
With make, be sure that the whole framework gets recompiled. bjam will anyway put the binaries into separate directories.
Compilation of C++QED under Mac OS X is straightforward once you have installed the developoment toolchain and the prerequisite libraries.
The toolchain can be obtained from the Apple Developer site (you need to register an Apple ID).
For Mac OS X 10.6 installing Xcode 3 (~4 GB) seems to be the only consistent way to obtain a complete toolchain for Unix development.
Starting with Mac OS X 10.7 you have the choice to install either the complete Xcode 4 suite (~1.8 GB) or just the command line tools for Xcode (~136.37 MB). The latter will provide everything you need to compile C++QED, whereas the graphical tools (most notable Xcode itself) are not included.
The easiest way to satisfy the dependencies is to use Homebrew, a package manager for Mac Os X. Optionally, if you are already using MacPorts it is also possible to install the dependencies with port analogously to the method described here.
Install Homebrew and don’t forget to run brew update afterwards.
Install GSL, Boost, CMake, Mercurial and Bazaar:
brew install gsl boost cmake mercurial bazaar
Note
In the present case, the apple darwin version of gcc-4.2 was present on the system, so GSL and all the following will be compiled with this.
Optional: If you want binary i/o, call brew edit blitz and add the line "--enable-serialization", to the ./configure command line.
Install the mercurial version of Blitz++ with:
brew install blitz --HEAD
Checkout C++QED:
bzr checkout bzr://cppqed.bzr.sourceforge.net/bzrroot/cppqed C++QED
From here, follow the CMake instructions (and don’t forget to set CXX=g++ when calling cmake, c.f. the note in the Cmake section). Note that it is possible to import the project into Xcode.
Note
The compilation of the scripts 2particles1mode, Ca40InCavity, QbitMode_Matrix and MLJC is disabled with gcc-4.2 because it implements an older C++ standard and would fail on these. Although it is easy to adjust them for gcc-4.2, it was chosen not to keep all scripts compatible with this relatively old compiler but rather to disable the problematic scripts.
Note
Building the framework with Boost.Build is not supported at the moment on Mac OS X due to problems with Boost.Build and search paths hard coded in shared libraries.