FVCOM Pre- and Post-Processing Utilities

Professional toolkit for FVCOM (Finite Volume Community Ocean Model) pre-processing, data preparation, and post-processing workflows.

This repository provides a comprehensive suite of Python modules and utilities to streamline the operational forecast cycle for FVCOM, including atmospheric forcing acquisition, oceanic data interpolation, boundary condition preparation, and model output analysis.

---

📋 Project Structure

Data Download Modules

download_hycom.py

Automated download of 3D oceanic data (temperature, salinity) from HYCOM with domain subsetting.

Capabilities:

• Supports both forecast (ESPC-D-V02) and historical (GLBy0.08 expt_93.0) modes
• Spatial and temporal subsetting via bounding box and date range
• NetCDF output with standardized dimensions: (time, depth, lat, lon)
• Command-line interface and importable API

Output: NetCDF with water_temp, salinity, coordinates

---

download_gfs.py

NCEP/NOMADS Global Forecast System (GFS) 0.25° atmospheric data acquisition.

Features:

• Automated GRIB filtering and subsetting via filter_gfs_0p25.pl service
• Retrieves: u10, v10 (wind), T2m (temperature), RH (relative humidity), PRMSL (pressure)
• Forecast cycle and hours-ahead specification
• Automatic cycle detection (latest available GFS cycle)

Output: NetCDF-converted forecast data ready for FVCOM forcing

---

download_era5.py

ERA5 reanalysis hourly wind data (u10/v10) from Copernicus Climate Data Store.

Requirements:

• Copernicus CDS API credentials (~/.cdsapirc)
• cdsapi Python package

Output: NetCDF with u10, v10, standardized lat/lon/time grid

---

Pre-Processing & Initial Conditions

modify_restart.py

Updates FVCOM restart files with downloaded oceanic forcing data.

Workflow:

1. Load FVCOM mesh (lon, lat, bathymetry, sigma layers)
2. Load forcing data (HYCOM/Mercator/GLORYS)
3. 3D interpolation of temperature & salinity to FVCOM nodes
4. Nearest-neighbor infill for masked regions
5. Update restart variables: temp, salinity, tmean1, smean1

Usage:

from modify_restart import modify_restart_from_forcing
modify_restart_from_forcing(
    restart_file='restart.nc',
    forcing_file='hycom_forecast.nc',
    add_nh_vars=True,
)

---

modify_restart_copernicus.py

Advanced restart modification with Copernicus/GLORYS data and density computation.

Additional Features:

• Interpolates velocity fields (u, v) to element centers
• Computes seawater density (EOS-80 equation of state at p=0)
• Updates density variables: rho1, rmean1, ua, va
• Synchronizes restart date/time to specified epoch

Example:

from modify_restart_copernicus import modify_restart_from_copernicus
modify_restart_from_copernicus(
    restart_src='restart_feb.nc',
    restart_out='restart_feb_modified.nc',
    forcing_file='copernicus_20000208.nc',
    target_date='2000-02-08 00:00:00',
)

---

create_initial_conditions.py

Constructs 3D temperature and salinity initial conditions from oceanic forcing.

Core Functions:

• build_initial_conditions(): Loads mesh, interpolates T/S to sigma layers
• write_ic_to_restart(): Embeds IC into FVCOM restart file

Key Steps:

• Grid loading from restart or reference NetCDF
• Full 3D+time interpolation with sigma layer handling
• NaN-filling via nearest-neighbor search
• Optional OBC (open boundary condition) output

---

create_tsobc.py

Generates/updates FVCOM open boundary condition files for temperature & salinity.

Features:

• Extracts OBC node indices and metadata from template file
• Interpolates forcing T/S to all FVCOM nodes (3D+time)
• Subsamples to OBC nodes only
• Preserves original header structure; updates T/S and time variable

Typical Use:

from create_tsobc import create_tsobc_from_forcing
create_tsobc_from_forcing(
    grid_file='restart.nc',
    forcing_file='glorys_forecast.nc',
    tsobc_template='tsobc_template.nc',
    output_file='tsobc_forecast.nc',
)

---

create_wind_uv.py

Converts downloaded wind data (ERA5 or GFS) to FVCOM meteorological forcing format.

Input Sources:

• ERA5 (hourly, Copernicus) → create_wind_forcing_from_era5()
• GFS forecast (NCEP NOMADS) → create_wind_forcing_from_gfs()
• Generic lon/lat NetCDF → create_wind_forcing()

Output: NetCDF with FVCOM-compliant structure:

• Variables: U10, V10, XLAT, XLONG, Times
• Global attributes: Standard WRF-grid metadata

---

tpxo_elevtide.py

Tidal elevation boundary forcing from TPXO9-atlas-v5 harmonic constants.

Astronomical Computations:

• Interpolates 8 principal constituents (M2, S2, N2, K2, K1, O1, P1, Q1)
• Computes nodal corrections (Schureman/Foreman)
• Predicts hourly/sub-hourly elevation time series for OBC nodes
• Outputs FVCOM-formatted elevation forcing file

Example:

from tpxo_elevtide import create_elevtide_from_tpxo
create_elevtide_from_tpxo(
    restart_file='restart_modified.nc',
    tpxo_dir='data/tpxo',
    output_file='elevtide.nc',
    start='2006-02-08 00:00:00',
    end='2006-03-10 00:00:00',
    dt_minutes=10,
)

---

Post-Processing & Analysis

cut_fvcom_output.py

Spatially subsets FVCOM model output by geographic bounds.

Purpose: Reduce file size and processing time for large output datasets.

Workflow:

1. Load FVCOM output mesh via PyFVCOM
2. Filter elements by lat/lon bounding box
3. Extract sub-dataset with specified variables

Function:

def cut_fvcom(min_lon, max_lon, min_lat, max_lat, file_name, variables):
    # Returns FileReader object with subset data

---

DeleteVectorsByMagnitude.py

Post-processing utility for velocity field visualization.

Function: delete_vectors(u_velocity, v_velocity, critical_value)

Problem Solved: When plotting FVCOM velocity vectors, extreme values often dominate and obscure smaller-scale features. This utility zeros out (or minimizes) vectors exceeding a specified magnitude threshold.

Usage:

from DeleteVectorsByMagnitude import delete_vectors
u_mod, v_mod = delete_vectors(u_field, v_field, critical_value=1.5)

---

validate_temp_profiles.py

Compares FVCOM modeled temperature profiles against in-situ observations.

Functionality:

• Loads FVCOM model output and in-situ station data
• Locates nearest FVCOM node to each station position
• Finds closest model time to observation time
• Generates side-by-side depth profile plots

Output: PNG plots comparing model vs. observations at each station

Data location: In-situ CSV files are read from ./data/in_situ/<year>/. Override the base directory with the IN_SITU_DATA_DIR environment variable or the data_dir argument of validate_profiles().

---

visualize.py

Quick-look visualization functions for downloaded and processed forcing data.

Functions:

• plot_hycom_surface(): SST & SSS maps from HYCOM
• plot_hycom_section(): Vertical sections (T or S) along a longitude
• plot_wind(): Wind magnitude + vector arrows (ERA5/GFS)
• plot_wind_timeseries(): Time series of wind at a point location

Optional Dependencies: Cartopy (mapping), cmocean (colormaps)

---

Notebooks

create_assim_files.ipynb

Jupyter notebook demonstrating data assimilation workflow.

Demonstrates:

• Loading FVCOM .mat files (MATLAB-format mesh data)
• Extracting grid coordinates and bathymetry
• Configuring model time window and domain
• Opening multi-file FVCOM output datasets with xarray

---

plot/temp_mur.ipynb

Visualization of MUR PODAAC JPL-L4 GHRSST analyzed sea surface temperature.

Purpose: Quick plotting of satellite SST data for model validation

---

🚀 Quick Start

Installation

# Clone repository
git clone <repo_url>
cd fvcom_stuff

# Install dependencies
pip install -r requirements.txt

# Optional visualization packages
pip install matplotlib cartopy cmocean

Typical Forecast Workflow

import fvcom_stuff as fs

# 1. Download forcing data
fs.download_hycom(
    lon_min=-115, lon_max=-105,
    lat_min=20, lat_max=32,
    date_start='2026-06-01',
    date_end='2026-06-04',
    output_file='hycom_forecast.nc',
    mode='forecast',
)

fs.download_gfs_forecast(
    lon_min=-115, lon_max=-105,
    lat_min=20, lat_max=32,
    output_file='gfs_forecast.nc',
    f_start=0, f_end=72, f_step=3,
)

# 2. Prepare restart file
fs.modify_restart_from_forcing(
    restart_file='restart_template.nc',
    forcing_file='hycom_forecast.nc'
)

# 3. Generate boundary conditions
fs.create_tsobc_from_forcing(
    grid_file='restart_template.nc',
    forcing_file='hycom_forecast.nc',
    tsobc_template='tsobc_template.nc',
    output_file='tsobc_forecast.nc'
)

# 4. Prepare wind forcing
fs.create_wind_forcing_from_gfs(
    wind_file='gfs_forecast.nc',
    output_file='wind_forcing.nc'
)

# 5. Generate tidal elevation
fs.create_elevtide_from_tpxo(
    restart_file='restart_modified.nc',
    tpxo_dir='tpxo_data',
    output_file='elevtide.nc',
    start='2026-06-01 00:00:00',
    end='2026-06-04 00:00:00',
)

---

📚 Dependencies

Package	Purpose
numpy	Numerical arrays and operations
scipy	Interpolation, scientific functions
xarray	NetCDF I/O and data manipulation
netCDF4	Direct NetCDF file access
pandas	Time series and data frames
PyFVCOM	FVCOM-specific tools and mesh handling
cdsapi	Copernicus CDS API (for ERA5)
matplotlib	Static plotting
cartopy	Geographic mapping (optional)
cmocean	Oceanographic colormaps (optional)

---

🔧 Configuration

ERA5 (Copernicus CDS)

Create ~/.cdsapirc:

url: https://cds.climate.copernicus.eu/api/v2
key: <YOUR_UID>:<YOUR_API_KEY>

Obtain credentials at: https://cds.climate.copernicus.eu/

---

⚠️ Important Notes

1. Path Hardcoding: Some modules contain hardcoded system paths. Parametrize these using environment variables or configuration files before production use.

2. Coordinate Conventions: Longitude handling varies across datasets:

   • HYCOM, ERA5: [-180, 180]
   • GFS: [0, 360]
   • FVCOM: typically [-180, 180] (internally converted)

   Verify your grid's convention and adjust conversion flags accordingly.

3. Interpolation: All 3D interpolation uses RegularGridInterpolator (rectilinear grids). For curvilinear grids, consider scipy.interpolate.griddata or PyFVCOM's native methods.

4. Time Handling: Datetimes are converted to Modified Julian Date (MJD) where needed; ensure consistency across modules.

---

📖 References

• FVCOM: http://fvcom.smast.umassd.edu/
• PyFVCOM: https://github.com/pwbrown/PyFVCOM
• HYCOM: https://www.hycom.org/
• GFS: https://www.ncei.noaa.gov/products/weather-global-forecast-system
• ERA5: https://www.ecmwf.int/en/forecasts/dataset/ecmwf-reanalysis-v5
• TPXO: https://www.tpxo.net/
• Tidal Theory: Schureman, P. (1941). Manual of Harmonic Analysis and Prediction of Tides.

---

📝 License & Attribution

Released under the MIT License. Developed for operational FVCOM forecasting workflows.

For questions or contributions, please refer to the project documentation or contact the development team.

---

Last Updated: June 2026