Blitz++: Introduction

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 1. Introduction

> 1.1 About this document |  |
> 1.2 Platform notes |  | Supported platforms
> 1.3 How to download Blitz++ |  | Where to download Blitz++?
> 1.4 Installation and porting |  | How to install Blitz++?
> 1.5 Compiling with Blitz++ |  | How to compile a program that uses Blitz++
> 1.6 Licensing terms |  | License considerations
> 1.7 Mailing lists and support |  | How to get help?

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.1 About this document

To use the Blitz++ library, you will need a compiler with near-ISO/ANSI C++ syntax support (see the following section for possible compilers). Information on what platforms are supported is available from http://oonumerics.org/blitz/platforms/. To download Blitz++, please go to the download page at http://oonumerics.org/blitz/download/.

If you need to do something that Blitz++ doesn't support, see a possible improvement, or notice an error in the documentation, please send a note to one of the Blitz++ mailing lists (described later).

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.2 Platform notes

For up-to-date information on supported platforms, please consult the Blitz++ web page:

http://oonumerics.org/blitz/platforms/

The information in this document may be out of date.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.2.1 KAI C++

Blitz++ was developed and tested using KAI C++ under AIX. It should (in theory) port to other KAI C++ platforms (Cray, SGI, HP, Sun, Linux, Compaq) without difficulty. Since KAI C++ uses an EDG front end, other EDG front-ended compilers (e.g. Comeau) should be able to compile Blitz++.

Recommended compile flags are:

    +K3 -O2 --restrict --abstract_pointer --abstract_float -tused

Note that you cannot compile with `-tall` (this will generate lots of errors).

Under Linux, you may need the flag `-D__signed__=`. You should omit `-tused` since this template instantiation model is not supported by `gcc`, which is used as the back-end compiler.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.2.2 Intel C++

Blitz++ compiles under fairly recent versions of the Intel C++ compiler (version 7.1 or 8.x) for Linux platforms, as well as the comparable plug-in compiler for Windows that can be used within the Microsoft Visual Studio IDE.

More information:

http://www.intel.com/software/products/compilers/clin

http://www.intel.com/software/products/compilers/cwin

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.2.3 Microsoft VS.NET 2003

Blitz++ has been ported to the C++ compiler within the Microsoft VS.NET 2003 compiler and IDE package. A zip archive containing an appropriate configuration header file and project files for building the Blitz library and all of the testsuite codes. Previous versions of the Microsoft C++ compiler within Visual Studio do not have the required C++ features needed by Blitz++ and are not supported. Blitz can be compiled under Visual Studio by using the Intel plug-in C++ compiler for Windows.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.2.4 gcc

GCC (`g++`) is a free GNU C++ compiler. It compiles Blitz++ reliably; in fact, most Blitz++ development work is done with `g++`.

gcc may be downloaded from http://www.gnu.org/software/gcc/gcc.html.

If you are using gcc under Solaris, SunOS, or OSF/1, please see the ``README.binutils'` file included in the distribution.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.2.5 Metrowerks

Metrowerks is sort-of supported; see the platforms web page and the mailing lists for more information. Support for Metrowerks is no longer being actively maintained.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.2.6 Compaq cxx

The Compaq C++ compiler version 6.x is supported.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.2.7 Cray T3E/Cray T90/Cray C90/Cray J90

As of Version 0.2-alpha-02 of Blitz++, Version 3.0.0.0 of the Cray C++ compiler is supported (well, tolerated anyway). It seems to be based on an older version of the EDG front end, so some kludges are required. It doesn't support partial ordering of member templates, so slicing arrays requires the workaround described in Section 2.4.4 Slicing. Portions of the standard library are missing, such as `<limits>`, `<complex>`, and `<set>`. This means you won't be able to use complex numbers (well, not the ISO/ANSI C++ versions anyway), numeric inquiry functions, or fast traversal orders.

These compilation flags are recommended:

    -h instantiate=used

For optimization, you'll want:

    -O3 -h aggress

The ability of the Cray C++ compiler to optimize away temporary objects is disappointing. It's not able to optimize away expression templates overhead or comma-delimited array initializers. Please note that support for compiling Blitz++ under the Cray C++ compiler is no longer being actively maintained.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.3 How to download Blitz++

To download the Blitz++ library, go to the Blitz++ download page, at http://oonumerics.org/blitz/download/

But please read the section on supported platforms and compilers first.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.4 Installation and porting

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.4.1 Installation

Blitz++ uses GNU Autoconf, which handles rewriting Makefiles for various platforms and compilers. It has greatly simplified installation and porting. Many thanks for John W. Eaton and Brendan Kehoe for their help with this.

To install blitz, unpack the ``blitz-VERSION.tar.gz'` file (it will install into a subdirectory ``blitz-VERSION'`). For example:

    [tveldhui@n2001:~] 32: ls -l blitz*.gz
    -rw-r--r--   1 tveldhui users      480953 Jun 23 15:20 blitz-0.5.tar.gz
    [tveldhui@n2001:~] 33: gunzip blitz-0.5.tar.gz
    [tveldhui@n2001:~] 34: tar xvf blitz-0.5.tar
    blitz-0.5/CHANGELOG
    blitz-0.5/COPYING
    blitz-0.5/INSTALL
    blitz-0.5/Makefile.in
    blitz-0.5/README
    blitz-0.5/THANKS
      .
      .

Then go into the main blitz directory, and type:

    ./configure CXX=[compiler]

where [compiler] is one of `xlc++`, `icpc`, `xlC`, `cxx`, `aCC`, `CC`, `g++`, `KCC`, `pgCC` or `FCC`.

You can also specify special command-line options for your compiler, using this syntax:

    ./configure CXX=g++ CXXFLAGS="-ftemplate-depth-50"

If you are interested in benchmarking, you may want to use the option `--with-blas=...` to specify the path where the blas library is found. Run the configure script with the option `--help` to see all the available options.

Once the configure script is done, you can do any of these things:

`make lib`
  Check the compiler and create ``libblitz.a'`.

`make check-testsuite`
  Make the blitz library plus build and run the testsuite.

`make check-examples`
  Make the blitz library plus build and run the examples.

`make check-benchmarks`
  Make the blitz library plus build and run the benchmarks.

`make all`
  Do all of the above. This may take a long time.

`make install`
  Build the blitz library and documentation and install, along with the blitz header files, in prefix directory.

Building the benchmark programs requires both a Fortran 77 and Fortran 90 compiler.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.4.2 The Blitz++ directory tree

The main Blitz++ directory contains these subdirectories:

`blitz`
  Blitz++ headers and source code files

`random`
  Random number generators

`src`
  Source code for ``libblitz.a'`

`lib`
  Location of ``libblitz.a'`

`doc`
  Documentation in HTML and PostScript

`testsuite`
  Testsuite programs

`examples`
  Example programs

`benchmarks`
  Benchmark programs

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.4.3 Porting Blitz++

If you want to try porting Blitz++ to a new compiler or platform, I suggest the following approach:

- First check the Blitz++ web page to make sure you have the latest snapshot, and that someone hasn't already ported blitz to your platform.

- Install autoconf (from e.g. ftp://prep.ai.mit.edu/pub/gnu) if you don't have it already.

- Run the configure script with CXX=[compiler]. This will exercise your compiler to see what language features it supports. If it doesn't have member templates and enum computations, just give up. You may need to set CXXFLAGS to use compiler options that enable some language features.

- Once you know what compiler options are needed, you can make these the default settings for your C++ compiler. Make a backup of ``m4/ac_cxx_flags_preset.m4'`, and then edit the file to add an appropriate case for your compiler. Invoke autoconf to regenerate the configure script. Then try configure with your new preset flags.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.5 Compiling with Blitz++

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.5.1 Header files

Blitz++ follows an X-windows style convention for header files. All headers are referred to with a prefix of ``blitz'`. For example, to use the `Array<T,N>` class, one needs to include `<blitz/array.h>` instead of just `<array.h>`. To make this work, the main Blitz++ directory must be in your include path. For example, if Blitz++ was installed in ``/software/Blitz++'`, you will need to compile with `-I /software/Blitz++`.

If you have root privileges, you may want to put in a symbolic link from the standard include path (e.g. ``/usr/include/blitz/'`) to the `blitz` directory of the distribution. This will allow you to omit the `-I ...` option when compiling.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.5.2 Linking to the Blitz++ library

The Blitz++ library file ``libblitz.a'` contains a few pieces of global data. You should ensure that the ``lib'` subdirectory of the Blitz++ distribution is in your library path (e.g. `-L/usr/local/blitz-0.5/lib`) and include `-lblitz` on your command line. If you use math functions, you should also compile with `-lm`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.5.3 An example Makefile

Here is a typical skeletal Makefile for compiling with Blitz++ under gcc:

    # Path where Blitz++ is installed
    BZDIR = /usr/local/blitz

    CXX = g++

    # Flags for optimized executables
    # CXXFLAGS = -O2 -I$(BZDIR) -ftemplate-depth-30

    # Flags for debugging
    CXXFLAGS = -ftemplate-depth-30 -g -DBZ_DEBUG -I$(BZDIR)

    LDFLAGS =
    LIBS = -L$(BZDIR)/lib -lblitz -lm

    TARGETS = myprogram1 myprogram2

    .SUFFIXES: .o .cpp

    .cpp.o:
        $(CXX) $(CXXFLAGS) -c $*.cpp

    $(TARGETS):
        $(CXX) $(LDFLAGS) $@.o -o $@ $(LIBS)

    all:
        $(TARGETS)

    myprogram1:      myprogram1.o
    myprogram2:      myprogram2.o

    clean:
        -rm -f *.o $(TARGETS)

There are more example makefiles in the examples, testsuite, and benchmarks directories of the distribution.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.5.4 Explicit instantiation

It is not possible to do explicit instantiation of Blitz++ arrays. If you aren't familiar with explicit instantiation of templates, then this fact will never bother you.

The reason is that explicit instantiation results in all members of a class template being instantiated. This is not the case for implicit instantiation, in which only required members are instantiated. The `Array<T,N>` class contains members which are not valid for all types `T`: for example, the binary AND operation `&=` is nonsensical if `T=float`. If you attempt to explicitly instantiate an array class, e.g.

`template class Array<float,3>;`

then you will be rewarded with many compile errors, due to methods such as `&=` which are nonsensical for `float`.

As some consolation, explicit instantiation would not be much help with Blitz++ arrays. The typical use for explicit instantiation is to instantiate all the templates you need in one compilation unit, and turn off implicit instantiation in the others -- to avoid duplicate instantiations and reduce compile times. This is only possible if you can predict ahead of time what needs instantiation. Easy for simple templates, but impossible for classes like `Array`. Almost every line of code you write using `Array` will cause a different set of things to be implicitly instantiated.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.6 Licensing terms

The Blitz++ library is licensed under both the GPL and the more permissive "Blitz++ Artistic License". Take your pick. They are detailed in GPL and LICENSE, respectively. The artistic license is more appropriate for commercial use, since it lacks the "viral" properties of the GPL.

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.

Copyright (C) 1996--2003 Free Software Foundation, Inc.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.7 Mailing lists and support

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.7.1 How to get help

The starting point for all bug reports, feature requests and support questions is the Blitz++ support page, at http://oonumerics.org/blitz/support/

Please note the search engine box on this web page which lets you search the mailing list archives. This will often turn up answers to your question if it has been asked before.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.7.2 How to subscribe to a mailing list

To subscribe to a Blitz++ mailing list, send a message containing one (or more) of these lines to majordomo@oonumerics.org:

    subscribe blitz-support
    subscribe blitz-bugs
    subscribe blitz-dev

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.7.3 blitz-bugs

You can report bugs (or things you suspect might be bugs) to blitz-bugs@oonumerics.org.

It's not a very interesting list to be subscribed to. There are archives available from the Blitz++ web site.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.7.4 blitz-dev

Blitz++ is in open development: anyone can contribute features and code to the library. If you are interested in helping out with coding or porting, you should start by subscribing to the `blitz-dev` mailing list.

This list is also the appropriate place to send suggestions for features; just send email to blitz-dev@oonumerics.org. We can't implement it if you don't suggest it.

Archives of this list are available from the Blitz++ web site.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 1.7.5 blitz-support

This mailing list is for posting and answering questions about using the Blitz++ library. Anyone can post questions; anyone can answer.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Julian Cummings on November, 4 2004 using texi2html