[ramondalmau]

What and why

Audit item I4.

BADA3Adapter.MPL always returned None, although pyBADA reads the maximum payload from the BADA3 OPF file. The mass estimate then used MTOW − OEW as the payload. With the default payload factor 1.0 that gives ZFW = MTOW, so every BADA3 flight took off at MTOW: 1,050 of 1,050 in the NEATS_FINAL sample.

BADA4 flights already used their real maximum payload. The same aircraft therefore got two different masses depending on the BADA family. For the A20N, BADA 3.16 and 4.2.1 give identical MTOW 79 t, OEW 46 t and MPL 18.3 t, yet the BADA3 path was about 11 t heavier.

Change

• BADA3Adapter.MPL returns the OPF maximum payload, as BADA4Adapter.MPL already does.
• The mass estimate treats a missing, zero, negative or NaN MPL as unusable and falls back to MTOW − OEW, with a warning. BADA 3.16 U2____.OPF gives 0; pyBADA also uses that file for G850, GFLY, M17 and M55. None of these types is in the NEATS mapping.
• Unchanged:
  • the payload factor default (1.0, the regulation default);
  • the 15 % reserve;
  • the fuel-burn guardrail, which uses MTOW − OEW on purpose because it covers payload and fuel together.
• Docs:
  • audit report (I4 note and the follow-up status table);
  • the two user-doc notes that said "BADA 3 does not provide MPL";
  • docstrings.

Effect on results (please review, Philippe)

Before/after on every flight of the NEATS_FINAL NM sample (4,959 flights), real code, no patches. The current dev reproduces production exactly on all 4,302 computed flights.

	Before (dev)	After	Change
BADA3 fleet fuel (1,050 flights)	7,312.8 t	6,983.0 t	−4.51 %
BADA3 fleet CO2			−4.48 %
BADA3 NOx			−8.1 %
BADA3 nvPM number			+2.1 %
Whole-fleet fuel (4,303 computed flights)			−0.66 %
BADA4 flights (3,253)			bit-identical, point by point
Failed flights (656)			same set, same messages

BADA3 per flight (fuel):

• median −5.7 %; 5th percentile −10.4 %; minimum −21 %;
• the minimum is on business jets with small OPF payloads (GLF5, GLEX);
• 42 flights are unchanged (still MTOW-limited, mostly long-haul);
• 5 small business jets go up by ≤ +0.6 % (H25B, C25A, LJ45), because a lower mass changes BADA3's phase selection;
• take-off mass: median −8.2 t.

NOx falls more than fuel and nvPM number rises: both emission indices depend on thrust, which is lower at lower mass.

What to look at

1. src/pyneats/steps/performance/bada_adapters.py: BADA3Adapter.MPL (4 lines).
2. src/pyneats/steps/performance/bada_model.py: the MPL guard in _estimate_initial_mass_iterative.
3. docs/internal/pyneats_units_audit.md: the I4 note and the status table.

Everything else is docstrings, user docs and tests.

Verification

• New tests in tests/test_bada3_max_payload.py:
  • the adapter returns the OPF value or None;
  • the mass estimate uses MPL, falls back on missing, zero or NaN, applies the payload factor and the MTOW cap;
  • a real-data check that A20N BADA3 MPL = BADA4 A320-271N MPL = 18,300 kg.
• The tests catch the old bug: two of them fail on the old code.
• Full suite with BADA and weather data on the final commit: 294 passed, 0 failed (4 skipped, the usual structural skips; 23 xfailed), 53 min. The golden files contain only BADA4 flights and are unchanged.
• Independent review (4 angles, every finding checked again): no code defects. Its two documentation points are fixed in this PR.

Not in this PR

• docs/explanation/input-prioritization.md and mrv-specification.md give the fuel reserve as 3 % of trip fuel; the code uses 15 %. This is pre-existing and will be a separate fix.