Users Guide

# Table of Contents

- Introduction
- Predefined Data Types
  - Predefined Scalar Types
  - Prepared Vector Types
  - Prepared Matrix Types
- Using Vectors
  - Defining a Vector
  - Vector Manipulation
  - Vector Converters
  - Vector Functions
- Using Matrices
  - Matrix Converters
- The Array Class
- Random Vectors, Matrices, and Generators
  - Random Vectors and Matrices
  - Random Number Generators (RNG)
- Deterministic Sources
- Filter Classes and Functions
- Signal Processing Functions
- Timer Classes
- Reading and Writing to Files

# 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

- Access to parts of a matrix

  a(r,c); // Access to a single element.
  a(i); // Access to a single element. Linear addressing, by rows.
  // 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 Thu Aug 20 2015 21:02:52 for IT++ by Doxygen 1.8.9.1