============ 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`. .. _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" ; 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) ^^^^^^^^^^^^^^^ .. 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()