writing instructions for direct inclusion after install

CMakeLists.txt

@@ -27,10 +27,6 @@ set(CMAKE_MODULE_PATH "${CMAKE_MODULE_PATH};${PROJECT_SOURCE_DIR}/cmake")
 # Set up include and lib directories
 set(MICM_LIB_DIR "${PROJECT_BINARY_DIR}/lib")
 
-include(GNUInstallDirs)
-set(INSTALL_PREFIX "micm-${PROJECT_VERSION}" )
-set(INSTALL_MOD_DIR "${INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}")
-
 option(ENABLE_CLANG_TIDY "Enable clang-tiday to format source code" OFF)
 option(ENABLE_MPI "Enable MPI parallel support" OFF)
 option(ENABLE_OPENMP "Enable OpenMP support" OFF)

docs/source/user_guide/installation_and_usage.rst

@@ -33,17 +33,23 @@ Onces that's done, you can move into the build direcotry and run the tests.
   cd build
   make test
 
+Installing
+----------
+
 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.
 
 Find a release of micm that you want to build and download that archive. You can either do this with the browser by
 poking on the desired file or with the commands below.
 
+If you intend to use cmake to install micm, you can choose the install location when you configure
+cmake: ``cmake -D CMAKE_INSTALL_PREFIX=/Users/me/Documents ..``.
+
 Zip
-^^^
+~~~
 .. code-block:: bash
 
   wget https://github.com/NCAR/micm/archive/refs/tags/v3.2.0.zip
@@ -53,9 +59,10 @@ Zip
   cmake ..
   make -j 8
   make test
+  sudo make install
 
 Tarball
-^^^^^^^
+~~~~~~~
 .. code-block:: bash
 
   wget https://github.com/NCAR/micm/archive/refs/tags/v3.2.0.tar.gz
@@ -65,9 +72,10 @@ Tarball
   cmake ..
   make -j 8
   make test
+  sudo make install
 
 Cloning from github
--------------------
+^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: bash
 
@@ -77,17 +85,73 @@ Cloning from github
   cmake ..
   make -j 8
   make test
+  sudo make install
+
+Usage after installation
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+micm installs itself in a location typical on your system, like ``/usr/local``. It does so under it's own
+directory with the version appended, e.g. ``/usr/local/micm-3.2.0``. It installs header files and files suitable
+for use with cmake's `find_package <https://cmake.org/cmake/help/latest/command/find_package.html>`_.
+
+::
+
+  $ tree /usr/local/micm-3.2.0 -L 2
+  /usr/local/micm-3.2.0
+  ├── cmake
+  │   ├── micmConfig.cmake
+  │   ├── micmConfigVersion.cmake
+  │   └── micm_Exports.cmake
+  └── include
+      └── micm
+
+Specify include path
+~~~~~~~~~~~~~~~~~~~~
+
+To compile micm code, it's as simple as adding the include path to your compile command ``-I/usr/local/micm-3.2.0/include``
+or ``export CPPFLAGS="-I/usr/local/micm-3.2.0/include"``. If you changed the install location when configuring cmake, you'll
+need to set that path instead.
+
+cmake with find_package
+~~~~~~~~~~~~~~~~~~~~~~~
+
+
 
 Cmake
 -----
 
 micm is developed with cmake support. This makes the inclusion of micm into projects that use cmake especially easy.
 
-Fetch content (recommended)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Fetch content
+^^^^^^^^^^^^^
+
+If you can use cmake 3.11+, the easiest way to include micm is with the 
+`FetchContent  module <https://cmake.org/cmake/help/latest/module/FetchContent.html>`_.
+If you must use a lower version, you'll either need to install the files on your system, or properly set
+the include flags of your cmake project to point to the micm header files if you don't need GPU support.
+You may also want to look into `ExternalProject <https://cmake.org/cmake/help/latest/module/ExternalProject.html>`_.
+
+To use micm with fetch content, you'll need to include the module and point it to the micm repository and a commit
+or tag that you want to use. Then you make the content available and link your cmake target to micm.
+
+.. code-block:: cmake
+
+  include(FetchContent)
+
+  FetchContent_Declare(micm
+    GIT_REPOSITORY https://github.com/NCAR/micm.git
+    GIT_TAG        0996e5848b097e77ccbb2819f22c49844154f3e3
+  )
+
+  FetchContent_MakeAvailable(micm)
+
+  add_executable(my_target my_target.cpp)
+
+  target_link_libraries(my_target 
+    PUBLIC 
+      musica::micm
+  )
 
-External project
-^^^^^^^^^^^^^^^^
 
 Debugging
 ---------

packaging/CMakeLists.txt

@@ -1,4 +1,6 @@
 include(CMakePackageConfigHelpers)
+include(GNUInstallDirs)
+set(INSTALL_PREFIX "micm-${PROJECT_VERSION}" )
 
 install(
   TARGETS 

test/integration/cmake/README.md

@@ -0,0 +1,3 @@
+This folder tests usage with cmake. These are not tests that can be run with `make test`.
+Both of these are tested in the dockerfiles so they are tested as part of the automated build. Please
+look at the dockerfiles to see how to test these.

test/integration/cmake/configs/robertson/reactions.json

@@ -0,0 +1,43 @@
+{
+  "camp-data": [
+    {
+      "name": "reaction rates no user defined",
+      "type": "MECHANISM",
+      "reactions": [
+        {
+          "type": "PHOTOLYSIS",
+          "reactants": {
+            "A": {}
+          },
+          "products": {
+            "B": {}
+          },
+          "MUSICA name": "r1"
+        },
+        {
+          "type": "PHOTOLYSIS",
+          "reactants": {
+            "B": { "qty": 2}
+          },
+          "products": {
+            "B": {},
+            "C": {}
+          },
+          "MUSICA name": "r2"
+        },
+        {
+          "type": "PHOTOLYSIS",
+          "reactants": {
+            "B": {},
+            "C": {}
+          },
+          "products": {
+            "A": {},
+            "C": {}
+          },
+          "MUSICA name": "r3"
+        }
+      ]
+    }
+  ]
+}

test/integration/cmake/configs/robertson/species.json

@@ -0,0 +1,16 @@
+{
+  "camp-data": [
+    {
+      "name": "A",
+      "type": "CHEM_SPEC"
+    },
+    {
+      "name": "B",
+      "type": "CHEM_SPEC"
+    },
+    {
+      "name": "C",
+      "type": "CHEM_SPEC"
+    }
+  ]
+}

test/integration/cmake/fetch_content/CMakeLists.txt

@@ -0,0 +1,37 @@
+cmake_minimum_required(VERSION 3.11)
+
+project(
+  test_micm_fetch_content
+  VERSION 0.0.0
+  LANGUAGES CXX
+)
+
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+
+include(FetchContent)
+
+FetchContent_Declare(micm
+  GIT_REPOSITORY https://github.com/NCAR/micm.git
+  GIT_TAG        0996e5848b097e77ccbb2819f22c49844154f3e3
+)
+
+FetchContent_MakeAvailable(micm)
+
+################################################################################
+# Tests
+add_executable(test_micm test_micm.cpp)
+
+target_link_libraries(test_micm 
+  PUBLIC 
+    musica::micm
+)
+
+enable_testing()
+
+add_test(
+  NAME test_micm 
+  COMMAND test_micm
+)
+
+add_custom_target(copy_configs ALL ${CMAKE_COMMAND} -E copy_directory
+  ${CMAKE_CURRENT_SOURCE_DIR}/configs ${CMAKE_BINARY_DIR}/configs)

test/integration/cmake/test_micm.cpp

@@ -0,0 +1,87 @@
+#include <micm/configure/solver_config.hpp>
+#include <micm/solver/rosenbrock.hpp>
+
+using namespace micm;
+
+void print_header()
+{
+  std::cout << std::setw(5) << "time"
+            << "," << std::setw(10) << "A"
+            << "," << std::setw(10) << "B"
+            << "," << std::setw(10) << "C" << std::endl;
+}
+
+template<template<class> class T>
+void print_state(double time, State<T>& state)
+{
+  std::ios oldState(nullptr);
+  oldState.copyfmt(std::cout);
+
+  std::cout << std::setw(5) << time << ",";
+  std::cout << std::scientific << std::setprecision(2) 
+    << std::setw(10) << state.variables_[0][state.variable_map_["A"]] << "," 
+    << std::setw(10) << state.variables_[0][state.variable_map_["B"]] << "," 
+    << std::setw(10) << state.variables_[0][state.variable_map_["C"]] 
+    << std::endl;
+
+  std::cout.copyfmt(oldState);
+}
+
+int main()
+{
+  constexpr size_t n_threads = 3;
+
+  SolverConfig solverConfig;
+
+  std::string config_path = "./configs/robertson";
+  ConfigParseStatus status = solverConfig.ReadAndParse(config_path);
+  if (status != micm::ConfigParseStatus::Success)
+  {
+    throw "Parsing failed";
+  }
+
+  micm::SolverParameters solver_params = solverConfig.GetSolverParams();
+
+  auto chemical_system = solver_params.system_;
+  auto reactions = solver_params.processes_;
+
+  RosenbrockSolver<> solver{ chemical_system,
+                                  reactions,
+                                  RosenbrockSolverParameters::three_stage_rosenbrock_parameters(1, false) };
+  State<Matrix> state = solver.GetState();
+
+  // mol m-3
+  state.variables_[0] = { 1, 0, 0 };
+
+  double k1 = 0.04;
+  double k2 = 3e7;
+  double k3 = 1e4;
+  state.SetCustomRateParameter("PHOTO.r1", k1);
+  state.SetCustomRateParameter("PHOTO.r2", k2);
+  state.SetCustomRateParameter("PHOTO.r3", k3);
+
+  double temperature = 272.5;  // [K]
+  double pressure = 101253.3;  // [Pa]
+  double air_density = 1e6;    // [mol m-3]
+
+  state.conditions_[0].temperature_ = temperature;
+  state.conditions_[0].pressure_ = pressure;
+  state.conditions_[0].air_density_ = air_density;
+
+  double time_step = 200;  // s
+
+  print_header();
+  print_state(0, state);
+  for (int i = 0; i < 10; ++i)
+  {
+    double elapsed_solve_time = 0;
+
+    while (elapsed_solve_time < time_step)
+    {
+      auto result = solver.Solve(time_step - elapsed_solve_time, state);
+      elapsed_solve_time = result.final_time_;
+      state.variables_ = result.result_;
+    }
+    print_state(time_step * (i + 1), state);
+  }
+}