Skip to content

Hycom documentation purge #3157

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jdkublnick wants to merge 5 commits into
base: develop
Choose a base branch
from
Open

Hycom documentation purge #3157

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cc0c605
purging hycom from the User's Guide
Mar 20, 2026
69a9813
Merge branch 'ufs-community:develop' into text/hycomdocpurge
jdkublnick Mar 20, 2026
7df8b77
Adding back in pertinent info
Mar 20, 2026
1c3daa8
Update doc/UsersGuide/source/InputsOutputs.rst
jdkublnick Mar 20, 2026
16f092b
Update doc/UsersGuide/source/InputsOutputs.rst
jdkublnick Mar 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions doc/UsersGuide/source/BuildingAndRunning.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -378,7 +378,6 @@ Lastly, the :wm-repo:`test configuration file <blob/develop/tests/tests/hafs_reg
export OCEAN_START_DTG=43340.00000

export atm_model=fv3
export ocn_model=hycom
export wav_model=ww3
OCN_tasks=60
WAV_tasks=60
Expand All @@ -390,7 +389,7 @@ Lastly, the :wm-repo:`test configuration file <blob/develop/tests/tests/hafs_reg
export INPUT_NML=input_regional_hafs.nml.IN
export MODEL_CONFIGURE=model_configure_hafs.IN
export UFS_CONFIGURE=ufs.configure.hafs_atm_ocn_wav.IN
export FV3_RUN="hafs_fv3_run.IN hycom_hat10_run.IN hafs_ww3_run.IN"
export FV3_RUN="hafs_fv3_run.IN hafs_ww3_run.IN"

if [[ $MACHINE_ID = orion ]]; then
WLCLK=40
Expand Down
6 changes: 0 additions & 6 deletions doc/UsersGuide/source/CodeOverview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,9 +79,6 @@ The UFS :term:`WM` repository supports the :term:`UFS` short-range weather appli
* - MOM6
- Modular Ocean Model (:term:`MOM6`)
- https://github.com/NOAA-EMC/MOM6
* - HYCOM-src
- HYbrid Coordinate Ocean Model (:term:`HYCOM`)
- https://github.com/NOAA-EMC/HYCOM-src
* - CICE
- Los Alamos sea ice model (:term:`CICE6`)
- https://github.com/NOAA-EMC/CICE
Expand Down Expand Up @@ -149,9 +146,6 @@ The umbrella repository for the UFS WM is named ``ufs-weather-model``. Under thi
├── fire_behavior -------- Community Fire Behavior Model
├── GOCART
│ └── (ESMF) -------- GOCART model
├── HYCOM-interface
│ └── HYCOM -------- HYCOM ocean model
│ └── (NUOPC) -------- NUOPC HYCOM cap
├── LICENSE.md
├── LM4-driver
│ ├── (LM4) -------- NUOPC NOAA-GFDL Land Model version 4
Expand Down
5 changes: 1 addition & 4 deletions doc/UsersGuide/source/Glossary.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ Glossary
DICE is the *Data Sea-Ice* component of :term:`CDEPS`. It uses static sea-ice forcing data (e.g., derived from observations) instead of output from an active sea-ice model (e.g., :term:`CICE6`). This reduces the complexity and computational cost associated with coupling to an active sea-ice model. The *Data Sea-Ice* component is particularly useful when employing computationally intensive Data Assimilation (DA) techniques to update atmospheric fields in a coupled model. In general, use of DICE in place of :term:`CICE6` can be appropriate when users are running a coupled model and only want certain components of the model to be active. More information about DICE is available in the `CDEPS DICE Documentation <https://escomp.github.io/CDEPS/versions/master/html/dice.html>`_.

DOCN
DOCN is the *Data Ocean* component of :term:`CDEPS`. It uses static ocean forcing files (derived from observations or previous ocean model runs) instead of output from an active ocean model. This reduces the complexity and computational cost associated with coupling to an active ocean model. The *Data Ocean* component is particularly useful when employing computationally intensive Data Assimilation (DA) techniques to update atmospheric fields in a coupled model. In general, use of DOCN in place of :term:`MOM6` or :term:`HYCOM` can be appropriate when users are running a coupled model and only want certain components of the model to be active. More information about DOCN is available in the `CDEPS DOCN Documentation <https://escomp.github.io/CDEPS/versions/master/html/docn.html>`_.
DOCN is the *Data Ocean* component of :term:`CDEPS`. It uses static ocean forcing files (derived from observations or previous ocean model runs) instead of output from an active ocean model. This reduces the complexity and computational cost associated with coupling to an active ocean model. The *Data Ocean* component is particularly useful when employing computationally intensive Data Assimilation (DA) techniques to update atmospheric fields in a coupled model. In general, use of DOCN in place of :term:`MOM6` can be appropriate when users are running a coupled model and only want certain components of the model to be active. More information about DOCN is available in the `CDEPS DOCN Documentation <https://escomp.github.io/CDEPS/versions/master/html/docn.html>`_.

dycore
dynamical core
Expand Down Expand Up @@ -111,9 +111,6 @@ Glossary
HPSS
High Performance Storage System (HPSS).

HYCOM
The HYbrid Coordinate Ocean Model (`HYCOM <https://www.hycom.org/>`_) was developed to address known shortcomings in the vertical coordinate scheme of the Miami Isopycnic-Coordinate Ocean Model (MICOM). HYCOM is a primitive equation, general circulation model with vertical coordinates that remain isopycnic in the open, stratified ocean. However, the isopycnal vertical coordinates smoothly transition to z-coordinates in the weakly stratified upper-ocean mixed layer, to terrain-following sigma coordinates in shallow water regions, and back to z-level coordinates in very shallow water. The latter transition prevents layers from becoming too thin where the water is very shallow. See the `HYCOM User's Guide <https://www.hycom.org/attachments/063_hycom_users_guide.pdf>`_ for more information on using the model. The `HYCOM model code <https://github.com/NOAA-EMC/HYCOM-src>`_ is publicly available on GitHub.

ICs
Initial conditions

Expand Down
226 changes: 3 additions & 223 deletions doc/UsersGuide/source/InputsOutputs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,13 +54,11 @@ mediator). Currently, supported configurations include:
* - LND-LM4
- Coupled :term:`CDEPS` - :term:`DATM` - :term:`LM4`
* - HAFS
- Coupled :term:`ATM` - :term:`HYCOM` - :term:`CMEPS`
* - HAFSW
- Coupled :term:`ATM` - :term:`HYCOM` - :term:`WW3` - :term:`CMEPS`
* - HAFS-MOM6W
- Coupled :term:`ATM` - :term:`MOM6`- :term:`WW3` - :term:`CMEPS`
* - HAFS-ALL
- Coupled :term:`CDEPS` - :term:`ATM` - :term:`HYCOM` - :term:`WW3` - :term:`CMEPS`
- Coupled :term:`CDEPS` - :term:`ATM` - :term:`WW3` - :term:`CMEPS`
Copy link
Collaborator

@gspetro-NOAA gspetro-NOAA Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Coupled :term:`CDEPS` - :term:`ATM` - :term:`WW3` - :term:`CMEPS`
- Coupled :term:`CDEPS` - :term:`ATM` - :term:`MOM6` - :term:`WW3` - :term:`CMEPS`

Doesn't make sense to have a hurricane test with no ocean model ;) MOM6 replaces HYCOM in tests that aren't deleted.

Copy link
Collaborator

@DeniseWorthen DeniseWorthen Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are tests with "hafs" in the name which do not include OCN. There are several ATM only as well as an ATM-WAV.

Copy link
Collaborator

@gspetro-NOAA gspetro-NOAA Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we list ATM and ATMW as separate configurations in this table near the top, and HAFS, HAFSW, HAFS-MOM6W, and HAFS-ALL are each listed, but @jdkublnick we are missing HAFS-MOM6. And I would think HAFS-ALL would switch from HYCOM to MOM6, right? That's the edit I was trying to make here. But I'm also wondering if this entire table may have outlived its usefulness... I mean, in theory, people could build experiments for any combination of WM components if they wanted, and the existing list in CMakeLists.txt just keeps expanding. It might make more sense to nix the list and send them to the relevant file for the list of APPs. And/or to rt.conf to see what particular tests are compiled with which -DAPP flag. If we keep the list, I think the key for @jdkublnick is going to be to check the tests for each relevant compile in rt.conf rather than just taking out HYCOM and assuming it'll still be valid and non-redundant (unless you can think of a better way?).

Copy link
Collaborator

@gspetro-NOAA gspetro-NOAA Mar 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jdkublnick It looks like the details on each APP and what components are available with each are listed in cmake/configure_apps.cmake. Maybe Denise has a different suggestion, but that looks to me like the clearest place to get the full list of APPs and corresponding components. It might be best just to go over this whole table and makes sure everything's covered and accurate/up-to-date.


.. COMMENT: Should HAFS-ALL be DATM instead of ATM?
.. COMMENT: No RTs for these apps: ATMWM, S2SL, S2SWL, HAFS-MOM6
Expand Down Expand Up @@ -346,15 +344,15 @@ The input files containing grid information and the initial conditions for globa
- land mask
- 1.00, 0.50
-
* - basin_codes.nc
* - basin_codes.nc
- ocean basin classification grid
- 0.50
-
* - hycom1_25.nc
- vertical coordinate thickness defining 25 vertical levels
- 9.00, 5.00
-
* - hycom1_75_800m.nc
* - hycom1_75_800m.nc
Comment on lines 353 to +357
Copy link
Collaborator

@gspetro-NOAA gspetro-NOAA Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@DeniseWorthen Are these two files used by MOM6 despite their name? They're listed in the MOM6 section of the docs.

Copy link
Collaborator

@DeniseWorthen DeniseWorthen Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, despite the name, they are used by MOM6 to set the vertical grid.

Copy link
Collaborator

@gspetro-NOAA gspetro-NOAA Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It could be good to look at changing that... Not a pressing issue, but maybe next time there's a new input data directory for other reasons, it could be considered? 🤔 Not sure to what extent changing the naming would have an outsized impact on other code/tests tho, so if we need to keep it as-is, that's fine.

- vertical coordinate level thickness
- 1.00, 0.50, 0.25
-
Expand Down Expand Up @@ -427,166 +425,6 @@ The input files containing grid information and the initial conditions for globa
- 1.00
- ✔

.. _hycom-in:

-------
HYCOM
-------

.. _hycom-fix-files:

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Static Datasets (i.e., *fix files*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Static input files have been created for several regional domains. These domains are listed and described in :numref:`Table %s <HYCOM_DomainIdentifiers>`.

.. _HYCOM_DomainIdentifiers:

.. list-table:: *The following table describes each domain identifier.*
:widths: 10 20
:header-rows: 1

* - Identifier
- Description
* - hat10
- Hurricane North Atlantic (1/12 degree)
* - hep20
- Hurricane Eastern North Pacific (1/12 degree)
* - hwp30
- Hurricane Western North Pacific (1/12 degree)
* - hcp70
- Hurricane Central North Pacific (1/12 degree)

Static input files are listed and described in :numref:`Table %s <HYCOM_FixFiles>`. Several datasets contain both dot-a (.a) and dot-b (.b) files. Dot-a files contain data written as 32-bit IEEE real values (idm*jdm) and dot-b files contain plain text metadata for each field in the dot-a file.

.. COMMENT: What is (idm*jdm)?

.. _HYCOM_FixFiles:

.. list-table:: *Fix files containing climatological information*
:widths: 15 30 15
:header-rows: 1

* - Filename
- Description
- Domain
* - :ref:`blkdat.input<HYCOM_BlkdatInput>`
- Model input parameters
-
* - patch.input
- Tile description
-
* - ports.input
- Open boundary cells
-
* - forcing.chl.(a,b)
- Chlorophyll (monthly climatology)
- hat10, hep20, hwp30, hcp70
* - forcing.rivers.(a,b)
- River discharge (monthly climatology)
- hat10, hep20, hwp30, hcp70
* - iso.sigma.(a,b)
- Fixed sigma thickness
- hat10, hep20, hwp30, hcp70
* - regional.depth.(a,b)
- Total depth of ocean
- hat10, hep20, hwp30, hcp70
* - regional.grid.(a,b)
- Grid information for HYCOM "C" grid
- hat10, hep20, hwp30, hcp70
* - relax.rmu.(a,b)
- Open boundary nudging value
- hat10, hep20, hwp30, hcp70
* - relax.ssh.(a,b)
- Surface height nudging value (monthly climatology)
- hat10, hep20, hwp30, hcp70
* - tbaric.(a,b)
- Thermobaricity correction
- hat10, hep20, hwp30, hcp70
* - thkdf4.(a,b)
- Diffusion velocity (m/s) for Laplacian thickness diffusivity
- hat10, hep20, hwp30, hcp70
* - veldf2.(a,b)
- Diffusion velocity (m/s) for biharmonic momentum dissipation
- hat10, hep20, hwp30, hcp70
* - veldf4.(a,b)
- Diffusion velocity (m/s) for Laplacian momentum dissipation
- hat10, hep20, hwp30, hcp70

.. _hycom-grid-ic-files:

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Grid Description and Initial Condition Files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The input files containing time dependent configuration and forcing data are listed and described in :numref:`Table %s <HYCOM_GridICFiles>`. These files are generated for specific regional domains (see :numref:`Table %s <HYCOM_DomainIdentifiers>`) during ocean prep. When uncoupled, the the forcing data drives the ocean model. When coupled, the forcing data is used to fill in unmapped grid cells. Several datasets contain both dot-a (.a) and dot-b (.b) files. Dot-a files contain data written as 32-bit IEEE real values (idm*jdm) and dot-b files contain plain text metadata for each field in the dot-a file.

.. COMMENT: What is (idm*jdm)?

.. _HYCOM_GridICFiles:

.. list-table:: *Input files containing grid information, initial conditions, and forcing data for regional configurations.*
:widths: 12 30 18 5
:header-rows: 1

* - Filename
- Description
- Domain
- Date-dependent
* - limits
- Model begin and end time (since HYCOM epoch)
-
- ✔
* - forcing.airtmp.(a,b)
- GFS forcing data for 2m air temperature
- hat10, hep20, hwp30, hcp70
- ✔
* - forcing.mslprs.(a,b)
- GFS forcing data for mean sea level pressure (symlink)
- hat10, hep20, hwp30, hcp70
- ✔
* - forcing.precip.(a,b)
- GFS forcing data for precipitation rate
- hat10, hep20, hwp30, hcp70
- ✔
* - forcing.presur.(a,b)
- GFS forcing data for mean sea level pressure
- hat10, hep20, hwp30, hcp70
- ✔
* - forcing.radflx.(a,b)
- GFS forcing data for total radiation flux
- hat10, hep20, hwp30, hcp70
- ✔
* - forcing.shwflx.(a,b)
- GFS forcing data for net downward shortwave radiation flux
- hat10, hep20, hwp30, hcp70
- ✔
* - forcing.surtmp.(a,b)
- GFS forcing data for surface temperature
- hat10, hep20, hwp30, hcp70
- ✔
* - forcing.tauewd.(a,b)
- GFS forcing data for eastward momentum flux
- hat10, hep20, hwp30, hcp70
- ✔
* - forcing.taunwd.(a,b)
- GFS forcing data for northward momentum flux
- hat10, hep20, hwp30, hcp70
- ✔
* - forcing.vapmix.(a,b)
- GFS forcing data for 2m vapor mixing ratio
- hat10, hep20, hwp30, hcp70
- ✔
* - forcing.wndspd.(a,b)
- GFS forcing data for 10m wind speed
- hat10, hep20, hwp30, hcp70
- ✔
* - restart_in.(a,b)
- Restart file for ocean state variables
- hat10, hep20, hwp30, hcp70
- ✔

.. _cice-in:

-------
Expand Down Expand Up @@ -955,9 +793,6 @@ The input files containing grid information and the time-varying forcing files f
* - GHRSST_mesh.nc
- ESMF mesh file for GHRSST data source
-
* - hycom_YYYYMM_surf_nolev.nc
- MOM6 forcing file for year YYYY and month MM
- ✔
Comment on lines -958 to -960
Copy link
Collaborator

@gspetro-NOAA gspetro-NOAA Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@DeniseWorthen @NickSzapiro-NOAA Is this file still used by CICE? The description indicates that despite the name, it's a MOM6 forcing file.

Copy link
Collaborator

@NickSzapiro-NOAA NickSzapiro-NOAA Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry ... where do you see this is related to CICE? Usage in RTs seems more CDEPS docn ocn_data

Copy link
Collaborator

@gspetro-NOAA gspetro-NOAA Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, you're right! I scrolled up too far. It was a CDEPS thing; wondering if it still is.

Copy link
Collaborator

@NickSzapiro-NOAA NickSzapiro-NOAA Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I imagine these are SSTs from a Hycom run and are now "data" input coupled to ATM in RT

* - ghrsst_YYYYMMDD.nc
- GHRSST forcing file for year YYYY, month MM and day DD
- ✔
Expand Down Expand Up @@ -1277,7 +1112,6 @@ The configuration files used by the UFS Weather Model are listed here and descri
* ``suite_[suite_name].xml`` (used only at build time)
* ``datm.streams`` (used by CDEPS)
* ``datm_in`` (used by CDEPS)
* ``blkdat.input`` (used by HYCOM)

While the ``input.nml`` file is also a configuration file used by the UFS Weather Model, it is described in
:numref:`Section %s <InputNML>`. The run-time configuration of model output fields is controlled by the combination of ``diag_table`` and ``model_configure``, and is described in detail in :numref:`Section %s <OutputFiles>`.
Expand Down Expand Up @@ -1966,14 +1800,6 @@ A sample of the data stream namelist file is shown below:
restfilm = "null"
/

.. _HYCOM_BlkdatInput:

---------------------------------------
``blkdat.input``
---------------------------------------

The HYCOM model reads parameters from a custom formatted configuraiton file, blkdat.input. The `HYCOM User's Guide <https://www.hycom.org/hycom/documentation>`_ provides an in depth description of the configuration settings.

.. _InputNML:

-----------------------------
Expand Down Expand Up @@ -2376,52 +2202,6 @@ A brief example of the diag_table is shown below. ``"..."`` denotes where lines
"ocean_model", "tauy", "tauy", "ocn%4yr%2mo%2dy%2hr","all",.true.,"none",2
...

.. _hycom-out:

-------
HYCOM
-------

HYCOM output configuration is set in the :ref:`blkdat.input<HYCOM_BlkdatInput>` file. A few common configuration options are described in :numref:`Table %s <HYCOM_OutputConfig>`

.. _HYCOM_OutputConfig:

.. list-table:: *The following table describes HYCOM output configuration.*
:widths: 10 25
:header-rows: 1

* - Parameter
- Description
* - dsurfq
- Number of days between model diagnostics at the surface
* - diagfq
- Number of days between model diagnostics
* - meanfq
- Number of days between model time averaged diagnostics
* - rstrfq
- Number of days between model restart output
* - itest
- i grid point where detailed diagnostics are desired
* - jtest
- j grid point where detailed diagnostics are desired

HYCOM outpus multiple datasets. These datasets contain both dot-a (.a), dot-b (.b), and dot-txt (.txt) files. Dot-a files contain data written as 32-bit IEEE real values (idm*jdm). Dot-b files contain plain text metadata for each field in the dot-a file. Dot-txt files contain plain text data for a single cell for profiling purposes. Post-processing utilties are available in the `HYCOM-tools <https://github.com/HYCOM/HYCOM-tools>`_ repository.

.. _HYCOM_OutputFiles:

.. list-table:: *The following table describes HYCOM output files.*
:widths: 10 10
:header-rows: 1

* - Filename
- Description
* - archs.YYYY_DDD_HH.(a,b,txt)
- HYCOM surface archive data
* - archv.YYYY_DDD_HH.(a,b,txt)
- HYCOM archive data
* - restart_out.(a,b)
- HYCOM restart files

.. _cice-out:

-------
Expand Down
Loading