docs: put UFS-Coastal under Systems (README and docs index)

README.md

@@ -12,6 +12,21 @@ nos-utils is a Python package that generates the forcing and run-configuration f
 | STOFS-3D-ATL | SCHISM standalone, DATM+SCHISM; ported to match operational v3.1 | the same set plus ADT and tide-gauge SSH adjustment, NWM and St. Lawrence rivers, and the post products |
 | STOFS-2D-Global | ADCIRC | GFS meteorological forcing in ADCIRC OWI NetCDF form (NWS=14) |
 
+### UFS-Coastal
+
+For DATM-coupled (`nws=4`) configurations, prep also renders the per-cycle UFS-Coastal inputs from the templates and fix files staged in `$FIXofs`:
+
+| File | Module | What it holds |
+|---|---|---|
+| `datm_forcing.nc` | `blender` | GFS, or HRRR blended over GFS, on a regular lat/lon grid for CDEPS DATM |
+| `datm_esmf_mesh.nc` | `esmf_mesh` | ESMF unstructured mesh of that grid |
+| `model_configure`, `datm_in`, `datm.streams` | `ufs_config` | From the `*.template` files: start time (cycle minus nowcast length), length of the phase being prepped (nowcast, forecast, or both), `dt_atmos`, DATM grid size and file names |
+| `ufs.configure` | `ufs_config` | From `$FIXofs`, with the PET bounds set from the resource layout (MED, ATM, OCN, and WAV when wave tasks are set) and the `runSeq` coupling interval set to the SCHISM time step or a configured multiple of it |
+| `fd_ufs.yaml`, `noahmptable.tbl` | `ufs_config` | Copied from `$FIXofs` |
+| `nest.ww3` | `wave_boundary` | WW3 boundary spectra from the GFS-Wave point spectra, through `ww3_bound`, when waves are enabled and `$COMINgfswave` is set |
+
+`model_configure` uses the same start time as `param.nml` and `bctides.in` (cycle minus nowcast length), which keeps the CMEPS clock in step with SCHISM.
+
 ## Install, test, docs
 
 ```bash
@@ -46,21 +61,6 @@ A prep cycle runs through `PrepOrchestrator(config, paths, skip_legacy=False)`,
 
 Other packages: `nos_utils.interp` (structured and precomputed-weight interpolation), `nos_utils.io` (GRIB2, NetCDF and SCHISM grid readers), `nos_utils.config` (`ForcingConfig`), `nos_utils.orchestrator`, `nos_utils.nco_bridge` (NCO environment variables), `nos_utils.cli`.
 
-## UFS-Coastal files
-
-For DATM-coupled (`nws=4`) configurations, prep also renders the per-cycle UFS-Coastal inputs from the templates and fix files staged in `$FIXofs`:
-
-| File | Module | What it holds |
-|---|---|---|
-| `datm_forcing.nc` | `blender` | GFS, or HRRR blended over GFS, on a regular lat/lon grid for CDEPS DATM |
-| `datm_esmf_mesh.nc` | `esmf_mesh` | ESMF unstructured mesh of that grid |
-| `model_configure`, `datm_in`, `datm.streams` | `ufs_config` | From the `*.template` files: start time (cycle minus nowcast length), length of the phase being prepped (nowcast, forecast, or both), `dt_atmos`, DATM grid size and file names |
-| `ufs.configure` | `ufs_config` | From `$FIXofs`, with the PET bounds set from the resource layout (MED, ATM, OCN, and WAV when wave tasks are set) and the `runSeq` coupling interval set to the SCHISM time step or a configured multiple of it |
-| `fd_ufs.yaml`, `noahmptable.tbl` | `ufs_config` | Copied from `$FIXofs` |
-| `nest.ww3` | `wave_boundary` | WW3 boundary spectra from the GFS-Wave point spectra, through `ww3_bound`, when waves are enabled and `$COMINgfswave` is set |
-
-`model_configure` uses the same start time as `param.nml` and `bctides.in` (cycle minus nowcast length), which keeps the CMEPS clock in step with SCHISM.
-
 ## Disclaimer
 
 This repository is a scientific product and is not official communication of the National Oceanic and Atmospheric Administration, or the United States Department of Commerce. All NOAA GitHub project code is provided on an "as is" basis and the user assumes responsibility for its use. Any claims against the Department of Commerce or Department of Commerce bureaus stemming from the use of this GitHub project will be governed by all applicable Federal law. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by the Department of Commerce. The Department of Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used in any manner to imply endorsement of any commercial product or activity by DOC or the United States Government.

docs/index.rst

@@ -26,6 +26,62 @@ Supported systems
 * **STOFS-2D-Global** -- ADCIRC. GFS meteorological forcing in ADCIRC OWI
   NetCDF form (``NWS=14``).
 
+.. _ufs-coastal:
+
+UFS-Coastal
+~~~~~~~~~~~
+
+For DATM-coupled (``nws=4``) configurations, for example SECOFS and
+STOFS-3D-ATL DATM+SCHISM and SECOFS DATM+SCHISM+WW3, prep also renders the
+per-cycle UFS-Coastal inputs. It fills them in from the templates and fix files
+that must already be staged in ``$FIXofs``.
+:class:`~nos_utils.orchestrator.PrepOrchestrator` runs these as its UFS-only
+steps: DATM blending and the ESMF mesh, then the configuration files.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 22 50
+
+   * - File
+     - Module
+     - What it holds
+   * - ``datm_forcing.nc``
+     - :mod:`~nos_utils.forcing.blender`
+     - GFS, or HRRR blended over GFS, on a regular lat/lon grid for CDEPS DATM.
+       ``nx_global``/``ny_global`` in ``datm_in`` are taken from its dimensions.
+   * - ``datm_esmf_mesh.nc``
+     - :mod:`~nos_utils.forcing.esmf_mesh`
+     - ESMF unstructured mesh of the DATM grid (all elements active).
+   * - ``model_configure``, ``datm_in``, ``datm.streams``
+     - :mod:`~nos_utils.forcing.ufs_config`
+     - Filled from the ``*.template`` files in ``$FIXofs``: start time (cycle
+       minus nowcast length), length of the phase being prepped (nowcast,
+       forecast, or both),
+       ``dt_atmos`` (``ufs_coastal.dt_atmos``), DATM grid size and file names.
+   * - ``ufs.configure``
+     - :mod:`~nos_utils.forcing.ufs_config`
+     - Copied from ``$FIXofs`` with the PET bounds set from the resource
+       layout (MED, ATM, OCN, and WAV when wave tasks are configured) and the
+       ``runSeq`` coupling interval set to the SCHISM time step, or to
+       ``ufs_coastal.coupling_interval`` when that is an integer multiple of
+       it. The WW3 component stanza comes from the system's own
+       ``ufs.configure`` fix file.
+   * - ``fd_ufs.yaml``, ``noahmptable.tbl``
+     - :mod:`~nos_utils.forcing.ufs_config`
+     - Copied from ``$FIXofs`` as they are.
+   * - ``nest.ww3``
+     - :mod:`~nos_utils.forcing.wave_boundary`
+     - WW3 boundary spectra built from the GFS-Wave point spectra with
+       ``ww3_bound`` (needs ``mod_def.ww3``). Runs when waves are enabled
+       (``forcing.waves``) and ``$COMINgfswave`` is set.
+
+``model_configure`` uses the same start time as
+:mod:`~nos_utils.forcing.param_nml` and :mod:`~nos_utils.forcing.tidal`
+(cycle minus nowcast length), which keeps the CMEPS clock in step with SCHISM.
+
+The WW3 runtime files (``ww3_shel.nml``, ``mod_def.ww3``, ``ww3_grid.nml``)
+come from ``$FIXofs`` and are not generated by nos-utils.
+
 Key features
 ------------
 
@@ -39,11 +95,6 @@ Key features
   and nudging runs sequentially in Phase 2.
 * **Interior T/S nudging** -- ``TEM_nu.nc`` and ``SAL_nu.nc`` from precomputed
   nudge weights.
-* **UFS-Coastal files** -- for DATM-coupled configurations, prep writes
-  ``datm_forcing.nc`` and the ESMF mesh, renders ``model_configure``,
-  ``datm_in``, ``datm.streams`` and ``ufs.configure`` (PET bounds and coupling
-  interval) from the ``$FIXofs`` templates, and, for WW3, writes the boundary
-  spectra ``nest.ww3``. See :doc:`ufs_coastal`.
 * **ADCIRC support** -- GFS to OWI NetCDF meteorology for STOFS-2D-Global.
 * **Ensemble** -- GEFS-driven perturbation members via
   :meth:`~nos_utils.config.ForcingConfig.for_ensemble`.
@@ -102,7 +153,6 @@ Documentation contents
 
    installation
    usage
-   ufs_coastal
    notebooks
    api/index
    contributing