Installation Guide - the-user-created/FERS GitHub Wiki

Installation Guide

(Instructions on how to build and install FERS)

This guide provides instructions for installing FERS on Ubuntu/Linux systems. FERS can also be run on Windows 10/11 using Windows Subsystem for Linux (WSL), but this is not an officially supported or tested configuration.

Prerequisites

A C++20/23 compatible compiler (e.g., GCC 10+ or Clang 12+).
CMake (version 3.16 or higher).
Git.

Dependencies

FERS relies on the following libraries:

HighFive (included as a git submodule for HDF5 integration)
libhdf5-dev / libhdf5-serial-dev (HDF5 C library)
libxml2-dev (XML C library)
python3.11-dev and python3.11-venv (for Python scripting capabilities and virtual environments)

Note: The Boost library has been completely removed, and FFTW3 is no longer required. Python version is strictly limited to 3.7.0 - 3.11.12 due to external integration factors. We recommend Python 3.11 for new setups.

Installation Steps on Ubuntu/Linux

Update System Packages: Open a terminal and update your system's package list:
```
sudo apt-get update && sudo apt-get upgrade -y
```
Install Dependencies: Install the required libraries:
```
sudo apt-get install -y build-essential cmake libhdf5-dev libhdf5-serial-dev libxml2-dev python3.11 python3.11-dev python3.11-venv
```
Optionally, install the CMake GUI for easier configuration:
```
sudo apt-get install -y cmake-qt-gui
```
Note on Python 3.11: If you encounter issues installing python3.11 via apt-get (e.g., on older Ubuntu versions), you may need to use the deadsnakes PPA:
```
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install -y python3.11 python3.11-dev python3.11-venv
```
If using a custom Python installation or the PPA, you might need to specify the Python executable path to CMake: -D PYTHON_EXECUTABLE=/usr/bin/python3.11
Clone the Repository: Clone the FERS repository and initialize its submodules (for HighFive):
```
git clone --recursive https://github.com/the-user-created/FERS.git
cd FERS
```
Build FERS: Create a build directory, configure the project using CMake, and compile:
```
mkdir build && cd build
cmake ..
make -j$(nproc)
```
The compiled fers binary will be located in the build/src/ directory.
- Debug Build (Optional): To create a debug build (e.g., for development or troubleshooting), use a separate build directory:
```
cd .. # Go back to FERS root
mkdir build-debug && cd build-debug
cmake -DCMAKE_BUILD_TYPE=Debug ..
make -j$(nproc)
```
Install FERS (Optional): To install FERS system-wide (this will typically install the binary to /usr/local/bin and libraries to /usr/local/lib):
```
cd ../build # Or your chosen build directory
sudo make install
sudo ldconfig # Updates the shared library cache
```
After this, you should be able to run fers from any terminal location.

Advanced Installation Notes

HDF5 Library Linking Issues (Ubuntu 15+ or specific systems): If CMake has trouble finding the HDF5 libraries, or if you have multiple versions installed, you might need to specify their paths manually.

# Example for typical serial HDF5 paths on Ubuntu
cmake -D FERS_LIB_HDF5="/usr/lib/x86_64-linux-gnu/hdf5/serial/libhdf5.so" \
      -D FERS_LIB_HDF5_HL="/usr/lib/x86_64-linux-gnu/hdf5/serial/libhdf5_hl.so" \
      -D CMAKE_CXX_FLAGS="-I/usr/include/hdf5/serial/" ..
make -j$(nproc)

You can also use cmake-qt-gui to browse and set these paths.

Running Regression Tests

After building FERS (preferably the Release version in a directory named build relative to the project root), you can run the regression test suite:

cd FERS # Navigate to the root directory of the FERS repository
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt # Installs numpy and other dependencies for testing
python3 run_sim_tests.py
deactivate # Optional: exit the virtual environment

This script will execute all test cases in test/sim_tests/ and compare their outputs against expected results.