YAML configuration

CMakeLists.txt

@@ -19,8 +19,14 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CXX_EXTENSIONS ON)
 
 # install Kokkos for project
-message(STATUS "Using Kokkos installation from: ${CMAKE_SOURCE_DIR}/extern/kokkos")
-add_subdirectory(${CMAKE_SOURCE_DIR}/extern/kokkos)
+set(kokkospath ${CMAKE_SOURCE_DIR}/extern/kokkos)
+message(STATUS "Using Kokkos installation from: ${kokkospath}")
+add_subdirectory(${kokkospath})
+
+# install yaml-cpp for project
+set(yamlcpppath ${CMAKE_SOURCE_DIR}/extern/yaml-cpp)
+message(STATUS "Using yaml-cpp installation from: ${yamlcpppath}")
+add_subdirectory(${yamlcpppath})
 
 # print default compiler flags
 message(STATUS "CMAKE_CXX_FLAGS: ${CMAKE_CXX_FLAGS}")

docs/source/index.rst

@@ -31,6 +31,7 @@ Time to get involved! Start by :doc:`installing CLEO<usage/installation>` and ex
 
    intro/intro
    usage/requirements
+   usage/extern
    usage/installation
    usage/examples
    usage/quickstart

docs/source/pySD/pySD.rst

@@ -22,6 +22,7 @@ input files and processing the Zarr output from CLEO.
    thermobinary_src/thermobinary_src
    sdmout_src/sdmout_src
    cxx2py
+   readconfigfile
    editconfigfile
    readbinary
    writebinary

docs/source/pySD/readconfigfile.rst

@@ -0,0 +1,5 @@
+READCONFIGFILE
+==============
+
+.. automodule:: pySD.readconfigfile
+   :members:

docs/source/usage/extern.rst

@@ -0,0 +1,31 @@
+External Libraries
+==================
+
+CLEO depends upon Kokkos and may depend upon some additional external libraries such as YAC and
+``yaml-cpp`` depending on your setup. These are automatically built using CMAKE and compiled if
+required.
+
+.. note::
+  The installation of YAC for CLEO is currently in development and may require some manual installation.
+
+Kokkos
+------
+All builds of CLEO require Kokkos in order to implement thread parallelism. You can read more about
+how we use Kokkos on :doc:`our page about Kokkos<../intro/kokkos>`.
+
+YAC
+---
+YAC is required if CLEO couples to dynamics using YAC and/or uses MPI domain decompoisiton. You can
+find more information about it from `its documentation: <https://dkrz-sw.gitlab-pages.dkrz.de/yac>`_.
+
+TODO(all): Detail how to install YAC for CLEO.
+
+yaml-cpp
+--------
+CLEO's ``initialise`` library depends on the ```yaml-cpp``` package to read and write YAML files. You
+can find more information about it from `its repository: <https://github.com/jbeder/yaml-cpp>`_.
+
+CVODE
+-----
+CLEO's ``coupldyn_cvode`` library requires the SUNDIALS CVODE package. You can find more information
+about it from `its webpage: <https://computing.llnl.gov/projects/sundials/cvode>`_.

docs/source/usage/requirements.rst

@@ -63,9 +63,14 @@ You can install Python packages to an existing Conda (or Mamba) environment via:
 YAC
 ---
 
-To use YAC some additional MPI, NetCDF and yaml libraries are required alongside the gcc compiler.
+.. note::
+  The installation of YAC for CLEO is currently in development and may require some manual installation.
 
-You can load them on Levante via:
+YAC is one of the :doc:`external libraries<extern>` which CLEO may require in order to
+couple to dynamics and/or have MPI domain decomposition.
+
+YAC requires some additional MPI, NetCDF and yaml libraries alongside the gcc compiler. You can
+load them on Levante via:
 
 .. code-block:: console
 

examples/adiabaticparcel/as2017.py

@@ -8,7 +8,7 @@
 Author: Clara Bayley (CB)
 Additional Contributors:
 -----
-Last Modified: Friday 12th April 2024
+Last Modified: Thursday 18th April 2024
 Modified By: CB
 -----
 License: BSD 3-Clause "New" or "Revised" License
@@ -80,30 +80,28 @@
 
 # parameters to edit in model configuration and plotting
 params1 = {
-    "W_AVG": 1,
-    "T_HALF": 150,
+    "W_avg": 1,
+    "TAU_half": 150,
     "T_END": 300,
     "COUPLTSTEP": 1,
     "OBSTSTEP": 2,
-    "lwdth": 2,
 }
 params2 = {
-    "W_AVG": 0.5,
-    "T_HALF": 300,
+    "W_avg": 0.5,
+    "TAU_half": 300,
     "T_END": 600,
     "COUPLTSTEP": 1,
     "OBSTSTEP": 2,
-    "lwdth": 1,
 }
 params3 = {
-    "W_AVG": 0.002,
-    "T_HALF": 75000,
+    "W_avg": 0.002,
+    "TAU_half": 75000,
     "T_END": 150000,
     "COUPLTSTEP": 3,
     "OBSTSTEP": 750,
-    "lwdth": 0.5,
 }
 paramslist = [params1, params2, params3]
+lwdths = [2, 1, 0.5]
 
 def displacement(time, w_avg, thalf):
     '''displacement z given velocity, w, is sinusoidal
@@ -163,16 +161,16 @@ def displacement(time, w_avg, thalf):
         plt.close()
 
     fig, axs = plt.subplots(nrows=3, ncols=1, figsize=(5, 16))
-    for params in paramslist:
+    for params, lwdth in zip(paramslist, lwdths):
 
         ### edit relevant setup file parameters
         params["zarrbasedir"] = binpath+"as2017_sol"+str(runnum)+".zarr"
-        params["setuptxt"] = binpath+"as2017_setup.txt"
+        params["setup_filename"] = binpath+"as2017_setup.txt"
         editconfigfile.edit_config_params(configfile, params)
 
         ### delete any existing dataset
         os.system("rm -rf "+params["zarrbasedir"])
-        os.system("rm "+params["setuptxt"])
+        os.system("rm "+params["setup_filename"])
 
         ### run model
         os.chdir(path2build)
@@ -197,18 +195,18 @@ def displacement(time, w_avg, thalf):
         supersat = thermo.supersaturation()
         time = pyzarr.get_time(dataset).secs
         sddata = pyzarr.get_supers(dataset, consts)
-        zprof = displacement(time, config["W_AVG"], config["T_HALF"])
+        zprof = displacement(time, config["W_avg"], config["TAU_half"])
 
         attrs = ["radius", "xi", "msol"]
         sd0 = sdtracing.attributes_for1superdroplet(sddata, 0, attrs)
         numconc = np.sum(sddata["xi"][0])/gbxs["domainvol"]/1e6  # [/cm^3]
 
         ### plot results
-        wlab = "<w> = {:.1f}".format(config["W_AVG"]*100)+"cm s$^{-1}$"
+        wlab = "<w> = {:.1f}".format(config["W_avg"]*100)+"cm s$^{-1}$"
         axs = as2017fig.condensation_validation_subplots(axs, time, sd0["radius"],
                                                    supersat[:, 0, 0, 0],
                                                    zprof,
-                                                   lwdth=params["lwdth"],
+                                                   lwdth=lwdth,
                                                    lab=wlab)
 
         runnum += 1

examples/adiabaticparcel/as2017.sh

@@ -23,7 +23,7 @@ path2build=${HOME}/CLEO/build_adia0D/
 executables="adia0D"
 
 pythonscript=${path2CLEO}/examples/adiabaticparcel/as2017.py
-configfile=${path2CLEO}/examples/adiabaticparcel/src/config/as2017_config.txt
+configfile=${path2CLEO}/examples/adiabaticparcel/src/config/as2017_config.yaml
 script_args="${configfile}"
 ### ---------------------------------------------------- ###
 ### ---------------------------------------------------- ###

examples/adiabaticparcel/cuspbifurc.py

@@ -6,7 +6,7 @@
 Author: Clara Bayley (CB)
 Additional Contributors:
 -----
-Last Modified: Friday 12th April 2024
+Last Modified: Thursday 18th April 2024
 Modified By: CB
 -----
 License: BSD 3-Clause "New" or "Revised" License
@@ -149,7 +149,7 @@ def displacement(time, w_avg, thalf):
 supersat = thermo.supersaturation()
 time = pyzarr.get_time(dataset).secs
 sddata = pyzarr.get_supers(dataset, consts)
-zprof = displacement(time, config["W_AVG"], config["T_HALF"])
+zprof = displacement(time, config["W_avg"], config["TAU_half"])
 
 ### plot results
 # sample drops to plot from whole range of SD ids
@@ -169,5 +169,5 @@ def displacement(time, w_avg, thalf):
                                 thermo.temp[:, 0, 0, 0],
                                 supersat[:, 0, 0, 0],
                                 sddata.IONIC, sddata.MR_SOL,
-                                config["W_AVG"], numconc,
+                                config["W_avg"], numconc,
                                 savename2)

examples/adiabaticparcel/cuspbifurc.sh

@@ -23,7 +23,7 @@ path2build=${HOME}/CLEO/build_adia0D/
 executables="adia0D"
 
 pythonscript=${path2CLEO}/examples/adiabaticparcel/cuspbifurc.py
-configfile=${path2CLEO}/examples/adiabaticparcel/src/config/cuspbifurc_config.txt
+configfile=${path2CLEO}/examples/adiabaticparcel/src/config/cuspbifurc_config.yaml
 script_args="${configfile}"
 ### ---------------------------------------------------- ###
 ### ---------------------------------------------------- ###

examples/adiabaticparcel/src/config/as2017_config.yaml

@@ -0,0 +1,74 @@
+# ----- CLEO -----
+# File: as2017_config.yaml
+# Project: config
+# Created Date: Wednesday 17th April 2024
+# Author: Clara Bayley (CB)
+# Additional Contributors:
+# -----
+# Last Modified: Wednesday 17th April 2024
+# Modified By: CB
+# -----
+# License: BSD 3-Clause "New" or "Revised" License
+# https://opensource.org/licenses/BSD-3-Clause
+# -----
+# Copyright (c) 2023 MPI-M, Clara Bayley
+# -----
+# File Description:
+# Configuration file for CLEO SDM coupled to a CVODE dynamics solver for an adiabatic parcel example
+# Note: The inital superdroplets data read from file "initsupers_filename" can be made with
+# CLEO's pySD module (see Python script "create_initsuperdropsbinary_script.py" for usage).
+# Likewise the "grid_filename" can be made using pySD (see "create_gbxboundariesbinary_script.py"),
+# and so can the thermodynamics files when using coupled thermodynamics "fromfile".
+#
+
+### Initialisation Parameters ###
+inputfiles:
+  constants_filename: ../libs/cleoconstants.hpp            # name of file for values of physical constants
+  grid_filename: ./share/as2017_dimlessGBxboundaries.dat   # binary filename for initialisation of GBxs / GbxMaps
+
+initsupers:
+  type: frombinary                                         # type of initialisation of super-droplets
+  initsupers_filename: ./share/as2017_dimlessSDsinit.dat   # binary filename for initialisation of SDs
+  totnsupers: 64                                           # initial total no. of SDs
+
+### Output Parameters ###
+outputdata:
+  setup_filename: /home/m/m300950/CLEO/build_adia0D//bin/as2017_setup.txt   # .txt filename to copy configuration to
+  stats_filename: /home/m/m300950/CLEO/build_adia0D//bin/as2017_stats.txt   # .txt file to output runtime statistics to
+  zarrbasedir: /home/m/m300950/CLEO/build_adia0D//bin/as2017_sol8.zarr      # zarr store base directory
+  maxchunk: 2500000                                                         # maximum no. of elements in chunks of zarr store array
+
+### SDM Runtime Parameters ###
+domain:
+  nspacedims: 0                                        # no. of spatial dimensions to model
+  ngbxs: 1                                             # total number of Gbxs
+
+timesteps:
+  CONDTSTEP: 1                                         # time between SD condensation [s]
+  COLLTSTEP: 1                                         # time between SD collision [s]
+  MOTIONTSTEP: 1                                       # time between SDM motion [s]
+  COUPLTSTEP: 3                                        # time between dynamic couplings [s]
+  OBSTSTEP: 750                                        # time between SDM observations [s]
+  T_END: 150000                                        # time span of integration from 0s to T_END [s]
+
+### Microphysics Parameters ###
+microphysics:
+  condensation:
+    do_alter_thermo: true                              # true = cond/evap alters the thermodynamic state
+    niters: 2                                          # no. iterations of Newton Raphson Method before testing for convergence
+    SUBTSTEP: 0.1                                      # smallest subtimestep in cases of substepping [s]
+    rtol: 0.0                                          # relative tolerance for implicit Euler integration
+    atol: 0.01                                         # abolute tolerance for implicit Euler integration
+
+### Coupled Dynamics Parameters ###
+coupled_dynamics:
+  type: cvode                                           # type of coupled dynamics to configure
+  # initial (uniform) thermodynamic conditions #
+  P_init: 100000.0                                      # initial pressure [Pa]
+  TEMP_init: 273.15                                     # initial temperature [T]
+  relh_init: 98.0                                       # initial relative humidity (%)
+  # ODE solver parameters #
+  W_avg: 0.002                                          # average amplitude of sinusoidal w [m/s] (dP/dt ~ w*dP/dz)
+  TAU_half: 75000                                       # timescale for w sinusoid, tau_half = TAU_half/pi [s]
+  rtol: 1e-6                                            # relative tolerance for integration of [P, T, qv, qc] ODEs
+  atol: 1e-6                                            # relative tolerance for integration of [P, T, qv, qc] ODEs