FEI Version of the Day
FEI.hpp
00001 /*
00002 // @HEADER
00003 // ************************************************************************
00004 //             FEI: Finite Element Interface to Linear Solvers
00005 //                  Copyright (2005) Sandia Corporation.
00006 //
00007 // Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation, the
00008 // U.S. Government retains certain rights in this software.
00009 //
00010 // Redistribution and use in source and binary forms, with or without
00011 // modification, are permitted provided that the following conditions are
00012 // met:
00013 //
00014 // 1. Redistributions of source code must retain the above copyright
00015 // notice, this list of conditions and the following disclaimer.
00016 //
00017 // 2. Redistributions in binary form must reproduce the above copyright
00018 // notice, this list of conditions and the following disclaimer in the
00019 // documentation and/or other materials provided with the distribution.
00020 //
00021 // 3. Neither the name of the Corporation nor the names of the
00022 // contributors may be used to endorse or promote products derived from
00023 // this software without specific prior written permission.
00024 //
00025 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
00026 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00027 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00028 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
00029 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00030 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00031 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00032 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00033 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00034 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00035 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00036 //
00037 // Questions? Contact Alan Williams (william@sandia.gov) 
00038 //
00039 // ************************************************************************
00040 // @HEADER
00041 */
00042 
00043 #ifndef _FEI_hpp_
00044 #define _FEI_hpp_
00045 
00046 //
00047 //=========================================================================
00048 // public C++ interface definition for FEI, version 2.1, Jan. 25, 2001
00049 //
00050 // This interface header is the C++ expression of the Finite Element
00051 // Interface to Linear Solvers.
00052 //
00053 //=========================================================================
00054 //
00055 // Below is a list of the functions in FEI 2.x, grouped roughly by
00056 // usage categories, with the initialization and load groups (1 and 2)
00057 // also reflecting common calling order.
00058 //
00059 //===================================================================
00060 //
00061 //  (0) Construction
00062 //  ----------------
00063 //
00064 //  <Implementation-dependent>
00065 //
00066 //
00067 //  (1) initialization
00068 //  ------------------
00069 //
00070 //      parameters
00071 //      setIDLists
00072 //      initSolveStep
00073 //
00074 //      initFields
00075 //      initElemBlock
00076 //
00077 //      initElem
00078 //
00079 //      initSharedNodes
00080 //
00081 //      initCRMult
00082 //      initCRPen
00083 //      initSlaveVariable
00084 //
00085 //      initComplete
00086 //
00087 //
00088 //  (2) load data
00089 //  -------------
00090 //
00091 //      setLHSID
00092 //      setRHSID
00093 //
00094 //      loadNodeBCs
00095 //      loadElemBCs
00096 //
00097 //      sumInElem
00098 //      sumInElemMatrix
00099 //      sumInElemRHS
00100 //
00101 //      loadCRMult
00102 //      loadCRPen
00103 //
00104 //      setMatScalars
00105 //      setRHSScalars
00106 //
00107 //      loadComplete
00108 //
00109 //  (3) equation solution
00110 //  ---------------------
00111 //
00112 //      residualNorm
00113 //      solve
00114 //
00115 //
00116 //  (4) return of solution data
00117 //  ---------------------------
00118 //
00119 //      getBlockNodeSolution
00120 //      getBlockFieldNodeSolution
00121 //      getBlockElemSolution
00122 //      getCRMultipliers
00123 //
00124 //  (5) initial guess 'put'ing
00125 //  --------------------------
00126 //
00127 //      putBlockNodeSolution
00128 //      putBlockFieldNodeSolution
00129 //      putBlockElemSolution
00130 //      putCRMultParam
00131 //      putNodalFieldData
00132 //
00133 //  (6) resetting functions
00134 //  -------------------------
00135 //
00136 //      resetSystem
00137 //      resetMatrix
00138 //      resetRHSVector
00139 //      resetInitialGuess
00140 //      deleteMultCRs
00141 //
00142 //  (7) query functions
00143 //  -------------------
00144 //
00145 //      version
00146 //      cumulative_cpu_times
00147 //
00148 //      iterations
00149 //      getNumSolnParams
00150 //      getNumElemBlocks
00151 //      getNumBlockActNodes
00152 //      getNumBlockActEqns
00153 //      getNumNodesPerElement
00154 //      getNumEqnsPerElement
00155 //      getNumBlockElements
00156 //      getNumBlockElemDOF
00157 //      getNumCRMultipliers
00158 //      getCRMultIDList
00159 //      getBlockNodeIDList
00160 //      getBlockElemIDList
00161 //      getFieldSize
00162 //      getEqnNumbers
00163 //      getNodalFieldSolution
00164 //      getNumLocalNodes
00165 //      getLocalNodeIDList
00166 //
00167  
00168 #include <fei_macros.hpp>
00169 #include <fei_defs.h>
00170 
00179 class FEI { 
00180  
00181   public: 
00182 
00185    virtual ~FEI() {} 
00186 
00195    virtual int parameters(int numParams, 
00196                           const char *const* paramStrings) = 0;
00197 
00214    virtual int setIDLists( int numMatrices,
00215                            const int* matrixIDs,
00216                            int numRHSs,
00217                            const int* rhsIDs ) = 0;
00218 
00219 
00228    virtual int setSolveType( int solveType ) = 0;    
00229 
00244    virtual int initFields( int numFields,
00245                            const int *fieldSizes, 
00246                            const int *fieldIDs,
00247                            const int *fieldTypes = NULL ) = 0;
00248                                 
00270    virtual int initElemBlock( GlobalID elemBlockID,
00271                               int numElements,
00272                               int numNodesPerElement,
00273                               const int *numFieldsPerNode,
00274                               const int *const *nodalFieldIDs,
00275                               int numElemDofFieldsPerElement,
00276                               const int* elemDOFFieldIDs,
00277                               int interleaveStrategy ) = 0;
00278  
00287    virtual int initElem( GlobalID elemBlockID,
00288                          GlobalID elemID, 
00289                          const GlobalID *elemConn ) = 0; 
00290  
00306    virtual int initSharedNodes( int numSharedNodes,
00307                                 const GlobalID *sharedNodeIDs,  
00308                                 const int *numProcsPerNode,
00309                                 const int *const *sharingProcIDs ) = 0;
00310  
00319    virtual int initCRMult( int numCRNodes,
00320                            const GlobalID* CRNodeIDs,
00321                            const int *CRFieldIDs,
00322                            int& CRID ) = 0;
00323  
00332    virtual int initCRPen( int numCRNodes,
00333                           const GlobalID* CRNodeIDs, 
00334                           const int *CRFieldIDs,
00335                           int& CRID ) = 0; 
00336 
00384    virtual int initSlaveVariable(GlobalID slaveNodeID,
00385                                  int slaveFieldID,
00386                                  int offsetIntoSlaveField,
00387                                  int numMasterNodes,
00388                                  const GlobalID* masterNodeIDs,
00389                                  const int* masterFieldIDs,
00390                                  const double* weights,
00391                                  double rhsValue) = 0;
00392 
00399    virtual int initComplete() = 0;
00400 
00401      
00402 // Load Phase.......................................... 
00403 
00410    virtual int setCurrentMatrix(int matrixID) = 0;
00411 
00418    virtual int setCurrentRHS(int rhsID) = 0;
00419 
00423    virtual int resetSystem(double s=0.0) = 0;
00424 
00429    virtual int resetMatrix(double s=0.0) = 0;
00430 
00434    virtual int resetRHSVector(double s=0.0) = 0;
00435 
00441    virtual int resetInitialGuess(double s) = 0;
00442 
00447    virtual int deleteMultCRs() = 0;
00448 
00467     virtual int loadNodeBCs(int numNodes,
00468                             const GlobalID *nodeIDs,
00469                             int fieldID,
00470                             const int* offsetsIntoField,
00471                             const double* prescribedValues) = 0;
00472 
00495    virtual int loadElemBCs( int numElems,
00496                             const GlobalID *elemIDs,
00497                             int fieldID,
00498                             const double *const *alpha,  
00499                             const double *const *beta,  
00500                             const double *const *gamma ) = 0;
00501 
00517    virtual int sumInElem(GlobalID elemBlockID,
00518                             GlobalID elemID,  
00519                             const GlobalID* elemConn,
00520                             const double* const* elemStiffness,
00521                             const double* elemLoad,
00522                             int elemFormat) = 0;
00523      
00538    virtual int sumInElemMatrix(GlobalID elemBlockID,
00539                                GlobalID elemID,  
00540                                const GlobalID* elemConn,
00541                                const double* const* elemStiffness,
00542                                int elemFormat) = 0;
00543      
00552    virtual int sumInElemRHS(GlobalID elemBlockID,
00553                             GlobalID elemID,  
00554                             const GlobalID* elemConn,
00555                             const double* elemLoad) = 0;
00556      
00566    virtual int loadCRMult(int CRMultID, int numCRNodes,
00567                           const GlobalID* CRNodeIDs,
00568                           const int* CRFieldIDs,
00569                           const double* CRWeights,
00570                           double CRValue) = 0;
00571  
00582    virtual int loadCRPen(int CRPenID, int numCRNodes,
00583                          const GlobalID* CRNodeIDs,
00584                          const int* CRFieldIDs,
00585                          const double* CRWeights,
00586                          double CRValue,
00587                          double penValue) = 0;
00588 
00590    virtual int putIntoRHS(int IDType,
00591                           int fieldID,
00592                           int numIDs,
00593                           const GlobalID* IDs,
00594                           const double* coefficients) = 0;
00595 
00597    virtual int sumIntoRHS(int IDType,
00598                           int fieldID,
00599                           int numIDs,
00600                           const GlobalID* IDs,
00601                           const double* coefficients) = 0;
00602 
00603    virtual int sumIntoMatrixDiagonal(int /*IDType*/,
00604                                      int /*fieldID*/,
00605                                      int /*numIDs*/,
00606                                      const GlobalID* /*IDs*/,
00607                                      const double* /*coefficients*/)
00608     { return -1; }
00609 
00617    virtual int setMatScalars( int numScalars,
00618                               const int* IDs,
00619                               const double* scalars ) = 0;
00620 
00628    virtual int setRHSScalars( int numScalars,
00629                               const int* IDs,
00630                               const double* scalars) = 0;
00631 
00636    virtual int loadComplete(bool applyBCs=true,
00637                             bool globalAssemble=true) = 0;
00638 
00639 // Equation solution services..................................... 
00640  
00653    virtual int residualNorm(int whichNorm, int numFields,
00654                              int* fieldIDs, double* norms) = 0;
00655 
00666    virtual int solve(int& status) = 0;
00667 
00668  
00669 // Solution return services....................................... 
00670 
00674    virtual int iterations(int& itersTaken) const = 0;
00675  
00680    virtual int getFieldSize(int fieldID, int& numScalars) = 0;
00681 
00694    virtual int getEqnNumbers(GlobalID ID,
00695                              int idType, 
00696                              int fieldID,
00697                              int& numEqns,
00698                              int* eqnNumbers) = 0;
00699 
00712    virtual int getNodalFieldSolution(int fieldID,
00713                                      int numNodes,
00714                                      const GlobalID* nodeIDs,
00715                                      double* results) = 0;
00716 
00722    virtual int getNumLocalNodes(int& numNodes) = 0;
00723 
00735    virtual int getLocalNodeIDList(int& numNodes,
00736                                   GlobalID* nodeIDs,
00737                                   int lenNodeIDs) = 0;
00738 
00742    virtual int putNodalFieldData(int fieldID,
00743                                  int numNodes,
00744                                  const GlobalID* nodeIDs,
00745                                  const double* data) = 0;
00746 
00764    virtual int getBlockNodeSolution( GlobalID elemBlockID,  
00765                                      int numNodes,
00766                                      const GlobalID *nodeIDs, 
00767                                      int *offsets,  
00768                                      double *results ) = 0;
00769 
00784    virtual int getNodalSolution(int numNodes,
00785                                 const GlobalID* nodeIDs,
00786                                 int* offsets,
00787                                 double* results) = 0;
00788  
00799    virtual int getBlockFieldNodeSolution(GlobalID elemBlockID,
00800                                           int fieldID,
00801                                           int numNodes, 
00802                                           const GlobalID *nodeIDs, 
00803                                           double *results) = 0;
00804          
00814    virtual int getBlockElemSolution( GlobalID elemBlockID,  
00815                                      int numElems,
00816                                      const GlobalID *elemIDs,
00817                                      int& numElemDOFPerElement, 
00818                                      double *results ) = 0;
00819 
00824    virtual int getNumCRMultipliers(int& numMultCRs) = 0;
00825 
00832    virtual int getCRMultIDList(int numMultCRs, int* multIDs) = 0;
00833 
00841    virtual int getCRMultipliers(int numCRs, 
00842                                  const int *CRIDs,  
00843                                  double *results) = 0;
00844 
00845  
00846 // Some 'put' methods paralleling the solution 'get' functions.
00847 // the int sizing parameters are passed for error-checking purposes, so
00848 // that the interface implementation can tell if the passed estimate
00849 // vectors make sense -before- an attempt is made to utilize them as
00850 // initial guesses by unpacking them into the solver's native solution
00851 // vector format.
00852 
00863    virtual int putBlockNodeSolution(GlobalID elemBlockID, 
00864                                      int numNodes, 
00865                                      const GlobalID *nodeIDs, 
00866                                      const int *offsets,
00867                                      const double *estimates) = 0;
00868 
00877    virtual int putBlockFieldNodeSolution(GlobalID elemBlockID, 
00878                                           int fieldID, 
00879                                           int numNodes, 
00880                                           const GlobalID *nodeIDs, 
00881                                           const double *estimates) = 0;
00882          
00892    virtual int putBlockElemSolution( GlobalID elemBlockID,  
00893                                      int numElems, 
00894                                      const GlobalID *elemIDs, 
00895                                      int dofPerElem,
00896                                      const double *estimates) = 0;
00897   
00903    virtual int putCRMultipliers( int numMultCRs,
00904                                  const int* CRMultIDs,
00905                                  const double *multEstimates ) = 0;
00906 
00907 
00908 // utility query functions..............
00909 
00918    virtual int getBlockNodeIDList( GlobalID elemBlockID,
00919                                    int numNodes,
00920                                    GlobalID *nodeIDs ) = 0;
00921                                
00927    virtual int getBlockElemIDList(GlobalID elemBlockID, 
00928                                    int numElems,
00929                                    GlobalID *elemIDs ) = 0;
00930  
00931 // miscellaneous self-explanatory query functions............ 
00932 
00941    virtual int version(const char*& versionString) = 0;
00942 
00950    virtual int cumulative_cpu_times(double& initPhase,
00951                                     double& loadPhase,
00952                                     double& solve,
00953                                     double& solnReturn) = 0;
00954  
00961    virtual int getNumSolnParams( GlobalID globalNodeID,
00962                                  int& numSolnParams) const = 0;
00963 
00967    virtual int getNumElemBlocks(int& numElemBlocks) const = 0;
00968 
00973    virtual int getNumBlockActNodes( GlobalID elemBlockID,
00974                                     int& numNodes) const = 0;
00975 
00981    virtual int getNumBlockActEqns( GlobalID elemBlockID,
00982                                    int& numEqns) const = 0;
00983 
00989    virtual int getNumNodesPerElement( GlobalID elemBlockID,
00990                                       int& nodesPerElem) const = 0;
00991     
00997    virtual int getNumEqnsPerElement( GlobalID elemBlockID,
00998                                      int& eqnsPerElem) const = 0;
00999 
01004    virtual int getNumBlockElements( GlobalID blockID,
01005                                     int& numElems) const = 0;
01006 
01011    virtual int getNumBlockElemDOF( GlobalID blockID,
01012                                    int& DOFPerElem) const = 0;
01013 
01014 };
01015 
01016 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Friends