GROMACS

https://manual.gromacs.org/2026.1
Admin
GROMACS is a molecular dynamics simulation package designed for biomolecular simulations with...
Tokens:3,200,731
Snippets:40,567
Trust Score:9.4
Update:1 week ago
Show doc for...
Tokens:
Raw
### void start ()

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/classgmx_1_1OptionsAssigner.xhtml

Starts assigning values.

```APIDOC
## void start ()

### Description
Starts assigning values.

### Method
start


```

--------------------------------

### Quick and dirty installation: build and install GROMACS

Source: https://manual.gromacs.org/2026.1/install-guide/index.html

Quick and dirty installation sequence for GROMACS. Downloads and builds FFTW (if -DGMX_BUILD_OWN_FFTW=ON is used), then compiles and installs GROMACS. Make sure CMake 3.28 or later and recent C/C++ compilers are available. After installation, source GMXRC to get access to GROMACS.

```shell
tar xfz gromacs-2026.1.tar.gz
cd gromacs-2026.1
mkdir build
cd build
cmake .. -DGMX_BUILD_OWN_FFTW=ON -DREGRESSIONTEST_DOWNLOAD=ON
make
make check
sudo make install
source /usr/local/gromacs/bin/GMXRC
```

--------------------------------

### Install gmxapi from downloaded source distribution

Source: https://manual.gromacs.org/2026.1/gmxapi/userguide/install.html

Download the source distribution archive and install it from the filesystem, substituting the actual version in the filename.

```bash
pip download gmxapi
pip install gmxapi-<version>.tar.gz

```

--------------------------------

### Install and run Black with .black.toml

Source: https://manual.gromacs.org/2026.1/dev-manual/code-formatting.html

Install Black and reformat all Python files in the repository using the .black.toml configuration. Black works in place by default.

```bash
pip install black
black --config .black.toml .
```

--------------------------------

### Build wheel with internet access and install offline

Source: https://manual.gromacs.org/2026.1/gmxapi/userguide/install.html

Build a gmxapi wheel and its dependencies while online, then install without internet access. The commands remove cached wheels, download dependencies, and install from a local directory.

```bash
# Remove any locally cached (previously built) wheels.
pip cache remove gmxapi

# Download gmxapi and dependencies from pypi.
pip wheel --wheel-dir DIR gmxapi
# or, using package source from the GROMACS repository
cd python_packaging/gmxapi
pip wheel --wheel-dir DIR .

# Later, install.
pip install --no-index --find-links=DIR DIR/gmxapi*whl

```

--------------------------------

### Install or upgrade required Python components

Source: https://manual.gromacs.org/2026.1/gmxapi/userguide/install.html

Upgrades pip, setuptools, and wheel to prepare for installing gmxapi dependencies.

```bash
python -m pip install --upgrade pip
pip install --upgrade setuptools wheel

```

--------------------------------

### Install gmxapi including pre-release versions

Source: https://manual.gromacs.org/2026.1/gmxapi/userguide/install.html

Use the --pre flag to allow pip to install pre-release versions of gmxapi.

```bash
# Get the latest version, including pre-release versions.
pip install --no-cache-dir --pre gmxapi

```

--------------------------------

### void H5md::setupFromExistingFile()

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/classgmx_1_1H5md.xhtml

Sets up from an existing file, reading its structure.

```APIDOC
## void H5md::setupFromExistingFile()

### Description
Set up from an existing file.

### Returns
None.
```

--------------------------------

### InstallationPrefixInfo Constructor

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/structgmx_1_1InstallationPrefixInfo.xhtml

Initializes the structure with the given path and source layout flag.

```APIDOC
## InstallationPrefixInfo Constructor

### Description
Initializes the structure with the given values.

### Signature
`InstallationPrefixInfo(const std::filesystem::path &path, bool bSource)`

### Parameters
- **path** (std::filesystem::path) - Path to the installation prefix.
- **bSource** (bool) - Whether the path points to a source tree layout.

```

--------------------------------

### Run mdrun with eight ranks and GPU task assignment

Source: https://manual.gromacs.org/2026.1/user-guide/mdrun-performance.html

Using similar hardware as the previous example, starts gmx mdrun on a machine with two nodes, using eight total ranks, each rank with three OpenMP threads, and all four ranks on a node sharing GPU with ID 0. This may or may not be faster than the previous setup on the same hardware.

```bash
mpirun -np 8 gmx_mpi mdrun -ntomp 3 -gputasks 0000

```

--------------------------------

### pybind11 build error output

Source: https://manual.gromacs.org/2026.1/gmxapi/userguide/install.html

Example error output when building gmxapi fails because pybind11 is not found. This can happen if automatic dependency installation is disabled.

```text
  ModuleNotFoundError: No module named 'pybind11'
  Building wheel for gmxapi (pyproject.toml): finished with status 'error'
  ERROR: Failed building wheel for gmxapi
Failed to build gmxapi
ERROR: Could not build wheels for gmxapi, which is required to install pyproject.toml-based projects

```

--------------------------------

### void gmx::H5md::setupFromExistingFile()

Source: https://manual.gromacs.org/2026.1/doxygen/html-lib/classgmx_1_1H5md.xhtml

Sets up from an existing file, scanning for trajectory data in the /particles/system group.

```APIDOC
## Member Function

### Description
Set up from an existing file. Scans for trajectory data available in the /particles/system group of the HDF5 file. For trajectories written by GROMACS this group contains data for all atoms in the simulated system.

### Note
Ignores trajectory data in other subgroups of /particles.
```

--------------------------------

### gmx::H5md::setupFromExistingFile

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/classgmx_1_1H5md-members.xhtml

Sets up the H5md object from an existing H5MD file.

```APIDOC
## Method: setupFromExistingFile

### Description
Sets up the H5md object from an existing H5MD file.

### Signature
`setupFromExistingFile()`

```

--------------------------------

### Run mdrun with external MPI on one node

Source: https://manual.gromacs.org/2026.1/user-guide/mdrun-performance.html

When using a gmx mdrun compiled with external MPI, this starts two ranks and as many OpenMP threads as the hardware and MPI setup will permit. If the MPI setup is restricted to one node, the resulting gmx mdrun will be local to that node.

```bash
gmx mdrun -ntmpi 8 -nb gpu -pme gpu -npme 1 -bonded gpu -update gpu

```

--------------------------------

### void H5md::setupFileFromInput(const gmx_mtop_t &topology, const t_inputrec &inputRecord)

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/classgmx_1_1H5md.xhtml

Sets up the file from input data, such as topology and input record.

```APIDOC
## void H5md::setupFileFromInput(const gmx_mtop_t &topology, const t_inputrec &inputRecord)

### Description
Set up the file from input data.

### Parameters
- **topology** (const gmx_mtop_t&) - The molecular topology.
- **inputRecord** (const t_inputrec&) - The input record.

### Returns
None.
```

--------------------------------

### CMake error for missing gmxapi package configuration

Source: https://manual.gromacs.org/2026.1/gmxapi/userguide/install.html

Example CMake error when the gmxapi support library cannot be found. This can occur if GROMACS is not installed, was built without GMXAPI=ON, or if gmxapi_ROOT is not set correctly.

```text
CMake Error at gmx/core/CMakeLists.txt:45 (find_package):
   Could not find a package configuration file provided by "gmxapi" with any
   of the following names:

     gmxapiConfig.cmake
     gmxapi-config.cmake

   Add the installation prefix of "gmxapi" to CMAKE_PREFIX_PATH or set
   "gmxapi_ROOT" to a directory containing one of the above files.  If "gmxapi"
   provides a separate development package or SDK, be sure it has been
   installed.

```

--------------------------------

### Example ndx index file with Oxygen and Hydrogen groups

Source: https://manual.gromacs.org/2026.1/reference-manual/file-formats.html

Example GROMACS index file (index.ndx) with two groups: Oxygen (atoms 1, 4, 7) and Hydrogen (atoms 2, 3, 5, 6, 8, 9). Group names are in square brackets; atom numbers can span multiple lines and start at 1. Use gmx make_ndx to generate index files.

```plaintext
[ Oxygen ]
1  4  7
[ Hydrogen ]
2  3  5  6
8  9

```

--------------------------------

### Run mdrun with GPU IDs 0 and 1

Source: https://manual.gromacs.org/2026.1/user-guide/mdrun-performance.html

Starts gmx mdrun with 20 ranks. This setup is likely to be suitable when there are ten nodes, each with two GPUs, but there is no need to specify -gpu_id for the normal case where all the GPUs on the node are available for use.

```bash
mpirun -np 20 gmx_mpi mdrun -gpu_id 01

```

--------------------------------

### void H5md::setupFromExistingFileForAppending(int64_t restartingFromStep, int64_t numParticles)

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/classgmx_1_1H5md.xhtml

Sets up from an existing file when restarting a simulation from a checkpoint, allowing appending.

```APIDOC
## void H5md::setupFromExistingFileForAppending(int64_t restartingFromStep, int64_t numParticles)

### Description
Set up from an existing file when restarting a simulation from a checkpoint.

### Parameters
- **restartingFromStep** (int64_t) - The step from which to restart.
- **numParticles** (int64_t) - The number of particles.

### Returns
None.
```

--------------------------------

### HaloExchange::setup

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/classgmx_1_1HaloExchange.xhtml

Sets up the halo communication after (re)partitioning.

```APIDOC
## HaloExchange::setup

### Description
Set up the halo communication, should be called after (re)partitioning.

### Method
setup

### Parameters
- **dd** (gmx_domdec_t*) - Required - Domain decomposition data.
- **localState** (t_state*) - Required - Local state.
- **ddbox** (const gmx_ddbox_t&) - Required - Domain decomposition box.
- **fr** (t_forcerec*) - Required - Force record.
- **cellsChanged** (bool) - Required - Whether cells have changed.
```

--------------------------------

### Run mdrun with 20 ranks and GPU task assignment

Source: https://manual.gromacs.org/2026.1/user-guide/mdrun-performance.html

Starts gmx mdrun with 20 ranks, and assigns the CPU cores evenly across ranks each to one OpenMP thread. This setup is likely to be suitable when there are ten nodes, each with one GPU, and each node has two sockets each of four cores.

```bash
mpirun -np 20 gmx_mpi mdrun -ntomp 4 -gputasks 00

```

--------------------------------

### Install cmake and pybind11

Source: https://manual.gromacs.org/2026.1/gmxapi/userguide/install.html

Install the additional packages required by the gmxapi installer.

```bash
pip install --upgrade cmake pybind11

```

--------------------------------

### OptionsAssigner::start()

Source: https://manual.gromacs.org/2026.1/doxygen/html-lib/classgmx_1_1OptionsAssigner.xhtml

Starts assigning values to options.

```APIDOC
## start

### Description
Starts assigning values to options.

### Signature
`void start()`

```

--------------------------------

### SPC water molecule topology with [settles]

Source: https://manual.gromacs.org/2026.1/reference-manual/topologies/constraint-algorithm-section.html

Example topology for SPC water using the SETTLE algorithm. The [settles] directive defines the first atom of the water molecule, with funct always 1 and the O-H and H-H distances given. This setup can also be used for TIP3P and TIP4P, though TIP4P has a virtual site that does not need to be shaken.

```gromacs
[ moleculetype ]
; molname       nrexcl
SOL             1

[ atoms ]
; nr    at type res nr  ren nm  at nm   cg nr   charge
1       OW      1       SOL     OW1     1       -0.82
2       HW      1       SOL     HW2     1        0.41
3       HW      1       SOL     HW3     1        0.41

[ settles ]
; OW    funct   doh     dhh
1       1       0.1     0.16333

[ exclusions ]
1       2       3
2       1       3
3       1       2

```

--------------------------------

### void startOption (const char *name)

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/classgmx_1_1OptionsAssigner.xhtml

Starts assigning values for an option.

```APIDOC
## void startOption (const char *name)

### Description
Starts assigning values for an option.

### Method
startOption

### Parameters
- **name** (const char*) - The name of the option.


```

--------------------------------

### subArray(size_type start, size_type count) const

Source: https://manual.gromacs.org/2026.1/doxygen/html-lib/classgmx_1_1ArrayRef-members.xhtml

Returns a sub-ArrayRef starting at index start with the given count.

```APIDOC
## subArray(size_type start, size_type count) const

### Description
Returns a sub-ArrayRef starting at index start with the given count.

### Method
Member function

### Signature
`subArray(size_type start, size_type count) const`

### Parameters
- **start** (size_type) - Required - Starting index.
- **count** (size_type) - Required - Number of elements in the sub-array.

### Returns
An ArrayRef referencing the sub-range.

```

--------------------------------

### static void init()

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/classgmx_1_1MimicCommunicator.xhtml

Initializes the communicator.

```APIDOC
## static void init()

### Description
Initializes the communicator.

### Method
static void init()

### Parameters
None.

### Returns
None.
```

--------------------------------

### Install Python requirements from requirements.txt

Source: https://manual.gromacs.org/2026.1/gmxapi/userguide/install.html

Installs the Python requirements listed in the GROMACS source tree's requirements.txt file before installing gmxapi.

```bash
pip install -r python_packaging/gmxapi/requirements.txt

```

--------------------------------

### Install mpi4py with matching MPI

Source: https://manual.gromacs.org/2026.1/gmxapi/userguide/install.html

Install mpi4py using the same MPI installation and compatible compilers as GROMACS. Use this if you did not inherit mpi4py from system site-packages.

```bash
MPICC=`which mpicc` pip install --no-cache-dir --upgrade mpi4py

```

--------------------------------

### Set up a simple simulation with gmxapi.read_tpr() and gmxapi.mdrun()

Source: https://manual.gromacs.org/2026.1/gmxapi/userguide/usage.html

Creates a simulation input from a TPR file and sets up an mdrun operation. Note that this only sets up the work; execution is not triggered until md.run() or result() is called.

```python
import gmxapi as gmx
simulation_input = gmx.read_tpr(tpr_filename)
md = gmx.mdrun(simulation_input)

```

--------------------------------

### Set up Python virtual environment and install mpi4py

Source: https://manual.gromacs.org/2026.1/gmxapi/userguide/install.html

Creates a Python virtual environment, activates it, ensures pip is available, upgrades pip/setuptools/wheel, and installs mpi4py. Note that mpi4py may require additional compiler hints.

```bash
python3 -m venv $HOME/myvenv
. $HOME/myvenv/bin/activate
python -m ensurepip --default-pip
pip install --upgrade pip setuptools wheel
pip install mpi4py

```

--------------------------------

### Install gmxapi Python package from PyPI

Source: https://manual.gromacs.org/2026.1/gmxapi/userguide/install.html

Sources the GROMACS environment via GMXRC and installs gmxapi from PyPI, building it for the GROMACS installation at /path/to/gromacs.

```bash
. /path/to/gromacs/bin/GMXRC
pip install --no-cache-dir gmxapi

```

--------------------------------

### gmx::H5md::setupFileFromInput

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/classgmx_1_1H5md-members.xhtml

Sets up the H5MD file based on the given topology and input record.

```APIDOC
## Method: setupFileFromInput

### Description
Sets up the H5MD file from the provided topology and input record.

### Signature
`setupFileFromInput(const gmx_mtop_t &topology, const t_inputrec &inputRecord)`

### Parameters
- **topology** (const gmx_mtop_t&) - The molecular topology.
- **inputRecord** (const t_inputrec&) - The input record.

```

--------------------------------

### Launch multi-simulation with -multidir and -gputasks

Source: https://manual.gromacs.org/2026.1/user-guide/mdrun-features.html

Starts the same multi-simulation as the previous example, but maps PP ranks to GPUs using -gputasks. On a machine with two physical nodes and two GPUs per node, there are 16 MPI ranks per node and 8 MPI ranks per simulation. The PP ranks from each simulation use a single GPU, but the order 0101010101010101 could run faster.

```bash
mpirun -np 32 gmx_mpi mdrun -multidir a b c d -gputasks 0000000011111111

```

--------------------------------

### HelpWriterContext::HelpWriterContext

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/classgmx_1_1HelpWriterContext.xhtml

Initializes a context with the given output writer and format. Optionally accepts links for help references.

```APIDOC
## HelpWriterContext::HelpWriterContext

### Description
Initializes a context with the given output writer and format. Optionally accepts links for help references.

### Method
Constructor

### Signature
HelpWriterContext(TextWriter *writer, HelpOutputFormat format)
HelpWriterContext(TextWriter *writer, HelpOutputFormat format, const HelpLinks *links)

### Parameters
- **writer** (TextWriter*) - Required - The output writer to use.
- **format** (HelpOutputFormat) - Required - The output format for help.
- **links** (const HelpLinks*) - Optional - Links for help references.

### Notes
Copying creates a context object that shares state with the source.
```

--------------------------------

### start(real min)

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/classgmx_1_1AnalysisHistogramSettingsInitializer-members.xhtml

Sets the start value of the histogram range.

```APIDOC
## start(real min)

### Description
Sets the start value of the histogram range.

### Method
Member function

### Signature
start(real min)

### Parameters
- **min** (real) - Required - The start value.

### Returns
No return value.
```

--------------------------------

### HelpWriterContext::writeOptionListStart

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/classgmx_1_1HelpWriterContext.xhtml

Starts writing a list of options.

```APIDOC
## HelpWriterContext::writeOptionListStart

### Description
Starts writing a list of options.

### Method
void writeOptionListStart() const
```

--------------------------------

### isAcceptableLibraryPathPrefix

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/group__module__commandline.xhtml

Checks whether a given path prefix could be the installation prefix where `share/top/` files have been installed. It appends the relative installation path of the data files and calls isAcceptableLibraryPath().

```APIDOC
## isAcceptableLibraryPathPrefix

### Description
Returns whether given path prefix contains files from `share/top/`. Checks whether `path` could be the installation prefix where `share/top/` files have been installed: appends the relative installation path of the data files and calls isAcceptableLibraryPath().

### Parameters
- **path** (const std::filesystem::path&) - Path prefix to check.

### Returns
`true` if `path` contains the data files.
```

--------------------------------

### gmx::H5md::setupFromExistingFileForAppending

Source: https://manual.gromacs.org/2026.1/doxygen/html-full/classgmx_1_1H5md-members.xhtml

Sets up the H5md object from an existing file for appending, given the restart step and number of particles.

```APIDOC
## Method: setupFromExistingFileForAppending

### Description
Sets up the H5md object from an existing file for appending.

### Signature
`setupFromExistingFileForAppending(int64_t restartingFromStep, int64_t numParticles)`

### Parameters
- **restartingFromStep** (int64_t) - The step from which to restart.
- **numParticles** (int64_t) - The number of particles.

```
Tokens:
Raw