Seldon user's guide

USER'S GUIDE
Installation
Overview
Vectors
- Dense Vectors
- Sparse Vectors
- Functions
Matrices
Other Structures
Allocators
Exceptions
Computations
Python Interface
Index
API REFERENCE
Classes
Functions
Search for
Support

In that page, methods and functions related to sparse vectors are detailed. Sparse vectors consist of row numbers and values. In order to have efficient algorithms, row numbers are always sorted in ascending order.

Basic declaration :

  // sparse vector of doubles
Vector<double, Vect_Sparse> V;

Methods :

Vector constructors
Vector operators
GetM	returns the number of elements in the vector
GetLength	returns the number of elements in the vector
GetSize	returns the number of elements in the vector
GetIndex	returns a pointer to the row numbers
GetData	returns a pointer to the values
GetDataConst	returns a pointer to the values
GetDataVoid	returns a pointer to the values
GetDataConstVoid	returns a pointer to the values
Clear	removes all elements of the vector
Reallocate	changes the size of vector (removes previous elements)
Resize	changes the size of vector (keeps previous elements)
SetData	sets the pointer to the array contained in the vector
Nullify	clears the vector without releasing memory
Index	access to row number
Value	access to value
Copy	copies a vector
Assemble	sorts row numbers
GetDataSize	returns the number of elements in the vector
Zero	sets all elements to zero
Fill	sets all elements to a given value
FillRand	fills randomly the vector
AddInteraction	adds a coefficient to the vector
AddInteractionRow	adds coefficients to the vector
GetNormInf	returns highest absolute value
GetNormInfIndex	returns the index of the highest absolute value
Print	displays the vector
Write	writes the vector in binary format
Read	reads the vector in binary format
WriteText	writes the vector in text format
ReadText	reads the vector in text format

Functions :

Mlt	multiplies the elements of the vector by a scalar
Add	adds two vectors
Copy	copies one vector into another one
Swap	exchanges two vectors
DotProd	scalar product between two vectors
DotProdConj	scalar product between two vectors, first vector being conjugated
Conjugate	conjugates a vector
GetMaxAbsIndex	returns index where highest absolute value is reached
Norm1	returns 1-norm of a vector
Norm2	returns 2-norm of a vector

Vector constructors

Syntax :

  Vector();
  Vector(const Vector& X );
  Vector(int n);

Example :

  // default constructor -> empty vector
Vector<int, Vect_Sparse> U;
cout << "Number of elements " << U.GetM() << endl; // It should return 0 
// then you can use Reallocate to change the number of non-zero entries
U.Reallocate(3);
// you need to initialize row numbers (in ascending order)
U.Index(0) = 0;
U.Index(1) = 4;
U.Index(2) = 14;
// for values, you can use Fill
U.Fill();

// copy constructor (V -> U)
Vector<int, Vect_Sparse> V = U;

// constructor specifying the number of non-zero entries
Vector<double, Vect_Sparse> W(2);
// W is not initialized, you have to fill it
W.Fill(1.0);
// and row numbers as well
W.Index(0) = 7;
W.Index(1) = 4;
// if you forgot to sort numbers, call Assemble
W.Assemble();

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

Vector operators

Syntax :

  T operator () const;
  T& operator ();
  Vector& operator =(const Vector& );
  Vector& operator *=(const T0& alpha);

The access operator () can be used to modify (or insert) a non-zero entry in the sparse vector.

Example :

  Vector<double, Vect_Sparse> V;
// use of operator () to insert non-zero entry
V(2) = 1.5;
V(5) = -1.0;
// you can display value of V at row i
// V(4) should return 0 (zero entry)
cout << "V(4) = " << V(4) << endl;
// but V(2) should return 1.5
cout << "V(2) = " << V(2) << endl;

Vector<double, Vect_Sparse> W;
// use of operator = to copy contents of vector V
W = V;

// multiplication by a scalar
W *= 1.5;

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

GetM, GetLength, GetSize, GetDataSize

Syntax :

  int GetM() const;
  int GetLength() const;
  int GetSize() const;
  int GetDataSize() const;

All those methods are identic and return the number of non-zero entries contained in the vector.

Example :

  Vector<float, Vect_Sparse> V(3);
cout << "Number of elements of V " << V.GetM() << endl;
V.Reallocate(5);
cout << "Number of elements of V " << V.GetSize() << endl;

Location :

Class Vector_Base
Vector.hxx
Vector.cxx

GetIndex

Syntax :

  int* GetIndex();

This method is used to retrieve the pointer to the row numbers and should be used in conjunction with method GetData.

Example :

  Vector<double, Vect_Sparse> V;
V(3) = -3.5;
V(1) = 1.3;
int* index = V.GetIndex();
// you can use data as a normal C array
cout << "row number 1 : " << index[0] << endl;

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

GetData, GetDataConst, GetDataVoid, GetDataConstVoid

Syntax :

  T* GetData() const;
  const T* GetDataConst() const;
  void* GetDataVoid() const;
  const void* GetDataConstVoid() const;

Those methods are useful to retrieve the pointer to the values. In practice, you can use those methods in order to interface fortran subroutines or to realize some low level operations. But in this last case, you have to be careful, because debugging operations will be more tedious.

Example :

  Vector<double, Vect_Sparse>; V;
V(3) = -3.5;
V(1) = 1.3;
double* data = V.GetData();
// you can use data as a normal C array
// here the sum of elements is computed
double sum = 0;
for (int i = 0; i < V.GetM(); i++)
  sum += data[i];

// this would be equivalent and safer to write
sum = 0;
for (int i = 0; i < V.GetM(); i++)
  sum += V.Value(i);

// if you want to call a fortran subroutine daxpy
Vector<double, Vect_Sparse> X(3), Y(3); 
double coef = 2.0;
// in this case, X is constant
int m = X.GetM();
int n = Y.GetM();
daxpy_(&coef, &m, X.GetDataConst(), X.GetIndex(),
       &n, Y.GetData(), Y.GetIndex());

// for complex numbers, conversion to void* is needed :
Vector<complex<double>, Vect_Sparse> Xc(3), Yc(3);
complex<double> beta(1,1);
zaxpy(reinterpret_cast<const void*>(beta), >m,
      Xc.GetDataConstVoid(), Xc.GetIndex(), >n,
      Yc.GetDataVoid(), Yc.GetIndex());

Location :

Class Vector_Base
Vector.hxx
Vector.cxx

Clear

Syntax :

  void Clear();

This method removes all the non-zero entries of the vector. After calling this method, the vector is equal to 0.

Example :

  Vector<double, Vect_Sparse> V;
V(2) = 1.5;
// clears vector V
V.Clear();

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

Reallocate

Syntax :

  void Reallocate(int);

This method changes the number of non-zero entries contained in the vector, but removes previous values. For sparse vectors, this may be a better solution to use methods AddInteraction, AddInteractionRow or the access operator.

Example :

  Vector<long double, Vect_Sparse> V;
V(1) = 1.5;
V(5) = -1.0;
// resizes vector V
V.Reallocate(20);
// you need to initialize all new values
V.Fill(1.0);
// and row numbers as well
for (int k = 0; k < 20; k++)
  V.Index(k) = 2*k+3;

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

Resize

Syntax :

  void Resize(int);

This method changes the size of the vector, and keeps previous elements. For sparse vectors, this may be a better solution to use methods AddInteraction, AddInteractionRow or the access operator.

Example :

  Vector<long double, Vect_Sparse> V;
V.AddInteraction(3, 1.4);
V.AddInteraction(7, -1.5;
// resizes vector V
V.Resize(4);
// you need to initialize new elements if there are new
// here two new elements
V.Index(2) = 0; V.Value(2) = 0.8;
V.Index(3) = 6; V.Value(3) = -0.7;
// Assemble should be called to sort row numbers
V.Assemble();

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

SetData

Syntax :

  void SetData(int, T*, int*);
  void SetData(Vector<T>, Vector<int>);

This method sets the row numbers and values. This method should be used carefully, and generally in conjunction with method Nullify.

Example :

  // for example, you can construct the sparse vector
// with two arrays row and values
IVect row(2);
Vector<double> values(2);
row(0) = 4; values(0) = 1.5;
row(1) = 1; values(1) = -0.5;
Vector<double, Vect_Sparse> U;

// and provide those arrays with SetData
U.SetData(values, row);

// but here, the row numbers are not sorted
U.Assemble();

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

Nullify

Syntax :

  void Nullify();

This method clears the vector without releasing memory. This method should be used carefully, and generally in conjunction with method SetData. You can look at the example shown in the explanation of method SetData.

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

Index

Syntax :

  int Index(int) const;
  int& Index(int);

This method gives a direct access to a non-zero entry

Example :

  Vector<double, Vect_Sparse> V(3);
// you can use Index and Value to modify sparse vector
V.Index(0) = 1; // row number of first non-zero entry 
V.Value(0) = 0.7; // value of first non-zero entry
V.Index(1) = 5; // row number of first non-zero entry
V.Value(1) = -0.7;
V.Index(2) = 7;
V.Value(2) = 1.2;

// we display non-zero entries
for (int k = 0; k < V.GetM(); k++)
  cout << "Interaction at row " << V.Index(k)
       << " value : " << V.Value(k) << endl;

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

Value

Syntax :

  T Value(int) const;
  T& Value(int);

This method gives a direct access to a non-zero entry

Example :

  Vector<double, Vect_Sparse> V(3);
// you can use Index and Value to modify sparse vector
V.Index(0) = 1; // row number of first non-zero entry 
V.Value(0) = 0.7; // value of first non-zero entry
V.Index(1) = 5; // row number of first non-zero entry
V.Value(1) = -0.7;
V.Index(2) = 7;
V.Value(2) = 1.2;

// we display non-zero entries
for (int k = 0; k < V.GetM(); k++)
  cout << "Interaction at row " << V.Index(k)
       << " value : " << V.Value(k) << endl;

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

Copy

Syntax :

  void Copy(const Vector<T>&);

This method copies a vector into the current vector.

Example :

  // copy of a vector V
Vector<double, Vect_Sparse> V(2), W;
V.Index(0) = 1; V.Index(1) = 3;
V.FillRand();
W.Copy(V);
// this is equivalent to use operator =
W = V;

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

Assemble

Syntax :

  void Assemble();

This method sorts row numbers, and adds values if there are two same row numbers. You don't need to call this method if you are using the access operator () or methods AddInteraction.

Example :

  Vector<double, Vect_Sparse> V(3);
V.Index(0) = 2; V.Value(0) = 0.3;
V.Index(1) = 0; V.Value(1) = -0.5;
V.Index(2) = 2; V.Value(2) = 1.2;
// here the row numbers given by using Index are not sorted
V.Assemble();
// V should be equal to [0 -0.5, 2 1.5]
cout << "V = " << V << endl;

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

Zero

Syntax :

  void Zero();

This method fills memory of 0. All non-zero entries have their values set to 0. This is useful in order to keep the same profile for the vector, and initialize it to 0, before adding new interactions. Since the profile is conserved, there is no insertion of non-zero entries, therefore the strategy is more efficient

Example :

  Vector<double, Vect_Sparse> V;
// we add two interactions
V.AddInteraction(5, 1.3);
V.AddInteraction(2, -10);

// now we want to keep the same profile but with null values
V.Zero();
// V should be equal to [2 0.0, 5 0.0]
cout << "V =  " << V << endl;

// after you can add coefficients in that profile
// so that you are more efficient (no insertion)
V.AddInteraction(2, 3.0);

Location :

Class Vector<T, Vect_Full>
Vector.hxx
Vector.cxx

Fill

Syntax :

  void Fill();
  void Fill(const T0& );

This method sets values of non-zero entries with 0, 1, 2, etc or with a given value. Row numbers are not affected.

Example :

  Vector<double> V(4);
// row numbers
V.Index(0) = 2;
V.Index(1) = 4;
V.Index(2) = 6;
V.Index(3) = 7;
// for values, we call fill
V.Fill();
// V should contain [2 0.0, 4 1.0, 6 2.0, 7 3.0]

// you can specify the coefficient for all values
V.Fill(2);
// V should contain [2 2.0, 4 2.0, 6 2.0, 7 2.0]

Location :

Class Vector<T, Vect_Full>
Vector.hxx
Vector.cxx

FillRand

Syntax :

  void FillRand();

This method sets values of non-zero entries randomly. Row numbers are not affected.

Example :

  Vector<double> V(4);
// row numbers
V.Index(0) = 2;
V.Index(1) = 4;
V.Index(2) = 6;
V.Index(3) = 7;
// for values, we ask random values
V.FillRand();
// V should contain [2 r0, 4 r1, 6 r2, 7 r3]
// where r0, r1, r2 and r3 are random numbers

Location :

Class Vector<T, Vect_Full>
Vector.hxx
Vector.cxx

AddInteraction

Syntax :

  void AddInteraction(int, T);

This method adds/inserts a coefficient to the sparse vector. If the entry doesn't exist, it is inserted at the correct position, so that row numbers stay sorted in ascending order.

Example :

  // empty vector
Vector<double, Vect_Sparse> V;

// a non-zero entry is created by using AddInteraction
V.AddInteraction(3, 2.5);

// if the non-zero entry exists, the coefficient is added
V.AddInteraction(3, -1.0);

// V is now equal to 3 1.5 
cout << "V = " << endl;

// if you want to set the value, you can use operator ()
V(3) = -0.8;
// V is now equal to 3 -0.8

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

AddInteractionRow

Syntax :

  void AddInteractionRow(Vector<int>, Vector<T>);

This method adds/inserts coefficients to the sparse vector. If there is no entry, it is inserted at the correct position, so that row numbers stay sorted in ascending order.

Example :

  // empty vector
Vector<double, Vect_Sparse> V;

// non-zero entries are created by using AddInteractionRow
IVect row(2);
Vector<double> value(2);
row(0) = 6; value(0) = 1.3;
row(1) = 3; value(1) = -0.8;

V.AddInteractionRow(row, value);
// V is now equal to [3 -0.8, 6 1.3] 
cout << "V = " << endl;

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

GetNormInf, GetNormInfIndex

Syntax :

  T GetNormInf();
  int GetNormInfIndex();

GetNormInf returns the highest absolute value whereas GetNormInfIndex returns the index where this maximum is reached. This returns the index and not the row number. This method does not work for complex numbers.

Example :

  Vector<double, Vect_Sparse> > V;
V(0) = 1; V(3) = -2.2; V(4) = 0.5;
int imax = V.GetNormInf(); // should return 2.2
int pos = V.GetNormInfIndex(); // should return 1
// if you want the row number, you can use Index
cout << "maximum reached at row " << V.Index(pos) << endl;

Location :

Class Vector<T, Vect_Full>
Vector.hxx
Vector.cxx

Print

Syntax :

  void Print() const;

This method displays the vector with 1-index convention for row numbers.

Example :

  Vector<double, Vect_Sparse> V;
V.AddInteraction(5, -1.0);
V.AddInteraction(2, 1.5);
V.Print(); // should display 3 1.5 \n 6 -1.0

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

Write

Syntax :

  void Write(string) const;
  void Write(ofstream&) const;

This method writes the vector on a file/stream in binary format. The file will contain the number of non-zero entries, the list of row numbers, and then the list of values.

Example :

  Vector<double, Vect_Sparse> V;
V(1) = 1.0; V(3) = 0.5; 
// you can write directly in a file
V.Write("vector.dat");

// or open a stream with other datas
ofstream file_out("vector.dat");
int my_info = 3;
file_out.write(reinterpret_cast<char*>(&my_info), sizeof(int));
V.Write(file_out);
file_out.close();

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

Read

Syntax :

  void Read(string);
  void Read(istream&);

This method reads the vector from a file/stream in binary format. The file will contain the number of non-zero entries, the list of row numbers, and then the list of values.

Example :

  Vector<double, Vect_Sparse> V; 
// you can read directly on a file
V.Read("vector.dat");

// or read from a stream
ifstream file_in("vector.dat");
int my_info;
file_in.read(reinterpret_cast<char*>(&my_info), sizeof(int));
V.Read(file_in);
file_in.close();

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

WriteText

Syntax :

  void WriteText(string) const;
  void WriteText(ofstream&) const;

This method writes the vector on a file/stream in text format. The file will contain the list of non-zero entries, each line of the file will contain a row number and a value. The 1-index convention is used for row numbers.

Example :

  Vector<double, Vect_Sparse> V;
V.AddInteraction(6, 3.1);
V.AddInteraction(2, -1.3);
// you can write directly in a file
V.WriteText("vector.dat");

// or open a stream with other datas
ofstream file_out("vector.dat");
int my_info = 3;
file_out << my_info << '\n';
V.WriteText(file_out);
file_out.close();

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

ReadText

Syntax :

  void ReadText(string);
  void ReadText(istream&);

This method reads the vector on a file/stream in text format. The used format is detailed above in the explanation of the method WriteText.

Example :

  Vector<double, Vect_Sparse> V; 
// you can read directly on a file
V.ReadText("vector.dat");

// or read from a stream
ifstream file_in("vector.dat");
int my_info;
file_in >> my_info;
V.ReadText(file_in);
file_in.close();

Location :

Class Vector<T, Vect_Sparse>
SparseVector.hxx
SparseVector.cxx

All Classes Namespaces Files Functions Variables Typedefs

Sparse Vectors

Basic declaration :

Methods :

Functions :

Vector constructors

Syntax :

Example :

Related topics :

Location :

Vector operators

Syntax :

Example :

Related topics :

Location :

GetM, GetLength, GetSize, GetDataSize

Syntax :

Example :

Location :

GetIndex

Syntax :

Example :

Related topics :

Location :

GetData, GetDataConst, GetDataVoid, GetDataConstVoid

Syntax :

Example :

Related topics :

Location :

Clear

Syntax :

Example :

Location :

Reallocate

Syntax :

Example :

Related topics :

Location :

Resize

Syntax :

Example :

Related topics :

Location :

SetData

Syntax :

Example :

Related topics :

Location :

Nullify

Syntax :

Related topics :

Location :

Index

Syntax :

Example :

Related topics :

Location :

Value

Syntax :

Example :

Related topics :

Location :

Copy

Syntax :

Example :

Related topics :

Location :

Assemble

Syntax :

Example :

Related topics :

Location :

Zero

Syntax :

Example :

Related topics :

Location :

Fill

Syntax :

Example :

Related topics :