Skip to content

Commit e0c7c53

Browse files
xylarxylar
authored
Merge pull request #296 from xylar/add-framework-pr-suite
Add a new suite for testing the framework
2 parents 74c567a + 304b62a commit e0c7c53

File tree

5 files changed

+180
-42
lines changed

5 files changed

+180
-42
lines changed

‎docs/developers_guide/ocean/tasks/ice_shelf_2d.md‎

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ its {py:class}`polaris.ocean.ice_shelf.ssh_forward.SshForward` and
2626
are used to set up one of each step for each iteration given by the config
2727
option `ssh_adjustment:iterations`.
2828

29+
(dev-ocean-ice-shelf-2d-init)=
30+
2931
### init
3032

3133
The class :py:class:`polaris.ocean.tasks.ice_shelf_2d.init.Init`
@@ -41,24 +43,30 @@ or top layers are removed where there is an ice shelf using a z-level
4143
coordinate. Finally, the initial salinity profile is computed along with
4244
uniform temperature and zero initial velocity.
4345

46+
(dev-ocean-ice-shelf-2d-forward)=
47+
4448
### forward
4549

4650
The class {py:class}`polaris.ocean.tests.ice_shelf_2d.forward.Forward`
4751
defines a step for running MPAS-Ocean from the initial condition produced in
4852
the `init` step. For MPAS-Ocean, PIO namelist options are modified and a
49-
graph partition is generated as part of `runtime_setup()`. Next, the ocean
50-
model is run.
53+
graph partition is generated as part of `runtime_setup()`. Next, the ocean
54+
model is run.
55+
56+
(dev-ocean-ice-shelf-2d-validate)=
5157

5258
### validate
5359

5460
The class {py:class}`polaris.ocean.tasks.ice_shelf_2d.validate.Validate`
5561
defines a step for validating outputs in two step directories against one
56-
another. This step ensures that `temperature`, `salinity`, `layerThickness`
62+
another. This step ensures that `temperature`, `salinity`, `layerThickness`
5763
and `normalVelocity` are identical in `output.nc` files in the two steps.
5864
It also checks a number of land ice variables and frazil variables stored in
5965
`land_ice_fluxes.nc` and `frazil.nc`, respectively. This step is used by the
6066
restart test (see {ref}`dev-ocean-ice-shelf-2d-restart`).
6167

68+
(dev-ocean-ice-shelf-2d-viz)=
69+
6270
### viz
6371

6472
The class {py:class}`polaris.ocean.tasks.ice_shelf_2d.viz.Viz` uses the planar
@@ -79,9 +87,17 @@ dynamic balance with the land-ice pressure. Then, it performs a 10-minute
7987
(both prognostic and related to land-ice fluxes) are checked to make sure
8088
they match the baseline.
8189

90+
(dev-ocean-ice-shelf-2d-restart)=
91+
92+
## with_restart
93+
8294
The restart test, `ocean/planar/ice_shelf_2d/$RES/$COORD_TYPE/default/with_restart`
8395
is just a variant of the default test that has two additional steps, a `forward`
84-
step and a `validate` step.
96+
step and a `validate` step.
97+
98+
(dev-ocean-ice-shelf-2d-tidal-forcing)=
99+
100+
## default_tidal_forcing
85101

86102
The tidal forcing test, `ocean/planar/ice_shelf_2d/$RES/$COORD_TYPE/default_tidal_forcing`
87103
is a variant of the `default` test that has tidal forcing, is run for longer

‎docs/tutorials/dev_add_test_group.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -489,7 +489,7 @@ By default, the subdirectory for the step is the same as the step name, but
489489
just like for a task, you can give the step a more complicated
490490
subdirectory name, possibly with multiple levels of directories. This is
491491
particularly important for parameter studies, an example of which can be seen
492-
in the {ref}`dev-ocean-global-convergence-cosine-bell` task.
492+
in the {ref}`dev-ocean-cosine-bell` task.
493493

494494
### Creating a horizontal mesh
495495

@@ -1294,12 +1294,12 @@ class Forward(OceanModelStep):
12941294
### Defining model config options and streams
12951295

12961296
The E3SM components supported by polaris require both model config options
1297-
and streams definitions (namelist and streams files for MPAS components,
1298-
see {ref}`dev-step-namelists-and-streams`, and yaml files for Omega, see
1299-
{ref}`dev-step-add-yaml-file`) to work properly. An important part of polaris'
1300-
functionality is that it takes the default model config options and E3SM
1301-
component and modifies only those options that are specific to the task to
1302-
produce the final model config files used to run the model.
1297+
and streams definitions (namelist and streams files for MPAS components, and
1298+
yaml files for Omega, see {ref}`dev-model-yaml-namelists-and-streams`) to work
1299+
properly. An important part of polaris' functionality is that it takes the
1300+
default model config options and E3SM component and modifies only those options
1301+
that are specific to the task to produce the final model config files used to
1302+
run the model.
13031303

13041304
In polaris, there are two main ways to set model config options and we will
13051305
demonstrate both in this task. First, you can define a namelist or yaml
@@ -2254,7 +2254,7 @@ combination is run and then an analysis step computes the rate of convergence
22542254
from the results. We won't cover this example here, in part because a
22552255
resolution study involves both a forward step and an initial condition step for
22562256
each resolution in order to generate unique meshes for each step. You may refer
2257-
to {ref}`dev-ocean-global-convergence-cosine-bell` for these details. Instead,
2257+
to {ref}`dev-ocean-cosine-bell` for these details. Instead,
22582258
we will explore the `rpe` for the `baroclinic_channel` test group, which
22592259
only requires unique forward runs for different viscosity values.
22602260

‎docs/users_guide/ocean/framework/vertical.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,11 @@ min_layer_thickness = 0
4545
```
4646

4747
The vertical coordinate is typically defined based on a 1D reference grid.
48-
Possible 1D grid types are: `uniform`, `tanh_dz`, `index_tanh_dz`,
48+
Possible 1D grid types are: `uniform`, `tanh_dz`, `index_tanh_dz`,
4949
`60layerPHC`, `80layerE3SMv1`, and `100layerE3SMv1`.
5050

5151
The meaning of the config options `vert_levels`, `bottom_depth`,
52-
`min_layer_thickness`, `max_layer_thickness`, and `transition_levels` depends
52+
`min_layer_thickness`, `max_layer_thickness`, and `transition_levels` depends
5353
grid type and is described below.
5454

5555
The options `coord_type`, `partial_cell_type` and `min_pc_fraction`
@@ -253,12 +253,12 @@ with the sea floor at 2500 m.
253253
## 3D vertical coordinates
254254

255255
Currently, `z-star`, `z-level` and `sigma` vertical coordinates are supported
256-
(`coord_type`). The `z-star` and `z-level` types support 3 options for
257-
`partial_cell_type`: `full` meaning the topography (bottom depth and
258-
sea-surface height) are expanded so that all layers have their full thickness;
259-
`partial` meaning that cells adjacent to the topography are allowed to be a
260-
small fraction of a full layer thickness; or `None` to indicate that no
261-
alteration is needed for full or partial cells (typically only in cases where
256+
(`coord_type`). The `z-star` and `z-level` types support 3 options for
257+
`partial_cell_type`: `full` meaning the topography (bottom depth and
258+
sea-surface height) are expanded so that all layers have their full thickness;
259+
`partial` meaning that cells adjacent to the topography are allowed to be a
260+
small fraction of a full layer thickness; or `None` to indicate that no
261+
alteration is needed for full or partial cells (typically only in cases where
262262
the topography is already flat).
263263

264264
If `partial_cell_type = partial`, the option `min_pc_fraction` indicates
@@ -277,7 +277,7 @@ by default. Typically (in the absence of ice-shelf cavities), the initial
277277
height evolves, the coordinate stretches and squashes in proportion to changes
278278
in the local water-column thickness.
279279

280-
In configurations with {ref}`ocean-ice-shelf-cavities`, the ice draft
280+
In configurations with {ref}`ocean-ice-shelf` cavities, the ice draft
281281
(elevation of the ice shelf-ocean interface) also acts the sea-surface height
282282
for a z-star coordinate. This means that the initial layers are squashed
283283
significantly from their "resting" thickness under ice shelves as if they were
@@ -287,7 +287,7 @@ being pressed down by the weight of the ice.
287287

288288
### z-level
289289

290-
In the absence of {ref}`ocean-ice-shelf-cavities`, the z-level coordinate in
290+
In the absence of {ref}`ocean-ice-shelf` cavities, the z-level coordinate in
291291
ocean is the same as the {ref}`ocean-z-star` coordinate.
292292

293293
When ice-shelf cavities are included, rather than depressing the vertical grid

‎docs/users_guide/ocean/suites.md‎

Lines changed: 120 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -4,34 +4,134 @@
44

55
The ocean component includes a number of {ref}`suites` that can be used to
66
run a series of ocean tasks and optionally compare them against a baseline
7-
run of the same tasks.
7+
run of the same tasks. To set them up, run:
88

9-
(ocean-suite-cosine-bell)=
9+
```bash
10+
polaris suite -c ocean -t <suite_name> ...
11+
```
1012

11-
## cosine_bell suite
13+
Below are details on some of the most commonly used suites. The other suites
14+
are mostly focused on specific tests as indicated by their names.
1215

13-
```bash
14-
polaris suite -c ocean -t cosine_bell ...
16+
(ocean-suite-pr)=
17+
18+
## pr suite
19+
20+
The `pr` suite is designed for testing pull-requests (PRs) that involve
21+
changes to the Ocean component or the Polaris framework. It includes some
22+
basic tests that are always expected to work, and which should indicate if
23+
any changes have been inadvertently introduced by the PR. For now, the
24+
suite is designed for use with MPAS-Ocean but not fully supported by Omega.
25+
26+
```none
27+
ocean/planar/baroclinic_channel/10km/threads
28+
ocean/planar/baroclinic_channel/10km/decomp
29+
ocean/planar/baroclinic_channel/10km/restart
30+
ocean/planar/ice_shelf_2d/5km/z-star/default/with_restart
31+
ocean/planar/ice_shelf_2d/5km/z-level/default/with_restart
32+
ocean/planar/inertial_gravity_wave/convergence_both
33+
ocean/planar/internal_wave/standard/default
34+
ocean/planar/internal_wave/vlr/default
35+
# currently not converging in MPAS-Ocean
36+
# ocean/planar/manufactured_solution/convergence_both
37+
ocean/single_column/cvmix
38+
ocean/single_column/ideal_age
39+
ocean/spherical/icos/cosine_bell/decomp
40+
ocean/spherical/icos/cosine_bell/restart
1541
```
1642

17-
The `cosine_bell` suite includes the following tasks:
43+
(ocean-suite-nightly)=
44+
45+
# nightly suite
46+
47+
The `nightly` suite is similar to the `pr` suite but is designed to allow for
48+
slightly heavier testing on a nightly basis. For now, the suite actually
49+
includes fewer tests than `pr` but it is expected to be fleshed out as Omega
50+
development matures:
1851

1952
```none
20-
ocean/spherical/icos/cosine_bell/convergence_space
21-
ocean/spherical/icos/cosine_bell/convergence_space/with_viz
22-
ocean/spherical/icos/cosine_bell/convergence_time
23-
ocean/spherical/icos/cosine_bell/convergence_time/with_viz
24-
ocean/spherical/icos/cosine_bell/convergence_both
25-
ocean/spherical/icos/cosine_bell/convergence_both/with_viz
53+
ocean/planar/baroclinic_channel/10km/threads
54+
ocean/planar/baroclinic_channel/10km/decomp
55+
ocean/planar/baroclinic_channel/10km/restart
56+
ocean/planar/ice_shelf_2d/5km/z-star/default/with_restart
57+
ocean/planar/ice_shelf_2d/5km/z-level/default/with_restart
58+
ocean/planar/inertial_gravity_wave/convergence_both
59+
# ocean/planar/manufactured_solution
2660
ocean/spherical/icos/cosine_bell/decomp
2761
ocean/spherical/icos/cosine_bell/restart
28-
ocean/spherical/qu/cosine_bell/convergence_space
29-
ocean/spherical/qu/cosine_bell/convergence_space/with_viz
30-
ocean/spherical/qu/cosine_bell/convergence_time
31-
ocean/spherical/qu/cosine_bell/convergence_time/with_viz
32-
ocean/spherical/qu/cosine_bell/convergence_both
33-
ocean/spherical/qu/cosine_bell/convergence_both/with_viz
34-
ocean/spherical/qu/cosine_bell/decomp
35-
ocean/spherical/qu/cosine_bell/restart
3662
```
3763

64+
# omega_pr suite
65+
66+
The `omega_pr` suite is designed to test changes in Omega or the affects of
67+
Polaris changes on Omega results.
68+
69+
Here are the tests in the suite:
70+
```none
71+
ocean/planar/manufactured_solution/convergence_both/default
72+
ocean/spherical/icos/rotation_2d
73+
ocean/spherical/icos/cosine_bell/decomp
74+
ocean/spherical/icos/cosine_bell/restart
75+
```
76+
77+
(ocean-suite-framework-pr)=
78+
79+
## framework_pr suite
80+
81+
The `framework_pr` suite is designed for testing pull-requests (PRs) that
82+
involve changes to the Polaris and/or Ocean framework. It includes the tests
83+
in the `pr` suite plus additional tests focued on visualizaiton and remapping.
84+
The tasks in this suite include:
85+
86+
```none
87+
## pr suite
88+
ocean/planar/baroclinic_channel/10km/threads
89+
ocean/planar/baroclinic_channel/10km/decomp
90+
ocean/planar/baroclinic_channel/10km/restart
91+
ocean/planar/ice_shelf_2d/5km/z-star/default/with_restart
92+
ocean/planar/ice_shelf_2d/5km/z-level/default/with_restart
93+
ocean/planar/inertial_gravity_wave/convergence_both
94+
ocean/planar/internal_wave/standard/default
95+
ocean/planar/internal_wave/vlr/default
96+
# ocean/planar/manufactured_solution/convergence_both
97+
ocean/single_column/cvmix
98+
ocean/single_column/ideal_age
99+
ocean/spherical/icos/cosine_bell/decomp
100+
ocean/spherical/icos/cosine_bell/restart
101+
102+
## viz
103+
ocean/planar/baroclinic_channel/10km/default
104+
ocean/planar/ice_shelf_2d/5km/z-star/default/with_viz
105+
ocean/spherical/icos/cosine_bell/convergence_both/with_viz
106+
ocean/spherical/icos/rotation_2d/with_viz
107+
108+
## remapping
109+
ocean/planar/isomip_plus/4km/z-star/ocean0
110+
```
111+
112+
(ocean-suite-convergence)=
113+
114+
## convergence suite
115+
116+
The `convergence` suite is designed for running all convergence tests. To
117+
speed up the process, most tests have cached base meshes. Here are the tests
118+
included:
119+
120+
```none
121+
ocean/planar/inertial_gravity_wave/convergence_both
122+
ocean/planar/manufactured_solution/convergence_both/default
123+
ocean/planar/manufactured_solution/convergence_both/del2
124+
ocean/planar/manufactured_solution/convergence_both/del4
125+
ocean/spherical/icos/correlated_tracers_2d
126+
ocean/spherical/qu/correlated_tracers_2d
127+
ocean/spherical/icos/cosine_bell/convergence_both
128+
ocean/spherical/qu/cosine_bell/convergence_both
129+
ocean/spherical/icos/geostrophic/convergence_both
130+
ocean/spherical/qu/geostrophic/convergence_both
131+
ocean/spherical/icos/divergent_2d
132+
ocean/spherical/qu/divergent_2d
133+
ocean/spherical/icos/nondivergent_2d
134+
ocean/spherical/qu/nondivergent_2d
135+
ocean/spherical/icos/rotation_2d
136+
ocean/spherical/qu/rotation_2d
137+
```

‎polaris/ocean/suites/framework_pr.txt‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
## pr suite
2+
ocean/planar/baroclinic_channel/10km/threads
3+
ocean/planar/baroclinic_channel/10km/decomp
4+
ocean/planar/baroclinic_channel/10km/restart
5+
ocean/planar/ice_shelf_2d/5km/z-star/default/with_restart
6+
ocean/planar/ice_shelf_2d/5km/z-level/default/with_restart
7+
ocean/planar/inertial_gravity_wave/convergence_both
8+
ocean/planar/internal_wave/standard/default
9+
ocean/planar/internal_wave/vlr/default
10+
# ocean/planar/manufactured_solution/convergence_both
11+
ocean/single_column/cvmix
12+
ocean/single_column/ideal_age
13+
ocean/spherical/icos/cosine_bell/decomp
14+
ocean/spherical/icos/cosine_bell/restart
15+
16+
## viz
17+
ocean/planar/baroclinic_channel/10km/default
18+
ocean/planar/ice_shelf_2d/5km/z-star/default/with_viz
19+
ocean/spherical/icos/rotation_2d/with_viz
20+
21+
## remapping
22+
ocean/planar/isomip_plus/4km/z-star/ocean0

0 commit comments

Comments
 (0)