nb_kerneltype.h

来自「最著名最快的分子模拟软件」· C头文件 代码 · 共 355 行 · 第 1/2 页

/*
 * $Id: nb_kerneltype.h,v 1.1.2.2 2008/02/29 07:02:44 spoel Exp $
 * 
 *                This source code is part of
 * 
 *                 G   R   O   M   A   C   S
 * 
 *          GROningen MAchine for Chemical Simulations
 * 
 *                        VERSION 3.3.3
 * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
 * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
 * Copyright (c) 2001-2008, The GROMACS development team,
 * check out http://www.gromacs.org for more information.

 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 * 
 * If you want to redistribute modifications, please consider that
 * scientific software is very special. Version control is crucial -
 * bugs must be traceable. We will be happy to consider code for
 * inclusion in the official distribution, but derived work must not
 * be called official GROMACS. Details are found in the README & COPYING
 * files - if they are missing, get the official version at www.gromacs.org.
 * 
 * To help us fund GROMACS development, we humbly ask that you cite
 * the papers on the package - you can find them in the top README file.
 * 
 * For more info, check our website at http://www.gromacs.org
 * 
 * And Hey:
 * Groningen Machine for Chemical Simulation
 */
#ifndef _NB_KERNEL_H_
#define _NB_KERNEL_H_

#include <types/simple.h>

/** Function interfaces and nonbonded kernel meta-data.
 * 
 *  \file nb_kernel.h
 *
 *  \internal
 *
 *  This file contains the definitions of the call sequences and 
 *  parameter documetation for the nonbonded kernels, both the 
 *  optimized level1/level2 kernels in Fortran or C, and the more 
 *  general level0 normal and free energy kernels. 
 *  It also defines an information structure used to record
 *  data about nonbonded kernels, their type of call sequence, 
 *  and the number of flops used in the outer and inner loops.
 */

#ifdef __cplusplus
extern "C" {
#endif
#if 0
} /* fixes auto-indentation problems */
#endif




/** Interface to level1 optimized nonbonded kernels.
 * 
 *  \internal
 *
 *  To simplify the jungle of nonbonded function calls in earlier
 *  versions of Gromacs, we have changed most nonbonded kernels
 *  to use the same call sequence, even if some of the parameters
 *  are ununsed in a particular kernel.
 *
 *  This function call sequence is used by all level1 kernels. When this is
 *  written it is actually used by the level2 kernels too, but that might
 *  change in the future - don't assume they are identical.
 *  All arguments are passed as pointers to make to interface identical across 
 *  the Fortran and C implementations. For the same reason (Fortran & assembly) 
 *  we cannot use structures.
 *
 *  The nonbonded kernels should never be called directly - use
 *  the setup and wrapper routines in gmx_nonbonded.h instead.
 *
 *  \param nri        Number of neighborlists/i-particles/outer-particles.
 *                    The outer loop of the nonbonded kernel will iterate
 *                    over these indices. This number must always
 *                    be provided,
 *  \param iinr       Atom number (starting on 0) for each index 0..(nri-1)
 *                    in the outer loop. These are the 'owner'/'parent' 
 *                    particles of each neighborlist. It is quite common
 *                    that a particle occurs several times with different
 *                    shift indices. This is the field 'ilist' in 
 *                    the neighborlist. This array must always be provided.
 *  \param jindex     This array specifies the index  of the first j neighbor
 *                    in the array jjnr[] which belongs to the corresponding
 *                    i atom. The j neighbors for all lists are merged into
 *                    one continous array, so we also get the first index for
 *                    the next list in the next element. The size of this list
 *                    is nri+1, and the last position contains the number of
 *                    entries in the j list. Confused? It is actually pretty
 *                    straightforward; for index <tt>i</tt> the i atom is 
 *                    <tt>iinr[i]</tt>, and the atom indices of the neighbors 
 *                    to interact with are in positions <tt>jindex[i]</tt> 
 *                    through <tt>(jindex[i+1]-1)</tt> in <tt>jjnr[]</tt>.
 *                    This corresponds to ilist_jindex in the neighborlist.
 *                    This array must always be provided.
 *  \param jjnr       Array with the j particle neighbors of list i in positions
 *                    <tt>jindex[i]</tt> through <tt>(jindex[i+1]-1)</tt>. This
 *                    field is called jlist in the neighborlist structure.
 *                    This array must always be provided.
 *  \param shift      Array with shift vector index corresponding to each 
 *                    iinr neighborlist. In most codes, periodic boundary 
 *                    conditions are applied by checking pairwise distances 
 *                    of particles, and correcting differences of more than 
 *                    half a box. This is costly (latencies) and unnecessary 
 *                    since we already decided which periodic copy to use during
 *                    neighborsearching. We solve this by introducing 
 *                    \a shiftvectors and a \a shiftindex. The shiftvectors is 
 *                    normally an array of 3*3*3 vectors, corresponding to 
 *                    displacements +- one box unit in one or more directions.
 *                    The central box (no displacement) is always in the middle,
 *                    index 13 in the case of 3*3*3 shift vectors.
 *                    Imagine a particle interacting with two particles in the
 *                    current box, and three particles in the box to the left. 
 *                    We represent this with two ilist entries, one with shift 
 *                    index=13 (central box) and one with shift index=12. 
 *                    all neighbors in each sublist will have the same shift,  
 *                    so in the nonbonded interaction, we only have to add the 
 *                    shift vector to the outer (i) particle coordinates before
 *                    starting the loop over neighbors. This extracts periodic 
 *                    boundary condition calculations from the inner loops, 
 *                    increasing performance significantly. This array must
 *                    always be provided, but if you do not use any periodic
 *                    boundary conditions you could set all elements to zero
 *                    and provide a shiftvec array of length three, with all
 *                    elements there too being zero.
 *  \param shiftvec   The shift vectors for each index. Since the code needs to
 *                    interface with Fortran or assembly, we have to use 
 *                    pointers to float/double instead of the gmx_rvec_t type.
 *                    The x/y/z shift distances for shift index idx are in
 *                    <tt>shiftvec[3*idx]</tt>, <tt>shiftvec[3*idx+1]</tt>, 
 *                    and <tt>shiftvec[3*idx+2]</tt>. This is fully binary 
 *                    compatible with an array of gmx_rvec_t, so you can simply
 *                    use a typecast when calling. The length of the array is
 *                    three times the number of shift indices. This array
 *                    must be provided, but see the comment for shift.
 *  \param fshift     Forces from 'other periodic boxes' for each shift index.
 *                    The shift concept does not affect the forces on individual
 *                    atoms, but it will have an effect on the virial. To 
 *                    account for this, we add the total force on the i particle 
 *                    in each outer loop to the current shift index in this 
 *                    array, which has exactly the same dimensions as the 
 *                    shiftvec array above. The Gromacs manual describes how 
 *                    this is used to calculate the effect in the virial.
 *                    Dimension is identical to shiftvec.
 *                    For kernels that do not calculate forces this can be NULL.
 *  \param gid        Energy group index for each i neighborlist index; this
 *                    corresponds to ilist_groupindex in the neighborlist and is
 *                    used to decompose energies into groupwise contributions.
 *                    If an i particle belongs to group A, and has interactions 
 *                    both with groups A,B, and C, you will get three different 
 *                    i list entries with energy group indices corresponding to 
 *                    A-A, A-B, and A-C neighbors, in addition to possible
 *                    copies due to different shift indices. The energies will 
 *                    be added to this index (i.e. index=gid[i]) in the vc and 
 *                    vnb arrays. This array must always be provided.
 *                    If you don't want to decompose energies all groups should 
 *                    be set to index 0 (length or the array nri).
 *  \param pos        Coordinates of atoms, starting on 0 as all arrays. To
 *                    interface with fortran and assembly this is a simple list
 *                    of floats, with x/y/z of atom n in positions
 *                    <tt>pos[3*n]</tt>, <tt>pos[3*n+1]</tt>, and
 *                    <tt>pos[3*n+2]</tt>. This is binary compatible with,
 *                    and can be typecast from, an array of gmx_rvec_t.
 *                    This array must always be provided.
 *  \param faction    Forces of atoms. To interface with fortran and assembly 
 *                    this is a simple list of floats, with x/y/z of atom n in