modified on 18 August 2015 at 13:46 ••• 144,626 views

Developer

From NWChem

Revision as of 13:46, 18 August 2015 by Huub (Talk | contribs)
Jump to: navigation, search

Contents

NWChem Development

NWChem is being developed by a consortium of scientists and maintained at the EMSL at PNNL. A current list of developers can be found here. This page provides important information for current and new developers.

Downloading from and Committing to the NWChem source tree

The NWChem source is maintained with subversion, an open-source version control system. To download NWChem you must have subversion installed on your development platform. For an extensive description of the SVN functionality and commands, please check the svn documentation.

Direct access to the source tree is password restricted. To gain access to the NWChem SVN tree see the section on Obtaining Read/Write access to NWChem source tree.

  • Downloading

The development version of NWChem can be downloaded using the command

    % svn checkout https://svn.pnl.gov/svn/nwchem/trunk nwchem
  • Committing changes adding new files

Committing changes to existing source files can be done using the command

    % svn commit -m <information about the changes made>

New files and directories can be added using the commands

    % svn add <files or directories to add>
    % svn commit -m <information about the changes made>

Notes:

  1. Before committing any changes or additions, make sure the NWChem tree compiles properly
  2. When adding new files, make sure to properly update the GNUMakefile in the directory you are working in, so that the new file gets compiled
  3. Do document your changes and additions using the "-m" option of svn
  4. The new SVN 1.7.* versions use different formats of the data in the .svn directories. When using SVN 1.7.* with a working copy checked out with an earlier version of SVN you need to run "svn upgrade" first.

Obtaining Read/Write access to NWChem source tree

Developer access to the NWChem source tree branches in svn is password restricted. New potential developers should contact members of the NWChem Core Developer Team. Before contributions from this new developer can be incorporated into NWChem, this person will have to provide written feedback that the contributions can be released within NWChem under a ECL 2.0 open-source license. A (Trusted) Developer will receive the appropriate access to svn. If a Developer consistently incorporates code changes that negatively affect the development tree, access to svn can be revoked.

The type of developer and their level of access are:

  1. NWChem Core Developer: Developer has full svn access to release and development branches of the NWChem source tree. Owns and is responsible for one or more modules.
  2. Trusted Developer: Developer may be internal or external to PNNL but has full svn access to release and development branches of the NWChem source tree. May own or be responsible for one or more modules.
  3. Developer: Developer may be internal or external to PNNL and has selected svn access to the development branch of the NWChem source tree. Each Developer closely coordinates code contributions with the assigned Point of Contact (POC) from the NWChem Core Developer Team, primarily the Core Developer owning the module in which the contributions will reside. If the development leads to a new module, the NWChem Core Developer Team will assign a POC with responsibility for the new module.
  4. Contributor: Contributor may be internal or external to PNNL and has no access to the development branch of the NWChem source tree. Contributor’s code will be incorporated by the Point of Contact from the NWChem Core Developer Team. This is the main mechanism for external users to contribute developments or enhancements to NWChem.

Compiling NWChem from source

A detailed step-by-step description of the build process and necessary and optional environment variables is outlined on the Compiling NWChem page.

Development Contribution Requirements

All new functionality or capability contributions require:

  1. Proper documentation in the user manual
  2. QA Test Cases that adequately test the added functionality

Proposed new modules and tasks, and their impact on existing modules and functionality need to be documented for review. New modules or tasks will require agreement from the full team before they can be added.

Programming Model and Languages

The programming model in is based on independent "task" modules that perform various functions in the code and are build on modular APIs. Modules and APIs can share data, or share access to files containing data, only through a (most of the time) disk-resident run time database, which is similar to the GAMESS-UK dumpfile or the Gaussian checkpoint file. The run time database contains all the information necessary to restart a task.

The structure and flow of the program and input are such that it allows for performing multiple tasks within one job. Input is read and stored into the run time database until a TASK directive is encountered. When a TASK directive is found in the input, the appropriate module will extract relevant data from the database and any associated files and perform the requested calculation. Upon completion of the task, the module will store significant results in the database, and may also modify other database entries in order to affect the behavior of subsequent computations.

  • Programming rules:
  1. All routines should start with "implicit none" and all variables used in the routine should be specified explicitly.
  2. Minimize or avoid sharing of data through common blocks. Instead use the run time database.
  3. Memory Allocation will be done through the MA and GA memory infrastructure.
  4. Global Arrays Toolkit and MPI for parallel programming.
  • NWChem consists of the programming languages:
  1. FORTRAN77 and FORTRAN90. For FORTRAN90, avoid using allocates and deallocates. Dynamic memory access should be performed using the memory access (MA) layer.
  2. C and C++. Only simple constructs should be used in C++.
  3. OpenMP directives and CUDA/OpenCL.
  4. Python scripts can be uploaded into the contrib directory. Bindings to additional functionality require QA and documentation.

Testing of development version

  1. Code will be build nightly on a Redhat Linux64 Platform using gfortran and gcc.
  2. Code will be tested nightly against QA suite.
  3. Exhaustive coverage analysis of the QA suite will be performed twice a year.

NWChem Mailing List Archive

The archive of the NWChem Mailing list can be found here.

NWChem Wiki Page Guidelines

Follow the link to the NWChem Wiki Page Guidelines.

NWChem Doxygen documentation

The source code in NWChem is documented using Doxygen in a number of places. In order to enable documentation for a given directory only a script has been created in

 nwchem/contrib/doxygen/run_doxygen

This script can be run in any subdirectory of the NWChem source tree. It will automatically adapt the Doxygen configuration file for the directory it is run in and generate documentation for that directory and all its children. The documentation is generated in a subdirectory

 doxydocs

and can be viewed, for example, by running

 % firefox doxydocs/html/index.html

Doxygen has many capabilities and a number of them can be driven through the run_doxygen script. Run

  % run_doxygen -h

for more details.

Module specific details

The NWXC module: higher order derivatives of density functionals

The NWXC module was primarily developed to provide higher order derivatives of density functionals. In addition it provides infrastructure needed to manage all aspects of a DFT energy expression in one place, including the range separation of the exchange integrals and dispersion corrections.

The derivatives of the density functionals can be optained in two different ways:

  • by automatic differentiation
  • by symbolic algebra

The directory structure of the NWXC module

  • nwxc
    • nwad
      • maxima
      • unit_tests
    • maxima
      • bin
      • max
      • f77

nwxc is the top-level directory. It also contains the code for the module API as well as the automatically differentiated code of the density functionals.

nwad contains the automatic differentiation module.

nwad/maxima contains a script to help create the automatic differentiation unit tests.

nwad/unit_tests contains the unit tests.

maxima contains the symbolic algebra tools as well as the code they generate

maxima/bin contains the scripts that driver the Maxima symbolic algebra engine as well as utility scripts that process the Maxima generated Fortran.

maxima/max contains the Maxima specifications of the functionals.

maxima/f77 contains the Maxima generated Fortran code.

Main functions

Main routines of the NWXC module are

  • nwxc_input [nwxc_nwchem.F] parse the functional input line
  • nwxc_print [nwxc_nwchem.F] print the current functional definition
  • nwxc_print_nwpw [nwxc_nwchem.F] print the current functional formatted for the NWPW module
  • nwxc_rtdb_store [nwxc_nwchem.F] store the current functional definition
  • nwxc_rtdb_load [nwxc_nwchem.F] load the currentl functional definition
  • nwxc_is_on [nwxc_query.F] is NWXC activated?
  • nwxc_has_hfx [nwxc_query.F] does the functional have Hartree-Fock exchange?
  • nwxc_has_mp2 [nwxc_query.F] does the functional have a fraction of MP2 correlation?
  • nwxc_has_cam [nwxc_query.F] does the functional use Coulomb operator attenuation?
  • nwxc_has_disp [nwxc_query.F] does the functional have dispersion correction terms?
  • nwxc_get_cam [nwxc_query.F] get the Coulomb attenuation parameters
  • nwxc_get_disp [nwxc_query.F] get the dispersion correction parameters
  • nwxc_wght_hfx [nwxc_query.F] get the Hartree-Fock exchange fraction
  • nwxc_wght_mp2 [nwxc_query.F] get the MP2 correlation fraction
  • nwxc_is_lda [nwxc_query.F] is the functional an LDA functional?
  • nwxc_is_gga [nwxc_query.F] is the functional a GGA functional?
  • nwxc_is_mgga [nwxc_query.F] is the functional a meta-GGA functional?