GromacsCommand

Module

viennaptm.gromacs.gromacs_command

class GromacsCommand(gmx_bin: str | None = None, mpi: MPIConfig | None = None, workdir: Path | None = None, stdin: str | None = None, timeout: int | None = None, env: Dict[str, str] | None = None)

Bases: ABC

Abstract base class for all GROMACS command wrappers.

This class provides common functionality for constructing, executing, and validating GROMACS command-line invocations, including optional MPI execution, environment handling, and post-run output validation.

Subclasses must implement build_gromacs_cmd() and expected_outputs().

build_command() → List[str]

Build the full command invocation.

This includes the optional MPI prefix followed by the GROMACS command constructed by the subclass.

Returns:

Complete command-line argument list.

Return type:

list[str]

abstractmethod build_gromacs_cmd() → List[str]

Build the GROMACS command invocation.

This method must be implemented by subclasses and should return the command arguments excluding any MPI prefix.

Returns:

Command-line argument list for the GROMACS command.

Return type:

list[str]

abstractmethod expected_outputs() → List[Path]

Declare output files expected from this command.

Subclasses must return a list of paths that should exist after successful execution.

Returns:

List of expected output file paths.

Return type:

list[pathlib.Path]

inspect_result(result: CompletedProcess) → None

Inspect command output for fatal GROMACS errors.

Both stdout and stderr are scanned for known fatal error markers. If detected, a readable error snippet is extracted and raised as an exception.

Parameters:

result (subprocess.CompletedProcess) – Completed subprocess result to inspect.

Raises:

RuntimeError – If a fatal GROMACS error marker is found.

mpi_prefix() → List[str]

Construct the MPI command prefix.

If MPI execution is disabled, an empty list is returned. Otherwise, the launcher and process count are included.

Returns:

MPI command prefix suitable for prepending to the GROMACS command.

Return type:

list[str]

post_run_checks() → None

Verify that expected output files were created.

Raises:

FileNotFoundError – If any expected output file is missing.

run() → CompletedProcess

Execute the GROMACS command.

The command is executed synchronously. Standard output and error streams are captured and inspected for fatal errors.

Raises:

• RuntimeError – If execution times out or a fatal GROMACS error is detected.

• FileNotFoundError – If expected output files are missing after execution.

Returns:

Completed subprocess result.

Return type:

subprocess.CompletedProcess

Methods

__init__([gmx_bin, mpi, workdir, stdin, ...])	Initialize a GROMACS command wrapper.
build_command()	Build the full command invocation.
build_gromacs_cmd()	Build the GROMACS command invocation.
expected_outputs()	Declare output files expected from this command.
inspect_result(result)	Inspect command output for fatal GROMACS errors.
mpi_prefix()	Construct the MPI command prefix.
post_run_checks()	Verify that expected output files were created.
run()	Execute the GROMACS command.