maybe setting up codespaces

.devcontainer/devcontainer.json

@@ -0,0 +1,10 @@
+{
+  "name": "Your Development Environment",
+  "dockerFile": "docker/Dockerfile.codespace",
+  "extensions": ["vscode.php"],
+  "settings": {
+      "php.validate.executablePath": "/usr/local/bin/php",
+      "php.executablePath": "/usr/local/bin/php"
+  },
+  "postCreateCommand": "mkdir /build && cd /build && cmake -D CMAKE_BUILD_TYPE=debug -D ENABLE_CLANG_TIDY:BOOL=FALSE -D ENABLE_LLVM:BOOL=TRUE -D ENABLE_MEMCHECK:BOOL=TRUE /micm && make install -j 8"
+}

README.md

@@ -3,6 +3,7 @@ MICM Chemistry
 
 Model Independent Chemical Module. MICM can be used to configure and solve atmospheric chemistry systems.
 
+[![GitHub Releases](https://img.shields.io/github/release/NCAR/micm.svg)](https://github.com/NCAR/micm/releases)
 [![License](https://img.shields.io/github/license/NCAR/micm.svg)](https://github.com/NCAR/micm/blob/master/LICENSE)
 [![CI Status](https://github.com/NCAR/micm/actions/workflows/test.yml/badge.svg)](https://github.com/NCAR/micm/actions/workflows/test.yml)
 [![codecov](https://codecov.io/gh/NCAR/micm/branch/main/graph/badge.svg?token=ATGO4DKTMY)](https://codecov.io/gh/NCAR/micm)

docker/Dockerfile.codespace

@@ -0,0 +1,15 @@
+FROM fedora:37
+
+RUN dnf -y update \
+    && dnf -y install \
+        cmake \
+        gcc-c++ \
+        gdb \
+        git \
+        make \
+        zlib-devel \
+        llvm-devel \
+    && dnf clean all
+
+
+COPY . /micm/

docs/source/getting_started.rst

@@ -5,6 +5,9 @@ Getting Started
 Build and Test
 ==============
 
+Configuring for different platforms and environments is shown here. There is an additional tutorial which covers 
+some other specifics: :ref:`Installation and usage`.
+
 CPU
 ---
 To build and install MICM locally, you must have the following libraries installed:

docs/source/user_guide/but_how_fast_is_it.rst

@@ -56,9 +56,9 @@ in the stats object.
 
 .. literalinclude:: ../../../test/tutorial/test_but_how_fast_is_it.cpp
   :language: cpp
-  :lines: 75-86
+  :lines: 69-80
 
-.. code-block:: console
+.. code-block:: bash
 
   Solver state: Converged
   accepted: 20
@@ -78,9 +78,9 @@ wasted, for the ``false`` version.
 
 .. literalinclude:: ../../../test/tutorial/test_but_how_fast_is_it.cpp
   :language: cpp
-  :lines: 88-96
+  :lines: 82-90
 
-.. code-block:: console
+.. code-block:: bash
 
   Total solve time: 24416 nanoseconds
   total_forcing_time: 3167 nanoseconds

docs/source/user_guide/index.rst

@@ -40,6 +40,7 @@ If you would like to include the json examples, you must configure micm to build
    :maxdepth: 1
    :caption: Contents:
 
+   installation_and_usage
    rate_constant_tutorial
    user_defined_rate_constant_tutorial
    multiple_grid_cells

docs/source/user_guide/installation_and_usage.rst

@@ -0,0 +1,43 @@
+.. _Installation and usage:
+
+Installation and usage
+======================
+
+This tutorial is going to focus **only** and how to install micm and/or include it 
+into your project in multiple different ways. Any API specific details will be elided and will be covered 
+in another tutorial.
+
+
+Github codespace
+----------------
+
+If you want to play around with micm without figuring out how to include it in your local setup, this is the **easiest** 
+option. Github codespaces offers a cloud-hosted version of Visual Studio Code configured to work with specific projects.
+We've set one up for micm. It'll allow you to instantly run the tests and make changes. Please note that there is a cap on
+the number of hours 
+
+
+From an archive
+---------------
+
+All versions of micm are associated with a github `release <https://github.com/NCAR/micm/releases>`_. 
+Each release includes a tarall and zip that you can use to grab the code.
+
+Zip
+^^^
+
+Tarball
+^^^^^^^
+
+Cloning from github
+-------------------
+
+
+Cmake
+-----
+
+Fetch content (recommended)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+External project
+^^^^^^^^^^^^^^^^

docs/source/user_guide/multiple_grid_cells.rst

@@ -34,29 +34,28 @@ This mechanism only needs the user defined rate constant and the rosenbrock solv
 
 .. literalinclude:: ../../../test/tutorial/test_multiple_grid_cells.cpp
   :language: cpp
-  :lines: 1-5
+  :lines: 1-4
 
-After that, we'll use the ``micm`` namespace and setup a template alias so that we can instantiate the 
-rosenbrock solver.
+After that, we'll use the ``micm`` namespace.
 
 .. literalinclude:: ../../../test/tutorial/test_multiple_grid_cells.cpp
   :language: cpp
-  :lines: 7-14
+  :lines: 6-7
 
 To create a :cpp:class:`micm::RosenbrockSolver`, we have to define a chemical system (:cpp:class:`micm::System`)
 and our reactions, which will be a vector of :cpp:class:`micm::Process` We will use the species to define these as
 well as a :cpp:class:`micm::Phase`.
 
 .. literalinclude:: ../../../test/tutorial/test_multiple_grid_cells.cpp
   :language: cpp
-  :lines: 56-60
+  :lines: 49-53
 
 
 With the species and gas phase, we can define all of our reactions
 
 .. literalinclude:: ../../../test/tutorial/test_multiple_grid_cells.cpp
   :language: cpp
-  :lines: 62-78
+  :lines: 55-71
 
 
 Now we can define our RosenbrockSolver. This time we'll form the reactions and chemical system in place.
@@ -67,7 +66,7 @@ the order the species are added to the gas phase.
 
 .. literalinclude:: ../../../test/tutorial/test_multiple_grid_cells.cpp
   :language: cpp
-  :lines: 80-84
+  :lines: 73-77
 
 
 Now we need to get a state and set the concentations of each of the species. In the 
@@ -77,25 +76,25 @@ to set the concentrations. Here we will set the concentations by providing the :
 
 .. literalinclude:: ../../../test/tutorial/test_multiple_grid_cells.cpp
   :language: cpp
-  :lines: 86-91
+  :lines: 79-84
 
 Then we set the reaction rates by creating a vector that is 3 elements long, one for each grid cell.
 
 .. literalinclude:: ../../../test/tutorial/test_multiple_grid_cells.cpp
   :language: cpp
-  :lines: 93-98
+  :lines: 86-91
 
 And lastly set the temperature, pressure, and air density for each grid cell.
 
 .. literalinclude:: ../../../test/tutorial/test_multiple_grid_cells.cpp
   :language: cpp
-  :lines: 100-108
+  :lines: 93-102
 
 Now we are ready to run the simulation.
 
 .. literalinclude:: ../../../test/tutorial/test_multiple_grid_cells.cpp
   :language: cpp
-  :lines: 110-133
+  :lines: 104-127
 
 
 And these are the results.

docs/source/user_guide/solver_configurations.rst

@@ -45,14 +45,14 @@ Configuring the rosenbrock solver is as easy as providing the solver with a set
 
 .. literalinclude:: ../../../test/tutorial/test_solver_configuration.cpp
   :language: cpp
-  :lines: 154-172
+  :lines: 147-165
 
 After that, the usage is the same as a regular solver. A templated method was used here to run the same solving code
 for each of the different solver configurations.
 
 .. literalinclude:: ../../../test/tutorial/test_solver_configuration.cpp
   :language: cpp
-  :lines: 40-123
+  :lines: 34-116
 
 Running this program should give an output similar to this:
 

docs/source/user_guide/user_defined_rate_constant_tutorial.rst

@@ -56,14 +56,14 @@ Adding the custom rate constant is quite simple. Include the header file:
 
 .. code-block:: diff
 
-     #include <micm/process/arrhenius_rate_constant.hpp>
-     #include <micm/process/branched_rate_constant.hpp>
-     #include <micm/process/surface_rate_constant.hpp>
-     #include <micm/process/ternary_chemical_activation_rate_constant.hpp>
-     #include <micm/process/troe_rate_constant.hpp>
-     #include <micm/process/tunneling_rate_constant.hpp>
-    +#include <micm/process/user_defined_rate_constant.hpp>
-     #include <micm/solver/rosenbrock.hpp>
+    #include <micm/process/arrhenius_rate_constant.hpp>
+    #include <micm/process/branched_rate_constant.hpp>
+    #include <micm/process/surface_rate_constant.hpp>
+    #include <micm/process/ternary_chemical_activation_rate_constant.hpp>
+    #include <micm/process/troe_rate_constant.hpp>
+    #include <micm/process/tunneling_rate_constant.hpp>
+  + #include <micm/process/user_defined_rate_constant.hpp>
+    #include <micm/solver/rosenbrock.hpp>
 
 
 Then setup the reaction which will use this rate constant:

test/tutorial/test_but_how_fast_is_it.cpp

@@ -7,12 +7,6 @@
 // Use our namespace so that this example is easier to read
 using namespace micm;
 
-// The Rosenbrock solver can use many matrix ordering types
-// Here, we use the default ordering, but we still need to provide a templated
-// Arguent to the solver so it can use the proper ordering with any data type
-template<class T>
-using SparseMatrixPolicy = SparseMatrix<T>;
-
 int main()
 {
   auto a = Species("A");
@@ -39,7 +33,7 @@ int main()
                    .rate_constant(UserDefinedRateConstant({ .label_ = "r3" }))
                    .phase(gas_phase);
 
-  RosenbrockSolver<Matrix, SparseMatrixPolicy> solver{ System(SystemParameters{ .gas_phase_ = gas_phase }),
+  RosenbrockSolver<> solver{ System(SystemParameters{ .gas_phase_ = gas_phase }),
                                                        std::vector<Process>{ r1, r2, r3 },
                                                        RosenbrockSolverParameters::three_stage_rosenbrock_parameters(
                                                            3, false) };

test/tutorial/test_multiple_grid_cells.cpp

@@ -6,12 +6,6 @@
 // Use our namespace so that this example is easier to read
 using namespace micm;
 
-// The Rosenbrock solver can use many matrix ordering types
-// Here, we use the default ordering, but we still need to provide a templated
-// Arguent to the solver so it can use the proper ordering with any data type
-template<class T>
-using SparseMatrixPolicy = SparseMatrix<T>;
-
 void print_header()
 {
   std::cout << std::setw(5) << "time"
@@ -76,7 +70,7 @@ int main()
                          .rate_constant(micm::UserDefinedRateConstant({ .label_ = "r3" }))
                          .phase(gas_phase);
 
-  micm::RosenbrockSolver<micm::Matrix, SparseMatrixPolicy> solver{
+  micm::RosenbrockSolver<> solver{
     micm::System(micm::SystemParameters{ .gas_phase_ = gas_phase }),
     std::vector<micm::Process>{ r1, r2, r3 },
     micm::RosenbrockSolverParameters::three_stage_rosenbrock_parameters(3, false)

test/tutorial/test_rate_constants_user_defined_by_hand.cpp

@@ -15,12 +15,6 @@
 // Use our namespace so that this example is easier to read
 using namespace micm;
 
-// The Rosenbrock solver can use many matrix ordering types
-// Here, we use the default ordering, but we still need to provide a templated
-// Arguent to the solver so it can use the proper ordering with any data type
-template<class T>
-using SparseMatrixPolicy = SparseMatrix<T>;
-
 void print_header()
 {
   std::cout << std::setw(5) << "time"
@@ -152,7 +146,7 @@ int main(const int argc, const char* argv[])
   auto chemical_system = System(micm::SystemParameters{ .gas_phase_ = gas_phase });
   auto reactions = std::vector<micm::Process>{ r1, r2, r3, r4, r5, r6, r7, r8, r9, r10 };
 
-  RosenbrockSolver<Matrix, SparseMatrixPolicy> solver{ chemical_system,
+  RosenbrockSolver<> solver{ chemical_system,
                                                        reactions,
                                                        RosenbrockSolverParameters::three_stage_rosenbrock_parameters() };
   State state = solver.GetState();

test/tutorial/test_rate_constants_user_defined_with_config.cpp

@@ -15,12 +15,6 @@
 // Use our namespace so that this example is easier to read
 using namespace micm;
 
-// The Rosenbrock solver can use many matrix ordering types
-// Here, we use the default ordering, but we still need to provide a templated
-// Arguent to the solver so it can use the proper ordering with any data type
-template<class T>
-using SparseMatrixPolicy = SparseMatrix<T>;
-
 void print_header()
 {
   std::cout << std::setw(5) << "time"
@@ -68,7 +62,7 @@ int main(const int argc, const char* argv[])
   auto chemical_system = solver_params.system_;
   auto reactions = solver_params.processes_;
 
-  RosenbrockSolver<Matrix, SparseMatrixPolicy> solver{ chemical_system,
+  RosenbrockSolver<> solver{ chemical_system,
                                                        reactions,
                                                        RosenbrockSolverParameters::three_stage_rosenbrock_parameters() };
 

test/tutorial/test_solver_configuration.cpp

@@ -7,12 +7,6 @@
 // Use our namespace so that this example is easier to read
 using namespace micm;
 
-// The Rosenbrock solver can use many matrix ordering types
-// Here, we use the default ordering, but we still need to provide a templated
-// Arguent to the solver so it can use the proper ordering with any data type
-template<class T>
-using SparseMatrixPolicy = SparseMatrix<T>;
-
 void print_header()
 {
   std::cout << std::setw(5) << "time"
@@ -150,23 +144,23 @@ int main()
   auto system = System(SystemParameters{ .gas_phase_ = gas_phase });
   auto reactions = std::vector<Process>{ r1, r2, r3 };
 
-  RosenbrockSolver<Matrix, SparseMatrixPolicy> two_stage{
+  RosenbrockSolver<> two_stage{
     system, reactions, RosenbrockSolverParameters::two_stage_rosenbrock_parameters()
   };
 
-  RosenbrockSolver<Matrix, SparseMatrixPolicy> three_stage{
+  RosenbrockSolver<> three_stage{
     system, reactions, RosenbrockSolverParameters::three_stage_rosenbrock_parameters()
   };
 
-  RosenbrockSolver<Matrix, SparseMatrixPolicy> four_stage{
+  RosenbrockSolver<> four_stage{
     system, reactions, RosenbrockSolverParameters::four_stage_rosenbrock_parameters()
   };
 
-  RosenbrockSolver<Matrix, SparseMatrixPolicy> four_stage_da{
+  RosenbrockSolver<> four_stage_da{
     system, reactions, RosenbrockSolverParameters::four_stage_differential_algebraic_rosenbrock_parameters()
   };
 
-  RosenbrockSolver<Matrix, SparseMatrixPolicy> six_stage_da{
+  RosenbrockSolver<> six_stage_da{
     system, reactions, RosenbrockSolverParameters::six_stage_differential_algebraic_rosenbrock_parameters()
   };