Regridder
This module contains functions to regrid information between spaces. Many of the functions used in this module call TempestRemap functions via ClimaCoreTempestRemap wrappers.
Information about the TempestRemap library can be found here. Multiple remapping approaches from TempestRemap have been tested with our implementation, and information about them is located here.
Regridder API
ClimaCoupler.Regridder.write_to_hdf5
— Functionwrite_to_hdf5(REGRID_DIR, hd_outfile_root, time, field, varname, comms_ctx)
Function to save individual HDF5 files after remapping. If a CommsContext other than SingletonCommsContext
is used for comms_ctx
, the HDF5 output is readable by multiple MPI processes.
Arguments
REGRID_DIR
: [String] directory to save output files in.hd_outfile_root
: [String] root of the output file name.time
: [Dates.DateTime] the timestamp of the data being written.field
: [CC.Fields.Field] object to be written.varname
: [String] variable name of data.comms_ctx
: [ClimaComms.AbstractCommsContext] context used for this operation.
ClimaCoupler.Regridder.read_from_hdf5
— Functionread_from_hdf5(REGIRD_DIR, hd_outfile_root, time, varname, comms_ctx)
Read in a variable varname
from an HDF5 file. If a CommsContext other than SingletonCommsContext
is used for comms_ctx
, the input HDF5 file must be readable by multiple MPI processes.
Arguments
REGRID_DIR
: [String] directory to save output files in.hd_outfile_root
: [String] root of the output file name.time
: [Dates.DateTime] the timestamp of the data being written.varname
: [String] variable name of data.comms_ctx
: [ClimaComms.AbstractCommsContext] context used for this operation.
Returns
- Field or FieldVector
ClimaCoupler.Regridder.dummmy_remap!
— Functiondummmy_remap!(target, source)
Simple stand-in function for remapping. For AMIP we don't need regridding of surface model CC.Fields. When we do, we re-introduce the ClimaCoreTempestRemap remapping functions.
Arguments
target
: [CC.Fields.Field] destination of remapping.source
: [CC.Fields.Field] source of remapping.
ClimaCoupler.Regridder.remap_field_cgll_to_rll
— Functionremap_field_cgll_to_rll(
name,
field::CC.Fields.Field,
remap_tmpdir,
datafile_rll;
nlat = 90,
nlon = 180
)
Remap an individual FT-valued Field from model (CGLL) nodes to a lat-lon (RLL) grid using TempestRemap.
Arguments
name
: [Symbol] variable name.field
: [CC.Fields.Field] data to be remapped.remap_tmpdir
: [String] directory used for remapping.datafile_rll
: [String] filename of remapped data output.
ClimaCoupler.Regridder.land_fraction
— Functionfunction land_fraction(
FT,
REGRID_DIR,
comms_ctx::ClimaComms.AbstractCommsContext,
infile,
varname,
boundary_space;
outfile_root = "land_sea_cgll",
mono = false,
threshold = 0.7,
)
Initialize a fraction for land/sea classification of grid squares over the space. With mono
= true
, remappings are monotone and conservative, (slower). With mono
= false
, values outside of threshold
are cutoff (faster).
See https://github.com/CliMA/ClimaCoupler.jl/wiki/ClimaCoupler-Lessons-Learned for a detailed comparison of remapping approaches.
Arguments
FT
: [DataType] Float typeREGRID_DIR
: [String] directory to save output files in.comms_ctx
: [ClimaComms.AbstractCommsContext] context used for this operation.infile
: [String] filename containing input data.varname
: [Symbol] variable name.boundary_space
: [CC.Spaces.AbstractSpace] over which we are mapping data.outfile_root
: [String] root for output file name.mono
: [Bool] flag for monotone remapping.threshold
: [FT] cutoff value forbinary_mask
when non-monotone remapping.
Returns
- CC.Fields.Field
ClimaCoupler.Regridder.update_surface_fractions!
— Functionupdate_surface_fractions!(cs::Interfacer.CoupledSimulation)
Updates dynamically changing area fractions. Maintains the invariant that the sum of area fractions is 1 at all points.
Arguments
cs
: [Interfacer.CoupledSimulation] containing area fraction information.
ClimaCoupler.Regridder.combine_surfaces!
— Functioncombine_surfaces!(combined_field::CC.Fields.Field, sims, field_name::Val)
Sums the fields, specified by field_name
, weighted by the respective area fractions of all surface simulations. THe result is saved in combined_field
.
Arguments
combined_field
: [CC.Fields.Field] output object containing weighted values.sims
: [NamedTuple] containing simulations .field_name
: [Val] containing the name Symbol of the field t be extracted by theInterfacer.get_field
functions.
Example
combine_surfaces!(temp_field, cs.model_sims, Val(:surface_temperature))
ClimaCoupler.Regridder.combine_surfaces_from_sol!
— Functioncombine_surfaces_from_sol!(combined_field::CC.Fields.Field, fractions::NamedTuple, fields::NamedTuple)
Sums Field objects in fields
weighted by the respective area fractions, and updates these values in combined_field
. NamedTuples fields
and fractions
must have matching field names. This method can be used to combine fields that were saved in the solution history.
Arguments
combined_field
: [CC.Fields.Field] output object containing weighted values.fractions
: [NamedTuple] containing weights used on values infields
.fields
: [NamedTuple] containing values to be weighted byfractions
.
Regridder Internal Functions
ClimaCoupler.Regridder.reshape_cgll_sparse_to_field!
— Functionreshape_cgll_sparse_to_field!(field::CC.Fields.Field, in_array::Array, R, ::CC.Spaces.SpectralElementSpace2D)
Reshapes a sparse vector array in_array
(CGLL, raw output of the TempestRemap), and uses its data to populate the input Field object field
. Redundant nodes are populated using dss
operations.
Arguments
field
: [CC.Fields.Field] object populated with the input array.in_array
: [Array] input used to fillfield
.R
: [NamedTuple] containingtarget_idxs
androw_indices
used for indexing.space
: [CC.Spaces.SpectralElementSpace2D] 2d space to which we are mapping.
reshape_cgll_sparse_to_field!(field::CC.Fields.Field, in_array::Array, R, ::CC.Spaces.ExtrudedFiniteDifferenceSpace)
Reshapes a sparse vector array in_array
(CGLL, raw output of the TempestRemap), and uses its data to populate the input Field object field
. Redundant nodes are populated using dss
operations.
Arguments
field
: [CC.Fields.Field] object populated with the input array.in_array
: [Array] input used to fillfield
.R
: [NamedTuple] containingtarget_idxs
androw_indices
used for indexing.space
: [CC.Spaces.ExtrudedFiniteDifferenceSpace] 3d space to which we are mapping.
ClimaCoupler.Regridder.hdwrite_regridfile_rll_to_cgll
— Functionhdwrite_regridfile_rll_to_cgll(
FT,
REGRID_DIR,
datafile_rll,
varname,
space;
hd_outfile_root = "data_cgll",
mono = false,
)
Reads and regrids data of the varname
variable from an input NetCDF file and saves it as another NetCDF file using Tempest Remap. The input NetCDF fileneeds to be Exodus
formatted, and can contain time-dependent data. The output NetCDF file is then read back, the output arrays converted into Fields and saved as HDF5 files (one per time slice). This function should be called by the root process. The saved regridded HDF5 output is readable by multiple MPI processes.
Arguments
FT
: [DataType] Float type.REGRID_DIR
: [String] directory to save output files in.datafile_rll
: [String] filename of RLL dataset to be mapped to CGLL.varname
: [String] the name of the variable to be remapped.space
: [CC.Spaces.AbstractSpace] the space to which we are mapping.hd_outfile_root
: [String] root of the output file name.mono
: [Bool] flag to specify monotone remapping.
ClimaCoupler.Regridder.write_datafile_cc
— Functionwrite_datafile_cc(datafile_cc, field, name)
Write the data stored in field
to an NCDataset file datafile_cc
.
Arguments
datafile_cc
: [String] filename of output file.field
: [CC.Fields.Field] to be written to file.name
: [Symbol] variable name.
ClimaCoupler.Regridder.binary_mask
— Functionbinary_mask(var, threshold)
Converts a number var
to 1, if var
is greater or equal than a given threshold
value, or 0 otherwise, keeping the same type.
Arguments
var
: [FT] value to be converted.threshold
: [FT] cutoff value for conversions.
binary_mask(var)
Converts a number var
to 1, if var
is greater or equal than eps(FT)
, or 0 otherwise, keeping the same type.
Arguments
var
: [FT] value to be converted.
ClimaCoupler.Regridder.read_remapped_field
— Functionread_remapped_field(name::Symbol, datafile_latlon::String, lev_name = "z")
Extract data and coordinates from datafile_latlon
.
ClimaCoupler.Regridder.get_coords
— Functionget_coords(ds, ::CC.Spaces.ExtrudedFiniteDifferenceSpace)
get_coords(ds, ::CC.Spaces.SpectralElementSpace2D)
Extracts the coordinates from a NetCDF file ds
. The coordinates are returned as a tuple of arrays, one for each dimension. The dimensions are determined by the space type.
ClimaCoupler.Regridder.get_time
— Functionget_time(ds)
Extracts the time information from a NetCDF file ds
.