Continuous integration tests

KPP contains several continuous integration (aka C-I) tests. Each C-I test calls KPP to generate source code for a given chemical mechanism, integrator, and target language, and then runs a short “box model” simulation with the generated code. C-I tests help to ensure that new features and updates added to KPP will not break any existing functionality.

C-I tests will run automatically as a GitHub Action when commits are pushed to the KPP Github repository, or when a new pull requests are opened. You may also run the integration tests locally on your own computer.

List of continuous integration tests

Continuous integration tests
C-I test	Language	Model	Integrator	What it tests
`C_rk`	C	small_strato	runge_kutta	Runge-Kutta integrator
`C_rosadj`	C	small_strato	rosenbrock_adj	Rosenbrock discrete adjoint
`C_sd`	C	small_strato	sdirk	SDIRK integrator
`C_sdadj`	C	small_strato	sdirk_adj	SDIRK discrete adjoint
`C_small_strato`	C	small_strato	rosenbrock	Rosenbrock integrator
`F90_feuler`	Fortran90	carbon	feuler	Forward Euler integrator
`F90_graph`	Fortran90	small_strato	rosenbrock	#GRAPH command
`F90_lsode`	Fortran90	small_strato	lsode	LSODE integrator
`F90_mcm`	Fortran90	mcm	rosenbrock	Master Chemical Mechanism
`F90_mcm_h211b`	Fortran90	mcm	rosenbrock_h211b_qssa	Rosenbrock int. w/ H211b time stepping
`F90_radau`	Fortran90	saprc99	radau5	RADAU5 integrator
`F90_rk`	Fortran90	small_strato	runge_kutta	Runge-Kutta integrator
`F90_rkadj`	Fortran90	small_strato	runge_kutta_adj	Runge-Kutta discrete adjoint
`F90_rktlm`	Fortran90	small_strato	runge_kutta_tlm	Runge-Kutta tangent linear model
`F90_ros`	Fortran90	small_strato	rosenbrock	Rosenbrock integrator
`F90_rosadj`	Fortran90	small_strato	rosenbrock_adj	Rosenbrock discrete adjoint
`F90_ros_autoreduce`	Fortran90	saprc99	rosenbrock_autoreduce	Rosenbrock integrator w/ auto-reduction
`F90_rosenbrock`	Fortran90	saprc99	rosenbrock	Rosenbrock integrator
`F90_ros_h211b`	Fortran90	saprc99	rosenbrock_h211b_qssa	Rosenbrock int. w/ H211b time stepping
`F90_ros_passivespc`	Fortran90	small_strato	rosenbrock	Excluding passive species
`F90_ros_split`	Fortran90	small_strato	rosenbrock	#FUNCTION SPLIT
`F90_rostlm`	Fortran90	small_strato	rosenbrock_tlm	Rosenbrock tangent linear model
`F90_ros_upcase`	Fortran90	saprc99	rosenbrock	#UPPERCASEF90 ON
`F90_saprc_2006`	Fortran90	saprcnov	rosenbrock	Rosenbrock integrator
`F90_sd4`	Fortran90	small_strato	sdirk4	Rosenbrock integrator
`F90_sd`	Fortran90	small_strato	sdirk	SDIRK integrator
`F90_sdadj`	Fortran90	small_strato	sdirk_adj	SDIRK discrete adjoint
`F90_sdtlm`	Fortran90	small_strato	sdirk_tlm	SDIRK tangent linear model
`F90_seulex`	Fortran90	saprcnov	seulex	SEULEX integrator
`F90_small_strato`	Fortran90	small_strato	rosenbrock	Rosenbrock integrator
`X_minver`	Fortran90	small_strato	runge_kutta	#MINVERSION command

Notes about C-I tests:

F90_ros_split uses #FUNCTION SPLIT.
F90_ros_upcase uses #UPPERCASEF90 ON.
F90_small_strato is the example from Running KPP with an example stratospheric mechanism.
X_minver tests if the #MINVERSION command works properly.

Each continuous integration test is contained in a subdirectory of $KPP_HOME/ci-tests. In each subdirectory is a KPP definition file (ending in .kpp).

Running continuous integration tests as a GitHub Action

The files needed to run the C-I tests are described below.

run-ci-tests.yml

Path: $KPP_HOME/.github/workflows/run-ci-tests.yml

Description: Configuration file with commands to download KPP, load libraries, and run the C-I tests as a GitHub Action.

C-I tests will run automatically when a commit is pushed to any branch at https://github.com/KineticPreProcessor/KPP, or when a new pull request is opened there. This is the recommended setting, but you can restrict this so that only pushes or pull requests to certain branches will trigger the C-I tests.

ci-testing-script.sh

Path: $KPP_HOME/.ci-pipelines/ci-testing-script.sh

Description: Runs the KPP C-I tests as a GitHub Action, or on a local computer system.

ci-cleanup-script.sh

Path: $KPP_HOME/.ci-pipelines/ci-cleanup-script.sh

Description: Removes compiler-generated files (e.g. *.o, .mod , and .exe) from C-I test folders.

ci-common-defs.sh

Path: $KPP_HOME/.ci-pipelines/ci-common-defs.sh

Description Contains common variable and function definitions needed by ci-testing-script.sh and ci-cleanup-script.sh.

Running continuous integration tests locally

To run the C-I tests on a local computer system, use this command:

$ $KPP_HOME/.ci-pipelines/ci-testing-script.sh | tee ci-tests.log

This will run all C-I tests on your own computer system and pipe the results to a log file. This will easily allow you to check if the results of the C-I tests are identical to C-I tests that were run on a prior commit or pull request.

To remove the files generated by the continuous integration tests, use this command:

$ $KPP_HOME/.ci-pipelines/ci-cleanup-script.sh

If you add new C-I tests, be sure to add the name of the new tests to the variable GENERAL_TESTS in ci-common-defs.sh.