Getting Started

Installation

Docker

The quickest way to get started with TUV-x is with Docker. The only requirement is that you have Docker Desktop installed and running. With Docker Desktop running, open a terminal window.

To get the latest release of TUV-x, run the following command to start the TUV-x container:

docker run -it ghcr.io/NCAR/tuv-x:release bash

To get the most recent, pre-release version of TUV-x instead run:

docker run -it ghcr.io/NCAR/tuv-x:main bash

Inside the container, you can run the TUV-x tests from the /build/ folder:

cd build/
make test

Local Installation

To build TUV-x locally, you will need to have:

• NetCDF-Fortran

• JSON-Fortran

If you plan to run the TUV-x tests, you will also need Python 3.x with numpy and scipy.

First, clone the TUV-x repo:

git clone https://github.com/NCAR/tuv-x.git
cd tuv-x

Alternatively, you can download the TUV-x source code for a particular release here.

To build TUV-x, from the root TUV-x folder run:

mkdir build
cd build/
export JSON_FORTRAN_HOME=/path/to/json-fortran/installation/
cmake ..
make -j 8
make test

The JSON_FORTRAN_HOME environment variable should point to the root JSON-Fortran installation folder, such that the jsonfortran library is located at JSON_FORTRAN_HOME/lib/libjsonfortran.so.

Depending on where you have the NetCDF library installed, you may also need to set the CMake variables for paths to their include folders and to the library files.

After verifying that the tests pass, you can instal tuv-x with make install. This will install the tuv-x standalone binary, the static library, and some data files. The install location will be the default for your system but you can change the location by modifying CMAKE_INSTALL_PREFIX during the cmake configure phase.

Assuming your prefix is /usr/local TUV-x will install into your file system with these paths:

:: tree -L 3 --filelimit=5 /usr/local/ncar
/usr/local/ncar
└── tuvx-0.3.0
   ├── bin
   │   └── tuv-x
   ├── data  [7 entries exceeds filelimit, not opening dir]
   ├── examples
   │   └── full_config.json
   ├── include  [104 entries exceeds filelimit, not opening dir]
   └── lib
      └── libtuvx.a

To include TUV-x in your cmake project after installing TUV-x, you can find TUV-x with find_package and add it to your target like this

find_package(tuvx REQUIRED)

target_link_libraries(your_lib
   PUBLIC
      musica::tuvx
)

MPI Support

To build TUV-x with MPI support, first clone or download the TUV-x source code as described in Local Installation. Then, from the root TUV-x folder, you can build a Docker image with MPI support and run it in a container:

docker build -t tuv-x . -f Dockerfile.mpi
docker run -it tuv-x bash
make test

Alternatively, you can follow the instructions in Local Installation, replacing the call to cmake with:

cmake -D CMAKE_Fortran_COMPILER=/path/to/mpif90 \
      -D TUVX_ENABLE_MPI:BOOL=TRUE \
      ..

You should replace path/to/mpif90 with the path to your local Fortran MPI compiler.