From 26cd7b50f29ffde199f41a7f532b493eeb632d90 Mon Sep 17 00:00:00 2001 From: mansurjisan Date: Mon, 19 Oct 2026 23:56:33 -0400 Subject: [PATCH 1/3] docs: list the UFS-Coastal files nos-utils generates (README and a new docs page) --- README.md | 15 ++++++++++++++ docs/index.rst | 8 +++++--- docs/ufs_coastal.rst | 49 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 69 insertions(+), 3 deletions(-) create mode 100644 docs/ufs_coastal.rst diff --git a/README.md b/README.md index 063f0ce..56b658c 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,21 @@ 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 the DATM-coupled configurations (`nws=4`), prep also writes the UFS-Coastal inputs, so a coupled run needs no hand-made configuration files: + +| File | Module | What it holds | +|---|---|---| +| `datm_forcing.nc` | `blender`, `datm_writer` | 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` | Filled from `$FIXofs` templates: run start (cycle minus nowcast length), run length, DATM grid size and file names | +| `ufs.configure` | `ufs_config` | PET bounds set from the resource layout (ATM, OCN, and WAV for WW3); `runSeq` coupling interval set to the SCHISM time step, or for WW3 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` (DATM+SCHISM+WW3) | + +All components share one start time (cycle minus nowcast length), which keeps the CMEPS clock of DATM, SCHISM and WW3 in step. + ## 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. diff --git a/docs/index.rst b/docs/index.rst index fa297c3..e259da1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,9 +39,10 @@ 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 support** -- ESMF mesh, HRRR/GFS blender, DATM writer, and - generation of the UFS configuration files, including the WW3 boundary - spectra (``nest.ww3``) from GFS-Wave. +* **UFS-Coastal files** -- for the DATM-coupled configurations, prep writes + ``datm_forcing.nc``, the ESMF mesh, ``model_configure``, ``datm_in``, + ``datm.streams``, ``ufs.configure`` (PET bounds and coupling interval) and, + for WW3, 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`. @@ -100,6 +101,7 @@ Documentation contents installation usage + ufs_coastal notebooks api/index contributing diff --git a/docs/ufs_coastal.rst b/docs/ufs_coastal.rst new file mode 100644 index 0000000..cc6dbde --- /dev/null +++ b/docs/ufs_coastal.rst @@ -0,0 +1,49 @@ +UFS-Coastal files +================= + +For the DATM-coupled configurations (``nws=4``: SECOFS DATM+SCHISM and +DATM+SCHISM+WW3, STOFS-3D-ATL DATM+SCHISM), prep also writes the inputs that +UFS-Coastal needs, so a coupled run needs no hand-made configuration files. +: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`, :mod:`~nos_utils.forcing.datm_writer` + - 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``: run start + (cycle minus nowcast length), run length (nowcast plus forecast), + DATM time step, 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 (ATM, OCN, and WAV when wave tasks are configured) and the + ``runSeq`` coupling interval set to the SCHISM time step (for WW3, a + configured 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 for DATM+SCHISM+WW3, built from the GFS-Wave + point spectra with ``ww3_bound`` (needs ``mod_def.ww3``). + +All components share one start time, the cycle minus the nowcast length (the +same anchor :mod:`~nos_utils.forcing.param_nml` and :mod:`~nos_utils.forcing.tidal` +use), which keeps the CMEPS clock of DATM, SCHISM and WW3 in step. + +WW3 runtime files (``ww3_shel.nml``, ``mod_def.ww3``, ``ww3_grid.nml``) are +static fix files and are not generated here. From 0fa0fe7af5b4defb8c2ec9f084fd9408fb2b1ddc Mon Sep 17 00:00:00 2001 From: mansurjisan Date: Tue, 20 Oct 2026 00:01:25 -0400 Subject: [PATCH 2/3] docs: UFS-Coastal files review fixes (templates from FIXofs, phase length, coupling interval, nest.ww3 gating) --- README.md | 12 ++++++------ docs/index.rst | 7 ++++--- docs/ufs_coastal.rst | 39 +++++++++++++++++++++------------------ 3 files changed, 31 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 56b658c..e0a1ba9 100644 --- a/README.md +++ b/README.md @@ -48,18 +48,18 @@ Other packages: `nos_utils.interp` (structured and precomputed-weight interpolat ## UFS-Coastal files -For the DATM-coupled configurations (`nws=4`), prep also writes the UFS-Coastal inputs, so a coupled run needs no hand-made configuration 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`, `datm_writer` | GFS, or HRRR blended over GFS, on a regular lat/lon grid for CDEPS DATM | +| `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` | Filled from `$FIXofs` templates: run start (cycle minus nowcast length), run length, DATM grid size and file names | -| `ufs.configure` | `ufs_config` | PET bounds set from the resource layout (ATM, OCN, and WAV for WW3); `runSeq` coupling interval set to the SCHISM time step, or for WW3 a configured multiple of it | +| `model_configure`, `datm_in`, `datm.streams` | `ufs_config` | From the `*.template` files: start time and length of the phase being prepped, `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` (DATM+SCHISM+WW3) | +| `nest.ww3` | `wave_boundary` | WW3 boundary spectra from the GFS-Wave point spectra, through `ww3_bound`, when waves are enabled and `$COMINgfswave` is set | -All components share one start time (cycle minus nowcast length), which keeps the CMEPS clock of DATM, SCHISM and WW3 in step. +`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 diff --git a/docs/index.rst b/docs/index.rst index e259da1..920ca3a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,10 +39,11 @@ 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 the DATM-coupled configurations, prep writes +* **UFS-Coastal files** -- for DATM-coupled configurations, prep renders ``datm_forcing.nc``, the ESMF mesh, ``model_configure``, ``datm_in``, - ``datm.streams``, ``ufs.configure`` (PET bounds and coupling interval) and, - for WW3, the boundary spectra ``nest.ww3``. See :doc:`ufs_coastal`. + ``datm.streams`` and ``ufs.configure`` (PET bounds and coupling interval) + from the templates in ``$FIXofs`` and, for WW3, 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`. diff --git a/docs/ufs_coastal.rst b/docs/ufs_coastal.rst index cc6dbde..54be52e 100644 --- a/docs/ufs_coastal.rst +++ b/docs/ufs_coastal.rst @@ -1,9 +1,10 @@ UFS-Coastal files ================= -For the DATM-coupled configurations (``nws=4``: SECOFS DATM+SCHISM and -DATM+SCHISM+WW3, STOFS-3D-ATL DATM+SCHISM), prep also writes the inputs that -UFS-Coastal needs, so a coupled run needs no hand-made configuration files. +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. @@ -15,7 +16,7 @@ steps: DATM blending and the ESMF mesh, then the configuration files. - Module - What it holds * - ``datm_forcing.nc`` - - :mod:`~nos_utils.forcing.blender`, :mod:`~nos_utils.forcing.datm_writer` + - :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`` @@ -23,27 +24,29 @@ steps: DATM blending and the ESMF mesh, then the configuration files. - 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``: run start - (cycle minus nowcast length), run length (nowcast plus forecast), - DATM time step, grid size and file names. + - Filled from the ``*.template`` files in ``$FIXofs``: start time and + 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 (ATM, OCN, and WAV when wave tasks are configured) and the - ``runSeq`` coupling interval set to the SCHISM time step (for WW3, a - configured integer multiple of it). The WW3 component stanza comes - from the system's own ``ufs.configure`` fix file. + 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 for DATM+SCHISM+WW3, built from the GFS-Wave - point spectra with ``ww3_bound`` (needs ``mod_def.ww3``). + - 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. -All components share one start time, the cycle minus the nowcast length (the -same anchor :mod:`~nos_utils.forcing.param_nml` and :mod:`~nos_utils.forcing.tidal` -use), which keeps the CMEPS clock of DATM, SCHISM and WW3 in step. +``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. -WW3 runtime files (``ww3_shel.nml``, ``mod_def.ww3``, ``ww3_grid.nml``) are -static fix files and are not generated here. +The WW3 runtime files (``ww3_shel.nml``, ``mod_def.ww3``, ``ww3_grid.nml``) +come from ``$FIXofs`` and are not generated by nos-utils. From 73dde8f3528768bab0837ba037ffb32b6e08c446 Mon Sep 17 00:00:00 2001 From: mansurjisan Date: Tue, 20 Oct 2026 00:02:22 -0400 Subject: [PATCH 3/3] docs: UFS start time is always cycle minus nowcast; index wording --- README.md | 2 +- docs/index.rst | 10 +++++----- docs/ufs_coastal.rst | 5 +++-- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index e0a1ba9..aa00d03 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ For DATM-coupled (`nws=4`) configurations, prep also renders the per-cycle UFS-C |---|---|---| | `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 and length of the phase being prepped, `dt_atmos`, DATM grid size and file names | +| `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 | diff --git a/docs/index.rst b/docs/index.rst index 920ca3a..baeb947 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,11 +39,11 @@ 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 renders - ``datm_forcing.nc``, the ESMF mesh, ``model_configure``, ``datm_in``, - ``datm.streams`` and ``ufs.configure`` (PET bounds and coupling interval) - from the templates in ``$FIXofs`` and, for WW3, the boundary spectra - ``nest.ww3``. See :doc:`ufs_coastal`. +* **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`. diff --git a/docs/ufs_coastal.rst b/docs/ufs_coastal.rst index 54be52e..b22929f 100644 --- a/docs/ufs_coastal.rst +++ b/docs/ufs_coastal.rst @@ -24,8 +24,9 @@ steps: DATM blending and the ESMF mesh, then the configuration files. - 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 and - length of the phase being prepped (nowcast, forecast, or both), + - 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`