Installation Guide¶

This guide covers the installation of Gaussian Extractor on various platforms including Linux, Windows, and cluster environments.

System Requirements¶

Minimum Requirements:

Operating System: Linux, Windows 10+, or macOS (not tested)
Compiler: C++20 compatible compiler
Memory: 2GB RAM minimum, 8GB recommended
Storage: 100MB for installation

Recommended Requirements:

Operating System: Linux (Ubuntu 20.04+, CentOS 7+, RHEL 8+)
Compiler: GCC 10+, Intel oneAPI, or Clang 10+
Memory: 16GB+ RAM for large datasets
Storage: 1GB+ for processing large log files

Supported Compilers¶

Gaussian Extractor supports multiple C++20 compilers:

GCC: 10.0+ (recommended for Linux)
Intel oneAPI: icpx/icpc (recommended for clusters)
Intel Classic: icpc (legacy support)
Clang: 10.0+ (alternative Linux compiler)
MSVC: 2019+ (Windows)

Note

Intel compilers provide the best performance on Intel-based cluster systems.

Installation Methods¶

Windows Users:

Pre-compiled Binary (Easiest)¶

Download the latest release from GitHub
Extract the ZIP file to your desired location
Add the bin directory to your system PATH

Test installation:

gaussian_extractor.x --version

double-click gaussian_extractor.x to run interactive mode

Linux/macOS Users:

Build from Source)¶

Prerequisites¶

Ubuntu/Debian:

sudo apt update
sudo apt install build-essential cmake git
# Optional: Install additional compilers
sudo apt install gcc-10 g++-10 clang-10

CentOS/RHEL:

sudo yum groupinstall "Development Tools"
sudo yum install cmake git
# For newer GCC versions, consider SCL:
sudo yum install centos-release-scl
sudo yum install devtoolset-10-gcc devtoolset-10-gcc-c++

macOS (Limited Support):

# Install Xcode command line tools
xcode-select --install
# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install cmake gcc

Automatic Build (Recommended)¶

Basic Build:

# Clone the repository
git clone https://github.com/lenhanpham/gaussian-extractor.git
cd gaussian-extractor

# Build with auto-detected compiler
make -j $(nproc)

# The binary will be created as gaussian_extractor.x

Build Variants:

# Cluster-optimized build
make cluster -j $(nproc)

# Debug build with additional safety checks
make debug -j $(nproc)

# High-performance release build
make release -j $(nproc)

Force Specific Compiler:

# Intel oneAPI compiler (recommended for clusters)
CXX=icpx make -j $(nproc)

# Intel Classic compiler
CXX=icpc make -j $(nproc)

# GNU compiler
CXX=g++ make -j $(nproc)

CMake Build (Cross-platform)¶

Standard CMake Build:

# Create build directory
mkdir build && cd build

# Configure with auto-detected compiler
cmake ..

# Build
cmake --build . -j $(nproc)

# Optional: Install system-wide
sudo make install

Advanced CMake Options:

# Specify compiler explicitly
CXX=icpx cmake -DCMAKE_BUILD_TYPE=Release ..

# Enable additional debugging
cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_DEBUG=ON ..

# Custom installation directory
cmake -DCMAKE_INSTALL_PREFIX=/opt/gaussian_extractor ..

Cluster Installation¶

Load Required Modules:

# Load Intel compilers and TBB
module load intel-compiler-llvm
module load intel-tbb

# Alternative: Load GCC
module load gcc

Build for Cluster:

# Use cluster-optimized build
make cluster -j 8

# Or with CMake
mkdir build && cd build
CXX=icpx cmake ..
make -j 8

Intel TBB Library Setup:

If using Intel compilers, ensure TBB library is available:

# Check if TBB is loaded
echo $TBBROOT

# If not loaded, add to LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$TBBROOT/lib:$LD_LIBRARY_PATH

# Make permanent in your shell profile
echo 'export LD_LIBRARY_PATH=$TBBROOT/lib:$LD_LIBRARY_PATH' >> ~/.bashrc

Post-Installation Setup¶

Configuration File¶

Create a default configuration file:

# Generate default configuration
gaussian_extractor.x --create-config

# This creates ~/.gaussian_extractor.conf
# Edit this file to set your preferred defaults

Environment Setup¶

Linux/macOS:

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH=$PATH:/path/to/gaussian_extractor

# Optional: Create alias
alias gx='gaussian_extractor.x'

Windows:

Open System Properties → Advanced → Environment Variables
Add the Gaussian Extractor directory to PATH
Open new Command Prompt and test:
```
gaussian_extractor.x --version
```

Verification¶

Test your installation:

# Check version
gaussian_extractor.x --version

# Show help
gaussian_extractor.x --help

# Show system resource information
gaussian_extractor.x --resource-info

# Test with sample data (if available)
gaussian_extractor.x

Troubleshooting¶

Common Build Issues¶

Compiler Not Found:

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

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

C++20 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 gaussian_extractor.x

# Install to user directory if system install fails
make install-user

Runtime Issues¶

Memory Errors:

# Reduce thread count
gaussian_extractor.x -nt 2

# Set explicit memory limit
gaussian_extractor.x --memory-limit 4096

File Permission Issues:

# Check file permissions
ls -la *.log

# Fix permissions if needed
chmod 644 *.log

Library Path Issues (Intel TBB):

# Check TBB library path
echo $LD_LIBRARY_PATH

# Add TBB path
export LD_LIBRARY_PATH=/opt/intel/tbb/lib:$LD_LIBRARY_PATH

Cluster-Specific Issues¶

SLURM Environment:

# Check available modules
module avail

# Load appropriate compiler
module load intel-compiler-llvm
module load intel-tbb

PBS/Torque:

# Load modules
module load gcc
module load cmake

SGE/Grid Engine:

# Load environment
module load gcc
module load cmake

Performance Optimization¶

Compiler Selection:

Intel oneAPI (icpx): Best performance on Intel systems
GCC 10+: Good general performance
Clang: Alternative with good optimization

Build Optimization:

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

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

Runtime Optimization:

# Use optimal thread count
gaussian_extractor.x -nt half

# For large files, increase memory limit
gaussian_extractor.x --max-file-size 500

Uninstallation¶

Binary Installation:

# Remove binary
rm /usr/local/bin/gaussian_extractor.x

# Remove configuration
rm ~/.gaussian_extractor.conf

Source Installation:

# From build directory
make uninstall

# Or manually remove files
rm -rf /usr/local/bin/gaussian_extractor.x
rm -rf /usr/local/share/gaussian_extractor

Getting Help¶

If you encounter issues:

Check the Usage Guide guide for proper usage
Use gaussian_extractor.x --help for command-line help
Check system requirements and compiler compatibility
Report issues on GitHub with system information

# Get detailed system information
gaussian_extractor.x --resource-info

# Check compiler information
make compiler-info