Skip to content

docs(kinematic): document units for all WRAP accessors - #70

Open
TommyC81 wants to merge 1 commit into
junzis:masterfrom
TommyC81:docs/kinematic-units
Open

docs(kinematic): document units for all WRAP accessors#70
TommyC81 wants to merge 1 commit into
junzis:masterfrom
TommyC81:docs/kinematic-units

Conversation

@TommyC81

@TommyC81 TommyC81 commented Aug 10, 2026

Copy link
Copy Markdown

What & why

The WRAP kinematic accessors in openap/kinematic.py return values in a mix of km, m/s, and m/s², but only climb_range() documented its unit. Every other accessor had a unit-less docstring (e.g. "Get takeoff distance."), so a consumer assuming meters / knots / ft·min⁻¹ silently gets a value off by 10–1000×.

The WRAP data is internally consistent — this is a documentation fix, not a computation change. Closes #69.

from openap import WRAP
w = WRAP("a320")
w.takeoff_distance()["default"]  # 1.65  -> was "1.65 of what?" — actually km
w.cruise_alt()["default"]        # 10.92 -> actually km (≈ FL358)
w.takeoff_speed()                # 85.3  -> actually m/s (166 kt)

Changes (docstrings only — zero logic change)

  • Added the unit to 27 accessors (km for distances/altitudes, m/s for speeds & vertical rates, m/s² for accelerations), matching the existing climb_range() (in km) style.
  • Added the 3 missing docstrings (cruise_max_alt, cruise_max_mach, cruise_mean_vcas).
  • Fixed landing_distance() typo: "breaking""braking".
  • Disambiguated a duplicate docstring: descent_cross_alt_concas() was a verbatim copy of …conmach(); now reads "from constant CAS to post-constant-CAS descent", matching the descent_vs_post_concas() naming already in the file.

Two minor rewordings beyond a pure unit-add, flagged for review:

  • climb_const_mach / descent_const_mach: "speed during constant Mach …""Mach number during constant Mach …" (Mach is dimensionless; there is no unit to append).
  • descent_cross_alt_concas: "from constant CAS to post-constant-CAS descent" — the constant-CAS phase ends at the lower crossover (de_h_cas_const ≈ 5.7 km), below which the descent decelerates toward approach. Verified against the three descent vertical-rate variables (de_vs_avg_mach_const / …cas_const / …after_cas) which encode the three-phase structure, and against the descent_vs_post_concas() method name.

Verification

No return values, signatures, or imports are touched. Confirmed by stripping all docstrings and diffing the remaining code — original and working copy are identical except for blank lines where docstrings were added to the three previously-bare functions.

Document units for all WRAP kinematic accessors (km, m/s, m/s^2). Docstrings only; zero logic change.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

WRAP kinematic functions return undocumented mix of units (km, m/s, m/s²) — only climb_range() documents its unit

1 participant