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.

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" ;
    double zeta(time, node) ;
        zeta:units = "m" ;
        zeta:long_name = "water surface elevation" ;
    double ucx(time, node) ;
        ucx:units = "m/s" ;
        ucx:long_name = "eastward velocity" ;
    double ucy(time, node) ;
        ucy:units = "m/s" ;
        ucy:long_name = "northward velocity" ;
    double zeta_max(node) ;
        zeta_max:units = "m" ;
        zeta_max:long_name = "Peak water surface elevation" ;
    double velocity_max(node) ;
        velocity_max:units = "m s-1" ;
        velocity_max:long_name = "Peak velocity magnitude" ;

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()