Move and rename the include directory to sharedlib

.github/workflows/ci.yml

@@ -126,7 +126,7 @@ jobs:
           FORT_VERSION: ${{ matrix.fortran }}
         run: |
           cp tools/install/Makefile.skel Makefile
-          ./build/build_atchem2.sh --mechanism=./model/mechanism.fac --shared_lib=./model/configuration/include --configuration=./model/configuration --mcm=v3.3.1
+          ./build/build_atchem2.sh --mechanism=./model/mechanism.fac --shared_lib=./model/sharedlib --configuration=./model/configuration --mcm=v3.3.1
 
           # macos only
           if [ $RUNNER_OS != "Linux" ] ; then

CHANGELOG.md

@@ -5,8 +5,12 @@ AtChem2 -- CHANGELOG
 post v1.2.3
 -----------
 
-- make install scripts more robust, and update to **openlibm v0.8.6**
-- add option to use time in user-defined Fortran functions
+- implement named arguments (flags) for the `build_atchem2.sh` script
+- remove the `mcm` argument from the executable, and redefine it in the build script to indicate the version of the MCM used
+- make shell scripts more robust, and update to **openlibm v0.8.6**
+- reformat python scripts using **black**, and add a python format test to the Testsuite
+- add option to use time in user-defined custom Fortran functions
+- update copyright notes
 
 
 v1.2.3 (May 2025)

build/build_atchem2.sh

@@ -27,7 +27,7 @@
 # `--shared_lib` is the shared library directory, which contains
 #    the chemical mechanism in Fortran format (`mechanism.*`) and
 #    the pre-compiled mechanism shared library (`mechanism.so`).
-#    Default value: ./model/configuration/include
+#    Default value: ./model/sharedlib
 #
 # `--mcm` is the MCM version of the chemical mechanism, which sets the
 #    reference list of organic peroxy radicals (RO2) and the empirical
@@ -43,15 +43,15 @@
 #     OR
 #   ./build/build_atchem2.sh --mechanism=/path/to/mechanism/file
 #                            --configuration=/path/to/configuration/directory
-#                            --shared_lib=/path/to/mechanism/directory
+#                            --shared_lib=/path/to/shared_lib/directory
 #                            --mcm=v3.3.1
 # -----------------------------------------------------------------------------
 set -eu
 
 # default values for the script flags
 MECHF=""
 CONFIGD="model/configuration"
-MECHD="model/configuration/include"
+SHAREDLIBD="model/sharedlib"
 MCMV="v3.3.1"
 
 # parse the script flags
@@ -64,15 +64,19 @@ while [ "$#" -gt 0 ]; do
             CONFIGD="${1#*=}"
             ;;
         --shared_lib=*)
-            MECHD="${1#*=}"
+            SHAREDLIBD="${1#*=}"
             ;;
         --mcm=*)
             MCMV="${1#*=}"
             ;;
-        *)
+        -*)
             printf "\n[INPUT ERROR] Invalid argument: %s\n" "$1" >&2
             exit 1
             ;;
+        *) # if the script flag is not specified assume the argument is the
+           # chemical mechanism file (`$MECHF`)
+            MECHF="$1"
+            ;;
     esac
     shift
 done
@@ -100,8 +104,8 @@ if [ ! -d "$CONFIGD" ]; then
 fi
 
 # set the shared library directory (`--shared_lib=`)
-printf "\n[*] Shared library directory: %s\n" "$MECHD"
-if [ ! -d "$MECHD" ]; then
+printf "\n[*] Shared library directory: %s\n" "$SHAREDLIBD"
+if [ ! -d "$SHAREDLIBD" ]; then
     printf "\n[INPUT ERROR] The shared library directory does not exist.\n"
     exit 1
 fi
@@ -128,7 +132,7 @@ printf "\n--> Using %s\n" "$PY_BIN"
 
 # compile the chemical mechanism shared library (`mechanism.so`)
 printf "\n--> Compiling chemical mechanism shared library...\n\n"
-make sharedlib PYTHON_BIN="$PY_BIN" MECHFILE="$MECHF" CONFIGDIR="$CONFIGD" MECHDIR="$MECHD" MCMVERS="$MCMV"
+make sharedlib PYTHON_BIN="$PY_BIN" MECHFILE="$MECHF" CONFIGDIR="$CONFIGD" SHAREDLIBDIR="$SHAREDLIBD" MCMVERS="$MCMV"
 if [ $? -ne 0 ] ; then
     printf "\n[FAIL] Check error message for details.\n"
     exit 1

build/fix_mechanism_fac.py

@@ -37,7 +37,6 @@
 import sys
 import re
 
-
 # =========================== FUNCTIONS =========================== #
 
 

build/kpp_conversion.py

@@ -22,7 +22,6 @@
 import sys
 import re
 
-
 # =========================== FUNCTIONS =========================== #
 
 

build/mech_converter.py

@@ -177,11 +177,9 @@ def separate_stoichiometry(input_species):
         else:  # if there is no coefficient then output an assumed coefficient of 1
             return (1.0, pat_match[2])
     else:
-        raise Exception(
-            f"""Reaction species does not match the correct
+        raise Exception(f"""Reaction species does not match the correct
                         format: '{input_species}'. Note that species names should
-                        not begin with numerical characters."""
-        )
+                        not begin with numerical characters.""")
 
 
 # ======================================================
@@ -643,8 +641,7 @@ def convert_to_fortran(mechFile, configDir, sharedDir, mcmV):
 
     # Combine mechanism rates and RO2 sum files.
     with open(os.path.join(sharedDir, "mechanism.f90"), "a") as mech_rates_coeff_file:
-        mech_rates_coeff_file.write(
-            """
+        mech_rates_coeff_file.write("""
 module mechanism_mod
     use, intrinsic :: iso_c_binding
     implicit none
@@ -657,8 +654,7 @@ def convert_to_fortran(mechFile, configDir, sharedDir, mcmV):
         integer, parameter :: DP = selected_real_kind( p = 15, r = 307 )
         real(c_double), intent(inout) :: p(*), q(*)
         real(c_double), intent(in) :: t, TEMP, N2, O2, M, RH, H2O, BLHEIGHT, DEC, JFAC, DILUTE, ROOFOPEN, ASA, J(*), RO2
-        """
-        )
+        """)
 
         # Write out 'Generic Rate Coefficients' and 'Complex reactions'.
         for item in mechanism_rates_coeff_list:
@@ -667,12 +663,10 @@ def convert_to_fortran(mechFile, configDir, sharedDir, mcmV):
         # Write out 'Reaction definitions'.
         for r in mech_rates_list:
             mech_rates_coeff_file.write(r)
-        mech_rates_coeff_file.write(
-            """
+        mech_rates_coeff_file.write("""
     end subroutine update_p
 end module mechanism_mod
-"""
-        )
+""")
 
     # -------------------------------------------------
 
@@ -721,9 +715,9 @@ def main():
         config_dir = "model/configuration"
     else:
         config_dir = sys.argv[2]
-    # `shared_dir` defaults to `model/configuration/include`, if not given as argument
+    # `shared_dir` defaults to `model/sharedlib`, if not given as argument
     if len(sys.argv) <= 3:
-        shared_dir = "model/configuration/include"
+        shared_dir = "model/sharedlib"
     else:
         shared_dir = sys.argv[3]
     # `mcm_vers` defaults to `v3.3.1`, if not given as argument

model/.gitignore

@@ -1,10 +1,10 @@
-# Ignore auto-generated mechanism files and output files in the model/ directory
+# Ignore constraint files, output files, auto-generated mechanism files in the model/ directory
 constraints/environment/*
 constraints/photolysis/*
 constraints/species/*
-configuration/include/*
 output/*.output
 output/*.pdf
 output/reactionRates/*
+sharedlib/*
 
 !.gitkeep

src/argparse.f90

@@ -281,7 +281,7 @@ subroutine get_and_set_directories_from_command_arguments()
     spec_constraints_dir  = read_value_or_default( valid_flags(8)%flag_switch, &
                                                    trim(constraints_dir)//'/species', names, values )
     shared_lib_dir         = read_value_or_default( valid_flags(9)%flag_switch, &
-                                                    trim(model_dir)//'/configuration/include', names, values )
+                                                    trim(model_dir)//'/sharedlib', names, values )
     shared_library        = trim(shared_lib_dir)//'/mechanism.so'
 
     write (*, '(2A)') ' Model directory is: ', trim( model_dir )

src/inputFunctions.f90

@@ -262,7 +262,7 @@ end subroutine setConcentrations
 
   ! -----------------------------------------------------------------
   ! This is called from readPhotoRates(). It reads photolysisNumbers
-  ! from the first column of `model/configuration/include/photolysis-rates` so that we know
+  ! from the first column of `model/sharedlib/photolysis-rates` so that we know
   ! the ID numbers of all photolysis rates and how many there are.
   subroutine readPhotolysisNumbers()
     use, intrinsic :: iso_fortran_env, only : stderr => error_unit
@@ -604,7 +604,7 @@ end subroutine readUnconstrainedPhotolysisRates
   ! This is called from readPhotoRates() if
   ! model/configuration/photolysisConstant.config doesn't exist/is
   ! empty. It reads ck, cl, cmm, cnn, unconstrainedPhotoNames and
-  ! transmissionFactor from `model/configuration/include/photolysis-rates`. It uses
+  ! transmissionFactor from `model/sharedlib/photolysis-rates`. It uses
   ! numUnconstrainedPhotoRates to allocate accordingly.
   subroutine readAllPhotolysisRates()
     use, intrinsic :: iso_fortran_env, only : stderr => error_unit

tests/model_tests/env_model_1/env_model_1.out.cmp

@@ -11,8 +11,8 @@ AtChem2 v1.3-dev
  Environment Constraints directory is: tests/model_tests/env_model_1/constraints/environment
  Photolysis Constraints directory is: tests/model_tests/env_model_1/constraints/photolysis
  Species Constraints directory is: tests/model_tests/env_model_1/constraints/species
- Shared Library directory is: tests/model_tests/env_model_1/configuration/include
- Shared Library is: tests/model_tests/env_model_1/configuration/include/mechanism.so
+ Shared Library directory is: tests/model_tests/env_model_1/sharedlib
+ Shared Library is: tests/model_tests/env_model_1/sharedlib/mechanism.so
 
 -----------------------
  Species and reactions

tests/model_tests/env_model_2/env_model_2.out.cmp

@@ -11,8 +11,8 @@ AtChem2 v1.3-dev
  Environment Constraints directory is: tests/model_tests/env_model_2/constraints/environment
  Photolysis Constraints directory is: tests/model_tests/env_model_2/constraints/photolysis
  Species Constraints directory is: tests/model_tests/env_model_2/constraints/species
- Shared Library directory is: tests/model_tests/env_model_2/configuration/include
- Shared Library is: tests/model_tests/env_model_2/configuration/include/mechanism.so
+ Shared Library directory is: tests/model_tests/env_model_2/sharedlib
+ Shared Library is: tests/model_tests/env_model_2/sharedlib/mechanism.so
 
 -----------------------
  Species and reactions
@@ -129,7 +129,7 @@ AtChem2 v1.3-dev
  7      DILUTE                NOTUSED
  8      JFAC                        1
  Reading all photolysis rates from file...
- 1 not found in tests/model_tests/env_model_2/configuration/include/photolysis-rates, so it will be treated as a constant.
+ 1 not found in tests/model_tests/env_model_2/sharedlib/photolysis-rates, so it will be treated as a constant.
  9      ROOF                     OPEN
  10     ASA                   NOTUSED
  Finished reading environment variables.

tests/model_tests/env_model_3/env_model_3.out.cmp

@@ -11,8 +11,8 @@ AtChem2 v1.3-dev
  Environment Constraints directory is: tests/model_tests/env_model_3/constraints/environment
  Photolysis Constraints directory is: tests/model_tests/env_model_3/constraints/photolysis
  Species Constraints directory is: tests/model_tests/env_model_3/constraints/species
- Shared Library directory is: tests/model_tests/env_model_3/configuration/include
- Shared Library is: tests/model_tests/env_model_3/configuration/include/mechanism.so
+ Shared Library directory is: tests/model_tests/env_model_3/sharedlib
+ Shared Library is: tests/model_tests/env_model_3/sharedlib/mechanism.so
 
 -----------------------
  Species and reactions
@@ -129,7 +129,7 @@ AtChem2 v1.3-dev
  7      DILUTE                NOTUSED
  8      JFAC                        0
  Reading all photolysis rates from file...
- 0 not found in tests/model_tests/env_model_3/configuration/include/photolysis-rates, so it will be treated as a constant.
+ 0 not found in tests/model_tests/env_model_3/sharedlib/photolysis-rates, so it will be treated as a constant.
  9      ROOF                     OPEN
  10     ASA                   NOTUSED
  Finished reading environment variables.

tests/model_tests/env_model_4/env_model_4.out.cmp

@@ -11,8 +11,8 @@ AtChem2 v1.3-dev
  Environment Constraints directory is: tests/model_tests/env_model_4/constraints/environment
  Photolysis Constraints directory is: tests/model_tests/env_model_4/constraints/photolysis
  Species Constraints directory is: tests/model_tests/env_model_4/constraints/species
- Shared Library directory is: tests/model_tests/env_model_4/configuration/include
- Shared Library is: tests/model_tests/env_model_4/configuration/include/mechanism.so
+ Shared Library directory is: tests/model_tests/env_model_4/sharedlib
+ Shared Library is: tests/model_tests/env_model_4/sharedlib/mechanism.so
 
 -----------------------
  Species and reactions
@@ -129,7 +129,7 @@ AtChem2 v1.3-dev
  7      DILUTE                NOTUSED
  8      JFAC                        1
  Reading all photolysis rates from file...
- 1 not found in tests/model_tests/env_model_4/configuration/include/photolysis-rates, so it will be treated as a constant.
+ 1 not found in tests/model_tests/env_model_4/sharedlib/photolysis-rates, so it will be treated as a constant.
  9      ROOF                   CLOSED
  10     ASA                   NOTUSED
  Finished reading environment variables.

tests/model_tests/firstorder/firstorder.out.cmp

@@ -11,8 +11,8 @@ AtChem2 v1.3-dev
  Environment Constraints directory is: tests/model_tests/firstorder/constraints/environment
  Photolysis Constraints directory is: tests/model_tests/firstorder/constraints/photolysis
  Species Constraints directory is: tests/model_tests/firstorder/constraints/species
- Shared Library directory is: tests/model_tests/firstorder/configuration/include
- Shared Library is: tests/model_tests/firstorder/configuration/include/mechanism.so
+ Shared Library directory is: tests/model_tests/firstorder/sharedlib
+ Shared Library is: tests/model_tests/firstorder/sharedlib/mechanism.so
 
 -----------------------
  Species and reactions

tests/model_tests/secondorder/secondorder.out.cmp

@@ -11,8 +11,8 @@ AtChem2 v1.3-dev
  Environment Constraints directory is: tests/model_tests/secondorder/constraints/environment
  Photolysis Constraints directory is: tests/model_tests/secondorder/constraints/photolysis
  Species Constraints directory is: tests/model_tests/secondorder/constraints/species
- Shared Library directory is: tests/model_tests/secondorder/configuration/include
- Shared Library is: tests/model_tests/secondorder/configuration/include/mechanism.so
+ Shared Library directory is: tests/model_tests/secondorder/sharedlib
+ Shared Library is: tests/model_tests/secondorder/sharedlib/mechanism.so
 
 -----------------------
  Species and reactions

tests/model_tests/spec_model_1/spec_model_1.out.cmp

@@ -11,8 +11,8 @@ AtChem2 v1.3-dev
  Environment Constraints directory is: tests/model_tests/spec_model_1/constraints/environment
  Photolysis Constraints directory is: tests/model_tests/spec_model_1/constraints/photolysis
  Species Constraints directory is: tests/model_tests/spec_model_1/constraints/species
- Shared Library directory is: tests/model_tests/spec_model_1/configuration/include
- Shared Library is: tests/model_tests/spec_model_1/configuration/include/mechanism.so
+ Shared Library directory is: tests/model_tests/spec_model_1/sharedlib
+ Shared Library is: tests/model_tests/spec_model_1/sharedlib/mechanism.so
 
 -----------------------
  Species and reactions

tests/model_tests/spec_model_func/spec_model_func.out.cmp

@@ -11,8 +11,8 @@ AtChem2 v1.3-dev
  Environment Constraints directory is: tests/model_tests/spec_model_func/constraints/environment
  Photolysis Constraints directory is: tests/model_tests/spec_model_func/constraints/photolysis
  Species Constraints directory is: tests/model_tests/spec_model_func/constraints/species
- Shared Library directory is: tests/model_tests/spec_model_func/configuration/include
- Shared Library is: tests/model_tests/spec_model_func/configuration/include/mechanism.so
+ Shared Library directory is: tests/model_tests/spec_model_func/sharedlib
+ Shared Library is: tests/model_tests/spec_model_func/sharedlib/mechanism.so
 
 -----------------------
  Species and reactions

tests/model_tests/spec_model_kpp/spec_model_kpp.out.cmp

@@ -11,8 +11,8 @@ AtChem2 v1.3-dev
  Environment Constraints directory is: tests/model_tests/spec_model_kpp/constraints/environment
  Photolysis Constraints directory is: tests/model_tests/spec_model_kpp/constraints/photolysis
  Species Constraints directory is: tests/model_tests/spec_model_kpp/constraints/species
- Shared Library directory is: tests/model_tests/spec_model_kpp/configuration/include
- Shared Library is: tests/model_tests/spec_model_kpp/configuration/include/mechanism.so
+ Shared Library directory is: tests/model_tests/spec_model_kpp/sharedlib
+ Shared Library is: tests/model_tests/spec_model_kpp/sharedlib/mechanism.so
 
 -----------------------
  Species and reactions

tests/model_tests/spec_model_stoich/spec_model_stoich.out.cmp

@@ -11,8 +11,8 @@ AtChem2 v1.3-dev
  Environment Constraints directory is: tests/model_tests/spec_model_stoich/constraints/environment
  Photolysis Constraints directory is: tests/model_tests/spec_model_stoich/constraints/photolysis
  Species Constraints directory is: tests/model_tests/spec_model_stoich/constraints/species
- Shared Library directory is: tests/model_tests/spec_model_stoich/configuration/include
- Shared Library is: tests/model_tests/spec_model_stoich/configuration/include/mechanism.so
+ Shared Library directory is: tests/model_tests/spec_model_stoich/sharedlib
+ Shared Library is: tests/model_tests/spec_model_stoich/sharedlib/mechanism.so
 
 -----------------------
  Species and reactions

tests/model_tests/static/static.out.cmp

@@ -11,8 +11,8 @@ AtChem2 v1.3-dev
  Environment Constraints directory is: tests/model_tests/static/constraints/environment
  Photolysis Constraints directory is: tests/model_tests/static/constraints/photolysis
  Species Constraints directory is: tests/model_tests/static/constraints/species
- Shared Library directory is: tests/model_tests/static/configuration/include
- Shared Library is: tests/model_tests/static/configuration/include/mechanism.so
+ Shared Library directory is: tests/model_tests/static/sharedlib
+ Shared Library is: tests/model_tests/static/sharedlib/mechanism.so
 
 -----------------------
  Species and reactions