From a0cb222e894d457367203a288b4eacff29b987c2 Mon Sep 17 00:00:00 2001 From: ageay Date: Wed, 18 May 2011 11:37:24 +0000 Subject: [PATCH] Some docs. --- doc/doxygen/Doxyfile_med_user.in | 6 +- doc/doxygen/medcoupling.dox | 208 ++++++++++++++++-------- src/MEDCoupling/MEDCouplingPointSet.hxx | 10 +- 3 files changed, 154 insertions(+), 70 deletions(-) diff --git a/doc/doxygen/Doxyfile_med_user.in b/doc/doxygen/Doxyfile_med_user.in index e11149c69..afc0ee9e8 100644 --- a/doc/doxygen/Doxyfile_med_user.in +++ b/doc/doxygen/Doxyfile_med_user.in @@ -214,13 +214,13 @@ GENERATE_XML = NO # Configuration options related to the preprocessor #--------------------------------------------------------------------------- ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = NO -EXPAND_ONLY_PREDEF = NO +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES SEARCH_INCLUDES = YES INCLUDE_PATH = INCLUDE_FILE_PATTERNS = PREDEFINED = -EXPAND_AS_DEFINED = +EXPAND_AS_DEFINED = MEDCOUPLING_EXPORT MEDCOUPLINGREMAPPER_EXPORT SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- # Configuration::addtions related to external references diff --git a/doc/doxygen/medcoupling.dox b/doc/doxygen/medcoupling.dox index 2fb227459..b1590229d 100644 --- a/doc/doxygen/medcoupling.dox +++ b/doc/doxygen/medcoupling.dox @@ -20,77 +20,23 @@ developped to be compatible with HPC constraints (compact structures, limitation of copies and launching of CPU consuming algorithms only when absolutely needed ). -\section MEDCouplingMainConc Main Concepts - -- \ref MEDCouplingMeshesP "Meshes" -- \ref MEDCouplingFieldsP "Fields" - -\section MEDCouplingFirstSteps1 Building an array from scratch +\section MEDCouplingMainBasics Basics -All of exemples given here make the assumption that the \c ParaMEDMEM -namespace is visible ( by calling for example \c using \c -namespace \c ParaMEDMEM; ). - -Here a description of typical usages to use \ref ParaMEDMEM::DataArrayDouble "MEDCoupling arrays". -In this example we will create arrays with 12 tuples constituted each -of 3 components. These arrays will be created using different ways. - -\code - -const int nbOfNodes=12; -double coords[3*nbOfNodes]={ ... }; - -DataArrayDouble *myCoords=0; -double *tmp=0; -\endcode +One of the most basic concept mainly used all over MEDCoupling is +MEDCoupling array. This concept is used all over +MEDCoupling/ParaMEDMEM/MEDLoader modules so it should be correctly +handled to play well with \ref MEDCouplingMeshesP "Meshes" and \ref MEDCouplingFieldsP "Fields". -- no copy no ownership -\code -myCoords=DataArrayDouble::New(); -myCoords->useArray(coords,false,CPP_DEALLOC,nbOfNodes,3); -//now use myCoords as you need -... -//myCoords is no more usefully here : release it -myCoords->decrRef(); -\endcode +It exists two type of arrays : + - double precision float array incarnated by ParaMEDMEM::DataArrayDouble class. + - integer array incarnated by ParaMEDMEM::DataArrayInt class. +To know more about arrays \ref MEDCouplingArrayPage "click here for arrays documentation". -- no copy and ownership C++ -\code -myCoords=DataArrayDouble::New(); -tmp=new double[3*nbOfNodes]; -std::copy(coords,coords+3*nbOfNodes,tmp); -myCoords->useArray(tmp,true,CPP_DEALLOC,nbOfNodes,3); -//now use myCoords as you need -... -//myCoords is no more usefully, release it -myCoords->decrRef(); -\endcode - -- no copy and ownership C -\code -myCoords=DataArrayDouble::New(); -tmp=(double *)malloc(3*nbOfNodes*sizeof(double)); -std::copy(coords,coords+3*nbOfNodes,tmp); -myCoords->useArray(tmp,true,C_DEALLOC,nbOfNodes,3); -//now use myCoords as you need -... -//myCoords is no more usefully here : release it -myCoords->decrRef(); -\endcode +\section MEDCouplingMainConc Main Concepts -- copy -\code -myCoords=DataArrayDouble::New(); -myCoords->alloc(nbOfNodes,3); -tmp=myCoords->getPointer(); -std::copy(coords,coords+3*nbOfNodes,tmp); -myCoords->declareAsNew();//you have modified data pointed by internal pointer notify object -//now use myCoords as you need -... -//myCoords is no more usefully here : release it -myCoords->decrRef(); -\endcode +- \ref MEDCouplingMeshesP "Meshes" +- \ref MEDCouplingFieldsP "Fields" \section MEDCouplingFirstSteps2 Building unstructured mesh from scratch @@ -423,3 +369,133 @@ The most important methods are : - \ref ParaMEDMEM::MEDCouplingTimeDiscretization::getValueForTime "getValueForTime" */ + +/*! +\page MEDCouplingArrayPage MEDCoupling Arrays + +\section MEDCouplingArrayIntro Introduction + +This page will try to describe data arrays in MEDCoupling. Presently, +in MEDCoupling it exists two types of arrays : + +- double precision array incarnated by ParaMEDMEM::DataArrayDouble class. +- signed integer (32 bits) array incarnated by ParaMEDMEM::DataArrayInt class. + +\section MEDCouplingArrayBasics Basics concepts + +It will be presented in this section common concept shared by the two classes to \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble" and \ref ParaMEDMEM::DataArrayInt "DataArrayInt". + +- The first thing is that an array has a name (stored as a C++ string). This name is often ignored in MEDCoupling algorithm when arrays are aggregated (field array, connectivity, coordinates). + The reason is that name is stored by the aggregating object. + But it can be very usefull for arrays not aggregated in bigger MEDCoupling object for groups ids and families ids for example. + +- The second thing is the data storage. For obvious reason, MEDCoupling DataArray stores data in a contiguous way in memory like \c std::vector does.\n + +- The third thing is linked to previous point. Data arrays are able to store vectorized data. It is usefull to store the data of a vectorial field. That's why MEDCoupling arrays uses the concepts + of components. To store an array for a vector field on cell with 3 components lying on a mesh having 5 cells. The array will contain 5*3=15 values grouped by 3. + The 5 groups containing each 3 elements are called \b tuples.\n \b Number \b of \b values \b stored \b in \b an \b array \b is \b equal \b to \b number \b of \b tuples + \b multiplied \b by \b number \b of \b components. \n + Generally speaking, except for vector field arrays, and array for nodes coordinates, the number of components is equal to one. + +- The fourth thing is linked to point 2 and 3 as MEDCoupling is developped in C++ the values of arrays are stored tuples by tuples, that is to say in full interlace mode.\n + That is to say, the 15 values in the example in point 3 will be stored like this :\n + \f$ x_0,y_0,z_0,x_1,y_1,z_1,x_2,y_2,z_2,x_3,y_3,z_3,x_4,y_4,z_4 \f$ where x stands for component #0, y for component #1 and z for component #2 + As consequence \b all \b algorithms \b in \b ParaMEDMEM \b are \b working \b in \b full \b interlace \b mode. + +- The fifth thing is that each components of an array has info stored in a string. If a unit is desired to be added on components the following convention should be used "MY_COMPO_INFO [MYUNIT]".\n + Unit should be put between "[" and "]" after info and one space character. + +- The sixth thing is that MEDCoupling arrays inherits from \ref ParaMEDMEM::TimeLabel "TimeLabel" class. It means that the time stamp attached to array indicates if yes or no the array has been modified. + In C++ if the access of data is direct using non const \c getPointer method it is the reponsability to the use to notify the possible modification. + Inversely if setIJ method is used to modify an array, take care of the fact that the time stamp of the array is modified on each call to setIJ. If huge amount of call to setIJ is required it + is better to use setIJSilent instead and call notifyNew right after instead. + + +\section MEDCouplingArraySteps0 Building an array from scratch in Python + +\verbatim +arrayDouble=DataArrayDouble.New(); +dataDouble=[0.,10.,20.,1.,11.,21.,2.,12.,22.,3.,13.,23.,4.,14.,24.] +arrayDouble.setValues(dataDouble,5,3);# 5 tuples containing each 3 components +##### +arrayInt=DataArrayInt.New(); +dataInt=[0, 10, 20, 1, 11, 21, 2, 12, 22, 3, 13, 23, 4, 14, 24] +arrayInt.setValues(dataInt,5,3);# 5 tuples containing each 3 components +\endverbatim + +\section MEDCouplingArraySteps1 Building an array from scratch in C++ + +All of exemples given here make the assumption that the \c ParaMEDMEM +namespace is visible ( by calling for example \c using \c +namespace \c ParaMEDMEM; ). + +Here a description of typical usages to use \ref ParaMEDMEM::DataArrayDouble "MEDCoupling arrays".\n +In this example we will create arrays with 12 tuples constituted each +of 3 components. These arrays will be created using different ways.\n + +The following code is only based using \ref ParaMEDMEM::DataArrayDouble "DataArrayDouble" +but the use of \ref ParaMEDMEM::DataArrayInt "DataArrayInt" is strictly equivalent. + +\code + +const int nbOfNodes=12; +double coords[3*nbOfNodes]={ ... }; + +DataArrayDouble *myCoords=0; +double *tmp=0; +\endcode + +- no copy no ownership +\code +myCoords=DataArrayDouble::New(); +myCoords->useArray(coords,false,CPP_DEALLOC,nbOfNodes,3); +//now use myCoords as you need +... +//myCoords is no more usefully here : release it +myCoords->decrRef(); +\endcode + + +- no copy and ownership C++ +\code +myCoords=DataArrayDouble::New(); +tmp=new double[3*nbOfNodes]; +std::copy(coords,coords+3*nbOfNodes,tmp); +myCoords->useArray(tmp,true,CPP_DEALLOC,nbOfNodes,3); +//now use myCoords as you need +... +//myCoords is no more usefully, release it +myCoords->decrRef(); +\endcode + +- no copy and ownership C +\code +myCoords=DataArrayDouble::New(); +tmp=(double *)malloc(3*nbOfNodes*sizeof(double)); +std::copy(coords,coords+3*nbOfNodes,tmp); +myCoords->useArray(tmp,true,C_DEALLOC,nbOfNodes,3); +//now use myCoords as you need +... +//myCoords is no more usefully here : release it +myCoords->decrRef(); +\endcode + +- copy +\code +myCoords=DataArrayDouble::New(); +myCoords->alloc(nbOfNodes,3); +tmp=myCoords->getPointer(); +std::copy(coords,coords+3*nbOfNodes,tmp); +myCoords->declareAsNew();//you have modified data pointed by internal pointer notify object +//now use myCoords as you need +... +//myCoords is no more usefully here : release it +myCoords->decrRef(); +\endcode + +\section MEDCouplingArrayRenumbering Array renumbering + +Here is presented all it is necessary to know concerning renumbering. +Renumbering is intensely required in %MEDLoader in %ParaMEDMEM. For MED + +*/ diff --git a/src/MEDCoupling/MEDCouplingPointSet.hxx b/src/MEDCoupling/MEDCouplingPointSet.hxx index 7367d9ca8..4029c373b 100644 --- a/src/MEDCoupling/MEDCouplingPointSet.hxx +++ b/src/MEDCoupling/MEDCouplingPointSet.hxx @@ -34,7 +34,15 @@ namespace ParaMEDMEM { class DataArrayInt; class DataArrayDouble; - + + /*! + * This class is abstract and not instanciable. + * ParaMEDMEM::MEDCouplingUMesh class inherits from this class. + * This class aggregates an array '_coords' containing nodes coordinates. + * So all operations on coordinates are managed by this class. + * This is the case for example for following methods : + * rotation, translation, scaling, getNodeIdsNearPoint, boundingbox... + */ class MEDCOUPLING_EXPORT MEDCouplingPointSet : public MEDCouplingMesh { protected: -- 2.39.2