============ Output Files ============ 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 except the forcing diagnostics ``tide_potential``, ``bpg_effective`` and ``wave_force`` and the wave periods ``wave_tmm10`` and ``wave_tps``, which are opt-in. You can selectively disable individual variables (or enable the opt-in ones) using the ``variables`` section: .. code-block:: yaml output: variables: pressure: false # Disable atmospheric pressure output wind: false # Disable wind velocity output tide_potential: true # Enable tidal potential output (off by default) bpg_effective: true # Enable effective BPG output (off by default) **Rules:** - Except for the opt-in diagnostics, only variables explicitly set to ``false`` are disabled. Setting such a variable to ``true`` or omitting it has the same effect -- it remains enabled. - ``tide_potential``, ``bpg_effective``, ``wave_force``, ``wave_tmm10`` and ``wave_tps`` are written only when explicitly set to ``true``. - Only time-series variables have a setting. The wave peaks follow the setting of the series they are taken from (``wave_tm01_max`` is written when ``wave_tm01`` is); the other peak variables are always written. - 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, the ``bpg_effective`` pair only when baroclinic forcing is enabled, the ``wave_force`` pair only when wave forcing is enabled, and the wave parameters (``wave_hs``, ``wave_dir``, ``wave_tm01``, ``wave_tmm10``, ``wave_tps``) only when the internal wave model drives it (``forcing.wave.source: model``). **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. Off by default; set to ``true`` to write it. * - ``bpg_effective`` - ``bpg_effective_x``, ``bpg_effective_y`` - Effective baroclinic pressure gradient components (m/s2), the file value plus the free-surface correction. Requires baroclinic forcing. Off by default; set to ``true`` to write it. * - ``wave_force`` - ``wave_force_x``, ``wave_force_y`` - Wave radiation-stress force per unit density (m2/s2), ramped and uncapped (:doc:`wave_forcing`). Requires wave forcing. Off by default; set to ``true`` to write it. * - ``wave_hs``, ``wave_dir``, ``wave_tm01`` - the same names - The internal wave model's significant wave height, mean direction and absolute mean period Tm01 at the last coupling, each with its CF ``standard_name``. Requires ``forcing.wave.source: model``. * - ``wave_tmm10``, ``wave_tps`` - the same names - The absolute mean period Tm-10 and SWAN's smoothed peak period, as above. Off by default; set to ``true`` to write them. 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) * - ``bpg_effective_x`` - Effective baroclinic pressure gradient, x-component - m s-2 - (time, node) * - ``bpg_effective_y`` - Effective baroclinic pressure gradient, y-component - m s-2 - (time, node) * - ``wave_force_x`` - Wave radiation-stress force per unit density, x-component - m2 s-2 - (time, node) * - ``wave_force_y`` - Wave radiation-stress force per unit density, y-component - m2 s-2 - (time, node) * - ``wave_hs`` - Significant wave height, 4 sqrt(m0) (Hm0). As in SWAN's output, the moments m0, m1 and m-1 include a sigma^-4 tail above the top frequency, a visible share of Tm01 at low wind, when the peak sits close to the top. - m - (time, node) * - ``wave_dir`` - Mean wave direction, where the waves come from, as a bearing clockwise from north on [0, 360) (CF ``sea_surface_wave_mean_from_direction``, the buoy convention). SWAN's default Cartesian ``DIR``, and so ADCIRC's ``swan_DIR`` without ``SET NAUTICAL``, is where the waves travel, counterclockwise from east: :math:`270^\circ` minus this. - degrees - (time, node) * - ``wave_tm01`` - Absolute mean wave period 2 pi m0 / m1, the moments taken over the absolute frequency :math:`\omega = \sigma + k\,\mathbf U\cdot \hat{\boldsymbol\theta}` that a fixed point sees, as SWAN's ``TM01`` and ADCIRC's ``swan_TM01``. It equals the intrinsic period where there is no current. - s - (time, node) * - ``wave_tmm10`` - Absolute mean wave period 2 pi m-1 / m0, as SWAN's ``TMM10`` - s - (time, node) * - ``wave_tps`` - Smoothed peak period: the parabola through the discrete peak of the frequency spectrum and its neighbors, intrinsic, as SWAN's ``TPS`` - s - (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 and ``output.variables.tide_potential`` is set to ``true``; likewise ``bpg_effective_x``/``bpg_effective_y`` require baroclinic forcing and ``output.variables.bpg_effective: true``, and ``wave_force_x``/``wave_force_y`` wave forcing and ``output.variables.wave_force: true``. .. _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``. The hydrodynamic and meteorological peaks are always written; each wave peak is written when its series is (:ref:`output-variable-selection`). The wave peaks are one record per node, taken at the coupling where that node's significant wave height was largest: ``wave_tm01_max`` is the Tm01 of that sea state, not the largest Tm01 of the run. A later coupling replaces the record only with a strictly larger Hs, so a tie keeps the earlier time. The record is updated at every coupling, so it does not depend on the output interval. Like the other peaks it is not checkpointed: a restarted run's peaks cover the restarted leg only. .. 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) * - ``wave_hs_max`` - Maximum significant wave height - m - (node) * - ``wave_dir_max`` - Mean wave direction (from, clockwise from north) at the time of the maximum significant wave height - degrees - (node) * - ``wave_tm01_max`` - Absolute mean wave period Tm01 at the time of the maximum significant wave height - s - (node) * - ``wave_tmm10_max`` - Absolute mean wave period Tm-10 at the time of the maximum significant wave height; written when ``wave_tmm10`` is - s - (node) * - ``wave_tps_max`` - Smoothed peak wave period at the time of the maximum significant wave height; written when ``wave_tps`` is - 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; use it when one 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()