C-Xool:

ERA5 Atmospheric Boundary Conditions Toolbox for Ocean Modelling with ROMS

Software Documentation

This software is called C-Xool and is distributed under the GNU GENERAL PUBLIC LICENSE.
This file is provided as-is, without any warranty.

Table of Contents

1. Introduction
2. Developers
3. Installing C-Xool
   • Installation using Mamba and pip (recommended)
   • Required Python libraries
4. Architecture
5. Execution
   • Basic execution
   • Execution of the provided examples
   • Execution of the provided tests
   • Required arguments to run C-Xool
   • Optional arguments to run with C-Xool
   • Example of execution
   • Help and further capabilities
6. Support
7. Known problems
8. Platforms
   • Note for Linux Users
   • Note for macOS Users
   • Note for Windows Users
9. Ready-to-use examples
10. ROMS versions tested with an atmospheric forcing built with C-Xool
11. Independent notes for the users to consider
12. Bibliography
13. Supplementary information

Introduction

C-Xool is a Python toolbox designed to prepare atmospheric forcing files for ocean models such as ROMS (Regional Ocean Modelling System). It facilitates downloading, interpolating, plotting, and writing atmospheric data (ERA5) in ROMS-compatible formats.

The toolbox was designed and developed at the Coastal Engineering and Processes Laboratory (LIPC, from its Spanish acronym Laboratorio de Ingeniería y Procesos Costeros), at the Engineering Institute of the National Autonomous University of Mexico (UNAM, Universidad Nacional Autónoma de México), in an office that overlooks the Gulf of Mexico and its beautiful landscape.

C-Xool is open-source and encourages collaboration. If you use C-Xool or improve it, please cite the associated publication [1] and share your improvements.

This README.md file accompanies the code; for more explanations, please refer to [1].

If you have questions, comments, or feedback, contact cargaezg@iingen.unam.mx.

Developers

• Carlos Argáez García, LIPC, IINGEN, UNAM (cargaezg@iingen.unam.mx)
• Simon Klüpfel, Axelyf, Iceland (simon.kluepfel@gmail.com)
• María Eugenia Allende Arandia, LIPC, IINGEN, UNAM (mallendea@iingen.unam.mx)
• Christian Mario Appendini Albrechtsen, LIPC, IINGEN, UNAM (cappendinia@iingen.unam.mx)

Installing C-Xool

Installation using Mamba and pip (recommended)

mamba create -n cxool python
mamba activate cxool
pip install cxool

Once installed, you're ready to run C-Xool.

Required Python libraries

C-Xool relies on the following libraries:

• cartopy
• cdsapi
• cmocean
• copernicusmarine
• dask
• matplotlib
• netcdf4
• numpy
• xarray
• argparse

Architecture

C-Xool is structured into the following modules:

• cxool_cli.py: Entry point; handles CLI parsing and orchestration.
• cds_handler.py: Handles data retrieval from the Climate Data Store (CDS).
• interpolation.py: Performs interpolation of atmospheric variables onto the model grid.
• plotting.py: Contains visualisation functions for assessing the final interpolated forcing file.
• specifications.py: Defines standard variable names, units, and categories.

Execution

Basic execution

Once installed, C-Xool is executed from a terminal.
An example of an execution line is the following:

cxool --grid_name your_grid.nc --initialdate YYYY-MM-DD --finaldate YYYY-MM-DD 
--vars_to_interp var1 var2 var3 --plot_interval int_val 
--final_interpolated_file "ERA5_interpolated_to_grid.nc" 
--output_folder "SoftwareXExample" -o "input"

Execution of the provided examples

Go into the examples folder. There you have three options:

• GermanNorthernSea: Contains a dummy grid for the Northern Sea between Denmark and Germany. Go to the folder and execute the Python script. This will complete the example run.
• MexicanCaribbean: Contains a dummy grid for the Caribbean Sea off the eastern coast of the Yucatan Peninsula. Go to the folder and execute the Python script. Run the script; it executes the full example.
• ROMS_example: Contains three folders: data, External, and Include. Inside data, there is a grid for the northern coast of the Yucatan Peninsula, the Gulf of Mexico, along with a Python script. Go to the folder and execute the Python script. The script runs automatically. Then, set up a ROMS execution using the files included in the folders External and Include. This is a toy model in ROMS that runs without boundary, climatology, runoff, or tidal forcing files.

Execution of the provided tests

We have provided a set of unit tests to assess:

• The CDSAPI credentials.
• The execution of the download commands and path settings.
• The execution of the merging of different downloaded data batches into one file to be read by interpolation.
• The argument parser reading.
• The interpolation of dummy ERA5 variable msl and dummy grid data variables lat_rho and lon_rho, to a NetCDF file.
• The plotting of dummy scalar and vectorial variables.
• The execution of real data download, interpolation onto a provided grid, and comparison to a reference forcing file.

To execute, go inside the folder tests. Then execute:

pytest . -v

Required arguments to run C-Xool

• --grid-name: Command expecting a string value as input. Name of the ROMS grid NetCDF file.
• --initialdate: Command expecting a numerical value as input. Initial date from which data download and interpolation will begin. Format: YYYY-MM-DD. Time is automatically set to 00:00:00 hrs.
• --finaldate: Command expecting a numerical value as input. Final date for data download and interpolation. Format: YYYY-MM-DD. Time is automatically set to 23:00:00 hrs.

Optional arguments to run with C-Xool

• --ref-date: Command expecting a string value as input. Reference date for the time variable in the output NetCDF file. Format should follow ISO 8601, e.g., 1948-01-01T00:00:00.000000000. Default: 1948-01-01T00:00:00.000000000.
• --interval: Command expecting a numerical value as input. Time step interval to download data in hours, starting from 00:00:00 hrs.
• --vars-to-interp: Command expecting a string value as input. Variables to download and interpolate. Default: msl, wind, t2m, tcc. Scalar variables refer to most ERA5 fields. Vector variable wind means u and v components at 10 m height. Both are treated as a pair.
• --plot: Command expecting string values as input. Specifies variables to plot from the final forcing file.
• --plot-interval: Command expecting a numerical value as input. Time interval for plotting data in time steps of the netCDF forcing file generated by C-Xool.
  • A negative value -t will plot the t-th slice of the interpolated NetCDF.
  • A value of 0 will plot only the first slice of the interpolated NetCDF.
  • A positive value t, to plot every t-th slice of the interpolated NetCDF, starting from the first slice.
• --projection: Map projection for plotting. Accepts stereographic or mercator.
• --scale-factor: Numerical value controlling arrow size in quiver plots. Higher value = smaller arrows.
• --arrowdensity: Numerical value controlling vector field density. Lower = denser field.
• --discrete-colors: Number of discrete colours in plots.
• --homogenise-limits: Boolean. When enabled, uses consistent colourbar limits for better comparison.
• --data-storage: Path to store raw ERA5 data.
• --data-subfolder: Subdirectory name for saving merged ERA5 data.
• --plots-folder: Folder to save output plots. Placed inside --output-folder if defined.
• --output-folder: Folder where all output files will be saved.
• --memory-chunks: Memory chunk size (MB) for processing large files.
• --out-config: String name to output a reusable configuration input file.
• --input-file: Input config file (manually or via --out-config) to rerun with same settings.
• --plot-format: Output image format for plots (png, pdf, eps, svg).
• --version: Show C-Xool version.
• --help: Show help menu and full list of options.

Example of execution

A basic command line execution example is the following:

python cxool_cli.py --grid-name model_grid.nc \
  --initialdate 1983-10-25 --finaldate 1983-10-27 \
  --vars-to-interp wind t2m msl tcc \
  --plot msl wind t2m tcc --plot-interval 3 \
  --final-interpolated-file ERA5_interpolated-to-grid.nc \
  --output-folder SoftwareXExample -o input

Help and further capabilities

To see the full list of options, run:

cxool --help

Support

If you encounter issues, please email cargaezg@iingen.unam.mx. We support Spanish, English, Italian, and Yucatec Maya.

Known problems

• You must set up your ECMWF account.
• You must set up CDSAPI.
• You must install the proper Python environment.
• You must install C-Xool.
• You must install the aforementioned libraries.
• Grid file, initial date, and final date are mandatory arguments. No default values were provided.

Ready-to-use examples

Inside the installation folder of C-Xool, there is a folder called examples that contains two subfolders: GermanNorthernSea and MexicanCaribbean. Inside each of these subfolders, a model grid is provided along with a Python script that allows running.

examples/
├── GermanNorthernSea
│   ├── example_German_Northern_sea.py
│   └── nordseedeu10km_grid.nc
├── MexicanCaribbean
│   ├── caribemex10km_grid.nc
│   └── example_Mexican_caribbean.py
└── ROMS_example
    ├── cxool_instructions.txt
    ├── data
    │   ├── inluum_grid.nc
    │   └── run_cxool_example.py
    ├── External
    │   └── inluum.in
    ├── Include
    │   └── gulfofmexico.h
    ├── README.html    
    └── README.md    

Platforms

Note for Linux Users

C-Xool has been tested on:

1. Fedora Linux 35 Workstation, 64-bit.
2. Rocky Linux 8.6, 64-bit.
3. Fedora Linux 41 Workstation, 64-bit.

Note for macOS Users

C-Xool has been tested on macOS. Please report any compatibility issues to the developer.

Note for Windows Users

C-Xool can be used under Windows via a properly configured Python environment.
It has been tested on:

1. Microsoft Windows 11, Pro, 64 bits.

ROMS versions tested with an atmospheric forcing built with C-Xool

We have tested the forcing file compatibility with different ROMS versions. The oldest version successfully used was the 2011 release (makefile 1417 2011-05-13 16:51:50Z kate), which is indeed quite dated. We also verified functionality with the latest ROMS version available on GitHub at the time of writing. All worked.

In accordance with the ROMS documentation [2] and recent ROMS-Tools guidelines [3], we know the NetCDF structure for atmospheric forcing variables is:

ATMOS_VAR(time, eta_rho, xi_rho)

Given the consistency across ROMS documentation, and based on our own testing, we do not anticipate any compatibility issues. The expected format for atmospheric forcing variables is well established as:

ATMOS_VAR(time, eta_rho, xi_rho)

and has remained stable across ROMS versions [2,3].

Independent notes for the users to consider

Producing a bathymetric grid for a ROMS model is a hard task that usually requires both good knowledge in coding and ocean-sciences. This is out of the scope of C-Xool. However, user may want to consider:

1. James, C., Gridbuilder, Austides Consulting, accessed: 10 June 2025.
2. Ådlandsvik, B., GridMap – Python toolbox for ROMS grid files based on explicit map projections, https://github.com/bjornaa/gridmap.

Bibliography

[1] C-Xool, ERA5 Atmospheric Boundary Conditions Toolbox for Ocean Modelling with ROMS, Argáez, C., Klüpfel, S., Allende Arandía, M. E., Appendini, C. M. Submitted to SoftwareX, under review.

[2] ROMS Forcing Package Documentation. Available at: https://www.myroms.org/index.php?page=forcing

[3] ROMS-Tools Documentation – Surface Forcing. Available at: https://roms-tools.readthedocs.io/en/latest/surface_forcing.html

Supplementary information

Modern package managers such as mamba and pip generally ensure a clean installation of the needed dependencies. However, we provide here the specific versions and distribution channels of the key Python libraries we used during our testing and development.

We do so in the hope that this information serves other users with two purposes:

• Reproducibility: It offers the configurations that were verified to work with C-Xool in both Linux and macOS environments. This information can be useful if any user wishes to replicate our setup exactly or needs to troubleshoot an unexpected behaviour.
• Demonstrated Compatibility: The examples show that C-Xool runs reliably across different platforms, Python versions, and package sources (e.g., conda-forge vs pypi). This underlines the flexibility and robustness of the tool in varied user environments.

Nevertheless, we recommend installing the latest compatible versions in a clean environment.

Fedora Linux 35 Workstation, 64-bit

In this case, Python version was 3.13.5 and the libraries distributions were as follows:

macOS Big Sur, Version 11.7.10

In this case, Python version was 3.12.2 and the libraries distributions were as follows: