The WESTPA documentation should help the user to understand how WESTPA works and how to use it. To aid in effective communication, a number of guidelines appear below.
When writing in the WESTPA documentation, please be:
Articles in this documentation should follow the guidelines on this page. However, there may be cases when following these guidelines will make an article confusing: when in doubt, use your best judgment and ask for the opinions of those around you.
Style and Usage
Acronyms and abbreviations
Software documentation often involves extensive use of acronyms and abbreviations.
Acronym: A word formed from the initial letter or letters of each or most of the parts of a compound term
Abbreviation: A shortened form of a written word or name that is used in place of the full word or name
Define non-standard acronyms and abbreviations on their first use by using the full-length term, followed by the acronym or abbreviation in parentheses.
A potential of mean force (PMF) diagram may aid the user in visuallizing the energy landscape of the simulation.
Only use acronyms and abbreviations when they make an idea more clear than spelling out the full term. Consider clarity from the point of view of a new user who is intelligent but may have little experience with computers.
Correct: The WESTPA wiki supports HyperText Markup Language (HTML). For example, the user may use HTML tags to give text special formatting. However, be sure to test that the HTML tag gives the desired effect by previewing edits before saving.
Avoid: The WESTPA wiki supports HyperText Markup Language. For example, the user may use HyperText Markup Language tags to give text special formatting. However, be sure to test that the HyperText Markup Language tag gives the desired effect by previewing edits before saving.
Avoid: For each iter, make sure to return the pcoord and any auxdata.
Use all capital letters for abbreviating file types. File extensions should be lowercase.
HDF5, PNG, MP4, GRO, XTC
west.h5, bound.png, unfolding.mp4, protein.gro, segment.xtc
Provide pronunciations for acronyms that may be difficult to sound out.
Do not use periods in acronyms and abbreviations except where it is customary:
Correct: HTML, U.S.
Avoid: H.T.M.L., US
Capitalize at the beginning of each sentence.
Do not capitalize after a semicolon.
Do not capitalize after a colon, unless multiple sentences follow the colon.
In this case, capitalize each sentence.
Preserve the capitalization of computer language elements (commands,
utilities, variables, modules, classes, and arguments).
Capitilize generic Python variables according to the
PEP 0008 Python Style Guide. For example, generic class names should follow the CapWords convention, such as
Do not use contractions. Contractions are a shortened version of word characterized by the omission of internal letters.
Avoid: can’t, don’t, shouldn’t
Possessive nouns are not contractions. Use possessive nouns freely.
Use short sentences (less than 25 words). Although we do not maintain WESTPA documentation in languages other than English, some users may use automatic translation programs. These programs function best with short sentences.
Do not use technical terms where a common term would be equally or more clear.
Use multiple simple sentences in place of a single complicated sentence.
Use italics (surround the word with * * on each side) to highlight words that are not part of a sentence’s normal grammer.
Correct: The word istates refers to the initial states that WESTPA uses to begin trajectories.
Avoid Latin words and abbreviations.
Avoid: etc., et cetera, e.g., i.e.
Specially formatted characters
Never begin a sentence with a specially formatted character. This includes abbreviations, variable names, and anything else this guide instructs to use with special tags. Sentences may begin with WESTPA.
Correct: The program
lsallows the user to see the contents of a directory.
lsallows the user to see the contents of a directory.
Use the word and rather than an
When a special character has a unique meaning to a program, first use the character surrounded by `` tags and then spell it out.
Correct: Append an
&ersand to a command to let it run in the background.
Avoid: Append an “&” to a command… Append an
&to a command… Append an ampersand to a command…
There are many names for the
#hash mark, including hash tag, number sign, pound sign, and octothorpe. Refer to this symbol as a “hash mark”.
Refer to the end WESTPA user as the user in software documentation.
Correct: The user should use the
processeswork manager to run segments in parallel on a single node.
Refer to the end WESTPA user as you in tutorials (you is the implied subject of commands). It is also acceptable to use personal pronouns such as we and our. Be consistent within the tutorial.
Correct: You should have two files in this directory, named
Use should to specify proper usage.
Correct: The user should run
w_truncate -n <var>iter</var>to remove iterations after and including iter from the HDF5 file specified in the WESTPA configuration file.
Use will to specify expected results and output.
Correct: WESTPA will create a HDF5 file when the user runs
Use active voice. Passive voice can obscure a sentence and add unnecessary words.
Correct: WESTPA will return an error if the sum of the weights of segments does not equal one.
Avoid: An error will be returned if the sum of the weights of segments does not equal one.
Refer to weighted ensemble in all lowercase, unless at the beginning of a sentence. Do not hyphenate.
Correct: WESTPA is an implementation of the weighted ensemble algorithm.
Avoid: WESTPA is an implementation of the weighted-ensemble algorithm.
Avoid: WESTPA is an implementation of the Weighted Ensemble algorithm.
Refer to WESTPA in all capitals. Do not use bold, italics, or other special formatting except when another guideline from this style guide applies.
Correct: Install the WESTPA software package.
The word WESTPA may refer to the software package or a entity of running software.
Correct: WESTPA includes a number of analysis utilities.
Correct: WESTPA will return an error if the user does not supply a configuration file.
Computer Language Elements
Classes, modules, and libraries
Display class names in fixed-width font using the
numpylibrary provides access to various low-level mathematical and scientific calculation routines.
Generic class names should be relevant to the properties of the class; do not use foo or bar
Methods and commands
Refer to a method by its name without parentheses, and without prepending the name of its class. Display methods in fixed-width font using the
arangemethod of the
arange()method of the
When referring to the arguments that a method expects, mention the method without arguments first, and then use the method’s name followed by parenthesis and arguments.
Correct: WESTPA calls the
assignmethod as assign(coords, mask=None, output=None)
Never use a method or command as a verb.
cdto change the current working directory.
cdinto the main simulation directory.
Some programming languages are both a language and a command. When referring to the language, capitalize the word and use standard font. When referring to the command, preserve capitalization as it would appear in a terminal and use the
Using WESTPA requires some knowledge of Python.
pythonto launch an interactive session.
The Bash shell provides some handy capabilities, such as wildcard matching.
.. code-block::directive for short scripts. Options are available for some languages, such as
.. code-block:: bashand
.. code-block:: python.
# This is a generic Bash script.
# This is a generic Python script.
pythonstr = "Hello, world!"
if __name__ == "__main__":
Begin a code snippet with a
#!shebang (yes, this is the real term), followed by the usual path to a program. The line after the shebang should be an ellipsis, followed by lines of code. Use
#!/bin/bashfor Bash scripts,
#!/bin/shfor generic shell scripts, and
#!/usr/bin/env pythonfor Python scripts. For Python code snippets that are not a stand-alone script, place any import commands between the shebang line and ellipsis.
return 1 + numpy.mean(generic_vals)
Follow the PEP 0008 Python Style Guide for Python scripts.
Indents are four spaces.
For comments, use the
#hash mark followed by a single space, and then the comment’s text.
Break lines after 80 characters.
For Bash scripts, consider following Google’s Shell Style Guide
Indents are two spaces.
Use blank lines to improve readability
; thenon the same line as
Break lines after 80 characters.
For other languages, consider following a logical style guide. At minimum, be consistent.
Use the fixed-width
``tag when referring to a variable.
When explicitly referring to an attribute as well as its class, refer to an attribute as: the
GenericClass, rather than
$dollar sign before Bash variables.
WESTPA makes the variable
$WEST_BSTATE_DATA_REFavailable to new trajectories.