import cartopy
import cartopy.crs as ccrs
import jigsawpy
import numpy as np
import xarray as xr
from jigsawpy.savejig import savejig
from matplotlib.figure import Figure
from mpas_tools.io import open_dataset, write_netcdf
from mpas_tools.logging import check_call
from mpas_tools.mesh.creation.jigsaw_to_netcdf import jigsaw_to_netcdf
from mpas_tools.ocean.inject_meshDensity import inject_spherical_meshDensity
from mpas_tools.viz.colormaps import register_sci_viz_colormaps
from mpas_tools.viz.paraview_extractor import extract_vtk
from polaris import Step
from polaris.cf import add_cf_conventions
from polaris.constants import get_constant
from polaris.mesh.reconstruct import (
compute_reconstruction_weights,
get_reconstruction_validate_vars,
)
from polaris.mesh.spherical.quality import check_cell_polygon_quality
from polaris.mesh.validate import (
CELL_WIDTH_VALIDATE_VARS,
MPAS_MESH_VALIDATE_VARS,
)
from polaris.model_step import make_graph_file
[docs]
class SphericalBaseStep(Step):
"""
A base class for steps that create a JIGSAW spherical mesh
Attributes
----------
opts : jigsawpy.jigsaw_jig_t
JIGSAW options for creating the mesh
mesh_name : str
The name of the mesh
"""
[docs]
def __init__(
self,
component,
name,
subdir,
mesh_name='mesh',
cpus_per_task=16,
min_cpus_per_task=1,
):
"""
Create a new step
Parameters
----------
component : polaris.Component
The component the step belongs to
name : str
the name of the step
subdir : {str, None}
the subdirectory for the step. The default is ``name``
mesh_name : str, optional
The name of the mesh
cpus_per_task : int, optional
The cores this step would ideally have, which is what JIGSAW is
told to use as threads. Measured on Chrysalis over five
quasi-uniform resolutions, JIGSAW returns about 2 to 2.8x however
many threads it is given, and the point at which it stops
improving rises with resolution -- 4 threads at 240 km, 8 at
120 km and about 16 from 60 km down. So 16 captures nearly all
of what is available at the resolutions Polaris builds, and
asking for more would reserve cores no mesh can use. A subclass
that knows its mesh is coarse may ask for fewer.
min_cpus_per_task : int, optional
The cores this step requires. JIGSAW runs on one, just more
slowly, so a mesh is never blocked for want of cores.
"""
super().__init__(
component=component,
name=name,
subdir=subdir,
cpus_per_task=cpus_per_task,
min_cpus_per_task=min_cpus_per_task,
)
# setup files for JIGSAW
self.opts = jigsawpy.jigsaw_jig_t()
self.mesh_name = mesh_name
[docs]
def save_and_plot_cell_width(self, lon, lat, cell_width):
"""
Save the cell width field on a lon/lat grid to
``self.cell_width_filename`` and plot
Parameters
----------
lon : numpy.ndarray
longitude in degrees (length n and between -180 and 180)
lat : numpy.ndarray
longitude in degrees (length m and between -90 and 90)
cell_width : numpy.ndarray
m x n array of cell width in km
"""
section = self.config['spherical_mesh']
da = xr.DataArray(
cell_width,
dims=['lat', 'lon'],
coords={
'lat': (
'lat',
lat,
{'long_name': 'latitude', 'units': 'degrees_north'},
),
'lon': (
'lon',
lon,
{'long_name': 'longitude', 'units': 'degrees_east'},
),
},
name='cellWidth',
attrs={'long_name': 'Target cell width', 'units': 'km'},
)
cell_width_filename = self.work_path(
section.get('cell_width_filename')
)
da.to_netcdf(cell_width_filename)
if section.getboolean('plot_cell_width'):
self._plot_cell_width(cell_width)
def runtime_setup(self):
"""
Make the JIGSAW file names absolute
JIGSAW's config file records these paths verbatim and the ``jigsaw``
executable then opens them, so they must not depend on the working
directory of whichever process happens to launch it.
"""
super().runtime_setup()
opts = self.opts
for attr in ['mesh_file', 'geom_file', 'jcfg_file', 'hfun_file']:
filename = getattr(opts, attr)
if filename is not None:
setattr(opts, attr, self.work_path(filename))
# Tell JIGSAW how many threads it may use, rather than letting it
# decide. It takes this from `NUMTHREAD` in its own config file and
# not from `OMP_NUM_THREADS`, so nothing in the environment reaches
# it; left unset it sizes itself from whatever cores it can see.
#
# That is not merely untidy. The mesh JIGSAW produces depends on the
# thread count -- measured directly, a quasi-uniform 120 km mesh has
# 41154 points at one, two and four threads and 41155 above that, and
# a 30 km mesh takes four distinct point counts across the range. So
# a mesh built on a node with more cores was a different mesh, and a
# step confined to part of an allocation built a different one again.
# Six baseline comparisons in the first concurrent omega_pr run
# differed for exactly this reason.
#
# `cpus_per_task` has been reduced by now to what this step was
# actually given, so the number is the same on the serial and
# concurrent paths and the mesh is reproducible between them.
opts.numthread = self.cpus_per_task
[docs]
def setup(self):
"""
Add output files
"""
config = self.config
section = config['spherical_mesh']
validate_vars = {
'jigsaw_mesh_filename': None,
'mpas_mesh_filename': MPAS_MESH_VALIDATE_VARS,
'cell_width_filename': CELL_WIDTH_VALIDATE_VARS,
}
for option, variables in validate_vars.items():
filename = section.get(option)
self.add_output_file(filename=filename, validate_vars=variables)
self.add_cf_check(section.get('mpas_mesh_filename'))
if section.getboolean('generate_reconstruction_weights'):
filename = section.get('reconstruction_weights_filename')
self.add_output_file(
filename=filename,
validate_vars=get_reconstruction_validate_vars(
location='cell'
),
)
self.add_cf_check(filename)
self.add_output_file(filename='graph.info')
[docs]
def run(self):
"""
Finish up the step. Run this after the subclass's run() method
"""
logger = self.logger
config = self.config
section = config['spherical_mesh']
earth_radius = get_constant('mean_radius')
jigsaw_mesh_filename = self.work_path(
section.get('jigsaw_mesh_filename')
)
mpas_mesh_filename = self.work_path(section.get('mpas_mesh_filename'))
triangles_filename = self.work_path('mesh_triangles.nc')
logger.info('Convert triangles from jigsaw format to netcdf')
jigsaw_to_netcdf(
msh_filename=jigsaw_mesh_filename,
output_name=triangles_filename,
on_sphere=True,
sphere_radius=earth_radius,
)
logger.info('Convert from triangles to MPAS mesh')
tmp_mesh_filename = self.work_path('mpas_mesh_netcdf4.nc')
args = ['MpasMeshConverter.x', triangles_filename, tmp_mesh_filename]
check_call(args=args, logger=logger)
# open the mesh and rewrite it in the desired NetCDF format
ds_mesh = open_dataset(tmp_mesh_filename)
write_netcdf(ds_mesh, mpas_mesh_filename)
self._check_cell_polygon_quality(ds_mesh=ds_mesh)
if section.getboolean('generate_reconstruction_weights'):
logger.info('\n')
logger.info(
'Compute vector-reconstruction weights at cell centers'
)
reconstruction_weights_filename = self.work_path(
section.get('reconstruction_weights_filename')
)
ds_weights = compute_reconstruction_weights(
ds_mesh, location='cell'
)
write_netcdf(
add_cf_conventions(ds_weights), reconstruction_weights_filename
)
if section.getboolean('add_mesh_density'):
logger.info('Add meshDensity into the mesh file')
cell_width_filename = self.work_path(
section.get('cell_width_filename')
)
ds = xr.open_dataset(cell_width_filename)
inject_spherical_meshDensity(
ds.cellWidth.values,
ds.lon.values,
ds.lat.values,
mesh_filename=mpas_mesh_filename,
)
if section.getboolean('convert_to_vtk'):
vtk_dir = self.work_path(section.get('vtk_dir'))
# only use progress bars if we're not writing to a log file
use_progress_bar = self.log_filename is None
lat_lon = section.getboolean('vtk_lat_lon')
logger.info('Create vtk file for visualization')
extract_vtk(
ignore_time=True,
lonlat=lat_lon,
dimension_list=['maxEdges='],
variable_list=['allOnCells'],
filename_pattern=mpas_mesh_filename,
out_dir=vtk_dir,
use_progress_bar=use_progress_bar,
)
make_graph_file(
mesh_filename=mpas_mesh_filename,
graph_filename=self.work_path('graph.info'),
)
def _check_cell_polygon_quality(self, ds_mesh):
"""
Check the generated MPAS mesh for degenerate cell polygons.
Parameters
----------
ds_mesh : xarray.Dataset
MPAS mesh dataset
"""
section = self.config['spherical_mesh_quality']
if not section.getboolean('check_cell_geometry'):
return
diagnostics = check_cell_polygon_quality(
ds_mesh=ds_mesh,
minimum_edge_length_ratio=section.getfloat(
'minimum_edge_length_ratio'
),
minimum_corner_sine=section.getfloat('minimum_corner_sine'),
max_bad_cells_to_report=section.getint('max_bad_cells_to_report'),
)
self.logger.info(
'Spherical mesh cell-polygon quality check passed. '
f'Minimum edge-length ratio: '
f'{diagnostics["minimum_edge_length_ratio"]:.3e}; '
f'minimum corner sine: '
f'{diagnostics["minimum_corner_sine"]:.3e}.'
)
def _plot_cell_width(self, cell_width):
"""
Plot a lat/lon map of cell widths (mesh resolution)
Parameters
----------
cell_width : numpy.ndarray
m x n array of cell width in km
"""
config = self.config
cmap = config.get('spherical_mesh', 'cell_width_colormap')
image_filename = self.work_path(
config.get('spherical_mesh', 'cell_width_image_filename')
)
register_sci_viz_colormaps()
fig = Figure(figsize=(16.0, 8.0))
ax = fig.add_subplot(111, projection=ccrs.PlateCarree())
ax.set_global()
im = ax.imshow(
cell_width,
origin='lower',
transform=ccrs.PlateCarree(),
extent=[-180, 180, -90, 90],
cmap=cmap,
zorder=0,
)
ax.add_feature(cartopy.feature.LAND, edgecolor='black', zorder=1)
gl = ax.gridlines(
crs=ccrs.PlateCarree(),
draw_labels=True,
linewidth=1,
color='gray',
alpha=0.5,
linestyle='-',
zorder=2,
)
gl.top_labels = False
gl.right_labels = False
min_width = np.amin(cell_width)
max_width = np.amax(cell_width)
ax.set_title(
f'Grid cell size, km, min: {min_width:.1f} max: {max_width:.1f}'
)
fig.colorbar(im, ax=ax, shrink=0.60)
# Save with the default margins. bbox_inches='tight' on a
# fixed-aspect GeoAxes with an attached colorbar collapses the map
# axes, leaving an image that is nothing but the colorbar -- the same
# failure that was fixed in plot_global_mpas_field().
fig.savefig(image_filename)
[docs]
class IcosahedralMeshStep(SphericalBaseStep):
"""
A step for creating an icosahedral JIGSAW mesh
Attributes
----------
cell_width : float
The approximate cell width in km of the mesh if constant resolution
subdivisions : int
The number of subdivisions of the icosahedral mesh to perform
"""
[docs]
def __init__(
self,
component,
name='base_mesh',
subdir=None,
cell_width=None,
subdivisions=None,
mesh_name='mesh',
):
"""
Create a new step
Parameters
----------
component : polaris.Component
The component the step belongs to
name : str, optional
the name of the step
subdir : {str, None}, optional
the subdirectory for the step
cell_width : float, optional
The approximate cell width in km of the mesh if constant resolution
subdivisions : int, optional
The number of subdivisions of the icosahedral mesh to perform
mesh_name : str, optional
The name of the mesh
"""
super().__init__(
component=component, name=name, subdir=subdir, mesh_name=mesh_name
)
# run as a subprocess so output goes to a log file
self.run_as_subprocess = True
self.cell_width = cell_width
self.subdivisions = subdivisions
self.opts.hfun_hmax = 1.0
# 2-dim. simplexes
self.opts.mesh_dims = 2
self.opts.optm_iter = 512
self.opts.optm_qtol = 1e-6
[docs]
def setup(self):
"""
Add JIGSAW options based on config options
"""
section = self.config['spherical_mesh']
self.opts.mesh_file = section.get('jigsaw_mesh_filename')
self.opts.geom_file = section.get('jigsaw_geom_filename')
self.opts.jcfg_file = section.get('jigsaw_jcfg_filename')
super().setup()
[docs]
def run(self):
"""
Run this step of the task
"""
logger = self.logger
logger.info('Generate JIGSAW icosahedral mesh')
subdivisions, cell_width, lon, lat = (
self.build_subdivisions_cell_width_lat_lon()
)
self.save_and_plot_cell_width(lon, lat, cell_width)
self.make_jigsaw_mesh(subdivisions)
# do the rest of the step (converting to the MPAS base mesh)
super().run()
[docs]
def make_jigsaw_mesh(self, subdivisions):
"""
Make the JIGSAW mesh. A subclass can override this method to build
the mesh in a different way.
Parameters
----------
subdivisions : int
The number of subdivisions of the icosahedron
"""
earth_radius = get_constant('mean_radius')
opts = self.opts
geom = jigsawpy.jigsaw_msh_t()
geom.mshID = 'ellipsoid-mesh'
geom.radii = earth_radius * 1e-3 * np.ones(3, float)
jigsawpy.savemsh(opts.geom_file, geom)
icos = jigsawpy.jigsaw_msh_t()
jigsawpy.cmd.icosahedron(opts, subdivisions, icos)
[docs]
def build_subdivisions_cell_width_lat_lon(self):
"""
A function for creating cell width array for this mesh on a regular
latitude-longitude grid.
Returns
-------
subdivisions : int
The number of subdivisions of the icosahedron to make
cell_width : numpy.ndarray
m x n array of cell width in km
lon : numpy.ndarray
longitude in degrees (length n and between -180 and 180)
lat : numpy.ndarray
longitude in degrees (length m and between -90 and 90)
"""
logger = self.logger
config = self.config
icosahedral_method = config.get('spherical_mesh', 'icosahedral_method')
if icosahedral_method == 'subdivisions':
subdivisions = self.subdivisions
if subdivisions is None:
raise ValueError('The number of subdivisions was not set.')
elif icosahedral_method == 'cell_width':
cell_width = self.cell_width
if cell_width is None:
raise ValueError('The cell width was not set.')
subdivisions = self.get_subdivisions(cell_width)
else:
raise ValueError(
f'"icosahedral_method" must be either '
f'"cell_width" or the "subdivisions". Got '
f'{icosahedral_method}.'
)
cell_width = self.get_cell_width(subdivisions)
logger.info(f' cell width: {cell_width} km')
logger.info(f' subdivisions: {subdivisions}')
# save the constant approximate resolution on a 1 degree grid
nlon = 361
nlat = 181
lon = np.linspace(-180.0, 180.0, nlon)
lat = np.linspace(-90.0, 90.0, nlat)
cell_width = cell_width * np.ones((nlat, nlon))
return subdivisions, cell_width, lon, lat
[docs]
@staticmethod
def get_subdivisions(cell_width):
"""
Find the number of subdivisions of an icosahedron to achieve a
resolution as close as possible to ``cell_width``.
Parameters
----------
cell_width : float
The approximate size in km of each cell in the resulting mesh.
Returns
-------
subdivisions : int
The number of subdivisions of the icosahedron
"""
earth_radius = get_constant('mean_radius')
earth_area = 4 * np.pi * earth_radius**2
# Using Euclidean, not spherical area, so not accurate for large cell
# widths
triangle_area = np.sqrt(3) / 4.0 * (cell_width * 1e3) ** 2
triangle_count = earth_area / triangle_area
subdivisions = 0.5 * np.log2(triangle_count / 20)
subdivisions = max(0, int(np.round(subdivisions)))
return subdivisions
[docs]
@staticmethod
def get_cell_width(subdivisions):
"""
Get the approximate cell width for an icosahedral mesh given either a
number of subdivisions of the icosahedron. As a rule of thumb:
============== =================
subdivisions cell width (km)
============== =================
5 240
6 120
7 60
8 30
9 15
10 7.5
11 3.8
12 1.9
13 0.94
============== =================
Parameters
----------
subdivisions : int
The number of subdivisions of the icosahedron to make
Returns
-------
cell_width : float
The approximate size in km of each cell
"""
earth_radius = get_constant('mean_radius')
earth_area = 4 * np.pi * earth_radius**2
# compute and save the cell widths for later use in computing mesh
# density
triangle_count = 20 * 2 ** (2 * subdivisions)
triangle_area = earth_area / triangle_count
cell_width = 1e-3 * np.sqrt(triangle_area * 4.0 / np.sqrt(3))
return cell_width