1 /** @defgroup MGparm MGparm class 2 * @brief Parameter which holds useful parameters for generic multigrid 3 * calculations 4 */ 5 6 /** 7 * @file mgparm.h 8 * @ingroup MGparm 9 * @brief Contains declarations for class MGparm 10 * @version $Id$ 11 * @author Nathan A. Baker 12 * 13 * @attention 14 * @verbatim 15 * 16 * APBS -- Adaptive Poisson-Boltzmann Solver 17 * 18 * Nathan A. Baker (nathan.baker@pnnl.gov) 19 * Pacific Northwest National Laboratory 20 * 21 * Additional contributing authors listed in the code documentation. 22 * 23 * Copyright (c) 2010-2014 Battelle Memorial Institute. Developed at the 24 * Pacific Northwest National Laboratory, operated by Battelle Memorial 25 * Institute, Pacific Northwest Division for the U.S. Department of Energy. 26 * 27 * Portions Copyright (c) 2002-2010, Washington University in St. Louis. 28 * Portions Copyright (c) 2002-2010, Nathan A. Baker. 29 * Portions Copyright (c) 1999-2002, The Regents of the University of 30 * California. 31 * Portions Copyright (c) 1995, Michael Holst. 32 * All rights reserved. 33 * 34 * Redistribution and use in source and binary forms, with or without 35 * modification, are permitted provided that the following conditions are met: 36 * 37 * Redistributions of source code must retain the above copyright notice, this 38 * list of conditions and the following disclaimer. 39 * 40 * Redistributions in binary form must reproduce the above copyright notice, 41 * this list of conditions and the following disclaimer in the documentation 42 * and/or other materials provided with the distribution. 43 * 44 * Neither the name of the developer nor the names of its contributors may be 45 * used to endorse or promote products derived from this software without 46 * specific prior written permission. 47 * 48 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 49 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 50 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 51 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 52 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 53 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 54 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 55 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 56 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 57 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 58 * THE POSSIBILITY OF SUCH DAMAGE. 59 * 60 * @endverbatim 61 */ 62 63 64 #ifndef _MGPARM_H_ 65 #define _MGPARM_H_ 66 67 /* Generic header files */ 68 #include "maloc/maloc.h" 69 70 #include "generic/vhal.h" 71 #include "generic/vstring.h" 72 73 /** 74 * @brief Calculation type 75 * @ingroup MGparm 76 */ 77 enum eMGparm_CalcType { 78 MCT_MANUAL=0, /**< mg-manual */ 79 MCT_AUTO=1, /**< mg-auto */ 80 MCT_PARALLEL=2, /**< mg-para */ 81 MCT_DUMMY=3, /**< mg-dummy */ 82 MCT_NONE=4 /**< unspecified */ 83 }; 84 85 /** 86 * @brief Declare MGparm_CalcType type 87 * @ingroup MGparm 88 */ 89 typedef enum eMGparm_CalcType MGparm_CalcType; 90 91 /** 92 * @brief Centering method 93 * @ingroup MGparm 94 */ 95 enum eMGparm_CentMeth { 96 MCM_POINT=0, /**< Center on a point */ 97 MCM_MOLECULE=1, /**< Center on a molecule */ 98 MCM_FOCUS=2 /**< Determined by focusing */ 99 }; 100 101 /** 102 * @brief Declare MGparm_CentMeth type 103 * @ingroup MGparm 104 */ 105 typedef enum eMGparm_CentMeth MGparm_CentMeth; 106 /** 107 * @ingroup MGparm 108 * @author Nathan Baker and Todd Dolinsky 109 * @brief Parameter structure for MG-specific variables from input files 110 * @note If you add/delete/change something in this class, the member 111 * functions -- especially MGparm_copy -- must be modified 112 * accordingly 113 */ 114 struct sMGparm { 115 116 MGparm_CalcType type; /**< What type of MG calculation? */ 117 int parsed; /**< Has this structure been filled? (0 = no, 1 = yes) */ 118 119 /* *** GENERIC PARAMETERS *** */ 120 int dime[3]; /**< Grid dimensions */ 121 int setdime; /**< Flag, @see dime */ 122 Vchrg_Meth chgm; /**< Charge discretization method */ 123 int setchgm; /**< Flag, @see chgm */ 124 Vchrg_Src chgs; /**< Charge source (Charge, Multipole, Induced Dipole, 125 * NL Induced */ 126 127 /* *** TYPE 0 PARAMETERS (SEQUENTIAL MANUAL) *** */ 128 int nlev; /**< Levels in multigrid hierarchy 129 * @deprecated Just ignored now */ 130 int setnlev; /**< Flag, @see nlev */ 131 double etol; /**< User-defined error tolerance */ 132 int setetol; /**< Flag, @see etol */ 133 double grid[3]; /**< Grid spacings */ 134 int setgrid; /**< Flag, @see grid */ 135 double glen[3]; /**< Grid side lengths. */ 136 int setglen; /**< Flag, @see glen */ 137 MGparm_CentMeth cmeth; /**< Centering method */ 138 double center[3]; /**< Grid center. If ispart = 0, then this is 139 * only meaningful if cmeth = 0. However, if 140 * ispart = 1 and cmeth = MCM_PNT, then this is the 141 * center of the non-disjoint (overlapping) 142 * partition. If ispart = 1 and cmeth = MCM_MOL, then 143 * this is the vector that must be added to the 144 * center of the molecule to give the center of 145 * the non-disjoint partition. */ 146 int centmol; /**< Particular molecule on which we want to center the grid. 147 This should be the appropriate index in an array of molecules, not the 148 positive definite integer specified by the user. */ 149 int setgcent; /**< Flag, @see cmeth */ 150 151 /* ******** TYPE 1 & 2 PARAMETERS (SEQUENTIAL & PARALLEL AUTO-FOCUS) *** */ 152 double cglen[3]; /**< Coarse grid side lengths */ 153 int setcglen; /**< Flag, @see cglen */ 154 double fglen[3]; /**< Fine grid side lengths */ 155 int setfglen; /**< Flag, @see fglen */ 156 MGparm_CentMeth ccmeth; /**< Coarse grid centering method */ 157 double ccenter[3]; /**< Coarse grid center. */ 158 int ccentmol; /**< Particular molecule on which we want to center the grid. 159 This should be the appropriate index in an array of molecules, not the 160 positive definite integer specified by the user. */ 161 int setcgcent; /**< Flag, @see ccmeth */ 162 MGparm_CentMeth fcmeth; /**< Fine grid centering method */ 163 double fcenter[3]; /**< Fine grid center. */ 164 int fcentmol; /**< Particular molecule on which we want to center the grid. 165 This should be the appropriate index in an array of molecules, not the 166 positive definite integer specified by the user. */ 167 int setfgcent; /**< Flag, @see fcmeth */ 168 169 170 /* ********* TYPE 2 PARAMETERS (PARALLEL AUTO-FOCUS) ******** */ 171 double partDisjCenter[3]; /**< This gives the center 172 of the disjoint partitions */ 173 double partDisjLength[3]; /**< This gives the lengths of the disjoint 174 * partitions */ 175 int partDisjOwnSide[6]; /**< Tells whether the boundary points are ours 176 * (1) or not (0) */ 177 178 int pdime[3]; /**< Grid of processors to be used in calculation */ 179 int setpdime; /**< Flag, @see pdime */ 180 int proc_rank; /**< Rank of this processor */ 181 int setrank; /**< Flag, @see proc_rank */ 182 int proc_size; /**< Total number of processors */ 183 int setsize; /**< Flag, @see proc_size */ 184 double ofrac; /**< Overlap fraction between procs */ 185 int setofrac; /**< Flag, @see ofrac */ 186 int async; /**< Processor ID for asynchronous calculation */ 187 int setasync; /**< Flag, @see asynch */ 188 189 int nonlintype; /**< Linearity Type Method to be used */ 190 int setnonlintype; /**< Flag, @see nonlintype */ 191 192 int method; /**< Solver Method */ 193 int setmethod; /**< Flag, @see method */ 194 195 int useAqua; /**< Enable use of lpbe/aqua */ 196 int setUseAqua; /**< Flag, @see useAqua */ 197 }; 198 199 /** @typedef MGparm 200 * @ingroup MGparm 201 * @brief Declaration of the MGparm class as the MGparm structure 202 */ 203 typedef struct sMGparm MGparm; 204 205 /** @brief Get number of grid points in x direction 206 * @ingroup MGparm 207 * @author Nathan Baker 208 * @param thee MGparm object 209 * @returns Number of grid points in the x direction 210 */ 211 VEXTERNC int MGparm_getNx(MGparm *thee); 212 213 /** @brief Get number of grid points in y direction 214 * @ingroup MGparm 215 * @author Nathan Baker 216 * @param thee MGparm object 217 * @returns Number of grid points in the y direction 218 */ 219 VEXTERNC int MGparm_getNy(MGparm *thee); 220 221 /** @brief Get number of grid points in z direction 222 * @ingroup MGparm 223 * @author Nathan Baker 224 * @param thee MGparm object 225 * @returns Number of grid points in the z direction 226 */ 227 VEXTERNC int MGparm_getNz(MGparm *thee); 228 229 /** @brief Get grid spacing in x direction (Å) 230 * @ingroup MGparm 231 * @author Nathan Baker 232 * @param thee MGparm object 233 * @returns Grid spacing in the x direction 234 */ 235 VEXTERNC double MGparm_getHx(MGparm *thee); 236 237 /** @brief Get grid spacing in y direction (Å) 238 * @ingroup MGparm 239 * @author Nathan Baker 240 * @param thee MGparm object 241 * @returns Grid spacing in the y direction 242 */ 243 VEXTERNC double MGparm_getHy(MGparm *thee); 244 245 /** @brief Get grid spacing in z direction (Å) 246 * @ingroup MGparm 247 * @author Nathan Baker 248 * @param thee MGparm object 249 * @returns Grid spacing in the z direction 250 */ 251 VEXTERNC double MGparm_getHz(MGparm *thee); 252 253 /** @brief Set center x-coordinate 254 * @ingroup MGparm 255 * @author Nathan Baker 256 * @param thee MGparm object 257 * @param x x-coordinate 258 */ 259 VEXTERNC void MGparm_setCenterX(MGparm *thee, double x); 260 261 /** @brief Set center y-coordinate 262 * @ingroup MGparm 263 * @author Nathan Baker 264 * @param thee MGparm object 265 * @param y y-coordinate 266 */ 267 VEXTERNC void MGparm_setCenterY(MGparm *thee, double y); 268 269 /** @brief Set center z-coordinate 270 * @ingroup MGparm 271 * @author Nathan Baker 272 * @param thee MGparm object 273 * @param z z-coordinate 274 */ 275 VEXTERNC void MGparm_setCenterZ(MGparm *thee, double z); 276 277 /** @brief Get center x-coordinate 278 * @ingroup MGparm 279 * @author Nathan Baker 280 * @param thee MGparm object 281 * @returns x-coordinate 282 */ 283 VEXTERNC double MGparm_getCenterX(MGparm *thee); 284 285 /** @brief Get center y-coordinate 286 * @ingroup MGparm 287 * @author Nathan Baker 288 * @param thee MGparm object 289 * @returns y-coordinate 290 */ 291 VEXTERNC double MGparm_getCenterY(MGparm *thee); 292 293 /** @brief Get center z-coordinate 294 * @ingroup MGparm 295 * @author Nathan Baker 296 * @param thee MGparm object 297 * @returns z-coordinate 298 */ 299 VEXTERNC double MGparm_getCenterZ(MGparm *thee); 300 301 /** @brief Construct MGparm object 302 * @ingroup MGparm 303 * @author Nathan Baker 304 * @param type Type of MG calculation 305 * @returns Newly allocated and initialized MGparm object 306 */ 307 VEXTERNC MGparm* MGparm_ctor(MGparm_CalcType type); 308 309 /** @brief FORTRAN stub to construct MGparm object 310 * @ingroup MGparm 311 * @author Nathan Baker and Todd Dolinsky 312 * @param thee Space for MGparm object 313 * @param type Type of MG calculation 314 * @returns Success enumeration 315 */ 316 VEXTERNC Vrc_Codes MGparm_ctor2(MGparm *thee, MGparm_CalcType type); 317 318 /** @brief Object destructor 319 * @ingroup MGparm 320 * @author Nathan Baker 321 * @param thee Pointer to memory location of MGparm object 322 */ 323 VEXTERNC void MGparm_dtor(MGparm **thee); 324 325 /** @brief FORTRAN stub for object destructor 326 * @ingroup MGparm 327 * @author Nathan Baker 328 * @param thee Pointer to MGparm object 329 */ 330 VEXTERNC void MGparm_dtor2(MGparm *thee); 331 332 /** @brief Consistency check for parameter values stored in object 333 * @ingroup MGparm 334 * @author Nathan Baker 335 * @param thee MGparm object 336 * @returns Success enumeration 337 */ 338 VEXTERNC Vrc_Codes MGparm_check(MGparm *thee); 339 340 /** @brief Copy MGparm object into thee 341 * @ingroup MGparm 342 * @author Nathan Baker and Todd Dolinsky 343 * @param thee MGparm object (target for copy) 344 * @param parm MGparm object (source for copy) 345 */ 346 VEXTERNC void MGparm_copy(MGparm *thee, MGparm *parm); 347 348 /** @brief Parse an MG keyword from an input file 349 * @ingroup MGparm 350 * @author Nathan Baker and Todd Dolinsky 351 * @param thee MGparm object 352 * @param tok Token to parse 353 * @param sock Stream for more tokens 354 * @returns Success enumeration (1 if matched and assigned; -1 if matched, but there's some sort 355 * of error (i.e., too few args); 0 if not matched) 356 */ 357 VEXTERNC Vrc_Codes MGparm_parseToken(MGparm *thee, char tok[VMAX_BUFSIZE], 358 Vio *sock); 359 360 #endif 361 362