Installation Guide

This guide covers the installation of OpenThermo on various platforms including Linux, macOS, and Windows.

System Requirements

Minimum Requirements:

  • Operating System: Linux, macOS 10.14+, or Windows 10+

  • Processor: x86_64 architecture

  • Memory: 512 MB RAM (2 GB recommended)

  • Storage: 50 MB free space

Recommended Requirements:

  • Operating System: Linux (Ubuntu 18.04+, CentOS 7+, Fedora 28+)

  • Compiler: Clang 6.0+, GCC 7.0+, or Intel C++ Compiler 18.0+

  • Memory: 2 GB+ RAM for large systems

  • Storage: 100 MB+ for processing large output files

Supported Compilers

OpenThermo supports multiple C++17 compilers:

  • Clang: 6.0+ (recommended)

  • GCC: 7.0+ (alternative)

  • Intel C++ Compiler: 18.0+ (alternative)

  • MSVC: 2017+ (Windows)

Note

Clang is the primary compiler used for development and testing.

Build Dependencies

Required:

  • GNU Make: 3.8.1+ (build system, tested)

  • CMake: 3.26.5+ (alternative build system, tested)

  • Standard Library: C++17 standard library

Optional:

  • Doxygen: 1.8+ (documentation generation)

  • Graphviz: For documentation diagrams

  • Python: 3.6+ (for test automation scripts)

  • OpenMP: For parallel computation support

Installation Methods

Quick Start Build

1. Clone or download the repository:

git clone https://github.com/lenhanpham/OpenThermo.git
cd OpenThermo

2. Build with Make (recommended):

make clean && make

3. Alternative CMake build:

mkdir build && cd build
cmake ..
make

GNU Make Build System

Standard Build:

# Standard optimized build
make

# Build with OpenMP parallelization
make OPENMP=1

# Debug build with AddressSanitizer
make debug

# Release build with maximum optimization
make release

# Force specific compiler
make CXX=g++      # GCC
make CXX=clang++  # Clang
make CXX=icpc     # Intel

# Clean build artifacts
make clean

Build Targets:

  • all (default): Standard optimized build

  • debug: Includes debug symbols and AddressSanitizer

  • release: Maximum optimization for production use

  • tsan: ThreadSanitizer build for detecting data races (use with OPENMP=1)

  • clean: Remove all build artifacts

  • test: Run the regression test suite

  • test-generate: Regenerate reference values from current build

CMake Build System

Standard CMake Build:

# Create build directory
mkdir build && cd build

# Configure and build
cmake ..
make

# Build with OpenMP parallelization
cmake .. -DENABLE_OPENMP=ON
make

Advanced CMake Options:

# Build types
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake .. -DCMAKE_BUILD_TYPE=Debug

# Specify compiler
cmake .. -DCMAKE_CXX_COMPILER=clang++

Windows Build (MSYS2/MinGW)

Note

For Windows Users, there is a binary package in the Releases. Download this package and unzip it for further installation instructions.

For those who would like to compile OpenThermo from source code on Windows:

1. Install MSYS2:

Download and install MSYS2 and open a MINGW64 terminal.

2. Install dependencies:

pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-clang mingw-w64-x86_64-cmake mingw-w64-x86_64-make

3. Build:

make

The Makefile auto-detects Windows and adds -static linking so the binary runs without MinGW DLLs.

Post-Build Setup

Add OpenThermo to PATH

Linux/macOS:

Add the following line to your shell configuration file (~/.bashrc, ~/.zshrc, or equivalent), replacing /path/to/OpenThermo with the actual path to the directory containing the OpenThermo binary (e.g. the repo root or build/):

export PATH=$PATH:/path/to/OpenThermo

Then reload your shell:

source ~/.bashrc   # or source ~/.zshrc

Windows:

  1. Open Settings → System → Advanced system settings → Environment Variables

  2. Add the directory containing OpenThermo.exe to the Path variable

  3. Open a new Command Prompt and test:

    OpenThermo --help

Verification

1. Verify executable:

OpenThermo --help

2. Create settings file (optional):

OpenThermo --create-config

This creates settings.ini with all available parameters and their default values.

3. Test installation:

# Run a test calculation (if test files are available)
OpenThermo test_molecule.log

Successful Compilation Output

Expected output during compilation:

Using compiler: g++
g++ -std=c++17 -Wall -Wextra -O2 -c main.cpp -o build/main.o
g++ -std=c++17 -Wall -Wextra -O2 -c atommass.cpp -o build/atommass.o
...
g++ build/main.o ... -o OpenThermo -lrt -lstdc++fs

Environment Setup

Note

After adding OpenThermo to PATH (see Post-Build Setup above), you can call OpenThermo directly from any directory without specifying its full path.

Troubleshooting

Common Build Issues

Compiler Not Found:

# Check available compilers
which g++ clang++ icpc

# Install missing compiler
sudo apt install g++-10  # Ubuntu/Debian
sudo yum install gcc-c++  # CentOS/RHEL

C++17 Support Missing:

# Check compiler version
g++ --version

# Upgrade compiler if needed
sudo apt install g++-10
sudo update-alternatives --config g++

Library Issues:

# Check for required libraries
ldconfig -p | grep stdc++

# Rebuild if libraries are missing
make clean && make

Permission Issues:

# Fix permissions
chmod +x build/OpenThermo

OpenMP Issues:

If OpenMP is not found during build:

# Install OpenMP development libraries
sudo apt install libomp-dev  # Ubuntu/Debian
sudo yum install libgomp    # CentOS/RHEL

Runtime Issues

File Not Found:

# Check file path and spelling
ls -la molecule.log

# Ensure file is in current directory or provide full path
OpenThermo /full/path/to/molecule.log

Unrecognized Program Format:

Ensure the input file contains frequency analysis output from a supported quantum chemistry program.

Invalid Arguments:

# Check argument syntax
OpenThermo --help-T

# Use proper format for temperature scan
OpenThermo molecule.log -T 200 400 25

Performance Optimization

Compiler Selection:

  • Clang: Recommended for best compatibility

  • GCC: Good general performance

  • Intel: Best performance on Intel systems

Build Optimization:

# Release build with full optimization
make release -j $(nproc)

# Use all available cores for compilation
make -j $(nproc)

OpenMP Parallelization:

# Build with OpenMP support
make OPENMP=1

# Or with CMake
cmake .. -DENABLE_OPENMP=ON
make

Runtime Optimization:

OpenThermo automatically uses half of detected physical CPU cores by default. For dedicated compute nodes:

# Use explicit thread count
OpenThermo molecule.log -omp-threads 8

Testing

Run Test Suite:

# Run the full test suite
make test

# Run with verbose output
python3 tests/run_tests.py --verbose

# Run a single test by ID
python3 tests/run_tests.py --test gaussian_h2co_freq

Regenerate Reference Values:

After modifying calculation logic:

make test-generate

This runs OpenThermo on all test inputs and writes the results to tests/reference_values.json.

Uninstallation

Source Installation:

# Remove build artifacts
make clean

# Remove binary
rm build/OpenThermo

# Remove settings file (if created)
rm settings.ini

Getting Help

If you encounter issues:

  1. Check the Usage Guide guide for proper usage

  2. Use OpenThermo --help for command-line help

  3. Check system requirements and compiler compatibility

  4. Report issues on GitHub with system information

# Get version information
OpenThermo --help

# Check compiler information
make compiler-info