for constructing command line argument arrays, and
test fixtures for tests that need to test long strings for correctness
and for tests that execute legacy code where
- `stdin` reading etc. cannot be easily mocked.
+ ``stdin`` reading etc. cannot be easily mocked.
__ doxygen-module-testutils_
where :math:`\nu` is the oscillator frequency, :math:`m` the (reduced)
mass, and :math:`k` Boltzmann’s constant. For a weak oscillator with a
wave number of 100 cm\ :math:`^{-1}` and a mass of 10 atomic units, at a
-temperature of 1 K, :math:`f=7.7` kJ mol\ :math:`^{-1}` nm:math:`^{-1}`.
+temperature of 1 K, :math:`f=7.7` kJ mol\ :math:`^{-1}` nm\ :math:`^{-1}`.
A value for :math:`\epsilon` between 1 and 10 is acceptable.
Conjugate Gradient
:numref:`Fig. %s <fig-grid>` shows, some grid cells may be searched
more than once for different images of :math:`i`. This is not a problem,
since, due to the minimum image convention, at most one image will “see”
-the :math:`j`-particle. For every particle, fewer than 125 (5:math:`^3`)
+the :math:`j`-particle. For every particle, fewer than 125 (5\ :math:`^3`)
neighboring cells are searched. Therefore, the algorithm scales linearly
with the number of particles. Although the prefactor is large, the
scaling behavior makes the algorithm far superior over the standard
position of atom :math:`i` at time :math:`t`. **Note** that fitting
does not have to use the same atoms as the calculation of the
:math:`RMSD`; *e.g.* a protein is usually fitted on the backbone atoms
- (N,C:math:`_{\alpha}`,C), but the :math:`RMSD` can be computed of the
+ (N, C\ :math:`_{\alpha}`, C), but the :math:`RMSD` can be computed of the
backbone or of the whole protein.
Instead of comparing the structures to the initial structure at time
:label: eqnvar0
of a quantity :math:`x` are to be computed. The variance
-:math:`\sigma_x` of a series of N\ :math:`_x` values, {x:math:`_i`}, can
+:math:`\sigma_x` of a series of N\ :math:`_x` values, {:math:`x_i`}, can
be computed from
.. math:: \sigma_x~=~ \sum_{i=1}^{N_x} x_i^2 ~-~ \frac{1}{N_x}\left(\sum_{i=1}^{N_x}x_i\right)^2
:math:`x_i` values twice, once to determine :math:`\left<x\right>` and
again to compute :math:`\sigma_x`, whereas
:eq:`eqn. %s <eqnvar0>` requires only one sequential scan of
-the series {x:math:`_i`}. However, one may cast
+the series {:math:`x_i`}. However, one may cast
:eq:`eqn. %s <eqnvar1>` in another form, containing partial
sums, which allows for a sequential update algorithm. Define the partial
sum
normal Lennard-Jones parameters. In other force fields, such as
OPLS \ :ref:`103 <refJorgensen88>`, the standard Lennard-Jones
parameters are reduced by a factor of two, but in that case also the
-dispersion (r:math:`^{-6}`) and the Coulomb interaction are scaled.
+dispersion (r\ :math:`^{-6}`) and the Coulomb interaction are scaled.
|Gromacs| can use either of these methods.
Charge Groups
Usage
^^^^^
-Density-guided simulations are controlled by setting `.mdp` options and
-providing a reference density map as a file additional to the `.tpr`.
+Density-guided simulations are controlled by setting ``.mdp`` options and
+providing a reference density map as a file additional to the ``.tpr``.
All options that are related to density-guided simulations are prefixed with
-`density-guided-simulation`.
+``density-guided-simulation``.
-Setting `density-guided-simulation-active = yes` will trigger density-guided
+Setting ``density-guided-simulation-active = yes`` will trigger density-guided
simulations with default parameters that will cause atoms to move into the
reference density.
Reference input for the densities are given in mrc format according to the
"EMDB Map Distribution Format Description Version 1.01 (c) emdatabank.org 2014".
-Closely related formats like `ccp4` and `map` might work.
+Closely related formats like ``ccp4`` and ``map`` might work.
Be aware that different visualization software handles map formats differently.
-During simulations, reference densities are interpreted as visualised by `VMD`.
+During simulations, reference densities are interpreted as visualised by ``VMD``.
Output
^^^^^^
the plane of three atoms, with fixed distance; C: in
the plane of three atoms, with fixed angle and distance;
D: construction for amine groups
- (-NH:math:`_2` or -NH:math:`_3^+`),
+ (-NH\ :math:`_2` or -NH\ :math:`_3^+`),
see text for details.
The goal of defining hydrogen atoms as virtual sites is to remove all
:label: eqnshearrate
For a simulation with: :math:`\eta=10^{-3}`
-[kgm:math:`^{-1}`\ s\ :math:`^{-1}`],
-:math:`\rho=10^3`\ [kgm:math:`^{-3}`] and :math:`l_z=2\pi`\ [nm],
-:math:`\mbox{sh}_{\max}=1`\ [psnm:math:`^{-1}`] :math:`A`. This shear
+[kgm\ :math:`^{-1}`\ s\ :math:`^{-1}`],
+:math:`\rho=10^3`\ [kgm\ :math:`^{-3}`] and :math:`l_z=2\pi`\ [nm],
+:math:`\mbox{sh}_{\max}=1`\ [psnm\ :math:`^{-1}`] :math:`A`. This shear
rate should be smaller than one over the longest correlation time in the
system. For most liquids, this will be the rotation correlation time,
which is around 10 ps. In this case, :math:`A` should be smaller than
and :math:`C_v` is the heat capacity. Using the values of the example
above, :math:`\tau=10^{-13}` [s] and :math:`C_v=2 \cdot 10^3`\ [J
kg\ :math:`^{-1}`\ K\ :math:`^{-1}`], we get:
-:math:`T_s=25`\ [Kps:math:`^{-2}`]sh\ :math:`_{\max}^2`. When we want
-the shear rate to be smaller than :math:`1/10`\ [ps:math:`^{-1}`],
+:math:`T_s=25`\ [Kps\ :math:`^{-2}`]sh\ :math:`_{\max}^2`. When we want
+the shear rate to be smaller than :math:`1/10`\ [ps\ :math:`^{-1}`],
:math:`T_s` is smaller than 0.25[K], which is negligible.
**Note** that the system has to build up the velocity profile when
``[ virtual_sites? ]`` (for backward compatibility the old
name ``[ dummies? ]`` can also be used) in your topology
file, where the ``?`` stands for the number constructing
-particles for the virtual site. This will be `:ref:`2`` for
-type 2, `:ref:`3`` for types 3, 3fd, 3fad and 3out and
-`:ref:`4`` for type 4fdn. The last of these replace an older
+particles for the virtual site. This will be ``2`` for
+type 2, ``3`` for types 3, 3fd, 3fad and 3out and
+``4`` for type 4fdn. The last of these replace an older
4fd type (with the ‘type’ value 1) that could occasionally be unstable;
while it is still supported internally in the code, the old 4fd type
should not be used in new input files. The different types are explained
* Docs for mdp options relating to bonds improved.
* Fixed various typos.
* Removed a leftover mention of the twin-range scheme.
-* `gmx trjconv -ndec`` docs improved.
+* ``gmx trjconv -ndec`` docs improved.
``GMX_PME_NUM_THREADS``
set the number of OpenMP or PME threads; overrides the default set by
- :ref:`gmx mdrun`; can be used instead of the `-npme` command line option,
+ :ref:`gmx mdrun`; can be used instead of the ``-npme`` command line option,
also useful to set heterogeneous per-process/-node thread count.
``GMX_PME_P3M``
``GMX_PME_THREAD_DIVISION``
PME thread division in the format "x y z" for all three dimensions. The
sum of the threads in each dimension must equal the total number of PME threads (set in
- `GMX_PME_NTHREADS`).
+ :envvar:`GMX_PME_NTHREADS`).
``GMX_PMEONEDD``
if the number of domain decomposition cells is set to 1 for both x and y,
``HWLOC_XMLFILE``
Not strictly a |Gromacs| environment variable, but on large machines
the hwloc detection can take a few seconds if you have lots of MPI processes.
- If you run the hwloc command `lstopo out.xml` and set this environment
+ If you run the hwloc command :command:`lstopo out.xml` and set this environment
variable to point to the location of this file, the hwloc library will use
the cached information instead, which can be faster.
.. mdp-value:: 3dc
The reciprocal sum is still performed in 3D, but a force and
- potential correction applied in the `z` dimension to produce a
+ potential correction applied in the ``z`` dimension to produce a
pseudo-2D summation. If your system has a slab geometry in the
- `x-y` plane you can try to increase the `z`-dimension of the box
+ ``x-y`` plane you can try to increase the ``z``-dimension of the box
(a box height of 3 times the slab height is usually ok) and use
this option.
.. mdp-value:: surface-tension
Surface tension coupling for surfaces parallel to the
- xy-plane. Uses normal pressure coupling for the `z`-direction,
- while the surface tension is coupled to the `x/y` dimensions of
+ xy-plane. Uses normal pressure coupling for the ``z``-direction,
+ while the surface tension is coupled to the ``x/y`` dimensions of
the box. The first :mdp:`ref-p` value is the reference surface
tension times the number of surfaces ``bar nm``, the second
- value is the reference `z`-pressure ``bar``. The two
+ value is the reference ``z``-pressure ``bar``. The two
:mdp:`compressibility` values are the compressibility in the
- `x/y` and `z` direction respectively. The value for the
- `z`-compressibility should be reasonably accurate since it
+ ``x/y`` and ``z`` direction respectively. The value for the
+ ``z``-compressibility should be reasonably accurate since it
influences the convergence of the surface-tension, it can also
be set to zero to have a box with constant height.
(1000) [kJ mol\ :sup:`-1` nm\ :sup:`-2`]
force constant for distance restraints, which is multiplied by a
- (possibly) different factor for each restraint given in the `fac`
+ (possibly) different factor for each restraint given in the ``fac``
column of the interaction in the topology file.
.. mdp:: disre-tau
.. mdp:: freezedim
dimensions for which groups in :mdp:`freezegrps` should be frozen,
- specify `Y` or `N` for X, Y and Z and for each group (*e.g.* ``Y Y
- N N N N`` means that particles in the first group can move only in
+ specify ``Y`` or ``N`` for X, Y and Z and for each group (*e.g.*
+ ``Y Y N N N N`` means that particles in the first group can move only in
Z direction. The particles in the second group can move in any
direction).
.. mdp:: QMcharge
(0) [integer]
- The total charge in `e` of the :mdp:`QMMM-grps`. In case there are
+ The total charge in ``e`` of the :mdp:`QMMM-grps`. In case there are
more than one :mdp:`QMMM-grps`, the total charge of each ONIOM
layer needs to be specified separately.
executed the respective part of the run, wall-time and cycle
count aggregates (across all threads and ranks) averaged over the entire run.
The last column also shows what precentage of the total runtime each row represents.
-Note that the :ref:`gmx mdrun` timer resetting functionalities (`-resethway` and `-resetstep`)
+Note that the :ref:`gmx mdrun` timer resetting functionalities (``-resethway`` and ``-resetstep``)
reset the performance counters and therefore are useful to avoid startup overhead and
performance instability (e.g. due to load balancing) at the beginning of the run.
Make sure that you have the latest drivers installed. For AMD GPUs,
the compute-oriented `ROCm <https://rocm.github.io/>`_ stack is recommended;
alternatively, the AMDGPU-PRO stack is also compatible; using the outdated
-and unsupported `fglrx` proprietary driver and runtime is not recommended (but
+and unsupported ``fglrx`` proprietary driver and runtime is not recommended (but
for certain older hardware that may be the only way to obtain support).
In addition Mesa version 17.0 or newer with LLVM 4.0 or newer is also supported.
For NVIDIA GPUs, using the proprietary driver is
log level to DEBUG, which could increase the output from other modules.
Each module in the gmxapi package uses its own hierarchical logger to allow
-granular control of log handling (e.g. `logging.getLogger('gmxapi.operation')`).
+granular control of log handling (e.g. ``logging.getLogger('gmxapi.operation')``).
Refer to the Python :py:mod:`logging` module for information on connecting to and handling
logger output.
"""
think this disallows important use cases, please let us know.
Arguments:
- command : a tuple (or list) to be the subprocess arguments, including `executable`
- output : mapping of command line flags to output filename arguments
- shell : unused (provides forward-compatibility)
+ command: a tuple (or list) to be the subprocess arguments, including `executable`
+ output: mapping of command line flags to output filename arguments
+ shell: unused (provides forward-compatibility)
Arguments are iteratively added to the command line with standard Python
iteration, so you should use a tuple or list even if you have only one parameter.
user input, and sends the output to cli()
Arguments:
- filemap : key-value map of command line flags and filename arguments
+ filemap: key-value map of command line flags and filename arguments
Returns:
list of strings and/or gmxapi data references
input/output data dependencies.
Arguments:
- executable : name of an executable on the path
- arguments : list of positional arguments to insert at argv[1]
- input_files : mapping of command-line flags to input file names
- output_files : mapping of command-line flags to output file names
+ executable: name of an executable on the path
+ arguments: list of positional arguments to insert at ``argv[1]``
+ input_files: mapping of command-line flags to input file names
+ output_files: mapping of command-line flags to output file names
Output:
The output node of the resulting operation handle contains
- * `file`: the mapping of CLI flags to filename strings resulting from the `output` kwarg
- * `erroroutput`: A string of error output (if any) if the process failed.
- * `returncode`: return code of the subprocess.
+ * ``file``: the mapping of CLI flags to filename strings resulting from the ``output_files`` kwarg
+ * ``erroroutput``: A string of error output (if any) if the process failed.
+ * ``returncode``: return code of the subprocess.
"""
.. versionadded:: 0.1
*shape* and *dtype* parameters
- If `data` is provided, `shape` and `dtype` are optional. If `data` is not
- provided, both `shape` and `dtype` are required.
+ If ``data`` is provided, ``shape`` and ``dtype`` are optional. If ``data`` is not
+ provided, both ``shape`` and ``dtype`` are required.
- If `data` is provided and shape is provided, `data` must be compatible with
- or convertible to `shape`. See Broadcast Rules in `datamodel` documentation.
+ If ``data`` is provided and shape is provided, ``data`` must be compatible with
+ or convertible to ``shape``. See Broadcast Rules in `datamodel` documentation.
- If `data` is provided and `dtype` is not provided, data type is inferred
- as the narrowest scalar type necessary to hold any element in `data`.
- `dtype`, whether inferred or explicit, must be compatible with all elements
- of `data`.
+ If ``data`` is provided and ``dtype`` is not provided, data type is inferred
+ as the narrowest scalar type necessary to hold any element in ``data``.
+ ``dtype``, whether inferred or explicit, must be compatible with all elements
+ of ``data``.
The returned object implements the gmxapi N-dimensional Array Interface.
"""
return gmxapicompat::copy_tprfile(input, outFile);
},
py::arg("source"), py::arg("destination"),
- "Copy a TPR file from `source` to `destination`.");
-
- module.def(
- "rewrite_tprfile",
- [](std::string input, std::string output, double end_time) {
- return gmxapicompat::rewrite_tprfile(input, output, end_time);
- },
- py::arg("source"), py::arg("destination"), py::arg("end_time"),
- "Copy a TPR file from `source` to `destination`, replacing `nsteps` with `end_time`.");
+ "Copy a TPR file from ``source`` to ``destination``.");
+
+ module.def("rewrite_tprfile",
+ [](std::string input, std::string output, double end_time) {
+ return gmxapicompat::rewrite_tprfile(input, output, end_time);
+ },
+ py::arg("source"), py::arg("destination"), py::arg("end_time"),
+ "Copy a TPR file from ``source`` to ``destination``, replacing `nsteps` with "
+ "``end_time``.");
}
} // end namespace gmxpy
New function accepts the same arguments, with additional arguments required by
the API.
- The new function returns an object with an `output` attribute containing the named outputs.
+ The new function returns an object with an ``output`` attribute containing the named outputs.
Example:
>>> assert operation1.output.spam.result() == 'spam spam'
>>> assert operation1.output.foo.result() == 'spam spam spam spam'
- If 'output' is provided to the wrapper, a data structure will be passed to
+ Arguments:
+ output (dict): output names and types
+
+ If ``output`` is provided to the wrapper, a data structure will be passed to
the wrapped functions with the named attributes so that the function can easily
- publish multiple named results. Otherwise, the `output` of the generated operation
+ publish multiple named results. Otherwise, the ``output`` of the generated operation
will just capture the return value of the wrapped function.
.. todo:: gmxapi typing stub file(s).
return False
-def has_feature(name='', enable_exception=False):
+def has_feature(name='', enable_exception=False) -> bool:
"""Query whether a named feature is available in the installed package.
Between updates to the API specification, new features or experimental aspects
development branches. Users should refer to the documentation for the package
modules and API level.
- The primary use case is, in conjunction with api_is_at_least(), to allow
+ The primary use case is, in conjunction with `api_is_at_least()`, to allow
client code to robustly identify expected behavior and API support through
conditional execution and branching. Note that behavior is strongly
specified by the API major version number. Features that have become part of
names will produce a DeprecationWarning for at least one major version, and
client code should be updated to avoid logic errors in future versions.
- For convenience, setting *enable_exception=True* causes the function to
+ For convenience, setting ``enable_exception = True`` causes the function to
instead raise a gmxapi.exceptions.FeatureNotAvailableError for unrecognized feature names.
This allows extension code to cleanly produce a gmxapi exception instead of
first performing a boolean check. Also, some code may be unexecutable for
more than one reason, and sometimes it is cleaner to catch all
- gmxapi.exceptions.Error exceptions for a code block, rather than to
+ `gmxapi.exceptions.Error` exceptions for a code block, rather than to
construct complex conditionals.
Returns:
True if named feature is recognized by the installed package, else False.
Raises:
- gmxapi.exceptions.FeatureNotAvailableError if `enable_exception == True` and feature is not found.
+ gmxapi.exceptions.FeatureNotAvailableError: If ``enable_exception == True`` and feature is not found.
"""
# First, issue a warning if the feature name is subject to removal because