Port WOA23 extrapolation from Compass

docs/developers_guide/e3sm/init/api.md

@@ -26,7 +26,10 @@
    CombineStep.setup
    CombineStep.constrain_resources
    CombineStep.run
-   CombineTask
+   get_cubed_sphere_topo_steps
+   get_lat_lon_topo_steps
+   CubedSphereCombineTask
+   LatLonCombineTask
    VizCombinedStep
    VizCombinedStep.setup
    VizCombinedStep.run

docs/developers_guide/e3sm/init/tasks/topo/combine.md

@@ -18,32 +18,37 @@ and Antarctic topography datasets into a single dataset suitable for use in
 E3SM simulations. The step supports blending datasets across specified latitude
 ranges and remapping them to a target grid.
 
-The {py:class}`polaris.tasks.e3sm.init.topo.combine.CombineTask` wraps the
-`CombineStep` into a task that can be used to generate and cache combined
-topography datasets for reuse in other contexts.
+The
+{py:class}`polaris.tasks.e3sm.init.topo.combine.CubedSphereCombineTask`
+and
+{py:class}`polaris.tasks.e3sm.init.topo.combine.LatLonCombineTask`
+wrap the `CombineStep` into tasks that can be used to generate and cache
+combined topography datasets for reuse in other contexts.
 
 The {py:class}`polaris.tasks.e3sm.init.topo.combine.VizCombinedStep` step is
 an optional visualization step that can be added to the workflow to create
 plots of the combined topography dataset. This step is particularly useful for
 debugging or analyzing the combined dataset.
 
-## High-Resolution and Low-Resolution Versions
+## Target Grids and Resolutions
 
-There are two versions of the combine steps and task:
+The combine framework is now organized explicitly around the target grid and
+resolution rather than around a special “low-resolution” mode. Current tasks
+include:
 
-1. **Standard (High-Resolution) Version**: This version maps to a
-   high-resolution (ne3000, ~1 km) cubed-sphere grid by default, producing
-   topogrpahy that is suitable for remapping to standard and high-resolution
-   MPAS meshes (~60 km and finer).
+1. Cubed-sphere topography on `ne3000`
+2. Cubed-sphere topography on `ne120`
+3. Latitude-longitude topography on `0.2500_degree`
 
-2. **Low-Resolution Version**: This version uses a coarser ne120 (~25 km) grid
-   for faster remapping to coarse-resolution MPAS meshes (e.g., Icos240). It is
-   designed to reduce computational cost while still providing adequate accuracy
-   for low-resolution simulations used for regression testing rather than
-   science.
+These appear in task paths such as:
 
-The low-resolution version can be selected by setting the `low_res` parameter
-to `True` when creating the `CombineStep` or `CombineTask`.
+- `e3sm/init/topo/combine_bedmap3_gebco2023/cubed_sphere/ne3000/task`
+- `e3sm/init/topo/combine_bedmap3_gebco2023/cubed_sphere/ne120/task`
+- `e3sm/init/topo/combine_bedmap3_gebco2023/lat_lon/0.2500_degree/task`
+
+This structure makes it easier for downstream consumers such as ocean
+hydrography preprocessing to reuse combined topography products without
+embedding product-specific names into `e3sm/init`.
 
 ## Key Features
 
@@ -73,9 +78,6 @@ the configuration file. Key options include:
 - `lat_tiles` and `lon_tiles`: Number of tiles to split the global dataset for parallel remapping.
 - `renorm_thresh`: Threshold for renormalizing Antarctic variables during blending.
 
-For the low-resolution version, additional configuration options are provided
-in the `combine_low_res.cfg` file.
-
 ## Workflow
 
 1. **Setup**: The step downloads required datasets and sets up input/output
@@ -98,21 +100,30 @@ task:
 from polaris.tasks.e3sm.init.topo.combine import CombineStep
 
 component = task.component
-subdir = CombineStep.get_subdir(low_res=False)
+subdir = CombineStep.get_subdir()
 if subdir in component.steps:
     step = component.steps[subdir]
 else:
-    step = CombineStep(component=component, low_res=False)
+    step = CombineStep(component=component, subdir=subdir)
     component.add_step(step)
 task.add_step(step)
 ```
 
-To create a `CombineTask` for caching combined datasets:
+To create a cubed-sphere combine task for caching combined datasets:
+
+```python
+from polaris.tasks.e3sm.init.topo.combine import CubedSphereCombineTask
+
+combine_task = CubedSphereCombineTask(component=my_component, resolution=3000)
+my_component.add_task(combine_task)
+```
+
+To create a latitude-longitude combine task:
 
 ```python
-from polaris.tasks.e3sm.init.topo.combine import CombineTask
+from polaris.tasks.e3sm.init.topo.combine import LatLonCombineTask
 
-combine_task = CombineTask(component=my_component, low_res=False)
+combine_task = LatLonCombineTask(component=my_component, resolution=0.25)
 my_component.add_task(combine_task)
 ```
 
@@ -133,7 +144,8 @@ The `VizCombinedStep` is typically added only when visualization is explicitly r
 
 For more details, refer to the source code of the
 {py:class}`polaris.tasks.e3sm.init.topo.combine.CombineStep` and
-{py:class}`polaris.tasks.e3sm.init.topo.combine.CombineTask` classes.
+{py:class}`polaris.tasks.e3sm.init.topo.combine.CubedSphereCombineTask` and
+{py:class}`polaris.tasks.e3sm.init.topo.combine.LatLonCombineTask` classes.
 
 ```{note}
 Since this step is expensive and time-consuming to run, most tasks will

docs/developers_guide/ocean/api.md

@@ -198,6 +198,38 @@
    viz.Viz.run
 ```
 
+### global_ocean
+
+```{eval-rst}
+.. currentmodule:: polaris.tasks.ocean.global_ocean
+
+.. autosummary::
+   :toctree: generated/
+
+   add_global_ocean_tasks
+```
+
+### global_ocean.hydrography.woa23
+
+```{eval-rst}
+.. currentmodule:: polaris.tasks.ocean.global_ocean.hydrography.woa23
+
+.. autosummary::
+   :toctree: generated/
+
+   Woa23
+   get_woa23_topography_step
+   get_woa23_steps
+
+   CombineStep
+   CombineStep.setup
+   CombineStep.run
+
+   ExtrapolateStep
+   ExtrapolateStep.setup
+   ExtrapolateStep.run
+```
+
 ### ice_shelf_2d
 
 ```{eval-rst}
@@ -617,4 +649,3 @@
    vertical.ztilde.pressure_and_spec_vol_from_state_at_geom_height
    vertical.ztilde.geom_height_from_pseudo_height
 ```
-

docs/developers_guide/ocean/tasks/global_ocean.md

@@ -0,0 +1,70 @@
+(dev-ocean-global-ocean)=
+
+# global_ocean
+
+The `global_ocean` tasks in `polaris.tasks.ocean.global_ocean` are intended
+for preprocessing and initialization workflows that are upstream of any
+particular MPAS mesh. The first task category under this framework is
+`hydrography/woa23`, which builds a reusable hydrography product from the
+World Ocean Atlas 2023 on its native 0.25-degree latitude-longitude grid.
+
+(dev-ocean-global-ocean-framework)=
+
+## framework
+
+The shared config options for the WOA23 hydrography task are described in
+{ref}`ocean-global-ocean` in the User's Guide.
+
+The implementation is intentionally organized around reusable Polaris steps
+rather than around the legacy Compass `utility/extrap_woa` multiprocessing
+workflow. One notable design choice is that the task reuses the combined
+topography product from `e3sm/init` rather than taking a raw topography
+filename as a task-specific input.
+
+### cached topography dependency
+
+The helper
+{py:func}`polaris.tasks.ocean.global_ocean.hydrography.woa23.get_woa23_topography_step`
+creates a shared `e3sm/init` {py:class}`polaris.tasks.e3sm.init.topo.combine.step.CombineStep`
+configured for a 0.25-degree lat-lon target grid. The
+{py:class}`polaris.tasks.ocean.global_ocean.hydrography.woa23.task.Woa23`
+task adds this step with a symlink `combine_topo` and prefers to use a cached
+version of its outputs when matching entries are available in the
+`e3sm/init` cache database.
+
+This keeps the expensive topography blending logic in one place and makes the
+ocean hydrography preprocessing task consistent with the broader Polaris
+approach to shared, cacheable preprocessing steps.
+
+(dev-ocean-global-ocean-woa23)=
+
+## hydrography/woa23
+
+The {py:class}`polaris.tasks.ocean.global_ocean.hydrography.woa23.task.Woa23`
+task is the Polaris port of the WOA preprocessing part of the legacy Compass
+workflow.
+
+### combine
+
+The class
+{py:class}`polaris.tasks.ocean.global_ocean.hydrography.woa23.combine.CombineStep`
+combines January and annual WOA23 temperature and salinity climatologies into
+a single dataset. January values are used where they exist, and annual values
+fill deeper levels where the monthly product is not available.
+
+WOA23 supplies in-situ temperature and practical salinity, so this step uses
+`gsw` to derive conservative temperature and absolute salinity for the
+canonical `woa_combined.nc` product.
+
+### extrapolate
+
+The class
+{py:class}`polaris.tasks.ocean.global_ocean.hydrography.woa23.extrapolate.ExtrapolateStep`
+uses the cached combined-topography product on the WOA grid together with
+`woa_combined.nc` to build a 3D ocean mask and then fill missing WOA values in
+two stages:
+
+1. Horizontal then vertical extrapolation within the ocean mask
+2. Horizontal then vertical extrapolation into land and grounded-ice regions
+
+The final output is `woa23_decav_0.25_jan_extrap.nc`.

docs/developers_guide/ocean/tasks/index.md

@@ -13,6 +13,7 @@ cosine_bell
 customizable_viz
 external_gravity_wave
 geostrophic
+global_ocean
 divergent_2d
 ice_shelf_2d
 inertial_gravity_wave

docs/users_guide/ocean/tasks/global_ocean.md

@@ -0,0 +1,84 @@
+(ocean-global-ocean)=
+
+# global_ocean
+
+This category contains ocean preprocessing tasks that are upstream of any
+particular MPAS mesh. The first task builds a reusable World Ocean Atlas 2023
+(WOA23) hydrography product on the native 0.25-degree latitude-longitude grid.
+
+## supported models
+
+This task is model-independent and does not require either MPAS-Ocean or
+Omega to be built.
+
+(ocean-global-ocean-woa23)=
+
+## woa23
+
+This task is the Polaris port of the legacy Compass
+`utility/extrap_woa` workflow. It combines January and annual WOA23
+climatologies, uses a cached `e3sm/init` combined-topography product on the
+WOA grid to define the ocean mask used during preprocessing, and then fills
+missing temperature and salinity values through staged horizontal and vertical
+extrapolation.
+
+The task can be set up with:
+
+```bash
+polaris setup -t ocean/global_ocean/hydrography/woa23 ...
+```
+
+### description
+
+The task is organized into three inspectable steps:
+
+1. `combine_topo` reuses a cached `e3sm/init` combined-topography step
+   configured for the WOA23 0.25-degree latitude-longitude grid.
+2. `combine` creates `woa_combined.nc` by combining January and annual WOA23
+   in-situ temperature and practical-salinity fields, then deriving
+   conservative temperature and absolute salinity.
+3. `extrapolate` creates the final
+   `woa23_decav_0.25_jan_extrap.nc` product.
+
+This layout is intended to match Polaris shared-step conventions so the WOA23
+preprocessing pipeline can later be reused by mesh-dependent
+`global_ocean` initialization tasks.
+
+### mesh
+
+N/A. This task operates on the native WOA23 latitude-longitude grid rather
+than an MPAS mesh.
+
+### vertical grid
+
+N/A. The task preserves the standard WOA23 depth levels.
+
+### initial conditions
+
+The source fields come from the WOA23 January and annual climatologies in the
+Polaris input database.
+
+### forcing
+
+N/A.
+
+### time step and run duration
+
+N/A.
+
+### config options
+
+```cfg
+# Options related to generating a reusable WOA23 hydrography product
+[woa23]
+
+# the minimum weight sum needed to mark a new cell valid in horizontal
+# extrapolation
+extrap_threshold = 0.01
+```
+
+### cores
+
+The local `combine` and `extrapolate` steps run serially. The
+`combine_topo` step is intended to use the cached `e3sm/init` output because
+regenerating the combined topography product is substantially more expensive.

docs/users_guide/ocean/tasks/index.md

@@ -13,6 +13,7 @@ cosine_bell
 customizable_viz
 external_gravity_wave
 geostrophic
+global_ocean
 divergent_2d
 ice_shelf_2d
 inertial_gravity_wave