Merge pull request NCAR#132 from NCAR/develop-host-model

MUSICA Tutorial Chapter 1

CMakeLists.txt

@@ -124,4 +124,4 @@ endif()
 # Musica python
 if(MUSICA_ENABLE_PYTHON_LIBRARY)
   add_subdirectory(python)
-endif()
+endif()

cmake/dependencies.cmake

@@ -111,4 +111,4 @@ endif()
 
 if(MUSICA_BUILD_DOCS)
   find_package(Sphinx REQUIRED)
-endif()
+endif()

docs/source/getting_started/getting_started.rst

@@ -0,0 +1,10 @@
+###############
+Getting Started
+###############
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   overview
+   installation

docs/source/getting_started/installation.rst

@@ -0,0 +1,16 @@
+Installation
+============
+
+MUSICA source code may be cloned from its public GitHub repository
+and configured and built with the cmake utility.
+In brief:
+
+.. code-block:: console
+ 
+    $ git clone https://github.com/NCAR/musica.git
+    $ cd musica
+    $ mkdir build
+    $ cd build
+    $ ccmake ..
+    $ make
+    $ make install

docs/source/getting_started/overview.rst

@@ -0,0 +1,19 @@
+Overview
+========
+
+The specific goal of MUSICA is to produce a new model independent infrastructure,
+which will enable chemistry and aerosols to be simulated
+at a large number of different resolutions in a single, coherent fashion.
+At first, MUSICA will be configured within the NCAR Community Earth system Model (CESM)
+and through this enable full feedbacks between the atmosphere, ocean and land.
+The infrastructure will unify the different chemical transport models
+including CAM-Chem, WACCM and WRF-Chem, and NCAR LES with chemistry
+and a box model in a single modular framework.
+The model infrastructure will be open source,
+flexible and computationally efficient in order
+to facilitate community co-development and use for scientific and operational purposes. 
+
+At the heart of MUSICA is the standalone Model Independent Chemistry Model (MICM), which is a gas-phase kinetic solver. MICM is made available by the MUSICA wrapper which satisfies the requirements of the Common Community Physics Package (CCPP)
+and that can be connected to any CCPP compliant atmosphere model.
+MUSICA and MICM will have a flexible design to handle a variety of gas phase and aerosol schemes
+and associated chemical modules such as deposition or photolysis.

docs/source/index.rst

@@ -16,14 +16,14 @@ Welcome to MUSICA's documentation!
 
     .. grid-item-card:: Getting started
         :img-top: _static/index_getting_started.svg
-        :link: getting_started
+        :link: getting_started/getting_started
         :link-type: doc
 
         Check out the getting started guide to build and install musica.
 
     .. grid-item-card::  User guide
         :img-top: _static/index_user_guide.svg
-        :link: user_guide/index
+        :link: user_guide/user_guide
         :link-type: doc
 
     .. grid-item-card::  API reference
@@ -41,13 +41,14 @@ Welcome to MUSICA's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   getting_started
-   user_guide/index
+   getting_started/getting_started
+   user_guide/user_guide
+   tutorial/tutorial
    api/index
    contributing/index
 
-.. getting_started
-.. user_guide/index
+.. getting_started/getting_started
+.. user_guide/user_guid
 .. api/index
 .. contributing/index
 .. citing_and_bibliography/index

docs/source/tutorial/chapter1.rst

@@ -0,0 +1,43 @@
+Chapter 1
+=========
+
+First Fortran MUSICA Program
+----------------------------
+The MUSICA library can be used 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`:
+
+  .. literalinclude:: ../../../fortran/test/fetch_content_integration/test_get_micm_version.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.
+To print the version string we just want the fortran character array,
+accessed by ``get_char_array``.
+
+Now, to build this simple program,
+invoke the `gfortran` compiler and link to ``libmusica-fortran``, ``libmusica``,
+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++
+
+``<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``
+module definition files.
+
+When the `demo` program is run it should display the MICM version: 
+
+.. code-block:: bash
+
+  $ ./demo
+   MICM version 3.5.0
+  $
+

docs/source/tutorial/tutorial.rst

@@ -0,0 +1,9 @@
+########
+Tutorial
+########
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   chapter1.rst

docs/source/user_guide/fortran_c.rst

@@ -0,0 +1,78 @@
+##############
+Model Inteface
+##############
+
+Fortran C Interface Example
+---------------------------
+
+.. code-block:: cpp
+
+  #include <stdio.h>
+
+  void test_proc_c(int n, double A[3][2]) {
+
+      printf("test_proc_c\n");
+      printf("n = %d\n", n);
+
+      printf("matrix A\n");
+
+      for (int i = 0; i < 2; i++) {
+          for (int j = 0; j < 3; j++) {
+              printf("%6.2f ", A[j][i]);
+          }
+          printf("\n");
+      }
+  }
+
+
+.. code-block:: f90
+
+  program demo_fort
+      use iso_c_binding, only: c_int, c_double
+      implicit none
+      integer :: i, j
+      integer(c_int) :: n_fort = 7
+      real(c_double), dimension(2, 3) :: A_fort
+
+      interface
+          subroutine test_proc_c(n_c, A_c) bind(C, name='test_proc_c')
+              use iso_c_binding, only: c_int, c_double
+              integer(c_int), intent(in), value :: n_c
+              real(c_double), dimension(2, 3), intent(in) :: A_c
+          end subroutine test_proc_c
+      end interface
+
+      do j = 1, 3
+          do i = 1, 2
+              A_fort(i, j) = real(i + j, c_double)
+          end do
+      end do
+
+      call test_proc_c(n_fort, A_fort)
+  end program demo_fort
+
+.. code-block:: bash
+
+    all: test_proc_c.o demo_fort.o demo_fort
+
+    test_proc_c.o : test_proc_c.c
+        gcc -c test_proc_c.c
+
+    demo_fort.o : demo_fort.f90
+        gfortran -c demo_fort.f90
+
+    demo_fort : test_proc_c.o demo_fort.o
+        gfortran -o demo_fort demo_fort.o test_proc_c.o -lc
+
+    clean:
+        rm -f test_proc_c.o demo_fort.o demo_fort
+
+.. code-block:: console
+
+  $ ./demo_fort
+  test_proc_c
+  n = 7
+  matrix A
+    2.00   3.00   4.00 
+    3.00   4.00   5.00
+

docs/source/user_guide/model_interface.rst

@@ -0,0 +1,4 @@
+##############
+Model Inteface
+##############
+

docs/source/user_guide/user_guide.rst

@@ -0,0 +1,9 @@
+##########
+User Guide
+##########
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   model_interface

fortran/micm.F90

@@ -5,11 +5,16 @@ module musica_micm
    use musica_util, only: assert, mapping_t
    implicit none
 
-   public :: micm_t
+   public :: get_micm_version, micm_t
    private
 
 
    interface
+      function get_micm_version_c() bind(C, name="get_micm_version")
+         use musica_util, only: string_t_c
+         type(string_t_c) :: get_micm_version_c
+      end function get_micm_version_c
+
       function create_micm_c(config_path, error) bind(C, name="CreateMicm")
          use musica_util, only: error_t_c
          import c_ptr, c_int, c_char
@@ -122,6 +127,14 @@ end subroutine delete_mappings_c
 
 contains
 
+   function get_micm_version() result(value)
+      use musica_util, only: string_t, string_t_c
+      type(string_t)   :: value
+      type(string_t_c) :: string_c
+      string_c = get_micm_version_c()
+      value = string_t(string_c)
+   end function get_micm_version
+
    function constructor(config_path, error)  result( this )
       use musica_util, only: error_t_c, error_t, copy_mappings
       type(micm_t), pointer         :: this
@@ -257,4 +270,4 @@ subroutine finalize(this)
       ASSERT(error%is_success())
    end subroutine finalize
 
-end module musica_micm
+end module musica_micm

fortran/test/fetch_content_integration/CMakeLists.txt

@@ -32,6 +32,7 @@ enable_testing()
 # API Test
 if (MUSICA_ENABLE_MICM)
   add_executable(test_micm_fortran_api test_micm_api.F90)
+  add_executable(test_get_micm_version test_get_micm_version.F90)
 
   target_link_libraries(test_micm_fortran_api
     PRIVATE
@@ -48,6 +49,22 @@ if (MUSICA_ENABLE_MICM)
     COMMAND $<TARGET_FILE:test_micm_fortran_api>
     WORKING_DIRECTORY ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}
   )
+
+  target_link_libraries(test_get_micm_version
+    PRIVATE
+      musica::musica-fortran
+  )
+
+  set_target_properties(test_get_micm_version
+    PROPERTIES
+      LINKER_LANGUAGE Fortran
+  )
+
+  add_test(
+    NAME test_get_micm_version
+    COMMAND $<TARGET_FILE:test_get_micm_version>
+    WORKING_DIRECTORY ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}
+  )
 endif()
 
 # API Test
@@ -69,4 +86,4 @@ if (MUSICA_ENABLE_TUVX)
     COMMAND $<TARGET_FILE:test_tuvx_fortran_api>
     WORKING_DIRECTORY ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}
   )
-endif()
+endif()

fortran/test/fetch_content_integration/test_get_micm_version.F90

@@ -0,0 +1,8 @@
+program demo
+    use musica_util, only: string_t
+    use musica_micm, only: get_micm_version
+    implicit none
+    type(string_t) :: micm_version
+    micm_version = get_micm_version()
+    print *, "MICM version ", micm_version%get_char_array()
+end program demo

fortran/test/fetch_content_integration/test_micm_api.F90

@@ -2,8 +2,8 @@ program test_micm_api
 
   use, intrinsic :: iso_c_binding
   use, intrinsic :: ieee_arithmetic
-  use musica_micm, only: micm_t
-  use musica_util, only: assert, error_t, mapping_t
+  use musica_micm, only: micm_t, get_micm_version
+  use musica_util, only: assert, error_t, mapping_t, string_t
 
 #include "micm/util/error.hpp"
 
@@ -19,6 +19,7 @@ program test_micm_api
 
   subroutine test_api()
 
+    type(string_t)                :: micm_version
     type(micm_t), pointer         :: micm
     real(c_double)                :: time_step
     real(c_double)                :: temperature
@@ -43,6 +44,8 @@ subroutine test_api()
     num_user_defined_reaction_rates = 3
     user_defined_reaction_rates = (/ 0.1, 0.2, 0.3 /)
 
+    micm_version = get_micm_version()
+    print *, "[test micm fort api] MICM version ", micm_version%get_char_array()
 
     write(*,*) "[test micm fort api] Creating MICM solver..."
     micm => micm_t(config_path, error)

fortran/test/unit/CMakeLists.txt

@@ -4,6 +4,7 @@ create_standard_test_fortran(NAME fortran_util SOURCES util.F90)
 
 if (MUSICA_ENABLE_MICM)
   create_standard_test_fortran(NAME micm_fortran_api SOURCES ../fetch_content_integration/test_micm_api.F90)
+  create_standard_test_fortran(NAME get_micm_version SOURCES ../fetch_content_integration/test_get_micm_version.F90)
 endif()
 
 if (MUSICA_ENABLE_TUVX)
@@ -16,4 +17,4 @@ if (MUSICA_ENABLE_TUVX)
   if (MUSICA_ENABLE_MPI)
     create_standard_test_fortran(NAME connect_to_tuvx_mpi SOURCES tuvx_mpi.F90)
   endif()
-endif()
+endif()