pyflightstream

Version-aware, didactic Python driver for the FlightStream panel-method solver. Successor of the author's legacy research scripts. MIT licensed.

Status: v0.7.0 is the current release. It publishes to PyPI and archives on Zenodo from the tag, so the concept DOI in CITATION.cff resolves to the newest archived version and the version DOI is recorded one commit after the tag that names it. CHANGELOG.md carries the release history. This release registers an eighth FlightStream build the day after the vendor issued it, and every command any of the eight registered manual editions documents now has an entry. Read that claim at the level it is measured at, which the release notes do: ten readings across four commands are deliberately withheld where a version row cannot express a layout, and the coverage tool reports that second measure beside the first rather than leaving it to prose.

The release before it registered three older builds and gave every registered build the vendor build number its solver prints, so an install can be identified rather than described.

pip install pyflightstream

A first taste, no solver required (build time is where errors surface):

from pyflightstream.commands import CommandNotInVersionError
from pyflightstream.script import Script

script = Script(version="26.120")  # the FlightStream version is explicit input
script.emit("NEW_SIMULATION")
script.emit("IMPORT", "METER", "STL", "wing.stl", clear=True)
script.emit("SOLVER_SET_AOA", 4.0)
script.emit("START_SOLVER")
print(script.render())  # validated ASCII script, ready for the solver

# The version is checked, and the check ASSERTS rather than prints:
# an example whose only claim is that something is refused goes green
# in CI the day the refusal stops firing, which is how this block came
# to promise a refusal it no longer made.
try:
    Script(version="26.0").emit("CAD_CREATE_BOX", frame=1, x=0.0, y=0.0, z=0.0,
                                len_x=1.0, len_y=1.0, len_z=1.0)
    raise AssertionError("26.000 has no CAD chapter; this must refuse")
except CommandNotInVersionError as error:
    print(error)  # the CAD primitives arrive at 26.100

The worked examples in examples/ take it from here to executed polars, campaign matrices, a static wing deflection, and a Campbell diagram. No example runs the coupled loop: it needs a licensed solver in the loop, and the rotary case is solver-blocked (reports/RPT-007). The capability status below says what the FSI subpackage does and does not claim.

Optional extras: [fsi] (aeroelastic coupling, PyNiteFEA), [geom] (probe-survey geometry gating, trimesh/rtree/scipy), [plot] (matplotlib for the plotting examples), and [manual] (pypdf), which is maintainer tooling rather than a user feature: it backs pyfs-manual and nothing in a run imports it.

Why this package

FlightStream is scripted through an ASCII command file, and the solver is under active development: the FlightStream team is responsive to user requests and works with intermediate hotfix builds that consolidate into stable releases. A fast-moving solver naturally means a scripting command set that evolves from version to version, faster than any single document can track. This package makes the FlightStream version an explicit input: every command it emits is validated against a per-version command database, and old versions are only ever added, never dropped, so campaigns stay reproducible across that evolution.

Every database entry carries exactly one piece of evidence: the manual page that documents the command, or, for the few the solver accepts and no manual edition describes, a committed probe report measuring that it does. Its status per version (documented, verified, broken) can only be promoted by citing a committed probe report from a licensed machine. Nothing is guessed; the honest gaps are reported as such.

What ships

• Command database with per-version evidence and a manual or probe-report citation on every entry, browsable offline via pyflightstream.help() (including a manual-coverage section) and as a generated docs site; the compatibility matrix carries the live counts.
• Validating script builder with curated helpers: phase ordering, didactic refusals at build time, entity labels (recipes can name frames, actuators, motions, and boundaries instead of raw indices), and a solver-setup provenance snapshot recording the effective value of every solver flag per run. A command a probe measured broken in the target version is refused too, because that one produces a complete run with wrong numbers rather than no run at all; the waiver that emits it anyway records the report and the reason in the manifest.
• Campaign workspace: an input-artifact library (references, solver presets, boundary groups, geometries, profiles, executables by build id), a run manifest as the single identity authority, output naming templates, campaign pre-flight with zero solver time, and resumable incremental sweeps.
• Runner and parsers: headless execution, anchor-based parsers for the solver outputs, and a pandas table layer (per-result tables, one wide row per run, whole-sweep DataFrame straight from the manifest).
• Run-matrix support as a first-class interface: read, convert, pre-flight, and run the pipe-delimited 15-column matrix format.
• Far-field probe surveys (planar grids, geometry gating, VTK/Tecplot writers, conservation ledgers on xarray) and an aeroelastic coupling subpackage (structural beam, coupled driver, replay harness).
• Architecture overview from the live module docstrings via pyflightstream.overview().
• Predictable surfaces: a declared-options registry (pyflightstream.options), one public exception catalog (pyflightstream.exceptions), test assertions with quantified reports (pyflightstream.testing), and the house conventions rendered by help().

Capability status

Not every subpackage carries the same weight of evidence, and until 2026-08-03 nothing said so: an independent review found the feature list above reading as one uniform claim, with the aeroelastic boundary stated only inside the code. The author's decision of 2026-08-03 is that the FSI and probe-survey paths are experimental behind an explicit boundary rather than release-supported, and this table is that boundary.

Experimental means the interface may change without the deprecation window of NFR-20, and that the evidence behind it is narrower than the supported rows: replaying archived fixtures shows the machine runs, not that its physics is right for a case nobody has measured.

Command-line tools

Supported FlightStream versions

"Supported" covered four different states, so it is now four named values (pyflightstream.SupportLevel), every one of them derived from the evidence rather than declared:

import pyflightstream

for row in pyflightstream.support_table():
    print(row.summary)

operational is the level that claims a user can get from geometry to a loads file, and it is checkable rather than asserted: it holds only when pyflightstream.support.minimal_workflow(version) builds, which a tier 1 test builds for every version reported at that level.

Not sure which one you have? Every install prints its release name and its build number when it starts, and the generated Which build do I have page maps that pair onto the identifier to pass. The release name alone does not identify a build.

Canonical identifiers use the YY.XXX scheme, the last digit indexing vendor hotfix builds, so 26.121 is hotfix build 1 of the 26.12 release. The vendor ships 26.120, 26.121 and 26.122 under the one release name "26.12", and both 26.100 and 26.101 under "26.1", so neither name selects a build and each is refused with its candidates named; pass the canonical identifier. A vendor name is unique only until the vendor ships the next build under it, which is why a script should not rely on one. The ordered list in src/pyflightstream/commands/_meta.yaml is the only ordering authority, and it orders releases, not support: 26.100 is newer than 26.000 and both sit below 26.120. Supported versions are only ever added, never dropped, which is why the February 2026 build entered as 26.100 and the May build it displaced was appended as 26.101 rather than either being renamed away. The compatibility matrix in the docs is generated from the database at build time.

What is each folder?

Development setup

Maintainers: several machine-specific environment variables locate local tooling and session state and are not in Git. A fresh clone must set them in .claude/settings.local.json; CLAUDE.md (Session protocol) is their single home, lists them, and states what each one does when unset. The count is deliberately not repeated here: it lived in two places and went stale in this one.

pip install -e .[dev,fsi,geom]
pre-commit install
pytest

Tier 1 (the pytest suite) runs anywhere. Tier 2 (command validity probes) and Tier 3 (physics regression) require a local FlightStream license and are documented in CONTRIBUTING.md, which also says which extras a full run needs and why two of them are left out on purpose. The docs build with properdocs build --strict.

License

MIT. Contributions must be original or MIT-compatible; code derived from the AGPL pyFlightscript package is not accepted. See CONTRIBUTING.md.