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 was cloned. Also add the path of the KPP executable to the PATH environment variable. These commands may be placed in your shell startup file, as shown below.

Important

The git clone command above creates a directory named KPP (uppercase). Make sure that KPP_HOME points to this exact directory name. On case-sensitive Linux filesystems, KPP and kpp are different directories.

If you use bash:

Add these statements to your $HOME/.bashrc file:
export KPP_HOME=$HOME/KPP
export PATH=$PATH:$KPP_HOME/bin
Then apply the settings with:
$ source $HOME/.bashrc

If you use zsh (macOS Catalina and later)

Add these statements to your $HOME/.zshrc file:
export KPP_HOME=$HOME/KPP
export PATH=$PATH:$KPP_HOME/bin
Then apply the settings with:
$ source $HOME/.zshrc
Important

macOS Catalina (2019) and later versions use zsh as the default shell instead of bash. If you are using bash on macOS, source ~/.bash_profile rather than ~/.bashrc, because macOS Terminal opens a login shell by default and login shells do not source ~/.bashrc automatically. The safest approach is to add the following line to your ~/.bash_profile:
[ -f ~/.bashrc ] && source ~/.bashrc

If you use csh or tcsh:

Add these statements to your $HOME/.cshrc file:
setenv KPP_HOME $HOME/KPP
setenv PATH ${PATH}:$KPP_HOME/bin
Then apply the settings with:
$ source $HOME/.cshrc

Test if KPP dependencies are installed

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

gcc

Important

macOS users: please read Force macOS to use the GNU gcc compiler before proceeding.

KPP uses the GNU Compiler Collection (gcc) by default. A version of gcc comes pre-installed with most Linux systems. To test whether gcc is installed, type:

gcc --version

This will display 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 searches for and replaces text in files. To test whether sed is 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 whether bison is installed, type:

which bison

This will print the path to bison on your system.

flex

Important

macOS users: please read Install and configure flex on macOS before proceeding.

The flex (Fast Lexical Analyzer) utility creates a scanner that recognizes the syntax generated by bison. To test whether 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. Use the find command to locate them:

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

This generates output similar to the following. Look for the entry containing 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 containing the flex library file (in this example /usr/lib), define the KPP_FLEX_LIB_DIR environment variable in your shell startup file as shown below.

If you use bash:

Add this code to your ~/.bashrc file:
export KPP_FLEX_LIB_DIR=/usr/lib
export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:${KPP_FLEX_LIB_DIR}"
Then apply the changes with:
$ source ~/.bashrc

If you use zsh:

Add this code to your ~/.zshrc file:
export KPP_FLEX_LIB_DIR=/usr/lib
export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:${KPP_FLEX_LIB_DIR}"
Then apply the changes with:
$ source ~/.zshrc

If you use csh or tcsh:

Add this code to your ~/.cshrc file:
setenv KPP_FLEX_LIB_DIR /usr/lib
setenv LD_LIBRARY_PATH  ${LD_LIBRARY_PATH}:${KPP_FLEX_LIB_DIR}
Then apply the changes with:
$ source ~/.cshrc

KPP will use the path specified by KPP_FLEX_LIB_DIR in the following section.

Build the KPP executable

Change to the KPP/src directory:

cd $KPP_HOME/src

Note

The following make clean and make distclean commands are only necessary if you have previously built KPP and wish to start from a clean state. You can skip them on a fresh clone.

To remove previously-built KPP object files and example output:

make clean

To also remove a previously-built KPP executable:

make distclean

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

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 creates the executable file $KPP_HOME/bin/kpp.

To verify that the KPP executable is accessible, type:

which kpp

The path displayed should match $KPP_HOME/bin/kpp.

Note

This check must be performed after running make. The executable does not exist before the build step completes.

Additional steps for macOS

When installing KPP on a macOS system, some additional configuration steps are necessary. The sections below address each one.

Force macOS to use the GNU gcc compiler

On macOS, the command:

gcc --version

will typically produce 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 installs clang as gcc. Follow the steps below to make your shell use the GNU gcc compiler instead.

1. Install gcc with Homebrew

brew install gcc

2. Determine which version of gcc was installed

ls $(brew --prefix gcc)/bin/ | grep "^gcc-"

You will see output such as:

gcc-13
gcc-ar-13
gcc-nm-13
gcc-ranlib-13

This indicates that gcc version 13 was installed and that the executable is named gcc-13. Your installed version may differ.

Important

The version number returned by the command above may differ from the examples shown here. Always use the actual version number found on your system in the steps that follow.

3. Define compiler settings in your shell startup file

The following code block uses brew --prefix to locate the Homebrew installation directory automatically. This works correctly on both Intel Macs (/usr/local) and Apple Silicon Macs (/opt/homebrew).

If you use bash:

Add the following to your ~/.bashrc (or ~/.bash_profile if you do not have a ~/.bashrc):

#==================================================================
# Compiler settings (macOS)
#
# Detect the gcc version installed by Homebrew and define
# aliases and environment variables accordingly.
# This overrides the Apple clang that macOS installs as gcc.
#==================================================================
_GCC_VER=$(ls "$(brew --prefix gcc)/bin/" \
           | grep '^gcc-[0-9]' \
           | grep -oP '[0-9]+$' \
           | sort -n | tail -1)

if [[ -n "${_GCC_VER}" ]]; then
    alias gcc="gcc-${_GCC_VER}"
    alias g++="g++-${_GCC_VER}"
    alias gfortran="gfortran-${_GCC_VER}"
    export CC="gcc-${_GCC_VER}"
    export CXX="g++-${_GCC_VER}"
    export FC="gfortran-${_GCC_VER}"
    export F77="gfortran-${_GCC_VER}"
fi
unset _GCC_VER

Then apply the changes with:

$ source ~/.bashrc

If you use zsh:

Add the following to your ~/.zshrc:

#==================================================================
# Compiler settings (macOS)
#
# Detect the gcc version installed by Homebrew and define
# aliases and environment variables accordingly.
# This overrides the Apple clang that macOS installs as gcc.
#==================================================================
_GCC_VER=$(ls "$(brew --prefix gcc)/bin/" \
           | grep '^gcc-[0-9]' \
           | grep -oE '[0-9]+$' \
           | sort -n | tail -1)

if [[ -n "${_GCC_VER}" ]]; then
    alias gcc="gcc-${_GCC_VER}"
    alias g++="g++-${_GCC_VER}"
    alias gfortran="gfortran-${_GCC_VER}"
    export CC="gcc-${_GCC_VER}"
    export CXX="g++-${_GCC_VER}"
    export FC="gfortran-${_GCC_VER}"
    export F77="gfortran-${_GCC_VER}"
fi
unset _GCC_VER

Then apply the changes with:

$ source ~/.zshrc

4. Verify that your shell now recognizes the GNU gcc compiler

gcc --version

You should see output similar to:

gcc-13 (Homebrew GCC 13.2.0) 13.2.0
Copyright (C) 2023 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 confirms that your shell is using GNU gcc rather than clang.

Install and configure flex on macOS

If your macOS system does not have the flex library installed, install it with Homebrew:

brew install flex

Unlike Linux package managers, which install the flex library files under /usr/lib/, Homebrew installs them under its own prefix directory.

Define the KPP_FLEX_LIB_DIR environment variable using brew --prefix so that the path is determined automatically regardless of the Homebrew prefix or the installed flex version:

If you use bash:

Add the following to your ~/.bashrc (or ~/.bash_profile):
export KPP_FLEX_LIB_DIR=$(brew --prefix flex)/lib
export DYLD_LIBRARY_PATH="${DYLD_LIBRARY_PATH}:${KPP_FLEX_LIB_DIR}"
Then apply the changes with:
$ source ~/.bashrc

If you use zsh:

Add the following to your ~/.zshrc:

export KPP_FLEX_LIB_DIR=$(brew --prefix flex)/lib
export DYLD_LIBRARY_PATH="${DYLD_LIBRARY_PATH}:${KPP_FLEX_LIB_DIR}"

Then apply the changes with:

$ source ~/.zshrc

Note

macOS uses DYLD_LIBRARY_PATH to locate shared libraries at runtime, not LD_LIBRARY_PATH (which is the Linux equivalent). If you find that DYLD_LIBRARY_PATH is blocked by System Integrity Protection (SIP), you can instead force a hard link:

brew link --force flex

Request maximum stack memory

macOS imposes a hard limit on stack memory of 65532 bytes, which is considerably less than what is available on typical GNU/Linux systems. To ensure that KPP uses the maximum available stack memory, add the following line to your shell startup file:

If you use bash:

Add this code to your ~/.bashrc file:
ulimit -s 65532
Then apply the change with:
$ source ~/.bashrc

If you use zsh:

Add this code to your ~/.zshrc file:
ulimit -s 65532
Then apply the change with:
$ source ~/.zshrc

This stack memory restriction means that KPP cannot parse mechanisms with more than approximately 2000 equations and 1000 species. To account for this, the KPP header file src/gdata.h defines the MAX_EQN and MAX_SPECIES parameters conditionally:

#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 KPP cannot parse your mechanism you can adjust MAX_EQN and MAX_SPECIES in src/gdata.h and then rebuild the KPP executable.

macOS is case-insensitive

Warning

macOS uses a case-insensitive filesystem by default. If your project contains two files whose names differ only in case (for example integrator.F90 and integrator.f90), macOS will treat them as the same file. This can cause build failures and unexpected behaviour when working with version control systems such as Git. Ensure that no two files in your project share a case-insensitive name.