Examples on “Vanilla” Computers

Having installed plotcleo, the following instructions are intended to guide you through running each example using the bash scripts in scripts/vanilla/.

Configure the Bash Scripts

These scripts work easiest when you first set certain environment variables. You can do this by adding the following lines to your .bashrc or .bash_profile file or execute these commands in your terminal before running any of the scripts:

export CLEO_PATH2CLEO=your/path/to/CLEO
export CLEO_PYTHON=your/path/to/python
export CLEO_YACYAXTROOT=your/path/to/yacyaxtroot
export CLEO_FYAMLLIB=your/path/to/fyaml/lib

On some systems you may need to specify the compiler wrappers for MPI. For example, on a Mac with Homebrew-installed OpenMPI and GCC-15, to prevent the clang compiler being used by default you may need to add:

export CC=gcc-15
export CXX=g++-15
export OMPI_CC=gcc-15
export OMPI_CXX=g++-15
export OMPI_FC=gfortran-15

The bash script for every example in scripts/vanilla/examples/ provides command line arguments to scripts/vanilla/examples/build_compile_run_plot.sh. This script has two steps:

1. It builds and compiles the specified exectuable(s) of Cleo by running scripts/vanilla/build_compile_cleo.sh [args]

2. It generates input files, runs the exectuable(s), and plots the results by calling the example’s Python script.

You will need to configure build_compile_run_plot.sh in the following ways:

• Use your Python version:

  replace the path in the line stating python=[...] with the path to your Python interpreter. (hint: if you used uv to install python for Cleo, you can find the interpreter path via uv python find.)

• Set the path to your YAC and YAXT installations

  replace yacyaxtroot=[...] with the path to the directory containing your yac and yaxt directories, or to yacyaxtroot="" if you do not intend to run an example that requires YAC.

You can optionally configure the bash script specific to each example (found in the same directory e.g. scripts/vanilla/examples/shima2009.sh) in the following ways:

• Choose your build configuration:

  choose which parallelism to utilise by modifying the buildtype parameter. The options are cuda, openmp or serial.

• Choose your compiler:

  choose which compilers to use via the compilername parameter. The options are intel or gcc (both via MPI wrappers). Note: the bubble3d example requires you use the gcc compiler.

• Choose your build directory:

  replace the path in the line stating path2build=[...] with the path you desire.

• If you did not install Cleo in your home directory:

  Ensure the lines which state the path2CLEO and path2build to reflect this.

The Examples

Adiabatic Parcel

The examples, as2017.py and cuspbifurc.py, in examples/adiabaticparcel/ are for a 0-D model of a parcel of air expanding and contracting adiabatically with a two-way coupling between the SDM microphysics and the thermodynamics. The setup mimics that in Arabas and Shima 2017 section 7 [AS17]. Note: due to numerical differences, the conditions for cusp bifurcation and the plots will not be exactly identical to this reference.

a) Arabas and Shima 2017

1. Configure the bash scripts, scripts/vanilla/examples/build_compile_run_plot.sh and scripts/vanilla/examples/as2017.sh.

2. Execute the bash script as2017.sh, e.g. from your Cleo directory:

$ scripts/vanilla/examples/as2017.sh

The plot produced, by default called ~/CLEO/build_adia0d/bin/as2017fig.png, should be similar to figure 5 from Arabas and Shima 2017 [AS17].

b) Cusp Bifurcation

1. Configure the bash scripts, scripts/vanilla/examples/build_compile_run_plot.sh and scripts/vanilla/examples/cuspbifurc.sh.

2. Execute the bash script cuspbifurc.sh, e.g. from your Cleo directory:

$ scripts/vanilla/examples/cuspbifurc.sh

The plots produced, by default called ~/CLEO/build_adia0d/bin/cuspbifurc_validation.png and ~/CLEO/build_adia0d/bin/cuspbifurc_SDgrowth.png illustrate an example of cusp bifurcation, analagous to the third column of figure 5 from Arabas and Shima 2017 [AS17].

Box Model Collisions

These examples, shima2009.py and breakup.py, in examples/boxmodelcollisions/ are for a 0-D box model with various collision kernels. The setup mimics that in Shima et al. 2009 section 5.1.4 [SKK+09]. Note: due to the randomness of the initial super-droplet conditions and the collision algorithm, each run of these examples will not be completely identical, but they should be reasonably similar, and have the same mean behaviour.

The Collision Kernels:

Golovin

The shima2009.py example models collision-coalescence using Golovin’s kernel.

The plot produced, by default called ~/CLEO/build_colls0d/[...]/bin/golovin_validation.png, should be similar to Fig.2(a) of Shima et al. 2009 [SKK+09].

Long

The shima2009.py example models collision-coalescence using Long’s collision efficiency as given by equation 13 of Simmel et al. 2002 [STT02].

The plot produced, by default called ~/CLEO/build_colls0d/[...]/bin/long_validation_[X].png, should be similar to Fig.2(b) of Shima et al. 2009 [SKK+09].

Low and List

The breakup.py example models collision-coalescence-rebound-breakup using the hydrodynamic kernel with Long’s collision efficiency as given by equation 13 of Simmel et al. 2002 [STT02], and the coalescence/breakup/rebound probability from Low and List 1982(a) [LL82] (see also McFarquhar 2004 [McF04]). If breakup occurs, a constant number of fragments is produced.

This example produces a plot, by default called ~/CLEO/build_colls0d/[...]/bin/lowlist_validation.png.

Szakáll and Urbich

The breakup.py example models collision-coalescence-rebound-breakup using the hydrodynamic kernel with Long’s collision efficiency as given by equation 13 of Simmel et al. 2002 [STT02], and the coalescence/breakup/rebound probability from Szakáll and Urbich 2018 [SU18]. If breakup occurs, a constant number of fragments is produced.

This example produces a plot, by default called ~/CLEO/build_colls0d/[...]/bin/szakallurbich_validation.png.

Testik and Straub

The breakup.py example models collision-coalescence-rebound-breakup using the hydrodynamic kernel with Long’s collision efficiency as given by equation 13 of Simmel et al. 2002 [STT02], and the coalescence/breakup/rebound probability based on section 4 of Testik et al. 2011 (figure 12) [TBB11] as well as coalescence efficiency and number of fragements produced from Straub et al. 2010 and Schlottke et al. 2010 respectively ([SSB+10], [SBS+10]).

This example produces a plot, by default called ~/CLEO/build_colls0d/[...]/bin/testikstraub_validation.png.

Running the Box Model Collisions Examples:

a) Shima et al. 2009

1. Configure the bash scripts, scripts/vanilla/examples/build_compile_run_plot.sh and scripts/vanilla/examples/shima2009.sh.

2. Execute the bash script shima2009.sh, e.g. from your Cleo directory:

$ scripts/vanilla/examples/shima2009.sh

By default the golovin exectuable and two examples using the long executable will be compiled and run. You can change this by editing script_args="[...] golovin long1 long2 in shima2009.sh.

Golovin

This example models collision-coalescence using Golovin’s kernel.

The plot produced, by default called ~/CLEO/build_colls0d/bin/golovin_validation.png, should be comparable to Fig.2(a) of Shima et al. 2009 [SKK+09].

Long1 and Long2

These examples model collision-coalescence using Long’s collision efficiency as given by equation 13 of Simmel et al. 2002 [STT02]. The two examples use almost identical initial conditions and collision timesteps, as in Shima et al. 2009 [SKK+09].

The plots produced, by default called ~/CLEO/build_colls0d/bin/long_validation_1.png and ~/CLEO/build_colls0d/bin/long_validation_2.png, should be comparable to Fig.2(b) and Fig.2(c) of Shima et al. 2009 [SKK+09].

b) Breakup

1. Configure the bash scripts, scripts/vanilla/examples/build_compile_run_plot.sh and scripts/vanilla/examples/breakup.sh.

2. Execute the bash script breakup.sh, e.g. from your Cleo directory:

$ scripts/vanilla/examples/breakup.sh

By default kernels including collision-coalescence, breakup and rebound will be compiled and run. You can change this by editing script_args="[...] lowlist etc. in breakup.sh.

Divergence Free Motion

This example is runs from the examples/divfreemotion/divfree2d.py script.

1. Configure the bash scripts, scripts/vanilla/examples/build_compile_run_plot.sh and scripts/vanilla/examples/divfree2d.sh.

2. Execute the bash script divfree2d.sh, e.g. from your Cleo directory:

$ scripts/vanilla/examples/divfree2d.sh

This example plots the motion of super-droplets without a terminal velocity in a 2-D divergence free wind field. It produces a plot showing the motion of a sample of super-droplets, by default called ~/CLEO/build_divfree2D/bin/divfree2d_motion2d_validation.png. The number of super-droplets in the domain should remain constant over time, as shown in the plot produced and by default called ~/CLEO/build_divfree2D/bin/divfree2d_totnsupers_validation.png.

1-D Rainshafts

The Original 1-D Rainshaft

This example is runs from the examples/rainshaft1d/rainshaft1d.py script.

1. Configure the bash scripts, scripts/vanilla/examples/build_compile_run_plot.sh and scripts/vanilla/examples/rainshaft1d.sh.

2. Execute the bash script rainshaft1d.sh, e.g. from your Cleo directory:

$ scripts/vanilla/examples/rainshaft1d.sh

Several plots and animations are produced by this example. If you would like to compare to our reference solutions please contact us.

The EUREC4A 1-D Rainshaft

This example is a variant on the 1-d rainshaft, it runs analagously but with different inputs, outputs, microphysics and boundary conditions, and it produces some different plots.

Constant 2-D Thermodynamics

This example is runs from the examples/constthermo2d/constthermo2d.py script.

1. Configure the bash scripts, scripts/vanilla/examples/build_compile_run_plot.sh and scripts/vanilla/examples/constthermo2d.sh

2. Execute the bash script constthermo2d.sh, e.g.

$ scripts/vanilla/examples/constthermo2d.sh

Several plots and animations are produced by this example. If you would like to compare to our reference solutions please contact us.

Kokkos Tools Profiling Test

This example, kokkostools.py, in examples/kokkostools/ compiles and runs the same executable kokkostools for three different build configurations, (1) “openmp” with only OpenMP parallelism, (2) “threads” with only C++ threads parallelism, and (3) “serial” without parallelism. Using the (pre-installed) Kokkos tooks’ Kernel Timer profiler, this example then outputs the time taken for each run in various ones of Cleo’s kernels.

Before running this example, you must first install the Kokkos tools libraries. You can use the bash script scripts/vanilla/bash/install_kokkos_tools.sh to help you. E.g. with a gcc compiler:

$ cd /your/path/to/kokkos-tools-repo/ && git clone git@github.com:kokkos/kokkos-tools.git
$ scripts/vanilla/bash/install_kokkos_tools.sh /your/path/to/kokkos-tools-repo/ gcc ${CLEO_KOKKOSTOOLS}

1. Configure the bash scripts, scripts/vanilla/examples/build_compile_run_plot.sh and scripts/vanilla/examples/kokkostools.sh. You will need to set the path2kokkostools variable to the path where you installed your Kokkos tools (path to lib or lib64 and bin).

2. Execute the bash script kokkostools.sh, e.g.

$ scripts/vanilla/examples/kokkostools.sh

By default, a .txt file with Kokkos’ simple kernel timer profiling tool data for two runs of each of the four different build configurations is written to ~/CLEO/build_kokkostools/bin/[build_type]_[run_number]_[process_info].txt. The time spent in the “timestep” region can be compared with the ones in ~/CLEO/examples/kokkostools/kokkostools_kpkerneltimer_example_solution.

Python Bindings

This example is runs from the examples/python_bindings/python_bindings.py script.

1. Configure the bash scripts, scripts/vanilla/examples/build_compile_run_plot.sh and scripts/vanilla/examples/python_bindings.sh

2. Execute the bash script python_bindings.sh, e.g.

$ scripts/vanilla/examples/python_bindings.sh

Note: you may have issues with python versions >= 3.14, please see this note for details.

No plots are produced by this example but it should run sucessfully multiple times and produce no plotting script for python bindings example messages. Please note the output during time-stepping may not be ordered due to parallel execution.

Extension

Explore examples/exampleplotting which gives examples of how to plot output from Cleo with cleopy and plotcleo, a few examples are demonstrated in the examples/exampleplotting/exampleplotting.py script.