KineticPreProcessor · yantosca · Jun 13, 2024 · Jun 14, 2024 · Jul 11, 2024 · Jul 17, 2024
diff --git a/.ci-pipelines/ci-common-defs.sh b/.ci-pipelines/ci-common-defs.sh
@@ -46,6 +46,18 @@ function get_ci_test_path() {
     return
 }
 
+# Prints a header with the compiler versions
+function print_compiler_versions() {
+    echo \
+"###########################################################################"
+    echo "         KPP CONTINUOUS INTEGRATION TESTS, USING THESE COMPILERS:"
+    echo ""
+    gcc --version
+    gfortran --version
+    echo \
+"###########################################################################"
+}
+
 # Run a C-I test
 function run_ci_test() {
 

diff --git a/.ci-pipelines/ci-testing-script.sh b/.ci-pipelines/ci-testing-script.sh
@@ -10,6 +10,9 @@
 # Current directory
 cwd=$(pwd -P)
 
+# Print a header with the compiler versions
+print_compiler_versions
+
 # Run C-I tests with various mechanism + integrator combinations
 for this_test in ${GENERAL_TESTS}; do
     run_ci_test "${this_test}" "${cwd}" ""

diff --git a/.gitignore b/.gitignore
@@ -15,6 +15,7 @@
 # from compiler:
 *.mod
 *.o
+*.exe
 
 # results from ci-tests:
 /ci-tests/**/*.m
@@ -67,5 +68,5 @@ docs/build/*
 
 # Other files/dirs to exclude
 *.pdf
-/examples/mcm/__pycache__
+/examples/mcm*/__pycache__
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,36 @@ All notable changes to this project will be documented in this file.
 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.2.0] - 2025-02-27
+### Added
+- Added new inline key `F90_RCONST_USE` in `src/gdata.h` and `src/scanner.c`
+- Added documentation about `F90_RCONST_USE` for ReadTheDocs
+- Added `F90_RCONST_USE` inlined code to `Update_RConst`and `Update_Photo` routines
+- Added warning that LSODE is not thread-safe to ReadTheDocs documentation
+
+### Changed
+- Updated `Update_RCONST` to use `Y` instead of `C` to account for updated variable species concentrations
+- Updated C-I tests to print the compiler versions that are used
+- Updated routine `GenerateUpdateRconst` to manually write the `SUBROUTINE` and `END SUBROUTINE` lines (F90 only)
+- Updated routine `GenerateUpdateRconst` to inline code from `#INLINE F90_RCONST_USE` before any other F90 variable declarations or statements
+- Updated `.gitignore` to ignore all executable files
+- Changed `Begin INLINED RCONST - F90 USE STATEMENTS` to `Begin inlined code from F90_RCONST_USE` in `src/gen.c`
+- Changed inlined code comments to be more precise (e.g. `Begin inlined code from F90_RCONST`) in `src/gen.c`
+- Updated Flex library installation example on ReadTheDocs
+- Renamed `int/beuler.f90` to the `int/sdirk.f90`, as this is a newer version of the SDIRK integrator
+- Updated documentation for Backwards Euler to instruct user to select `#INTEGRATOR sdirk` with `ICNTRL(3) = 6`
+- Updated ReadTheDocs dependency`jinja2` to version 3.1.5 (fixes a security issue)
+
+### Fixed
+- Added `char* rootFileName` to functions and function prototypes for `Use_C`, `Use_F`, `Use_F90`, `Use_MATLAB`, and `Generate`
+- Updated `docs/requirements.txt` to use `jinja2==3.1.4` (fixes a security issue)
+- Moved `USE constants_mcm` from `F90_RCONST` to `F90_RCONST_USE` in `examples/mcm/mcm_isoprene.eqn`
+- Fixed MacOS-specific handling for x86_64 or arm64 in `src/Makefile.defs`
+
+### Removed
+- Removed `int/beuler.f90`
+- Removed `int/beuler.def`
+
 ## [3.1.1] - 2024-04-30
 ### Changed
 - Updated Python package versions for ReadTheDocs in `docs/requirements.txt`

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -12,4 +12,4 @@ sphinxcontrib-bibtex==2.6.2
 sphinx-autobuild==2021.3.14
 recommonmark==0.7.1
 docutils==0.20.1
-jinja2==3.1.3
+jinja2==3.1.5
diff --git a/docs/source/citations/09_acknowledgments.rst b/docs/source/citations/09_acknowledgments.rst
@@ -41,4 +41,7 @@ Stuart Lacy wrote an export function for the `Master Chemical Mechanism
 used out-of-the-box for the small model in the :file:`examples/mcm`
 directory.
 
+Simon Rosanka improved the :code:`Update_RCONST` subroutine by providing
+time-dependent concentration values via an optional parameter.
+
 Parts of this user manual are based on :cite:t:`Damian-Iordache_1996`.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -25,7 +25,7 @@
 # The full version, including alpha/beta/rc tags
 # (version numbers must be synchronized in CHANGELOG.md, src/gdata.h,
 # and docs/source/conf.py)
-release = "3.1.1"
+release = "3.2.0"
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/source/getting_started/00_revision_history.rst b/docs/source/getting_started/00_revision_history.rst
@@ -8,20 +8,38 @@ Only the major new features are listed here. For a detailed description
 of the changes, read `CHANGELOG.md
 <https://github.com/KineticPreProcessor/KPP/blob/main/CHANGELOG.md>`_.
 
+.. _kpp320:
+
+=========
+KPP 3.2.0
+=========
+
+- Added new inline key :literal:`F90_RCONST_USE` so that F90
+  :literal:`USE` statements can be inlined into the
+  :code:`Update_RCONST` and :literal:`UPDATE_PHOTO` routines
+- Updated code in :code:`src/gen.c` to generate the
+  :code:`UPDATE_RCONST` routine with an optional argument :code:`Y`
+- Updated C-I tests to print the compiler versions that are used
+- Updated :literal:`int/sdirk.f90` to a newer version
+- Removed :literal:`int/beuler.f90`; Users can select Backward Euler
+  with :literal:`sdirk` integrator and :literal:`ICNTRL(3)=6`
+- Added MacOS architecture-specific compilation flags to the build sequence
+
 .. _kpp311:
 
 =========
 KPP 3.1.1
 =========
 
-.. _kpp310:
 - Use newer Python packages to build ReadTheDocs documentation (see
   :file:`docs/requirements.txt`)
 - Increased :code:`MAX_NO_OF_LINES` and :code:`MAX_EQN` in order to
   parse the entire MCM mechanism
 - Now only add the extra `Aout` argument to `Fun` and `Fun_Split` for
   target language :literal:`Fortran90`.  This fixes a Matlab build error.
 
+.. _kpp310:
+
 =========
 KPP 3.1.0
 =========

diff --git a/docs/source/getting_started/01_installation.rst b/docs/source/getting_started/01_installation.rst
@@ -178,8 +178,9 @@ the :envvar:`KPP_FLEX_LIB_DIR`  environment variable in your
 .. code-block:: bash
 
    export KPP_FLEX_LIB_DIR=/usr/lib
+   export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:${KPP_FLEX_LIB_DIR}:"
 
-And then apply the changes with:
+Then apply the changes with:
 
 .. code-block:: console
 

diff --git a/docs/source/reference/known-bugs.rst b/docs/source/reference/known-bugs.rst
@@ -1,6 +1,30 @@
-##########
-Known Bugs
-##########
+#####################
+Known bugs and issues
+#####################
 
-Bugs are discussed at the `KPP repository Github issues page
-<https://github.com/KineticPreProcessor/KPP/issues/>`_.
+Please see our `Issue tracker on GitHub
+<https://github.com/KineticPreProcessor/KPP/issues>`_ for a list of recent
+bugs and fixes.
+
+===================
+Current bug reports
+===================
+
+These `bug reports (on GitHub)
+<https://github.com/KineticPreProcessor/KPP/issues?q=is%3Aissue%20state%3Aopen%20label%3Abug>`_
+are currently unresolved. We hope to fix these in future releases.
+
+LSODE integrator is not thread-safe
+-----------------------------------
+
+We have discovered that the current implementation of the LSODE
+integrator is not thread-safe for `OpenMP parallelization
+<https://www.openmp.org/>`_.  When LSODE is called from within an
+OpenMP parallel loop, the integration will fail because key internal
+variables in LSODE will be overwritten by concurrent threads.
+
+============================
+Bugs that have been resolved
+============================
+
+These `bugs (reported on GitHub) <https://github.com/KineticPreProcessor/KPP/issues?q=is%3Aissue%20state%3Aclosed%20label%3Abug>`_ have been resolved.
diff --git a/docs/source/tech_info/07_numerical_methods.rst b/docs/source/tech_info/07_numerical_methods.rst
@@ -534,6 +534,15 @@ LSODE, the Livermore ODE solver
 differentiation formula (BDF) methods for stiff problems.  LSODE has
 been translated to Fortran90 for the incorporation into the KPP library.
 
+.. attention::
+
+   We have discovered that the current implementation of the LSODE
+   integrator is not thread-safe for `OpenMP parallelization
+   <https://www.openmp.org/>`_.  When LSODE is called from within
+   an OpenMP parallel loop, the integration will fail because key
+   internal variables in LSODE will be overwritten by concurrent
+   threads.
+
 VODE
 ----
 
@@ -546,9 +555,16 @@ the KPP library uses directly the KPP sparse linear algebra routines.
 BEULER
 ------
 
-**Integrator file:** :file:`int/beuler.f90`
+**Integrator file:** :file:`int/sdirk.f90`
+
+Backward Euler integration method.  To request this method, make sure
+you select
+
+.. code-block:: console
+
+   #INTEGRATOR sdirk
 
-Backward Euler integration method.
+in your definition file, and then set :code:`ICNTRL(3) = 6`.
 
 .. _other-methods:
 

diff --git a/docs/source/using_kpp/04_input_for_kpp.rst b/docs/source/using_kpp/04_input_for_kpp.rst
@@ -24,8 +24,9 @@ description file:
    :ref:`kpp-commands`, and :ref:`inlined-code`. Their syntax is
    presented in :ref:`bnf-description`.
 
--  Comments are either enclosed between the curly braces :code:`{` and
-   :code:`}`, or written in a line starting with two slashes :code:`//`.
+-  Comments are either enclosed between the curly braces ":code:`{`" and
+   ":code:`}`", or written in a line starting with two slashes and a
+   space ":code:`// `".
 
 -  Any name given by the user to denote an atom or a species is
    restricted to be less than 32 character in length and can only
@@ -789,26 +790,28 @@ by :code:`C`, or :code:`matlab`, respectively.
 .. table:: KPP inlined types
    :align: center
 
-   +-----------------+-------------------+---------------------+---------------------+
-   | Inline_type     | File              | Placement           | Usage               |
-   +=================+===================+=====================+=====================+
-   | **F90_DATA**    | :ref:`Monitor`    | specification       | (obsolete)          |
-   |                 |                   | section             |                     |
-   +-----------------+-------------------+---------------------+---------------------+
-   | **F90_GLOBAL**  | :ref:`Global`     | specification       | global variables    |
-   |                 |                   | section             |                     |
-   +-----------------+-------------------+---------------------+---------------------+
-   | **F90_INIT**    | :ref:`Initialize` | subroutine          | integration         |
-   |                 |                   |                     | parameters          |
-   +-----------------+-------------------+---------------------+---------------------+
-   | **F90_RATES**   | :ref:`Rates`      | executable section  | rate law functions  |
-   +-----------------+-------------------+---------------------+---------------------+
-   | **F90_RCONST**  | :ref:`Rates`      | subroutine          | statements and      |
-   |                 |                   |                     | definitions of rate |
-   |                 |                   |                     | coefficients        |
-   +-----------------+-------------------+---------------------+---------------------+
-   | **F90_UTIL**    | :ref:`Util`       | executable section  | utility functions   |
-   +-----------------+-------------------+---------------------+---------------------+
+   +--------------------+-------------------+---------------------+---------------------+
+   | Inline_type        | File              | Placement           | Usage               |
+   +====================+===================+=====================+=====================+
+   | **F90_DATA**       | :ref:`Monitor`    | specification       | (obsolete)          |
+   |                    |                   | section             |                     |
+   +--------------------+-------------------+---------------------+---------------------+
+   | **F90_GLOBAL**     | :ref:`Global`     | specification       | global variables    |
+   |                    |                   | section             |                     |
+   +--------------------+-------------------+---------------------+---------------------+
+   | **F90_INIT**       | :ref:`Initialize` | subroutine          | integration         |
+   |                    |                   |                     | parameters          |
+   +--------------------+-------------------+---------------------+---------------------+
+   | **F90_RATES**      | :ref:`Rates`      | executable section  | rate law functions  |
+   +--------------------+-------------------+---------------------+---------------------+
+   | **F90_RCONST**     | :ref:`Rates`      | subroutine          | rate coefficient    |
+   |                    |                   |                     | definitions         |
+   +--------------------+-------------------+---------------------+---------------------+
+   | **F90_RCONST_USE** | :ref:`Rates`      | subroutine          | rate coefficient    |
+   |                    |                   |                     | definitions         |
+   +--------------------+-------------------+---------------------+---------------------+
+   | **F90_UTIL**       | :ref:`Util`       | executable section  | utility functions   |
+   +--------------------+-------------------+---------------------+---------------------+
 
 .. _f90-data:
 
@@ -908,29 +911,38 @@ F90_RCONST
 ----------
 
 This inline type can be used to define time-dependent values of rate
-coefficients. You may inline :code:`USE` statements that reference
-modules where rate coefficients are computed, e.g.:
+coefficients.  You may inline variables directly, e.g.:
 
 .. code-block:: fortran
 
    #INLINE F90_RCONST
-     USE MyRateFunctionModule
+     k_DMS_OH = 1.E-9*EXP(5820./temp)*C(ind_O2)/ &
+       (1.E30+5.*EXP(6280./temp)*C(ind_O2))
    #ENDINLINE
 
-or define variables directly, e.g.:
+The inlined code will be placed directly into the subroutines
+:code:`UPDATE_RCONST` and :code:`UPDATE_PHOTO` in the :ref:`Rates` file.
+
+.. _f90-rconst-use:
+
+F90_RCONST_USE
+--------------
+
+Similar to :ref:`f90-rconst`, but allows you to inline Fortran-90
+:code:`USE` statements referencing modules where rate coefficients are
+computed, such as:
 
 .. code-block:: fortran
 
-   #INLINE F90_RCONST
-     k_DMS_OH = 1.E-9*EXP(5820./temp)*C(ind_O2)/ &
-       (1.E30+5.*EXP(6280./temp)*C(ind_O2))
+   #INLINE F90_RCONST_USE
+     USE MyRateFunctionModule
    #ENDINLINE
-
-Note that the :code:`USE` statements must precede any variable
-definitions.
-
+
 The inlined code will be placed directly into the subroutines
-:code:`UPDATE_RCONST` and :code:`UPDATE_PHOTO` in the :ref:`Rates` file.
+:code:`UPDATE_RCONST` and :code:`UPDATE_PHOTO` in the :ref:`Rates`
+file.  :code:`USE` statements will be placed before Fortran variable
+definitions and executable statements, as is required by the
+Fortran-90 language standard.  
 
 .. _f90-util:
 
@@ -1077,7 +1089,7 @@ List of symbols replaced by the substitution preprocessor
    +--------------------------+-------------------------------+----------------------------+
 
 .. _icntrl-rcntrl:
-   
+
 =================================================================
 Controlling the Integrator with :code:`ICNTRL` and :code:`RCNTRL`
 =================================================================
@@ -1220,6 +1232,18 @@ ICNTRL
    :code:`Update_SUN` and :code:`Update_PHOTO`, but not to
    :code:`Update_RCONST`.
 
+   Calling :code:`Update_RCONST` may be necessary when reaction rate
+   coefficients depend on the concentration of a specific species, e.
+   g.:
+
+   .. code-block:: console
+
+      HSO3m + HSO5m + Hp = 2 HSO4m + Hp : k_aqueous( C(ind_Hp) );
+
+   This ensures that the concentration :code:`C(ind_Hp)` at the specific
+   integration time is used when the reaction rate coefficient is
+   updated within the integrator.
+
 .. option:: ICNTRL(16)
 
    Treatment of negative concentrations:

diff --git a/examples/mcm/mcm_isoprene.eqn b/examples/mcm/mcm_isoprene.eqn
@@ -662,8 +662,12 @@ C536OOH = IGNORE ;
 C537O = IGNORE ;
 C537OOH = IGNORE ;
 
-#INLINE F90_RCONST 
+#INLINE F90_RCONST_USE
+  ! Use statment to be inlined into Update_RCONST
   USE constants_mcm
+#ENDINLINE
+
+#INLINE F90_RCONST
   ! Peroxy radicals
   ! WARNING: The following species do not have SMILES strings in the database. 
   !           If any of these are peroxy radicals the RO2 sum will be wrong! 

diff --git a/int/beuler.def b/int/beuler.def