Convert files without the Converter tool

Overview

Each language below ships three converters that do the same job:

• ESPEC: ocean data (currents, temperature, salinity) delivered as separate NetCDF files per variable.
• GBLY: ocean data delivered as grouped NetCDF files (currents together, temperature/salinity together).
• GRIB2: meteorological data: wind at 10 m and air temperature at 2 m.

All four implementations read the same grid.txt, crop the source files to that area before loading them into memory, interpolate onto the grid, and write the same STFM-ready text files. The only thing that changes is the language you run them in.

Python

Objective: install, configure, and run the STFM converters in Python.

1. Presentation

This guide explains how to prepare a Windows computer to run the three converters covered in this tutorial:

• converter_ESPEC.py: converts ESPEC/HYCOM ocean files with separate variables.
• converter_GBLY.py: converts GBLY/HYCOM ocean files with grouped currents and thermohaline properties.
• converter_grib.py: converts GRIB2 weather files with wind at 10 m and air temperature at 2 m.

The scripts interpolate the data onto the grid defined in grid.txt and produce text files ready for STFM.

2. Download the scripts

Download Python scripts (.zip)

Quick registration required before download.

3. Requirements and installation

Operating system

This step-by-step guide was prepared for:

• Windows 10 or Windows 11, 64-bit;
• a user with permission to install programs under their own account;
• internet access during installation.

The scripts can also run on Linux and macOS, but the navigation and install commands may differ.

Recommended hardware

• 64-bit processor;
• at least 8 GB of RAM;
• 16 GB RAM recommended for large grids;
• enough free space for the original files and the generated TXT output.

Global HYCOM files can be several gigabytes each. The ocean converters crop the area defined in grid.txt before loading values into memory, which keeps memory use down. The size of the final TXT depends on the number of points and depth levels requested.

Programming language

The three converters are written in Python 3, the program that interprets and runs files with the .py extension. This guide recommends Python 3.12 inside an isolated Conda environment, which keeps this tutorial's libraries from conflicting with any other Python setup already on your computer.

Miniconda (recommended)

Miniconda installs Python and the Conda environment manager. It's recommended here because GRIB processing depends on the binary library ecCodes, which installs far more easily through the conda-forge channel than any other way.

1. Open the official Miniconda download page for Windows.
2. Download the 64-bit graphical installer.
3. Run the installer.
4. Choose Just Me: the option Anaconda's own documentation recommends.
5. Choose an install folder without spaces or special characters, if possible.
6. Leave Add Miniconda3 to my PATH environment variable unchecked. Anaconda advises against it, since it can conflict with other installs.
7. Finish the installation.
8. Open Anaconda Prompt from the Windows Start menu.

Confirm the install:

conda --version

The command should print the Conda version with no error.

Visual Studio Code (recommended, optional IDE)

An IDE is an editor for viewing, editing, and running code. The scripts run fine from Anaconda Prompt alone, but VS Code makes editing and spotting errors easier.

1. Download Visual Studio Code from the official website.
2. Install it normally.
3. Open VS Code.
4. Open the Extensions panel.
5. Search for Python, published by Microsoft, and install it.

The extension doesn't install Python itself; it connects VS Code to the interpreter Miniconda already installed. This separation is explained in the official Python-in-VS-Code documentation.

Creating the Python environment

Open Anaconda Prompt and create an environment called stfm-converter:

conda create -n stfm-converter python=3.12 -y

Activate it:

conda activate stfm-converter

When active, the line should start with (stfm-converter). Always activate this environment before running the converters.

Installing the libraries

With the environment active, run:

conda install -c conda-forge numpy pandas xarray netcdf4 cftime cfgrib eccodes -y

Library	Function in this tutorial
numpy	Manipulation of numerical arrays and coordinates.
pandas	Reading grid.txt and formatting dates and times.
xarray	Opening, selecting, and interpolating scientific data.
netcdf4	Engine for reading ocean NetCDF files.
cftime	Extra support for calendars and dates in scientific archives.
cfgrib	Lets xarray open GRIB1/GRIB2 files.
eccodes	Binary library cfgrib uses to decode GRIB.

The xarray project recommends netCDF4 for reading and writing NetCDF, and the conda-forge channel for scientific dependencies that are hard to compile. The cfgrib project makes the same recommendation for its own binary dependencies.

Verify the installation

Run:

python -c "import numpy, pandas, xarray, netCDF4, cftime, cfgrib; print('Libraries installed successfully')"

Then check ecCodes:

python -m cfgrib selfcheck

The test should report that ecCodes was found and the system is ready.

VS Code setup

1. In VS Code, choose File > Open Folder.
2. Open the tutorial folder.
3. Press Ctrl+Shift+P.
4. Type Python: Select Interpreter.
5. Choose the stfm-converter environment.
6. Open a terminal from Terminal > New Terminal.
7. Confirm the line starts with (stfm-converter).

If the environment doesn't show up, close and reopen VS Code after installing the libraries.

Updating or removing the environment

List installed packages:

conda list

Update only this environment's libraries:

conda activate stfm-converter
conda update -c conda-forge numpy pandas xarray netcdf4 cftime cfgrib eccodes

Updates can change how libraries behave, so on computers used in production or in classes, test the converters again before updating everyone.

To remove the environment entirely, if you ever need to reinstall it:

conda deactivate
conda remove -n stfm-converter --all

This only removes the Python environment. It doesn't touch the scripts or tutorial data.

Alternative install with pip

For NetCDF only, you can use a plain virtual environment instead:

python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install numpy pandas xarray netCDF4 cftime

This route isn't recommended for the GRIB converter on Windows, since cfgrib depends on ecCodes and binary components that pip doesn't handle well. To run all three converters, prefer Conda and conda-forge.

4. Project structure

All scripts must stay in the tutorial folder, next to grid.txt:

tutorial/
├── converter_ESPEC.py
├── converter_GBLY.py
├── converter_grib.py
├── grid.txt
├── input/
│   ├── espec/
│   │   ├── water_u/
│   │   ├── water_v/
│   │   ├── temperature/
│   │   └── salinity/
│   ├── gbly/
│   │   ├── currents/
│   │   └── temperature/
│   └── grib/
└── output/
    ├── currents/
    ├── temperature/
    └── winds/

The scripts use relative paths, so they must always be run from inside the tutorial folder.

5. Preparation of input files

grid.txt

Defines the output grid points. It must sit directly in the tutorial folder and contain at least these columns:

i, j, longitude, latitude, bottom(m), landmask

• Column names must be preserved exactly.
• Values must be separated by spaces.
• Longitude and latitude must be numeric.
• Indices i and j must form a regular grid.
• Don't change the header line without updating the scripts to match.
• Use a point as the decimal separator, e.g. -38.500000.

The longitude/latitude limits in grid.txt are used to automatically crop the global ocean files. The original source file is never modified.

ESPEC files

Place the NetCDFs in the matching folders:

input/espec/water_u/       files containing water_u
input/espec/water_v/       files containing water_v
input/espec/temperature/   files containing water_temp
input/espec/salinity/      files containing salinity

The four files for the same instant must share the same date/time in their filename, in the compact YYYYMMDDHH format, e.g.:

..._2026081012_..._u3z.nc
..._2026081012_..._v3z.nc
..._2026081012_..._t3z.nc
..._2026081012_..._s3z.nc

The converter uses the water_u files as the anchor and looks for the other variables at the same date/time.

GBLY files

Place the files in:

input/gbly/currents/       NetCDF with water_u and water_v
input/gbly/temperature/    NetCDF with water_temp and salinity

Matching files must share the same date/time, e.g.:

hycom_glby_930_2024081012_t000_uv3z.nc
hycom_glby_930_2024081012_t000_ts3z.nc

The first file holds currents (uv), the second holds temperature and salinity (ts).

GRIB2 files

Place the weather files in input/grib/. Accepted extensions: .grib2 and .grb2.

The converter expects to find in the GRIB file:

• 10u: zonal wind component at 10 m;
• 10v: meridional wind component at 10 m;
• 2t: air temperature at 2 m;
• a valid time, or the combination of base time and step.

Temperature is converted from Kelvin to Celsius before writing.

6. Depth configuration

In the ESPEC and GBLY converters, the target-levels variable defines the output depths.

Surface only:

levels_alvo = [0]

Example with multiple levels:

levels_alvo = [0, 2, 4, 6, 8, 10, 15, 20, 25, 50, 100, 250, 500, 1000, 2000, 3000, 4000, 5000]

Every horizontal point in grid.txt generates one line per requested depth. Land points, uncovered areas, and positions below the seabed may come out as zero, since the scripts fill missing values with fillna(0).

7. Running the converters

Open Anaconda Prompt, activate the environment, and move into the tutorial folder:

conda activate stfm-converter
cd C:\path\to\project\tutorial

Replace the path with your tutorial folder's actual location.

Run the ESPEC converter

python -u converter_ESPEC.py

Run the GBLY converter

python -u converter_GBLY.py

Run the GRIB2 converter

python -u converter_grib.py

The -u flag prints messages immediately to the terminal, which makes it easier to follow long-running processing.

8. Generated files

The output follows one consistent pattern:

output/currents/currents_YYYYMMDD_HH.txt
output/temperature/temperature_YYYYMMDD_HH.txt
output/winds/winds_YYYYMMDD_HH.txt

For example:

output/currents/currents_20260810_12.txt
output/temperature/temperature_20260810_12.txt
output/winds/winds_20260810_12.txt

The date/time comes from the internal coordinates of the source files. Running two ocean products for the same date/time writes to the same output filename, so move or rename the first result first if you need to keep both.

9. Troubleshooting

"python" or "conda" is not recognised

Make sure you're using Anaconda Prompt, not a regular Command Prompt. Confirm with:

conda --version
python --version

"ModuleNotFoundError"

Activate the environment and reinstall the dependencies:

conda activate stfm-converter
conda install -c conda-forge numpy pandas xarray netcdf4 cftime cfgrib eccodes -y

VS Code is using the wrong Python

Press Ctrl+Shift+P, choose Python: Select Interpreter, and pick stfm-converter.

Error opening GRIB, or ecCodes not found

python -m cfgrib selfcheck

If it fails, reinstall both from the same channel:

conda install -c conda-forge --force-reinstall cfgrib eccodes -y

Don't mix a pip-installed cfgrib with a Conda-installed one in the same environment.

"Tau" or "hours since analysis" error

The ESPEC and GBLY converters ignore the auxiliary tau variable when opening NetCDF files. Confirm you're running the current version of the script, not an older copy in another folder.

Matching file not found

• Check the file is in the correct subfolder.
• Check the extension is .nc, .grib2, or .grb2 as expected.
• Check the matching ocean files share the same YYYYMMDDHH in their names.
• Check the terminal is open inside the tutorial folder.

Ocean values are all zero

Possible causes:

• the grid falls outside the source file's coverage;
• the points fall on land;
• the file has no valid values at the chosen date or depth;
• you're running an older copy of the converter;
• the coordinate or variable names differ from what's expected.

The scripts expect the coordinates time, depth, lat, and lon, plus the variables water_u, water_v, water_temp, and salinity.

"MemoryError" or "ArrayMemoryError"

Confirm you're using the current version of grid.txt. Close other programs, reduce the number of depth levels, and check the grid doesn't cover an excessively large region.

Processing looks stuck

Grids with hundreds of thousands of points can take a while during interpolation and line-by-line writing. Use python -u to follow the messages, and check whether the output file size keeps growing.

10. Quick checklist

Before running, confirm:

• Miniconda installed;
• stfm-converter environment created and activated;
• libraries installed from conda-forge;
• python -m cfgrib selfcheck passes;
• grid.txt present in the tutorial folder;
• source files placed in the correct input subfolders;
• terminal opened inside the tutorial folder;
• target depth levels set as intended;
• enough free disk space for the TXT output;
• previous results protected from being overwritten, if needed.

Once these are checked, run the converter that matches your input product.

R

Objective: install, configure, and run the STFM converters in R.

1. Presentation

This is the validated procedure for installing and running the STFM converters in R without loading entire global files into memory.

Script	Input	Output
R/converter_ESPEC.R	NetCDF ESPEC/HYCOM, separate variables	currents, temperature and salinity
R/converter_GBLY.R	NetCDF GBLY/HYCOM, grouped variables	currents, temperature and salinity
R/converter_grib.R	GRIB2 GFS	wind at 10 m and air temperature at 2 m

The ocean converters use ncdf4 and only read the crop around grid.txt. For GFS, ecCodes extracts 10u, 10v, and 2t separately. This strategy avoids memory errors when processing global files.

2. Download the scripts

Download R scripts (.zip)

Quick registration required before download.

3. Requirements and installation

• Windows 10 or 11, 64-bit;
• 64-bit R;
• 8 GB of RAM or more;
• about 5 GB free disk space;
• internet access during installation.

Install R

1. Go to CRAN's R for Windows page.
2. Download and install the 64-bit version with the default options.
3. Open R x64 and confirm:

R.version.string

This tutorial was validated with R 4.6.1.

In the R console, find the exact path to the interpreter:

file.path(R.home("bin"), "Rscript.exe")

A typical result looks like:

C:\Program Files\R\R-4.6.1\bin\Rscript.exe

This guide uses the full path so it doesn't depend on the Windows PATH.

Install ncdf4

In the R or RStudio console, run once:

install.packages("ncdf4", repos = "https://cloud.r-project.org")

Validate it:

library(ncdf4)
packageVersion("ncdf4")

A version number should appear with no error.

Install ecCodes for GRIB2

This step is only required for converter_grib.R. If the C++ tutorial's stfm-cpp environment is already set up, the script will find that ecCodes automatically.

Otherwise, install Miniforge, open Miniforge Prompt, and run:

conda create -n stfm-r -c conda-forge eccodes -y
conda activate stfm-r
grib_copy -V
grib_to_netcdf -V

The last two commands should print the ecCodes version. The script looks for active stfm-r or stfm-cpp environments in both Anaconda and Miniforge.

4. Project structure

tutorial/
├── GUIA_R.md
├── grid.txt
├── R/
│   ├── common.R
│   ├── converter_ESPEC.R
│   ├── converter_GBLY.R
│   └── converter_grib.R
├── input/
│   ├── espec/
│   │   ├── water_u/
│   │   ├── water_v/
│   │   ├── temperature/
│   │   └── salinity/
│   ├── gbly/
│   │   ├── currents/
│   │   └── temperature/
│   └── grib/
└── output/
    ├── currents/
    ├── temperature/
    └── winds/

Don't move common.R. The other scripts depend on it being right next to them. Always run the scripts from inside the tutorial folder.

5. Preparation of input files

grid.txt

Must contain at least these space-separated columns:

i, j, longitude, latitude, bottom(m), landmask

Preserve the header line, use a point as the decimal separator, and keep a regular grid.

ESPEC files

input/espec/water_u/       NetCDF with water_u
input/espec/water_v/       NetCDF with water_v
input/espec/temperature/   NetCDF with water_temp
input/espec/salinity/      NetCDF with salinity

The four matching files must share the same YYYYMMDDHH in their names.

GBLY files

input/gbly/currents/       NetCDF with water_u and water_v
input/gbly/temperature/    NetCDF with water_temp and salinity

The two matching files must also share the same YYYYMMDDHH.

GRIB2 files

Place .grib2 or .grb2 files in input/grib. Each file must contain:

• 10u: zonal wind at 10 m;
• 10v: meridional wind at 10 m;
• 2t: air temperature at 2 m.

6. Depth configuration

In converter_ESPEC.R and converter_GBLY.R, the default configuration processes the surface only:

levels_target <- c(0)

Example with multiple levels:

levels_target <- c(0, 2, 4, 6, 8, 10, 15, 20, 25, 50, 100, 250,
500, 1000, 2000, 3000, 4000, 5000)

No compilation step is needed after saving, just run the script again.

7. Running the converters

From Command Prompt

These commands go in the Windows Command Prompt, not the R console. Enter the folder (replacing the username):

cd /d C:\Users\your_user\Documents\SISMOM\tutorial

Limit the numeric libraries to one thread each, to reduce initial memory use:

set OPENBLAS_NUM_THREADS=1
set OMP_NUM_THREADS=1
set MKL_NUM_THREADS=1

Run only the converter you need:

"C:\Program Files\R\R-4.6.1\bin\Rscript.exe" R\converter_ESPEC.R
"C:\Program Files\R\R-4.6.1\bin\Rscript.exe" R\converter_GBLY.R
"C:\Program Files\R\R-4.6.1\bin\Rscript.exe" R\converter_grib.R

If you installed a different R version, adjust R-4.6.1 to match. There's no underscore before the extension: the filename is exactly converter_ESPEC.R.

A correct run prints messages similar to:

Found 1 ESPEC file(s).
[OK] currents_20260810_12.txt
[OK] temperature_20260810_12.txt
[DONE] ESPEC processing completed.

From R or RStudio

Don't type cd /d in the R console. When the prompt starts with >, use:

setwd("C:/Users/your_user/Documents/SISMOM/tutorial")
getwd()
source("R/converter_ESPEC.R")

For the other products:

source("R/converter_GBLY.R")
source("R/converter_grib.R")

In RStudio, you can also use Session > Set Working Directory > Choose Directory.

8. Generated files

output/currents/currents_YYYYMMDD_HH.txt
output/temperature/temperature_YYYYMMDD_HH.txt
output/winds/winds_YYYYMMDD_HH.txt

The date and time come from the file's internal time coordinate. An existing output for the same date/time is overwritten.

9. Troubleshooting

"Rscript" is not recognized

Use the full path returned by file.path(R.home("bin"), "Rscript.exe") in the R console.

"unexpected symbol" after "cd /d"

That command was typed into the R console by mistake. Use setwd() inside R, or cd /d in Command Prompt, not both mixed together.

Missing ncdf4 package

install.packages("ncdf4", repos = "https://cloud.r-project.org")

ecCodes not found

At the Miniforge prompt:

conda activate stfm-r
grib_copy -V
grib_to_netcdf -V

"grid.txt" not found

The terminal is in the wrong folder:

cd /d C:\Users\your_user\Documents\SISMOM\tutorial
dir grid.txt

NetCDF variable not found

The expected files use the coordinates lon, lat, depth, and time, and the variables water_u, water_v, water_temp, and salinity.

Matching file not found

Check the subfolder, and confirm the files for the same instant share YYYYMMDDHH in their names.

Values are all zero

Values outside coverage, missing, on land, or at unavailable depths are written as zero. Confirm grid.txt falls inside the source data's domain.

Running out of memory

Use the current scripts, which subset NetCDF files by index and process one GRIB field at a time. Close other programs and reduce levels_target if needed. Don't open the global files with terra::rast().

10. Checklist

Before the first run, in Command Prompt:

dir grid.txt
dir R\*.R
"C:\Program Files\R\R-4.6.1\bin\Rscript.exe" -e "library(ncdf4); print(packageVersion('ncdf4'))"

For GRIB, at the Miniforge Prompt:

conda activate stfm-r
grib_copy -V
grib_to_netcdf -V

If these all complete with no error, the install is ready. Quick checklist:

• 64-bit R installed;
• Rscript.exe path confirmed;
• ncdf4 installed;
• ecCodes available for GRIB;
• terminal opened inside the tutorial folder;
• thread variables set to 1;
• grid.txt present;
• source files in the correct subfolders;
• target depths configured;
• free space available for temporary files and TXT output;
• previous important results protected from overwriting.

After the initial install, the daily routine is: enter the tutorial folder, set the three thread variables, and run the converter you need.

C++

Objective: install, configure, and run the STFM converters in C++.

1. Presentation

This guide was written for people who have never programmed in C++. Follow the steps in order. You don't need to understand all the code to install, compile, and run the converters.

What the project does: it reads environmental data, interpolates it onto the grid.txt points, and creates the text files STFM uses.

Program	Input	Output
converter_ESPEC_cpp.exe	NetCDF ESPEC/HYCOM, separate	currents, temperature and salinity
converter_GBLY_cpp.exe	NetCDF GBLY/HYCOM, grouped	currents, temperature and salinity
converter_grib_cpp.exe	GRIB2 weather data	wind and air temperature

A few terms you'll run into

• C++: a programming language. The code lives in .cpp and .hpp files. Unlike Python, Windows can't run these directly; they need to be compiled into .exe programs first.
• Compiler: the program that translates C++ code into machine instructions. This guide uses Microsoft's MSVC compiler, installed via Visual Studio Build Tools.
• CMake: reads CMakeLists.txt, locates the compiler and libraries, and prepares the build. cmake --build build is what actually creates the executables.
• Conda and Miniforge: Miniforge installs the Conda environment manager, which creates an isolated environment called stfm-cpp to avoid conflicting with anything else on your machine.
• Libraries: NetCDF opens the ocean .nc files; ecCodes opens the weather .grib2/.grb2 files; Ninja carries out the build steps CMake prepares.

2. Download the scripts

Download C++ scripts (.zip)

Quick registration required before download.

3. Requirements and installation

What you'll need installed by the end of this section: Visual Studio Build Tools, a working C++ compiler, Miniforge, and the stfm-cpp environment, then the project compiled.

What to install

1. Visual Studio Build Tools: provides the C++ compiler.
2. Miniforge: provides Conda.
3. CMake, Ninja, NetCDF, and ecCodes: inside the Conda environment.
4. Optionally, Visual Studio Code, just to view and edit the code (it doesn't install the compiler).

Requirements: 64-bit Windows 10/11, internet access, about 5 GB free, and preferably 8 GB of RAM or more.

Install the C++ compiler

1. Open the Visual Studio downloads page.
2. Look for "Tools for Visual Studio".
3. Download Build Tools for Visual Studio.
4. Run the installer.

In the Visual Studio Installer window:

1. Check Desktop development with C++.
2. In the right-hand pane, confirm these are selected: MSVC C++ x64/x86 build tools; Windows 10 or 11 SDK; C++ CMake tools (if available).
3. Click Install.
4. Wait for it to finish, and restart Windows if prompted.

Test it: from the Start menu, open x64 Native Tools Command Prompt for Visual Studio and run:

cl

You should see something like Microsoft (R) C/C++ Optimizing Compiler Version ... for x64. In a regular Command Prompt, cl may not be recognized. That's expected, since the compiler paths aren't set up there.

Install Miniforge

1. Open the official conda-forge download page.
2. Under Miniforge's latest release, click Windows (x86_64).
3. Run the downloaded Miniforge3-Windows-x86_64.exe installer.
4. Click Next and accept the license.
5. Choose Just Me.
6. Use a simple folder path, e.g. C:\Users\your_user\miniforge3.
7. Leave shortcut creation checked.
8. Leave Add Miniforge3 to my PATH unchecked. The project itself warns this can cause conflicts.
9. Click Install.

Test it: open Miniforge Prompt from the Start menu and run:

conda --version
conda list

If a version and a package list appear, it's working.

Create the project environment

In Miniforge Prompt, copy this whole command and press Enter:

conda create -n stfm-cpp -c conda-forge cmake ninja cxx-compiler libnetcdf eccodes -y

This can take a few minutes. What it means: conda create makes a new environment; -n stfm-cpp names it; -c conda-forge uses the conda-forge channel; the names after that are the tools to install; -y auto-confirms.

Activate it:

conda activate stfm-cpp

The terminal prompt should now start with (stfm-cpp). Repeat conda activate stfm-cpp every time you open a new terminal. Activation is what makes the tools and DLLs from the environment available.

Check the tools

With (stfm-cpp) visible, run each of these separately:

cmake --version
ninja --version
codes_info -v
cl

Each one should print a version.

If only "cl" fails:

1. In Visual Studio Installer, confirm Desktop development with C++ is installed.
2. Close the terminal.
3. Open x64 Native Tools Command Prompt instead.
4. Activate Conda and the environment:

call %USERPROFILE%\miniforge3\Scripts\activate.bat
conda activate stfm-cpp

Then run cl again. If you installed Miniforge somewhere else, adjust the path.

Compile

Inside the tutorial folder, configure the build:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=%CONDA_PREFIX%

What each flag means: -S . sets sources to the current folder; -B build sends generated files to build; -G Ninja selects Ninja; Release builds optimized programs; CMAKE_PREFIX_PATH locates the Conda environment's libraries.

A correct run ends with:

Configuring done
Generating done
Build files have been written to: ...\tutorial\build

Now build the executables:

cmake --build build

Check the programs were created:

dir build\*.exe

You should see:

build\converter_ESPEC_cpp.exe
build\converter_GBLY_cpp.exe
build\converter_grib_cpp.exe

What needs repeating, and when:

• Installing Build Tools and Miniforge: once.
• Creating stfm-cpp: once.
• conda activate stfm-cpp: every new terminal.
• cmake -S . (configure): the first time, or after changing CMake settings.
• cmake --build build: the first time, and after any change to the .cpp files.
• Running the .exe files: whenever you want to convert data.

Visual Studio Code (optional)

1. Download Visual Studio Code.
2. Install and open it.
3. Press Ctrl+Shift+X.
4. Install the Microsoft C/C++ and CMake Tools extensions.
5. Use File > Open Folder and open the tutorial folder.

You can also activate stfm-cpp, enter the tutorial folder, and run code ., then keep compiling from VS Code's integrated terminal with the same commands as above.

Rebuilding from scratch

If a build goes wrong, delete only the tutorial\build folder in File Explorer. Never delete input, output, cpp, or grid.txt. Then run the configure and build commands again:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=%CONDA_PREFIX%
cmake --build build

Don't reuse a build folder with a different generator than the one that created it.

Resetting the environment

conda deactivate
conda remove -n stfm-cpp --all -y
conda create -n stfm-cpp -c conda-forge cmake ninja cxx-compiler libnetcdf eccodes -y

This doesn't touch your code, grid, or data.

4. Project structure

Don't change this layout:

tutorial/
├── CMakeLists.txt
├── GUIA_CPP.md
├── grid.txt
├── cpp/
│   ├── include/
│   │   └── common.hpp
│   └── src/
│       ├── common.cpp
│       ├── converter_espec.cpp
│       ├── converter_gbly.cpp
│       └── converter_grib.cpp
├── input/
│   ├── espec/ (water_u, water_v, temperature, salinity)
│   ├── gbly/ (currents, temperature)
│   └── grib/
└── output/ (currents, temperature, winds)

The programs look for grid.txt, input, and output relative to the folder they're run from.

5. Preparation of input files

Following the folder structure above:

• ESPEC: water_u, water_v, water_temp, and salinity files in their matching input/espec subfolders.
• GBLY: currents in input/gbly/currents, temperature/salinity in input/gbly/temperature.
• GRIB2: .grib2 or .grb2 files in input/grib.

Matching ocean files must share the same YYYYMMDDHH in their names. Keep grid.txt at the root of the tutorial folder.

6. Depth configuration

By default, ESPEC and GBLY process the surface only:

const std::vector<double> levels{0.0};

This line lives in converter_espec.cpp and converter_gbly.cpp. For multiple levels:

const std::vector<double> levels{
0, 2, 4, 6, 8, 10, 15, 20, 25, 50, 100, 250,
500, 1000, 2000, 3000, 4000, 5000
};

Save the file, then rebuild:

cmake --build build

You don't need to run conda create again for this.

7. Running the converters

At the Miniforge prompt, enter the tutorial folder:

cd /d C:\Users\your_user\Documents\SISMOM\tutorial

On another computer, use the real path. /d also lets you switch drives, e.g. from C: to D:. Check what's inside:

dir

You should see CMakeLists.txt, grid.txt, cpp, input, and output.

Confirm (stfm-cpp) is active and the terminal is inside the tutorial folder before running any of these.

ESPEC: place the NetCDFs in input\espec\water_u, water_v, temperature, and salinity, then run:

build\converter_ESPEC_cpp.exe

GBLY: place current data in input\gbly\currents and thermal data in input\gbly\temperature, then run:

build\converter_GBLY_cpp.exe

GRIB2: place .grib2/.grb2 files in input\grib, then run:

build\converter_grib_cpp.exe

[OK] messages mark files as they're created; [DONE] marks the end of the run.

Daily routine, once everything's installed and compiled:

conda activate stfm-cpp
cd /d C:\Users\your_user\Documents\SISMOM\tutorial
build\converter_ESPEC_cpp.exe
build\converter_GBLY_cpp.exe
build\converter_grib_cpp.exe

Run only the converter that matches your input data.

8. Generated files

output\currents\currents_YYYYMMDD_HH.txt
output\temperature\temperature_YYYYMMDD_HH.txt
output\winds\winds_YYYYMMDD_HH.txt

Example: output\winds\winds_20260810_12.txt. An existing result with the same date/time is replaced, so copy anything important before reprocessing.

9. Troubleshooting

"conda" is not recognised

Open Miniforge Prompt, not a regular Command Prompt. If the shortcut is missing, reinstall Miniforge and keep the shortcuts option checked.

"cl" is not recognised

In Visual Studio Installer, choose Modify and confirm Desktop C++, MSVC, and the Windows SDK are checked. Use the x64 Native Tools terminal, as in section 3.

"cmake" or "ninja" is not recognised

conda activate stfm-cpp
conda install -n stfm-cpp -c conda-forge cmake ninja -y

NetCDF or ecCodes not found

conda activate stfm-cpp
conda install -n stfm-cpp -c conda-forge libnetcdf eccodes -y
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=%CONDA_PREFIX%

converter_grib_cpp wasn't created

ecCodes wasn't found. Reinstall it with the command above and configure again.

Missing DLL while running

Don't double-click the .exe. Run it from Miniforge Prompt with stfm-cpp active. Activation is what makes the DLLs available.

grid.txt not found

cd /d C:\correct\path\tutorial
dir grid.txt

Matching file not found

Check the subfolder, extension, and the YYYYMMDDHH in the filename. Matching ESPEC or GBLY files need to represent the same instant.

"FAILED" appeared

Look for the first error line; everything after it may just be a consequence. Test cl, cmake, ninja, and codes_info -v individually.

Processing looks stuck

Global grids and files can take time. Check whether an output file is still growing, and don't close the terminal mid-run.

10. Checklist

• Build Tools installed with Desktop C++, MSVC, and the Windows SDK;
• Miniforge installed;
• stfm-cpp created and activated;
• cl, cmake, ninja, and codes_info all work;
• terminal is inside the tutorial folder;
• data is in the correct folders;
• CMake configure finished with no error;
• all three executables exist in build;
• important old results are protected from being overwritten.

Fortran

Objective: install, configure, and run the STFM converters in Fortran.

1. Presentation

This guide is written for Windows 10/11 and for people who haven't worked with Fortran before. These programs read the same data, interpolate it onto grid.txt, and generate the same text files for STFM as the other three languages.

Program	Input	Output
converter_espec_fortran.exe	NetCDF ESPEC/HYCOM, separate variables	currents, temperature and salinity
converter_gbly_fortran.exe	NetCDF GBLY/HYCOM, grouped variables	currents, temperature and salinity
converter_grib_fortran.exe	GRIB2 weather data	wind at 10 m and air temperature at 2 m

How this differs from the Python version

• The programs are compiled once, then run as .exe files.
• They don't depend on pandas, NumPy, xarray, or cfgrib.
• The ocean converters talk to NetCDF-Fortran directly.
• The weather converter uses ecCodes utilities to pull out 10u, 10v, and 2t, with interpolation done in Fortran.
• The target grid, longitude normalization, the ±10 m/s cutoff for invalid currents, the Kelvin-to-Celsius conversion, and the output filenames all match the Python scripts exactly.

2. Download the scripts

Download Fortran scripts (.zip)

Quick registration required before download.

3. Requirements and installation

This uses Miniforge/Conda to install everything in an isolated environment:

• LLVM Flang: the NetCDF-Fortran-compatible compiler conda-forge distributes for Windows;
• Visual Studio Build Tools: provides the linker and Windows system libraries;
• CMake and Ninja: configure and run the build;
• NetCDF-Fortran: reads the ocean .nc files;
• ecCodes: reads the .grib2/.grb2 files.

Recommended: 64-bit Windows, at least 8 GB RAM (16 GB for large grids), internet access during install, and free space for data and results. The combination validated for this tutorial is LLVM Flang + NetCDF-Fortran from conda-forge + Visual Studio Build Tools 2022.

Install Visual Studio Build Tools

1. Download Build Tools for Visual Studio 2022 from visualstudio.microsoft.com/downloads.
2. In the installer, check Desktop development with C++.
3. Confirm MSVC x64/x86 and the Windows 10/11 SDK are selected.
4. Finish the install and restart Windows if prompted.

Even though the code is Fortran, on Windows Flang relies on the linker and system libraries this package provides.

Install Miniforge

1. Go to conda-forge.org/download.
2. Download Miniforge for Windows x86_64.
3. Run the installer, choose Just Me, and keep the Start menu shortcuts.
4. You don't need to add Miniforge to PATH manually.
5. Open Miniforge Prompt and test:

conda --version

Create the Fortran environment

In Miniforge Prompt, enter the tutorial folder first, then create the environment from the validated versions file:

cd /d C:\Users\your_user\Documents\SISMOM\tutorial
conda env create -f environment-fortran.yml
conda activate stfm-fortran

environment-fortran.yml pins the exact combination this tutorial was tested with. On a different computer, only adjust the folder path. Don't change the pinned versions.

Check the install:

flang-new --version
cmake --version
ninja --version
codes_info -v
where flang-new
dir "%CONDA_PREFIX%\Library\include\netcdf.mod"

Keep (stfm-fortran) visible in the terminal, and reactivate it every time you open a new one. The nf-config utility, common on Linux, may not exist on Windows. The presence of netcdf.mod is the right check here instead.

Compile

On Windows, Flang and lld-link also need the Windows SDK and MSVC libraries. Open x64 Native Tools Command Prompt for VS 2022 from the Start menu, then activate Conda in that same terminal:

call %USERPROFILE%\miniforge3\Scripts\activate.bat
conda activate stfm-fortran

If Miniforge is installed somewhere else, adjust that first path. Then enter the project folder:

cd /d C:\Users\your_user\Documents\SISMOM\tutorial

Configure explicitly with Flang, using a separate build folder from the C++ tutorial's if you've already built that one:

cmake -S . -B build-fortran-flang -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="%CONDA_PREFIX%" -DCMAKE_Fortran_COMPILER="%CONDA_PREFIX%\Library\bin\flang-new.exe"
cmake --build build-fortran-flang

Type the parameters with plain underscores, e.g. CMAKE_BUILD_TYPE. Don't add a backslash before it.

Check the executables:

dir build-fortran-flang\*fortran.exe

All three programs from the table above should appear. If CMake reports it can't find the compiler or NetCDF-Fortran, confirm (stfm-fortran) is active and recreate build-fortran-flang as described below.

Rebuilding only

Close any programs using the executables, then delete only build-fortran-flang in File Explorer. Never delete input, output, fortran, or grid.txt. Then, in x64 Native Tools Command Prompt for VS 2022 with stfm-fortran active:

cmake -S . -B build-fortran-flang -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="%CONDA_PREFIX%" -DCMAKE_Fortran_COMPILER="%CONDA_PREFIX%\Library\bin\flang-new.exe"
cmake --build build-fortran-flang

4. Project structure

tutorial/
├── CMakeLists.txt
├── GUIA_FORTRAN.md
├── environment-fortran.yml
├── grid.txt
├── fortran/
│   ├── stfm_common.f90
│   ├── converter_espec.f90
│   ├── converter_gbly.f90
│   └── converter_grib.f90
├── input/
│   ├── espec/ (water_u, water_v, temperature, salinity)
│   ├── gbly/ (currents, temperature)
│   └── grib/
└── output/ (currents, temperature, winds)

Run the programs from the tutorial folder. The paths they use are relative to it.

5. Preparation of input files

Following the folder structure above:

• ESPEC: water_u, water_v, water_temp, and salinity files in their matching input/espec subfolders.
• GBLY: currents in input/gbly/currents, temperature/salinity in input/gbly/temperature.
• GRIB2: .grib2 or .grb2 files in input/grib.

Matching ocean files must share the same YYYYMMDDHH in their names. Keep grid.txt at the root of the tutorial folder.

6. Depth configuration

ESPEC and GBLY start out using only the surface:

real(dp), parameter :: levels(1) = [0.0_dp]

This line is in converter_espec.f90 and converter_gbly.f90. For multiple levels, replace it with:

real(dp), parameter :: levels(18) = [ &
0._dp, 2._dp, 4._dp, 6._dp, 8._dp, 10._dp, 15._dp, 20._dp, 25._dp, &
50._dp, 100._dp, 250._dp, 500._dp, 1000._dp, 2000._dp, 3000._dp, &
4000._dp, 5000._dp ]

Save, then rebuild:

cmake --build build-fortran-flang

Only request depths that the source files actually cover.

7. Running the converters

ESPEC: place the matching NetCDFs in the four input\espec subfolders and run:

build-fortran-flang\converter_espec_fortran.exe

The water_u file is the anchor: its internal date identifies the matching water_v, temperature, and salinity files.

GBLY: place current data in input\gbly\currents and thermal data in input\gbly\temperature, then run:

build-fortran-flang\converter_gbly_fortran.exe

GRIB2: place the files in input\grib, then run:

build-fortran-flang\converter_grib_fortran.exe

Keep the Conda environment active during the run. The GRIB converter calls grib_get and grib_get_data, the official ecCodes tools.

Global GRIB files are much larger than the local grid, so this is usually the slowest converter. It uses O(n log n) sorting and binary search to organize the global coordinates. Don't replace these with simple linear scans, since that alone can push processing from minutes to hours. ESPEC and GBLY apply the same optimizations through the shared stfm_common.f90 module: quicksort while loading grid.txt, and binary search during ocean interpolation.

Daily routine, once everything's set up:

conda activate stfm-fortran
cd /d C:\Users\your_user\Documents\SISMOM\tutorial
build-fortran-flang\converter_espec_fortran.exe
build-fortran-flang\converter_gbly_fortran.exe
build-fortran-flang\converter_grib_fortran.exe

Run only the converter that matches your input data.

8. Generated files

output\currents\currents_YYYYMMDD_HH.txt
output\temperature\temperature_YYYYMMDD_HH.txt
output\winds\winds_YYYYMMDD_HH.txt

[OK] marks each result as it's created, and [DONE] marks the end of the batch. An existing file with the same date/time is replaced.

9. Troubleshooting

"conda", "flang-new", or "cmake" is not recognised

Open Miniforge Prompt and run conda activate stfm-fortran. If only flang-new is missing, install the Fortran build metapackage:

conda install -n stfm-fortran -c conda-forge fortran-compiler -y
conda deactivate
conda activate stfm-fortran
flang-new --version

Don't mix gfortran with this environment's NetCDF-Fortran on Windows. .mod module files are compiler-specific, and conda-forge's NetCDF-Fortran package here is built for Flang.

NetCDF-Fortran not found

conda install -n stfm-fortran -c conda-forge libnetcdf netcdf-fortran -y
dir "%CONDA_PREFIX%\Library\include\netcdf.mod"

On Windows, nf-config may not exist; its absence alone doesn't mean NetCDF-Fortran is missing. Reconfigure after installing.

"grib_get" or "grib_get_data" is not recognised

conda install -n stfm-fortran -c conda-forge eccodes -y

GRIB converter runs for a long time without finishing

Abort with Ctrl+C, confirm the code is up to date, and recompile converter_grib_fortran. Global GFS grids can legitimately take a few minutes, but the CPU should stay active throughout. An older version of the converter used a quadratic sort that could take hours. It's since been replaced with quicksort and binary search.

grid.txt not found

The terminal is in the wrong folder. Enter the tutorial folder before running.

Matching file not found

Check the subfolder and date. ESPEC and GBLY match files by internal date and by the YYYYMMDDHH sequence in the filename.

Unsupported dimension order

The expected NetCDFs use the time, depth, lat, and lon dimensions, matching this tutorial's HYCOM examples. A product with different names or ordering needs an adjustment in stfm_common.f90.

Missing DLL

Run from Miniforge Prompt with stfm-fortran active. Activation is what provides the NetCDF and ecCodes DLLs.

"msvcrt.lib" or "OLDNAMES.lib" not found

The terminal never loaded Visual Studio's x64 developer environment. Close it, open x64 Native Tools Command Prompt for VS 2022, activate stfm-fortran, and compile again. No need to reinstall NetCDF. You can also load the developer environment into your current prompt before compiling:

call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
conda activate stfm-fortran
cmake --build build-fortran-flang

10. Checklist

• scripts downloaded and extracted from the download button;
• language tools and dependencies installed;
• grid.txt present in the tutorial folder;
• source data in the correct input subfolders;
• depths configured as needed;
• terminal opened inside the tutorial folder;
• enough free space available, and previous results protected.