1use std::f64::consts::TAU;
55
56use hpr_atmos::profile::geometric_from_wmo_geopotential_m;
57use hpr_atmos::wind::WindInterpolation;
58use hpr_atmos::{AtmosError, SoundingLevel, SoundingProfile};
59use serde::{Deserialize, Serialize};
60use thiserror::Error;
61
62use crate::netcdf::{NetCdf, NetCdfError, Variable};
63
64pub const ERA5_GRAVITY_M_S2: f64 = 9.80665;
66
67#[derive(Debug, Clone, PartialEq, Error)]
69#[non_exhaustive]
70pub enum Era5Error {
71 #[error(transparent)]
73 NetCdf(#[from] NetCdfError),
74 #[error("the file has no `{name}` variable")]
76 MissingVariable {
77 name: String,
79 },
80 #[error("`{variable}` has dimensions {found:?}; expected {expected}")]
82 Dimensions {
83 variable: String,
85 found: Vec<String>,
87 expected: String,
89 },
90 #[error("`{variable}` is in `{units}`; expected {expected}")]
92 Units {
93 variable: String,
95 units: String,
97 expected: String,
99 },
100 #[error("the time axis cannot be read: {reason}")]
102 Time {
103 reason: String,
105 },
106 #[error(
108 "the launch time ({requested} s after 1970) is outside the file's times ({first} to {last})"
109 )]
110 OutsideTimes {
111 requested: f64,
113 first: f64,
115 last: f64,
117 },
118 #[error("the site's {axis} ({value}°) is outside the file's grid ({first}° to {last}°)")]
120 OutsideGrid {
121 axis: &'static str,
123 value: f64,
125 first: f64,
127 last: f64,
129 },
130 #[error("the `{axis}` axis is empty")]
132 EmptyAxis {
133 axis: String,
135 },
136 #[error("`{axis}` is missing its value at index {index}")]
138 MissingCoordinate {
139 axis: String,
141 index: usize,
143 },
144 #[error("the `{axis}` axis is not strictly monotonic")]
146 NotMonotonic {
147 axis: String,
149 },
150 #[error("`{variable}` is missing at {pressure_pa} Pa near the site")]
152 MissingValue {
153 variable: String,
155 pressure_pa: f64,
157 },
158 #[error("{what} is {value}, which is not usable")]
160 Domain {
161 what: &'static str,
163 value: f64,
165 },
166 #[error(transparent)]
168 Atmos(#[from] AtmosError),
169}
170
171#[derive(Debug, Clone, Copy, PartialEq, PartialOrd, Serialize, Deserialize)]
174#[serde(try_from = "f64", into = "f64")]
175pub struct UtcTime {
176 unix_s: f64,
177}
178
179impl UtcTime {
180 pub fn from_unix_seconds(seconds: f64) -> Result<Self, Era5Error> {
186 if !seconds.is_finite() {
187 return Err(Era5Error::Domain {
188 what: "the time (s)",
189 value: seconds,
190 });
191 }
192 Ok(UtcTime { unix_s: seconds })
193 }
194
195 pub fn from_civil(
202 year: i32,
203 month: u32,
204 day: u32,
205 hour: u32,
206 minute: u32,
207 second: f64,
208 ) -> Result<Self, Era5Error> {
209 let bad = |what, value: f64| Err(Era5Error::Domain { what, value });
210 if !(1..=12).contains(&month) {
211 return bad("the month", f64::from(month));
212 }
213 if day == 0 || day > days_in_month(year, month) {
214 return bad("the day of the month", f64::from(day));
215 }
216 if hour > 23 {
217 return bad("the hour", f64::from(hour));
218 }
219 if minute > 59 {
220 return bad("the minute", f64::from(minute));
221 }
222 if !(0.0..60.0).contains(&second) {
223 return bad("the second", second);
224 }
225 let days = days_from_civil(i64::from(year), month, day);
226 let whole = days * 86_400 + i64::from(hour) * 3600 + i64::from(minute) * 60;
227 Ok(UtcTime {
229 unix_s: whole as f64 + second,
230 })
231 }
232
233 pub fn unix_seconds(self) -> f64 {
235 self.unix_s
236 }
237}
238
239impl TryFrom<f64> for UtcTime {
240 type Error = Era5Error;
241
242 fn try_from(seconds: f64) -> Result<Self, Era5Error> {
243 UtcTime::from_unix_seconds(seconds)
244 }
245}
246
247impl From<UtcTime> for f64 {
248 fn from(time: UtcTime) -> f64 {
249 time.unix_s
250 }
251}
252
253fn is_leap(year: i32) -> bool {
254 (year % 4 == 0 && year % 100 != 0) || year % 400 == 0
255}
256
257fn days_in_month(year: i32, month: u32) -> u32 {
258 match month {
259 2 if is_leap(year) => 29,
260 2 => 28,
261 4 | 6 | 9 | 11 => 30,
262 _ => 31,
263 }
264}
265
266fn days_from_civil(year: i64, month: u32, day: u32) -> i64 {
269 let y = if month <= 2 { year - 1 } else { year };
270 let era = y.div_euclid(400);
271 let year_of_era = y.rem_euclid(400);
272 let m = i64::from(month);
273 let day_of_year = (153 * (if m > 2 { m - 3 } else { m + 9 }) + 2) / 5 + i64::from(day) - 1;
274 let day_of_era = year_of_era * 365 + year_of_era / 4 - year_of_era / 100 + day_of_year;
275 era * 146_097 + day_of_era - 719_468
276}
277
278#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
280pub struct Era5Request {
281 pub latitude_deg: f64,
283 pub longitude_deg: f64,
285 pub time: UtcTime,
287}
288
289#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
291pub struct Era5Level {
292 pub pressure_pa: f64,
294 pub geopotential_height_m: f64,
296 pub height_msl_m: f64,
298 pub temperature_k: f64,
300 pub wind_east_m_s: f64,
302 pub wind_north_m_s: f64,
304}
305
306#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
308pub struct Era5Profile {
309 pub request: Era5Request,
311 pub times: Vec<(UtcTime, f64)>,
313 pub levels: Vec<Era5Level>,
315 pub unread: Vec<String>,
317}
318
319const TIME_NAMES: [&str; 2] = ["valid_time", "time"];
322const LEVEL_NAMES: [&str; 2] = ["pressure_level", "level"];
323
324fn find<'a>(file: &'a NetCdf, names: &[&str]) -> Result<&'a Variable, Era5Error> {
325 names
326 .iter()
327 .find_map(|name| file.variable(name))
328 .ok_or_else(|| Era5Error::MissingVariable {
329 name: names.join("` or `"),
330 })
331}
332
333fn units(variable: &Variable) -> String {
334 variable
335 .attribute("units")
336 .and_then(|a| a.values.text())
337 .unwrap_or("")
338 .trim()
339 .to_owned()
340}
341
342fn check_units(variable: &Variable, accepted: &[&str]) -> Result<(), Era5Error> {
343 let found = units(variable);
344 if accepted.contains(&found.as_str()) {
345 Ok(())
346 } else {
347 Err(Era5Error::Units {
348 variable: variable.name.clone(),
349 units: found,
350 expected: format!("`{}`", accepted.join("` or `")),
351 })
352 }
353}
354
355fn names_of(variable: &Variable) -> Vec<String> {
359 const SHOWN: usize = 8;
360 let mut names: Vec<String> = variable
361 .dimensions
362 .iter()
363 .take(SHOWN)
364 .map(|d| d.to_string())
365 .collect();
366 if let Some(rest) = variable
367 .dimensions
368 .len()
369 .checked_sub(SHOWN)
370 .filter(|&n| n > 0)
371 {
372 names.push(format!("and {rest} more"));
373 }
374 names
375}
376
377fn axis(variable: &Variable) -> Result<Vec<f64>, Era5Error> {
379 if !matches!(&variable.dimensions[..], [only] if **only == *variable.name) {
382 return Err(Era5Error::Dimensions {
383 variable: variable.name.clone(),
384 found: names_of(variable),
385 expected: format!("[\"{}\"]", variable.name),
386 });
387 }
388 if variable.values.is_empty() {
389 return Err(Era5Error::EmptyAxis {
390 axis: variable.name.clone(),
391 });
392 }
393 let packing = variable.packing()?;
394 (0..variable.values.len())
395 .map(|index| {
396 variable
397 .values
398 .get(index)
399 .and_then(|stored| packing.unpack(stored))
400 .ok_or_else(|| Era5Error::MissingCoordinate {
401 axis: variable.name.clone(),
402 index,
403 })
404 })
405 .collect()
406}
407
408fn bracket(values: &[f64], x: f64) -> Option<(usize, usize, f64, f64, f64)> {
411 if let Some(i) = values.iter().position(|&v| v == x) {
412 return Some((i, i, 1.0, 0.0, 1.0));
413 }
414 values.windows(2).enumerate().find_map(|(i, pair)| {
415 let (x1, x2) = (pair[0], pair[1]);
416 let inside = (x1 < x && x < x2) || (x2 < x && x < x1);
417 inside.then(|| (i, i + 1, x2 - x, x - x1, x2 - x1))
418 })
419}
420
421fn strictly_monotonic(values: &[f64]) -> bool {
422 values.windows(2).all(|w| w[0] < w[1]) || values.windows(2).all(|w| w[0] > w[1])
423}
424
425fn time_units(units: &str, calendar: Option<&str>) -> Result<(f64, f64), Era5Error> {
428 let bad = |reason: String| Era5Error::Time { reason };
429 let calendar = calendar.map(str::to_ascii_lowercase);
430 let proleptic = match calendar.as_deref() {
431 None | Some("standard" | "gregorian") => false,
432 Some("proleptic_gregorian") => true,
433 Some(other) => return Err(bad(format!("calendar `{other}` is not read"))),
434 };
435 let mut words = units.split_whitespace();
436 let unit = words.next().unwrap_or("").to_ascii_lowercase();
437 let seconds = match unit.as_str() {
438 "seconds" | "second" | "secs" | "sec" | "s" => 1.0,
439 "minutes" | "minute" | "mins" | "min" => 60.0,
440 "hours" | "hour" | "hrs" | "hr" | "h" => 3600.0,
441 "days" | "day" | "d" => 86_400.0,
442 _ => return Err(bad(format!("units `{units}` are not a time since a date"))),
443 };
444 if words.next().map(str::to_ascii_lowercase).as_deref() != Some("since") {
445 return Err(bad(format!("units `{units}` are not a time since a date")));
446 }
447 let rest: Vec<&str> = words.collect();
448 let (date, clock, zone) = match rest.as_slice() {
449 [date] => match date.split_once('T') {
450 Some((d, t)) => (d.to_owned(), t.to_owned(), None),
451 None => ((*date).to_owned(), "0:0:0".to_owned(), None),
452 },
453 [date, clock] => ((*date).to_owned(), (*clock).to_owned(), None),
454 [date, clock, zone] => ((*date).to_owned(), (*clock).to_owned(), Some(*zone)),
455 _ => return Err(bad(format!("units `{units}` have no reference date"))),
456 };
457 if clock.ends_with('Z') && zone.is_some() {
459 return Err(bad(format!(
460 "reference time in `{units}` names two time zones"
461 )));
462 }
463 let (clock, zone) = match clock.strip_suffix('Z') {
464 Some(clock) => (clock.to_owned(), Some("Z")),
465 None => (clock, zone),
466 };
467 if !matches!(
468 zone,
469 None | Some("UTC" | "Z" | "+00:00" | "+0000" | "+00" | "00:00")
470 ) {
471 return Err(bad(format!("reference time zone in `{units}` is not UTC")));
472 }
473 if date
476 .splitn(3, '-')
477 .chain(clock.splitn(3, ':'))
478 .any(|field| field.starts_with(['+', '-']))
479 {
480 return Err(bad(format!(
481 "reference date or time in `{units}` has a signed field"
482 )));
483 }
484 let number = |text: &str| text.parse::<f64>().ok();
485 let date: Vec<Option<f64>> = date.splitn(3, '-').map(number).collect();
486 let clock: Vec<Option<f64>> = clock.splitn(3, ':').map(number).collect();
487 let (Some(year), Some(month), Some(day)) = (
488 date.first().copied().flatten(),
489 date.get(1).copied().flatten(),
490 date.get(2).copied().flatten(),
491 ) else {
492 return Err(bad(format!(
493 "reference date in `{units}` is not YYYY-MM-DD"
494 )));
495 };
496 let field = |i: usize| clock.get(i).copied().unwrap_or(Some(0.0));
497 let (Some(hour), Some(minute), Some(second)) = (field(0), field(1), field(2)) else {
498 return Err(bad(format!("reference time in `{units}` is not hh:mm:ss")));
499 };
500 let whole = |x: f64| x.fract() == 0.0 && x.abs() < 1e6;
501 if ![year, month, day, hour, minute].into_iter().all(whole) {
502 return Err(bad(format!(
503 "reference date in `{units}` is not whole numbers"
504 )));
505 }
506 if !proleptic && (year, month, day) < (1582.0, 10.0, 15.0) {
508 return Err(bad(format!(
509 "reference date in `{units}` falls in the standard calendar's Julian part"
510 )));
511 }
512 #[allow(
513 clippy::cast_possible_truncation,
514 clippy::cast_sign_loss,
515 reason = "whole numbers under 10⁶ with no sign, by the checks above, so each cast is exact"
516 )]
517 let epoch = UtcTime::from_civil(
518 year as i32,
519 month as u32,
520 day as u32,
521 hour as u32,
522 minute as u32,
523 second,
524 )
525 .map_err(|e| bad(format!("reference date in `{units}`: {e}")))?;
526 Ok((seconds, epoch.unix_seconds()))
527}
528
529fn positions(variable: &Variable, names: [&str; 4]) -> Result<[usize; 4], Era5Error> {
532 let error = || Era5Error::Dimensions {
533 variable: variable.name.clone(),
534 found: names_of(variable),
535 expected: format!("{names:?} in any order"),
536 };
537 if variable.dimensions.len() != 4 {
538 return Err(error());
539 }
540 let mut out = [0; 4];
541 for (slot, name) in out.iter_mut().zip(names) {
542 *slot = variable
543 .dimensions
544 .iter()
545 .position(|d| **d == *name)
546 .ok_or_else(error)?;
547 }
548 Ok(out)
549}
550
551impl Era5Profile {
552 pub fn read(file: &NetCdf, request: Era5Request) -> Result<Self, Era5Error> {
560 for (what, value) in [
561 ("the latitude (deg)", request.latitude_deg),
562 ("the longitude (deg)", request.longitude_deg),
563 ] {
564 if !value.is_finite() {
565 return Err(Era5Error::Domain { what, value });
566 }
567 }
568 if request.latitude_deg.abs() > 90.0 {
569 return Err(Era5Error::Domain {
570 what: "the latitude (deg)",
571 value: request.latitude_deg,
572 });
573 }
574
575 let time = find(file, &TIME_NAMES)?;
577 let calendar = time.attribute("calendar").and_then(|a| a.values.text());
578 let (unit_s, epoch_s) = time_units(&units(time), calendar)?;
579 let times: Vec<f64> = axis(time)?
580 .into_iter()
581 .map(|t| epoch_s + t * unit_s)
582 .collect();
583 if !times.windows(2).all(|w| w[0] < w[1]) {
584 return Err(Era5Error::NotMonotonic {
585 axis: time.name.clone(),
586 });
587 }
588 let t = request.time.unix_seconds();
589 let (first, last) = (times[0], times[times.len() - 1]);
591 let Some((t1, t2, a1, a2, span)) = bracket(×, t) else {
592 return Err(Era5Error::OutsideTimes {
593 requested: t,
594 first,
595 last,
596 });
597 };
598 let mut time_weights = vec![(t1, a1 / span)];
599 if t2 != t1 {
600 time_weights.push((t2, a2 / span));
601 }
602
603 let level = find(file, &LEVEL_NAMES)?;
605 let level_scale = match units(level).as_str() {
606 "millibars" | "millibar" | "mbar" | "hPa" => 100.0,
607 "Pa" => 1.0,
608 other => {
609 return Err(Era5Error::Units {
610 variable: level.name.clone(),
611 units: other.to_owned(),
612 expected: "`hPa`, `millibars` or `Pa`".into(),
613 });
614 }
615 };
616 let pressures: Vec<f64> = axis(level)?.iter().map(|p| p * level_scale).collect();
617
618 let latitude = find(file, &["latitude"])?;
620 let longitude = find(file, &["longitude"])?;
621 check_units(latitude, &["degrees_north"])?;
622 check_units(longitude, &["degrees_east"])?;
623 let lats = axis(latitude)?;
624 let lons = axis(longitude)?;
625 for (name, values) in [("latitude", &lats), ("longitude", &lons)] {
626 if !strictly_monotonic(values) {
627 return Err(Era5Error::NotMonotonic { axis: name.into() });
628 }
629 }
630 let outside = |axis, value, values: &[f64]| Era5Error::OutsideGrid {
631 axis,
632 value,
633 first: values.first().copied().unwrap_or(f64::NAN),
634 last: values.last().copied().unwrap_or(f64::NAN),
635 };
636 let x = request.latitude_deg;
637 let (i1, i2, xa, xb, xspan) =
638 bracket(&lats, x).ok_or_else(|| outside("latitude", x, &lats))?;
639 let (low, high) = lons
641 .iter()
642 .fold((f64::INFINITY, f64::NEG_INFINITY), |(l, h), &v| {
643 (l.min(v), h.max(v))
644 });
645 let y = [0.0, -360.0, 360.0]
646 .into_iter()
647 .map(|turn| request.longitude_deg + turn)
648 .find(|y| (low..=high).contains(y))
649 .ok_or_else(|| outside("longitude", request.longitude_deg, &lons))?;
650 let (j1, j2, ya, yb, yspan) =
651 bracket(&lons, y).ok_or_else(|| outside("longitude", y, &lons))?;
652
653 let names = [
654 time.name.as_str(),
655 level.name.as_str(),
656 "latitude",
657 "longitude",
658 ];
659 let field = |name: &str, accepted: &[&str]| -> Result<Vec<f64>, Era5Error> {
661 let variable = find(file, &[name])?;
662 check_units(variable, accepted)?;
663 let at = positions(variable, names)?;
664 let packing = variable.packing()?;
665 let mut out = Vec::with_capacity(pressures.len());
666 for (k, &pressure_pa) in pressures.iter().enumerate() {
667 let value = |ti: usize, i: usize, j: usize| -> Result<f64, Era5Error> {
668 let mut index = [0u64; 4];
669 for (slot, n) in at.into_iter().zip([ti, k, i, j]) {
670 index[slot] = n as u64;
671 }
672 variable
673 .offset(&index)
674 .and_then(|o| variable.values.get(o))
675 .and_then(|stored| packing.unpack(stored))
676 .ok_or_else(|| Era5Error::MissingValue {
677 variable: name.to_owned(),
678 pressure_pa,
679 })
680 };
681 let mut total = 0.0;
682 for &(ti, weight) in &time_weights {
683 let f11 = value(ti, i1, j1)?;
684 let f21 = value(ti, i2, j1)?;
685 let f12 = value(ti, i1, j2)?;
686 let f22 = value(ti, i2, j2)?;
687 let f = (f11 * xa * ya + f21 * xb * ya + f12 * xa * yb + f22 * xb * yb)
688 / (xspan * yspan);
689 total += weight * f;
690 }
691 out.push(total);
692 }
693 Ok(out)
694 };
695 let z = field("z", &["m**2 s**-2", "m2 s-2"])?;
696 let t_k = field("t", &["K"])?;
697 let u = field("u", &["m s**-1", "m s-1"])?;
698 let v = field("v", &["m s**-1", "m s-1"])?;
699
700 let latitude_rad = request.latitude_deg.to_radians();
701 let mut levels = Vec::with_capacity(pressures.len());
702 for k in 0..pressures.len() {
703 let geopotential_height_m = z[k] / ERA5_GRAVITY_M_S2;
704 levels.push(Era5Level {
705 pressure_pa: pressures[k],
706 geopotential_height_m,
707 height_msl_m: geometric_from_wmo_geopotential_m(
708 geopotential_height_m,
709 latitude_rad,
710 )?,
711 temperature_k: t_k[k],
712 wind_east_m_s: u[k],
713 wind_north_m_s: v[k],
714 });
715 }
716 levels.sort_by(|a, b| b.pressure_pa.total_cmp(&a.pressure_pa));
717
718 let unread = file
719 .variables
720 .iter()
721 .filter(|var| var.dimensions.len() == 4 && !["z", "t", "u", "v"].contains(&&*var.name))
722 .map(|var| var.name.clone())
723 .collect();
724 let times = time_weights
725 .into_iter()
726 .map(|(i, w)| (UtcTime { unix_s: times[i] }, w))
727 .collect();
728 Ok(Era5Profile {
729 request,
730 times,
731 levels,
732 unread,
733 })
734 }
735
736 pub fn sounding(
744 &self,
745 wind_interpolation: WindInterpolation,
746 ) -> Result<SoundingProfile, AtmosError> {
747 let levels = self
748 .levels
749 .iter()
750 .map(|level| SoundingLevel {
751 height_msl_m: level.height_msl_m,
752 temperature_k: level.temperature_k,
753 pressure_pa: Some(level.pressure_pa),
754 relative_humidity: None,
755 wind_speed_m_s: Some(level.wind_east_m_s.hypot(level.wind_north_m_s)),
756 wind_direction_from_rad: Some(direction_from_rad(
757 level.wind_east_m_s,
758 level.wind_north_m_s,
759 )),
760 })
761 .collect();
762 SoundingProfile::new(
763 levels,
764 self.request.latitude_deg.to_radians(),
765 wind_interpolation,
766 )
767 }
768}
769
770pub fn direction_from_rad(u: f64, v: f64) -> f64 {
773 if u == 0.0 && v == 0.0 {
774 return 0.0;
775 }
776 let angle = (-u).atan2(-v).rem_euclid(TAU);
777 if angle >= TAU { 0.0 } else { angle + 0.0 }
779}
780
781#[cfg(test)]
782mod tests;