musica 0.8.0__tar.gz → 0.9.0__tar.gz

{musica-0.8.0 → musica-0.9.0}/.github/workflows/pip.yml

@@ -13,7 +13,7 @@ jobs:
       fail-fast: false
       matrix:
         platform: [windows-latest, macos-13, ubuntu-latest]
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
         # python versions: https://devguide.python.org/versions/
 
     runs-on: ${{ matrix.platform }}

{musica-0.8.0 → musica-0.9.0}/CITATION.cff

@@ -64,4 +64,4 @@ number: 10
 page: "E1743 - E1760"
 doi: "10.1175/BAMS-D-19-0331.1"
 url: "https://journals.ametsoc.org/view/journals/bams/101/10/bamsD190331.xml"
-version: 0.8.0
+version: 0.9.0

{musica-0.8.0 → musica-0.9.0}/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.9.0)
 
 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH};${PROJECT_SOURCE_DIR}/cmake)
 set(CMAKE_USER_MAKE_RULES_OVERRIDE ${CMAKE_MODULE_PATH}/SetDefaults.cmake)
@@ -30,7 +30,7 @@ option(MUSICA_BUILD_DOCS "Build the documentation" OFF)
 option(MUSICA_ENABLE_MICM "Enable MICM" ON)
 option(MUSICA_ENABLE_TUVX "Enable TUV-x" ON)
 
-set(MUSICA_SET_MICM_VECTOR_MATRIX_SIZE "1" CACHE STRING "Set MICM vector-ordered matrix dimension")
+set(MUSICA_SET_MICM_VECTOR_MATRIX_SIZE "4" CACHE STRING "Set MICM vector-ordered matrix dimension")
 
 cmake_dependent_option(
   MUSICA_ENABLE_PYTHON_LIBRARY "Adds pybind11, a lightweight header-only library that exposes C++ types in Python and vice versa" OFF "MUSICA_BUILD_C_CXX_INTERFACE" OFF)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: musica
-Version: 0.8.0
+Version: 0.9.0
 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.9.0}/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 v.3.7.0)
 
   FetchContent_Declare(micm
       GIT_REPOSITORY ${MICM_GIT_REPOSITORY}
@@ -86,7 +86,7 @@ if (MUSICA_ENABLE_TUVX AND MUSICA_BUILD_C_CXX_INTERFACE)
   set(TUVX_INSTALL_INCLUDE_DIR ${MUSICA_INSTALL_INCLUDE_DIR} CACHE STRING "" FORCE)
 
   set_git_default(TUVX_GIT_REPOSITORY https://github.com/NCAR/tuv-x.git)
-  set_git_default(TUVX_GIT_TAG v0.10.0)
+  set_git_default(TUVX_GIT_TAG v0.10.1)
 
   FetchContent_Declare(tuvx
     GIT_REPOSITORY ${TUVX_GIT_REPOSITORY}
@@ -94,6 +94,9 @@ if (MUSICA_ENABLE_TUVX AND MUSICA_BUILD_C_CXX_INTERFACE)
     GIT_PROGRESS NOT ${FETCHCONTENT_QUIET}
   )
 
+  set(TUVX_ENABLE_TESTS OFF)
+  set(TUVX_ENABLE_REGRESSION_TESTS OFF)
+
   FetchContent_MakeAvailable(tuvx)
 endif()
 

musica-0.9.0/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.9.0/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.9.0/configs/chapman/config.json

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

{musica-0.8.0 → musica-0.9.0}/docker/Dockerfile.fortran-intel

@@ -1,5 +1,5 @@
 # versions and sizes from here: https://hub.docker.com/r/intel/oneapi-hpckit/tags
-FROM intel/oneapi-hpckit:latest
+FROM intel/oneapi-hpckit:2024.0.1-devel-ubuntu22.04
 
 # Based off of this: https://dgpu-docs.intel.com/driver/installation.html#repository-public-key-used-for-package-and-repository-signing
 # however those docs (at the time of this writing are incorrect) and this is the correct url

musica-0.9.0/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.9.0/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.9.0/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
+  $
+