musica 0.8.0__tar.gz → 0.8.1__tar.gz

{musica-0.8.0 → musica-0.8.1}/CMakeLists.txt

@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.21)
 
 # must be on the same line so that pyproject.toml can correctly identify the version
-project(musica-distribution VERSION 0.8.0)
+project(musica-distribution VERSION 0.8.1)
 
 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH};${PROJECT_SOURCE_DIR}/cmake)
 set(CMAKE_USER_MAKE_RULES_OVERRIDE ${CMAKE_MODULE_PATH}/SetDefaults.cmake)

{musica-0.8.0 → musica-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: musica
-Version: 0.8.0
+Version: 0.8.1
 Summary: MUSICA is a Python library for performing computational simulations in atmospheric chemistry.
 Home-page: https://wiki.ucar.edu/display/MUSICA/MUSICA+Home
 Author-Email: Matthew Dawsom <mattdawson@ucar.edu>, Jiwon Gim <jiwongim@ucar.edu>, David Fillmore <fillmore@ucar.edu>, Kyle Shores <kshores@ucar.edu>

{musica-0.8.0 → musica-0.8.1}/cmake/dependencies.cmake

@@ -62,7 +62,7 @@ endif()
 if (MUSICA_ENABLE_MICM AND MUSICA_BUILD_C_CXX_INTERFACE)
 
   set_git_default(MICM_GIT_REPOSITORY https://github.com/NCAR/micm.git)
-  set_git_default(MICM_GIT_TAG v3.6.0)
+  set_git_default(MICM_GIT_TAG b3c462a)
 
   FetchContent_Declare(micm
       GIT_REPOSITORY ${MICM_GIT_REPOSITORY}

musica-0.8.1/configs/analytical/reactions.json

@@ -0,0 +1,71 @@
+{
+  "camp-data": [
+    {
+      "type": "MECHANISM",
+      "name": "music box interactive configuration",
+      "reactions": [
+        {
+          "type": "ARRHENIUS",
+          "A": 0.004,
+          "C": 50,
+          "reactants": {
+            "A": {
+              "qty": 1
+            }
+          },
+          "products": {
+            "B": {
+              "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 1",
+          "reactants": {
+            "D": {
+              "qty": 1
+            }
+          },
+          "products": {
+            "E": {
+              "yield": 1
+            }
+          }
+        },
+        {
+          "type": "USER_DEFINED",
+          "MUSICA name": "reaction 2",
+          "reactants": {
+            "E": {
+              "qty": 1
+            }
+          },
+          "products": {
+            "F": {
+              "yield": 1
+            }
+          }
+        }
+      ]
+    }
+  ]
+}

musica-0.8.1/configs/analytical/species.json

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

musica-0.8.1/configs/chapman/config.json

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

musica-0.8.1/docs/source/tutorial/chapter0.rst

@@ -0,0 +1,86 @@
+Chapter 0
+=========
+
+.. _installing_musica:
+
+Installing MUSICA
+-----------------
+
+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.
+
+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.
+
+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
+
+  sudo dnf install -y cmake git gcc-c++ gcc-gfortran netcdf-devel netcdf-fortran-devel
+
+On other distributions or operating systems, you may need to install the dependencies
+using the package manager for your system.
+
+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
+
+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
+
+  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.)
+
+

musica-0.8.1/docs/source/tutorial/chapter1.rst

@@ -0,0 +1,75 @@
+.. _chapter1:
+
+Chapter 1
+=========
+
+First Fortran MUSICA 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.
+
+Save the following code to a file named `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 the ``get_char_array`` function.
+
+Now, to build this simple program,
+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>/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 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.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
+  $

musica-0.8.1/docs/source/tutorial/chapter2.rst

@@ -0,0 +1,86 @@
+Chapter 2
+=========
+
+An MICM Box Model Example in Fortran
+--------------------------------------
+
+In this next MUSICA Fortran example,
+we will setup a MICM solver, starting with a set of MICM configuration files,
+and run the solver for a single integration time step.
+
+The following three configuration files (``config.json``, ``species.json``, and ``reactions.json``)
+should be saved in a subdirectory named ``configs/analytical`` relative directory
+from which you plan to call the box model executable.
+
+(You can find a copy of these files in the MUSICA repository at ``configs/analytical``.)
+
+The top-level MICM configuration ``config.json`` file
+simply lists the configuration files to parse. In this case, these are the 
+chemical species configuration file ``species.json`` and
+the reactions configuration file ``reactions.json``.
+
+The contents of the ``config.json`` file for this example are:
+
+  .. literalinclude:: ../../../configs/analytical/config.json
+    :language: json
+
+For this example, we will have a system of three chemical species
+`A`, `B`, and `C`, defined in the JSON file ``species.json`` as follows:
+
+  .. literalinclude:: ../../../configs/analytical/species.json
+    :language: json
+
+The ``reactions.json`` specifies a mechanism, or a set of reactions for the system.
+Here, we will introduce two Arrhenius type reactions, the first
+with `B` evolving to `C`, and specifying all five reaction parameters,
+and the second reaction with `A` evolving to `B` and using only two reaction parameters.
+
+We also include two reactions with rate constants that are provided by the host
+application at runtime. These types of reactions are useful when outside calculations
+are needed to determine the rate constants, such as in the case of photolysis reactions.
+
+The ``reactions.json`` file for this example should look like this:
+
+  .. literalinclude:: ../../../configs/analytical/reactions.json
+    :language: json
+
+More information on MICM configurations and reactions can be found in the `MICM documentation
+<https://ncar.github.io/micm/user_guide/>`_
+
+To create a simple box model, save the following Fortran code to a file named ``micm_box_model.F90``: 
+
+  .. literalinclude:: ../../../fortran/test/fetch_content_integration/test_micm_box_model.F90
+    :language: f90
+
+From the ``musica_util`` module we need the Fortran types
+``error_t``, ``string_t``, and ``mapping_t``.
+A pointer to a ``musica_micm::micm_t`` will serve as the interface to the MICM solver
+(in the example the pointer name is ``micm``).
+Note that the ``config_path`` in the code sample has been set to ``configs/analytical``,
+so that subdirectory should be created relative to the main program and contain
+the MICM JSON configuration files,
+otherwise the ``config_path`` should be modified appropriately.
+The initial species concentrations are initialized in the ``concentrations`` array,
+which is an argument to the MICM solver.
+
+Finally, a single time step solution is obtained through a call to ``micm%solve``,
+after which the updated concentrations may be displayed.
+
+To build the example, follow the instructions in :ref:`chapter1`.
+
+Assuming you name the executable ``micm_box_model``, you can run the program as follows:
+
+.. code-block:: bash
+
+  $ ./micm_box_model
+ Creating MICM solver...
+ Species Name:A, Index:           1
+ Species Name:B, Index:           2
+ Species Name:C, Index:           5
+ Species Name:D, Index:           3
+ Species Name:E, Index:           4
+ Species Name:F, Index:           6
+ Solving starts...
+ After solving, concentrations  0.38236272259073301        1.4676807523204496       0.67030703490468713        1.1155750798779909        1.1499565250888166        1.2141178852173222
+  $
+

{musica-0.8.0 → musica-0.8.1}/fortran/micm.F90

@@ -22,7 +22,6 @@ module musica_micm
     integer(c_int64_t) :: rejected_ = 0_c_int64_t
     integer(c_int64_t) :: decompositions_ = 0_c_int64_t
     integer(c_int64_t) :: solves_ = 0_c_int64_t
-    integer(c_int64_t) :: singular_ = 0_c_int64_t
     real(c_double)     :: final_time_ = 0._c_double
   end type solver_stats_t_c
 
@@ -162,7 +161,6 @@ module musica_micm
     integer(int64) :: rejected_
     integer(int64) :: decompositions_
     integer(int64) :: solves_
-    integer(int64) :: singular_
     real           :: final_time_
   contains
     procedure :: function_calls => solver_stats_t_function_calls
@@ -172,7 +170,6 @@ module musica_micm
     procedure :: rejected => solver_stats_t_rejected
     procedure :: decompositions => solver_stats_t_decompositions
     procedure :: solves => solver_stats_t_solves
-    procedure :: singular => solver_stats_t_singular
     procedure :: final_time => solver_stats_t_final_time
   end type solver_stats_t
 
@@ -286,7 +283,6 @@ contains
     new_solver_stats%rejected_ = c_solver_stats%rejected_
     new_solver_stats%decompositions_ = c_solver_stats%decompositions_
     new_solver_stats%solves_ = c_solver_stats%solves_
-    new_solver_stats%singular_ = c_solver_stats%singular_
     new_solver_stats%final_time_ = real( c_solver_stats%final_time_ )
 
   end function solver_stats_t_constructor
@@ -361,16 +357,6 @@ contains
 
   end function solver_stats_t_solves
 
-  !> Get the number of times a singular matrix is detected
-  function solver_stats_t_singular( this ) result( singular )
-    use iso_fortran_env, only: int64
-    class(solver_stats_t), intent(in) :: this
-    integer(int64)                    :: singular
-
-    singular = this%function_calls_
-
-  end function solver_stats_t_singular
-
   !> Get the final time the solver iterated to
   function solver_stats_t_final_time( this ) result( final_time )
     class(solver_stats_t), intent(in) :: this

{musica-0.8.0 → musica-0.8.1}/fortran/test/fetch_content_integration/test_get_micm_version.F90

@@ -1,8 +1,12 @@
 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

{musica-0.8.0 → musica-0.8.1}/fortran/test/fetch_content_integration/test_micm_api.F90

@@ -135,7 +135,6 @@ contains
     write(*,*) "[test micm fort api] Rejected: ", solver_stats%rejected()
     write(*,*) "[test micm fort api] Decompositions: ", solver_stats%decompositions()
     write(*,*) "[test micm fort api] Solves: ", solver_stats%solves()
-    write(*,*) "[test micm fort api] Singular: ", solver_stats%singular()
     write(*,*) "[test micm fort api] Final time: ", solver_stats%final_time()
 
     string_value = micm%get_species_property_string( "O3", "__long name", error )

{musica-0.8.0 → musica-0.8.1}/fortran/test/tutorial/CMakeLists.txt

@@ -6,18 +6,14 @@ project(
   LANGUAGES CXX C Fortran
 )
 
-# mkdir build
-# cd build
-# cmake -DMUSICA_INSTALL_DIR=<musica_install_dir> ..
-
 set(MUSICA_INCLUDE_DIR "${MUSICA_INSTALL_DIR}/include")
-set(MUSICA_LIB_DIR "${MUSICA_INSTALL_DIR}/lib")
+set(MUSICA_LIB_DIR "${MUSICA_INSTALL_DIR}/lib64")
 
 message(STATUS "${MUSICA_INCLUDE_DIR}")
 message(STATUS "${MUSICA_LIB_DIR}")
 
-add_executable(demo_f demo.f90)
+add_executable(demo_f demo.F90)
 
 target_include_directories(demo_f PUBLIC ${MUSICA_INCLUDE_DIR})
 target_link_directories(demo_f PUBLIC ${MUSICA_LIB_DIR})
-target_link_libraries(demo_f musica-fortran musica stdc++)
+target_link_libraries(demo_f musica-fortran musica stdc++ yaml-cpp)

musica-0.8.0/fortran/test/tutorial/demo.f90 → musica-0.8.1/fortran/test/tutorial/demo.F90

@@ -1,8 +1,12 @@
 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

{musica-0.8.0 → musica-0.8.1}/fortran/test/unit/CMakeLists.txt

@@ -4,7 +4,7 @@ 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)
   create_standard_test_fortran(NAME micm_box_model SOURCES ../fetch_content_integration/test_micm_box_model.F90)
-  create_standard_test_fortran(NAME demo_fortran SOURCES ../tutorial/demo.f90)
+  create_standard_test_fortran(NAME demo_fortran SOURCES ../tutorial/demo.F90)
 endif()
 
 if (MUSICA_ENABLE_TUVX)