Kernel Components > Utils

Release Information

Project: Siconos
Internal Release Number: 1.0
Last update: September 15, 2005
Related Documents:

Introduction


    To find more details on objects described int this section, see Doxygen documentation of Siconos/Kernel.

Siconos Algebra


What for? vectors and matrices handling.
Feature sets: F-2003 and F-2.303
Depencies: Lapack, Blas, Lapack++.
Sources directory name: Kernel/src/utils/SiconosAlgebra

This module is based on Blas/Lapack Library.  
For vectors, two objects are available:
        - SimpleVector, a vector of double. Its core is a Lapack double vector(class LaVectorDouble).
        - CompositeVector, a sequence of SimpleVector. It uses a STL container, vector.

These objects are derived classes of a virtual one, SiconosVector, which provides an interface for vectors handling.

An object SiconosMatrix is also available, with a LaGenMatDouble (Lapack matrix) as main member.

Operators:


All classical operators (+,-,*,/,+=,-=,...) have been overloaded, and are supposed to accept mixed operations such as
SimpleVector = SiconosMatrix * CompositeVector, as soon as sizes are coherent.
The access operator is ().

    Example:
        for a composite vector v, that contains 2 simple vectors, v1 and v2 of respective sizes n1 and n2, the size of v is n1+n2.
        For i<n1 v(i)=w1(i) and for i>=n1, v(i)=w2(i-n1).

For matrices, first index is line number, second one column number.
Assignment operator (=) is also overloaded. The rule is that to use it, right-hand and left-hand size objects must have coherent sizes.
For pointers, they must have been allocated before assignment.

    Example:
        SiconosMatrix *M1, *M2;
        M1 = new SiconosMatrix(...);  // allocate memory for M1 and fill it in
       
*M2 = *M1 ;  // FALSE !!! Memory has to be allocated for M2 //
        // Right way:
        M2 = new SiconosMatrix(...); *M2 = *M1;

        // Best way: use copy constructor
        SiconosMatrix *M2 = new SiconosMatrix(*M1);    

C vs Fortran vectors and matrices ordering:
   
Platform and plugin functions are coded in C/C++   , but double pointers representing vectors and matrices given in
parameters are column-oriented (FORTRAN format), in order to be used simply with FORTRAN
computation libraries, e.g. Blas,  through  Siconos/Numerics.
   
    Example :          
                        1      2      3      4
               M =   5     6      7      8
                        9    10    11    12 

                n = 3 and m = 4   (Warning: indices start at 0 in C language).
                MFor is the array in memory representing M. Its elements are sorted as follows :
               
1
5 9 2 6 10 3 7 11 4 8 12
                 
               To access to element Mij of matrix M, we need to compute its position in the array : MFor[i + jn].
                For example, this is a short C function which returns a M element from its coordinates in the matrix :
	int getMatrixElement(int i, int j, int n, int m, int MFor[])
{
// i and j are the coordinates of the element in the matrix M
// n is the number of lines of M
// m is the number of columns of M
// MFor is the array representing the matrix M

return MFor[i + j * n];
}

                If we try to get the element M(1,3)

	printf("searched element is : \%d", getMatrixElement(1, 3, 3, 4, MFor));
                The result displayed on the screen is : searched element is : 8.

Siconos Memory


What for? to save variable values (ie SiconosVector) for previous time steps
Depencies: SiconosVector
Sources directory name: Kernel/src/ utils/SiconosMemory

This object is based on a STL container, deque, of SiconosVector.
The size (maximum number of saved vectors) is usually fixed. When a new vector is saved, it enters in first position, other are translated.
 If the SiconosMemory object is full, the first saved vector is deleted.
For example, SiconosMemory is useful for integrators that require several preceding time steps values for state of the dynamical system.
The class is designed to avoid useless copies of SiconosVectors, using pointers and push_front/push_back function of deque object.

Siconos Exception


What for? object for exceptions handling and throwing
Depencies: none
Sources directory name: Kernel/src/ utils/Siconos/Exception


Seven objects: RuntimeException, XMLException, SiconosMemoryException, SiconosMatrixException, SiconosVectorException,
SiconosSharedLibraryException, SiconosException.
The six first are derived classes from the last one.
  
     Example:  main cpp-file with exception handling:

	int main(int argc, char* argv[]) 
try // main program commands ...
catch (SiconosException e)
cout « e.report() « endl;
catch(...)
cout « "Exception caught in exampleFile" « endl;
   

Utils classes diagram


utils classes diagram