Regridders
Simulations often need to import external data directly onto the computational grid. The Regridders
module implements different schemes to accomplish this goal.
Currently, Regridders
comes with two implementations:
TempestRegridder
uses TempestRemap (throughClimaCoreTempestRemap
) to perform conservative interpolation onto lat-long grids.TempestRegridder
only works for single-threaded CPU runs and works directly with files.InterpolationsRegridder
uses Interpolations.jl to perform non-conservative linear interpolation onto lat-long(-z) and x-y-z grids.InterpolationsRegridder
works directly with data.
While the Regridders
can be used independently, most users will find their needs are immediately met by the SpaceVaryingInputs
and TimeVaryingInputs
interfaces. These higher-level objects implement everything that is needed to read a file to the model grid (internally using the Regridders
).
If a regridder type is not specified by the user, and multiple are available, the InterpolationsRegridder
will be used by default. At least one regridder extension must be loaded to be able to use regridding.
TempestRegridder
This extension is loaded when loading
ClimaCoreTempestRemap
TempestRegridder
performs conservative interpolation of lat-lon grids onto computational domains. TempestRegridder
performs all the interpolation ahead of time and saves the regridded fields to HDF5 files that can be read during the simulation.
Currently, TempestRegridder
does not support regridding on 3D domains. The InterpolationsRegridder
described below can be used for these cases.
Example
Assuming target_space
is a ClimaCore
2D spherical field, the input data is the variable u
in the file era5_example.nc
, and we want to read the data associated with date target_date
.
import ClimaUtilities.Regridders
import ClimaCoreTempestRemap
# Loading ClimaCoreTempest automatically loads TempestRegridder
reg = Regridders.TempestRegridder(target_space, "regrid_output", "u", "era5_example.nc")
# When reg is created, the variable `u` is regridded and the output files
# are saved to the `regrid_output` folder
regridded_u = Regridders.regrid(reg, target_date)
InterpolationsRegridder
This extension is loaded when loading
ClimaCore
andInterpolations
InterpolationsRegridder
performs linear interpolation of input data (linear along each direction) and returns a ClimaCore
Field
defined on the target_space
.
Currently, InterpolationsRegridder
only supports spherical shells and extruded spherical shells (but it could be easily extended to other domains).
It is easy to change the spatial interpolation type if needed.
InterpolationsRegridder
are created once, they are tied to a target_space
, but can be used with any input data. With MPI runs, every process computes the interpolating function. This is always done on the CPU and moved to GPU for accelerated runs.
By default, InterpolationsRegridder
assumes you are interpolating on a globe and the default extrapolation boundary conditions are: periodic (along longitudes), copy (along latitude), and throwing an error (along z). These can be changed by passing the extrapolation_bc
to the constructor of the regridder.
FAQ: How do I enable linear extrapolation in z?
Create the regridder like this:
import Interpolations as Intp
extrapolation_bc = (Intp.Periodic(), Intp.Flat(), Intp.Linear())
regridder = InterpolationsRegridder(target_space; extrapolation_bc)
Example
Assuming target_space
is a ClimaCore
2D spherical field.
import ClimaUtilities.Regridders
import ClimaCore, Interpolations
# Loading ClimaCore and Interpolations automatically loads InterpolationsRegridder
reg = Regridders.InterpolationsRegridder(target_space)
# Now we can regrid any data
lon = collect(-180:1:180)
lat = collect(-90:1:90)
# It has to be lon, lat (because this is the assumed order in the CF conventions)
dimensions = (lon, lat)
data = rand((length(lon), length(lat)))
interpolated_data = Regridders.InterpolationsRegridder(reg, data, dimensions)
interpolated_2data = Regridders.InterpolationsRegridder(reg, 2 .* data, dimensions)
API
ClimaUtilities.Regridders.TempestRegridder
— FunctionTempestRegridder(target_space::ClimaCore.Spaces.AbstractSpace,
varname::AbstractString,
input_file::AbstractString;
regrid_dir::AbstractString,
mono::Bool)
Set up a TempestRegridder
object to regrid the variable in the given input_file
to the target_space
. TempestRegridder
works only on CPU and on a single process.
Positional arguments
target_space
: the ClimaCore Space where the simulation is being performed.input_file
: the path of the NetCDF file that has to be read and processed.regrid_dir
: the path where to save the regrid files created by TempestRemap.varname
: the name of the variable in the NetCDF file.regrid_dir
: a folder where regridded Fields are saved as HDF5 files.
Keyword arguments
mono
: Whether remapping has to be monotonic or not.
ClimaUtilities.Regridders.InterpolationsRegridder
— FunctionInterpolationsRegridder(target_space::ClimaCore.Spaces.AbstractSpace
[; extrapolation_bc::Tuple])
An online regridder that uses Interpolations.jl
Currently, InterpolationsRegridder is only implemented for LatLong and LatLongZ spaces. It performs linear interpolation along each of the directions (separately). By default, it imposes periodic boundary conditions for longitude, flat for latitude, and throwing errors when extrapolating in z. This can be customized by passing the extrapolation_bc
keyword argument.
InterpolationsRegridder is GPU and MPI compatible in the simplest possible way: each MPI process has the entire input data and everything is copied to GPU.
Keyword arguments
The optional keyword argument extrapolation_bc
controls what should be done when the interpolation point is not in the domain of definition. This has to be a tuple of N elements, where N is the number of spatial dimensions. For 3D spaces, the default is (Interpolations.Periodic(), Interpolations.Flat(), Interpolations.Throw())
.
The optional keyword argument dim_increasing
controls which dimensions should be reversed before performing interpolation. This must be a tuple of N booleans, where N is the number of spatial dimensions. The default is the true
for each spatial dimension.
ClimaUtilities.Regridders.regrid
— Functionregrid(regridder::TempestRegridder, date::Dates.DateTime)
Return the field associated to the regridder
at the given date
.
regrid(regridder::InterpolationsRegridder, data, dimensions)::Field
Regrid the given data as defined on the given dimensions to the target_space
in regridder
.
This function is allocating.