add tutorial

open-atmos · Sep 6, 2021 · a51429f · a51429f
1 parent 2439ba6
commit a51429f
Show file tree

Hide file tree

Showing 52 changed files with 4,525 additions and 64 deletions.
diff --git a/.dockerignore b/.dockerignore
@@ -3,6 +3,7 @@
 
 # whitelist things to copy
 !CMakeLists.txt
+!doc/
 !docker/
 !src/
 !test/

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -11,6 +11,19 @@ set(PACKAGE_STRING "CAMP 1.0.0")
 set(PACKAGE_TARNAME "camp")
 set(PACKAGE_VERSION "1.0.0")
 
+if ( "${CMAKE_SYSTEM_NAME}" MATCHES "Darwin" )
+  set ( ENABLE_DYLIBS_USE_RPATH TRUE CACHE BOOL
+    "Enable @rpath install name for dylibs" )
+  mark_as_advanced ( ENABLE_DYLIBS_USE_RPATH )
+endif ()
+
+if ( ENABLE_DYLIBS_USE_RPATH )
+  set ( CMAKE_MACOSX_RPATH TRUE )
+else ()
+  set ( CMAKE_INSTALL_NAME_DIR
+    "${CMAKE_INSTALL_FULL_LIBDIR}" )
+endif ()
+
 ######################################################################
 # options
 
@@ -154,7 +167,7 @@ endif()
 
 macro(do_unit_test test_name result)
   if(ENABLE_MPI)
-    add_test(unit_test_${test_name} mpiexec_mpt -v -np 2 ${CMAKE_BINARY_DIR}/unit_test_${test_name})
+    add_test(unit_test_${test_name} mpirun -v -np 2 ${CMAKE_BINARY_DIR}/unit_test_${test_name})
   else()
     add_test(unit_test_${test_name} ${CMAKE_BINARY_DIR}/unit_test_${test_name})
   endif()
@@ -168,7 +181,8 @@ endmacro(do_unit_test)
 add_custom_target(copy_test ALL ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/test ${CMAKE_BINARY_DIR}/test_run)
 add_custom_target(copy_mechanism ALL ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/mechanisms ${CMAKE_BINARY_DIR}/mechanisms_run)
 add_custom_target(copy_scenario ALL ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/scenarios ${CMAKE_BINARY_DIR}/scenarios_run)
-set_property(DIRECTORY PROPERTY ADDITIONAL_MAKE_CLEAN_FILES test_run mechanisms_run scenarios_run)
+add_custom_target(copy_boot_camp ALL ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/doc/camp_tutorial/boot_camp ${CMAKE_BINARY_DIR}/boot_camp_run)
+set_property(DIRECTORY PROPERTY ADDITIONAL_MAKE_CLEAN_FILES test_run mechanisms_run scenarios_run boot_camp_run)
 
 ######################################################################
 # tests
@@ -211,6 +225,10 @@ add_test(test_chemistry_cb05cl_ae5 ${CMAKE_BINARY_DIR}/test_run/chemistry/cb05cl
 add_test(test_chemistry_eqsam_v03d ${CMAKE_BINARY_DIR}/test_run/chemistry/eqsam_v03d/test_chemistry_eqsam_v03d.sh ${MPI_TEST_FLAG})
 add_test(test_MONARCH_1 ${CMAKE_BINARY_DIR}/test_run/monarch/test_monarch_1.sh ${MPI_TEST_FLAG})
 add_test(test_MONARCH_2 ${CMAKE_BINARY_DIR}/test_run/monarch/test_monarch_2.sh ${MPI_TEST_FLAG})
+add_test(boot_camp_part_1 ${CMAKE_BINARY_DIR}/boot_camp_run/part_2_code/run_part_1.sh ${MPI_TEST_FLAG})
+add_test(boot_camp_part_2 ${CMAKE_BINARY_DIR}/boot_camp_run/part_2_code/run_part_2.sh ${MPI_TEST_FLAG})
+add_test(boot_camp_part_3 ${CMAKE_BINARY_DIR}/boot_camp_run/part_3_code/run_part_3.sh ${MPI_TEST_FLAG})
+add_test(boot_camp_part_4 ${CMAKE_BINARY_DIR}/boot_camp_run/part_4_code/run_part_4.sh ${MPI_TEST_FLAG})
 
 ######################################################################
 # camp library
@@ -332,7 +350,7 @@ else()
   set(CAMP_CUDA_SRC "")
 endif()
 
-add_library(camplib
+set(CAMP_LIB_SRC
   src/constants.F90
   src/util.F90
   src/mpi.F90
@@ -348,9 +366,44 @@ add_library(camplib
   ${CAMP_C_SRC} ${AEROSOL_REPS_SRC} ${SUB_MODELS_SRC} ${REACTIONS_SRC}
   ${CAMP_CUDA_SRC} ${GSL_SRC} ${CAMP_CXX_SRC} )
 
+add_library(camplib SHARED ${CAMP_LIB_SRC})
+add_library(camplib-static STATIC ${CAMP_LIB_SRC})
+
 target_link_libraries(camplib ${SUNDIALS_LIBS} ${GSL_LIBS} ${JSON_LIB})
+target_link_libraries(camplib-static ${SUNDIALS_LIBS} ${GSL_LIBS} ${JSON_LIB})
+
+set(MODULE_DIR "${CMAKE_BINARY_DIR}/include")
+
+set_target_properties(camplib PROPERTIES
+                         OUTPUT_NAME camp
+                         PREFIX lib
+                         VERSION ${PACKAGE_VERSION}
+                         SOVERSION ${PACKAGE_VERSION}
+                         LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib
+                         Fortran_MODULE_DIRECTORY ${CMAKE_BINARY_DIR})
+set_target_properties(camplib-static PROPERTIES
+                         OUTPUT_NAME camp
+                         PREFIX lib
+                         VERSION ${PACKAGE_VERSION}
+                         ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib
+                         Fortran_MODULE_DIRECTORY ${MODULE_DIR})
 
-set_target_properties(camplib PROPERTIES OUTPUT_NAME camp)
+######################################################################
+# Install options
+
+include(GNUInstallDirs)
+install(TARGETS camplib camplib-static
+        EXPORT camplib-targets
+        LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}"
+        ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}"
+       )
+
+set(MOD_DIR_TO_INSTALL "${MODULE_DIR}")
+set(MOD_DESTINATION_DIR "${CMAKE_INSTALL_INCLUDEDIR}/camp")
+install(
+  CODE "file(GLOB_RECURSE MODULE_FILES \"${MOD_DIR_TO_INSTALL}/*.mod\")"
+  CODE "file(INSTALL \${MODULE_FILES} DESTINATION \"\${CMAKE_INSTALL_PREFIX}/${MOD_DESTINATION_DIR}\")"
+  )
 
 ######################################################################
 # camp-chem box model
@@ -562,3 +615,28 @@ add_executable(test_chem_mech_solver test/chemistry/test_chem_mech_solver.F90)
 target_link_libraries(test_chem_mech_solver camplib)
 
 ######################################################################
+# BootCAMP Tutorial Exercises
+######################################################################
+
+######################################################################
+# Part 1
+
+add_executable(boot_camp_part_1 doc/camp_tutorial/boot_camp/part_1_code/box_model.F90)
+
+target_link_libraries(boot_camp_part_1 camplib)
+
+######################################################################
+# Part 3
+
+add_executable(boot_camp_part_3 doc/camp_tutorial/boot_camp/part_3_code/box_model.F90)
+
+target_link_libraries(boot_camp_part_3 camplib)
+
+######################################################################
+# Part 4
+
+add_executable(boot_camp_part_4 doc/camp_tutorial/boot_camp/part_4_code/box_model.F90)
+
+target_link_libraries(boot_camp_part_4 camplib)
+
+######################################################################
diff --git a/Dockerfile b/Dockerfile
@@ -48,15 +48,18 @@ RUN tar -zxvf /camp/cvode-3.4-alpha.tar.gz \
              .. \
     && make install
 
+# Update environment variables
+ENV LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib:/usr/local/lib64:/usr/local/jsonfortran-gnu-6.1.0/lib"
+ENV PATH="${PATH}:/usr/local/jsonfortran-gnu-6.1.0/lib"
+
 # Build CAMP
  RUN mkdir build \
     && cd build \
     && export JSON_FORTRAN_HOME="/usr/local/jsonfortran-gnu-6.1.0" \
     && cmake -D CMAKE_BUILD_TYPE=release \
-             -D CMAKE_C_FLAGS_DEBUG="-g" \
-             -D CMAKE_Fortran_FLAGS_DEBUG="-g" \
+             -D CMAKE_C_FLAGS_DEBUG="-pg" \
+             -D CMAKE_Fortran_FLAGS_DEBUG="-pg" \
+             -D CMAKE_MODULE_LINKER_FLAGS="-pg" \
              -D ENABLE_GSL:BOOL=TRUE \
-             -D SUNDIALS_CVODE_LIB=/usr/local/lib/libsundials_cvode.so \
-             -D SUNDIALS_INCLUDE_DIR=/usr/local/include \
              /camp \
-    && make
+    && make install
diff --git a/Dockerfile.mpi b/Dockerfile.mpi
@@ -0,0 +1,77 @@
+FROM fedora:27
+
+RUN dnf -y update \
+    && dnf install -y sudo \
+    && adduser test_user \
+    && echo "test_user ALL=(root) NOPASSWD:ALL" > /etc/sudoers.d/test_user \
+    && chmod 0440 /etc/sudoers.d/test_user
+
+USER test_user
+WORKDIR /home/test_user
+
+RUN sudo dnf -y install \
+        openmpi-devel \
+        gcc-gfortran \
+        gcc-c++ \
+        gsl-devel \
+        metis-devel \
+        lapack-devel \
+        openblas-devel \
+        cmake \
+    && sudo dnf clean all
+ENV PATH="${PATH}:/usr/lib64/openmpi/bin/"
+
+# Build the SuiteSparse libraries for sparse matrix support
+RUN curl -kLO http://faculty.cse.tamu.edu/davis/SuiteSparse/SuiteSparse-5.1.0.tar.gz \
+    && tar -zxvf SuiteSparse-5.1.0.tar.gz \
+    && export CXX=/usr/bin/cc \
+    && cd SuiteSparse \
+    && sudo make install INSTALL=/usr/local BLAS="-L/lib64 -lopenblas"
+
+# Install json-fortran
+RUN curl -LO https://github.com/jacobwilliams/json-fortran/archive/6.1.0.tar.gz \
+    && tar -zxvf 6.1.0.tar.gz \
+    && cd json-fortran-6.1.0 \
+    && export FC=gfortran \
+    && mkdir build \
+    && cd build \
+    && cmake -D SKIP_DOC_GEN:BOOL=TRUE .. \
+    && sudo make install
+
+# NOTE: Modify .dockerignore to whitelist files/directories to copy.
+COPY . /home/test_user/camp/
+
+# Install a modified version of CVODE
+RUN tar -zxvf /home/test_user/camp/cvode-3.4-alpha.tar.gz \
+    && cd cvode-3.4-alpha \
+    && mkdir build \
+    && cd build \
+    && cmake -D CMAKE_BUILD_TYPE=release \
+             -D CMAKE_C_FLAGS_DEBUG="-g -pg" \
+             -D CMAKE_EXE_LINKER_FLAGS_DEBUG="-pg" \
+             -D CMAKE_MODULE_LINKER_FLAGS_DEBUG="-pg" \
+             -D CMAKE_SHARED_LINKER_FLAGS_DEBUG="-pg" \
+             -D KLU_ENABLE:BOOL=TRUE \
+             -D KLU_LIBRARY_DIR=/usr/local/lib \
+             -D KLU_INCLUDE_DIR=/usr/local/include \
+             .. \
+    && sudo make install
+
+# Update environment variables
+ENV LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib:/usr/local/lib64:/usr/local/jsonfortran-gnu-6.1.0/lib"
+ENV PATH="${PATH}:/usr/local/jsonfortran-gnu-6.1.0/lib"
+
+# Build CAMP
+ RUN mkdir build \
+    && cd build \
+    && export JSON_FORTRAN_HOME="/usr/local/jsonfortran-gnu-6.1.0" \
+    && cmake -D CMAKE_BUILD_TYPE=release \
+             -D CMAKE_C_FLAGS_DEBUG="-g -pg" \
+             -D CMAKE_Fortran_FLAGS_DEBUG="-g -pg" \
+             -D CMAKE_MODULE_LINKER_FLAGS="-pg" \
+             -D ENABLE_DEBUG:BOOL=TRUE \
+             -D ENABLE_MPI:BOOL=TRUE \
+             -D CMAKE_Fortran_COMPILER=/usr/lib64/openmpi/bin/mpif90 \
+             ../camp \
+    && make \
+    && sudo make install
diff --git a/README.md b/README.md
@@ -5,15 +5,13 @@ CAMP
 CAMP: Chemistry Across Multiple Phases
 
 [![Latest version](https://img.shields.io/github/tag/open-atmos/camp.svg?label=version)](https://github.com/open-atmos/camp/blob/main/ChangeLog.md)
-[![Docker build status](https://img.shields.io/docker/automated/open-atmos/camp.svg)](https://cloud.docker.com/swarm/compdyn/repository/docker/openatmos/camp/builds)
 [![CI Status](https://github.com/open-atmos/camp/actions/workflows/main.yml/badge.svg)](https://github.com/open-atmos/camp/actions/workflows/main.yml)
 [![License](https://img.shields.io/github/license/open-atmos/camp.svg)](https://github.com/open-atmos/camp/blob/main/COPYING)
 
-Version -.-.-
-Released -
-
 <http://open-atmos.org/camp/>
 
+The full CAMP documentation, including the BootCAMP tutorial is available [here](https://open-atmos.github.io/camp).
+
 References:
 
    * M. Dawson, C. Guzman, J. H. Curtis, M. Acosta, S. Zhu, D. Dabdub,
@@ -37,7 +35,7 @@ This is the fastest way to get running.
 * **_Step 2:_** Run the CAMP test suite with:
 
 ```text
-docker run -it --rm openatmos/camp bash -c 'cd /build; make test'
+docker run -it --rm ghcr.io/open-atmos/camp:main bash -c 'cd /build; make test'
 ```
 
 
@@ -51,7 +49,7 @@ Required dependencies:
    * json-fortran for JSON input file support -
      <https://github.com/jacobwilliams/json-fortran>
    * SuiteSparse - <http://faculty.cse.tamu.edu/davis/SuiteSparse/SuiteSparse-5.1.0.tar.gz>
-   * A modified version of CVODE 3.1.2 - <https://github.com/mattldawson/cvode>
+   * A modified version of CVODE 3.1.2 - provided here in `cvode-3.4-alpha.tar.gz`
 
 Optional dependencies:
 

diff --git a/doc/Doxyfile b/doc/Doxyfile
@@ -864,7 +864,10 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../src
+INPUT                  = ../src \
+                         camp_tutorial \
+                         ../Dockerfile \
+                         ../Dockerfile.mpi
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -969,7 +972,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = camp_tutorial
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -983,13 +986,14 @@ EXAMPLE_PATTERNS       = *
 # irrespective of the value of the RECURSIVE tag.
 # The default value is: NO.
 
-EXAMPLE_RECURSIVE      = NO
+EXAMPLE_RECURSIVE      = YES
 
 # The IMAGE_PATH tag can be used to specify one or more files or directories
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = images/ \
+                         diagrams/
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1204,7 +1208,7 @@ HTML_HEADER            =
 # that doxygen normally uses.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_FOOTER            =
+HTML_FOOTER            = doxygen_footer.html
 
 # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style
 # sheet that is used by each HTML page. It can be used to fine-tune the look of
@@ -1229,7 +1233,7 @@ HTML_STYLESHEET        =
 # list). For an example see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_STYLESHEET  = doxygen_html_style.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -2284,7 +2288,7 @@ EXTERNAL_PAGES         = YES
 # powerful graphs.
 # The default value is: YES.
 
-CLASS_DIAGRAMS         = NO
+CLASS_DIAGRAMS         = YES
 
 # You can include diagrams made with dia in doxygen documentation. Doxygen will
 # then run dia to produce the diagram and insert it in the documentation. The
@@ -2357,7 +2361,7 @@ CLASS_GRAPH            = YES
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-COLLABORATION_GRAPH    = NO
+COLLABORATION_GRAPH    = YES
 
 # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for
 # groups, showing the direct groups dependencies.
@@ -2445,7 +2449,7 @@ INCLUDED_BY_GRAPH      = YES
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-CALL_GRAPH             = NO
+CALL_GRAPH             = YES
 
 # If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller
 # dependency graph for every global function or class method.
@@ -2457,7 +2461,7 @@ CALL_GRAPH             = NO
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-CALLER_GRAPH           = NO
+CALLER_GRAPH           = YES
 
 # If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical
 # hierarchy of all classes instead of a textual one.
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,6 +3,7 @@ @@
     # whitelist things to copy
     !CMakeLists.txt
+    !doc/
     !docker/
     !src/
     !test/
@@ Expand Down @@