What does that mean ?

---

Hibridon v5.1

Hibridon is a program package to solve the close-coupled equations which occur in the quantum treatment of inelastic atomic and molecular collisions. Gas-phase scattering, photodissociation, collisions of atoms and/or molecules with flat surfaces, and bound states of weakly-bound complexes can be treated

The full documentation is available on https://github.com/hibridon/hibridon/wiki

Changes:

• CHANGELOG

Prerequisites

Required tools:

• CMake >= 3.3
• Fortran compiler with support for fortran 2008 and fpp preprocessing (e.g. GNU Fortran).
• Git (optional)

Required libraries:

• BLAS compatible library (e.g. Netlib BLAS)
• LAPACK compatible library (e.g. Netlib LAPACK)

Build instructions

1. Get Hibridon source code

Using GIT

git clone https://github.com/hibridon/hibridon.git ~/hib_src

This will create a directory ~/hib_src/ which is a clone of https://github.com/hibridon/hibridon.git

Without GIT

• Download Hibridon source code as a zip archive: hibridon-master.zip

• Extract the content of the archive into the directory of your choice, e.g.: ~/hib_src/

2. Create a configuration file for your potential energy surfaces (PESs)

Create the directories that will contain Hibridon build files and store your project configuration file:

mkdir -p ~/hib_build/project/

Create a CMake project configuration file:

touch ~/hib_build/project/CMakeLists.txt

Copy and past the following example into your CMake project configuration file:

# this is a minimal cmake example for creating a hibridon executable with an user-supplied PES
cmake_minimum_required (VERSION 3.3)
project (my_pots)
enable_language (Fortran)

# add hibridon library by specifying the directory in which the source files are
add_subdirectory("/home/myuser/hib_src/" hibridon)

# declare new executables using hibridon's add_hibexe cmake function, where:
#  - the 1st argument is the name of the resulting executable
#  - the 2nd argument is the file path of the user provided potential file
#  - the 3rd argument is the size of the t matrix:
#    - "kmax": for normal cases
#    - "kbig": for special cases (only arn2_big test uses it)

add_hibexe(NH3-H2.exe "/home/myuser/my_pots/pot_nh3h2.F90" "kmax") # NH3-H2

# You can add as many executables as you want by using the add_hibexe function:
#add_hibexe(OH-H2.exe "/home/myuser/my_pots/pot_ohh2.F90" "kmax") # OH-H2
#add_hibexe(He-CO.exe "/home/myuser/my_pots/pot_heco.F90" "kmax") # He-CO

Adapt this example to suit your needs.

WARNING: The tilde ~ character is not exapnded by CMake, you must replace it with the full path to your home directory, e.g. /home/myuser/

3. Configure your project's build

cd ~/hib_build
cmake ./project/

This will automatically find the required libraries and compiler and create a Makefile to build Hibridon.

Useful CMake options and special cases:

• Use a specific compiler

• cd ~/hib_build
  cmake ./project/ -DCMAKE_Fortran_COMPILER=<compiler>

  Where <compiler> is your compiler executable e.g.:

  • gfortran
  • gfortran-8
  • ifort

• Use a specific BLAS/LAPACK library

  cd ~/hib_build
  cmake ./project/ -DBLA_VENDOR=<BLAS_LIB> 

  Where <BLAS_LIB> is your BLAS library e.g.:

  • OpenBLAS
  • Intel10_64lp
  • Apple

  see CMake BLAS/LAPACK VENDORS for a full list of supported libraries

• Enable Hibridon testing

  cd ~/hib_build
  cmake ./project/ -DBUILD_TESTING=ON

• Build in debug mode

  By default, the source files are compiled in "Release" mode. You can build Hibridon in a "Debug" mode that will disable all compiler optimizations and produce debugging symbols table and traceback informations:

  cd ~/hib_build
  cmake ./project/ -DCMAKE_BUILD_TYPE=Debug

• Change the default install prefix By default, the executables will be installed in /usr/local/bin/. You can change this by setting the CMAKE_INSTALL_PREFIX variable:

  cd ~/hib_build
  cmake ./project/ -DCMAKE_INSTALL_PREFIX=<path>

  Where <path> is the path to the directory where you want to install the executables.

4. Make your project

• Make all executables

  make

  The executable files will be put in the current directory (~/hib_build).

• Make a specific executable

    make <executable>

  Where <executable> is one of the executable you defined in the CMakeLists.txt configuration file, e.g.: NH3-H2.exe.

• Install executables in /usr/local/bin/ (Optional)

  You can install all the generatted executables in the <prefix>/bin/ directory by running:

  make install

  By default, <prefix> is set to /usr/local/, which is the standard location for user-installed software on macOS and most Linux distributions.

  Note that this will overwrite any existing executable with the same name in the destination folder.

  The default directory (/usr/local/) can be changed by setting the CMAKE_INSTALL_PREFIX (see previous section).

5. Test Hibridon (Optional)

Hibridon testing must be enabled (see Section 3: Configure your project's build). The following commands need to be executed within the Hibridon build directory (e.g. ~/hib_build/project/hibridon/).

• Run all tests

  ctest

• Run a test suite (group of tests)

  ctest -L <testsuite>

  Where testsuite is the name of the test suite among:

  • coverage (covers most of the source code)
  • quick (runs only quick tests)
  • benchmark (runs long tests for the purpose of measuring hibridon's performance)

• Run tests for only one PES

  ctest -L <label>

  Where <label> is the name of a group of tests associated to one PES.

  The full list of avaible labels can be printed using:

  ctest --print-labels

6. Run your project

Once your executables are created (step 4), you can interactively run hibridon using:

./<executable> -k <kmax>
# or 
./<executable> --kmax <kmax>

Where <kmax> is the maximum number of channels (see Memory Requirements).

You can also run your Hibridon executable using a command file:

./<executable> -k <kmax> < <command file>
# or
./<executable> -k <kmax> -c <command file>
# or
./<executable> -k <kmax> --com <command file>

Where <commands file> is a file containing the input commands you want to execute (see Batch-mode-and-background-execution)

7. One liner example

This one line command configures, builds and tests Hibridon from a directory ~/hib_build containing the source code.

 git clone https://github.com/hibridon/hibridon.git ~/hib_src && mkdir -p ~/hib_build && cmake -DCMAKE_Fortran_COMPILER=gfortran -DBUILD_TESTING=ON -S ~/hib_src/ -B ~/hib_build && cd ~/hib_build/ && make && ctest -L coverage

Please note that this only builds and tests Hibridon library; it doesn't build any user-provided PES.

For code contributors

Performance profiling

To activate profiling, add -DENABLE_PROFILING=ON to the cmake command. This will build and run hibridon with profiling option. When run, each test will additionnaly create a <test_id>_call_graph.pdf file which shows where time was spent during the test.