Installation

This section can be skipped if KPP is already installed on your system.

Download KPP from Github

Clone the KPP source code from the KPP Github repository:

$ cd $HOME
$ git clone https://github.com/KineticPreProcessor/KPP.git

This will create a directory named KPP in your home directory.

Define the KPP_HOME environment variable

Define the $KPP_HOME environment variable to point to the complete path where KPP is installed. Also, add the path of the KPP executable to the $PATH environment variable.

If you are using the Unix C-shell (aka csh), add add these statements to your $HOME/.cshrc file:

setenv KPP_HOME $HOME/kpp
setenv PATH ${PATH}:$KPP_HOME/bin

and then apply the settings with:

$ source $HOME/.cshrc

If, on the other hand, you are using the Unix bash shell, add these statements to your $HOME/.bashrc file:

export KPP_HOME=$HOME/kpp
export PATH=$PATH:$KPP_HOME/bin

and then apply the settings with:

$ source $HOME/.bashrc

Now if you type:

$ which kpp

the path to the executable file (kpp) will be displayed. This path should match the path specified by $KPP_HOME/bin/kpp.

Test if KPP dependencies are installed on your system

KPP depends on several other Unix packages. Before using KPP for the first time, test if these are installed on your system. If any of these packages are missing, you can install them with your system’s package manager (e.g. apt for Ubuntu, yum for Fedora, homebrew for MacOS, etc.), or with Spack.

gcc

Important

You might have to follow some additional configuration and installation steps regarding gcc on MacOS X systems.

KPP uses the GNU Compiler Collection (aka gcc) by default. A version of gcc comes pre-installed with most Linux or MacOS systems. To test if gcc is installed on your system, type:

$ gcc --version

This will display the version information, such as:

gcc (GCC) 11.2.0
Copyright (C) 2021 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

sed

The sed utility is used to search for and replace text in files. To test if sed has been installed, type:

$ which sed

This will print the path to sed on your system.

bison

The bison utility parses the chemical mechanism file into a computer-readable syntax. To test bison is installed, type:

$ which bison

This will print the path to bison on your system.

flex

Important

You might have to follow some additional configuration and installation steps regarding flex on MacOS X systems.

The flex (the Fast Lexical Analyzer) creates a scanner that can recognize the syntax generated by bison. To test if flex is installed, type:

$ which flex

This will print the path to flex on your system.

You will also need to specify the path to the flex library files (libfl.so or libfl.a) in order to build the KPP executable. This can be done with the find command:

$ find /usr/ -name "*libfl*" -print

This will generate a list of file paths such as shown below. Look for the text libfl.:

/usr/include/libflashrom.h
/usr/lib/gthumb/extensions/libflicker.so
/usr/lib/gthumb/extensions/libflicker_utils.so
/usr/lib/libflashrom.so.1.0.0
/usr/lib/libfl.so                # <---- This is the flex library file
# ... etc ...

Once you have located the directory where flex library file resides (which in this example is /usr/lib), use it to define the KPP_FLEX_LIB_DIR environment variable in your .bashrc (or .bash_aliases file if you have one):

export KPP_FLEX_LIB_DIR=/usr/lib

And then apply the changes with:

. ~/.bashrc

KPP will use the path specified by KPP_FLEX_LIB_DIR during the compilation sequence (described in the next section).

Build the KPP executable

Change to the KPP/src directory:

$ cd $KPP_HOME/src

To clean a previously-built KPP installation, delete the KPP object files and all the examples with:

$ make clean

To delete a previoulsy-built KPP executable as well, type:

$ make distclean

KPP will use gcc as the default compiler. If you would like to use a different compiler (e.g. icc), then edit src/Makefile.defs to add your compiler name.

Create the KPP executable with:

$ make

You should see output similar to:

gcc -g -Wall -Wno-unused-function -I/usr/include -c code.c
gcc -g -Wall -Wno-unused-function -I/usr/include -c code_c.c
gcc -g -Wall -Wno-unused-function -I/usr/include -c code_f77.c
gcc -g -Wall -Wno-unused-function -I/usr/include -c code_f90.c
gcc -g -Wall -Wno-unused-function -I/usr/include -c code_matlab.c
gcc -g -Wall -Wno-unused-function -I/usr/include -c debug.c
gcc -g -Wall -Wno-unused-function -I/usr/include -c gen.c
gcc -g -Wall -Wno-unused-function -I/usr/include -c kpp.c
flex -olex.yy.c scan.l
bison -d -o y.tab.c scan.y
gcc -g -Wall -Wno-unused-function -I/usr/include -c lex.yy.c
gcc -g -Wall -Wno-unused-function -I/usr/include -c scanner.c
gcc -g -Wall -Wno-unused-function -I/usr/include -c scanutil.c
gcc -g -Wall -Wno-unused-function -I/usr/include -c y.tab.c
gcc -g -Wall -Wno-unused-function code.o code_c.o
    code_f77.o code_f90.o code_matlab.o debug.o gen.o kpp.o
    lex.yy.o scanner.o scanutil.o y.tab.o -L/usr/lib -lfl -o kpp

This will create the executable file $KPP_HOME/bin/kpp.

Instructions for MacOS X users

When installing KPP on a MacOS X system, some additional configuration and installation steps may be necessary.

Force MacOS to recognize the gcc compiler

On MacOS X, if you type:

$ gcc --version

you will probably see output similar to:

Apple clang version 13.1.6 (clang-1316.0.21.2.5)
Target: x86_64-apple-darwin21.5.0
Thread model: posix
InstalledDir: /Library/Developer/CommandLineTools/usr/bin

This is because MacOS X installs clang as gcc. To force MacOS X to recognize the gcc compiler, follow these steps:

  1. Use the homebrew package manager to install gcc:

    $ brew install gcc

  2. Type this command:

    $ ls /usr/local/Cellar/gcc/*/bin/ | grep gcc

    You should see output such as:

    gcc-11*
gcc-ar-11*
gcc-nm-11*
gcc-ranlib-11*
# ... etc ...

    This output indicates gcc major version 11 has been installed, and that the gcc executable is called gcc-11. (Your version may differ.)

  3. Add the following code block to your .bashrc file (or to your .bash_aliases file if you have one). This will define aliases that will override clang with gcc.

    #============================================================================
# Compiler settings (MacOS)
#
# NOTE: MacOSX installs Clang as /usr/bin/gcc, so we have to manually
# force reference to gcc-11, g++-11, and gfortran-11, which HomeBrew
# installs to /usr/local/bin.  (bmy, 10/28/21)
#============================================================================
alias gcc=gcc-11
alias g++=g++-11
alias gfortran=gfortran-11
export CC=gcc
export CXX=g++-11
export FC=gfortran-11
export F77=gfortran-11

    Then apply the changes with:

    $ . ~/.bashrc

  4. To check if your shell now recognizes the gcc compiler, type:

    $ gcc --version

    You should see output similar to:

    gcc-11 (Homebrew GCC 11.3.0_1) 11.3.0
Copyright (C) 2021 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

    This now indicates that your compiler is gcc and not clang.

Install flex with homebrew

If your MacOS X computer does not have the flex library installed, then you can install it with homebrew:

$ brew install flex

Unlike Linux pacakge managers, which would install the flex library files in the path /usr/lib/, homebrew will install it to a path such as /usr/local/Cellar/flex/X.Y.Z/lib/.

To find the version of flex that has been installed by homebrew, type:

$ ls /usr/local/Cellar/flex

and you will get a listing such as:

2.6.4_2

This indicates that the version of flex on your system is 2.6.4_2 (the _2 denotes the number of bug-fix updates since version 2.6.4 was released).

The flex library files (libfl.so or libfl.a) will be found in lib/ subfolder. In this example, the path will be:

/usr/local/Cellar/flex/2.6.4_2/lib

Knowing this, you can now define the KPP_FLEX_LIB_DIR environment variable as described above:

export FLEX_LIB_DIR=/usr/local/Cellar/flex/2.6.4_2/lib

Request maximum stack memory

MacOS X has a hard limit of 65332 bytes for stack memory. This is much less memory than what is available on GNU/Linux operating systems such as Ubuntu, Fedora, etc.

To make sure you are using the maximum amount of stack memory on MacOS X add this command to your .bashrc file:

ulimit -s 65532

and then apply the change with:

$ . ~/.bashrc

This stack memory limit means that KPP will not be able to parse mechanisms with more than about 2000 equations and 1000 species. Because of this, we have added an #ifdef block to KPP header file src/gdata.h to define the MAX_EQN and MAX_SPECIES parameters accordingly:

#ifdef MACOS
#define MAX_EQN        2000     // Max number of equations (MacOS only)
#define MAX_SPECIES    1000     // Max number of species   (MacOS only)
#else
#define MAX_EQN       11000     // Max number of equations
#define MAX_SPECIES    6000     // Max number of species
#endif

If you find that KPP will not parse your mechanism, you can increase MAX_EQN and decrease MAX_SPECIES (or vice-versa) as needed, and then rebuild the KPP executable.

Know that MacOS X is case-insenstive

If you have two files with identical names except for case (e.g. integrator.F90 and integrator.f90) then MacOS X will not be able to tell them apart. Because of this, you may encounter an error if you try to commit such files into Git, etc.