============
Output Files
============

Cocoa produces NetCDF output files containing simulation results.

Output Configuration
--------------------

Configure output in the YAML file:

.. code-block:: yaml

   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:**

.. list-table::
   :header-rows: 1
   :widths: 25 15 15 45

   * - 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 :ref:`duration-intervals`.
   * - ``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
       :ref:`output-mode`.
   * - ``variables``
     - map
     - *(all enabled)*
     - Selectively disable time-series variables. See
       :ref:`output-variable-selection`.
   * - ``compression``
     - map
     - ``level: 1``, ``shuffle: false``
     - NetCDF deflate settings for output variables. See
       :ref:`output-compression`.

.. _output-compression:

Compression
-----------

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

.. code-block:: yaml

   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.

.. _output-variable-selection:

Variable Selection
------------------

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

.. code-block:: yaml

   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:**

.. list-table::
   :header-rows: 1
   :widths: 20 20 50

   * - 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``.

.. list-table::
   :header-rows: 1

   * - 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.

.. _output-peak-variables:

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.

.. list-table::
   :header-rows: 1

   * - 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:

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

.. code-block:: yaml

   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:

.. list-table::
   :header-rows: 1

   * - 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
^^^^^^^^^^^^^

.. code-block:: yaml

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

.. code-block:: text

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

.. code-block:: python

   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:

.. code-block:: python

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

Python (netCDF4)
^^^^^^^^^^^^^^^^

.. code-block:: python

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