Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions .github/workflows/cmdata.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,11 +36,15 @@ jobs:
- name: Build cmdata
run: |
cd tools/cmdata; mkdir build; cd build
cmake ../
cmake ../ -DCMDATA_BUILD_TESTS=ON
make
sudo make install
- name: Test cmdata
run: |
cd tools/cmdata/build
make test
cmdata --help
- name: Run cmdata test
- name: Run cmdata regtests
run: |
source /usr/local/gromacs/bin/GMXRC
cd tests; bash run_cmdata.sh; cd ..
Expand Down
6 changes: 3 additions & 3 deletions tests/run_cmdata.sh
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@ set -o pipefail

# Relative and absolute tolerances for numerical comparison.
# Adjust RTOL / ATOL here to tighten or loosen the test.
RTOL=${CMDATA_RTOL:-1e-4}
RTOL=${CMDATA_RTOL:-5e-4}
ATOL=${CMDATA_ATOL:-1e-7}

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
COMPARE="$SCRIPT_DIR/compare_histo.py"

mkdir test_inputs/cmdata/histo
mkdir -p test_inputs/cmdata/histo
cd test_inputs/cmdata/histo
cmdata -f ../traj.xtc -s ../protein.tpr --noh5
OMP_NUM_THREADS=2 cmdata -f ../traj.xtc -s ../protein.tpr --noh5
cd ../../../

tar -zxf test_outputs/cmdata/hh.tgz -C test_outputs/cmdata/
Expand Down
1 change: 1 addition & 0 deletions tools/cmdata/.gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
build/
exe/
test/test_cmdata
26 changes: 25 additions & 1 deletion tools/cmdata/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,17 @@ endif()
# find gromacs
find_package(GROMACS REQUIRED NAMES gromacs gromacs_mpi gromacs_d gromacs_mpi_d HINTS "$ENV{GROMACS_DIR}")

find_package(OpenMP)
if(OpenMP_CXX_FOUND)
message(STATUS "OpenMP ${OpenMP_CXX_VERSION} found — parallel build enabled (set OMP_NUM_THREADS at runtime)")
else()
message(WARNING "OpenMP not found — building single-threaded.\n"
" On macOS: brew install libomp, then re-run cmake with:\n"
" -DOpenMP_CXX_FLAGS='-Xpreprocessor -fopenmp'\n"
" -DOpenMP_CXX_LIB_NAMES=omp\n"
" -DOpenMP_omp_LIBRARY=$(brew --prefix libomp)/lib/libomp.dylib")
endif()

# check if gromacs version is at least 2026
string(REPLACE "." ";" GMX_VER_LIST "${GROMACS_VERSION}")
list(GET GMX_VER_LIST 0 GMX_MAJOR_VER)
Expand Down Expand Up @@ -61,6 +72,12 @@ FetchContent_Declare(
DOWNLOAD_EXTRACT_TIMESTAMP TRUE
)
FetchContent_MakeAvailable(popt)
# Suppress all warnings from popt (third-party, no control)
target_compile_options(popt PRIVATE -w)
get_target_property(_popt_inc popt INTERFACE_INCLUDE_DIRECTORIES)
if(_popt_inc)
set_target_properties(popt PROPERTIES INTERFACE_SYSTEM_INCLUDE_DIRECTORIES "${_popt_inc}")
endif()

message(STATUS "Fetching xdrfile")
FetchContent_Declare(
Expand All @@ -72,9 +89,15 @@ FetchContent_Declare(
# default so the warning is suppressed in that subdirectory.
set(CMAKE_POLICY_DEFAULT_CMP0048 NEW)
FetchContent_MakeAvailable(xdrfile)
# Suppress all warnings from xdrfile (third-party, no control)
target_compile_options(xdrfile PRIVATE -w)
get_target_property(_xdr_inc xdrfile INTERFACE_INCLUDE_DIRECTORIES)
if(_xdr_inc)
set_target_properties(xdrfile PROPERTIES INTERFACE_SYSTEM_INCLUDE_DIRECTORIES "${_xdr_inc}")
endif()

# link libraries
target_link_libraries(${CMDATA} PRIVATE Gromacs::libgromacs xdrfile popt)
target_link_libraries(${CMDATA} PRIVATE Gromacs::libgromacs xdrfile popt $<$<BOOL:${OpenMP_CXX_FOUND}>:OpenMP::OpenMP_CXX>)

# Workaround for macOS 26+ SDK: libm.tbd was removed because math functions are
# now fully part of libSystem. GROMACS (and other deps) may export an absolute
Expand Down Expand Up @@ -103,6 +126,7 @@ set_target_properties(${PROJECT_NAME} PROPERTIES INSTALL_RPATH ${CMAKE_INSTALL_P
install(TARGETS ${CMDATA} DESTINATION ${CMAKE_INSTALL_PREFIX}/bin)

# build test
option(CMDATA_BUILD_TESTS "Build and register unit tests (no GROMACS required)" OFF)
if(CMDATA_BUILD_TESTS)
enable_testing()
add_subdirectory(test/)
Expand Down
99 changes: 63 additions & 36 deletions tools/cmdata/README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# cmdata

`cmdata` calculates interatomic distance histograms from GROMACS trajectories and outputs probability density and CDF files used by multi-eGO to build its input contact matrices.
`cmdata` calculates interatomic distance histograms from GROMACS trajectories and outputs probability density and cumulative distribution function (CDF) files used by multi-eGO to build its contact matrices.

## Installation

### Prerequisites

GROMACS 2023, 2024, or 2026+ must be compiled and installed with:
**GROMACS** (2023+) must be built with the legacy API and shared libraries enabled:

```bash
cmake .. -DGMX_INSTALL_LEGACY_API=ON \
Expand All @@ -15,7 +15,23 @@ cmake .. -DGMX_INSTALL_LEGACY_API=ON \
make -j$(nproc) && make install
```

HDF5 is optional. If found by CMake, output files can be written in HDF5 format (`.h5`) in addition to plain text (`.dat`).
**OpenMP** is used for parallelism and is detected automatically at build time. On Linux it is provided by GCC or Clang out of the box. On macOS, Apple Clang does not include OpenMP; install it via Homebrew:

```bash
brew install libomp
```

then point CMake at it:

```bash
cmake .. -DOpenMP_CXX_FLAGS="-Xpreprocessor -fopenmp" \
-DOpenMP_CXX_LIB_NAMES="omp" \
-DOpenMP_omp_LIBRARY=$(brew --prefix libomp)/lib/libomp.dylib
```

If OpenMP is not found, cmdata builds and runs correctly but uses only one core.

**HDF5** is optional but recommend. If found by CMake, output files can be written in HDF5 format (`.h5`) in addition to plain text (`.dat`).

### Building cmdata

Expand All @@ -26,14 +42,13 @@ cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install \
make -j$(nproc) && make install
```

> **macOS note:** the build system automatically strips the stale `libm.tbd` reference that GROMACS exports in its CMake config — this stub was removed from the macOS 26+ SDK (math is now part of `libSystem`). No manual workaround is needed.

Set `GROMACS_DIR` to the root of your GROMACS installation if it is not in a standard location.

To build with tests:
To build with unit tests (no GROMACS required for the tests themselves):

```bash
cmake .. -DCMDATA_BUILD_TESTS=ON
make && ctest
```

## Usage
Expand All @@ -46,27 +61,25 @@ cmdata -f TRAJ -s TOP [OPTIONS]

| Option | Description |
|--------|-------------|
| `-f`, `--traj=FILE` | Input trajectory file (`.xtc`, `.trr`, `.gro`, or `.pdb`) |
| `-f`, `--traj=FILE` | Input trajectory file (`.xtc`) |
| `-s`, `--top=FILE` | Input topology file (`.tpr`) |
| `--mode=STRING` | Calculation mode (see below) |

### Optional options

| Option | Default | Description |
|--------|---------|-------------|
| `-o`, `--out=STRING` | `""` (current dir) | Output file prefix |
| `-b`, `--t_begin=FLOAT` | `0.0` | Start time (ps) |
| `-e`, `--t_end=FLOAT` | `-1` (end of traj) | End time (ps); `-1` means read to the end |
| `--dt=INT` | `0` (every frame) | Only process frames at multiples of this time (ps) |
| `--cutoff=FLOAT` | `0.75` | Distance cutoff for atom pairs (nm) |
| `--mol_cutoff=FLOAT` | `6.0` | Centre-of-mass cutoff for molecule pairs (nm) |
| `--nskip=INT` | `0` | Skip every N frames (0 = no skipping) |
| `--num_threads=INT` | `1` | Number of threads for the mindist accumulation step |
| `--mol_threads=INT` | `1` | Number of concurrent molecule threads |
| `--weights=FILE` | `""` (none) | Per-frame weight file (one float per line) |
| `--bkbn_H=STRING` | `""` (none) | Backbone hydrogen atom name to include (all other H atoms are skipped) |
| `--no_pbc` | off | Disable periodic boundary corrections |
| `--noh5` | off | Write plain-text `.dat` files instead of HDF5 `.h5` files (ignored if HDF5 was not found at build time) |
| `-o`, `--out=STRING` | `""` (current dir) | Output file prefix |
| `-b`, `--t_begin=FLOAT` | `0.0` | Start time (ps) |
| `-e`, `--t_end=FLOAT` | `-1` (end of traj) | End time (ps); `-1` means read to the end |
| `--dt=INT` | `0` (every frame) | Only process frames at multiples of this time (ps) |
| `--cutoff=FLOAT` | `0.75` | Distance cutoff for atom pairs (nm) |
| `--mol_cutoff=FLOAT` | `6.0` | Centre-of-mass cutoff for molecule pairs (nm) |
| `--nskip=INT` | `0` | Skip every N frames (0 = no skipping) |
| `--weights=FILE` | `""` (none) | Per-frame weight file (one float per line) |
| `--bkbn_H=STRING` | `""` (none) | Backbone hydrogen atom name to include (all other H are skipped) |
| `--no_pbc` | off | Disable periodic boundary corrections |
| `--noh5` | off | Write plain-text `.dat` files instead of HDF5 `.h5` (ignored if HDF5 was not found at build time) |

### Mode

Expand All @@ -80,40 +93,54 @@ cmdata -f TRAJ -s TOP [OPTIONS]

Examples: `--mode intra`, `--mode same+cross`, `--mode intra+same+cross`.

### Parallelism

cmdata uses **OpenMP** to parallelise the per-molecule pairwise distance loop. The number of threads is controlled at runtime via the standard `OMP_NUM_THREADS` environment variable — no build-time flags are needed:

```bash
OMP_NUM_THREADS=8 cmdata -f traj.xtc -s topol.tpr --mode intra+same
```

If `OMP_NUM_THREADS` is not set, OpenMP defaults to using all available cores. Set it to `1` to force single-threaded execution.

## Output files

Each output file is named `<prefix><type>_<i>_<j>_aa_<ii>.h5` (or `.dat`), where:
Each output file is named `<prefix><type>_<i>_<j>_aa_<ii>.dat` (or `.h5`), where:

- `<type>` is `intra_mol`, `inter_mol`, or `inter_mol_c`
- `<i>`, `<j>` are 1-based molecule-type indices
- `<ii>` is the 1-based atom index within molecule type `i`

- `<type>` is `intra_mol`, `inter_mol`, or `inter_mol_c` (cross)
- `<i>`, `<j>` are zero-based molecule-type indices
- `<ii>` is the atom index within molecule type `i`
Each file contains one column per atom in molecule type `j`. The rows correspond to histogram bins uniformly spaced from `dx/2` to `cutoff`, with `dx = cutoff / n_bins`.

Each file contains one column per atom pair `(ii, jj)`. The rows are histogram bins from `dx/2` to `cutoff` in steps of `dx = cutoff / n_bins`.
For `same` and `cross` modes, two files are written per atom:

For `same` and `cross` modes two files are written per atom: one for the full density histogram and one for the per-molecule maximum-CDF (`maxcdf`).
- `inter_mol_*` — probability density histogram
- `inter_mol_c_*` — per-molecule maximum CDF (used directly by multi-eGO)

## Examples

Compute intra-molecular histograms only, using 8 threads:

```bash
cmdata -f traj.xtc -s topol.tpr --mode intra --num_threads 8 -o output/
OMP_NUM_THREADS=8 cmdata -f traj.xtc -s topol.tpr --mode intra -o output/
```

Compute all three modes with a 1.0 nm cutoff, skipping the first 10 ns:

```bash
cmdata -f traj.xtc -s topol.tpr \
--mode intra+same+cross \
--cutoff 1.0 \
--t_begin 10000 \
--num_threads 4 --mol_threads 4 \
-o run1/
OMP_NUM_THREADS=8 cmdata -f traj.xtc -s topol.tpr \
--mode intra+same+cross \
--cutoff 1.0 \
--t_begin 10000 \
-o run1/
```

Use a per-frame weight file (e.g., from replica-exchange or metadynamics):
Use a per-frame weight file (e.g. from replica-exchange or metadynamics):

```bash
cmdata -f traj.xtc -s topol.tpr --mode intra+same \
--weights weights.dat -o weighted/
OMP_NUM_THREADS=8 cmdata -f traj.xtc -s topol.tpr \
--mode intra+same \
--weights weights.dat \
-o weighted/
```
23 changes: 5 additions & 18 deletions tools/cmdata/main.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@
int main(int argc, const char** argv)
{
std::cout << "################################################" << std::endl;
std::cout << "#################### CMDATA ####################" << std::endl;
std::cout << "################################################" << std::endl;
std::cout << "################## Version 0.1 #################" << std::endl;
std::cout << "#################### cmdata ####################" << std::endl;
std::cout << "################### Multi-eGO ##################" << std::endl;
std::cout << "################## Version 1.0 #################" << std::endl;
std::cout << "################################################\n" << std::endl;

float cutoff = 0.75, mol_cutoff = 6.0;
int nskip = 0, num_threads = 1, mol_threads = -1, dt = 0;
int nskip = 0, dt = 0;
float t_begin = 0.0, t_end = -1.0;
char *p_traj_path = NULL, *p_top_path = NULL, *p_mode = NULL,*p_bkbn_H = NULL, *p_weights_path = NULL;
char *p_out_prefix = NULL;
Expand All @@ -42,8 +42,6 @@ int main(int argc, const char** argv)
{"cutoff", '\0', POPT_ARG_DOUBLE | POPT_ARGFLAG_OPTIONAL, &cutoff, 0, "Cutoff distance", "DOUBLE"},
{"mol_cutoff", '\0', POPT_ARG_DOUBLE | POPT_ARGFLAG_OPTIONAL, &mol_cutoff, 0, "Molecule cutoff distance", "DOUBLE"},
{"nskip", '\0', POPT_ARG_INT | POPT_ARGFLAG_OPTIONAL, &nskip, 0, "Number of frames to skip", "INT"},
{"num_threads", '\0', POPT_ARG_INT | POPT_ARGFLAG_OPTIONAL, &num_threads, 0, "Number of threads", "INT"},
{"mol_threads", '\0', POPT_ARG_INT | POPT_ARGFLAG_OPTIONAL, &mol_threads, 0, "Number of molecule threads", "INT"},
{"mode", '\0', POPT_ARG_STRING | POPT_ARGFLAG_OPTIONAL, &p_mode, 0, "Mode of operation", "STRING"},
{"bkbn_H", '\0', POPT_ARG_STRING | POPT_ARGFLAG_OPTIONAL, &p_bkbn_H, 0, "Extra backbone H name (H and HN are always included)", "STRING"},
{"weights", '\0', POPT_ARG_STRING | POPT_ARGFLAG_OPTIONAL, &p_weights_path, 0, "Weights file", "FILE"},
Expand Down Expand Up @@ -115,17 +113,6 @@ int main(int argc, const char** argv)
}
}
}
if ( num_threads != 1 )
{
std::cerr << "Number of threads is currently unused!" << std::endl;
num_threads = 1;
//return 6;
}
if ( mol_threads != 1 )
{
std::cout << "threads cannot be used currently!" << std::endl;
mol_threads = num_threads;
}
if ( dt < 0 )
{
std::cerr << "Time step must be a positive number!" << std::endl;
Expand Down Expand Up @@ -158,7 +145,7 @@ int main(int argc, const char** argv)
}

cmdata::CMData cmdata(
top_path, traj_path, cutoff, mol_cutoff, nskip, num_threads, mol_threads, dt,
top_path, traj_path, cutoff, mol_cutoff, nskip, dt,
mode, bkbn_H, weights_path, nopbc, t_begin, t_end, h5
);
cmdata.run();
Expand Down
Loading
Loading