Resolving merge conflicts.

CMakeLists.txt

@@ -4,7 +4,7 @@ cmake_minimum_required(VERSION 3.21)
 
 project(
   micm
-  VERSION 3.4.0
+  VERSION 3.5.0
   LANGUAGES CXX
 )
 
@@ -32,13 +32,14 @@ option(MICM_ENABLE_MPI "Enable MPI parallel support" OFF)
 option(MICM_ENABLE_OPENMP "Enable OpenMP support" OFF)
 option(MICM_ENABLE_COVERAGE "Enable code coverage output" OFF)
 option(MICM_ENABLE_MEMCHECK "Enable memory checking in tests" OFF)
-option(MICM_ENABLE_JSON "Enable json configureation file reading" ON)
+option(MICM_ENABLE_JSON "Enable json configuration file reading" ON)
 option(MICM_BUILD_DOCS "Build the documentation" OFF)
 option(MICM_ENABLE_CUDA "Build with Cuda support" OFF)
 option(MICM_ENABLE_OPENACC "Build with OpenACC Support" OFF)
 option(MICM_ENABLE_LLVM "Build with LLVM support for JIT-compiling" OFF)
 option(MICM_ENABLE_TESTS "Build the tests" ON)
 option(MICM_ENABLE_EXAMPLES "Build the examples" ON)
+option(MICM_ENABLE_PROFILE "Profile MICM Solver" OFF)
 set(MICM_DEFAULT_VECTOR_MATRIX_SIZE "4" CACHE STRING "Default size for vectorizable matrix types")
 
 include(CMakeDependentOption)
@@ -107,16 +108,16 @@ if (${CMAKE_HOST_SYSTEM_NAME} MATCHES "Linux" AND "${CMAKE_CXX_COMPILER_ID}" STR
 endif()
 
 ################################################################################
-# Command-line driver examples
+# Command-line driver examples / Command-line profiler
 
-if(PROJECT_IS_TOP_LEVEL AND MICM_ENABLE_EXAMPLES AND MICM_ENABLE_JSON)
+if(PROJECT_IS_TOP_LEVEL AND MICM_ENABLE_JSON AND (MICM_ENABLE_EXAMPLES OR MICM_ENABLE_PROFILE))
   add_subdirectory(examples)
 endif()
 
 ################################################################################
 # Copy configuration data
 
-if(PROJECT_IS_TOP_LEVEL AND (MICM_ENABLE_TESTS OR MICM_ENABLE_EXAMPLES))
+if(PROJECT_IS_TOP_LEVEL AND (MICM_ENABLE_TESTS OR MICM_ENABLE_EXAMPLES OR MICM_ENABLE_PROFILE))
   add_custom_target(copy_example_configs ALL ${CMAKE_COMMAND} -E copy_directory
     ${CMAKE_SOURCE_DIR}/examples/configs ${CMAKE_BINARY_DIR}/examples/configs)
-endif()
+endif()

cmake/dependencies.cmake

@@ -73,7 +73,7 @@ endif()
 ################################################################################
 # google test
 
-if(PROJECT_IS_TOP_LEVEL)
+if(MICM_ENABLE_TESTS)
   FetchContent_Declare(googletest
     GIT_REPOSITORY https://github.com/google/googletest.git
     GIT_TAG be03d00f5f0cc3a997d1a368bee8a1fe93651f48

docs/source/user_guide/but_how_fast_is_it.rst → docs/source/user_guide/solver_results.rst

@@ -1,9 +1,11 @@
-.. _But how fast is it:
+.. _Solver results:
 
-But how fast is it?
+Solver results
 ===================
 
-This tutorial will focus on timing the solver to show how you can measure performance.
+This tutorial will focus on solver result. Solver result is made of a collection of information useful
+to understand convergence of solution. In a 3D model, if certain grid cells fail the solver convergence
+criteraia, solver statistics can be used to diagnose strange behavior.
 We will use a simple 3-reaction 3-species mechanism. The setup here is the same in
 :ref:`Multiple grid cells`. To understand the full setup, read that tutorial. Otherwise,
 we assume that configuring a rosenbrock solver is understood and instead we will focus on timing 
@@ -34,25 +36,25 @@ There are four values returned.
 
 #. :cpp:member:`micm::RosenbrockSolver::SolverResult::final_time_`
 
-    * This is the final simulation time achieved by the solver. The :cpp:func:`micm::RosenbrockSolver::Solve` function attempts to integrate the passed in state forward a set number of seconds. Often, the solver is able to complete the integration.  However, extremely stiff systems may only solve for a fraction of the time. It is imperative that the ``final_time_`` value is checked. If it is not equal to the amount of time you intended to solve for, call solve again as we do in the tutorials with the difference between what was solved and how long you intended to solve.
+    * This is the final simulation time achieved by the solver. The :cpp:func:`micm::RosenbrockSolver::Solve` function attempts to integrate the passed in state forward a set number of seconds. Often, the solver is able to complete the integration.  However, extremely stiff systems may only solve for a fraction of the time. It is imperative that the ``final_time_`` value is checked. If it is not equal to the amount of time you intended to solve for, call Solve again as we do in the tutorials with the difference between what was solved and how long you intended to solve.
 
       .. note::
-        This does **not** represent the amount of time taken by the solve routine. You must measure that yourself(shown below). The ``final_time_`` is simulation time.
+        This does **not** represent the amount of time taken by the solve routine.
 
 #. :cpp:member:`micm::RosenbrockSolver::SolverResult::result_`
 
     * This contains the integrated state value; the concentrations reached at the end of Solve function after the amount of time specified by ``final_time_``.
 
 #. :cpp:member:`micm::RosenbrockSolver::SolverResult::state_`
 
-    * There are many possible reasons for the solver to return. This value is one of the possible enum values define on the :cpp:enum:`micm::SolverState`. Hopefully, you receive a :cpp:enumerator:`micm::SolverState::Converged` state. But, it is good to always check this to ensure the solver really did converge. You can print this value using the :cpp:func:`micm::StateToString` function.
+    * There are many possible reasons for the solver to return. This value is one of the possible enum values defined on the :cpp:enum:`micm::SolverState`. Hopefully, you receive a :cpp:enumerator:`micm::SolverState::Converged` state. But, it is good to always check this to ensure the solver really did converge. You can print this value using the :cpp:func:`micm::StateToString` function.
 
 #. :cpp:member:`micm::RosenbrockSolver::SolverResult::stats_`
 
-    * This is an instance of a :cpp:class:`micm::RosenbrockSolver::SolverStats` struct which contains information about the number of function calls and optionally the total cumulative amount of time spent calling each function. For the time to be collected, you must call the ``Solve`` function with a ``true`` templated parameter. Please see the example below.
+    * This is an instance of a :cpp:class:`micm::RosenbrockSolver::SolverStats` struct which contains information about the number of individual function calls during solving process and the number of accepted or rejected solutions at every time step.
 
-First, let's run the simulation but without collecting the solve time. We'll inspect the solver state and look at what's collected
-in the stats object. 
+Upon completion of the simulation, we can inspect the solver state and statistics including the number of individual function calls,
+acceptance/rejection of solutions and the existence of singular matrix.
 
 .. literalinclude:: ../../../test/tutorial/test_but_how_fast_is_it.cpp
   :language: cpp
@@ -69,24 +71,4 @@ in the stats object.
   rejected: 0
   decompositions: 20
   solves: 60
-  singular: 0
-
-To get the total accumulated time of each function call, you need to specify the templated boolean argument to turn the timing on.
-We can also record the total runtime of the ``Solve`` function. Through the magic of templates, the timing information is only
-collected when you use the ``true`` version of the templated function. These values are not even computed, meaning no CPU cycles are 
-wasted, for the ``false`` version.
-
-.. literalinclude:: ../../../test/tutorial/test_but_how_fast_is_it.cpp
-  :language: cpp
-  :lines: 82-90
-
-.. code-block:: bash
-
-  Total solve time: 24416 nanoseconds
-  total_forcing_time: 3167 nanoseconds
-  total_jacobian_time: 1710 nanoseconds
-  total_linear_factor_time: 4584 nanoseconds
-  total_linear_solve_time: 3290 nanoseconds
-
-.. note::
-  Your systems clock may not report the same granularity depending on how accurate your system clock is. 
+  singular: 0

examples/CMakeLists.txt

@@ -1,23 +1,35 @@
 # disable clang tidy for test files
 set(CMAKE_CXX_CLANG_TIDY "")
 
-add_executable(micmDriver example.cpp)
-target_link_libraries(micmDriver PUBLIC musica::micm )
+if(MICM_ENABLE_EXAMPLES)
+  add_executable(micmDriver example.cpp)
+  target_link_libraries(micmDriver PUBLIC musica::micm)
+  set_target_properties(micmDriver PROPERTIES OUTPUT_NAME "micm")
 
-set_target_properties(micmDriver PROPERTIES OUTPUT_NAME "micm")
+  ################################################################################
+  # Run each example configuration as a test
 
-################################################################################
-# Run each example configuration as a test
+  add_test(NAME carbon_bond_5_example
+          COMMAND micm ${CMAKE_BINARY_DIR}/examples/configs/carbon_bond_5 ${CMAKE_BINARY_DIR}/examples/configs/carbon_bond_5/initial_conditions.csv
+          WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
+  add_test(NAME chapman_example
+          COMMAND micm ${CMAKE_BINARY_DIR}/examples/configs/chapman ${CMAKE_BINARY_DIR}/examples/configs/chapman/initial_conditions.csv
+          WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
+  add_test(NAME robertson_example
+          COMMAND micm ${CMAKE_BINARY_DIR}/examples/configs/robertson ${CMAKE_BINARY_DIR}/examples/configs/robertson/initial_conditions.csv
+          WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
+  add_test(NAME ts1_example
+          COMMAND micm ${CMAKE_BINARY_DIR}/examples/configs/TS1 ${CMAKE_BINARY_DIR}/examples/configs/TS1/initial_conditions.csv
+          WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
+endif()
 
-add_test(NAME carbon_bond_5_example
-         COMMAND micm ${CMAKE_BINARY_DIR}/examples/configs/carbon_bond_5 ${CMAKE_BINARY_DIR}/examples/configs/carbon_bond_5/initial_conditions.csv
-         WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
-add_test(NAME chapman_example
-         COMMAND micm ${CMAKE_BINARY_DIR}/examples/configs/chapman ${CMAKE_BINARY_DIR}/examples/configs/chapman/initial_conditions.csv
-         WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
-add_test(NAME robertson_example
-         COMMAND micm ${CMAKE_BINARY_DIR}/examples/configs/robertson ${CMAKE_BINARY_DIR}/examples/configs/robertson/initial_conditions.csv
-         WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
-add_test(NAME ts1_example
-         COMMAND micm ${CMAKE_BINARY_DIR}/examples/configs/TS1 ${CMAKE_BINARY_DIR}/examples/configs/TS1/initial_conditions.csv
-         WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
+if(MICM_ENABLE_PROFILE)
+  add_executable(micmprofiler profile_example.cpp)
+  target_link_libraries(micmprofiler PUBLIC musica::micm)
+  set_target_properties(micmprofiler PROPERTIES OUTPUT_NAME "profile")
+
+  # Run TS1 configuration as a test
+  add_test(NAME profile_ts1
+          COMMAND profile ${CMAKE_BINARY_DIR}/examples/configs/TS1 ${CMAKE_BINARY_DIR}/examples/configs/TS1/initial_conditions.csv
+          WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
+endif()