% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/era5_met.R
\name{get_era5_met}
\alias{get_era5_met}
\title{Fetch ERA5 conditions for OpenFOAM boundary conditions}
\usage{
get_era5_met(
  lon,
  lat,
  datetime,
  cds_key = Sys.getenv("CDS_API_KEY"),
  cache_dir = tempdir(),
  quiet = FALSE
)
}
\arguments{
\item{lon}{Numeric. Longitude of the site in decimal degrees (WGS-84).}

\item{lat}{Numeric. Latitude of the site in decimal degrees (WGS-84).}

\item{datetime}{POSIXct or character \code{"YYYY-MM-DD HH:MM"} in UTC.
ERA5 is available at full hours; the nearest hour is used automatically.}

\item{cds_key}{Character. CDS personal access token.  Defaults to the
\code{CDS_API_KEY} environment variable.}

\item{cache_dir}{Character. Directory for caching downloaded NetCDF files so
repeated calls for the same location and time are instant.
Default \code{tempdir()}.}

\item{quiet}{Logical. Suppress progress messages.  Default \code{FALSE}.}
}
\value{
A named list (invisibly) containing:
\describe{
\item{\code{inlet_velocity}}{\code{c(u, v, 0)} in m/s - direct input for
\code{prepare_foam_case(inlet_velocity = ...)}.  x = east, y = north,
matching a UTM-projected domain.}
\item{\code{z_ref}}{Reference height for the wind measurement - always 10 m.}
\item{\code{T_ref}}{ERA5 2-m air temperature in K. In wind-only
\code{prepare_foam_case()} runs, this is used as the uniform reference
temperature that switches buoyancy off.}
\item{\code{T_skin}}{ERA5 skin (land-surface) temperature in K.  Useful as a
\code{T_ground} estimate; \code{NULL} if unavailable.}
\item{\code{wind_speed_ms}}{Scalar 10-m wind speed in m/s.}
\item{\code{wind_dir_deg}}{Meteorological wind direction in degrees (direction
FROM which the wind blows; 0 = from North, 90 = from East).}
\item{\code{u10}, \code{v10}}{Raw ERA5 eastward and northward wind components (m/s).}
\item{\code{datetime}}{Rounded POSIXct of the ERA5 time step used.}
\item{\code{lon}, \code{lat}}{Site coordinates as supplied.}
}
}
\description{
Downloads one hour of ERA5 reanalysis data (10-m wind components, 2-m
temperature, skin temperature) from the Copernicus Climate Data Store for a
single location and time step.  Returns the values pre-formatted for direct
use as arguments to \code{\link[=prepare_foam_case]{prepare_foam_case()}} for wind simulation.

ERA5 is a global reanalysis with 0.25 deg (~28 km) spatial resolution and
hourly temporal resolution from 1940 to present.  It is \strong{not} a local
measurement; treat it as a representative synoptic condition, not a
site-specific reading.
}
\section{Authentication}{

You need a free Copernicus CDS account and a personal access token.
\enumerate{
\item Register at \url{https://cds.climate.copernicus.eu}
\item Copy your personal access token from your user profile page.
\item Set it once per session: \code{Sys.setenv(CDS_API_KEY = "your-token-here")}
or store it in \verb{~/.Renviron} so it loads automatically.
}

The legacy CDS was retired in 2024, so \code{ecmwfr} >= 2.0.0 is required for
current tokens. This function detects the installed \code{ecmwfr} API version and
adapts automatically, but on older versions the request will be rejected by
the server. Upgrade with \code{install.packages("ecmwfr")} if you hit auth errors.

You must also accept the dataset licence once, in the browser, at
\url{https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels}
(the "Terms of use" tab). Requests fail with a licence error until you do.
}

\examples{
\dontrun{
Sys.setenv(CDS_API_KEY = "your-token-here")

# Summer evening in Detroit
met <- get_era5_met(
  lon               = -83.05,
  lat               =  42.34,
  datetime          = "2023-07-15 22:00"
)

## ---- Wind simulation ------------------------------------------------
prepare_foam_case(
  case_dir       = "path/to/case",
  stl_file       = "path/to/buildings.stl",
  domain         = list(xmin = 0, xmax = 500, ymin = 0, ymax = 500,
                        zmin = 0, zmax = 200),
  inlet_velocity = met$inlet_velocity,
  z_ref          = met$z_ref,
  T_ref          = met$T_ref
)
}

}
\seealso{
\code{\link[=prepare_foam_case]{prepare_foam_case()}}
}
