Source code for acoustic_spaces.doc29.tables

"""Doc 29's aircraft data read from tables laid out as the ANP database's (Doc 29
Volume 2 Appendix G, as Volume 3's workbook lays out its reference aircraft): the
aircraft, their NPD curves, their spectral classes and their fixed-point profiles.

A table is a CSV file with a header row; its separator may be a comma or a semicolon.
Columns are found by their names, whatever their case, spaces and punctuation, and a
length or a speed is read in the unit its column's name gives in round or square
brackets, as Appendix G's "Distance (ft)" and Volume 3's "Distance (m)": m, ft or feet
for a length, m/s, kt, kts or knots for a speed. A column that names another unit, or
none, is an error.
"""

from __future__ import annotations

import csv
import re
from collections.abc import Iterable, Sequence
from dataclasses import dataclass
from pathlib import Path

import numpy as np

#: A foot (m), a knot (m/s) and a nautical mile (m).
FOOT_M = 0.3048
KNOT_M_S = 1852.0 / 3600.0
NAUTICAL_MILE_M = 1852.0
#: The units a column of lengths (m) or of speeds (m/s) may give in brackets, its case
#: and spaces aside.
LENGTH_UNITS = {"m": 1.0, "ft": FOOT_M, "feet": FOOT_M}
SPEED_UNITS = {"m/s": 1.0, "kt": KNOT_M_S, "kts": KNOT_M_S, "knots": KNOT_M_S}
#: The engine installations a lateral directivity identifier names by its start, its
#: case and punctuation aside (Volume 2 Appendix G2: "Fuselage-mounted", "Wing-mounted"
#: or "Prop").
INSTALLATIONS = ("Fuselage", "Wing", "Prop")
#: The distances of the NPD tables (ft), 200 to 25000 ft (Volume 2 Appendix G).
NPD_FEET = (200.0, 400.0, 630.0, 1000.0, 2000.0, 4000.0, 6300.0, 10000.0, 16000.0, 25000.0)
#: The third-octave bands of a spectral class (Hz), 50 Hz to 10 kHz.
SPECTRAL_BANDS_HZ = (
    50, 63, 80, 100, 125, 160, 200, 250, 315, 400, 500, 630,
    800, 1000, 1250, 1600, 2000, 2500, 3150, 4000, 5000, 6300, 8000, 10000,
)  # fmt: skip


def _key(name: str) -> str:
    return re.sub(r"[^a-z0-9]", "", name.lower())


[docs] def read_rows(path: str | Path) -> list[dict[str, str]]: """The rows of the CSV table ``path``, each a dict from its column's name to its cell (stripped).""" text = Path(path).read_text(encoding="utf-8-sig") first = text.splitlines()[0] if text else "" delimiter = ";" if first.count(";") > first.count(",") else "," reader = csv.reader(text.splitlines(), delimiter=delimiter) header = [cell.strip() for cell in next(reader)] return [ {name: cell.strip() for name, cell in zip(header, row, strict=False)} for row in reader if any(cell.strip() for cell in row) ]
def _starts(key: str, want: str) -> bool: """Whether the column key ``key`` starts with the wanted key ``want`` and does not go on with more digits of a number ``want`` ends in ("l200" starts "l200ft", not "l2000ft").""" rest = key[len(want) :] return key.startswith(want) and not (want[-1:].isdigit() and rest[:1].isdigit()) def _column(names: Iterable[str], *wanted: str) -> str: """The column of ``names`` whose name, its case and punctuation aside, is one of ``wanted`` (the first that one is), or else starts with one of them and does not go on with more digits of a number it ends in: "L_200" names "L_200 (ft)" and "L_200ft", not "L_2000 (ft)". A wanted name that two columns match alike is a ValueError, none a KeyError.""" names = list(names) for whole in (True, False): for want in wanted: key = _key(want) found = [ name for name in names if (_key(name) == key if whole else _starts(_key(name), key)) ] if len(found) > 1: listed = ", ".join(repr(name) for name in found[:-1]) raise ValueError( f"the columns {listed} and {found[-1]!r} each name {want!r}: " "which one is meant cannot be told" ) if found: return found[0] raise KeyError(f"no column {wanted[0]!r} among {names}") def _unit(name: str, units: dict[str, float], quantity: str) -> float: """The SI units in one unit of the column ``name``: the unit of ``units`` its name gives in round or square brackets.""" tags = {re.sub(r"\s", "", t).lower() for t in re.findall(r"[(\[]([^()\[\]]*)[)\]]", name)} known = tags & units.keys() if len(known) == 1: return units[known.pop()] choices = [f"({u})" for u in units] raise ValueError( f"the column {name!r} names {'more than one' if known else 'none'} of the units " f"of a {quantity} in brackets, {', '.join(choices[:-1])} or {choices[-1]}" ) def _length_m(name: str) -> float: """The metres in one unit of the column ``name`` (:data:`LENGTH_UNITS`).""" return _unit(name, LENGTH_UNITS, "length") def _speed_m_s(name: str) -> float: """The m/s in one unit of the column ``name`` (:data:`SPEED_UNITS`).""" return _unit(name, SPEED_UNITS, "speed")
[docs] def installation_of(label: str) -> str: """The engine installation, one of :data:`INSTALLATIONS`, that the lateral directivity identifier ``label`` names by its start ("Wing-mounted" names "Wing").""" key = _key(label) for installation in INSTALLATIONS: if key.startswith(installation.lower()): return installation raise ValueError( f"the lateral directivity {label!r} is none of {', '.join(INSTALLATIONS)} " "(Volume 2 Appendix G2)" )
[docs] @dataclass(frozen=True) class Aircraft: """An aircraft of the ANP database's aircraft table (Volume 2 Appendix G2): what the noise calculation needs of it.""" #: Its identifier, its description, its engines ("Jet", "Turboprop" or "Piston") #: and how many it has. name: str description: str engine_type: str engines: int #: The identifier of its NPD curves, and the power parameter they are given against. npd: str power_parameter: str #: The identifiers of its spectral classes on approach and on departure. approach_spectrum: str departure_spectrum: str #: Its lateral directivity, "Fuselage", "Wing" or "Prop" (:data:`INSTALLATIONS`): #: the engine installation correction of Volume 2 section 4.5.3. installation: str @property def jet(self) -> bool: """Whether its engines are jets (the start-of-roll directivity of jets).""" return self.engine_type.lower().startswith("jet") @property def power_in_lb(self) -> bool: """Whether its NPD curves' power parameter is in pounds, as "Corrected Net Thrust (lb)" (a percentage of one is not): the corrected net thrust per engine that Appendix B's procedural steps give.""" text = self.power_parameter.lower() pounds = re.search(r"(?<![a-z])lbf?s?(?![a-z])|pound", text) is not None return pounds and "%" not in text and "percent" not in text
[docs] def read_aircraft(path: str | Path) -> dict[str, Aircraft]: """The aircraft of the aircraft table ``path``, by identifier, each its lateral directivity the installation of :data:`INSTALLATIONS` it names.""" rows = read_rows(path) if not rows: return {} c = rows[0].keys() name = _column(c, "Aircraft Identifier", "ACFT_ID", "Aircraft ID") found = {} for row in rows: try: installation = installation_of(row[_column(c, "Lateral Directivity")]) except ValueError as error: raise ValueError(f"{Path(path).name}, aircraft {row[name]!r}: {error}") from None found[row[name]] = Aircraft( name=row[name], description=row[_column(c, "Description")], engine_type=row[_column(c, "Engine Type")], engines=int(float(row[_column(c, "Number of Engines")])), npd=row[_column(c, "NPD Identifier", "NPD ID", "NPD_ID")], power_parameter=row[_column(c, "Power Parameter")], approach_spectrum=row[_column(c, "Approach Spectral Class")], departure_spectrum=row[_column(c, "Departure Spectral Class")], installation=installation, ) return found
[docs] @dataclass(frozen=True) class NpdCurves: """One set of NPD curves (noise-power-distance, Volume 2 section 4.2): a level (dB) at each of :data:`NPD_FEET` for each power, interpolated linearly in power (eq. 4-3) and in the logarithm of the distance (eq. 4-4), and extrapolated from the last two curves or distances beyond them (eq. 4-5).""" powers: tuple[float, ...] #: The levels, a row for each power (as many as :attr:`powers`), a column for each #: distance. levels: tuple[tuple[float, ...], ...]
[docs] def level(self, power: np.ndarray | float, distance_m: np.ndarray | float) -> np.ndarray: """The level at ``power`` and ``distance_m`` (m), each an array or a number.""" powers = np.asarray(self.powers, dtype=float) table = np.asarray(self.levels, dtype=float) x = np.log10(np.asarray(distance_m, dtype=float) / FOOT_M) xs = np.log10(NPD_FEET) j = np.clip(np.searchsorted(xs, x) - 1, 0, len(xs) - 2) t = (x - xs[j]) / (xs[j + 1] - xs[j]) p = np.asarray(power, dtype=float) if len(powers) == 1: row = table[0] return np.asarray(row[j] + t * (row[j + 1] - row[j])) i = np.clip(np.searchsorted(powers, p) - 1, 0, len(powers) - 2) u = (p - powers[i]) / (powers[i + 1] - powers[i]) low = table[i, j] + t * (table[i, j + 1] - table[i, j]) high = table[i + 1, j] + t * (table[i + 1, j + 1] - table[i + 1, j]) return np.asarray(low + u * (high - low))
[docs] def read_npd(path: str | Path) -> dict[tuple[str, str, str], NpdCurves]: """The NPD curves of the NPD table ``path``, by (NPD identifier, noise descriptor, operation mode): ("JETF", "SEL", "D") for instance, the descriptor "SEL" or "LAmax" and the mode "A" (arrival) or "D" (departure).""" rows = read_rows(path) if not rows: return {} c = list(rows[0].keys()) name = _column(c, "Aircraft Identifier", "NPD Identifier", "NPD ID", "NPD_ID") metric = _column(c, "Noise Descriptor", "Noise Metric") mode = _column(c, "Operation Mode", "Op Mode") power = _column(c, "Power Setting") distances = [_column(c, f"L_{int(feet)}", f"L{int(feet)}") for feet in NPD_FEET] grouped: dict[tuple[str, str, str], list[tuple[float, tuple[float, ...]]]] = {} for row in rows: key = (row[name], _descriptor(row[metric]), row[mode][:1].upper()) levels = tuple(float(row[d]) for d in distances) grouped.setdefault(key, []).append((float(row[power]), levels)) return { key: NpdCurves( powers=tuple(p for p, _ in sorted(curves)), levels=tuple(levels for _, levels in sorted(curves)), ) for key, curves in grouped.items() }
def _descriptor(text: str) -> str: key = _key(text) if key in ("sel", "lae"): return "SEL" if key in ("lamax", "lasmax", "lmax"): return "LAmax" return text
[docs] @dataclass(frozen=True) class SpectralClass: """A spectral class (Volume 2 Appendix D, G): the spectrum, in third octaves of :data:`SPECTRAL_BANDS_HZ`, of an aircraft's sound 1000 ft (305 m) under it, its level 70 dB at 1 kHz.""" name: str mode: str description: str levels: tuple[float, ...]
[docs] def read_spectral_classes(path: str | Path) -> dict[str, SpectralClass]: """The spectral classes of the table ``path``, by identifier.""" rows = read_rows(path) if not rows: return {} c = list(rows[0].keys()) name = _column(c, "Spectral Class Identifier", "Spectral Class ID") bands = [_column(c, f"L_{hz}Hz", f"L{hz}Hz", f"{hz}Hz", str(hz)) for hz in SPECTRAL_BANDS_HZ] return { row[name]: SpectralClass( name=row[name], mode=row[_column(c, "Operation Mode", "Op Mode")], description=row[_column(c, "Description")], levels=tuple(float(row[b]) for b in bands), ) for row in rows }
[docs] @dataclass(frozen=True) class ProfilePoint: """A point of a fixed-point profile: the distance along the ground track (m; from the start of roll on departure, to touchdown on approach, negative before it), the height above the runway (m), the true airspeed (m/s) and the power (the NPD curves' parameter, per engine).""" distance_m: float height_m: float speed_m_s: float power: float
[docs] def read_fixed_point_profiles( path: str | Path, ) -> dict[tuple[str, str, str, str], tuple[ProfilePoint, ...]]: """The fixed-point profiles of the table ``path``, by (aircraft, operation mode "A" or "D", profile identifier, stage length), each its points in order.""" rows = read_rows(path) if not rows: return {} c = list(rows[0].keys()) name = _column(c, "Aircraft Identifier", "ACFT_ID", "Aircraft ID") mode = _column(c, "Operation Mode", "Op Mode") profile = _column(c, "Profile Identifier", "Profile ID") stage = _column(c, "Stage Length") number = _column(c, "Point Number") distance = _column(c, "Distance") height = _column(c, "Altitude", "Height") speed = _column(c, "True Airspeed", "TAS", "Speed") power = _column(c, "Corrected Net Thrust", "Power") grouped: dict[tuple[str, str, str, str], list[tuple[int, ProfilePoint]]] = {} for row in rows: key = (row[name], row[mode][:1].upper(), row[profile], row[stage]) point = ProfilePoint( distance_m=float(row[distance]) * _length_m(distance), height_m=float(row[height]) * _length_m(height), speed_m_s=float(row[speed]) * _speed_m_s(speed), power=float(row[power]), ) grouped.setdefault(key, []).append((int(float(row[number])), point)) return {key: tuple(p for _, p in sorted(points)) for key, points in grouped.items()}
[docs] def points_m(rows: Sequence[dict[str, str]], x: str, y: str) -> list[tuple[float, float]]: """The points (m) of the columns ``x`` and ``y`` of ``rows``, in the unit of their names.""" return [(float(r[x]) * _length_m(x), float(r[y]) * _length_m(y)) for r in rows]