Skip to content

Commit

Permalink
Merge pull request #140 from xylar/switch-spherical-viz-to-uxarray
Browse files Browse the repository at this point in the history 
Switch spherical viz to use `uxarray` and `holoviews`
  • Loading branch information
@xylar
xylar authored Oct 27, 2023
2 parents 5789b34 + 0679279 commit ea309c8
Show file tree
Hide file tree
Showing 28 changed files with 546 additions and 712 deletions.
6 changes: 6 additions & 0 deletions deploy/conda-dev-spec.template
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,17 @@

# Base
python>=3.9,<3.12
antimeridian
cartopy
cartopy_offlinedata
cmocean
esmf={{ esmf }}={{ mpi_prefix }}_*
ffmpeg
geometric_features={{ geometric_features }}
geoviews
git
holoviews
hvplot
importlib_resources
ipython
jigsaw={{ jigsaw }}
Expand All @@ -36,6 +40,8 @@ ruamel.yaml
requests
scipy>=1.8.0
shapely>=2.0,<3.0
spatialpandas
uxarray
xarray

# Static typing
Expand Down
3 changes: 2 additions & 1 deletion docs/developers_guide/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -394,7 +394,8 @@ seaice/api
use_mplstyle
plot_horiz_field
plot_global_field
plot_global_lat_lon_field
plot_global_mpas_field
```

### yaml
Expand Down
Binary file added docs/developers_guide/framework/images/cosine_bell_final_mpas.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
83 changes: 76 additions & 7 deletions docs/developers_guide/framework/visualization.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,19 +55,88 @@ plot_horiz_field(config, ds, ds_mesh, 'normalVelocity',

(dev-visualization-global)=

## global lat/lon plots from spherical meshes
## global lat/lon plots

You can use {py:func}`polaris.viz.plot_global_field()` to plot a field on
a regular lon-lat mesh, perhaps after remapping from an MPAS mesh using
### plotting from spherical MPAS meshes

You can use {py:func}`polaris.viz.plot_global_mpas_field()` to plot a field on
a spherical MPAS mesh.

```{image} images/cosine_bell_final_mpas.png
:align: center
:width: 500 px
```

Typical usage might be:
```python
import cmocean # noqa: F401
import xarray as xr

from polaris import Step
from polaris.viz import plot_global_mpas_field

class Viz(Step):
def run(self):

ds = xr.open_dataset('initial_state.nc')
da = ds['tracer1'].isel(Time=0, nVertLevels=0)

plot_global_mpas_field(
mesh_filename='mesh.nc', da=da,
out_filename='init.png', config=self.config,
colormap_section='cosine_bell_viz',
title='Tracer at init', plot_land=False,
central_longitude=180.)
```

The `plot_land` parameter to {py:func}`polaris.viz.plot_global_mpas_field()` is
used to enable or disable continents overlain on top of the data.

The `central_longitude` defaults to `0.0` and can be set to another value
(typically 180 degrees) for visualizing quantities that would otherwise be
divided across the antimeridian.

The `colormap_section` of the config file must contain config options for
specifying the colormap:

```cfg
# options for visualization for the cosine bell convergence test case
[cosine_bell_viz]
# colormap options
# colormap
colormap_name = viridis
# the type of norm used in the colormap
norm_type = linear
# colorbar limits
colorbar_limits = 0.0, 1.0
```

`colormap_name` can be any available matplotlib colormap. For ocean test
cases, we recommend importing [cmocean](https://matplotlib.org/cmocean/) so
the standard ocean colormaps are available.

The `norm_type` is one of `linear` (a linear colormap) or `log` (a logarithmic
colormap).

The `colorbar_limits` are the lower and upper bound of the colorbar range.


### plotting from lat/lon grids

You can use {py:func}`polaris.viz.plot_global_lat_lon_field()` to plot a field
on a regular lon-lat grid, perhaps after remapping from an MPAS mesh using
{py:class}`polaris.remap.MappingFileStep`.

```{image} images/cosine_bell_final.png
:align: center
:width: 500 px
```

The `plot_land` parameter to {py:func}`polaris.viz.plot_global_field()` is used
to enable or disable continents overlain on top of the data:
The `plot_land` parameter to {py:func}`polaris.viz.plot_global_lat_lon_field()`
is used to enable or disable continents overlain on top of the data:

```{image} images/cosine_bell_final_land.png
:align: center
Expand All @@ -80,14 +149,14 @@ import cmocean # noqa: F401
import xarray as xr

from polaris import Step
from polaris.viz import plot_global_field
from polaris.viz import plot_global_lat_lon_field

class Viz(Step):
def run(self):
ds = xr.open_dataset('initial_state.nc')
ds = ds[['tracer1']].isel(Time=0, nVertLevels=0)

plot_global_field(
plot_global_lat_lon_field(
ds.lon.values, ds.lat.values, ds.tracer1.values,
out_filename='init.png', config=self.config,
colormap_section='cosine_bell_viz',
Expand Down
128 changes: 60 additions & 68 deletions docs/developers_guide/ocean/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,69 +53,6 @@
rpe.analysis.Analysis.run
```

### inertial_gravity_wave

```{eval-rst}
.. currentmodule:: polaris.ocean.tasks.inertial_gravity_wave
.. autosummary::
:toctree: generated/
add_inertial_gravity_wave_tasks
InertialGravityWave
analysis.Analysis
analysis.Analysis.exact_solution
exact_solution.ExactSolution
exact_solution.ExactSolution.ssh
exact_solution.ExactSolution.normal_velocity
forward.Forward
forward.Forward.compute_cell_count
init.Init
init.Init.run
viz.Viz
viz.Viz.run
```

### sphere_transport

```{eval-rst}
.. currentmodule:: polaris.ocean.tasks.sphere_transport
.. autosummary::
:toctree: generated/
add_sphere_transport_tasks
SphereTransport
SphereTransport.configure
init.Init
init.Init.run
forward.Forward
analysis.Analysis
analysis.Analysis.convergence_parameters
mixing_analysis.MixingAnalysis
mixing_analysis.MixingAnalysis.run
filament_analysis.FilamentAnalysis
filament_analysis.FilamentAnalysis.run
viz.VizMap
viz.VizMap.runtime_setup
viz.Viz
viz.Viz.run
```

### cosine_bell

```{eval-rst}
Expand All @@ -140,9 +77,6 @@
analysis.Analysis
analysis.Analysis.exact_solution
viz.VizMap
viz.VizMap.run
viz.Viz
viz.Viz.run
```
Expand All @@ -169,13 +103,40 @@
analysis.Analysis.exact_solution
analysis.Analysis.get_output_field
viz.VizMap
viz.VizMap.run
viz.Viz
viz.Viz.run
```

### inertial_gravity_wave

```{eval-rst}
.. currentmodule:: polaris.ocean.tasks.inertial_gravity_wave
.. autosummary::
:toctree: generated/
add_inertial_gravity_wave_tasks
InertialGravityWave
analysis.Analysis
analysis.Analysis.exact_solution
exact_solution.ExactSolution
exact_solution.ExactSolution.ssh
exact_solution.ExactSolution.normal_velocity
forward.Forward
forward.Forward.compute_cell_count
init.Init
init.Init.run
viz.Viz
viz.Viz.run
```


### manufactured_solution

```{eval-rst}
Expand Down Expand Up @@ -228,6 +189,37 @@
ideal_age.IdealAge
```

### sphere_transport

```{eval-rst}
.. currentmodule:: polaris.ocean.tasks.sphere_transport
.. autosummary::
:toctree: generated/
add_sphere_transport_tasks
SphereTransport
SphereTransport.configure
init.Init
init.Init.run
forward.Forward
analysis.Analysis
analysis.Analysis.convergence_parameters
mixing_analysis.MixingAnalysis
mixing_analysis.MixingAnalysis.run
filament_analysis.FilamentAnalysis
filament_analysis.FilamentAnalysis.run
viz.Viz
viz.Viz.run
```

## Ocean Framework

### Convergence Tests
Expand Down
33 changes: 6 additions & 27 deletions docs/developers_guide/ocean/tasks/correlated_tracers_2d.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,34 +61,16 @@ plots the relationship between two correlated tracers for each resolution in

### viz

Visualization steps are available only in the `correlated_tracers_2d/with_viz`
tasks. They are not included in the `correlated_tracers_2d` in order to keep regression
Visualization step is available only in the `correlated_tracers_2d/with_viz`
tasks. It is not included in the `correlated_tracers_2d` in order to keep regression
as fast as possible when visualization isn't needed.

The class {py:class}`polaris.ocean.tasks.sphere_transport.viz.VizMap`
defines a step for creating a mapping file from the MPAS mesh at a given
resolution to a lon-lat grid at a resolution and interpolation method
determined by config options.

```cfg
# options for visualization for the cosine bell convergence test case
[sphere_transport_viz]
# visualization latitude and longitude resolution
dlon = 0.5
dlat = 0.5
# remapping method ('bilinear', 'neareststod', 'conserve')
remap_method = conserve
```

The class {py:class}`polaris.ocean.tasks.sphere_transport.viz.Viz`
is a step for plotting the initial and final states of the advection test for
each resolution, mapped to the common lat-lon grid. The colormap is controlled
by these options:
each resolution. The colormap is controlled by these options:

```cfg
# options for visualization for the cosine bell convergence test case
# options for visualization for the sphere transport test case
[sphere_transport_viz_*]
# colormap options
Expand All @@ -98,11 +80,8 @@ colormap_name = viridis
# the type of norm used in the colormap
norm_type = linear
# A dictionary with keywords for the norm
norm_args = {'vmin': 0., 'vmax': 1.}
# We could provide colorbar tick marks but we'll leave the defaults
# colorbar_ticks = np.linspace(0., 1., 9)
# colorbar limits
colorbar_limits = 0., 1.
```

See {ref}`dev-visualization-global` for more details.
Loading

0 comments on commit ea309c8

Please sign in to comment.