Package {taruwind}

TaruWind: reduced-mode terrain and surface wind downscaling

Description

New to TaruWind? Click here to open the complete HTML getting-started guide. It walks through one connected example, from coordinates and downloads to interpreting the result.

Details

Start with taruwind_downscale for coordinates and a period, or taruwind_build and taruwind_predict for metric-grid inputs. If the help viewer does not open the link, run browseURL(system.file("doc", "getting-started.html", package = "taruwind")).

Author(s)

Maintainer: Cem Özen ozenc@itu.edu.tr

Authors:

• Cem Özen ozenc@itu.edu.tr

Build a current TaruWind response

Description

This is the current six-mode solver, not the retired spectral/shallow-layer interface. Supply the explicit metric-grid arguments documented below.

Usage

taruwind_build(...)

Arguments

Value

A prepared TaruWind response.

Examples

h = matrix(0, 5, 5)
op = taruwind_build(h, h + .03, 90, 0, 0, 180, 180, 900, .03)
taruwind_predict(op, 3, 4)

Prepare independent metric-grid sites with portable workers

Description

Prepare independent metric-grid sites with portable workers

Usage

taruwind_build_many(requests, workers = "auto", max_total_cells = 4e+06)

Arguments

Value

A list of prepared responses in input order.

Inspect downloaded cache files without changing them

Description

Reports files and their total size. Files are not removed, opened as data, or uploaded. A caller-selected persistent cache survives R restarts; the default cache is inside the current session's temporary directory.

Usage

taruwind_cache_info(cache_dir = file.path(tempdir(), "taruwind-cache"))

Arguments

Value

A tibble with relative path, bytes and modification time. Attributes 'cache_dir' and 'total_bytes' identify the root and total file size.

Examples

info = taruwind_cache_info()
attr(info, "total_bytes")

Download Copernicus GLO-30/GLO-90 DEM tiles from the public AWS registry

Description

GLO-90 is the default. If explicitly requested, GLO-30 is attempted first and missing tiles fall back to GLO-90. The product is a digital surface model and its licence/attribution remain the user's responsibility. See <https://registry.opendata.aws/copernicus-dem/>. Requests are limited to 16 source tiles; this helper downloads whole DEM tiles and reuses them from cache. It does not silently substitute ocean zero elevations when a source tile is unavailable.

Usage

taruwind_download_copernicus_dem(
  bbox,
  target_crs,
  resolution = 90,
  cache_dir = file.path(tempdir(), "taruwind-dem"),
  prefer_glo30 = FALSE,
  output = NULL
)

Arguments

Value

A projected 'terra::SpatRaster' with source/citation attributes.

Download four-node ERA5 wind support and interpolate it to target sites

Description

'taruwind_download_era5()' reads native hourly 10 m or 100 m wind components from the official geo-chunked CDS ARCO store. For every target it retrieves the four surrounding 0.25-degree nodes, performs bilinear interpolation on the selected 'u' and 'v' components separately, and returns a tidy hourly table. Downloaded Zarr metadata and chunks are cached and reused.

Usage

taruwind_download_era5(
  sites = NULL,
  lon = NULL,
  lat = NULL,
  start = NULL,
  end = NULL,
  period = NULL,
  api_key = NULL,
  cache_dir = file.path(file.path(tempdir(), "taruwind-cache"), "era5"),
  local_tz = FALSE,
  include_nodes = FALSE,
  refresh = c("auto", "always", "never"),
  quiet = FALSE,
  allow_large = FALSE,
  wind_height = 10L
)

Arguments

Details

The Climate Data Store is free to use, but its ARCO endpoint requires a CDS API key. The function checks 'api_key', then 'CDSAPIKEY' and 'CDS_API_KEY', and finally the 'key:' entry in '~/.cdsapirc'. The key is sent only in the HTTPS authorization header and is never written to the cache or result.

Value

A 'taruwind_era5' tibble with hourly vector-bilinear wind at every site. Provenance, interpolation nodes and cache files are stored as attributes.

Download WorldCover roughness on a target raster grid

Description

Reads windows from public ESA WorldCover 2021 v200 COGs, samples categorical land cover by nearest neighbour, and applies the WindKit 2.1.0 default WorldCover lookup. This is an empirical land-cover conversion, not a direct roughness measurement. It is not interchangeable with the manuscript's CORINE-based inputs. Water is floored at 0.0002 m for logarithmic profiles.

Usage

taruwind_download_worldcover(
  template,
  cache_dir = file.path(file.path(tempdir(), "taruwind-cache"), "worldcover")
)

Arguments

Value

Roughness SpatRaster in metres, with conversion provenance.

References

ESA WorldCover: <https://esa-worldcover.org/en/data-access>. WindKit roughness tables: <https://docs.wasp.dk/windkit/latest/user_guide/topography/roughness_maps.html>.

Download ERA5 and downscale geographic target time series

Description

Downloads ERA5 and (unless supplied) GLO-90. Roughness and source-profile parameters remain explicit: this function does not equate source roughness with target roughness or assume that ERA5 has one global roughness value. Downloads and raster preparation are serial to avoid cache races. Independent numeric response construction uses [taruwind_build_many()] with its memory guard and portable workers. Prepared responses can then be reused. This is a point workflow, not a national atlas tool.

Usage

taruwind_downscale(
  sites = NULL,
  lon = NULL,
  lat = NULL,
  start = NULL,
  end = NULL,
  period = NULL,
  roughness = NULL,
  depth = NULL,
  source_z0 = NULL,
  dem = NULL,
  resolution = 90,
  domain_m = 30000,
  wind_height = 10,
  local_tz = FALSE,
  cache_dir = file.path(tempdir(), "taruwind-cache"),
  api_key = NULL,
  responses = NULL,
  workers = "auto",
  profile_year = 2021,
  profile_wait_seconds = 60,
  refresh = c("auto", "always", "never"),
  quiet = FALSE
)

Arguments

Value

A tibble (also a data frame) with one row per site-hour. 'wind_speed' is vector-bilinear ERA5 speed; 'taruwind_speed' is the downscaled speed. 'attr(result, "responses")' is a named list of prepared responses, one per site. 'attr(result, "forcing_provenance")' records ERA5 source and interpolation metadata. These two attributes are separate from the printed columns. The current ERA5 download metadata is also forwarded as attributes, including 'sites', 'source', 'license', 'citation', 'retrieved_utc', 'wind_height_m', 'component_variables', 'interpolation' and 'cache_dir'. Inspect 'names(attributes(result))' for the complete set. 'saveRDS()' retains attributes; CSV does not.

Downscale a small local grid of target points

Description

Each output cell centre receives its own complete TaruWind response. This produces a map of point estimates on a regular metric grid; it is not a single shared-domain flow solve. Work therefore grows with cell count. The square output grid is centred on 'lon, lat' and rounded to an odd number of cells so that one cell represents the centre exactly. Its spacing ('map_resolution') is independent of the terrain grid spacing ('resolution'). A call may cover at most 168 hourly timestamps (seven complete UTC days). For longer periods, make consecutive calls and reuse the prepared responses from 'attr(previous$wind, "responses")'.

Usage

taruwind_downscale_area(
  lon,
  lat,
  start = NULL,
  end = NULL,
  period = NULL,
  area_m = 990,
  map_resolution = 500,
  max_cells = 25,
  roughness = "worldcover",
  depth = NULL,
  source_z0 = NULL,
  dem = NULL,
  resolution = 90,
  domain_m = 30000,
  wind_height = 10,
  cache_dir = file.path(tempdir(), "taruwind-cache"),
  api_key = NULL,
  workers = "auto",
  responses = NULL,
  profile_year = 2021,
  profile_wait_seconds = 60,
  refresh = c("auto", "always", "never"),
  quiet = FALSE
)

Arguments

Value

A list with 'wind' (site-hour tibble), 'maps' (time-labelled 'terra::SpatRaster' layers for TaruWind and vector-bilinear ERA5), and 'grid' (output grid and coordinate provenance). Use [taruwind_plot_map()] to display an individual map layer.

Automatic-workflow safety limits

Description

TaruWind's automatic download workflow is intended for point networks and local terrain domains, not accidental continental raster production. These conservative limits are checked before network or DEM work starts. Advanced users of [taruwind_download_era5()] can explicitly opt out with 'allow_large = TRUE'. The main [taruwind_downscale()] workflow does not expose this override; split larger requests into recoverable batches. A point or raw ERA5 request is limited to ten calendar years per call. Local area maps are limited to 168 hourly timestamps (seven days). Longer series can be built in batches with reusable prepared responses. Terrain-cell limits count the reflected computational grid, not just the output square. They do not estimate network bytes or guarantee that a large request will fit in memory.

Usage

taruwind_limits()

Value

A named list containing the default limits.

Apply a current reduced-mode response to target-interpolated wind

Description

Apply a current reduced-mode response to target-interpolated wind

Usage

taruwind_modal_predict(object, u, v)

Arguments

Value

A tibble of wind speeds in metres per second.

Prepare the current reduced-mode terrain and surface-memory response

Description

Low-level metric-grid interface to the manuscript formulation. Grid rows run south to north. Source roughness is an explicit effective input, not inferred from target land cover. This interface does not download or reproject data. Heights other than 10 m are supported numerically, not validated universally.

Usage

taruwind_modal_prepare(
  dem,
  roughness,
  dx,
  x0,
  y0,
  x,
  y,
  depth,
  source_z0,
  height = 10,
  profile_z0 = 0.03,
  min_scale = 10,
  reflection = TRUE,
  max_cells = 2e+06
)

Arguments

Value

A prepared response with a 2-by-2 terrain matrix, 72 directional surface factors and solver diagnostics. Construction is single-threaded.

Compute the model's neutral modal depth from latitude

Description

Compute the model's neutral modal depth from latitude

Usage

taruwind_neutral_depth(lat)

Arguments

Value

Neutral depth in metres, using the study convention '0.2 * (0.4 * 10 / log(10 / 0.01)) / abs(1.4544e-4 * sin(latitude))'. This is a fixed numerical scale, not measured or hourly ERA5 BLH.

Plot aligned terrain or an hourly wind map

Description

Uses base 'terra' graphics. Pass the two-layer output of [taruwind_site_layers()] or the 'maps' component of [taruwind_downscale_area()]. Layer names are available with 'names(x)'. When 'layer' is omitted, all supplied layers are drawn.

Usage

taruwind_plot_map(x, layer = NULL, file = NULL, width = 1200, height = 700)

Arguments

Value

The selected 'terra::SpatRaster', invisibly; draws the plot.

Predict wind speed from a prepared response

Description

Predict wind speed from a prepared response

Usage

taruwind_predict(object, u, v, weights = NULL)

Arguments

Value

A tibble with a speed column in metres per second.

Prepare a geographic target using raster terrain and roughness

Description

A local azimuthal-equidistant grid is centred on the target, so its axes at the target coincide with east/north wind components. Raster rows are reversed explicitly for the native solver. No missing cells are filled implicitly.

Usage

taruwind_prepare_site(
  lon,
  lat,
  roughness,
  depth,
  source_z0,
  dem = NULL,
  resolution = 90,
  domain_m = 30000,
  height = 10,
  cache_dir = file.path(file.path(tempdir(), "taruwind-cache"), "dem"),
  quiet = TRUE
)

Arguments

Value

A prepared response usable with [taruwind_predict()], with geographic input provenance. Caller-provided rasters must have a valid CRS.

Retrieve the terrain layers used for one geographic site

Description

Returns the GLO-90 elevation and aerodynamic roughness after alignment to the same target-centred metric grid used by [taruwind_prepare_site()]. The layers can be plotted with [taruwind_plot_map()]. No wind is downloaded or response constructed. WorldCover roughness is a land-cover lookup, not a measured roughness map.

Usage

taruwind_site_layers(
  lon,
  lat,
  roughness = "worldcover",
  dem = NULL,
  resolution = 90,
  domain_m = 30000,
  cache_dir = file.path(file.path(tempdir(), "taruwind-cache"), "dem"),
  quiet = TRUE
)

Arguments

Value

A two-layer 'terra::SpatRaster' named 'elevation_m' and 'roughness_m'.

Obtain the explicit ERA5 source-profile convention

Description

Retrieves the four-node ERA5 forecast surface roughness (FSR) climatology from CDS monthly means, averages the 12 months and 24 hours equally and bilinearly interpolates the result. The default reference year is 2021, matching the study input convention, not necessarily the requested wind year. At 10 m the effective diagnostic reference is bounded to [0.0002, 0.03] m. This cap is a source-profile convention, not a claim that ERA5's actual roughness is globally 0.03 m. At 100 m the raw FSR is retained with a 0.0002 m floor. The surface multiplier is unity at the 100 m matching reference.

Usage

taruwind_source_profile(
  lon,
  lat,
  wind_height = 10,
  reference_year = 2021,
  fsr_file = NULL,
  api_key = NULL,
  cache_dir = file.path(file.path(tempdir(), "taruwind-cache"), "source_profile"),
  wait_seconds = 60,
  quiet = TRUE
)

Arguments

Details

CDS credentials and dataset terms acceptance are required. A queued job is cached and resumed on the next call; timeout does not submit duplicate jobs. No Python, keyring or observations are needed. Existing FSR NetCDF files may be supplied for offline use. REST access is subject to CDS service changes.

Value

A list containing raw/effective roughness, neutral depth and provenance.

References

<https://cds.climate.copernicus.eu/how-to-api>

Resolve portable batch concurrency

Description

Resolve portable batch concurrency

Usage

taruwind_workers(
  workers = "auto",
  n_sites = 1L,
  cores = parallel::detectCores()
)

Arguments

Value

An integer worker count. Auto uses half the cores, rounded down, bounded below by one and above by 16 and the request count.