Tutorial updates (#222)

* update tutorial

* update tutorial ch 0

* final updates

* update file name

* update build script

* update file name

* minor updates

* fix typo

* update references

* address comments

configs/analytical/config.json

@@ -1 +1,6 @@
-{"camp-files": ["species.json", "reactions.json"]}
+{
+  "camp-files": [
+    "species.json",
+    "reactions.json"
+  ]
+}

configs/analytical/reactions.json

@@ -1,32 +1,69 @@
 {
-  "camp-data":
-  [
+  "camp-data": [
     {
       "type": "MECHANISM",
       "name": "music box interactive configuration",
-      "reactions":
-      [
+      "reactions": [
         {
-          "type": "USER_DEFINED",
-          "MUSICA name" : "reaction 2",
-          "reactants": {"E": {"qty": 1}},
-          "products": {"F": {"yield": 1}}
+          "type": "ARRHENIUS",
+          "A": 0.004,
+          "C": 50,
+          "reactants": {
+            "A": {
+              "qty": 1
+            }
+          },
+          "products": {
+            "B": {
+              "yield": 1
+            }
+          }
         },
         {
-          "type": "USER_DEFINED",
-          "MUSICA name" : "reaction 1",
-          "reactants": {"D": {"qty": 1}},
-          "products": {"E": {"yield": 1}}
+          "type": "ARRHENIUS",
+          "A": 0.012,
+          "B": -2,
+          "C": 75,
+          "D": 50,
+          "E": 1.0e-6,
+          "reactants": {
+            "B": {
+              "qty": 1
+            }
+          },
+          "products": {
+            "C": {
+              "yield": 1
+            }
+          }
         },
         {
-          "type": "ARRHENIUS", "A": 0.004, "C" : 50,
-          "reactants": {"A": {"qty": 1}},
-          "products": {"B": {"yield": 1}}
+          "type": "USER_DEFINED",
+          "MUSICA name": "reaction 1",
+          "reactants": {
+            "D": {
+              "qty": 1
+            }
+          },
+          "products": {
+            "E": {
+              "yield": 1
+            }
+          }
         },
         {
-          "type": "ARRHENIUS", "A": 0.012, "B": -2, "C" : 75, "D": 50, "E": 1.0e-6,
-          "reactants": {"B": {"qty": 1}},
-          "products": {"C": {"yield": 1}}
+          "type": "USER_DEFINED",
+          "MUSICA name": "reaction 2",
+          "reactants": {
+            "E": {
+              "qty": 1
+            }
+          },
+          "products": {
+            "F": {
+              "yield": 1
+            }
+          }
         }
       ]
     }

configs/analytical/species.json

@@ -1,23 +1,28 @@
 {
-  "camp-data":
-  [
+  "camp-data": [
     {
-      "name": "A", "type": "CHEM_SPEC"
+      "name": "A",
+      "type": "CHEM_SPEC"
     },
     {
-      "name": "B", "type": "CHEM_SPEC"
+      "name": "B",
+      "type": "CHEM_SPEC"
     },
     {
-      "name": "C", "type": "CHEM_SPEC"
+      "name": "C",
+      "type": "CHEM_SPEC"
     },
     {
-      "name": "D", "type": "CHEM_SPEC"
+      "name": "D",
+      "type": "CHEM_SPEC"
     },
     {
-      "name": "E", "type": "CHEM_SPEC"
+      "name": "E",
+      "type": "CHEM_SPEC"
     },
     {
-      "name": "F", "type": "CHEM_SPEC"
+      "name": "F",
+      "type": "CHEM_SPEC"
     }
   ]
 }

docs/source/tutorial/chapter0.rst

@@ -1,40 +1,86 @@
 Chapter 0
 =========
 
-The MUSICA CMake Package
-------------------------
+.. _installing_musica:
 
-The MUSICA library installs with `CMake` ``musica`` and ``musica_fortran``
-packages to facilitate linking
-to higher level libraries and host models that have CMake build systems.
+Installing MUSICA
+-----------------
 
-A minimal ``CMakeLists.txt`` file designed to link the ``musica_fortran`` library
-to a Fortran program ``demo_f.f90`` is exhibited below
+This tutorial will guide you through the installation and use of MUSICA and
+the MUSICA-Fortran interface. The MUSICA library is a C++ library that
+provides a set of tools and solvers for the simulation of atmospheric
+chemistry and aerosols. The MUSICA-Fortran interface provides a
+Fortran API to the MUSICA library.
 
-  .. literalinclude:: ../../../fortran/test/tutorial/CMakeLists.txt
-    :language: cmake
+The MUSICA library and the MUSICA-Fortran interface can be installed
+together or separately. The MUSICA library is required to build the
+MUSICA-Fortran interface.
 
-These `CMake` directives are essentially equivalent to compilation on the command line via
+The MUSICA library and the MUSICA-Fortran interface can be installed
+using the CMake build system.
+
+
+Local Installation
+~~~~~~~~~~~~~~~~~~
+
+First, ensure that you have the required dependencies installed. On
+Fedora, you can install the required dependencies with the following:
 
 .. code-block:: bash
 
-  gfortran -o demo_f demo_f.f90 -I<MUSICA_DIR>/include -L<MUSICA_DIR>/lib -lmusica-fortran -lmusica -lstdc++
+  sudo dnf install -y cmake git gcc-c++ gcc-gfortran netcdf-devel netcdf-fortran-devel
 
-``<MUSICA_DIR>`` is the full path of the MUSICA installation directory,
-specified by the option ``CMAKE_INSTALL_PREFIX``
-during the `cmake` configuration process.
+On other distributions or operating systems, you may need to install the dependencies
+using the package manager for your system.
 
-Common practice is to create a ``build`` subdir (relative to the top level ``CMakeLists.txt`` file, say).
+Next, clone the MUSICA repository from GitHub:
+
+.. code-block:: bash
+
+  git clone https://github.com/NCAR/musica.git
+
+Next, create a build directory and run CMake:
 
 .. code-block:: bash
 
   mkdir build
   cd build
+  cmake -D CMAKE_INSTALL_PREFIX=<INSTALL_DIR>  -D MUSICA_BUILD_FORTRAN_INTERFACE=ON ../musica
 
-The ``cmake`` could then be invoked with:
+where ``<INSTALL_DIR>`` is the directory where you want to install MUSICA.
+We use the ``MUSICA_BUILD_FORTRAN_INTERFACE`` option to build the MUSICA-Fortran
+interface, which is not built by default.
+
+Finally, build and install MUSICA:
 
 .. code-block:: bash
 
-  cmake -DMUSICA_INSTALL_DIR <MUSICA_DIR> ..
-  cmake --build .
+  make
+  make install
+
+Docker Installation
+~~~~~~~~~~~~~~~~~~~
+
+Alternatively, you can build and install MUSICA using Docker. First, ensure
+that you have
+`Docker Desktop <https://www.docker.com/products/docker-desktop/>`_
+installed and running on your system.
+
+Then, clone the MUSICA GitHub repository and use the provided Dockerfile to
+build the MUSICA Docker image:
+
+.. code-block:: bash
+
+  git clone https://github.com/NCAR/musica.git
+  cd musica
+  docker build -t musica-fortran -f docker/Dockerfile.fortran-gcc .
+  docker run -it musica-fortran bash
+
+You can then perform the remainder of the tutorial inside the Docker container.
+The ``<MUSICA_DIR>`` directory used throughout the tutorial will be located at ``/musica/build``
+
+Once you are finished, you can exit the container by typing ``exit``. (Note that
+the container will be deleted along with any files you created or modified when
+you exit.)
+
 

docs/source/tutorial/chapter1.rst

@@ -1,43 +1,75 @@
+.. _chapter1:
+
 Chapter 1
 =========
 
 First Fortran MUSICA Program
 ----------------------------
-The MUSICA library can be used within a fortran program.
+The MUSICA-Fortran API provides access to the MUSICA library within a fortran program.
 To get started, let us create a simple program that links
 to MUSICA and prints the version of MICM.
 
-Here are the contents of the program `demo.f90`:
+Save the following code to a file named `demo.F90`:
 
   .. literalinclude:: ../../../fortran/test/fetch_content_integration/test_get_micm_version.F90
-    :language: f90
+    :language: F90
 
 From the ``musica_micm`` module, we only need the function ``get_micm_version``,
 which returns a derived string type from the ``musica_util`` module, ``string_t``.
-The ``string_t`` type will be discussed in more detail in later chapters.
+(The ``string_t`` type will be discussed in more detail in later chapters.)
 To print the version string we just want the fortran character array,
-accessed by ``get_char_array``.
+accessed by the ``get_char_array`` function.
 
 Now, to build this simple program,
-invoke the `gfortran` compiler and link to ``libmusica-fortran``, ``libmusica``,
+invoke the `gfortran` compiler and link to ``libmusica-fortran``, ``libmusica``, ``yaml-cpp``,
 and the standard C++ library ``libstdc++``.
 The full command is
 
 .. code-block:: bash
 
-  gfortran -o demo demo.f90 -I<MUSICA_DIR>/include -L<MUSICA_DIR>/lib -lmusica-fortran -lmusica -lstdc++
+  gfortran -o demo demo.F90 -I<MUSICA_DIR>/include -L<MUSICA_DIR>/lib64 -lmusica-fortran -lmusica -lstdc++ -lyaml-cpp
 
 ``<MUSICA_DIR>`` is the full path of the MUSICA installation directory,
 specified by the option ``CMAKE_INSTALL_PREFIX``
-during the `cmake` configuration process.
-Note the include path allows the linker to find the ``musica_micm.mod`` and ``musica_util.mod``
+during installation (see :ref:`installing_musica`).
+Note that the include path allows the linker to find the ``musica_micm.mod`` and ``musica_util.mod``
 module definition files.
 
 When the `demo` program is run it should display the MICM version: 
 
 .. code-block:: bash
 
   $ ./demo
-   MICM version 3.5.0
+   MICM version 3.6.0
   $
 
+Building a MUSICA Fortran Program with CMake
+--------------------------------------------
+
+A minimal ``CMakeLists.txt`` file designed to link the ``musica_fortran`` library
+to the ``demo_f.F90`` file described above is exhibited below
+
+  .. literalinclude:: ../../../fortran/test/tutorial/CMakeLists.txt
+    :language: cmake
+
+Common practice is to create a ``build`` subdirectory (relative to the top level ``CMakeLists.txt`` file shown above).
+
+.. code-block:: bash
+
+  mkdir build
+  cd build
+
+Then, ``cmake`` can then be invoked with:
+
+.. code-block:: bash
+
+  cmake -DMUSICA_INSTALL_DIR=<MUSICA_DIR> ..
+  make
+
+Then, the ``demo_f`` executable can be run:
+
+.. code-block:: bash
+
+  $ ./demo_f
+    MICM version 3.6.0
+  $