Next: , Previous: Some Useful Commands, Up: Top



6 The Structure of GAMESS CCA Components

6.1 Wrapper Functions

  1. gamess-component/legacy/gamess/wrapper/wrapper.src a) SUBROUTINE GAMESS_START source: gamess main function
    purpose: initialize variables, DDI b) SUBROUTINE GAMESS_END source: gamess main function
    purpose: finalize memory, DDI c) SUBROUTINE GAMESS_READ_INPUT(FILENAME) source: gamess main function
    purpose: read the input file d) SUBROUTINE GAMESS_GET_ENERGY(RETENERGY) source: gamess main function
    purpose: calculating energy (set runtyp = energy) e) SUBROUTINE GAMESS_GET_GRADIENT(RETGRAD) source: gamess main function
    purpose: calculating gradient (set runtyp = grad) f) SUBROUTINE GAMESS_GET_HESSIAN(RETHESS) source: gamess main function
    purpose: calculating hessian (set runtyp = hssian) g) SUBROUTINE GAMESS_GET_NUMCOORD (RETNUM) purpose: return the number of atoms h) SUBROUTINE GAMESS_RUN_INPUT(FILENAME) source: gamess main function purpose: run the gamess input directly
  2. gamess-component-$VERSION/legacy/gamess/wrapper/1eintegral.src a) SUBROUTINE GAMESS_1E_INITIALIZE source: oneei (int1.src)
    purpose: initialize variables b) SUBROUTINE GAMESS_DBLET_INTEGRAL(INI,INJ,RESULT,LL2,TYPE) source: hsandt (int1.src)
    purpose: calculate shell doublet (ini, inj) c) SUBROUTINE GAMESS_1E_FINALIZE purpose: finalize 1e-integral calculation (currently unimplemented)
  3. gamess-component-$VERSION/legacy/gamess/wrapper/2eintegral.src a) SUBROUTINE GAMESS_TWOEI_INITIALIZE source: jandk, twoei (int2a.src)
    purpose: initialize memory and variables b) SUBROUTINE GAMESS_TWOEI_COMPUTE(INI,INJ,INK,INL,RES2E,INTSIZE) purpose: passing memory location of allocated arrays for computing a shell quartet c) SUBROUTINE GAMESS_TWOEI_COMPUTE_DO(BUFP,BUFK,IX,XINTS, * GHONDO,DDIJ,INI,INJ,INK,INL,RES2E,INTSIZE, * IA,DA,FA,DB,FB,DSH,DNLO,FNLO,NFLMAT) source: twoei (int2a.src)
    purpose: computing shell quartet ini, inj, ink, inl of integrals and store the result array in res2e d) SUBROUTINE GAMESS_QOUT(BUFP,IX,NINTMX,GHONDO,RES2E,INTSIZE) source: qout (int2a.src)
    purpose: read the shell quartet of integrals and store the resulting array to res2e e) SUBROUTINE GAMESS_DEBUT(DIRSCF,BUFP,BUFK,IX,NINTMX,NEED,DIRTRF) source: debut (int2a.src)
    purpose: initialize 2e-integral calculation (comment out some output from the original code) f) SUBROUTINE GAMESS_TWOEI_FINALIZE source: jandk, twoei (int2a.src)
    purpose: finalize memory allocation and variables for 2e-integral calculation
  4. gamess-component-$VERSION/legacy/gamess/wrapper/basis.src a) SUBROUTINE GAMESS_NBASIS(NBAS) Return: the number of basis functions for the molecular basis set. b) SUBROUTINE GAMESS_GMAM(LMAX) Return: the maximum angular momentum value for any contraction in the basis set. c) SUBROUTINE GAMESS_GATYP(LTYP) Return: the angular type 0,1,2 = {CARTESIAN, SPHERICAL, MIXED} d) SUBROUTINE GAMESS_ATMNAMES(NUMATOM) Return: get the array of atom names e) SUBROUTINE GAMESS_GTITLE(TITL) Return: the title of the input file f) SUBROUTINE GAMESS_NATOM(NATOMS) Return: the number of atoms
  5. gamess-component-$VERSION/legacy/gamess/wrapper/nshel.src The following subroutines aim to get the value of an array in the common block /NSHEL/. a) SUBROUTINE GAMESS_EX(INDEX,ANSWER) b) SUBROUTINE GAMESS_CS(INDEX,ANSWER) c) SUBROUTINE GAMESS_CP(INDEX,ANSWER) d) SUBROUTINE GAMESS_CD(INDEX,ANSWER) e) SUBROUTINE GAMESS_CF(INDEX,ANSWER) f) SUBROUTINE GAMESS_CG(INDEX,ANSWER) g) SUBROUTINE GAMESS_CH(INDEX,ANSWER) h) SUBROUTINE GAMESS_CI(INDEX,ANSWER) i) SUBROUTINE GAMESS_KSTART(INDEX,IPRIM) j) SUBROUTINE GAMESS_KATOM(INDEX,IATOM) k) SUBROUTINE GAMESS_KTYPE(INDEX,IANGU) l) SUBROUTINE GAMESS_KNG(INDEX,IPRIM) m) SUBROUTINE GAMESS_NSHELLS(NSHELS) n) SUBROUTINE GAMESS_KLOC(INDEX,IANSWER) o) SUBROUTINE GAMESS_KMIN(INDEX,IANSWER)

6.2 Modified Source Files

  1. gamess-component-$VERSION/legacy/ddi/modified_src/ddi_init.c When using ”mpi” or ”MPI2” mode, MPI_Init will be invoked in the function ddi_init. However, when the CCAFFEINE framework starts, MPI_Init will also be invoked by the CCAFFEINE framework. Since the CCAFFEINE framework cannot be modified easily, a flag is added in the function ddi_init to test if MPI has been initialized. If so, MPI_Init will not be called in the function ddi_init. Otherwise, MPI_Init will be called and the command-line arguments will be passed to MPI. This part of code will only be executed when TARGET_MODEL=mpi/MPI2.
              int flag;
              MPI_Initialized(&flag);
              if (!flag) { 
                  if(MPI_Init(&argc,&argv) != MPI_SUCCESS) {
                      fprintf(stdout," DDI: MPI_Init failed.\n");
                      fflush(stdout); exit(911);
                  }
              }
         

  2. gamess-component-$VERSION/legacy/ddi/modified_src/ddi_fortran.c In ”sockets” mode, ddi_init needs the command-line arguments for collecting the information of process id, port number, hostname, etc. When DDI kick off the GAMESS program, the calling path for passing the command-line arguments from ddikick.x to ddi_init is: ddikick.x -> GAMESS -> BEGING(VERSN) -> F77_PBeg(int_f77 *nwdvar) -> F77_Init() -> DDI_Init(int argc, char **arcv). When DDI kick off the CCAFFEINE framework, the calling path for passing the command-line arguments from ddikick.x to ddi_init is: ddikick.x -> CCAFFEINE -> GAMESS CCA Components -> GAMESS -> BEGING(VERSN) -> F77_PBeg(int_f77 *nwdvar) -> F77_Init() -> DDI_Init(int argc, char **arcv) However, the CCAFFEINE framework is not able to directly pass the command-line arguments to GAMESS program. The command-line arguments can be read only through the StovePipe library. Since the StovePipe library requires special format for storing the command-line arguments, DDI kickoff program has to modify the format of the command-line arguments such that the StovePipe library can store the arguments. The GAMESS CCA components needs to collect the arguments from the CCAFFEINE framework and convert the format of the command-line argument back to the format ddi_init function recognize. The collected arguments are stored in the global variables gargc and gargv. Since the function ddi_init is invoked in the function F77_Init, a different set of arguments need to be passed as the arguments in the function ddi_init. The following is the modified source code in F77_Init function:
              # if defined DDI_SOC
              extern int gargc;
              extern int ddi_initialized;
              extern char **gargv;
              extern ddi_finalized;
              # endif
              
              # if defined DDI_SOC
              DDI_Init(gargc, gargv);
              MAX_DEBUG((stdout," DDI: Calling DDI_Init(gargc, gargv).\n"))
              # endif
              
              # if defined DDI_MPI
              DDI_Init(argc,argv);
              MAX_DEBUG((stdout," DDI: Calling DDI_Init(argc, argv).\n"))
              # endif
         

  3. gamess-component-$VERSION/legacy/ddi/modified_src/kickoff_local.c ”kickoff_local.c” is a source file for the ddikick program. In the function kickoff_local, the command-line arguments are read and the information are grouped and stored in . Eventually, in each data server/compute process the program will be started and the information about processes are passed to the program as arguments. When the program that being kicked off by ddikick.x is the CCAFFEINE framework, the format of the arguments need to be modified to the format that the StovePipe library knows. The format is ”- -argument_name1 - -argument_value1 ... - -argument_namen - -argument_valuen”. The value of an argument can be get by using the function: stp_get(argument_namex)
              # if defined DDI_SOC
              # include "ddiarg.h"
              # endif
              
              /* ---------------------------------------- *\
                 Initialize arguments for the DDI process
              \* ---------------------------------------- */
              
              /************************************************************\
               use the original argument list for ddi-mpi model (Fang Peng)  *    \***********************************************************/
              # if defined DDI_MPI
                  nargs = info->ddiarg + info->nnodes + 8;
                  rargs = (char **) Malloc(nargs*sizeof(char*));
                 
                  for(i=1,r=0; i<info->ddiarg-1; i++) rargs[r++] = argv[i];
                 
                  rargs[r++] = ddiinfo;
                  rargs[r++] = info->kickoffhost;    /*   kickoff host name     */
                  rargs[r++] = portid;               /*   kickoff port number   */
                  rargs[r++] = nodeid;               /*   rank of this node     */
                  rargs[r++] = procid;               /*   rank of this process  */
                  rargs[r++] = snodes;               /*   number of nodes       */
                  rargs[r++] = sprocs;               /*   number of processors  */
                
                  for(i=0,iarg=info->nodearg; i<info->nnodes; i++,iarg++) {
                     rargs[r++] = argv[iarg];
                  }   
                        
                  rargs[r] = NULL;
              
              # endif
              
              /*
               * use the modified argument list for ddi-sockets model (Fang Peng)
              */
               # if defined DDI_SOC
                   nargs = info->ddiarg + 2 * info->nnodes + 2*8;
                   rargs = (char **) Malloc(nargs*sizeof(char*));
                   for(i=1,r=0; i<info->ddiarg-1; i++) rargs[r++] = argv[i];
              
                   // change the argument to the format that cca framework can detect
                   rargs[r++] = "--ddihost";
                   rargs[r++] = info->kickoffhost;    /*   kickoff host name     */
              
                    rargs[r++] = "--ddiportid";
                    rargs[r++] = portid;               /*   kickoff port number   */
              
                    rargs[r++] = "--ddinodeid";
                    rargs[r++] = nodeid;               /*   rank of this node     */
              
                    rargs[r++] = "--ddiprocid";
                    rargs[r++] = procid;               /*   rank of this process  */
              
                    rargs[r++] = "--ddisnodes";
                    rargs[r++] = snodes;               /*   number of nodes       */
              
                    rargs[r++] = "--ddisprocs";
                    rargs[r++] = sprocs;               /*   number of processors  */
              
                    rargs[r++] = "--ddinumrest";
                    char numrest[8];
                    sprintf(numrest,"%d",info->nnodes);
                    rargs[r] = numrest;
                    r++;
              
                    for(i=0,iarg=info->nodearg; i<info->nnodes; i++,iarg++) {
                        rargs[r] = (char*)malloc(sizeof(char*));
                        sprintf(rargs[r],"%s%d","--ddirest",i);
                        r++;
              
                        rargs[r++] = argv[iarg];
                    }
              
                    /*
                     * add one more argument to the argument lists
                     * --ddiscr path-to-scratch-directory
                     */
                    rargs[r++] = "--ddiscr";
                    int not_it;
                    for(i=0,not_it=1; i<info->argc-1 && not_it; i++) 
                        not_it = strcmp(argv[i],"-scr");
                    if(not_it==1) {
              	  fprintf(stdout," DDI: Invalid command-line arguments: Missing -scr!\n");
                        Fatal_error(911);
                    }
                    rargs[r++] = argv[i];
                    rargs[r] = NULL; /* set the last argument to NULL */
              
                     /* print out the argument lists that passed to the program */
                     fprintf(stdout, "In kickoff_local.c: nargs = %d \n", nargs);
                     for(i=0; i<nargs; i++) {
                         fprintf(stdout, "rargs[%d] = %s ; ", i, rargs[i]);
                     }
                     fprintf(stdout, "\n\n");
                     r=r-1;
              
                 # endif
              /********************** END *********************/
         

  4. The following files are added some variables and will automatically generate scripts for compiling and testing GAMESS and GAMESS CCA components. gamess/ddi/compddi.in gamess/comp.in gamess/compall.in gamess/lked.in gamess/rungms.in gamess/runall.in gamess/tools/checktst.in

6.3 GAMESS CCA Components

  1. GAMESS.ModelFactory The purpose of this component is to read user input options and return a model object. This component is currently required for all GAMESS CCA computations for initializing the GAMESS program. The returned model object is used to calculate energy, gradient, and hessian.
  2. GAMESS.IntegralEvaluatorFactory The purpose of this component is to create and return integral evaluators. The returned integral evaluators, such as integral evaluator2 and integral evaluator 4, are used for computing 1e- or 2e-integrals.
  3. GAMESS.Manager This component is just for testing. It is used to read user input options and initialize the GAMESS program. Some components, such as IntegralEvaluatorFactory, don't have interfaces for read user input options or getting geometry from molecule object. To add Manager component, those GAMESS CCA components can be used without using ModelFactory component.
  4. GAMESS.SimpleDriver A simple driver for testing energy, gradient, and hessian calculations.
  5. GAMESS.IntegralDriver A simple driver for testing 1e and 2e-integral calculations.
  6. GAMESS.TWOEIDriver A simple driver for testing 1e and 2e-integral calculations with load balancing approaches configured.

6.4 Parameters for GAMESS.ModelFactory

The available input options for the GAMESS.ModelFactory component is as the follows. Parameter Port: CONFIG

use_inputfile
Pass an input file directly to the GAMESS program. This is a bool number, and the default value is false.
inputParam
The full path to the input file for the GAMESS program.
scratchParam
The full path to the scratch directory.
symmetryParam
The symmetry group allowed by the GAMESS program. The default symmetry group is C1.
coordParam
The full path to the file that provides the coordinates for a molecule.
basisSetParam
The basis set for GAMESS to use in computation. The default basis set is STO-3
theoryName
The theory for GAMESS to use in computation. The default theory is RHF
systemGroup
The $SYSTEM input group for GAMESS computations.
guessGroup
The $GUESS input group for GAMESS computations.
contrlGroup
The $CONTRL input group for GAMESS computations.
basisGroup
The $BASIS input group for GAMESS computations.
integrlGroup
The $INTEGRL input group for GAMESS computations.

6.5 Calling Sequences

  1. The calling sequence for starting the CCAFFEINE framework and GAMESS CCA components in the ”sockets” mode:

    1. The ddikick.x program starts the required number of data servers/compute process. (source: gamess-component-$VERSION/legacy/ddi/tools/ddikick/ddikick.c)

    2. Each data server/compute process collects information about host names, port numbers, ranks of nodes, ranks of process, number of nodes and number of processes and stores the information in the format that the StovePipe library (supported by the cca-tools package) recognizes. All of the information is stored in the variable ”rargs”. (source: gamess-component-$VERSION/legacy/ddi/modified_src/kickoff_local.c)

    3. Each data server/compute process starts the CCAFFEINE framework with the parameter ”rargs”. (source: gamess-component-$VERSION/legacy/ddi/modified_src/kickoff_local.c)

    4. The CCAFFEINE framework in each data server/compute process instantiates GAMESS CCA components based on the CCAFFEINE RC file.

    5. The GAMESS.ModelFactory component collects the information in ”rargs” from the StovePipe library and convert to the format that DDI knows. The information will be stored in the global variables ”gargc” and ”gargv”. Finally, GAMESS initialization function gamess_start will be called. (source: gamess-component-$VERSION/legacy/ddi/include/ddiarg.h, gamess-component-$VERSION/legacy/Chemistry/server/GAMESS_*Factory_Impl.cc, gamess-component-$VERSION/legacy/gamess/wrapper/wrapper.src)

    6. The global variables ”gargc” and ”gargv” will eventually be passed to DDI_Init function through the sequence: gamess_start -> BEGING(VERSN) -> F77_PBeg(int_f77 *nwdvar) -> F77_Init() -> DDI_Init(int gargc, char **gargv)

  2. The calling sequence for starting the CCAFFEINE framework and GAMESS CCA components in ”mpi” mode:

    1. MPI kickoff program starts the user required number of processes.

    2. Each process starts a CCAFFEINE framework.

    3. The CCAFFEINE framework in each process instantiates GAMESS CCA components based on the RC file.

    4. The GAMESS.ModelFactory component in each process calls the GAMESS initialization function gamess_start, which calls ddi_init for initializing DDI. The calling sequence is: gamess_start -> BEGING(VERSN) -> F77_PBeg(int_f77 *nwdvar) -> F77_Init() -> DDI_Init(int argc, char **argv)
    5. For older version of DDI, the data server is required for each compute process, so the number of processes in each node is required to be even. If the number of processes in some node is odd, the program will exit with error. For newer version of DDI, there is no data server required in ”mpi” mode.

  3. The calling sequence for calculating energy, gradient, and hessian

    1. Follow the same sequences in 1 for ”sockets” mode or 2 for ”mpi” mode.

    2. The required CCA components are Chemistry.MoleculeFactory GAMESS.ModelFactory and GAMESS.SimpleDriver (or other driver component). The connection is created as follows: Chemistry.MoleculeFactory (provides port: MoleculeFactoryInterface) -> GAMESS.ModelFactory (uses port: MoleculeFactoryInterface) GAMESS.ModelFactory (provides port: ModelFactoryInterface) -> GAMESS.SimpleDriver (uses port: ModelFactoryInterface)

    3. GAMESS.SimpleDriver component get a ModelFactory object through uses port and get a Model object by invoking get_model method.

    4. When get_model method is called, GAMESS.ModelFactory component will do the following steps:
      • get user parameters, such as theory, basis set, symmetry group, etc, through parameter port.
      • get a MoleculeFactory object through uses port and get a Molecule object by passing the molecule file name to the MoleculeFactory object.
      • get molecule coordinates through Molecule object.
      • convert the molecule coordinates to the format of GAMESS input.
      • convert theory, basis sets, symmetry group and other information into the format of GAMESS input.
      • create a GAMESS input file based on the information above.
      • revoke GAMESS wrapper function to initialize input groups from the created GAMESS input file.
      • return model object

    5. Call get_energy, get_gradient, or get_hessian methods of the model object.

    6. The corresponding GAMESS wrapper functions gamess_get_energy, gamess_get_gradient and gamess_get_hessian will be called. The corresponding branches ENERGY, GRAD and HSSIAN in GAMESS program will be chosen (see GAMESS main function).

  4. The calling sequence for calculating 1e-integral

    1. Follow the same sequences in 1 for ”sockets mode or 2 for ”mpi” mode.

    2. The CCA components need to be instantiated are Chemistry.MoleculeFactory, GAMESS.ModelFactory, GAMESS.IntegralEvaluatorFactory and GAMESS.IntegralDriver (or other dirvier component). The connection is created as follows: Chemistry.MoleculeFactory (provides port: MoleculeFactoryInterface) -> GAMESS.ModelFactory (uses port: MoleculeFactoryInterface GAMESS.ModelFactory (provides port: ModelFactoryInterface) -> GAMESS.IntegralDriver (uses port: ModelFactoryInterface) GAMESS.IntegralEvaluatorFactory (provides port: IntegralEvaluatorFactoryInterface) -> GAMESS.IntegralDriver (uses port: IntegralEvaluatorFactoryInterface)

    3. The GAMESS.IntegralDriver component get a ModelFactory object through uses port and get a model object by invoking get_model method.

    4. When get_model method is called, the GAMESS.ModelFactory component will do the following steps:
      • get user parameters, such as theory, basis set, symmetry group, etc, through parameter port.
      • get a MoleculeFactory object through uses port and get a Molecule object by passing the molecule file name to the MoleculeFactory object.
      • get molecule coordinates through Molecule object.
      • convert the molecule coordinates to the format of GAMESS input.
      • convert theory, basis sets, symmetry group and other information into the format of GAMESS input.
      • create a GAMESS input file based on the information above.
      • revoke GAMESS wrapper function to initialize input groups from the created GAMESS input file.
      • return model object

    5. The GAMESS.IntegralDriver component get a GAMESS.IntegralEvaluatorFactory object through uses port and get an GAMESS.IntegralEvaluator2 object by invoking get_evaluator2 method.

    6. invoke initialize method of IntegralEvaluator2 object to initialize 1e-integral. In initialize method, the wrapper function gamess_1e_initializeis invoked;

    7. Use compute method of IntegralEvuator2 object to do some computations.

    8. Call finalize method of IntegralEvaluator2 object to finalize 1e-integral computations.

  5. The calling sequence for calculating 2e-integral.

    1. follow the same steps of 4.a ~ 4.e

    2. The GAMESS.IntegralDriver component get an IntegralEvaluatorFactory object through IntegralEvaluatorFactory uses port.

    3. Create a GaussianMolecular object and a CompositeIntegralDescr object and get an IntegralEvaluator4 object by invoking the get_evaluator4 method of the IntegralEvaluatorFactory component.

    4. Invoke initialize method of IntegralEvaluator4 object to initialize 2e-integral. In initialize method, the wrapper function gamess_twoei_initialize will be invoked;

    5. Use the compute method of IntegralEvaluator4 object to do some computations.

    6. Call finalize method of IntegralEvaluator4 object to finalize 2e-integral. In finalize method, the wrapper function gamess_twoei_finalize will be invoked;