Users Guide

## Introduction

The `itbase` library is the core of `IT++` and it contains classes and functions for mathematics with scalars, vectors, and matrices. This document does not cover all the aspects of the `itbase` library. It does however explain the most important things you need to know in order to start using IT++. Once you are more familiar with the `itbase` library you will find the online reference manual more useful.

## Predefined Data Types

### Predefined Scalar Types

Apart from the standard C++ types e.g. `char`, `short`, `int`, `long`, `double`, `float`, and `long` `long`, the following types are specific for `IT++`:

• `complex<double>`: Contains real and imaginary parts of type `double`
• `bin:` Used for binary (0,1) data

### Prepared Vector Types

A vector can in principle be of arbitrary type (that support addition, subtraction, multiplication and division), since the general vector class `Vec<TYPE>` is templated. However, the most commonly used vector types are predefined. These predefined vector types are:

• `vec:` Basic vector type containing `double`
• `cvec:` Vector type containing `complex<double>`
• `ivec:` Vector type containing `int`
• `bvec:` Vector type containing `bin`
• `svec:` Vector type containing `short`

The general vector class is used to define the specialized classes above. The `vec` class is actually a `Vec<double>`. We urge you to use these predefined classes instead of `Vec<TYPE>` when ever possible.

### Prepared Matrix Types

The general matrix class is called `Mat<TYPE>`. These predefined matrix types are:

• `mat:` Basic matrix type containing double
• `cmat:` Matrix type containing `complex<double>`
• `imat:` Matrix type containing `int`
• `bmat:` Matrix type containing `bin`
• `smat:` Matrix type containing `short`

As with vector, the general matrix class is used to define the specialized classes above. The `mat` class is thus a `Mat<double>`. We urge you to use these predefined classes instead of `Mat<TYPE>` whenever possible.

## Using Vectors

Vectors and matrices in `IT++` are very similar. We therefore begin to describe the vector class in detail and then briefly explain the differences regarding matrices in the next section.

### Defining a Vector

A vector containing elements of type `double` is defined with:

```vec my_vector;
```

However, this will not assign a size (memory) to the vector. To assign size 10 to the vector we may use:

```vec my_vector(10);
```

or

```vec my_vector;
my_vector.set_size(10,false);
```

where the second parameter in the `set_size` call (`true` or `false`) determines if you want to copy the contents of the old data area into the new resized one, or not. This may be useful when down-sizing a vector, but in this case it is not. It is also equivalent to use

```my_vector.set_length(10,false);
```

instead of `set_size`.

Observe that a declared vector (or matrix) is not cleared (the element values are undefined). To clear a vector we simply write

```my_vector.clear();
```

or

```my_vector.zeros();
```

To fill the vector with ones we write

```my_vector.ones();
```

It is possible to retrieve the length (size) of a vector in any of the following ways:

```length_of_vector = my_vector.length();
length_of_vector = my_vector.size();
length_of_vector = length(my_vector);
```

To assign values to a vector

```vec  a = "0 0.7 5 9.3";        // that is a = [0 0.7 5 9.3]
ivec b = "0:5";                // that is b = [0 1 2 3 4 5]
vec  c = "3:2.5:13";           // that is c = [3 5.5 8 10.5 13]
ivec d = "1:3:5,0:2:4";        // that is d = [1 3 5 0 2 4]
vec e("1.2,3.4,5.6");          // that is e = [1.2 3.4 5.6]
vec f;
f.set("1.0 2.0 3.0 4.0");      // that is f = [1.0 2.0 3.0 4.0]
vec g;
g = f;                         // that is g is a copy of f
```

A comma or a space character separates the vector elements. When assigning or retrieving a specific vector element use

```a(i) = 3.14;
double p = a(i);
```

for element number i. Vector elements are numbered such that a(0) denotes the first element. It is also possible to use square brackets as in the C language, i.e.

```a[i] = 3.14;
double p = a[i];
```

Parts or a vector are retrieved by

```a.left(3);   // a vector containing the first 3 elements of a
a.right(2);  // a vector containing the last 2 elements of a
a.mid(1,2);  // a vector containing the 2 elements starting with a(1)
a(2,4);      // a vector containing all elements from a(2) to a(4)
a(2,-1);     // a vector containing all elements from a(2) to the end of a
```

Alternatively you can use get() methods instead of () or [] operators, e.g.

```a.get(4);
a.get(5,-1);
```

If you have a vector called index_list containing indexes (ivec) you may write

```// these give a vector containing elements with indexes in index_list
a(index_list);
a.get(index_list);
```

If you have a `bvec` called e.g. bin_list you may write

```// these give a vector containing all elements a(i) for which bin_list(i) equals 1
a(bin_list);
a.get(bin_list);
```

Have a look at the following example:

```#include <itpp/itbase.h>
using namespace itpp;
using namespace std;

int main() {
vec a = linspace(0,1,11);
ivec index_list = "3 5 2 2";
bvec bin_list = "1 0 1 0 1 0 1 0 1 0 1";

cout << "a = " << a << endl;
cout << "a(index_list) = " << a(index_list) << endl;
cout << "a.get(bin_list) = " << a.get(bin_list) << endl;
}
```

When you run this program you will see

```a = [0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0]
a(index_list) = [0.3 0.5 0.2 0.2]
a.get(bin_list) = [0.0 0.2 0.4 0.6 0.8 1.0]
```

### Vector Manipulation

Below follows a listing of the most common vector manipulation commands that are available. All examples are given for an `ivec` denoted my_ivec, but of course this will work for other vector types as well.

• `shift_right:`
```// Shift in scalar data (10) at position 0
my_ivec.shift_right(10);

// Shift in vector at position 0
my_ivec.shift_right("10 4");
```
• `shift_left:`
```// Shift in scalar data (10) at position Size()-1
my_ivec.shift_left(10);

// Shift in vector at position Size()-1
my_ivec.shift_left("10 4");
```
• `set_subvector:`
```// Replace part of vector from position (10) with the vector "11 13"
my_ivec.set_subvector(10,"11 13");
```
• `del:`
```// Delete element at index (10), making vector size one less
my_ivec.del(10);
```
• `ins:`
```// Insert element at index (10), making vector size one extra
my_ivec.ins(10);
```
• `split:`
```// Splits vector at pos (10). Returns first part, keep second part.
ivec first_part = my_ivec.split(10);
```
• `elem_mult:`
```// Multiply two vectors element wise.
ivec my_product = elem_mult(my_invec1,my_ivec2);
```
• `elem_div:`
```// Dividide two vectors element wise.
ivec my_product = elem_div(my_invec1,my_ivec2);
```
• Calculation: +, -, *, /
```a = my_ivec1 + my_ivec2;  // Addition of vectors
a = my_ivec + 10;         // Addition of vector and scalar
a = my_ivec1 - my_ivec2;  // Subtraction of vectors
a = my_ivec - 10;         // Subtraction of vector and scalar
a = my_ivec * 10;         // Multiplication of vector and scalar
a = my_ivec / 10;         // Division of vector and scalar
```
• Calculation: +=, -=, *=, /=, |=
```a += my_ivec;  // Addition of vectors (a = a+my_ivec)
my_ivec += 10; // Addition of vector and scalar (10)
a -= my_ivec;  // Subtraction of vectors (a = a-my_ivec)
my_ivec -= 10; // Subtraction of vector and scalar (10)
my_ivec *= 10; // Multiplication of vector and scalar (10)
my_ivec /= 10; // Divsion of vector and scalar (10)
my_ivec |= a;  // Element wise division
```
• `concat`
```a = concat(my_ivec1, my_ivec2);  // concatenation of two vectors
```

### Vector Converters

In order to convert e.g an `ivec` to a `vec` we can write some thing like `my_vec` = `to_vec(my_ivec)`. The following converters are available:

• `to_bvec`,
• `to_svec`,
• `to_ivec`,
• `to_vec`,
• `to_cvec`.

### Vector Functions

There are several functions that operate on vectors. Some examples are: `max`, `max_index`, `min`, `min_index`, `product`, `energy`, `geometric_mean`, `mean`, `median`, `norm`, `round`, `variance`, `ceil_i`, `floor_i`, `round_i`, `find`.

Examples of functions that generate different kinds of vectors are: `linspace`, `ones_b`, `ones_c`, `ones_i`, `ones` `zeros_b`. There are several more than these. Please refer to the IT++ reference manual for a description of these.

## Using Matrices

Matrices are two-dimensional arrays, and most of their functionality is similar to that of vectors. The predefined matrix types are:

• `mat`,
• `cmat`,
• `imat`,
• `smat`,
• `bmat`.

Below follows some examples that are specific for matrices only:

• Define a matrix of type `double` with 3 rows and 4 columns

```mat a(3,4);
```

• Define a matrix of type `int` with 2 rows and 3 columns. A comma (,) or space is used to separate columns and a semicolon (;) is used to separate rows.

```imat a = "1 2 3;4 5 6";
```

• Access to rows and columns with `get_row` and `get_col`

```a.get_row(1); // Returns the second row of the matrix b
a.get_col(0); // Returns the first column of the matrix b
```

• Set rows and columns with `set_row` and `set_col`

```a.set_row(1,"9 8 7"); // Set second row to "9 8 7"
a.set_col(0,"7 2");   // Set first column to "7 2"
```

• The size of a matrix

```// Set the size. "false" means "do not copy"
a.set_size(4,5,false);
int nr_of_rows = a.rows();    // return the number of rows
int nr_of_columns = a.cols(); // return the number of columns
```

```a(r,c); // Access to a single element.

// Returns the sub-matrix from rows r1 to r2 and columns c1 to c2.
a(r1,r2,c1,c2);
```

• Copy rows and columns

```// Copy row number "from" to row number "to"
a.copy_row(to,from)

// Copy column number "from" to column number "to"
a.copy_col(to,from)
```

• Swap rows and columns

```// Swap rows number r1 and r2
a.swap_rows(r1,r2)

// Swap columns number c1 and c2
a.swap_cols(c1,c2)
```

• Horizontal and vertical concatenation
```// Equivalent to the MATLAB command c = [a b]
c = concat_horizontal(a,b);

// Equivalent to the MATLAB command c = [a;b]
c = concat_vertical(a,b);
```

### Matrix Converters

The following converters are available:

• `to_mat`,
• `to_imat`,
• `to_cmat`,
• `to_bmat`.

## The Array Class

The `itbase` library contains, among other things, the `Array` class. An `Array` can contain any type of data. Below is an example of an `Array` containing vectors (`vec`):

```#include <itpp/itbase.h>

using namespace itpp;
using namespace std;

int main() {
Array<vec> my_vec_array(2);
my_vec_array(0) = linspace(0,1,4);
my_vec_array(1) = "0.1 0.2 0.3 0.4 0.3 0.2 0.1";
cout << "my_vec_array = " << my_vec_array << endl;

return 0;
}
```

## Random Vectors, Matrices, and Generators

### Random Vectors and Matrices

Random vectors and matrices are easily obtained by using these predefined functions:

• `randb:` Generates a random bit vector or matrix
• `randu:` Generates a random uniform vector or matrix
• `randi:` Generates a random index vector or matrix
• `randray:` Generates a random Rayleigh vector or matrix
• `randrice:` Generates a random Rice vector or matrix
• `randexp:` Generates a random Exponential vector or matrix
• `randn:` Generates a random Gaussian vector or matrix
• `randn_c:` Generates a random complex Gaussian vector or matrix

### Random Number Generators (RNG)

The following discrete valued random number generators are available. More information about these can be found in the IT++ reference manual.

• `Bernoulli_RNG`
• `I_Uniform_RNG`

The following continuous valued random number generators are available.

• `Uniform_RNG`
• `Exponential_RNG`
• `Normal_RNG`
• `Complex_Normal_RNG`
• `AR1_Normal_RNG`
• `Weibull_RNG`
• `Rayleigh_RNG`
• `Rice_RNG`

## Deterministic Sources

The following deterministic sources are available:

• `Sine_Source`
• `Square_Source`
• `Triangle_Source`
• `Sawtooth_Source`
• `Impulse_Source`
• `Pattern_Source`

## Filter Classes and Functions

The following filter classes are available:

• `AR_Filter`
• `MA_Filter`
• `ARMA_Filter`
• `Freq_Filt`

The following filter functions are available:

• `filter`

### Signal Processing Functions

The following signal processing functions are available:

• `a2k`, `k2a`, `a2lar`, `k2lar`, `lpc`, `levinsson`, `lerouxguegen`
• `fft`, `ifft`, `fft_real`, `ifft_real`
• `dct`, `idct`
• `spectrum`
• `cov`, `xcorr`
• `chirp`
• `dht`, `dht2`, `dwht`, `dhwt2`, `self_dht`, `self_dwht`
• `filter_spectrum`
• `filter_whiteness`

## Timer Classes

The `Real_Timer` class can be used to measure execution time of a program as in the following example:

```#include <itpp/itbase.h>

using namespace itpp;
using namespace std;

int main() {
long sum = 0;
Real_Timer my_timer;

my_timer.tic();
for (int i=0; i<10000000; i++) {
sum += i;
}
my_timer.toc_print();

cout << "The sum is " << sum << endl;

return 0;
}
```

## Reading and Writing to Files

The following example saves the variable a to the file `my_file_name.it:`

```#include <itpp/itbase.h>

using namespace itpp;

int main() {
it_file my_file("my_file_name.it");
vec a = "1.0 2.0 3.0 4.0";
my_file << Name("a") << a;

return 0;
}
```

The following example reads the variable a from the file `my_file_name.it` and prints it:

```#include <itpp/itbase.h>

using namespace itpp;
using namespace std;

int main() {
it_file my_file("my_file_name.it");
vec a;
my_file >> Name("a") >> a;
cout << "a = " << a << endl;

return 0;
}
```

Note that `*.it` files can be read and written in Matlab/Octave by using the `itload.m` and `itsave.m` functions.

Also available is the class `it_ifile` that can only be used for reading of files.

Generated on Sat Mar 17 2012 00:01:07 for IT++ by Doxygen 1.7.4