From 024b473673928490d6e03f9103bf71aa507eb870 Mon Sep 17 00:00:00 2001 From: Ramon DALMAU Date: Wed, 21 Oct 2026 10:27:41 +0200 Subject: [PATCH 1/2] docs: state the 15 % fuel reserve used in the initial mass estimate input-prioritization.md and mrv-specification.md gave the fuel reserve of the initial mass estimate as about 3 % of trip fuel. The code uses 15 % (DEFAULT_FUEL_RESERVE_FRACTION = 0.15, following Teoh et al. 2024). Records the item in the units audit (Section 9 and the follow-up status table) and sets the I4 status row to #73. Co-Authored-By: Claude Opus 5.5 --- docs/explanation/input-prioritization.md | 2 +- docs/explanation/mrv-specification.md | 2 +- docs/internal/pyneats_units_audit.md | 4 +++- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/explanation/input-prioritization.md b/docs/explanation/input-prioritization.md index 9910db3..bf7fd88 100644 --- a/docs/explanation/input-prioritization.md +++ b/docs/explanation/input-prioritization.md @@ -57,7 +57,7 @@ $$ **Step 2 — Compute fuel flow** and fuel burn at each trajectory point using BADA. -**Step 3 — Estimate fuel reserve** (≈ 3 % of trip fuel). +**Step 3 — Estimate fuel reserve:** 15 % of trip fuel (`fuel_reserve_fraction`, following Teoh et al., 2024). **Step 4 — Update TOW:** diff --git a/docs/explanation/mrv-specification.md b/docs/explanation/mrv-specification.md index 1ac4a84..849a426 100644 --- a/docs/explanation/mrv-specification.md +++ b/docs/explanation/mrv-specification.md @@ -200,7 +200,7 @@ The following rules are applied **sequentially** to determine how the primary da 2. **First performance calculation:** compute fuel flow and fuel burn at each trajectory point from this mass. - 3. **Fuel-reserve estimation:** the required reserve is approximated at **3 % of trip fuel**. + 3. **Fuel-reserve estimation:** the required reserve is **15 % of trip fuel** (`fuel_reserve_fraction`, following Teoh et al., 2024). 4. **Updated TOW:** diff --git a/docs/internal/pyneats_units_audit.md b/docs/internal/pyneats_units_audit.md index 1c4bc5b..969a99c 100644 --- a/docs/internal/pyneats_units_audit.md +++ b/docs/internal/pyneats_units_audit.md @@ -14,7 +14,8 @@ note under its item. Items not listed here are open. | D2 (trajectory `ts` offsets) | Fixed | #70 | 2026-10-20 | | One flight that cannot be converted no longer stops the run (D2 follow-up) | Fixed | #71 | 2026-10-20 | | D1 (bare single-flight object) | Open; now a clear `TypeError` on the `FleetRunner` JSON path | #71 | 2026-10-20 | -| I4 (BADA3 maximum payload) | Fixed; changes BADA3 fuel and CO2 | `fix/bada3-max-payload` | 2026-10-21 | +| I4 (BADA3 maximum payload) | Fixed; changes BADA3 fuel and CO2 | #73 | 2026-10-21 | +| Fuel reserve stated as 3 % in the user docs (Section 9) | Fixed (docs only; the code uses 15 %) | `docs/fuel-reserve-15pct` | 2026-10-21 | ## 1. Outcome @@ -707,6 +708,7 @@ discrepancies: | `docs/internal/performance_use_cases_analysis.md` | TAS always recomputed; early exit on FF+EE; FF never derived from mass | TAS kept when provided; early exit needs FF+EE+AM; FF derived from AM | mark superseded | | `scripts/parquet_to_neats_json.py` | treats `altitude` as feet and stamps `+0000` without converting | basis (barometric or geometric) and time zone unverified | document expected input | | `tests/test_performance_fallback.py:4,74,80`; `tests/test_guardrails.py:133,142,151` | FL15; 500 hPa | FL20; 550 hPa | update test docstrings | +| `docs/explanation/input-prioritization.md:60`; `docs/explanation/mrv-specification.md:203` | initial-mass fuel reserve ≈ 3 % of trip fuel | 15 % (`DEFAULT_FUEL_RESERVE_FRACTION = 0.15`, `neats_default_parameters.py:148`; `bada_model.py:1058`). Found after this audit, during the I4 review | fixed (`docs/fuel-reserve-15pct`) | ## 10. Incidental observations outside the unit scope From 25370d7339d8d8e2366e604b0d4663c17528af04 Mon Sep 17 00:00:00 2001 From: Ramon DALMAU Date: Wed, 21 Oct 2026 10:50:33 +0200 Subject: [PATCH 2/2] docs: describe the mass-estimate iterations as the code runs them The user docs said steps 2-4 of the mass estimate run twice. The code runs one constant-mass BADA pass, then up to three passes from the updated TOW, and stops when the TOW changes by 1 % or less of the previous TOW (max_mass_estimation_iter = 4, max_rel_mass_diff = 0.01). The last pass is kept; a BADA 3 or altitude-fallback retry starts the estimate again. Measured with the real code on the 4,303 computed NEATS_FINAL sample flights: 2,769 stop after two passes, 1,415 after three, 119 after four (3 of them at the cap with a change of 1.0-1.4 %). Recorded in the units audit, Section 9. Co-Authored-By: Claude Opus 5.5 --- docs/explanation/input-prioritization.md | 2 +- docs/explanation/mrv-specification.md | 2 +- docs/internal/pyneats_units_audit.md | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/explanation/input-prioritization.md b/docs/explanation/input-prioritization.md index bf7fd88..fbac529 100644 --- a/docs/explanation/input-prioritization.md +++ b/docs/explanation/input-prioritization.md @@ -67,7 +67,7 @@ $$ Reduce aircraft mass along the trajectory according to fuel burnt at each point. -**Step 5 — Iterate** steps 2–4 until convergence. In PyNeats, **two iterations** are used to balance accuracy and computational cost. +**Step 5 — Iterate** steps 2–4, with the mass now starting at the updated TOW and decreasing along the trajectory, until the TOW changes by 1 % or less of the previous TOW (`max_rel_mass_diff`). Within one estimate, steps 2–4 run at least twice and at most four times (`max_mass_estimation_iter`); after the fourth time the result is kept even if the change is still above 1 %. A retry with BADA 3, or after points below FL20 are removed, starts the estimate again from step 1. The fuel flow, thrust and mass kept are those of the last BADA calculation, which started from the TOW of the previous update; the TOW computed after that calculation is used only for the convergence test. !!! info "MPL source" MPL (Maximum Payload) is read from the BADA files: the OPF maximum payload for BADA 3, the aircraft file for BADA 4. Only if a BADA file gives no MPL is $\text{MPL} = MTOW - OEW$ used. diff --git a/docs/explanation/mrv-specification.md b/docs/explanation/mrv-specification.md index 849a426..dbcb94a 100644 --- a/docs/explanation/mrv-specification.md +++ b/docs/explanation/mrv-specification.md @@ -211,7 +211,7 @@ The following rules are applied **sequentially** to determine how the primary da !!! note "MPL source" MPL is read from the BADA files (the OPF maximum payload for BADA 3). Only if a BADA file gives no MPL is $\text{MPL} = MTOW - OEW$ used. - 5. **Iteration:** steps 2–4 are repeated until convergence (fixed number of iterations, or relative-tolerance stopping criterion). In PyNeats, **steps 2–4 are performed twice** to reduce computational effort. + 5. **Iteration:** steps 2–4 are repeated, with the mass along the trajectory now starting at the updated TOW, until the TOW changes by 1 % or less of the previous TOW (`max_rel_mass_diff`). Within one estimate, steps 2–4 run at least twice and at most four times (`max_mass_estimation_iter`); after the fourth time the result is kept even if the change is still above 1 %. A retry with BADA 3, or after points below FL20 are removed, starts the estimate again from step 1. The fuel flow, thrust and mass kept are those of the last BADA calculation, which started from the TOW of the previous update; the TOW computed after that calculation is used only for the convergence test. See [Input Prioritization](input-prioritization.md) for the full decision flowchart. diff --git a/docs/internal/pyneats_units_audit.md b/docs/internal/pyneats_units_audit.md index 969a99c..8cc036a 100644 --- a/docs/internal/pyneats_units_audit.md +++ b/docs/internal/pyneats_units_audit.md @@ -15,7 +15,7 @@ note under its item. Items not listed here are open. | One flight that cannot be converted no longer stops the run (D2 follow-up) | Fixed | #71 | 2026-10-20 | | D1 (bare single-flight object) | Open; now a clear `TypeError` on the `FleetRunner` JSON path | #71 | 2026-10-20 | | I4 (BADA3 maximum payload) | Fixed; changes BADA3 fuel and CO2 | #73 | 2026-10-21 | -| Fuel reserve stated as 3 % in the user docs (Section 9) | Fixed (docs only; the code uses 15 %) | `docs/fuel-reserve-15pct` | 2026-10-21 | +| Fuel reserve and number of mass iterations misstated in the user docs (Section 9) | Fixed (docs only) | `docs/fuel-reserve-15pct` | 2026-10-21 | ## 1. Outcome @@ -709,6 +709,7 @@ discrepancies: | `scripts/parquet_to_neats_json.py` | treats `altitude` as feet and stamps `+0000` without converting | basis (barometric or geometric) and time zone unverified | document expected input | | `tests/test_performance_fallback.py:4,74,80`; `tests/test_guardrails.py:133,142,151` | FL15; 500 hPa | FL20; 550 hPa | update test docstrings | | `docs/explanation/input-prioritization.md:60`; `docs/explanation/mrv-specification.md:203` | initial-mass fuel reserve ≈ 3 % of trip fuel | 15 % (`DEFAULT_FUEL_RESERVE_FRACTION = 0.15`, `neats_default_parameters.py:148`; `bada_model.py:1058`). Found after this audit, during the I4 review | fixed (`docs/fuel-reserve-15pct`) | +| `docs/explanation/input-prioritization.md:70`; `docs/explanation/mrv-specification.md:214` | the mass estimate runs steps 2–4 "twice" | when neither an `aircraft_mass` column nor a `takeoff_weight` attribute is given, steps 2–4 run at least twice and at most four times per estimate: one constant-mass BADA pass, then up to three passes from the updated TOW, stopping when the TOW changes by ≤ 1 % of the previous TOW (`max_mass_estimation_iter = 4`, `max_rel_mass_diff = 0.01`, `bada_model.py:1065-1117`); the last pass is kept. Measured on the 4,303 flights computed from the NEATS_FINAL sample: 2,769 stop after two passes, 1,415 after three, 119 after four, 3 of which stop at the cap with a change of 1.0–1.4 % (1.04, 1.17 and 1.39 %) | fixed (`docs/fuel-reserve-15pct`) | ## 10. Incidental observations outside the unit scope