Guidelines for Authors
From NWChem
The current wiki has been created to provide documentation related to NWChem [1]. This includes the user manual, tutorials and common practices, as well as programmer references, as well as other useful information. In order to make this wiki as useful as possible to the NWChem community a certain level of consistency of style is useful. To asist with this and beause of the nature of the subject matter of this specific wiki a number of tools and extensions have been selected to help document relevant aspects. These tools and suggestions for their use will be discussed here as well. Obviously for general information on these tools external references will be used.
Contents |
Tools
This wiki has a number of extensions installed to facilitate the documentation process for which it is intended. The configuration of the wiki installation can found at Special:Version. For the purpose of this wiki there are a number of aspects that are relevant. These include Links, Equations, Citations, and Images.
Links
Links are an essential tool for integrating information from various sources. The wiki therefore supports a wide variety of links that can be used and details on how to used them can be found at Links, URLs. For general use there are a few types of links that are clearly important. These links include
- intra wiki links to other pages
- intra wiki links to sections of pages
- external links
Below a few simple examples can be found. However, before links are discussed a few comments on how the wiki handles anchors are in order so that there is a construct to link to.
Anchors on wiki pages
Anchors are points on the wiki pages that you can link to. Anchors are either automatically generated by the wiki but can also be created manually.
The wiki automatically creates anchors for all pages and all headers on each page. This means that you can link to every page and every section or subsection on every page in any case.
In cases where the automatically generated anchors do not provide for the right points to link to anchors can be created manually. In HTML one would use a construct such as <a name="link here">text</a>. However, the wiki does not allow the use of the <a> tag. Instead, the "id" HTML attribute can be used with a number of tags to the same effect. Examples of this are:
<div id="link here">text</div> <div id="link here"/> <span id="link here">text</span>
Occasionally manually entered anchors are also needed where one would expect automatically generated anchors to work. For example, the automatically generated anchor for the subsection entitled "Dyall's Modified Dirac Hamiltonian approximation" cannot be linked to as the apostrophe character cannot be used in a link. In this case adding an anchor manually for the title allows the subsection to be linked successfully. To see this compare the examples below:
[[Relativistic_All-electron_Approximations#Dyall's Modified Dirac-Hamiltonian approximation]] [[Relativistic_All-electron_Approximations#Dyall-Mod-Dirac-Hamiltonian]]
Relativistic_All-electron_Approximations#Dyall's Modified Dirac-Hamiltonian approximation Relativistic_All-electron_Approximations#Dyall-Mod-Dirac-Hamiltonian
Intra wiki links to other pages
Links to other pages are generated by placing the page title between double square brackets.
[[Getting Started]] [[ECP|Effective Core Potentials]]
becomes
Getting Started Effective Core Potentials
Note that spaces in the specified page name are automatically replaced by underscores to generate the correct link. In addition the "|" character may be used to specify a label for the link.
Intra wiki links to sections of pages
Links to sections of pages are a simple extension of the links to other pages. Similar to ordinary URLs one simply appends a "#" character followed by the section title. For example
[[ECP#Scalar ECPs]] [[ECP#Scalar ECPs|Scalar Effective Core Potentials]]
results in
ECP#Scalar ECPs Scalar Effective Core Potentials
which takes you to the section "Scalar ECPs" on the ECP page. Obviously the construct to provide labels for links comes in handy to make these links look appealing.
External links
External links can be specified simply by placing the corresponding URL in single square brackets. For example
[http://dx.doi.org/10.1103/PhysRev.28.1049] [http://dx.doi.org/10.1103/PhysRev.28.1049 Schrödingers wave mechanics (English)]
becomes
[1] Schrödingers wave mechanics (English)
The URLs may, of course, use any of the usual protocols including ftp: and mailto:. Note that in external links the "|" construct to provide a label does not work. Instead the text that appears after the first space is used as the label.
Equations
As people working in the quantum chemistry domain are usually familiar with LaTeX (and the original documentation was written in LaTeX) it is reasonable to provide a mechanism in which equations can be entered in LaTeX on the wiki pages. When a wiki page is saved the LaTeX equations are extracted and transformed to images which are displayed on pages served to readers.
This capability is offered by the <math> ... </math> construct. With this construct the time dependent Schrödinger equation may be entered as:
<math>
\hat{H}\Psi = i\hbar\frac{\partial}{\partial t}\Psi
</math>
which comes out to look like
Because the expression is extracted, embedded in some default LaTeX shrubbery, and then passed to the LaTeX program for processing it is clear that only fairly standard mathematical commands are going to work. Therefore all equations need to be written in plain LaTeX without relying on special packages or user defined commands.
For further details, including a quick LaTeX math reference, more information can be found at displaying a formula.
Images
"One picture says more than a thousand words" is the cliche statement expressing that graphical representations can provide a very direct way to communicate something. For the purposes of this wiki there are three kinds of graphical representations that are clearly useful. They are: Charts (scaling curves, spectra, function plots, etc.), Diagrams (organization of code modules, flow charts, data dependency graphs, etc.), Pictures (images of computer, molecules, developers & collaborators, etc.). Although the need for supporting diagrams is foreseen this is currently not supported for technical reasons. The support for other kinds of graphical representations is described below.
Charts
To include charts on the wiki pages the extension [pChart4mw] is supported. Although the link provides a reasonable documentation of the extension the salient points are summarized below. The extension works similar to many other tools. The extension detects certain keywords on the wiki page and extracts the associated data block. The data block is fed to a tool (pChart in this case) which renders a chart based on the data provided. The chart is subsequently included as an image on the page the wiki serves. The advantage of using a tool like this is that charts can easily be updated when new data becomes available. If the chart was uploaded as a picture instead the chances are that it can only be updated by redrawing it from scratch.
The extension supports a number of different kinds of charts. They are: line charts, bar charts, pie charts, scatter diagrams, radar charts and bubble charts. As line charts are probably the most important ones for our purposes let's look at an example of a scaling curve.
<plines title="Scaling of NWChem DFT on C240" xtitle="processors" ytitle="time (s)" labels=true xlabels=true
legend=right cubic=true plots=closed>
,Fock_2e,Fock_xc,Diag
32, 2777, 35, 26
64, 1392, 19, 16
128, 691, 11, 12
256, 351, 7, 12
512, 178, 5, 12
1024, 91, 4, 12
2048, 51, 4, 13
4096, 31, 6, 13
</plines>
Obviously there are quite a number of attributes that can be set at the start of the chart data. The pChart4mw Parameters page provides details on which attributes can be set, how and what they mean.
Pictures
There are a variety of situations where the best way to show something is to provide a picture. In order to do this the image file has to be uploaded (see the Upload page) to the wiki server. Next a link on the wiki page to the image file has be included. In order to avoid trampling over previously uploaded image files it is recommended to check the list of previously uploaded files at the ListFiles page.
As an example the (old) NWChem logo image is used. First the picture was included on with wiki page using
[[file:Nwchem_logo_dark.png|NWChem logo]]
to give
Alternatively the construct
[[media:Nwchem_logo_dark.png]]
gives
media:Nwchem_logo_dark.png
The wiki page generated will include a link to the upload page to upload the file. Following the link the upload page is displayed with the destination file name already filled in (so less opportunity to introduce inconsistencies through typos). After that it is simply a matter of selecting the right file and click the upload button and the picture will appear on the wiki page.
Note that the [[media: ... ]] construct introduces a link to the file instead of displaying its contents. This might be a good way to provide sample input files, for example.
Citations
In any scientific endeavor linking your statements to the work of others is essential in building interpersonal understanding of the scientific domain. As this wiki is about NWChem only the references cited tend to be related and each reference may be cited multiple times. So for consistency reasons alone it makes sense to store all the references in a single wiki-wide location. For this purpose RefBase was chosen which is a literature reference data base. The corresponding media wiki extension enables the wiki to query the data base to extract the citation, the citation data is parsed by media wiki's Cite extension to generate the appropriate links on the page and the table of references at the bottom.
The consequence of this is that adding references is a two stage process:
- Add the reference data to the data base
- Cite the reference on the wiki page
Adding references in RefBase
To add references to the RefBase data base you will need a RefBase account (email e.g. huub to request one to be set up). Go to RefBase and login to get access to the data base. At the top of the page, right under the title "Your Literature Database", two new links "add record" and "import" have now appeared.
Clicking "add record" brings up a form. Simply filling out the various fields on the form and clicking "Save Record" at the bottom of the page will add the data to the data base. It is recommended to also complete the DOI field as that eventually adds a link to the paper on the wiki page.
Alternatively, clicking "import" brings up a form that allows reference to be imported from external sources. These sources can be files containing references in the EndNote, BibTeX or other formats (see the import page for a complete list), or they can be web-based sources such as DOI, OpenURL, etc. Unfortunately the web-based sources importation does not seem to work at present. What does work is looking the paper up online and using the publisher's export function to export the reference to a file of a format that RefBase recognizes and import this file into RefBase.
After entering a reference, you can find and inspect the details of it. Particularly relevant in this is the field "Serial" which is the reference number RefBase assigned to it. This is the data base's primary key that you use to cite the reference on a wiki page.
Citing references on wiki pages
The mechanism for citing references from RefBase on a wiki is a two stage one. The first stage is extracting a reference from the RefBase data base. The second stage involves parsing and formatting the reference for presentation on the wiki page.
To extract a reference from RefBase use the construct
<refbase>14</refbase>
to obtain
Pulay, P. (1980). "Convergence acceleration of iterative sequences. the case of scf iteration". Chemical Physics Letters 73: 393-398. doi:10.1016/0009-2614(80)80396-4. ISSN 0009-2614.
This information is the same kind of information that could be provided manually to the Cite extension. For example
DIIS
<ref>Pulay, P. (1980). "Convergence acceleration of iterative sequences.
the case of scf iteration". Chemical Physics Letters 73: 393-398.
doi:10.1016/0009-2614(80)80396-4. ISSN 0009-2614</ref>
gives
DIIS[2]
The combination of RefBase and Cite allows this to be rolled into one as
DIIS<ref><refbase>14</refbase></ref>
to yield
DIIS[3]
The Cite extension obviously still needs somewhere to put the references being cited. It uses the construct
<references/>
for this. Where <references/> is replaced with the list of references. An example of a table generated in this way can be found at the bottom of this page under the heading References.
Jmol extensions
JMol applets can be included in the pages. More information can be found at the MediaWiki Extension Page and the JMol Wiki Page.
Clicking the link above should pop up a Java Applet window!!!
Generating a new copy of the documentation to work on for next development release
The NWChem 6.0 documentation is in the main namespace, and should be left alone. The NWChem 6.1 documentation is in the namespace Release61. To make a duplicate of this documentation for Development or for a next release, the following approach works best:
- Go to Special Pages
- Go to All Pages and select the namespace you want the pages from
- Copy the list
- Go to Export pages
- Past the list, parse to one per line, add "namespace:" in front of each page
- Export the page into an XML document
- Edit the XML document and replace the old namespace with the new one you want to use. Example: replace "Release61:" with "Release 62:" and save.
- Add the new namespace you want to use in the list of defined namespaces with a unique numbering to LocalSettings.php . Also add the new numbers of the namespace of the CollectionArticleNamespaces list in LocalSettings.php
- Go to Import pages
- Read in the file
- Now you have a new set of pages with the new name space. beats copying one page at a time.
Updating release documentation on top
You need to update the page "MediaWiki:Sidebar".
Making a PDF of the NWChem documentation
- In LocalSettings.php, uncomment the Collections.php extensions (don't leave it there, comment out after you're done so it's not exposed to the users).
- In "Book Creator" add all individual pages in the documentation (in order). Add chapter headings like the documentation. Export to PDF, and you're done.
Movies
The effort to add movies to the Wiki pages is under development.
<player>Eric.mpg</player>
Counters
Below is a list of files and the number of times they have been downloaded. The download counts represent the number of downloads since we introduced the download.php mechanism on October 12, 2012. Downloads before that date have not been counted. The actual files users can obtain from the Download page.
| File | Total downloads | Last download |
|---|---|---|
| Release 6.6 r27746 tar gz | 10470 | 15/09/2017 01:43:30 |
| Release 6.6 r27746 tar bz2 | 4528 | 14/09/2017 20:08:36 |
| Release 6.6 r27746 srconly tar bz2 | 1024 | 11/09/2017 05:59:09 |
| Release 6.6 r27746 nonsrc tar bz2 | 590 | 14/09/2017 19:44:03 |
| Release 6.6 patch1 | 1577 | 15/09/2017 01:10:11 |
| Release 6.6 patch3 | 1430 | 15/09/2017 01:10:37 |
| NWChem6.6_Documentation.pdf | 3343 | 14/09/2017 00:37:45 |
| Release 6.6beta5 tar gz | 65 | 27/10/2015 10:33:03 |
| Release 6.6beta5 tar bz2 | 37 | 19/10/2015 23:30:05 |
| Release 6.6beta5 srconly tar bz2 | 2 | 16/10/2015 10:52:38 |
| Release 6.6beta4 tar gz | 44 | 16/10/2015 04:10:40 |
| Release 6.6beta4 tar bz2 | 11 | 27/10/2015 03:40:48 |
| Release 6.6beta4 srconly tar bz2 | 1 | 12/10/2015 21:21:32 |
| Release 6.6beta3 tar gz | 98 | 25/10/2015 19:27:48 |
| Release 6.6beta3 tar bz2 | 35 | 19/10/2015 03:41:36 |
| Release 6.6beta3 srconly tar bz2 | 11 | 09/10/2015 07:40:17 |
| Release 6.6beta2 | 16 | 01/10/2015 16:09:00 |
| Release 6.6beta1 | 9 | 09/10/2015 03:46:42 |
| Release 6.5 | 6774 | 14/09/2017 19:57:47 |
| Development snapshot July 10, 2015 | 1156 | 13/09/2017 22:39:02 |
| Development snapshot May 26, 2015 | 326 | 13/09/2017 22:39:01 |
| Development snapshot May 04, 2015 | 246 | 13/09/2017 22:39:00 |
| Development snapshot March 30, 2015 | 320 | 13/09/2017 22:38:59 |
| Development snapshot February 24, 2015 | 283 | 13/09/2017 22:38:59 |
| Development snapshot January 19, 2015 | 304 | 13/09/2017 22:38:58 |
| Development snapshot December 10, 2014 | 312 | 13/09/2017 22:38:57 |
| Development snapshot October 22, 2014 | 356 | 13/09/2017 22:38:56 |
| Release 6.3 | 620 | 03/09/2017 08:05:58 |
| Release 6.3.revision1 | 3154 | 06/09/2017 13:10:38 |
| Release 6.3.revision2 | 7809 | 14/09/2017 22:23:18 |
| Development snapshot June 17, 2013 | 1673 | 14/09/2017 19:44:35 |
| Development snapshot July 19, 2013 | 582 | 13/09/2017 22:38:36 |
| Development snapshot September 10, 2013 | 448 | 13/09/2017 22:38:37 |
| Development snapshot October 16, 2013 | 417 | 13/09/2017 22:38:38 |
| Development snapshot November 12, 2013 | 502 | 13/09/2017 22:38:39 |
| Development snapshot December 18, 2013 | 476 | 13/09/2017 22:38:40 |
| Development snapshot January 28, 2014 | 723 | 13/09/2017 22:38:41 |
| Development snapshot May 03, 2014 | 700 | 13/09/2017 22:38:42 |
| Development snapshot June 09, 2014 | 492 | 13/09/2017 22:38:54 |
| Development snapshot July 08, 2014 | 439 | 13/09/2017 22:38:55 |
| Development snapshot August 25, 2014 | 594 | 13/09/2017 22:38:56 |
| Release 6.1.1 | 5294 | 11/09/2017 00:10:44 |
| Development snapshot July 25, 2012 | 331 | 24/08/2017 23:23:25 |
| Development snapshot August 27, 2012 | 141 | 25/08/2017 01:03:21 |
| Development snapshot October 02, 2012 | 256 | 25/08/2017 15:09:20 |
| Development snapshot November 06, 2012 | 210 | 27/08/2017 10:08:10 |
| Development snapshot December 01, 2012 | 301 | 30/08/2017 19:35:33 |
| Development snapshot January 07, 2013 | 293 | 28/08/2017 17:19:56 |
| Development snapshot February 06, 2013 | 537 | 24/08/2017 23:23:54 |
| PDF version of NWChem 6.3 documentation pages | 2396 | 09/09/2017 18:25:53 |
| PDF version of documentation pages | 1201 | 11/09/2017 15:44:54 |
| NWChem 6.0 RH binary | 0 | 14/09/2016 10:20:03 |
References
- ↑ Kendall, R.A.; Apra, E.; Bernholdt, D.E.; Bylaska, E.J.; Dupuis, M.; Fann, G.I.; Harrison, R.J.; Ju, J.; Nichols, J.A.; Nieplocha, J.; Straatsma, T.P.; Windus, T.L.; Wong, A.T. (2000). "High performance computational chemistry: an overview of NWChem a distributed parallel application". Computer Physics Communication 128: 260-283. doi:10.1016/S0010-4655(00)00065-5.
- ↑ Pulay, P. (1980). "Convergence acceleration of iterative sequences. the case of scf iteration". Chemical Physics Letters 73: 393-398. doi:10.1016/0009-2614(80)80396-4. ISSN 0009-2614
- ↑ Pulay, P. (1980). "Convergence acceleration of iterative sequences. the case of scf iteration". Chemical Physics Letters 73: 393-398. doi:10.1016/0009-2614(80)80396-4. ISSN 0009-2614.