ModFEM: include/aph_intf.h Source File

00001 /************************************************************************
00002 File aph_intf.h - interface with approximation modules of the code
00003 
00004 Contains declarations of constants and interface routines:
00005   apr_module_introduce - to return the approximation method's name
00006   apr_get_mesh_id - to return the ID of the associated mesh
00007   apr_get_mixed_second_field_id - to return ID of second field in mixed approximation
00008   apr_get_nreq - to return the number of components in solution vector
00009   apr_get_mixed_nreq - to return the number of components in solution vector for mixed field
00010   apr_get_nr_sol - to return the number of solution vectors stored
00011   apr_get_base_type - to return the type of basis functions
00012   apr_get_ent_pdeg - to return the degree of approximation symbol
00013                       associated with a given mesh entity
00014   apr_set_ent_pdeg - to set the degree of approximation index
00015                       associated with a given mesh entity
00016   apr_get_ent_numshap - to return the number of shape functions (vector DOFs)
00017                     associated with a given mesh entity
00018   apr_get_ent_nrdofs - to return the number of dofs associated with
00019                       a given mesh entity
00020   apr_get_el_pdeg - to return the degree of approximation vector
00021                       associated with a given element
00022   apr_set_el_pdeg - to set the degree of approximation vector
00023                       associated with a given element
00024   apr_get_mixed_pdeg - to get approximation pdeg associated with 
00025                        first or second field in mixed approximation
00026   apr_get_el_geo_pdeg - to return the degree of approximation
00027                                           associated with geometric transformation of element
00028   apr_set_el_geo_pdeg - to set the degree of approximation
00029                                           associated with geometric transformation of element
00030   apr_move_node - to move real geometric node by vector, node is related to vertex / edge / face or element
00031   apr_node_coor - to return node cordinates related to vertices / edges or faces
00032   apr_get_el_pdeg_numshap - to return the number of shape functions
00033                     (scalar DOFs) for an element given its
00034                 degree of approximation symbol or vector pdeg
00035   apr_get_el_dofs - to return the number and the list of element's degrees
00036             of freedom (corresponding to standard shape functions)
00037   apr_get_el_geo_dofs - to get geometric coordinates for element
00038   apr_get_nr_dof_ents - to return a global number of dof_entities
00039   apr_get_nrdofs_glob - to return a global dimension of the problem
00040   apr_read_ent_dofs - to read a vector of dofs associated with a given
00041               mesh entity from approximation field data structure
00042   apr_write_ent_dofs - to write a vector of dofs associated with a given
00043                mesh entity to approximation field data structure
00044   apr_create_ent_dofs - to write a vector of dofs associated with a given
00045                mesh entity to approximation field data structure
00046   apr_free_field - to free approximation field data structure
00047 
00048 Constrained approximation handling:
00049   apr_create_constr_data - to create and fill constraint arrays
00050                    (assuming approximation and mesh data agree)
00051   apr_get_el_constr_data - to return the number and the list of element's real
00052                nodes, with the corresponding constraint coefficients
00053   apr_get_constr_data - to return constraints data for a node (dof entity)
00054 
00055 Numerical integration support
00056   apr_prepare_integration_parameters - used e.g. by apr_num_int_el
00057   apr_num_int_el - to perform numerical integration for an element
00058   apr_get_stiff_mat_data - to return data on dof entities for an element and
00059           to compute or rewrite element's stiffness matrix and RHSV
00060 
00061 Adaptivity supporting functions
00062   apr_limit_deref - to return whether derefinement is allowed or not
00063   apr_limit_ref - to return whether refinement is allowed or not
00064     the routines does not use approximation data structures but the result
00065     depends on the approximation method
00066   apr_refine - to refine an element or the whole mesh checking mesh irregularity
00067   apr_derefine - to derefine an element or the whole mesh with irregularity check
00068 
00069 Utilities:
00070   apr_shape_fun_3D - to compute values of shape functions and their
00071     local derivatives at a point within the master 3D element
00072   apr_elem_calc_3D - to perform element calculations (to provide data on
00073     coordinates, solution, shape functions, etc. for a given point
00074     inside element (given local coordinates Eta[i]);
00075     for geometrically multi-linear or linear 3D elements
00076   apr_set_quadr_3D - to prepare quadrature data for a given element
00077   apr_set_quadr_2D - to prepare quadrature data for a given face
00078   apr_set_quadr_2D_penalty - to prepare penalty quadrature data for a given face
00079   apr_L2_proj - to L2 project a function onto an element
00080   apr_get_profile - to return profile of the solution along a specified line
00081 
00082 
00083 Global (O(N)) functions - very fast, but can be (should be?) parallelized...
00084   apr_init_field - to initiate new approximation field and read its data
00085   apr_write_field - to dump-out field data in the standard MOD_FEM format
00086   apr_check_field - to check approximation field data structure
00087   apr_set_ini_con - to set an initial condition
00088   apr_proj_dof_ref - to rewrite dofs after modifying the mesh
00089   apr_rewr_sol - to rewrite solution from one vector to another
00090   apr_sol_xglob - to return the solution at a point with global
00091     coordinates specified
00092 
00093 apr_create_constr_data - O(N) also!
00094 
00095 ------------------------------
00096 History:
00097     02.2002 - Krzysztof Banas, initial version
00098 *************************************************************************/
00099 
00100 #ifndef _aph_intf_
00101 #define _aph_intf_
00102 
00103 #include <stdio.h>
00104 
00105 #ifdef __cplusplus
00106 extern "C"{
00107 #endif
00108 
00115 /*** CONSTANTS ***/
00116 #define APC_TRUE 1
00117 #define APC_FALSE 0
00118 
00120 #define APC_MAXELP_COMP 5
00121 #define APC_MAXELP_TENS 505 // 6*6*7/2 = 126 shape functions (for DG only scalar)
00122 
00124 #define APC_MAXELVD 130 // was: 300, for degree 707 
00125 
00127 #define APC_MAXELSD 300 // was: 300, for degree 707
00128 #define APC_DOUBLE_MAXELSD 600 // for satisfy plast_flow module in some situation
00129   
00131 #define APC_MAX_GEO_DOFS 18 // maximum is 18 dofs
00132 
00133 /*** CONSTANTS ***/
00134 #define APC_CUR_FIELD_ID  0 
00137 #define APC_NO_DOFS  -1
00138 
00140 #define APC_BASE_TENSOR_DG  1
00141 #define APC_BASE_COMPLETE_DG  2
00142 #define APC_BASE_PRISM_STD  3   
00143 #define APC_BASE_PRISM_QUAD_STD 32 
00144 #define APC_BASE_TETRA_STD  4  
00145 #define APC_BASE_TETRA_QUAD_STD  42  
00148 #define APC_ZERO  0
00149 #define APC_READ  1
00150 #define APC_INIT  2
00151 
00153 // SHOULD BE CHOSEN AS SUBSEQUENT INTEGERS SINCE USED FOR ARRAY INDEXING !!!
00154 #define APC_ELEMENT  4 
00155 #define APC_FACE     3 
00156 #define APC_EDGE     2 
00157 #define APC_VERTEX   1 
00159 #define APC_MIXED_ELEMENT  8 
00160 #define APC_MIXED_FACE     7 
00161 #define APC_MIXED_EDGE     6 
00162 #define APC_MIXED_VERTEX   5 
00164 // NO SECOND FIELD
00165 #define APC_MIXED_NO_SEC_FIELD -1 
00168 // Exact values are used in apr_get_stiff_mat_data
00169 #define APC_NO_COMP    0 
00170 #define APC_COMP_SM    1 
00171 #define APC_COMP_RHS   2 
00172 #define APC_COMP_BOTH  3 
00173 #define APC_COMP_MM  10 
00174 #define APC_REWR_SM    4 
00175 #define APC_REWR_RHS   5 
00176 #define APC_REWR_BOTH  6 
00177 #define APC_REWR_MM  13 
00181 #define APC_REF_ALLOWED 1
00182 #define APC_REF_DENIED  2
00183 #define APC_DEREF_ALLOWED 3
00184 #define APC_DEREF_DENIED  4
00185 
00187 #define APC_LINEAR_APPROXIMATION_PDEG 1 
00188 #define APC_QUADRATIC_HIERACHICAL_APPROXIMATION_PDEG 15 
00189 #define APC_QUADRATIC_APPROXIMATION_PDEG 2 
00190 #define APC_MIXED_P1_P1_APPROXIMATION_PDEG 11 
00191 #define APC_MIXED_P2_P1_APPROXIMATION_PDEG 21 
00192 #define APC_MIXED_P2_P2_APPROXIMATION_PDEG 22 
00195 #define APC_P1_NONE_G1 101 
00196 #define APC_P15_NONE_G1 151 
00197 #define APC_P2_NONE_G1 201 
00198 #define APC_P2_NONE_G2 202 
00199 #define APC_P1_P1_G1 111 
00200 #define APC_P2_P2_G2 222 
00201 #define APC_P2_P1_G2 212 
00202 #define APC_P2_P1_G1 211 
00205 #define APC_TETRA_NUM_SHAP_LINEAR_APROXIMATION 4 
00206 #define APC_TETRA_NUM_SHAP_QUADRATIC_APROXIMATION 10 
00208 #define APC_PRISM_NUM_SHAP_LINEAR_APROXIMATION 6 
00209 #define APC_PRISM_NUM_SHAP_QUADRATIC_APROXIMATION 18 
00210 #define APC_PRISM_NUM_SHAP_HIERARCHICAL_QUADRATIC_APROXIMATION 15 
00212 #define APC_MAX_CONSTR_EL_LOC 10 
00214 
00215 
00216 #define APC_CLOSE 1.0e-6
00217 #define APC_SMALL 1.0e-9
00218 
00219 /*** FUNCTION DECLARATIONS - headers for external functions ***/
00220 
00224 extern int apr_module_introduce(
00226   char* Approx_name 
00227   );
00228 
00233 extern int apr_init_field(  
00234   char Field_type, 
00237   int Control,   
00242   int Mesh_id,   
00243   int Nreq,  
00244   int Nr_sol,    
00245   int Pdeg_in,   
00247   //int GeoPdeg_in,   /* in: degree of approximating polynomial for geometry */
00248   char *Filename, 
00249   double (*Fun_p)(int, double*, int) 
00251   );
00252 
00256 extern int apr_write_field( 
00257   int Field_id,    
00258   int Nreq,        
00259   int Select,      
00260   double Accuracy, 
00262   char *Filename   
00263   );
00264 
00268 extern int apr_check_field(
00269   int Field_id    
00270   );
00271 
00275 extern int apr_get_mesh_id( 
00277   int Field_id     
00278   );
00279 
00283 extern int apr_get_mixed_second_field_id( 
00285   int Field_id     
00286   );
00287 
00291 int apr_get_nreq( 
00293   int Field_id     
00294   );
00295 
00296 /*------------------------------------------------------------
00297   apr_get_mixed_nreq - to return the number of components in solution vector for mixed field
00298 ------------------------------------------------------------*/
00299 int apr_get_mixed_nreq( /* returns: >0 - number of solution components,
00300                                         <0 - error code */
00301   int Field_id     /* in: approximation field ID  */
00302   );
00303 
00307 extern int apr_get_nr_sol(  
00309   int Field_id     
00310   );
00311 
00312 
00318 extern int apr_get_el_pdeg_numshap(
00320   int Field_id,  
00321   int El_id,        
00322   int *Pdeg_vec       
00323   );
00324 
00325 
00326 /*---------------------------------------------------------
00327 apr_get_el_pdeg_numshap_related_with_dof_type - return number of shape functions retated with 
00328                                                   dof type 
00329 ---------------------------------------------------------*/
00330 extern int apr_get_el_pdeg_numshap_related_with_dof_type(
00331          /* returns: >=0 - success code, <0 - error code*/
00332   int Field_id,  /* in: field ID */
00333   int El_id,     /* in: element ID */
00334   int Dof_type,  /* in: dof type */
00335   int *Pdeg      /* in: degree of approximation symbol or vector */
00336 );
00337 
00338 
00349 extern int apr_get_base_type(
00351   int Field_id,  
00352   int El_id 
00353   );
00354 
00359 extern int apr_get_ent_pdeg( 
00362   int Field_id,     
00363   int Ent_type,      
00364   int Ent_id         
00365   );
00366 
00371 extern int apr_set_ent_pdeg( 
00373   int Field_id,     
00374   int Ent_type,      
00375   int Ent_id,         
00376   int Pdeg          
00377   );
00378 
00383 extern int apr_get_el_pdeg( 
00385   int Field_id,     
00386   int El_id,         
00387   int *Pdeg_vec       
00388   );
00389 
00394 extern int apr_set_el_pdeg( 
00396   int Field_id,     
00397   int El_id,         
00398   int *Pdeg       
00399   );
00400 
00405 extern int apr_get_mixed_pdeg( 
00407   int Field_id,     
00408   int *Pdeg_vec       
00409   );
00410 
00415 extern int apr_get_el_geo_pdeg( 
00417   int Field_id,     
00418   int El_id,         
00419   int *Pdeg_vec       
00420   );
00421   
00426 extern int apr_set_el_geo_pdeg( 
00428   int Field_id,     
00429   int El_id,         
00430   int *Pdeg_vec       
00431   );
00432 
00437 extern int apr_move_node( 
00439   int Field_id, /* in: field ID */
00440   int Node_id, /* in: node ID */
00441   int Node_type, /* in: node type - APC_VERTEX / APC_EDGE / APC_FACE */
00442   double *Shift_vec /* in: shift vector */
00443 );
00444   
00448 extern int apr_node_coor( 
00450  int Field_id, /* in: field ID */
00451  int Node_id, /* in: node ID */
00452  int Node_type, /* in: node type - APC_VERTEX / APC_EDGE / APC_FACE */
00453  double *coord /* out: cordinates of node */
00454 );
00455 
00460 extern int apr_get_el_dofs( 
00462   int Field_id,     
00463   int El_id,        
00464   int Vect_id,       
00465   double *El_dofs_std     
00466   );
00467 
00471 extern int apr_get_el_geo_dofs( 
00473   int Field_id, 
00474   int El_id,    
00475   int *GeoDofs_id,    
00476         /*   (Dofs[0] - number of dofs) */
00477   int *GeoDofs_type, 
00478                   /*     (Dofs_type[0] - geo_pdeg */
00479   double *GeoDofs /* out: coordinates of element dofs */
00480   );
00481 
00486 extern int apr_get_ent_numshap( 
00488   int Field_id,     
00489   int Ent_type,      
00490   int Ent_id         
00491   );
00492 
00497 extern int apr_get_ent_nrdofs( 
00499   int Field_id,     
00500   int Ent_type,      
00501   int Ent_id         
00502   );
00503 
00507 extern int apr_get_nrdofs_glob( 
00508   int Field_id    
00509   );
00510 
00515 extern int apr_read_ent_dofs(
00516   int Field_id,     
00517   int Ent_type,      
00518   int Ent_id,        
00519   int Ent_nrdofs,     
00520   int Vect_id,       
00521   double* Vect_dofs  
00522   );
00523 
00524 
00529 extern int apr_write_ent_dofs(
00530   int Field_id,     
00531   int Ent_type,      
00532   int Ent_id,        
00533   int Ent_nrdofs,     
00534   int Vect_id,       
00535   double* Vect_dofs);
00536 
00537 
00542 extern int apr_create_ent_dofs(
00544   int Field_id,      
00545   int Ent_type,      
00546   int Ent_id,        
00547   int Ent_nrdofs,     
00548   int Vect_id,       
00549   double* Vect_dofs  
00550   );
00551 
00555 extern int apr_set_ini_con(
00556   int Field_id,     
00557   double (*Fun_p)(int, double*, int) 
00559   );
00560 
00561 
00565 extern int apr_prepare_integration_parameters( 
00566   int Field_id,     
00567   int El_id,        
00568   int *Geo_order,   
00569   int *Num_geo_dofs,
00570   double* Geo_dofs, 
00571   int *El_mate,     
00572   int *Base,        
00573   int *Pdeg_vec,    
00574   int *Num_shap,    
00575   int *Nreq,        
00576   int *Num_dofs     
00577   );
00578 
00579 
00583 extern int apr_num_int_el(
00584   int Problem_id,
00585   int Field_id,    
00586   int El_id,       
00587   int Comp_sm,     
00592   int *Pdeg_vec,        
00593   double *Sol_dofs_k,   
00595   double *Sol_dofs_n,   
00597   int *diagonal,   
00598   double *Stiff_mat,    
00599   double *Rhs_vect  
00600   );
00601 
00602 
00603 
00608 extern int apr_get_stiff_mat_data(
00609   int Field_id,  
00610   int El_id,     
00611   int Comp_sm,   
00619   char Transpose,
00621   int Pdeg_in,    
00622   int Nreq_in,    
00623   int* Nr_dof_ent,
00626   int* List_dof_ent_type, 
00627   int* List_dof_ent_id,   
00628   int* List_dof_ent_nrdofs,
00629   int* Nrdofs_loc,
00631   double* Stiff_mat,      
00632   double* Rhs_vect        
00633                  );
00634 
00638 extern int apr_proj_dof_ref(
00639   int Field_id,    
00640   int El,      
00642   int Max_elem_id, 
00643   int Max_face_id, 
00644   int Max_edge_id,
00645   int Max_vert_id
00646   );
00647 
00651 extern int apr_rewr_sol(
00652   int Field_id,      
00653   int Sol_from,      
00654   int Sol_to         
00655   );
00656 
00660 extern int apr_free_field(
00661   int Field_id    
00662   );
00663 
00664 
00670 extern int apr_limit_deref(
00671   int Field_id,    
00672   int El_id      
00673   );
00674 
00680 extern int apr_limit_ref(
00681   int Field_id,    
00682   int El_id      
00683   );
00684 
00688 int apr_refine( 
00689   int Field_id,  
00690   int El_id   
00691         );
00692 
00696 int apr_derefine( 
00697   int Field_id, 
00698   int El_id  
00699           );
00700 
00701 /****************** FUNCTIONS IN APS_...._UTIL.C ******************/
00702 
00707 int apr_shape_fun_3D( 
00708     int Base_type,     
00714     int Pdeg,      
00715                /*   a single number, for isotropic p, */
00716                /*   or a combination pdegy*10+pdegx */
00717     double *Eta,       
00718     double *Base_phi,  
00719     double *Base_dphix,
00720     double *Base_dphiy,
00721     double *Base_dphiz 
00722               );
00723 
00724 
00725 #define APC_ELEM_CALC_SHAPE_FUNC_N_VALUES 1
00726 #define APC_ELEM_CALC_DERIVATIVES_AND_JACOBIAN 2
00727 #define APC_ELEM_CALC_ON_FACE(face_number) 3+face_number
00728 
00734 extern double apr_elem_calc_3D(
00738     int Control,    
00739             /*  APC_ELEM_CALC_SHAPE_FUNC_N_VALUES 1  - shape functions and values */
00740             /*  APC_ELEM_CALC_DERIVATIVES_AND_JACOBIAN 2  - derivatives and jacobian */
00742         /*                                         (Control-2)-th element's face */
00743     int Nreq,       
00744     int *Pdeg_vec,      
00745     int Base_type,      
00752     double *Eta,    
00753     double *Node_coor,  
00754     double *Sol_dofs,   
00755     double *Base_phi,   
00756     double *Base_dphix, 
00757     double *Base_dphiy, 
00758     double *Base_dphiz, 
00759     double *Xcoor,      
00760     double *Sol,        
00761     double *Dsolx,      
00762     double *Dsoly,      
00763     double *Dsolz,      
00764     double *Vec_nor     
00765     );
00766 
00770 extern int apr_set_quadr_3D(
00771     int Base_type,     
00774     int *Pdeg_vec,  
00775     int *Ngauss,    
00776     double *Xg, 
00777     double *Wg  
00778     );
00779 
00783 extern int apr_set_quadr_2D(
00784     int Fa_type,    
00785     int Base_type,     
00788     int *Pdeg_vec,  
00789     int *Ngauss,    
00790     double *Xg, 
00791     double *Wg  
00792     );
00793 
00797 extern int apr_set_quadr_2D_penalty(
00798     int Fa_type,    
00799     int Base_type,     
00802     int *Pdeg_vec,  
00803     int *Ngauss,    
00804     double *Xg, 
00805     double *Wg  
00806     );
00807 
00811 extern int apr_L2_proj( 
00812         int Field_id,   
00813     int Mode,   
00820     int El,     
00821     int *Pdeg_vec,  
00822     double* Dofs,   
00824     int *El_from,   
00825     int *Pdeg_vec_from, 
00828     double* Dofs_from, 
00829     double (*Fun_p)(double*,double*,double*,double*)   
00831     );
00832 
00834 enum ape_sol_xglob{
00842     APE_SOL_XGLOB_DEFAULT = 0x00,
00843     APE_SOL_XGLOB_MATCH_ALL_ELEMENTS = 0x01,
00844     APE_SOL_XGLOB_MATCH_WITH_ADAPTATION = 0x02,
00848     APE_SOL_XGLOB_CHECK_ONLY_GIVEN_ELEMENT = 0x04
00849 
00850 };
00851 
00862 extern int apr_sol_xglob(
00863   int Field_id,   
00864   double *Xglob,    
00865   int Nb_sol,    
00866   int* El,  
00868   double* Xloc, 
00869   double *Sol,  
00870   double *Dxsol,  
00871   double *Dysol,  
00872   double *Dzsol,   
00873   double Close_proximity_precision, //< default to APC_CLOSE; how far from element point is considered to be within an element
00874   int Sol_xglob_flags //< see ape_sol_xlgob
00875 );
00876 
00877 
00882 extern int apr_create_constr_data(
00884   int Field_id    
00885   );
00886 
00887 
00888 
00893 extern int apr_get_el_constr_data(
00895   int Field_id,   
00896   int El_id,        
00897   int* Nodes,     
00898               /*    (Nodes[0] - number of nodes) */
00899   int* Nr_constr, 
00900   int* Constr_id, 
00901   int* Constr_type,   
00902   double* Constr_val  
00903   );
00904 
00908 extern int apr_get_constr_data(
00909   int Field_id,     
00910   int Node_id,      
00911   int Node_type,    
00913   int *Constr,      
00918   int *Constr_type  
00921   );
00922 
00923 
00925 //                      to generate plots and diagrams
00926 
00927 extern int apr_get_profile( // returns: >0 - success, <=0 - failure
00928     FILE* filePtr,  //in: pointer to file, where profile will be printed
00929     int fieldId,    //in: field ID
00930     int solNr,  //in: solution number
00931     int nSol,   //in: solution length (no. of components)
00932     double * pt1,   //in: begin point coords
00933     double * pt2,   //in: end point coords
00934     int nPoints //in: number of points (including end points)
00935     );
00936      // end of group
00938 
00939 #ifdef __cplusplus
00940 }
00941 #endif
00942 
00943 #endif