Changeset 2919 in Sophya for trunk/SophyaLib/Manual

Timestamp:

Feb 23, 2006, 6:35:27 PM (20 years ago)

Author:

ansari

Message:

MAJ doc sophya oveview pour modifs Range() - Reza 23/02/2006

Location:

trunk/SophyaLib/Manual

Files:

• modifs.tex (modified) (1 diff)
• sophya.tex (modified) (5 diffs)

trunk/SophyaLib/Manual/modifs.tex

@@ -134 +134 @@
 \begin{itemize}
 
-\item[\rond] Janvier 2006  \\
+\item[\rond] Janvier, FŽvrier 2006  \\
+- AmŽlioration des fonctionalitŽs de la classe {\bf Range} et  des mŽthodes d'extraction
+de sous-tableaux (+ correction bugs et amŽlioration documentation) \\ 
 - Ajout de la methode BaseArray::ValueAtPositionDB() pour corriger un gros bug au 
 niveau de la conversion de type (r\_4 r\_8 ...) des tableaux \\

trunk/SophyaLib/Manual/sophya.tex

@@ -43 +43 @@
 \vspace{1cm}
 \begin{center}
-{\bf \Large Sophya Version: 1.9 (V\_Mai2005) }
+{\bf \Large Sophya Version: 1.929 (V\_Fev2006) }
 % Document revision 1.0 }
 \end{center}
@@ -494 +494 @@
 \end{figure}
 
+The development of this module started around 1999-2000,
+after evaluation of a number of publicly  available 
+C++ array hadling packages, including TNT, Lapack++, Blitz++, 
+as well as commercial packages from RogueWave (math.h++ \ldots). 
+Most of these packages provide interesting functionalities, however, 
+not any one package seemed to fulfill most of our requirements.
+\begin{itemize}
+\item Capability to handle {\bf large - multidimensional - dense} 
+arrays, for numerical data types. Although we have used templates, for
+data type specialisation, the actual code, apart inline functions is
+not in header files. Instead, we use explicit instanciation, and the 
+compiled code for the various numerical types of arrays is the
+library .
+\item The shape and size of the arrays can be defined and changed
+at run time. The classes ensure the memory management of the 
+created objets, with reference sharing for the array data. 
+The default behaviour of the copy constructor is to share the data,
+avoiding expensive memory copies.
+\item The package provides transparent management of sub-arrays
+and slices, in an intuitive way, somehow similar to what is
+available in Mathlab or Scilab.
+\item The memory organisation for arrays, specially matrices 
+(row-major or column major) can be 
+controled. This provide compatibility when using existing C or
+Fortran coded numerical libraries.
+\item The classes provide efficient methods to perform basic arithmetic
+and mathematical operations on arrays. In addition, operator overload 
+provides intuitive programming for element acces and most basic
+arithmetic operations.
+\item Conversion can be performed between arrays with different
+data types. Copy and arithmetic operations can be done transparently 
+between arrays with different memory organisation patterns.   
+\item This module does not provide more complex operations 
+such as FFT or linear algebra. Additional libraries are used, with interface
+classes for these operations.
+\item ASCII formatted I/O, for printing and read/write operations to/from text files.
+\item Efficient binary I/O for object persistence (PPF format), or import/export 
+to other data formats, such as FITS are provided by helper or handler classes. 
+\end{itemize}
 
 \subsection{Using arrays}
@@ -594 +633 @@
 \end{verbatim}
 
+{\bf Warning: } The operations defined in {\tt sopemtx.h}, such as 
+matrix inversion and linear system solver use a basic Gauss pivot
+algorithm which are not adapted for large matrices ($>\sim 100x100$).
+The services provided in other modules, such as {\bf LinAlg} should
+be preferred in such cases.
+
 \subsection{Working with sub-arrays and Ranges}
 \index{Range}
@@ -601 +646 @@
 range can be specified, using the {\tt start} and {\tt end} index
 and an optional step (or stride). It is also possible to specify
-the {\tt start} index and the number of elements: 
+the {\tt start} index and the number of elements.
+\begin{itemize}
+\item {\bf Range::all()} {\tt = Range(Range::firstIndex(), Range::lastIndex())}  \\
+return a Range objects representing all  valid indexes along the 
+corresponding axe.
+\item {\bf Range::first()} {\tt = Range(Range::firstIndex())}  \\
+return a Range object representing the first valid index
+\item {\bf Range::last()} {\tt = Range(Range::lastIndex())} 
+return a Range object representing the last valid index
+\item {\bf Range(idx)} represents a single index ({\bf = idx})
+\item {\bf Range(first, last)} represents the range of indices
+{\bf first} $\leq$ index $\leq$ {\bf last}.
+The static method {\tt Range::lastIndex()} can be used 
+to specify the last valid index.
+\item {\bf Range(first, last, step)} represents the range of index
+which is equivalent to \\  {\tt for(index=first; index <= last; index += step) }
+\item { \bf Range (first, last, size, step) } the general form can be used 
+to specify an index range, using the number of elements. 
+It is possible to specify a range of index, ending with the last valid index. 
+For example \\
+\hspace*{5mm} 
+{\tt Range(Range::lastIndex(), Range::lastIndex(), 3, 2) }  \\
+defines  the index range: \hspace*{5mm}  last-4, last-2, last.
+
 \begin{center}
-
 \begin{tabular}{ll}
-\multicolumn{2}{c}{ {\bf Range} {\tt (start=0, end=0, size=1, step=1) } } \\[2mm]
+\multicolumn{2}{c}{ {\bf Range} {\tt (start, end, size, step) } } \\[2mm]
 \hline \\
-{\bf Range} {\tt r(3,6); } &  index range 3,4,5,6 \\
-{\bf Range} {\tt r(7,0,3); } &  index range 7,8,9 \\
-{\bf Range} {\tt r(10,0,3,5); } &  index range 10,12,14,16,18 \\
+{\bf Range} {\tt r(3,6); } &  index range:  \hspace{2mm} 3,4,5,6 \\
+{\bf Range} {\tt r(3,6,0,1); } &  index range: \hspace{2mm} 3,4,5,6 \\
+{\bf Range} {\tt r(7,0,3,1); } &  index range: \hspace{2mm} 7,8,9 \\
+{\bf Range} {\tt r(10,0,5,2); } &  index range: \hspace{2mm} 10,12,14,16,18 \\
 \end{tabular}
 \end{center}
+\end{itemize}
+
+The method {\tt TArray<T>SubArray(Range ...)} can be used 
+to extract subarrays and slices. The operator {\tt operator() (Range rx, Range ry ...)}
+is also overloaded for sub-array extraction.
+For matrices, {\tt TMatrix<T>::Row()} and {\tt TMatrix<T>::Column()} 
+extract selected matrix rows and columns.
+
+The example illustrates the sub-array extraction using Range objects:
+\begin{verbatim}
+  // Creating and initialising a 2-D (6 x 4) array of integers
+  TArray<int> iaa(6, 4);
+  iaa = RegularSequence(1,2);
+  cout << "Array<int> iaa = \n" << iaa;
+  // We extract a sub-array - data is shared with iaa
+  TArray<int> iae = iaa(Range(1, Range::lastIndex(), 3) ,
+                        Range::all(), Range::first() );
+  cout << "Array<int> iae=subarray(iaa) = \n" << iae;
+  // Changing iae elements changes corresponding iaa elements
+  iae = 0;
+  cout << "Array<int> iae=0 --> iaa = \n" << iaa;
+
+\end{verbatim}
 
 In the following example, a simple low-pass filter, on a one 
@@ -668 +759 @@
 \end{verbatim} 
 The execution of this sample code creates the file {\tt aas.ppf} and 
-its output is reproduced here. Notice that the array hierarch is 
+its output is reproduced here. Notice that the array hierarchy is 
 recovered. BS is a sub-array of B, and modifying BS changes also
 the corresponding element in B.