KPP 3.5.0 release

.ci-pipelines/ci-common-defs.sh

@@ -24,6 +24,7 @@ F90_rosadj
 F90_ros_autoreduce
 F90_rosenbrock
 F90_ros_h211b
+F90_ros_passivespc
 F90_ros_split
 F90_rostlm
 F90_ros_upcase
@@ -59,8 +60,8 @@ function print_compiler_versions() {
 "###########################################################################"
     echo "         KPP CONTINUOUS INTEGRATION TESTS, USING THESE COMPILERS:"
     echo ""
-    gcc --version
-    gfortran --version
+    ${CC} --version
+    ${FC} --version
     echo \
 "###########################################################################"
 }

.gitattributes

@@ -0,0 +1,45 @@
+# KPP .gitattributes file
+#
+# Normalizes line endings for text source files (this codebase has
+# contributions from multiple organizations and platforms going back
+# decades) and marks flex/bison-generated files as generated so they
+# are collapsed by default in GitHub diffs/blame.
+#
+# For info on how .gitattributes rules work, see:
+# https://git-scm.com/docs/gitattributes
+
+# Default: normalize line endings to LF in the repo, let git decide
+# checkout behavior based on the platform.
+* text=auto eol=lf
+
+# Source code
+*.c      text
+*.h      text
+*.f      text
+*.f90    text
+*.F90    text
+*.m      text
+*.kpp    text
+*.eqn    text
+*.spc    text
+*.def    text
+*.l      text
+*.y      text
+Makefile*  text
+*.sh     text eol=lf
+
+# Docs
+*.md     text
+*.rst    text
+
+# Files generated by flex/bison at build time (see src/Makefile) --
+# hide them from GitHub's diff/blame view by default.
+src/lex.yy.c linguist-generated=true
+src/y.tab.c  linguist-generated=true
+src/y.tab.h  linguist-generated=true
+
+# Binary/opaque files: do not attempt line-ending or diff normalization
+*.pdf    -text binary
+*.exe    -text binary
+*.o      -text binary
+*.mod    -text binary

.github/workflows/run-ci-tests.yml

@@ -20,7 +20,7 @@ jobs:
       KPP_FLEX_LIB_DIR: /usr/lib/x86_64-linux-gnu
     strategy:
       matrix:
-        gcc-version: [9, 10, 11, 12, 13]
+        gcc-version: [9, 10, 11, 12, 13, 14, 15, 16]
 
 
     name: Run C-I tests with GCC ${{ matrix.gcc-version }}
@@ -33,6 +33,10 @@ jobs:
 
       - name: Install libraries
         run: |
+          sudo grep -rl 'packages.microsoft.com' /etc/apt/sources.list.d/ | xargs -r sudo rm -f
+          sudo apt update -y
+          sudo apt install -y software-properties-common
+          sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
           sudo apt update -y
           sudo apt install -y flex bison libfl-dev
           sudo apt install -y gcc-${{ matrix.gcc-version }} g++-${{ matrix.gcc-version }} gfortran-${{ matrix.gcc-version }}

.gitignore

@@ -12,6 +12,7 @@
 **/*~
 **/.\#*
 **/\#*
+**/.DS_Store
 
 # Ignore files generated by bison (in src/)
 /src/lex.yy.c
@@ -31,6 +32,9 @@
 /ci-tests/**/*results*
 /ci-tests/**/*.csv
 
+# Ignore byte-compiled emacs lisp files
+/site-lisp/*.elc
+
 # Ignore files generated by KPP (everywhere)
 **/*_Function*
 **/*_Global*
@@ -73,4 +77,4 @@ docs/build/*
 !/util/Makefile*
 
 # ReadTheDocs
-docs/_build/*
+docs/_build/*

.readthedocs.yaml

@@ -14,10 +14,8 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.12"
-    nodejs: "14"
-    rust:   "1.55"
-    golang: "1.17"
+    python: "3.13"
+    nodejs: "24"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

CHANGELOG.md

@@ -12,6 +12,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [3.5.0] - 2026-07-09
+### Added
+- Added function `F90_FunctionBeginNoArgDecl` in `src/code_f90.c` with corresponding function prototypes in `src/code.c` and `src/code.h`
+- Added macro `DefElmO` in `src/code.h`, which writes a scalar F90 variable with the `OPTIONAL` attribute
+- Added code to `src/gen.c` to add `NonPassiveSpc_Count` and `NonPassiveSpc_Indices` to `ROOT_Global` (only for F90)
+- Added code to `src/gen.c` to filter out passive species if the `PassiveSpc_ATOL_Threshold` optioal argument is passed to `ROOT_Initialize` (F90-only)
+- Added GCC 14, 15, and 16 to the list of compilers used to run C-I tests in GitHub Actions
+- Added `F90_ros_passivespc` C-I test to validate filtering out of passive species
+- Added `drv/general_passivespc.f90` driver program, which passes optional `PassiveSpc_ATOL_Threshold` argument to `ROOT_Initialize`
+- Added documentation about excluding passive species to ReadTheDocs
+- Added `.gitattributes`, `CLAUDE.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`
+
+### Changed
+- Updated `Makefile.defs` and `util/Makefile*` to look for the value of `CC` or `FC` from the shell before explicitly setting it
+- Updated documentation about forcing MacOSX to prefer GNU compilers over Clang
+- Updated `Makefile.defs` with robust cross-architecture code
+- Updated the C-I test function `print_compiler_versions` to display the proper compiler info
+- Initialized `Hacc` and `ErrOld` variables to `ZERO` in `int/runge_kutta.c`, to avoid compiler warnings
+- Updated all `int/rosenbrock*.f90` integrators to use `NonPassiveSpc_Count` and `NonPassiveSpc_Indices` to exclude passive species from the error norm calculation
+- Split ReadTheDocs documentation files into smaller files and reorganized folders in `docs/source`
+
+### Fixed
+- Fixed several emacs font-lock issues in `site-lisp/kpp.el`
+- Fixed `src/gen.c` to avoid generating an uninitialized variable compiler warning
+
+### Removed
+- Removed references to unneccessary `azure-cli` and `microsoft-prod` packages in `.github/workflows/run-ci-tests.yml`
+
 ## [3.4.0] - 2026-04-29
 ### Added
 - Added `Rodas3_1` integration method (with updated coefficents by @msl3v) to `rosenbrock_autoreduce.f90`, `rosenbrock.{c,f90,m}`, `rosenbrock_adj.{c,f90}`, `rosenbrock_tlm.f90`

CLAUDE.md

@@ -0,0 +1,153 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repository is
+
+KPP (Kinetic PreProcessor) is a source-code generator (written in C, built
+with flex/bison) for chemical kinetics simulations. Given a chemical
+mechanism description written in the KPP domain-specific language
+(`.kpp`, `.spc`, `.eqn`, `.def` files), the `kpp` executable generates
+standalone simulation code in Fortran90, C, or Matlab: ODE
+function/Jacobian/Hessian evaluation, sparse-matrix data structures, a
+numerical integrator, and a driver program.
+
+KPP itself is not a chemistry solver — it is a compiler whose target
+languages are Fortran90/C/Matlab and whose output is a complete,
+compilable box-model simulation.
+
+## Build
+
+```bash
+export KPP_HOME=/home/bob/repos/KPP3
+export PATH=$PATH:$KPP_HOME/bin
+export KPP_FLEX_LIB_DIR=/usr/lib   # wherever libfl.a/libfl.so lives
+
+cd $KPP_HOME/src
+make clean       # remove *.o (optional, only needed after a prior build)
+make distclean   # also remove bin/kpp (optional)
+make              # builds bin/kpp via gcc + flex + bison
+```
+
+Requires `gcc`, `flex`, `bison`, and `sed` on the PATH. Compiler/flags are
+configured in `src/Makefile.defs` (defaults to `gcc`; honors `CC`/`FC`
+from the shell environment if set). On macOS, `gcc` is aliased to
+`clang` by default — see `docs/source/getting_started/installation.rst`
+for the Homebrew GCC workaround, the flex-library-path workaround, and
+the stack-size (`ulimit -s`) requirement.
+
+`kpp` must be invoked with `KPP_HOME` set, since it looks up
+`$KPP_HOME/models`, `$KPP_HOME/int`, and `$KPP_HOME/drv` by default
+(overridable via `KPP_MODEL`, `KPP_INT`, `KPP_DRV`).
+
+## Running a single mechanism through KPP
+
+```bash
+cd ci-tests/F90_small_strato
+$KPP_HOME/bin/kpp F90_small_strato.kpp
+make -f Makefile_F90_small_strato COMPILER=GFORTRAN
+./F90_small_strato.exe
+```
+
+This generates `<ROOT>_Function.f90`, `<ROOT>_Jacobian*.f90`,
+`<ROOT>_Global.f90`, `<ROOT>_Parameters.f90`, `<ROOT>_Rates.f90`,
+`<ROOT>_Initialize.f90`, `<ROOT>_Integrator.f90`, `<ROOT>_Main.f90`,
+etc., named after the `ROOT` in `#DRIVER`/model name.
+
+## Tests (C-I tests)
+
+There is no unit test framework — correctness is verified end-to-end by
+generating code for real mechanisms, compiling, and running a box-model
+simulation. Requires `bin/kpp` to be built first.
+
+```bash
+# Run the full C-I test suite (all mechanism/integrator/language combos)
+$KPP_HOME/.ci-pipelines/ci-testing-script.sh | tee ci-tests.log
+
+# Remove compiler-generated files from all C-I test folders afterward
+$KPP_HOME/.ci-pipelines/ci-cleanup-script.sh
+```
+
+To run/inspect a single C-I test, see "Running a single mechanism"
+above — each subdirectory of `ci-tests/` is one test, using the naming
+convention `<LANG>_<description>` (e.g. `F90_rosadj`, `C_sd`). The list
+of test directory names to run is maintained in
+`GENERAL_TESTS`/`MCM_1`/`MCM_2`/`MINVERSION_TEST` in
+`.ci-pipelines/ci-common-defs.sh` — new C-I tests must be added there
+or they won't run in CI. GitHub Actions (`.github/workflows/run-ci-tests.yml`)
+runs this same script across a matrix of GCC versions (9–16) on every
+push/PR.
+
+## Documentation
+
+User docs are Sphinx/ReadTheDocs sources under `docs/source/`, built
+from `docs/source/conf.py` (see `.readthedocs.yaml`). When changing
+behavior (new command, new integrator, new output file), update the
+corresponding `.rst` file — `docs/source/input/kpp_commands.rst` for
+`#COMMAND` options, `docs/source/output/` for generated-file formats,
+`docs/source/num_methods/` for integrators.
+
+## Architecture
+
+### Directory roles (each maps to a `KPP_*` search path or a fixed role)
+
+- `src/` — the KPP program itself (C, flex/bison). Builds `bin/kpp`.
+- `bin/` — holds the built `kpp` executable.
+- `models/` — chemical mechanism definitions (`.def`/`.eqn`/`.spc`)
+  usable via `#MODEL`; searched by default, overridable with `KPP_MODEL`.
+- `int/` — integrator (numerical solver) templates, one `.def` +
+  language-specific source (`.f90`/`.c`/`.m`) per integrator, selected
+  via `#INTEGRATOR`; overridable with `KPP_INT`. `int/user_contributed/`
+  holds community-contributed integrators.
+- `drv/` — driver program templates (the `main`/box-model driver),
+  selected via `#DRIVER`; overridable with `KPP_DRV`.
+- `util/` — per-language function templates (Fortran90/C/Matlab
+  variants of the same utility) substituted into generated code.
+- `examples/` — example `.kpp` mechanism files.
+- `ci-tests/` — one subdirectory per C-I test (see Tests above).
+- `.ci-pipelines/` — shell scripts that run/clean the C-I tests.
+- `site-lisp/` — `kpp.el`, an Emacs major mode for KPP files.
+- `docs/` — Sphinx source for the ReadTheDocs user manual.
+
+### How KPP itself works (`src/`)
+
+1. **Scanner/parser** (`scan.l` → `lex.yy.c`, `scan.y` → `y.tab.c`,
+   `scanner.c`, `scanutil.c`): flex/bison-based lexer+parser reads the
+   `.kpp`/`.def`/`.eqn`/`.spc` input language and fills in-memory tables
+   (atom list, species list, stoichiometry matrices, rate expressions,
+   option list), declared in `gdata.h`. `kpp.c` is the driver/`main`.
+2. **Species reordering**: variable vs. fixed species are separated and
+   variable species are reordered with a Markowitz-type algorithm to
+   minimize Jacobian LU fill-in (unless `#REORDER OFF`).
+3. **Expression-tree / code generation core** (`gen.c`, `code.c`,
+   `code.h`): builds a language-independent expression-tree
+   representation of each generated statement (production/destruction
+   terms, Jacobian, Hessian, stoichiometric matrix, etc.) directly from
+   the coefficient matrices — one statement at a time, not one
+   whole-program IR.
+4. **Per-target-language emitters** (`code_f90.c`, `code_c.c`,
+   `code_f77.c` [deprecated], `code_matlab.c`): each expression tree is
+   rendered into valid syntax for the selected `#LANGUAGE`, then
+   line-wrapped for readability.
+5. Driver/integrator/util *template* files (in `drv/`, `int/`, `util/`)
+   are passed through a substitution preprocessor (symbol substitution,
+   not full macro expansion) rather than being generated from scratch.
+
+Adding a new `#COMMAND` touches `scan.h`, `scan.l`, `scan.y`,
+`scanner.c` in `src/`, plus a new C-I test and new `.rst` docs and
+`site-lisp/kpp.el` — see
+`docs/source/tech_info/adding_new_commands.rst` for the exact checklist.
+
+### Versioning
+
+The version string (`X.Y.Z`, semver, checked against `#MINVERSION` in
+mechanism files) must be kept in sync in four places whenever it
+changes: `src/gdata.h` (`KPP_VERSION`), `CHANGELOG.md`,
+`docs/source/conf.py` (`release`), and the KPP Wikipedia page.
+
+### macOS-specific constraint
+
+macOS's default 64KB stack limit means `MAX_EQN`/`MAX_SPECIES` in
+`src/gdata.h` are conditionally compiled smaller on macOS (`#ifdef
+MACOS`) than on Linux; if a mechanism is too large to parse, these
+constants (and possibly `ulimit -s`) need adjusting.

CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation
+in our community a harassment-free experience for everyone, regardless
+of age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open,
+welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for
+our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our
+  mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or
+  political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in
+  a professional setting
+
+## Enforcement Responsibilities
+
+The KPP development team (listed in [`AUTHORS.txt`](AUTHORS.txt)) is
+responsible for clarifying and enforcing our standards of acceptable
+behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening,
+offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces (GitHub
+issues, pull requests, and discussions in this repository), and also
+applies when an individual is officially representing the community in
+public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may
+be reported to the KPP development team by opening a private report
+through the "Report content" option on the relevant GitHub issue,
+pull request, or comment, or by contacting a maintainer listed in
+[`AUTHORS.txt`](AUTHORS.txt) directly.
+
+All complaints will be reviewed and investigated promptly and fairly.
+All community leaders are obligated to respect the privacy and security
+of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html