PyPI - flow5ctl - Versions diffs - 0.1.0__py3-none-any.whl - Mend

flow5ctl 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (50) hide show

flow5ctl/__init__.py +35 -0
flow5ctl/__main__.py +4 -0
flow5ctl/advisor/__init__.py +0 -0
flow5ctl/advisor/dragbudget.py +155 -0
flow5ctl/advisor/guardrails.py +451 -0
flow5ctl/advisor/stability.py +81 -0
flow5ctl/advisor/structure.py +159 -0
flow5ctl/cli.py +771 -0
flow5ctl/errors.py +55 -0
flow5ctl/flow5/__init__.py +0 -0
flow5ctl/flow5/airfoils.py +175 -0
flow5ctl/flow5/foilpolar.py +121 -0
flow5ctl/flow5/markers.py +293 -0
flow5ctl/flow5/probe.py +141 -0
flow5ctl/flow5/results.py +309 -0
flow5ctl/flow5/runner.py +149 -0
flow5ctl/flow5/summary.py +427 -0
flow5ctl/flow5/xmlgen.py +422 -0
flow5ctl/geometry/__init__.py +0 -0
flow5ctl/geometry/derived.py +279 -0
flow5ctl/geometry/massprops.py +87 -0
flow5ctl/geometry/planform.py +254 -0
flow5ctl/mcp_server.py +615 -0
flow5ctl/model/__init__.py +0 -0
flow5ctl/model/design.py +280 -0
flow5ctl/model/presets.py +74 -0
flow5ctl/presets/custom.yaml +34 -0
flow5ctl/presets/hpa.yaml +53 -0
flow5ctl/presets/rc-glider.yaml +42 -0
flow5ctl/presets/uav.yaml +40 -0
flow5ctl/project/__init__.py +0 -0
flow5ctl/project/store.py +262 -0
flow5ctl/units.py +53 -0
flow5ctl/usecases/__init__.py +0 -0
flow5ctl/usecases/analyze.py +634 -0
flow5ctl/usecases/define.py +124 -0
flow5ctl/usecases/edit.py +320 -0
flow5ctl/usecases/ground.py +129 -0
flow5ctl/usecases/gui.py +50 -0
flow5ctl/usecases/plot.py +95 -0
flow5ctl/usecases/sweep.py +385 -0
flow5ctl/usecases/trim.py +371 -0
flow5ctl/viz/__init__.py +0 -0
flow5ctl/viz/charts.py +374 -0
flow5ctl/viz/palette.py +71 -0
flow5ctl-0.1.0.dist-info/METADATA +348 -0
flow5ctl-0.1.0.dist-info/RECORD +50 -0
flow5ctl-0.1.0.dist-info/WHEEL +4 -0
flow5ctl-0.1.0.dist-info/entry_points.txt +2 -0
flow5ctl-0.1.0.dist-info/licenses/LICENSE +202 -0

flow5ctl/__init__.py ADDED Viewed

@@ -0,0 +1,35 @@
+"""flow5ctl — AI-driven aircraft design with flow5.
+The public surface is the use-case layer (`flow5ctl.usecases`) and the CLI. The
+`flow5ctl.flow5` package is the only code that knows flow5 exists; nothing in
+`flow5ctl.geometry` or `flow5ctl.model` may import it, so the aerodynamic model is
+testable with flow5 absent. See docs/ARCHITECTURE.md.
+"""
+from __future__ import annotations
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _installed_version
+def _version() -> str:
+    """The one place the version comes from is the packaging metadata.
+    It used to be written here as well as in `pyproject.toml`, and the two drifted
+    the moment one of them was bumped: the 0.1.0 wheel was built correctly while
+    `flow5ctl --version`, `doctor` and the `flow5://status` resource all still said
+    `0.1.0.dev0`. A user installing a release would have been told they had a
+    pre-release. Reading it back from the installed distribution means there is
+    nothing to keep in step.
+    The fallback is for running out of a source tree with nothing installed at all,
+    where the honest answer is that we do not know rather than a number that might
+    be wrong.
+    """
+    try:
+        return _installed_version("flow5ctl")
+    except PackageNotFoundError:
+        return "0+unknown"
+__version__ = _version()
+__all__ = ["__version__"]

flow5ctl/__main__.py ADDED Viewed

@@ -0,0 +1,4 @@
+from .cli import main
+if __name__ == "__main__":
+    raise SystemExit(main())

flow5ctl/advisor/__init__.py ADDED Viewed

File without changes

flow5ctl/advisor/dragbudget.py ADDED Viewed

@@ -0,0 +1,155 @@
+"""What the drag figure does NOT include.
+A VLM analysis of a wing and a tail returns the drag of a wing and a tail. On a
+human-powered aircraft that is roughly two thirds of the aeroplane: the rigging
+wires, the fairing, the pilot's body, the wheel and every joint between components
+are simply not in the model, and flow5 has no way to put them there through this
+interface (`<body>` exists but is a lifting-surface fuselage, not a drag bookkeeping
+device).
+Leaving the reader to remember that is how a number gets quoted as if it were the
+aeroplane's. This module names the missing pieces and puts a size on them, so the
+gap between "what was modelled" and "what will fly" is on the page next to the L/D.
+**These are published estimates, not measurements by this project.** They are deliberately given as ranges: an HPA's rigging
+drag depends on wire diameter, count, length and whether the wires are faired, and
+a design that has not chosen those yet cannot be given a single number.
+The estimates are expressed as a fraction of the *modelled* total drag at the best
+lift-to-drag point, because that is the number a designer is looking at when they
+need the warning. The per-item ranges are not added together to reach the total -
+see `_TOTAL`.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+@dataclass(frozen=True, slots=True)
+class Missing:
+    """One thing the aerodynamic model does not contain."""
+    name: str
+    low: float
+    high: float
+    """Fraction of the modelled drag, low and high estimate."""
+    note: str
+    def as_dict(self) -> dict:
+        return {"item": self.name, "low": self.low, "high": self.high, "note": self.note}
+#: Human-powered aircraft. Ranges from the Daedalus and Monarch project reports and
+#: from Birdman Rally teams' own published drag budgets; see docs/DESIGN-GUIDE.md.
+#: An HPA carries a lot of wire and very little else, which is why rigging dominates.
+_HPA: tuple[Missing, ...] = (
+    Missing("rigging wires", 0.10, 0.30,
+            "bare wire runs at a section drag coefficient near 1.0. A 32 m aircraft "
+            "carries tens of metres of it. Faired wire cuts this by roughly half."),
+    Missing("pilot and fairing", 0.08, 0.20,
+            "the pilot is a bluff body. A good fairing is worth a lot here and a bad "
+            "one is worse than none, because it separates."),
+    Missing("interference at joints", 0.03, 0.08,
+            "wing-to-fuselage, tail-to-boom, and every strut end."),
+    Missing("surface finish and rib stitching", 0.02, 0.06,
+            "film over ribs is not the smooth aerofoil the 2D polar assumes."),
+    Missing("undercarriage", 0.01, 0.04,
+            "small if retracted or dropped, not small if left hanging."),
+)
+#: RC gliders and UAVs. No rigging, a much smaller fuselage relative to the wing,
+#: and usually a moulded surface - so the budget is dominated by the fuselage itself.
+_SMALL: tuple[Missing, ...] = (
+    Missing("fuselage", 0.06, 0.15, "not modelled as a drag source by this analysis."),
+    Missing("interference at joints", 0.02, 0.06, "wing root and tail junctions."),
+    Missing("surface finish", 0.01, 0.04, "a moulded surface is close to the 2D "
+                                          "assumption; a built-up one is not."),
+    Missing("control gaps and linkages", 0.01, 0.03, "hinge lines and horns."),
+)
+#: The total, taken from published whole-aircraft drag budgets rather than by summing
+#: the per-item highs above. Summing them assumes every item is simultaneously at its
+#: worst, which no flying aircraft is: for a Daedalus-class HPA the lifting surfaces
+#: are roughly three quarters of the total drag, putting everything else near 25-35 %
+#: of the modelled figure. The per-item ranges say where that total comes from and
+#: which choices move it; they are not meant to be added up.
+_TOTAL: dict[str, tuple[float, float]] = {
+    "hpa": (0.20, 0.40),
+    "rc-glider": (0.08, 0.20),
+    "uav": (0.08, 0.20),
+}
+_BY_PRESET: dict[str, tuple[Missing, ...]] = {
+    "hpa": _HPA,
+    "rc-glider": _SMALL,
+    "uav": _SMALL,
+}
+def items_for(preset_name: str) -> tuple[Missing, ...]:
+    """The missing-drag list for a preset, or nothing for `custom`.
+    `custom` gets nothing on purpose: the whole point of that preset is that no
+    assumptions are made about what kind of aircraft it is, and a drag budget IS an
+    assumption about the airframe.
+    """
+    return _BY_PRESET.get(preset_name, ())
+def budget(preset_name: str, modelled_ld: float | None) -> dict | None:
+    """A drag budget for what is not in the model, or None when nothing is known.
+    `modelled_ld` is the best lift-to-drag ratio the analysis produced. The realistic
+    band is that figure divided by (1 + missing fraction), because adding drag at
+    constant lift divides the ratio.
+    """
+    items = items_for(preset_name)
+    if not items or not modelled_ld or modelled_ld <= 0:
+        return None
+    low, high = _TOTAL.get(preset_name, (0.0, 0.0))
+    if high <= 0:
+        return None
+    return {
+        "modelled_best_LD": round(modelled_ld, 2),
+        "missing_fraction": {"low": round(low, 3), "high": round(high, 3)},
+        "realistic_best_LD": {
+            "low": round(modelled_ld / (1 + high), 2),
+            "high": round(modelled_ld / (1 + low), 2),
+        },
+        "items": [i.as_dict() for i in items],
+        "basis": ("published estimates for this class of aircraft, not measurements "
+                  "by this project"),
+    }
+def warning(preset_name: str, modelled_ld: float | None,
+            induced_bias: float | None = None) -> str | None:
+    """One sentence for the analysis output, or None when there is nothing to say.
+    `induced_bias` is the fraction of the induced drag flow5 leaves out at this
+    aircraft's aspect ratio. It is **not** folded into the band, because the band
+    comes from published whole-aircraft budgets measured against a modelled drag
+    that was assumed sound. Two optimistic errors that stack have to be said to
+    stack, or the reader subtracts one of them and thinks they are done.
+    """
+    b = budget(preset_name, modelled_ld)
+    if b is None:
+        return None
+    lo, hi = b["realistic_best_LD"]["low"], b["realistic_best_LD"]["high"]
+    frac = b["missing_fraction"]
+    names = ", ".join(i["item"] for i in b["items"][:3])
+    stacked = ""
+    if induced_bias and induced_bias >= 0.05:
+        stacked = (
+            f" That band does not include the {induced_bias:.0%} of the induced drag "
+            "flow5 leaves out at this aspect ratio, which is a separate error in the "
+            "same direction: the two stack, so treat the band as an upper bound too."
+        )
+    return (
+        f"this L/D of {b['modelled_best_LD']} is for the lifting surfaces only. "
+        f"{names} and the rest are not in the model and flow5 cannot put them there. "
+        f"Published estimates for this class put them at {frac['low']:.0%}-{frac['high']:.0%} "
+        f"of the modelled drag, which would give a realistic {lo}-{hi}. Compare a "
+        "published aircraft's figure against that band, not against the number above."
+        + stacked
+    )

flow5ctl/advisor/guardrails.py ADDED Viewed

@@ -0,0 +1,451 @@
+"""Make the wrong thing hard.
+flow5 will accept a stability request on a fixed-speed polar and answer with an
+eigenvalue of 5.995e+51. It will accept an alpha sweep well past the airfoil's stall
+and extrapolate a straight lift line through it. It will accept an inviscid run and
+report an L/D three times too high. None of these raise an error.
+So the guardrails live here, ahead of the solver, and they refuse rather than warn
+when the result would be meaningless.
+"""
+from __future__ import annotations
+import itertools
+from dataclasses import dataclass, field
+from ..errors import DesignError, UnsupportedByFlow5
+from ..geometry.derived import Derived
+from ..model.presets import Preset
+STABILITY_TYPES = {"T7"}
+DERIVATIVE_TYPES = {"T7"}
+@dataclass(slots=True)
+class Check:
+    warnings: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+    def warn(self, message: str) -> None:
+        self.warnings.append(message)
+    def note(self, message: str) -> None:
+        self.notes.append(message)
+def check_polar_type(polar_type: str, *, wants_stability: bool = False,
+                     derivatives: bool = False) -> None:
+    """Refuse combinations flow5 answers wrongly."""
+    pt = polar_type.upper()
+    if pt == "T8":
+        raise UnsupportedByFlow5(
+            "flow5 accepts a T8 polar and returns nonsense from it rather than "
+            "refusing. Measured on a 3 m glider asked for alpha 2 to 8 in steps of "
+            "2: one point came back, at a speed of 2.0 m/s that nothing in the "
+            "request mentioned, reporting a lift-to-drag ratio of 68.6. Whatever "
+            "T8POLAR is for, it is not an alpha sweep, and flow5's own "
+            "documentation does not say. Use T1, T2, T3, T5 or T7."
+        )
+    if pt == "T4":
+        raise UnsupportedByFlow5(
+            "a T4 polar holds the angle of attack and sweeps the speed, and this "
+            "tool has no way to express a speed range — `alpha` is the only sweep "
+            "there is. flow5 rejects the analysis we generate for it outright "
+            "(\"matched no plane with any analysis\"), which used to be reported as "
+            "a bug in flow5ctl. To vary speed at a fixed attitude, use `sweep` on "
+            "the `speed` parameter with a T1 polar, which is the same question "
+            "asked in a way that works."
+        )
+    if pt in {"T6"}:
+        raise UnsupportedByFlow5(
+            "T6 control polars need flap or control-surface definitions, and flow5's "
+            "plane XML has no hinge elements — a flap belongs to flow5's Foil object, "
+            "which a .dat file cannot carry. Planes loaded from a GUI-made project "
+            "cannot be paired with new analyses either, so there is no way in. "
+            "See docs/FLOW5-INTERFACE.md section 3.3."
+        )
+    if wants_stability and pt not in STABILITY_TYPES:
+        raise DesignError(
+            f"A {pt} polar cannot answer a stability question. flow5 will return "
+            "eigenvalues of order 1e51 from a non-T7 polar rather than refusing. "
+            "Use polar_type='T7' (STABILITYPOLAR) instead.\n"
+            "Static margin and neutral point ARE available from a T1 polar; it is the "
+            "dynamic modes that require T7."
+        )
+    if derivatives and pt not in DERIVATIVE_TYPES:
+        raise DesignError(
+            f"Compute_derivatives is only meaningful on a T7 polar; on a {pt} polar "
+            "flow5 fills the derivative columns with zeros and the eigenvalues with "
+            "nonsense. Use polar_type='T7'."
+        )
+def check_analysis(derived: Derived, preset: Preset, *, polar_type: str,
+                   alpha: tuple[float, float, float] | None, viscous: bool,
+                   on_the_fly: bool, ground_height: float | None) -> Check:
+    c = Check()
+    limits = preset.limits
+    panels = derived.panel_count
+    max_panels = int(limits.get("max_panels", 6000))
+    if panels > max_panels:
+        raise DesignError(
+            f"the mesh has {panels} panels, above the {preset.name} preset's ceiling of "
+            f"{max_panels}. Reduce wing.panels.spanwise or chordwise. Measured on a 34 m "
+            "high-aspect-ratio wing, results were already converged at 544 panels, so a "
+            "finer mesh usually buys nothing."
+        )
+    if alpha is not None:
+        max_alpha = float(limits.get("max_alpha", 14.0))
+        if max(abs(alpha[0]), abs(alpha[1])) > max_alpha:
+            c.warn(
+                f"the alpha sweep reaches {max(abs(alpha[0]), abs(alpha[1])):g}°, beyond "
+                f"{max_alpha:g}° where a potential-flow result is fiction — there is no "
+                "separation model, so CL keeps rising past the real CL_max. Treat the "
+                "top of this polar as unusable."
+            )
+        if alpha[2] <= 0:
+            raise DesignError("the alpha step must be positive")
+    if not viscous:
+        c.warn(
+            "this is an INVISCID run. On the shipped 3 m glider at alpha 0 the drag "
+            "came to 0.000332 inviscid against 0.017991 viscous — the inviscid run left out "
+            "98 % of the drag. Do not quote an L/D from it."
+        )
+    elif on_the_fly:
+        if len(derived.surfaces) > 1:
+            c.warn(
+                "on-the-fly XFoil can fail outright on a multi-surface aircraft: on one "
+                "3-surface glider it reported Cl = 3.23 on the elevator, discarded every "
+                "operating point, and had not finished after two minutes. It does not "
+                "always — the shipped 3 m glider runs all five points — but it is 8x "
+                "slower there (6.5 s against 0.8 s) and gives 19-28 % less viscous drag "
+                "than the interpolated method, so the two must never be mixed inside one "
+                "comparison. Check that every operating point you asked for came back."
+            )
+        c.note("viscous drag from on-the-fly XFoil; do not compare against interpolated runs.")
+    else:
+        c.note("viscous drag interpolated from a 2D polar mesh.")
+    if ground_height is not None:
+        span = derived.reference_span
+        if span and ground_height > span:
+            c.warn(
+                f"ground height {ground_height:g} m exceeds the span {span:g} m; ground "
+                "effect will be negligible at that height."
+            )
+        c.note(
+            "ground effect is on. Report the out-of-ground-effect case too — measured "
+            "on the shipped examples with the current defaults, +15.2 % on best L/D "
+            "for the 3 m glider at h = 0.30 m and +16.0 % for the 34 m HPA at "
+            "h = 2.0 m. `--compare-ground` gives both from one call."
+        )
+    elif preset.analysis.get("ground_effect"):
+        c.warn(
+            f"the {preset.name} preset expects ground effect to matter, but this "
+            "analysis has none. For an aircraft flown a few metres above water that "
+            "omits a large part of the performance."
+        )
+    if polar_type.upper() in {"T2", "T3"}:
+        c.note(
+            "a fixed-lift or glide polar flies slower at high CL, so the local Reynolds "
+            "number drops well below cruise. The 2D polar mesh must cover that."
+        )
+        if alpha is not None and alpha[0] <= 0.0:
+            c.warn(
+                f"this {polar_type.upper()} polar starts at α = {alpha[0]:g}°. A "
+                "fixed-lift or glide polar has no solution where the aircraft produces "
+                "no lift — the required speed diverges, and flow5 solves an enormous "
+                "speed rather than refusing. Start the sweep above the zero-lift angle "
+                "(α > 0 for a symmetric section)."
+            )
+    return c
+def check_geometry(derived: Derived, preset: Preset) -> Check:
+    """Sanity thresholds, plus the checks flow5 will never do for you."""
+    c = Check()
+    def band(key: str, value: float | None, label: str, fmt: str = "{:.3g}") -> None:
+        b = preset.band(key)
+        if b is None or value is None:
+            return
+        lo, hi = b
+        if value < lo or value > hi:
+            c.warn(
+                f"{label} is {fmt.format(value)}, outside the {lo:g}–{hi:g} range typical "
+                f"for {preset.label.lower()}. Check the design, or use preset='custom' if "
+                "this is deliberate."
+            )
+    band("aspect_ratio", derived.aspect_ratio, "aspect ratio", "{:.1f}")
+    band("wing_loading", derived.wing_loading, "wing loading (kg/m²)")
+    band("reynolds_at_mac", derived.reynolds_at_mac, "Reynolds number at the MAC", "{:.3g}")
+    band("tail_volume_h", derived.tail_volume_h, "horizontal tail volume")
+    band("tail_volume_v", derived.tail_volume_v, "vertical tail volume", "{:.4g}")
+    fin = next((x for x in derived.surfaces if x.wing.role == "fin"), None)
+    if fin is not None and fin.wing.count == 2 and preset.band("tail_volume_v"):
+        lo, hi = preset.band("tail_volume_v")
+        if derived.tail_volume_v is not None and not (lo <= derived.tail_volume_v <= hi):
+            # The band was fitted to single-fin aircraft. A twin fin needs more total
+            # area for the same effect - each one sits in a worse part of the flow -
+            # and one published human-powered aircraft flies at 0.0264 with two.
+            # Rather than invent a second band from one data point, say so.
+            c.note(
+                "that band was set from aircraft with one fin. This design has two, "
+                "which normally need more total area for the same effect, so the "
+                "figure above may be reasonable — compare it against twin-fin "
+                "aircraft rather than against the band."
+            )
+    _check_wake_plane(derived, c)
+    _check_induced_drag_bias(derived, c)
+    _check_spanwise_mesh(derived, c)
+    _check_extra_surfaces(derived, c)
+    if derived.tail_volume_h is None and len(derived.surfaces) == 1:
+        c.note("wing only — no tail, so pitch trim and stability cannot be assessed.")
+    _check_coincident_surfaces(derived, c)
+    semi_span = derived.reference_span / 2.0
+    if derived.mass.from_components and derived.mass.lateral_inertia_is_degenerate(semi_span):
+        kx = derived.mass.roll_radius_of_gyration
+        c.warn(
+            f"the roll radius of gyration is {kx:.3g} m, only "
+            f"{kx / semi_span * 100:.1f} % of the semi-span (Ixx = {derived.mass.ixx:.3g} "
+            "kg·m²). The mass model has essentially no spanwise content, so "
+            "lateral-directional results will be meaningless — flow5 returns `inf` for "
+            "roll damping in this situation. Give the wing structure mass spanwise "
+            "positions; real aircraft sit around 15-35 % of semi-span."
+        )
+    if not derived.mass.from_components:
+        c.note(
+            "mass was given as a total, so inertia is unknown and lateral-directional "
+            "results will not be meaningful. Use mass.components to get inertia."
+        )
+    if derived.cg_percent_mac is not None:
+        c.note(f"CG is at {derived.cg_percent_mac * 100:.1f} % MAC.")
+    return c
+#: Below this many spanwise panels per semi-span, induced drag is measurably
+#: optimistic. See docs/log/2026-09-04-induced-drag-and-the-mesh.md.
+MIN_SPANWISE = 25
+#: Below this the bias is under about 5 % and saying so every time would be noise.
+INDUCED_DRAG_AR_FLOOR = 15.0
+#: Measured on elliptic wings, where the exact answer is e = 1.0 and a planar wing
+#: cannot beat it. (aspect ratio, fraction by which flow5's induced drag is low).
+#: docs/log/2026-09-04-induced-drag-against-avl.md
+_INDUCED_BIAS = ((6.0, 0.009), (10.0, 0.024), (15.0, 0.046), (20.0, 0.072),
+                 (25.0, 0.098), (30.0, 0.124), (40.0, 0.174), (50.0, 0.219))
+def induced_drag_bias(aspect_ratio: float) -> float:
+    """How much of the induced drag flow5 leaves out, as a fraction, at this AR.
+    Linear between the measured points and held flat outside them, because
+    extrapolating a fitted curve past AR 50 would be inventing numbers.
+    """
+    pts = _INDUCED_BIAS
+    if aspect_ratio <= pts[0][0]:
+        return pts[0][1]
+    if aspect_ratio >= pts[-1][0]:
+        return pts[-1][1]
+    for (a0, b0), (a1, b1) in itertools.pairwise(pts):
+        if a0 <= aspect_ratio <= a1:
+            return b0 + (b1 - b0) * (aspect_ratio - a0) / (a1 - a0)
+    return pts[-1][1]
+def _check_induced_drag_bias(derived: Derived, c: Check) -> None:
+    """flow5 under-predicts induced drag, and the shortfall grows with span.
+    Measured against AVL and against the one case with an exact answer: an elliptic
+    planar wing has e = 1.0 and cannot exceed it. flow5 returns 1.024 at AR 10 and
+    **1.210 at AR 40** — 21 % past a hard physical limit — while AVL returns 0.997
+    and 0.996 on the same planforms. It is not the mesh, the panel distribution or
+    the method: varying all of those moves it by 0.4 %.
+    Human-powered aircraft fly at AR 30-45, where induced drag is most of the drag
+    budget, so this is the largest known bias in the tool for its main users. It is
+    reported rather than corrected: applying a fudge factor to a solver's output
+    would hide the problem and would be wrong for any case not measured here.
+    """
+    ar = derived.aspect_ratio
+    if not ar or ar < INDUCED_DRAG_AR_FLOOR:
+        return
+    bias = induced_drag_bias(ar)
+    c.warn(
+        f"at aspect ratio {ar:.0f}, flow5's induced drag is about {bias:.0%} low. "
+        "Measured on elliptic wings, where the exact answer is a span efficiency of "
+        "1.0 and no planar wing can beat it: flow5 returns 1.21 at AR 40, while AVL "
+        "returns 0.996 on the same wing. Lift is unaffected — the two solvers agree "
+        "within 0.6 % — and changing method does not help: flow5's panel methods "
+        "(QUADS, TRIUNIFORM, TRILINEAR) come out 21 % on the other side of the same "
+        "limit. So the lift-to-drag "
+        "figures from this run are optimistic on top of everything the drag budget "
+        "already lists, and the more so the more of the drag is induced. Cross-check "
+        "against AVL before committing a design."
+    )
+#: A downstream surface closer than this to the wing's own plane, as a fraction of
+#: the wing's MAC, sits in its trailing vortex sheet and the induced drag is wrong.
+WAKE_PLANE_MAC = 0.10
+def _check_wake_plane(derived: Derived, c: Check) -> None:
+    """A tail level with the wing sits in its wake sheet, and the drag halves.
+    The wing's trailing vortices leave at its own height and run downstream. Put a
+    horizontal tail at exactly that height and its control points sit on the sheet,
+    which is singular; flow5 does not complain, it returns a number.
+    Measured on an AR 12 wing of 0.25 m chord with a 0.9 x 0.15 m tail 1.2 m behind,
+    inviscid, at alpha 6, moving only the tail's z:
+    | tail z | as a fraction of chord | induced drag | span efficiency |
+    |---|---|---|---|
+    | 0.000 | 0 | 0.00483 | **1.93 — impossible** |
+    | 0.001 | 0.4 % | 0.00734 | 1.27 — impossible |
+    | 0.005 | 2 % | 0.00935 | 0.996 |
+    | 0.010 | 4 % | 0.00964 | 0.966 |
+    | 0.020 | 8 % | 0.00977 | 0.953 |
+    Two centimetres of offset **doubles** the induced drag, to a value that then
+    matches AVL within 3 %. So this is not a small sensitivity to a modelling
+    choice: at zero offset the answer is out by a factor of two, in the optimistic
+    direction, with nothing in the output to say so.
+    Real aircraft rarely sit exactly there, but a design.yaml written as
+    `position: [1.2, 0, 0]` does, and that is an easy thing to type.
+    """
+    main = derived.main
+    if main is None:
+        return
+    mac = derived.reference_chord
+    if not mac:
+        return
+    z_wing = main.position_m[2]
+    for s in derived.surfaces:
+        if s is main or s.wing.role == "fin":
+            continue                      # a fin is vertical; it has no such plane
+        if s.position_m[0] <= main.position_m[0]:
+            continue                      # a canard is upstream of the sheet
+        gap = abs(s.position_m[2] - z_wing)
+        if gap >= WAKE_PLANE_MAC * mac:
+            continue
+        name = s.wing.name or s.wing.role
+        c.warn(
+            f"{name} sits {gap:.3g} m from the wing's own height, which is "
+            f"{gap / mac:.0%} of the MAC, and it is behind the wing. That puts it in "
+            "the wing's trailing vortex sheet, where the induced drag comes out "
+            "wrong and flow5 says nothing. Measured on a comparable layout: at zero "
+            "offset the induced drag was half its converged value and the span "
+            "efficiency read 1.93, which is impossible; moving the tail 2 cm — 8 % "
+            f"of chord — doubled it and brought it within 3 % of AVL. Offset {name} "
+            "vertically by at least a tenth of the MAC, or model the height it "
+            "actually has."
+        )
+def _check_extra_surfaces(derived: Derived, c: Check) -> None:
+    """Tail volume is a two-surface idea, and a fourth surface breaks it.
+    Both tail volume coefficients are area x lever arm over the main wing's area and
+    a reference length, and every published band for them was fitted to aircraft
+    with one lifting wing and one tail. On a tandem or a canard the lift is shared
+    between two surfaces and the bands are simply not about that aircraft, so the
+    number is still computed - it is what flow5's geometry gives - but it is not
+    something to size against.
+    """
+    extra = [s for s in derived.surfaces if s.wing.role == "other"]
+    if not extra:
+        return
+    names = ", ".join(s.wing.name or "unnamed" for s in extra)
+    if derived.tail_volume_h is not None or derived.tail_volume_v is not None:
+        c.note(
+            f"this design has a lifting surface beyond the wing, elevator and fin "
+            f"({names}). The tail volumes above are still computed from the elevator "
+            "and fin alone, and the bands they are compared against were fitted to "
+            "aircraft with one wing and one tail. On a tandem or a canard they are "
+            "not the right measure of pitch or yaw authority — check the trimmed "
+            "condition and the static margin instead."
+        )
+def _check_spanwise_mesh(derived: Derived, c: Check) -> None:
+    """Induced drag is set by the span, and a coarse span makes it optimistic.
+    Measured on rectangular wings at AR 10 and AR 40, inviscid, varying only the
+    spanwise panel count. Span efficiency comes out **above 1** on a coarse mesh —
+    impossible for a planar wing — and falls monotonically, linearly in 1/N:
+    | spanwise per semi-span | how optimistic the induced drag is |
+    |---|---|
+    | 20 | about 3 % |
+    | 40 | about 1.5 % |
+    | 80 | about 0.7 % |
+    Chordwise panels make no difference to this at all: 7, 13 and 21 chordwise agree
+    to four decimal places. So the fix is always to spend the panels on the span.
+    """
+    main = derived.main
+    if main is None:
+        return
+    spanwise = getattr(main.wing.panels, "spanwise", None)
+    if not spanwise or spanwise >= MIN_SPANWISE:
+        return
+    c.note(
+        f"the wing has {spanwise} spanwise panels per semi-span. Induced drag is set "
+        "by the span, and below about 25 it is optimistic — measured 3 % at 20 "
+        "panels, with the span efficiency coming out above 1, which is impossible "
+        "for a planar wing. Chordwise panels do not help this; 40 spanwise brings it "
+        "inside 1.5 %."
+    )
+def _check_coincident_surfaces(derived: Derived, c: Check) -> None:
+    """Two surfaces in the same place make flow5 produce nonsense, not an error.
+    Observed: a fin whose root sat exactly on the elevator gave an effective angle of
+    attack of -104 degrees at the elevator centre and failed the whole analysis. flow5
+    does not check for this, so we do.
+    """
+    tol = 0.02
+    for i, a in enumerate(derived.surfaces):
+        for b in derived.surfaces[i + 1:]:
+            same_x = abs(a.position_m[0] - b.position_m[0]) < tol
+            same_z = abs(a.position_m[2] - b.position_m[2]) < tol
+            if not (same_x and same_z):
+                continue
+            roles = {a.wing.role, b.wing.role}
+            if roles == {"elevator", "fin"}:
+                c.warn(
+                    f"the fin root and the elevator are both at x = "
+                    f"{a.position_m[0]:.3g} m, z = {a.position_m[2]:.3g} m. Coincident "
+                    "surfaces make flow5 compute nonsensical local flow angles and fail "
+                    "the analysis. Offset the fin root a few centimetres above the "
+                    "elevator."
+                )
+            else:
+                c.warn(
+                    f"{a.wing.name or a.wing.role!r} and {b.wing.name or b.wing.role!r} "
+                    f"are at the same position (x = {a.position_m[0]:.3g} m, "
+                    f"z = {a.position_m[2]:.3g} m). Overlapping panels give unreliable "
+                    "results."
+                )