gmxapi Python module reference#

Version 0.5.0a1.

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

Interface concepts#

gmxapi commands return references to operations. Generally, the operations are collected into a graph of data flow dependencies, and only executed when the results are requested.

class gmxapi.abc.OperationReference#

Client interface to an element of computational work already configured.

An “instance” of an operation is assumed to be a node in a computational work graph, owned and managed by a Context. This class describes the interface of the reference held by a client once the node exists.

The convergence of OperationReferences with Nodes as the results of the action of a Director implies that a Python user should also be able to “subscribe” to an operation handle (or its member resources). This could be a handy feature with which a user could register a call-back. Note that we will want to provide an optional way for the call-back (as with any subscriber) to assert a chain of prioritized Contexts to find the optimal path of subscription.

abstract property output: OutputDataProxy#

Get a proxy collection to the output of the operation.

Developer note: The ‘output’ property exists to isolate the namespace of output data from other operation handle attributes and we should consider whether it is actually necessary or helpful. To facilitate its possible future removal, do not enrich its interface beyond that of a collection of OutputDescriptor attributes. The OutputDataProxy also serves as a Mapping, with keys matching the attributes. We may choose to keep only this aspect of the interface instead of trying to keep track of the set of attributes.

abstract run()#

Assert execution of an operation.

After calling run(), the operation results are guaranteed to be available in the local context.

gmxapi uses a Future to reference an operation output or data that may not yet be available.

class gmxapi.abc.Future#

Data source that may represent Operation output that does not yet exist.

Futures represent “immutable resources,” or fixed points in the data flow.

abstract property dtype: type#

Data type for the promised result.

abstract result() → Any#

Fetch data to the caller’s Context.

Returns the actual result of the operation supplying this Future.

Ensemble data are returned as a list. Scalar results or results from single member ensembles are returned as scalars. If this behavior is confusing or problematic for you, please reopen https://gitlab.com/gromacs/gromacs/-/issues/3179 or a new issue and join the discussion.

An OperationReference may provide several named Futures on its output attribute.

A Future may be provided directly as inputs to other gmxapi commands. gmxapi will execute the required operation to get the data when it is needed.

To get an actual result in your Python script, you can call result() on any gmxapi data reference. If the operation has not yet been executed, the operation (and any operation dependencies) will be executed immediately.

You can also force an operation to run by calling its run() method. But this is not generally necessary unless your only goal is to produce output files on disk that are not consumed in the same script.

In some cases, a Future can be subscripted to get a new Future representing a slice of the original. For instance, commandline_operation objects have a file output that produces a mapping of command line flags to output files (per the output_files parameter). This file output can be subscripted with a single command line option to get a Future for just one output file type. See Preparing simulations for an illustrative example.

Ensemble data flow#

gmxapi automatically generates arrays of operations and parallel data flow, when parallel inputs are provided to gmxapi command parameters.

When a Future represents the output of an ensemble operation, result() returns a list with elements corresponding to the ensemble members.

It is not currently possible to get a Future for a specific ensemble member.

See Input arguments and “ensemble” syntax for more information.

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.

@gmxapi.function_wrapper(output: Optional[dict] = None, allow_duplicate=False)#

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.

gmxapi.commandline_operation(executable=None, arguments=(), input_files: Optional[Union[dict, Iterable[dict]]] = None, output_files: Optional[Union[dict, Iterable[dict]]] = None, stdin: Optional[Union[str, Iterable[str]]] = None, env: Optional[Union[dict, Iterable[dict]]] = None, **kwargs)#

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.

Note that the operation will be executed in a subprocess in an automatically generated subdirectory. See below for more information.

Parameters:

  • arguments – list of positional arguments to insert at argv[1]

  • env – Optional replacement for the environment variables seen by the subprocess.

  • executable – name of an executable on the path

  • input_files – mapping of command-line flags to input file paths

  • output_files – mapping of command-line flags to output file names

  • stdin (str) – String input to send to STDIN (terminal input) of the executable (optional).

Changed in version 0.5.0: Relative paths in input_files are considered relative to the current working directory, and are immediately converted to absolute paths.

Multi-line text sent to stdin should be joined into a single string. E.g.:

commandline_operation(..., stdin='\n'.join(list_of_strings) + '\n')

If multiple strings are provided to stdin, gmxapi will assume an ensemble, and will run one operation for each provided string.

Only string input (str()) to stdin is currently supported. If you have a use case that requires streaming input or binary input, please open an issue or contact the author(s).

Changed in version 0.3.0: output_files paths are converted to absolute paths at run time.

If non-absolute paths are provided to output_files, paths are resolved relative to the working directory of the command instance (not relative to the working directory of the workflow script).

By default, executable runs in a subprocess that inherits its environment and resources from the Python interpreter. (See https://docs.python.org/3/library/subprocess.html#subprocess.run)

New in version 0.3.1: If specified, env replaces the default environment variables map seen by executable in the subprocess.

Changed in version 0.4.1: If unspecified, env defaults to a filtered copy of the current environment (with MPI-related environment variables removed). See gmxapi.runtime.filtered_mpi_environ().

In addition to controlling environment variables used for user-input, it may be necessary to adjust the environment to prevent the subprocess from inheriting variables that it should not. This is particularly relevant if the Python script is launched with mpiexec and then commandline_wrapper is used to launch an MPI-aware executable that may try to manage the MPI context. (Reference Issue 4421)

When overriding the environment variables, don’t forget to include basic variables like PATH that are necessary for the executable to run. os.getenv can help. E.g. commandline_operation(..., env={'PATH': os.getenv('PATH'), ...})

See also

gmxapi.runtime.filtered_mpi_environ().

Output:

The output node of the resulting operation handle contains

  • directory: filesystem path that was used as the working directory for the subprocess

  • file: the mapping of CLI flags to filename strings resulting from the output_files kwarg

  • returncode: return code of the subprocess.

  • stderr: A string mapping from process STDERR; it will be the

    error output (if any) if the process failed.

  • stdout: A string mapping from process STDOUT.

Changed in version 0.3: Subprocesses run in directories managed by gmxapi.

New in version 0.3: The directory output.

Working directory names are details of the gmxapi implementation; the naming scheme is not yet specified by the API, but is intended to be related to the operation ID.

Note that re-executing a gmxapi script in the same directory will cause commands to be executed again in the same directories. If this presents a risk of data corruption (or just wasted compute cycles), you may include the key word argument _exist_ok=False to force an error. Please consider contacting the developers through any of the various GROMACS community channels to further discuss your use case.

gmxapi.subgraph(variables: Optional[Mapping] = None)#

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)#

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 API is finalized.

When called, while_loop calls operation without arguments and captures the return value for inspection of outputs. The object produced by operation() must have a reset, a run method, and an output attribute. From gmxapi 0.1, an additional values attribute is examined to advertise the output members that will appear on the while_loop output.

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.

Simulation module#

GROMACS simulation subpackage for gmxapi.

Provides operations for configuring and running molecular simulations.

The initial version of this module is a port of the gmxapi 0.0.7 facilities from https://github.com/kassonlab/gmxapi and is not completely integrated with the gmxapi 0.1 specification. Operation execution is dispatched to the old execution manager for effective ensemble handling and C++ MD module binding. This should be an implementation detail that is not apparent to the typical user, but it is worth noting that chains of gmxapi.simulation module operations will be automatically bundled for execution as gmxapi 0.0.7 style API sessions. Run time options and file handling will necessarily change as gmxapi data flow handling evolves.

In other words, if you rely on behavior not specified explicitly in the user documentation, please keep an eye on the module documentation when updating gmxapi and please participate in the ongoing discussions for design and implementation.

Preparing simulations#

gmxapi.read_tpr(filename, label: Optional[str] = None, context=None)#

Get simulation input from a TPR file.

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).

See OutputDataProxy for members of the output attribute.

class gmxapi.simulation.read_tpr.OutputDataProxy(*args, **kwargs)#

Implement the ‘output’ attribute of read_tpr operations.

parameters#

Dictionary of simulation parameters.

Additionally (through an unspecified interface), the object serves as a complete simulation input to other gmxapi operations.

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

Modify simulation input with data flow operations.

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

See OutputDataProxy for output attribute members.

class gmxapi.simulation.modify_input.OutputDataProxy(*args, **kwargs)#

Implement the ‘output’ attribute of modify_input operations.

parameters#

Aggregated dictionary simulation parameters for the resulting simulation input.

Additionally (through an unspecified interface), the object serves as a complete simulation input to other gmxapi operations.

Running simulations#

gmxapi.mdrun(input, runtime_args: Optional[Union[dict, Sequence[dict]]] = None, label: Optional[str] = None, context=None)#

MD simulation operation.

Parameters:

  • input – valid simulation input

  • runtime_args (dict) – command line flags and arguments to be passed to mdrun (optional)

Returns:

runnable operation to perform the specified simulation

See OutputDataProxy for members of the output attribute.

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

runtime_args allows an optional dictionary of mdrun options, using the option flag (including the leading hyphen -) as the dictionary key. For mdrun command line options that do not take a value (e.g. -noappend), use None as the dictionary value.

Warning

Run time argument processing does not have Python bindings at this time. key-value pairs are passed as plain text to the underlying library. Usage errors can be hard to discover. Refer to the MD log file in the output directory for messages regarding argument processing.

Note, in particular, that the available mdrun arguments can depend on the GROMACS build configuration, such as whether an MPI library or thread-MPI is enabled.

See also

The gmx mdrun command line tool.

class gmxapi.simulation.mdrun.OutputDataProxy(instance: SourceResource, client_id: Optional[int] = None)#

Implement the ‘output’ attribute of mdrun operations.

checkpoint#

Full path to cpt file.

Type:

str

directory#

Full path to the working directory in which the simulation ran.

Type:

str

parameters#

Dictionary of parameters with which the simulation was run.

Type:

dict

stderr#

Full path to the text file that captured stderr during the simulation.

Type:

str

stdout#

Full path to the text file that captured stdout during the simulation.

Type:

str

trajectory#

Full path to trajectory output (corresponding to the -o flag, if provided).

Type:

str

Notes

For multi-rank MPI-enabled simulators, stderr and stdout are reported for the root rank only, in line with how GROMACS behaves.

Changed in version 0.4: Added directory output, replacing an earlier “hidden” _work_dir output.

New in version 0.4: stderr and stdout provide paths to the captured standard I/O. Previously, a lot of output from the underlying library bypassed Python and went straight to the standard output and standard error of the calling process.

Utilities#

Provide some additional utilities.

gmxapi.utility.config()#

Get the GROMACS configuration detected during installation.

Returns read-only dictionary proxy to file written during installation. The Mapping contains information about the supporting GROMACS installation that was used to configure the Python package installation. The exact keys in the Mapping is not formally specified, and mostly for internal use.

New in version 0.4.

gmxapi.utility.join_path(first: str, second: str, output=None)#

Get a Future path for use in data flow.

This is useful when a base path or filename is not known until runtime.

output.path#

first and second, joined by the native filesystem path separator.

Type:

str

gmxapi.concatenate_lists(sublists: Sequence[Sequence[Scalar]] = ()) → ArrayFuture[Scalar]#

Combine data sources into a single list.

A trivial data flow restructuring helper.

gmxapi.join_arrays(*, front: NDArray = (), back: NDArray = ()) → Future[NDArray]#

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.

gmxapi.logical_not(value)#

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 produces the logical opposite of the result of the callable. If the callable produces a (non-string) sequence, the wrapper returns a list of the negated results of the callable.

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

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.

Run time details#

Note

The gmxapi.runtime Python module is evolving. Some details are not yet well specified.

Manage computing resources and runtime context.

Utilities, context managers, and singletons for handling resource allocation and lifetime management.

For the purposes of this module, the term “assignment” refers to resources that have been reserved (usually for exclusive use) within a well-defined scope (such as a specific function call or phase of program execution).

“Allocation” can be taken to mean “resources that are available to be assigned,” and may or may not be tightly scoped.

Resource assignment may be nested, in which case an Assignment with a broader scope in the program is used as the Allocation from which a more local Assignment is made.

Assignment and Allocation are roles that can be served by Context objects. Abstractly, a Context is a notion of some aspect of program or resource state. A Context may be represented by a concrete class when an object manages the details needed to participate in a stateful protocol.

Note that resource assignment is usually a collective operation within the scope of an allocation. For instance, an MPI_Comm_split call must be made (synchronously) on all members of the parent MPI communicator. Similar care must be taken with the Allocation and Assignment protocols in this module.

New in version 0.4.0: This module generalizes some of the resource management previously in gmxapi.simulation.mdrun, decoupling MPI communicator handling from gmxapi.simulation.context. See also https://gitlab.com/gromacs/gromacs/-/issues/3718

gmxapi.runtime.filtered_mpi_environ() → dict#

Return a filtered environment variables map with MPI-related entries removed.

See also

filtered_prefixes

gmxapi.runtime.filtered_prefixes = ('DCMF_', 'MPICH_', 'MPIEXEC_', 'MPIO_', 'MV2_', 'MVAPICH_', 'HYDRA_', 'OMPI_', 'PMI_', 'PMIX_', 'I_MPI_')#

MPI-related environment variable prefixes.

Environment variable prefixes known to be associated with MPI implementations, which may affect MPI context detection, and which should not matter outside of MPI contexts.

References

Status messages and Logging#

Python logging facilities use the built-in logging module.

Upon import, the gmxapi package sets a placeholder “NullHandler” to block propagation of log messages to the root logger (and sys.stderr, if not handled).

If you want to see gmxapi logging output on sys.stderr, import logging in your script or module and configure it. For the simplest case, consider logging.basicConfig:

>>> import logging
>>> logging.basicConfig(level=logging.DEBUG)

For more advanced usage, consider attaching a logging.StreamHandler to the gmxapi logger.

The gmxapi logging module adds an additional rank_tag log formatter field that can be particularly helpful in ensemble MPI workflows.

Example:

ch = logging.StreamHandler()
# Optional: Set log level.
ch.setLevel(logging.DEBUG)
# Optional: create formatter and add to character stream handler
formatter = logging.Formatter('%(levelname)s %(asctime)s:%(name)s %(rank_tag)s%(message)s')
ch.setFormatter(formatter)
# add handler to logger
logging.getLogger('gmxapi').addHandler(ch)

To handle log messages that are issued while importing gmxapi and its submodules, attach the handler before importing gmxapi

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#

An API operation was attempted with an incompatible object.

exception gmxapi.exceptions.DataShapeError#

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#

Base exception for gmx.exceptions classes.

exception gmxapi.exceptions.FeatureNotAvailableError#

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.MissingImplementationError#

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.

Changed in version 0.3: Named changed to avoid conflict with built-in NotImplementedError exception

exception gmxapi.exceptions.ProtocolError#

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#

Incompatible type for gmxapi data.

Reference datamodel.rst for more on gmxapi data typing.

exception gmxapi.exceptions.UsageError#

Unsupported syntax or call signatures.

Generic usage error for gmxapi module.

exception gmxapi.exceptions.ValueError#

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

exception gmxapi.exceptions.Warning#

Base warning class for gmx.exceptions.

gmx.version module#

gmxapi version and release information.

The gmxapi.__version__ attribute contains a version string. The more general way to access the package version is with the pkg_resources module:

pkg_resources.get_distribution('gmxapi').version

gmxapi.version module functions api_is_at_least() and has_feature() support additional convenience and introspection.

Changed in version 0.2: This module no longer provides public data attributes. Instead, use the module functions or packaging.version.

See also

Consider https://packaging.pypa.io/en/latest/version/ for programmatic handling of the version string. For example:

import pkg_resources
from packaging.version import parse
gmxapi_version = pkg_resources.get_distribution('gmxapi').version
if parse(gmxapi_version).is_prerelease:
    print('The early bird gets the worm.')
gmxapi.version.api_is_at_least(major_version, minor_version=0, patch_version=0)#

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: str, 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 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#

Module Exceptions#

exception gmxapi._gmxapi.Exception#

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

exception gmxapi._gmxapi.FeatureNotAvailable#

An API feature is not available in the current installation.

This may occur when a new gmxapi Python package is installed with an older GROMACS installation that does not have the library support for a newer feature.

Wrapped C++ exceptions emitted through the supporting GROMACS library#

exception gmxapi._gmxapi.MissingImplementationError#

Expected feature is not implemented.

Changed in version 0.3: Renamed from NotImplementedError.

exception gmxapi._gmxapi.ProtocolError#

Behavioral protocol violated.

exception gmxapi._gmxapi.UsageError#

Unacceptable API usage.

Other#

No other C++ exceptions are expected, but will be wrapped in a Exception to help tracing and reporting bugs.

exception gmxapi._gmxapi.UnknownException#

Catch-all exception wrapper.

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.)

Functions#

This documentation is provided for completeness and as an aid to developers. Users of the gmxapi package, generally, should not need to use the following tools directly.

Tools for launching simulations#

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

Return a system container initialized from the given input record.

gmxapi._gmxapi.create_context(*args, **kwargs)#

Overloaded function.

  1. create_context() -> gmxapi._gmxapi.Context

Initialize a new API Context to manage resources and software environment.

  1. create_context(arg0: object) -> gmxapi._gmxapi.Context

Initialize a new API Context to manage resources and software environment.

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.

Utilities#

gmxapi._gmxapi.has_feature(arg0: str) → bool#

Check feature name first with the bindings package, then the supporting library.

Available features may depend on the package version, the details of the supporting GROMACS installation, the software environment detected when the package was built, or possibly on detected runtime details. These feature checks are largely for internal use. The gmxapi commands may adjust their behavior slightly depending on feature checks, and (at worst) should produce meaningful error messages or exceptions.

Named features:

  • create_context: create_context can be used to initialize a Context with assigned resources.

  • mpi_bindings: C++ extension module was built with mpi4py compatibility.

Classes#

class gmxapi._gmxapi.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#
get_args(self: gmxapi._gmxapi.MDArgs) → list#

Get an iterator of command line argument tokens, if possible and relevant.

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#