Output Files

Cocoa produces NetCDF output files containing simulation results.

Output Configuration

Configure output in the YAML file:

output:
  step_interval: 1h               # Output every hour (or integer step count)
  filename: cocoa_output.nc        # Output filename (optional)
  mode: split                      # "split" (default) or "combined"
  variables:                       # Selectively disable time-series variables
    pressure: false
    wind: false

By default the output file is named cocoa_output.nc in the working directory. Use the filename parameter to change it.

Parameters:

Parameter	Type	Default	Description
`step_interval`	int or duration	100	Interval between output writes. Accepts a plain integer (number of time steps) or a duration string with suffix: `s`, `m`, `h`, `d` (e.g., `15m`, `1h`). See Duration Syntax.
`filename`	string	`cocoa_output.nc`	Output NetCDF filename
`mode`	string	`split`	Output mode for peak variables. `split` writes peak data to a separate file; `combined` writes everything to one file. See Output Mode.
`variables`	map	(all enabled)	Selectively disable time-series variables. See Variable Selection.
`compression`	map	`level: 1`, `shuffle: false`	NetCDF deflate settings for output variables. See Compression.

Compression

Output variables are written with NetCDF-4 deflate compression. The level and the HDF5 byte-shuffle filter are configurable:

output:
  compression:
    level: 1        # Deflate level 0-9; 0 disables compression entirely
    shuffle: false  # Byte-shuffle filter (small ratio gain, slower writes)

Compression runs on the background writer thread, one snapshot at a time. When output is frequent enough that compressing a snapshot takes longer than the simulation takes to reach the next output step, the writer falls behind and the simulation stalls waiting for it. If frequent output is slowing the model down, reduce level — or set level: 0 to write uncompressed, which removes the compression cost entirely at the price of larger files. Files remain valid NetCDF-4 at every setting, and readers do not need any configuration to match.

Variable Selection

By default, all available time-series variables are written. You can selectively disable individual variables using the variables section:

output:
  variables:
    pressure: false    # Disable atmospheric pressure output
    wind: false        # Disable wind velocity output

Rules:

Omitting the variables section enables all variables (backward compatible).
Only variables explicitly set to false are disabled. Setting a variable to true or omitting it has the same effect — it remains enabled.
Only time-series variables can be disabled. Peak variables are always written regardless of this setting.
Meteorological variables (pressure, wind) are only available when meteorological forcing is enabled.
The tide_potential variable is only available when tidal potential forcing is enabled.

Available time-series variables:

YAML Name	NetCDF Variable(s)	Description
`zeta`	`zeta`	Water surface elevation (m)
`velocity`	`ucx`, `ucy`	Velocity vector components (m/s)
`pressure`	`pressure`	Atmospheric pressure at mean sea level (Pa). Requires meteorological forcing.
`wind`	`wind_u`, `wind_v`	Wind velocity vector components (m/s). Requires meteorological forcing.
`tide_potential`	`tide_potential`	Tidal potential displacement (m). Requires tidal potential forcing.

Output Variables

Time-Series Variables

Time-varying variables are written at each output interval. Dry nodes are masked using a fill value of -99999.0.

Variable	Description	Units	Dimensions
`zeta`	Water surface elevation	meters	(time, node)
`ucx`	Eastward velocity component	m/s	(time, node)
`ucy`	Northward velocity component	m/s	(time, node)
`pressure`	Atmospheric pressure at mean sea level	Pa	(time, node)
`wind_u`	Eastward wind velocity component	m/s	(time, node)
`wind_v`	Northward wind velocity component	m/s	(time, node)
`tide_potential`	Tidal potential displacement	m	(time, node)

Note

The pressure, wind_u, and wind_v variables are only present when meteorological forcing is enabled. The tide_potential variable is only present when tidal potential forcing is enabled.

Peak Variables

Peak (maximum) values are accumulated over the entire simulation and written once at the end. Nodes that were never wet contain the fill value -99999.0. Peak variables are always written and cannot be disabled.

Variable	Description	Units	Dimensions
`zeta_max`	Peak water surface elevation	meters	(node)
`velocity_max`	Peak velocity magnitude	m/s	(node)
`pressure_min`	Minimum atmospheric pressure	Pa	(node)
`wind_max`	Peak wind speed	m/s	(node)

Note

The pressure_min and wind_max variables are only present when meteorological forcing is enabled.

Output Mode

The mode parameter controls whether peak variables are written to the same file as time-series data or to a separate file.

Split Mode (Default)

output:
  mode: split

In split mode, Cocoa writes two files:

Main file (cocoa_output.nc): time-series variables only
Peak file (cocoa_output_peak.nc): peak variables only

The peak filename is derived from the main filename by inserting _peak before the .nc extension. For example:

Main Filename	Peak Filename
`cocoa_output.nc`	`cocoa_output_peak.nc`
`gulf_simulation.nc`	`gulf_simulation_peak.nc`

Split mode is the default because peak files are small and easy to transport independently of the larger time-series file.

Combined Mode

output:
  mode: combined

In combined mode, both time-series and peak variables are written to a single file. This is the legacy behavior and may be preferred when a single file is more convenient.

NetCDF File Structure

Output files follow CF-1.8 and UGRID-1.0 conventions. Example structure (combined mode):

dimensions:
    time = UNLIMITED ;
    node = 1000 ;
    nfaces = 1800 ;

variables:
    double time(time) ;
        time:units = "seconds since 1970-01-01 00:00" ;
        time:calendar = "standard" ;
    double x(node) ;
        x:units = "degrees_east" ;
    double y(node) ;
        y:units = "degrees_north" ;
    float zeta(time, node) ;
        zeta:units = "m" ;
        zeta:long_name = "water surface elevation" ;
    float ucx(time, node) ;
        ucx:units = "m/s" ;
        ucx:long_name = "eastward velocity" ;
    float ucy(time, node) ;
        ucy:units = "m/s" ;
        ucy:long_name = "northward velocity" ;
    float zeta_max(node) ;
        zeta_max:units = "m" ;
        zeta_max:long_name = "Peak water surface elevation" ;
    float velocity_max(node) ;
        velocity_max:units = "m s-1" ;
        velocity_max:long_name = "Peak velocity magnitude" ;

Field variables are stored as single precision (float): ~7 significant digits, ample for model output products, at half the file size and write cost of double. Coordinates, bathymetry, and the time axis remain double.

In split mode, the main file omits the peak variables (zeta_max, velocity_max, etc.), and they appear in the separate peak file instead.

Reading Output Files

Python (xarray)

import xarray as xr

ds = xr.open_dataset("cocoa_output.nc")
zeta = ds['zeta']              # Time-varying elevation
zeta_max = ds['zeta_max']      # Peak elevation (combined mode)

# Plot time series at a specific node
zeta.isel(node=100).plot()

For split mode, open the peak file separately:

peak = xr.open_dataset("cocoa_output_peak.nc")
zeta_max = peak['zeta_max']

Python (netCDF4)

from netCDF4 import Dataset

nc = Dataset("cocoa_output.nc", "r")
zeta = nc.variables['zeta'][:]         # Shape: (time, node)
time = nc.variables['time'][:]
nc.close()

# For split mode peak data:
peak = Dataset("cocoa_output_peak.nc", "r")
zeta_max = peak.variables['zeta_max'][:] # Shape: (node,)
peak.close()