FEI.hpp

#ifndef _FEI_hpp_
#define _FEI_hpp_
/*--------------------------------------------------------------------*/
/*    Copyright 2005 Sandia Corporation.                              */
/*    Under the terms of Contract DE-AC04-94AL85000, there is a       */
/*    non-exclusive license for use of this work by or on behalf      */
/*    of the U.S. Government.  Export of this program may require     */
/*    a license from the United States Government.                    */
/*--------------------------------------------------------------------*/

//
//=========================================================================
// public C++ interface definition for FEI, version 2.1, Jan. 25, 2001
//
// This interface header is the C++ expression of the Finite Element
// Interface to Linear Solvers.
//
//=========================================================================
//
// Below is a list of the functions in FEI 2.x, grouped roughly by
// usage categories, with the initialization and load groups (1 and 2)
// also reflecting common calling order.
//
//===================================================================
//
//  (0) Construction
//  ----------------
//
//  <Implementation-dependent>
//
//
//  (1) initialization
//  ------------------
//
//      parameters
//      setIDLists
//      initSolveStep
//
//      initFields
//      initElemBlock
//
//      initElem
//
//      initSharedNodes
//
//      initCRMult
//      initCRPen
//      initSlaveVariable
//
//      initComplete
//
//
//  (2) load data
//  -------------
//
//      setLHSID
//      setRHSID
//
//      loadNodeBCs
//      loadElemBCs
//
//      sumInElem
//      sumInElemMatrix
//      sumInElemRHS
//
//      loadCRMult
//      loadCRPen
//
//      setMatScalars
//      setRHSScalars
//
//      loadComplete
//
//  (3) equation solution
//  ---------------------
//
//      residualNorm
//      solve
//
//
//  (4) return of solution data
//  ---------------------------
//
//      getBlockNodeSolution
//      getBlockFieldNodeSolution
//      getBlockElemSolution
//      getCRMultipliers
//
//  (5) initial guess 'put'ing
//  --------------------------
//
//      putBlockNodeSolution
//      putBlockFieldNodeSolution
//      putBlockElemSolution
//      putCRMultParam
//      putNodalFieldData
//
//  (6) resetting functions
//  -------------------------
//
//      resetSystem
//      resetMatrix
//      resetRHSVector
//      resetInitialGuess
//      deleteMultCRs
//
//  (7) query functions
//  -------------------
//
//      version
//      cumulative_cpu_times
//
//      iterations
//      getNumSolnParams
//      getNumElemBlocks
//      getNumBlockActNodes
//      getNumBlockActEqns
//      getNumNodesPerElement
//      getNumEqnsPerElement
//      getNumBlockElements
//      getNumBlockElemDOF
//      getNumCRMultipliers
//      getCRMultIDList
//      getBlockNodeIDList
//      getBlockElemIDList
//      getFieldSize
//      getEqnNumbers
//      getNodalFieldSolution
//      getNumLocalNodes
//      getLocalNodeIDList
//
 
#include <fei_macros.hpp>
#include <fei_defs.h>

class FEI { 
 
  public: 

   virtual ~FEI() {} 

   virtual int parameters(int numParams, 
                          const char *const* paramStrings) = 0;

   virtual int setIDLists( int numMatrices,
                           const int* matrixIDs,
                           int numRHSs,
                           const int* rhsIDs ) = 0;


   virtual int setSolveType( int solveType ) = 0;    

   virtual int initFields( int numFields,
                           const int *fieldSizes, 
                           const int *fieldIDs,
                           const int *fieldTypes = NULL ) = 0;
                                
   virtual int initElemBlock( GlobalID elemBlockID,
                              int numElements,
                              int numNodesPerElement,
                              const int *numFieldsPerNode,
                              const int *const *nodalFieldIDs,
                              int numElemDofFieldsPerElement,
                              const int* elemDOFFieldIDs,
                              int interleaveStrategy ) = 0;
 
   virtual int initElem( GlobalID elemBlockID,
                         GlobalID elemID, 
                         const GlobalID *elemConn ) = 0; 
 
   virtual int initSharedNodes( int numSharedNodes,
                                const GlobalID *sharedNodeIDs,  
                                const int *numProcsPerNode,
                                const int *const *sharingProcIDs ) = 0;
 
   virtual int initCRMult( int numCRNodes,
                           const GlobalID* CRNodeIDs,
                           const int *CRFieldIDs,
                           int& CRID ) = 0;
 
   virtual int initCRPen( int numCRNodes,
                          const GlobalID* CRNodeIDs, 
                          const int *CRFieldIDs,
                          int& CRID ) = 0; 

   virtual int initSlaveVariable(GlobalID slaveNodeID,
                                 int slaveFieldID,
                                 int offsetIntoSlaveField,
                                 int numMasterNodes,
                                 const GlobalID* masterNodeIDs,
                                 const int* masterFieldIDs,
                                 const double* weights,
                                 double rhsValue) = 0;

   virtual int initComplete() = 0;

     
// Load Phase.......................................... 

   virtual int setCurrentMatrix(int matrixID) = 0;

   virtual int setCurrentRHS(int rhsID) = 0;

   virtual int resetSystem(double s=0.0) = 0;

   virtual int resetMatrix(double s=0.0) = 0;

   virtual int resetRHSVector(double s=0.0) = 0;

   virtual int resetInitialGuess(double s) = 0;

   virtual int deleteMultCRs() = 0;

    virtual int loadNodeBCs(int numNodes,
                            const GlobalID *nodeIDs,
                            int fieldID,
                            const int* offsetsIntoField,
                            const double* prescribedValues) = 0;

   virtual int loadElemBCs( int numElems,
                            const GlobalID *elemIDs,
                            int fieldID,
                            const double *const *alpha,  
                            const double *const *beta,  
                            const double *const *gamma ) = 0;

   virtual int sumInElem(GlobalID elemBlockID,
                            GlobalID elemID,  
                            const GlobalID* elemConn,
                            const double* const* elemStiffness,
                            const double* elemLoad,
                            int elemFormat) = 0;
     
   virtual int sumInElemMatrix(GlobalID elemBlockID,
                               GlobalID elemID,  
                               const GlobalID* elemConn,
                               const double* const* elemStiffness,
                               int elemFormat) = 0;
     
   virtual int sumInElemRHS(GlobalID elemBlockID,
                            GlobalID elemID,  
                            const GlobalID* elemConn,
                            const double* elemLoad) = 0;
     
   virtual int loadCRMult(int CRMultID, int numCRNodes,
                          const GlobalID* CRNodeIDs,
                          const int* CRFieldIDs,
                          const double* CRWeights,
                          double CRValue) = 0;
 
   virtual int loadCRPen(int CRPenID, int numCRNodes,
                         const GlobalID* CRNodeIDs,
                         const int* CRFieldIDs,
                         const double* CRWeights,
                         double CRValue,
                         double penValue) = 0;

   virtual int putIntoRHS(int IDType,
                          int fieldID,
                          int numIDs,
                          const GlobalID* IDs,
                          const double* coefficients) = 0;

   virtual int sumIntoRHS(int IDType,
                          int fieldID,
                          int numIDs,
                          const GlobalID* IDs,
                          const double* coefficients) = 0;

   virtual int sumIntoMatrixDiagonal(int /*IDType*/,
                                     int /*fieldID*/,
                                     int /*numIDs*/,
                                     const GlobalID* /*IDs*/,
                                     const double* /*coefficients*/)
    { return -1; }

   virtual int setMatScalars( int numScalars,
                              const int* IDs,
                              const double* scalars ) = 0;

   virtual int setRHSScalars( int numScalars,
                              const int* IDs,
                              const double* scalars) = 0;

   virtual int loadComplete(bool applyBCs=true,
                            bool globalAssemble=true) = 0;

// Equation solution services..................................... 
 
   virtual int residualNorm(int whichNorm, int numFields,
                             int* fieldIDs, double* norms) = 0;

   virtual int solve(int& status) = 0;

 
// Solution return services....................................... 

   virtual int iterations(int& itersTaken) const = 0;
 
   virtual int getFieldSize(int fieldID, int& numScalars) = 0;

   virtual int getEqnNumbers(GlobalID ID,
                             int idType, 
                             int fieldID,
                             int& numEqns,
                             int* eqnNumbers) = 0;

   virtual int getNodalFieldSolution(int fieldID,
                                     int numNodes,
                                     const GlobalID* nodeIDs,
                                     double* results) = 0;

   virtual int getNumLocalNodes(int& numNodes) = 0;

   virtual int getLocalNodeIDList(int& numNodes,
                                  GlobalID* nodeIDs,
                                  int lenNodeIDs) = 0;

   virtual int putNodalFieldData(int fieldID,
                                 int numNodes,
                                 const GlobalID* nodeIDs,
                                 const double* data) = 0;

   virtual int getBlockNodeSolution( GlobalID elemBlockID,  
                                     int numNodes,
                                     const GlobalID *nodeIDs, 
                                     int *offsets,  
                                     double *results ) = 0;

   virtual int getNodalSolution(int numNodes,
                                const GlobalID* nodeIDs,
                                int* offsets,
                                double* results) = 0;
 
   virtual int getBlockFieldNodeSolution(GlobalID elemBlockID,
                                          int fieldID,
                                          int numNodes, 
                                          const GlobalID *nodeIDs, 
                                          double *results) = 0;
         
   virtual int getBlockElemSolution( GlobalID elemBlockID,  
                                     int numElems,
                                     const GlobalID *elemIDs,
                                     int& numElemDOFPerElement, 
                                     double *results ) = 0;

   virtual int getNumCRMultipliers(int& numMultCRs) = 0;

   virtual int getCRMultIDList(int numMultCRs, int* multIDs) = 0;

   virtual int getCRMultipliers(int numCRs, 
                                 const int *CRIDs,  
                                 double *results) = 0;

 
// Some 'put' methods paralleling the solution 'get' functions.
// the int sizing parameters are passed for error-checking purposes, so
// that the interface implementation can tell if the passed estimate
// vectors make sense -before- an attempt is made to utilize them as
// initial guesses by unpacking them into the solver's native solution
// vector format.

   virtual int putBlockNodeSolution(GlobalID elemBlockID, 
                                     int numNodes, 
                                     const GlobalID *nodeIDs, 
                                     const int *offsets,
                                     const double *estimates) = 0;

   virtual int putBlockFieldNodeSolution(GlobalID elemBlockID, 
                                          int fieldID, 
                                          int numNodes, 
                                          const GlobalID *nodeIDs, 
                                          const double *estimates) = 0;
         
   virtual int putBlockElemSolution( GlobalID elemBlockID,  
                                     int numElems, 
                                     const GlobalID *elemIDs, 
                                     int dofPerElem,
                                     const double *estimates) = 0;
  
   virtual int putCRMultipliers( int numMultCRs,
                                 const int* CRMultIDs,
                                 const double *multEstimates ) = 0;


// utility query functions..............

   virtual int getBlockNodeIDList( GlobalID elemBlockID,
                                   int numNodes,
                                   GlobalID *nodeIDs ) = 0;
                               
   virtual int getBlockElemIDList(GlobalID elemBlockID, 
                                   int numElems,
                                   GlobalID *elemIDs ) = 0;
 
// miscellaneous self-explanatory query functions............ 

   virtual int version(const char*& versionString) = 0;

   virtual int cumulative_cpu_times(double& initPhase,
                                    double& loadPhase,
                                    double& solve,
                                    double& solnReturn) = 0;
 
   virtual int getNumSolnParams( GlobalID globalNodeID,
                                 int& numSolnParams) const = 0;

   virtual int getNumElemBlocks(int& numElemBlocks) const = 0;

   virtual int getNumBlockActNodes( GlobalID elemBlockID,
                                    int& numNodes) const = 0;

   virtual int getNumBlockActEqns( GlobalID elemBlockID,
                                   int& numEqns) const = 0;

   virtual int getNumNodesPerElement( GlobalID elemBlockID,
                                      int& nodesPerElem) const = 0;
    
   virtual int getNumEqnsPerElement( GlobalID elemBlockID,
                                     int& eqnsPerElem) const = 0;

   virtual int getNumBlockElements( GlobalID blockID,
                                    int& numElems) const = 0;

   virtual int getNumBlockElemDOF( GlobalID blockID,
                                   int& DOFPerElem) const = 0;

};

#endif