Canoe: Comprehensive Atmosphere N' Ocean Engine

Install system libraries and toolchain

Canoe can be installed on either a Linux distribution or on MacOS. Open a Linux or Mac terminal, you can clone this repo using the following command:

git clone https://github.com/chengcli/canoe

This will copy all source files into your local computer. You will need to install a few system libraries before installing canoe. All following instructions are executed under the canoe/ directory, which is referred to as the root.

MacOS Installation Guide

We assume that homebrew is already installed on your Mac and we will use brew to install required system libraries. The system libraries are listed in Brewfile at the root. To install them all, execute

brew bundle

Ubuntu Linux Installation Guide

On a Ubuntu linux system, use apt to install

sudo apt install $(cat packages_debian.txt)

Redhat Linux Installation Guide

On a Redhat linux system, use yum to install

sudo yum -y install $(cat packages_centos.txt)

Multi-core execution

If multi-core parallelization is needed, these extra pacakges should be install

mpich parallel library

Ubuntu linux:

sudo apt install libmpich-dev

Redhat linux:

sudo yum install mpich-devel
source ~/.bash_profile

pnetcdf output

Redhat linux does not support pnetcdf natively. So it should be downloaded and install. The default installation directory is $HOME/opt/

cd external
./fetch_pnetcdf.sh
./install_pnetcdf.sh
cd ..

Notes on using openmpi

Some system, especially conda, uses openmpi by default. It is know that openmpi sometimes causes trouble in the simulation and mpich works better with canoe. If you have to use openmpi and the run fails immediately after execution, try to run with a single core first and then multi-core.

Install python libraries

The minimum python version is 3.8. All needed python libraries are collected in requirements.txt. We suggest using a python virtual environment to install these packages. If you are already using a virtual enviroment, install python packages by

pip3 install -r requirements.txt

Otherwise, to create a python virtual environment:

python -m venv pyenv

This command will create an environment named pyenv in your current directory. Then, you can use the previous command to install the python packages.

Install pre-commit

pre-commit install

The contributor's guide explains the meaning of pre-commit.

Environment variables

These following environment variables are important for the system to find the appropriate MPI:

export PATH=$PATH:/usr/lib64/mpich/bin
export LD_LIBRARY_PATH=/usr/lib64/mpich/lib:$LD_LIBRARY_PATH
export MPICC=/usr/lib64/mpich/bin/mpicc
export MPICXX=/usr/lib64/mpich/bin/mpicxx

How to build and test

After you completed the installation steps, you can build the canoe library. The easiest way is to build it in-place, meaning that the build (binary files) are located under root. To do so, make a new directory named build

mkdir build

All build files will be generated and placed under this directory. It is completely safe to delete the whole directory if you want another build. cd to build and cmake

cd build
cmake ..

This command tells the cmake command to look for CMakeFiles.txt in the parent directory, and start configuring the compile environment. Then compile the code by

make -j4

This comman will use 4 cores to compile the code in parallel. Once complete, all executable files will be placed in build/bin.

Optional packages

The Reference Forward Model (RFM) is provided optionally as a tool to generate opacity tables. The source code of this package is not publically available. Please contact Anu Dudhia ar Cheng Li to obtain access. The build process turns off RFM by default. To turn on building RFM, use
```
cmake .. -DRFM=ON
```
The DIScrete Ordinate Radiative Transfer (DISORT) is provided optionally as a plane-parallel radiative transfer solver. The original source code was in Fortran77. Tim Downling translated it to C in 2011. The C-source code, version 2.1.3, is hosted at libradtran.org. The build process turns off DISORT by default. To turn on building DISORT, use
```
cmake .. -DDISORT=ON
```
The Parallel Kernel-Independent Fast Multipole Method (PVFMM) is provided optionally as a potential solver for N-Body simulation. The upstream source code is hosted at pvfmm. We made a customized fork hosted at chengcli:pvfmm. The build process turns off PVFMM by default. To turn on building PVFMM, use
```
cmake .. -DPVFMM=ON
```

chengcli / canoe

readme