gmxapi Python module reference

The Gromacs Python package includes a high-level scripting interface implemented in pure Python and a lower-level API implemented as a C++ extension module. The pure Python implementation provides the basic gmxapi module and classes with a very stable syntax that can be maintained with maximal compatibility while mapping to lower level interfaces that may take a while to sort out. The separation also serves as a reminder that different execution contexts may be implemented quite diffently, though Python scripts using only the high-level interface should execute on all.

Package documentation is extracted from the gmxapi Python module and is also available directly, using either pydoc from the command line or help() from within Python, such as during an interactive session.

Refer to the Python source code itself for additional clarification.

See also

Accessing gmxapi documentation

gmxapi basic package

import gmxapi as gmx

gmxapi Python package for GROMACS.

This package provides Python access to GROMACS molecular simulation tools. Operations can be connected flexibly to allow high performance simulation and analysis with complex control and data flows. Users can define new operations in C++ or Python with the same tool kit used to implement this package.

class gmxapi.NDArray(data=None)[source]

N-Dimensional array type.

gmxapi.commandline_operation(executable=None, arguments=(), input_files: dict = None, output_files: dict = None, **kwargs)[source]

Helper function to define a new operation that executes a subprocess in gmxapi data flow.

Define a new Operation for a particular executable and input/output parameter set. Generate a chain of operations to process the named key word arguments and handle input/output data dependencies.

Parameters

  • 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_files kwarg * erroroutput: A string of error output (if any) if the process failed. * returncode: return code of the subprocess.

gmxapi.concatenate_lists(sublists: list = ()) → gmxapi.typing.Future[gmxapi.datamodel.NDArray][source]

Combine data sources into a single list.

A trivial data flow restructuring operation.

gmxapi.function_wrapper(output: dict = None)[source]

Generate a decorator for wrapped functions with signature manipulation.

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.

Example

>>> @function_wrapper(output={'spam': str, 'foo': str})
... def myfunc(parameter: str = None, output=None):
...    output.spam = parameter
...    output.foo = parameter + ' ' + parameter
...
>>> operation1 = myfunc(parameter='spam spam')
>>> assert operation1.output.spam.result() == 'spam spam'
>>> assert operation1.output.foo.result() == 'spam spam spam spam'
Parameters

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 will just capture the return value of the wrapped function.

Todo

gmxapi typing stub file(s). The way this wrapper uses parameter annotations is not completely compatible with static type checking (PEP 484). If we decide to keep the convenience functionality by which operation details are inferred from parameter annotations, we should provide a separate stub file (.pyi) to support static type checking of the API.

gmxapi.join_arrays(*, front: gmxapi.datamodel.NDArray = (), back: gmxapi.datamodel.NDArray = ()) → gmxapi.datamodel.NDArray[source]

Operation that consumes two sequences and produces a concatenated single sequence.

Note that the exact signature of the operation is not determined until this helper is called. Helper functions may dispatch to factories for different operations based on the inputs. In this case, the dtype and shape of the inputs determines dtype and shape of the output. An operation instance must have strongly typed output, but the input must be strongly typed on an object definition so that a Context can make runtime decisions about dispatching work and data before instantiating. # TODO: elaborate and clarify. # TODO: check type and shape. # TODO: figure out a better annotation.

gmxapi.logical_not(value: bool) → gmxapi.typing.Future[source]

Boolean negation.

If the argument is a gmxapi compatible Data or Future object, a new View or Future is created that proxies the boolean opposite of the input.

If the argument is a callable, logical_not returns a wrapper function that returns a Future for the logical opposite of the callable’s result.

gmxapi.make_constant(value: Scalar) → gmxapi.typing.Future[source]

Provide a predetermined value at run time.

This is a trivial operation that provides a (typed) value, primarily for internally use to manage gmxapi data flow.

Accepts a value of any type. The object returned has a definite type and provides same interface as other gmxapi outputs. Additional constraints or guarantees on data type may appear in future versions.

gmxapi.mdrun(input, label: str = None, context=None)[source]

MD simulation operation.

Parameters

input – valid simulation input

Returns

runnable operation to perform the specified simulation

The output attribute of the returned operation handle contains dynamically determined outputs from the operation.

input may be a TPR file name or a an object providing the SimulationInput interface.

Note

New function names will be appearing to handle tasks that are separate

“simulate” is plausibly a dispatcher or base class for various tasks dispatched by mdrun. Specific work factories are likely “minimize,” “test_particle_insertion,” “legacy_simulation” (do_md), or “simulation” composition (which may be leap-frog, vv, and other algorithms)

gmxapi.modify_input(input, parameters: dict, label: str = None, context=None)[source]

Modify simulation input with data flow operations.

Given simulation input input, override components of simulation input with additional arguments, such as parameters.

gmxapi.ndarray(data=None, shape=None, dtype=None)[source]

Create an NDArray object from the provided iterable.

Parameters

data – object supporting sequence, buffer, or Array Interface protocol

New in version 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 and shape is provided, data must be compatible with or convertible to shape. See Broadcast Rules in Data model 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.

The returned object implements the gmxapi N-dimensional Array Interface.

gmxapi.read_tpr(filename, label: str = None, context=None)[source]
Parameters

  • filename – input file name

  • label – optional human-readable label with which to tag the new node

  • context – Context in which to return a handle to the new node. Use default (None) for Python scripting interface

Returns

Reference (handle) to the new operation instance (node).

gmxapi.subgraph(variables=None)[source]

Allow operations to be configured in a sub-context.

The object returned functions as a Python context manager. When entering the context manager (the beginning of the with block), the object has an attribute for each of the named variables. Reading from these variables gets a proxy for the initial value or its update from a previous loop iteration. At the end of the with block, any values or data flows assigned to these attributes become the output for an iteration.

After leaving the with block, the variables are no longer assignable, but can be called as bound methods to get the current value of a variable.

When the object is run, operations bound to the variables are reset and run to update the variables.

gmxapi.while_loop(*, operation, condition, max_iteration=10)[source]

Generate and run a chain of operations such that condition evaluates True.

Returns and operation instance that acts like a single node in the current work graph, but which is a proxy to the operation at the end of a dynamically generated chain of operations. At run time, condition is evaluated for the last element in the current chain. If condition evaluates False, the chain is extended and the next element is executed. When condition evaluates True, the object returned by while_loop becomes a proxy for the last element in the chain.

Equivalent to calling operation.while(condition), where available.

Parameters

  • operation – a callable that produces an instance of an operation when called with no arguments.

  • condition – a callable that accepts an object (returned by operation) that returns a boolean.

  • max_iteration – execute the loop no more than this many times (default 10)

Warning

max_iteration is provided in part to minimize the cost of bugs in early versions of this software. The default value may be changed or removed on short notice.

Warning

The protocol by which while_loop interacts with operation and condition is very unstable right now. Please refer to this documentation when installing new versions of the package.

Protocol:
Warning:

This protocol will be changed before the 0.1 API is finalized.

When called, while_loop calls operation without arguments and captures the return value captured as _operation. The object produced by operation() must have a reset, a run method, and an output attribute.

This is inspected to determine the output data proxy for the operation produced by the call to while_loop. When that operation is called, it does the equivalent of

while(condition(self._operation)):

self._operation.reset() self._operation.run()

Then, the output data proxy of self is updated with the results from self._operation.output.

Status messages and Logging

Python logging facilities use the built-in logging module.

Upon import, the gmxapi package configures the root Python logger with a placeholder “NullHandler” to reduce default output. If logging has already been imported when gmxapi is imported, this has no effect. However, we set the root 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')). Refer to the Python logging module for information on connecting to and handling logger output.

Exceptions module

Exceptions and Warnings raised by gmxapi module operations.

Errors, warnings, and other exceptions used in the GROMACS Python package are defined in the exceptions submodule.

The gmxapi Python package defines a root exception, exceptions.Error, from which all Exceptions thrown from within the module should derive. If a published component of the gmxapi package throws an exception that cannot be caught as a gmxapi.exceptions.Error, please report the bug.

exception gmxapi.exceptions.ApiError[source]

An API operation was attempted with an incompatible object.

exception gmxapi.exceptions.DataShapeError[source]

An object has an incompatible shape.

This exception does not imply that the Type or any other aspect of the data has been checked.

exception gmxapi.exceptions.Error[source]

Base exception for gmx.exceptions classes.

exception gmxapi.exceptions.FeatureNotAvailableError[source]

Requested feature not available in the current environment.

This exception will usually indicate an issue with the user’s environment or run time details. There may be a missing optional dependency, which should be specified in the exception message.

exception gmxapi.exceptions.NotImplementedError[source]

Specified feature is not implemented in the current code.

This exception indicates that the implemented code does not support the API as specified. The calling code has used valid syntax, as documented for the API, but has reached incompletely implemented code, which should be considered a bug.

exception gmxapi.exceptions.ProtocolError[source]

Unexpected API behavior or protocol violation.

This exception generally indicates a gmxapi bug, since it should only occur through incorrect assumptions or misuse of API implementation internals.

exception gmxapi.exceptions.TypeError[source]

Incompatible type for gmxapi data.

Reference datamodel.rst for more on gmxapi data typing.

exception gmxapi.exceptions.UsageError[source]

Unsupported syntax or call signatures.

Generic usage error for gmxapi module.

exception gmxapi.exceptions.ValueError[source]

A user-provided value cannot be interpreted or doesn’t make sense.

exception gmxapi.exceptions.Warning[source]

Base warning class for gmx.exceptions.

gmx.version module

Provide version and release information.

gmxapi.version.major

gmxapi major version number.

Type

int

gmxapi.version.minor

gmxapi minor version number.

Type

int

gmxapi.version.patch

gmxapi patch level number.

Type

int

gmxapi.version.release

True if imported gmx module is an officially tagged release, else False.

Type

bool

gmxapi.version.api_is_at_least(major_version, minor_version=0, patch_version=0)[source]

Allow client to check whether installed module supports the requested API level.

Parameters

  • major_version (int) – gmxapi major version number.

  • minor_version (int) – optional gmxapi minor version number (default: 0).

  • patch_version (int) – optional gmxapi patch level number (default: 0).

Returns

True if installed gmx package is greater than or equal to the input level

Note that if gmxapi.version.release is False, the package is not guaranteed to correctly or fully support the reported API level.

gmxapi.version.has_feature(name='', enable_exception=False) → bool[source]

Query whether a named feature is available in the installed package.

Between updates to the API specification, new features or experimental aspects may be introduced into the package and need to be detectable. This function is intended to facilitate code testing and resolving differences between 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 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 the specification and bug-fixes referring to previous major versions should not be checked with has_feature(). Using has_feature() with old feature 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 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 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.

Core API

gmxapi core module

gmxapi._gmxapi provides Python access to the GROMACS C++ API so that client code can be implemented in Python, C++, or a mixture. The classes provided are mirrored on the C++ side in the gmxapi namespace as best as possible.

This documentation is generated from C++ extension code. Refer to C++ source code and developer documentation for more details.

Exceptions

exception gmxapi._gmxapi.Exception

Root exception for the C++ extension module. Derives from gmxapi.exceptions.Error.

exception gmxapi._gmxapi.NotImplementedError

Expected feature is not implemented.

exception gmxapi._gmxapi.ProtocolError

Behavioral protocol violated.

exception gmxapi._gmxapi.UnknownException

GROMACS library produced an exception that is not mapped in gmxapi or which should have been caught at a lower level. I.e. a bug. (Please report.)

exception gmxapi._gmxapi.UsageError

Unacceptable API usage.

Functions

Tools for launching simulations

gmxapi._gmxapi.from_tpr(arg0: str) → gmxapi._gmxapi.MDSystem

Return a system container initialized from the given input record.

Tools to manipulate TPR input files

gmxapi._gmxapi.copy_tprfile(source: gmxapi._gmxapi.TprFile, destination: str) → bool

Copy a TPR file from source to destination.

gmxapi._gmxapi.read_tprfile(filename: str) → gmxapi._gmxapi.TprFile

Get a handle to a TPR file resource for a given file name.

gmxapi._gmxapi.write_tprfile(filename: str, parameters: gmxapi._gmxapi.SimulationParameters) → None

Write a new TPR file with the provided data.

gmxapi._gmxapi.rewrite_tprfile(source: str, destination: str, end_time: float) → bool

Copy a TPR file from source to destination, replacing nsteps with end_time.

Classes

class gmxapi._gmxapi.Context(self: gmxapi._gmxapi.Context) → None

Create a default execution context.

add_mdmodule(self: gmxapi._gmxapi.Context, arg0: object) → None

Add an MD plugin for the simulation.

setMDArgs(self: gmxapi._gmxapi.Context, arg0: gmxapi._gmxapi.MDArgs) → None

Set MD runtime parameters.

class gmxapi._gmxapi.MDArgs(self: gmxapi._gmxapi.MDArgs) → None

Create an empty MDArgs object.

set(self: gmxapi._gmxapi.MDArgs, arg0: dict) → None

Assign parameters in MDArgs from Python dict.

class gmxapi._gmxapi.MDSession
close(self: gmxapi._gmxapi.MDSession) → gmxapi._gmxapi.Status

Shut down the execution environment and close the session.

run(self: gmxapi._gmxapi.MDSession) → gmxapi._gmxapi.Status

Run the simulation workflow

class gmxapi._gmxapi.MDSystem
launch(self: gmxapi._gmxapi.MDSystem, arg0: gmxapi._gmxapi.Context) → gmxapi._gmxapi.MDSession

Launch the configured workflow in the provided context.

class gmxapi._gmxapi.SimulationParameters
extract(self: gmxapi._gmxapi.SimulationParameters) → dict

Get a dictionary of the parameters.

set(*args, **kwargs)

Overloaded function.

  1. set(self: gmxapi._gmxapi.SimulationParameters, key: str, value: int) -> None

Use a dictionary to update simulation parameters.

  1. set(self: gmxapi._gmxapi.SimulationParameters, key: str, value: float) -> None

Use a dictionary to update simulation parameters.

  1. set(self: gmxapi._gmxapi.SimulationParameters, key: str, value: none) -> None

Use a dictionary to update simulation parameters.

class gmxapi._gmxapi.TprFile
params(self: gmxapi._gmxapi.TprFile) → gmxapi._gmxapi.SimulationParameters