Update documentation for TChem-atm version 2 release. (#75)

odiazib · web-flow · commit 0e47bf59c2c5 · 2025-04-30T08:33:54.000-06:00
* Update documentation for TChem-atm version 2 release.

* addressing Sam's comments.

* Fixing file name.
diff --git a/docs/SIMPOL_example.md b/docs/SIMPOL_example.md
@@ -0,0 +1,36 @@
+# **SIMPOL mass transfer**
+
+Scripts to run and plot the outputs of this example are located at: `$TCHEM_INSTALL_PATH/examples/runs/atmospheric_chemistry/Simpol`. The bash script to run this case is shown below:
+
+```bash
+exec=$TCHEM_INSTALL_PATH/examples/TChem_AerosolChemistry.x
+
+run_this="$exec --chemfile=config_gas.yaml \
+	            --aerofile=test_SIMPOL_phase_transfer.yaml \
+                --inputfile_particles=scenario_conditions_particle.yaml \
+	            --outputfile=full_gas.dat \
+	            --time-iterations-per-interval=10 \
+                --max-time-iterations=100\
+	            --tol-time=1e-3 \
+          		--atol-time=1e-12 \
+	  			--dtmin=1e-20 \
+          		--dtmax=10\
+          		--tend=1000 \
+          		--atol-newton=1e-12 \
+          		--rtol-newton=1e-8 \
+          		--max-newton-iterations=20 \
+          		--max-time-iterations=200000"
+
+echo $run_this
+eval $run_this
+``` 
+Here, the `TChem_AerosolChemistry.x` executable is a box model that integrates (in time) a list of species using the mechanism file specified in the `chemfile` and aerosol species specified in the `aerofile`.
+
+TChem-atm provides executables for CVODE, `$TCHEM_INSTALL_PATH/examples/TChem_AerosolChemistry_CVODE.x`, and Kokkos-Kernels, $`TCHEM_INSTALL_PATH/examples/TChem_AerosolChemistry_KokkosKernels.x`.
+
+The time profiles for ethanol and its aqueous solution are depicted in the figures below. These profiles were generated using TChem-atm, employing ODE solvers such as Tines, Kokkos-kernels (BDF), and Sundials (CVODE). For the purpose of code-to-code verification, we additionally showcase profiles derived from CAMP.
+
+![TChem-atm vs CAMP](figures/simpol_ethanol.png)
+
+
+![TChem-atm vs CAMP](figures/simpol_ethanol_aq.png)
diff --git a/docs/examples.md b/docs/examples.md
@@ -1,3 +1,6 @@
 [Carbon Bond 05](CB5_example.md)
 
 [UCI Chemistry for E3SM Version 3](UCI_example.md)
+
+
+[SIMPOL](SIMPOL_example.md)
diff --git a/docs/figures/RHS_gas_aerosol.png b/docs/figures/RHS_gas_aerosol.png
diff --git a/docs/figures/simpol_ethanol.png b/docs/figures/simpol_ethanol.png
diff --git a/docs/figures/simpol_ethanol_aq.png b/docs/figures/simpol_ethanol_aq.png
diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,6 @@
 # **Overview**
 
-Tchem-atm is a chemistry solver for problems in atmospheric chemistry.
+TChem-atm is a chemistry solver for problems in atmospheric chemistry.
 TChem-atm computes source terms and Jacobian matrices for chemical systems. It is a performance-portable software toolkit designed for complex kinetic mechanisms.
 
 Software Design:
@@ -9,16 +9,15 @@ Software Design:
   * [Kokkos](https://github.com/kokkos/kokkos.git) programming model for performance portability.
   * CMake build system.
   * Numerical and SACADO analytic Jacobian calculations for all models.
-  * Coupling to external ODE solvers, e.g., [Tines](https://github.com/sandialabs/Tines), [Sundials](https://computing.llnl.gov/projects/sundials) (CVODE).
+  * Coupling to external ODE solvers, e.g., [Tines](https://github.com/sandialabs/Tines), [Sundials](https://computing.llnl.gov/projects/sundials) (CVODE), [Kokkos-kernels](https://github.com/kokkos/kokkos-kernels)(BDF).
+  * Continuous integration with GitHub Actions.
+  * Code coverage with Codecov. 
+  * Online documentation deployed with GitHub Actions.
+  * Docker support. 
 
 ![TChem](figures/TChem_atm.png)
 
-TChem-atm is configured using a YAML input file to construct the internal representation of the kinetic model, containing relevant parameters for the computation of chemical source terms.
-It computes reaction constants and rates of progress for all reactions and calculates the net production rate, or source terms, for all chemical species.
-TChem-atm automatically calculates the Jacobian matrix for source terms using either finite differences (numerical Jacobian) or automatic differentiation (analytical Jacobian via SACADO).
-Furthermore, the computation of the source term and associated Jacobian is independent of the time integration solver in TChem-atm.
-As such, TChem-atm provides an interface for time-stepping solutions (Box model) for the Tines and CVODE libraries.
-Finally, TChem-atm features a batched interface for all of the above calculations.
+TChem-atm is configured using a YAML input file to construct the internal representation of the kinetic model, containing relevant parameters for the computation of chemical source terms. It computes reaction constants and rates of progress for all reactions and calculates the net production rate, or source terms, for all chemical species. Furthermore, it provides an interface for gas-aerosol interactions that allows coupling with aerosol models. TChem-atm automatically calculates the Jacobian matrix for source terms using either finite differences (numerical Jacobian) or automatic differentiation (analytical Jacobian via SACADO). Furthermore, the computation of the source term and associated Jacobian is independent of the time integration solver in TChem-atm. As such, TChem-atm provides an interface for time-stepping solutions (Box model) for the Tines, CVODE, and Kokkos-kernels libraries. Finally, TChem-atm features a batched interface for all of the above calculations.
 
 # **Citations**
 
diff --git a/docs/input.md b/docs/input.md
@@ -50,6 +50,24 @@ species:
 
 A description of the reaction types currently implemented in TChem-atm is presented in [Methodology section](methodology.md). In addition, a set of examples of input files is presented under `/src/examples/runs/atmopheric_chemistry`.
 
+## **Gas-Aerosol Chemistry Input File**
+
+To execute a gas-aerosol case in TChem-atm, one needs an input file with the aerosol mechanisms, `aerofile`, and a file where scenario particle information is given, `inputfile_particles`. The aerosol mechanism utilizes a YAML file and follows to the [CAMP format](https://github.com/open-atmos/camp). The scenario particle information follows this format:
+
+```yaml
+particles:
+  initial_state:
+    species_name_1: 
+      initial_value: [1.0e-8]
+    species_name_2: 
+      initial_value: [1.4e-2]
+  num_concentration:
+   initial_value: [1.3e6]  
+
+```
+In this structure, `species_name_1` denotes the initial concentration of species 1 within a single particle. It's important to note that the initial composition for species 1 is consistent across all particles.
+
+Additionally, to incorporate gas-phase reactions into the simulation, a gas reaction mechanism can be seamlessly integrated into the gas-aerosol case.
 <!-- Future work -->
 <!-- ## Gas-Particle chemistry input file. -->
 
diff --git a/docs/installation.md b/docs/installation.md
@@ -15,6 +15,7 @@ TChem-atm requires the following third-party libraries:
     * [Sundials](https://github.com/LLNL/sundials.git)
   * [Gtest](https://github.com/google/googletest.git)
   * [Skywalker](https://github.com/eagles-project/skywalker.git)
+  * [Kokkos-kernels](https://github.com/kokkos/kokkos-kernels)
 
 These third-party libraries are submodules in TChem-atm.
 Thus, we can initialize them (i.e., download and update) using the following command:
@@ -39,27 +40,43 @@ To build/install with CUDA `ON` or `OFF`, use the flag:
 CUDA="ON" # Set to ON/OFF to compile TChem-atm with or without NVIDIA-GPUs support.
 ```
 
-Additionally, specify the root directory for installing/building the third-party libraries:
+To build/install with HIP `ON` or `OFF`, use the flag:
 
 ```bash
-ROOT=/path/to/tchem-atm/.
+HIP="ON" # Set to ON/OFF to compile TChem-atm with or without AMD-GPUs support.
 ```
 
-This script initializes the submodules and installs/builds the third-party libraries in the `$ROOT/HOST` or `$ROOT/DEVICE` directory, depending on whether `CUDA=OFF` or `CUDA=ON` is chosen.
-Since Kokkos can be installed/built with both CUDA `ON` or `OFF`, this script installs it in both `$ROOT/HOST` and `$ROOT/DEVICE`, while the other libraries are installed in `$ROOT/HOST`. Therefore, one must run this script using `CUDA=OFF` to install all third-party libraries and run it a second time with `CUDA=ON` if an NVIDIA GPU is available.
+Note that both CUDA and HIP cannot be enabled simultaneously.
 
-## **Building and installing TChem-atm and Tines**
-The script `scripts/build_script.sh` builds and installs TChem-atm and Tines. Similarly to the script for third-party libraries, in `scripts/build_script.sh`, one must provide the same compiler information and CUDA flag.
+To enable OpenMP.
 
-<!-- ```bash
-MY_CC=gcc # C++ compiler
-MY_CXX=g++ # C++ compiler
-MY_FC=gfortran # Fortran compiler
+```bash
+OPENMP="ON"
+```
+
+The following path specifies the location of the TChem-atm source code.
+
+```bash
+TCHEM_REPOSITORY_PATH=/path/to/tchem-atm/.
 ```
-To build/install with CUDA ON (or OFF), use:
 
-`CUDA="ON" # Set to ON/OFF to compile TChem with NVIDIA-GPUs` -->
+Determine whether to install OpenBLAS using this script.
+```bash
+INSTALL_OPENBLAS="ON"
+```
+
+This script initializes submodules and manages the installation/building of third-party libraries within the `$PWD/HOST`, `$PWD/CUDA`, or `$PWD/HIP` directories, based on the selected settings: `CUDA/HIP=OFF`, `CUDA=ON`, or `HIP=ON`. Given that Kokkos and Kokkos-kernels support installation/building with both `CUDA` and `HIP` enabled (`ON`) or disabled (`OFF`), the script ensures their deployment in both `$PWD/HOST` and the relevant GPU-specific directories (`$PWD/CUDA` or `$PWD/HIP`). Other libraries, however, are exclusively installed in `$PWD/HOST`. To accommodate all third-party libraries, execute this script initially with `CUDA=OFF`. For systems equipped with NVIDIA or AMD GPUs, a subsequent run with CUDA=`ON` or `HIP=ON`, respectively, is necessary to leverage GPU-specific installations.
+
+
+## **Building and installing TChem-atm and Tines**
+
+The script `scripts/build_script.sh` builds and installs TChem-atm and Tines. Similarly to the script for third-party libraries, in `scripts/build_script.sh`, one must provide the same compiler information and CUDA/HIP flag.
 
 In addition, this script adds the option to turn `SACADO="ON"` or `SACADO="OFF"` to enable or disable the SACADO library's automatic differentiation capability.
 
-The installation path for the third-party libraries is specified by `INSTALL_BASE_HOST`, and `ROOT=/path/to/tchem-atm` is where TChem-atm and Tines are installed. If CUDA is `ON`, libraries will be installed in the `ROOT/DEVICE` directory. Otherwise, they will be installed in the `ROOT/HOST` directory.
+If OpenBLAS is included as part of a module; `USE_THIS_OPENBLAS="MODULE"`.
+
+The installation path for the third-party libraries is specified by `INSTALL_BASE_HOST`, and `ROOT=/path/to/tchem-atm` is where TChem-atm and Tines are installed. If CUDA is `ON`, libraries will be installed in the `ROOT/CUDA` directory. If HIP is `ON`, libraries will be installed in the `ROOT/HIP` directory. Otherwise, they will be installed in the `ROOT/HOST` directory.
+ 
+Finally, To select the build type `BUILD_TYPE`, choose either `DEBUG` or `RELEASE`.
+
diff --git a/docs/methodology.md b/docs/methodology.md
@@ -34,6 +34,14 @@ where $N_{\text{spec}}$ is the number of species, ${k_f}_i$ is the reaction cons
 
 <!-- Note that in $\eee{}$`s CAMPP solver, only forward reaction calculations are employed, and the single reaction constant values depend on the type of reaction. -->
 
+## **Aerosol-Gas interations**
+
+TChem-atm facilitates the construction of source terms (or RHS) for gas-aerosol cases. In these cases, the RHS is constructed as follows:
+
+![RHS of gas-aerosol](figures/RHS_gas_aerosol.png)
+
+Where, the first part of the RHS corresponds to the concentration of gas species. Then, the concentration of each particle is appended. Currently, TChem-atm supports the [SIMPOL mass transfer](methodology.md#simpol-mass-transfer).
+
 ## **Reaction Types**
 
 Currently, TChem-atm can reproduce gas chemistry for two complex reaction mechanisms: the gas chemistry of $\eee{}$ v3, i.e., the UCI chemistry system (University of California Irvine), and the Carbon Bond 2005 chemical mechanism, which is well-formulated for urban to remote tropospheric conditions ([Dawson](https://gmd.copernicus.org/articles/15/3663/2022/),[Yarwood](https://www.camx.com/Files/CB05_Final_Report_120805.pdf)).
@@ -182,7 +190,9 @@ $$
 2HO_2 \rightarrow H_2O_2
 $$
 
+<!--
 **Note: from here, onward, the equations and variable names don't agree, so I would make sure to provide a map between the corresponding quantities.**
+-->
 
 ```yaml
 - MUSICA_name: R34
@@ -361,6 +371,14 @@ The `reaction_list` gives the index of the reactions for which this modifier is
 
 Future work will convert `reaction_list` from a list of indices to reaction IDs, as will `photolysis_reaction_index`. Thus, one does not need to know the index of each reaction before running a TChem simulation.
 
+## **Gas-Aerosol Reaction Types**
+
+### SIMPOL mass transfer
+
+It calculates the evaporation rate of organic species that partition between the gas and aerosol phase, based on the parameterization by [Pankow and Asher (2008)](https://acp.copernicus.org/articles/8/2773/2008/acp-8-2773-2008.html).
+
+TChem-atm utilizes a YAML file and follows to the [CAMP format](https://github.com/open-atmos/camp) to specify SIMPOL types.
+
 <!--Future work-->
 <!-- ## Gas and Particle interaction
 
diff --git a/src/examples/runs/atmospheric_chemistry/Simpol/runModelKK.sh b/src/examples/runs/atmospheric_chemistry/Simpol/runModelKK.sh
@@ -3,7 +3,7 @@ exec=$TCHEM_INSTALL_PATH/examples/TChem_AerosolChemistry_KokkosKernels.x
 run_this="$exec --chemfile=config_gas.yaml \
 	  --aerofile=test_SIMPOL_phase_transfer.yaml \
           --inputfile_particles=scenario_conditions_particle.yaml \
-	  --outputfile=full_gas_KK.dat \
+	  --outputfile=full_gas_kk.dat \
 	  --time-iterations-per-interval=10 \
 	  --tol-time=1e-3 \
           --atol-time=1e-12 \
