pyflightstream

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

Documentation

nevesgeovana.github.io/pyflightstream

New here? Start with Getting started, which walks a first workspace file by file and says what each of the four kinds of artifact answers. Then The workspace and the workflow is the reference chapter, and Which build do I have answers the question a version-aware driver exists for.

Every example on those pages is compared against an artifact this repository ships, most of them under tests/tier3_licensed/, by a test on every commit, so a page cannot quietly stop being true.

Status: v0.16.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.

v0.16.0 is the release the reference workspace asked for. The additions came from running 0.15.0 at work and reading what came back, and two of them are defects found while measuring for the others. A surface-section distribution is created AFTER the solver is initialised, which is where the recorded reference scripts put it and which is why fifty sections said nothing; a steady row now CREATES the probe points it exports, instead of asking the solver to export something nobody made; a probe entry prescribes a rectangular or a circular plane, point by point, or cites a points file the user wrote; and [probes] became [[probes]], a list of tables, so one artifact can probe several frames.

What a campaign WRITES moved with it. A simulation's collected outputs live under sims/<sim>/datapoints/DP-<point>/, the per-polar tables under post/<matrix>/polars/, and the flow-field samples under post/<matrix>/probes/ whatever the run type was. Each polar and group also gets one derived file, SUPER-...csv, whose columns are a superset of everything the workspace knows about that simulation: if you have to open a second file to know something about it, that file failed.

Two new answers a study wants before it is run and after. pyfs-matrix plan --cost tables what each POINT will cost: mesh size, trailing edges marked, farfield layers, viscous coupling, run type, time steps, processors, an expected time, and the number of recorded runs that estimate was fitted from. The table says under every printing that the time is an extrapolation from this workspace's own recorded wall times and not a measurement, and a point with no comparable recorded run gets no number at all. And a probe table now says WHERE each sample is, with the frame it is measured in, which an unsteady export never stated at all.

A swept row now runs and is judged end to end. Each point collects its outputs into its own folder, sims/<sim>/datapoints/DP-<point>/, named by the same point tag that ends the run id and names the generated script. Until this release every point of a row wrote into one shared folder, so from the second point onward the standard assessor found two files that both read as loads tables and refused rather than guess between them. Name your outputs per point, as before: two points of one row still may not share a file name, because the per-point products are named after it and would collide there even though the folders no longer do. A workspace recorded under the older layout is read exactly as before.

What changes for you at v0.16.0. This is the most breaking release of the set, and the break is first: [probes] IS NOW [[probes]], a list of tables, and the old spelling is REFUSED BY NAME, so every 0.15.0 artifact that declares probe lines must be edited. That is a recorded decision rather than an accident. Beside it: the five names the 0.14.0 polar rename deprecated are gone; a simulation's collected outputs are under sims/<sim>/datapoints/DP-<point>/, one folder per point, and a workspace holding either older folder is still read; the per-polar tables moved to post/<matrix>/polars/ and are named by the point convention with the swept variable written literally as sweep; and sweep.csv is gone in favour of campaign_sweep.csv, which it duplicated byte for byte.

What changes for you at v0.15.0. The run matrix LOSES A COLUMN: SWEEP_TYPE is gone, because a sweep is applied to a variable that DEFINES the flight condition and the FLIGHT_CONDITION cell says which by carrying the word sweep where that key's value would be. Run pyfs-matrix upgrade <path> --in-place, which folds the cell and DOES NOT RENAME A RUN: a held angle is carried at every point, so the point tags that end every run_id in your manifests are the ones the converted file plans under, and a resume after the upgrade finds its records. The one row it refuses to convert is one that sweeps BOTH angles, which is one row per sideslip and each needs a POL of its own. CLOCK_MOTION is now REQUIRED on a row that states a MOTIONS list, naming the rotor that owns the time step; the flat pre-0.15.0 form is exempt. The airframe and blades family SELECTORS are REFUSED since 0.15.0, not warned about: declare the set in your reference's [aliases] table and cite it by name, because those two decided what a blade IS from a pattern over the family name and a mesh spelled another way was guessed wrong in silence. An alias of the same name is read FIRST and keeps its own meaning, so a reference that already declares airframe is untouched. New: --ignore-missing-families false on plan and run turns a family the opened mesh does not carry from a skip into a refusal, for a run against the one geometry you believe carries everything.

What changes for you, and what you must do. v0.13.0 changes no column of the run-matrix file. Two inputs that used to plan are refused at plan time now, each naming the cell: a row carrying a key its run type does not register (a misspelt key planned READY and reached the solver as nothing), and a pproc artifact whose [groups] table is keyed by a word or whose groups cite a boundary name the opened geometry does not carry. Python 3.11 leaves the supported window: the floor follows SPEC 0, the scientific-python schedule, computed on 2026-09-09 as Python 3.12, numpy 2.2 and pandas 2.3, and the window now moves by a published rule rather than by choice. The hand-built physics runner is gone: run_physics, run_drift and the four build_phy*_script builders are removed, and pyfs-qa physics --workspace <root> and pyfs-qa drift --workspace <root> read the physics cases as rows of a campaign workspace; an import of a removed name says so and names the replacement. Anything you wrote against runs.json or the campaign products meets three moves: the manifest key broken_commands is waived_commands and the schema stamp is pyfs-manifest/3 (the old key is still read, and goes when no recorded workspace carries it rather than on a stated release); plan.json, campaign_sweep.csv and the product tables live under post/<matrix stem>/, one folder per matrix; and a registered post stage is called with a third keyword, matrix_stem. sweep_editions is manual_editions and propose_type takes its two strings by keyword; the old spellings warn and name the release that removes them. A simulation folder has three managed subfolders, since parsed/ was never written to; an empty one left by an earlier release is left alone. At v0.14.0 one artifact key is renamed: [products] her_polar_format is custom_polar_format, and the four Python names HerPolarTable, her_polar_file_name, write_her_polar_format and read_her_polar_format are spelled custom; the old spellings were read and warned until 0.16.0, WHICH REMOVES THEM. The format itself is untouched: only the spelling that named a person was ever deprecated.

What it adds. An unsteady row may say when its exports begin, EXPORT_UNSTEADY_AFTER_REV or EXPORT_UNSTEADY_AFTER_ITER, and the run registers the two solver actions that make the solver export from that step on, measured on 26.123. The products stage writes a PROV-JSON provenance document per point, every reduction of an unsteady row (the time average over the window the row states, the phase-locked passages, the per-blade split), and the polar tables in the custom polar format when the pproc artifact asks for it. The geometry library may hold one folder per geometry beside the flat layout, pyfs-workspace migrate-geometries moves a library into it, and pyfs-workspace archive <root> <sim_id> zips one recorded simulation. Every command-line option states what it reads, the run record says how the solver was called (executor, export_window, the waived commands by their name), and the whole test suite is organized by tier, with the licensed tier a campaign workspace of seven run matrices whose goldens are rendered offline on every commit.

v0.12.0 changed no column of the run-matrix file and no cell already in one. It added two ways to say what you were already saying. A setup artifact may carry a [flight_condition] table holding the fluid pins (RHOkgm3, MUPas, ASMPS, TK, PPA), so a thirteen-point polar states its campaign's constants once instead of thirteen times; a row that states a pin still overrides the setup's, and the resolved state is the same state either way, which a test holds to the rendered script BYTE FOR BYTE. And an unsteady run that meshes nothing turning may state its clock as DELTA_THETA and REVOLUTIONS, resolved against the rotor speed whose azimuth the step measures, where before only the seconds and the step count were accepted. The reproduction workspace of the reference campaign needs both, which is why that release existed.

Two derived numbers moved with it, and a row already written felt them. A rotor speed derived from ADVANCE_RATIO is emitted at four decimals, the reference precision: 473.1723 rev/min where the unrounded derivation gives 473.17227304. And the default loads assessor judged a point's OWN declared outputs, so a two-point sweep whose points name their own tables is judged where it used to be refused as ambiguous. Re-baseline against v0.12.0 rather than comparing its tables with v0.11.0's.

v0.11.0 changed the run-matrix FILE FORMAT, and one command moved a workspace. The ENTRY column is now PPROC and names the post-processing artifact, the FS_SCRIPT column is gone and a LEGACY row carries its recipe code in its cell, and the GEOMETRY cell names the file with its extension. Run pyfs-matrix upgrade matriz.fs --in-place --inputs inputs once in the workspace: it rewrites the matrix, moves the groups library to inputs/pproc/ and strips the four rotor facts from the reference artifact. What you get is the study stated once, in the workspace: the campaign is named after its directory, the post-processing artifact says which exports, sections, plots, probes and products every point leaves, the products are CSV tables the run writes itself (pyfs-matrix post rewrites them with no solver), the boundary order of a geometry is read from the file (pyfs-matrix inventory), a row may state several rotors, and every point opens its geometry through a link rather than a copy. The reproduction of the reference campaign, script by script and product by product, is the exit condition of GOAL-011 and is what that release was built against.

v0.10.1 changed no column of the run-matrix file and no cell you had already written. What it changed is what one cell MEANS.

A rotor row's MOVING_BOUNDARIES used to cite boundaries by their POSITION in one geometry's boundary order. Those positions were right for the file they were written against and named different surfaces in any file that ordered them differently, and nothing said so. Write the names now, or the FAMILY they belong to, and the package reads the geometry the row opens and resolves them:

MOVING_BOUNDARIES: Blade,S

One cell, and it is right for a three-boundary sector and an eight-boundary wheel alike. Positions still work and now warn, naming the surfaces they actually selected, so nothing you have written stops running.

And this patch carries a third run type, unsteady, an unsteady run with nothing turning. It is a new capability under a patch number, by an explicit exception, and it is named here because a patch number will not carry that news on its own. It asks nothing of you: no existing row changes. docs/workspace-and-workflows.md describes it.

What v0.10.0 asked of you, kept here because a reader may be arriving from 0.9.x. v0.10.0 changes no column of the run-matrix file, so no conversion is needed. Two things still want a look before you re-run anything.

Your solver preset now reaches the script, and that is the SILENT half. A preset key naming a real setting used to be honoured only where the model already defaulted to it: a preset asking for SUBSONIC_PRANDTL_GLAUERT ran INCOMPRESSIBLE and said nothing. Twelve settings and eleven of the solver's own key spellings now reach the emitted script. Nothing refuses and nothing warns; the NUMBERS move. On the reference campaign the axial force coefficient moved about one percent. If your preset states anything the solver was not already defaulting to, re-baseline before you compare against an older run.

The loud half is smaller: a preset key this package cannot emit at all used to be dropped with a warning and is now refused, naming the key and listing what applies. The remedy is usually one line in the preset file, and for one key it is a line in the row instead, which the refusal says.

Five names are now the package's inside VAR_NAMES_VALUES: ADVANCE_RATIO, RPM_SIGN, DELTA_THETA, REVOLUTIONS and LOG_OUTPUT. The match is on the exact key. If a cell of yours already spells one, rename yours or adopt the meaning; a row spelling ADVANCE_RATIO or RPM_SIGN beside an existing RPM is REFUSED, because that states the rotor speed twice.

If you are coming from v0.8.x you still have the older job. If you have a run matrix written then, v0.9.0 changed its FILE FORMAT and you must convert it. The RE and MACH columns are gone, replaced by one mandatory FLIGHT_CONDITION cell. A file written under either older layout is recognised and refused rather than misread, so nothing runs silently wrong; run this on it:

pyfs-matrix upgrade your_matrix.fs --in-place

Then read the next sentence before you re-run a campaign. The conversion is lossless as a FILE, every value moving across verbatim, and it is not neutral as a RESULT. Under v0.8.x the RE column was recorded metadata that reached no emitted line; from v0.9.0 REmi is a constraint that solves for density, so every upgraded row emits a fluid state it never emitted before and your numbers will move. How far they move is not something this repository can tell you, because the row previously emitted NO fluid state at all and what the solver assumed instead is a question about the solver. What is measured, on this repository's own fixture, is the state your row will now be run at: one row solves at 1.3319 kg/m3, 8.7 percent above sea level. To keep the previous behaviour, state the condition without REmi. docs/flight-conditions.md is the whole grammar, the units, and the migration in full.

The earlier upgrade action still applies if you are coming from before v0.8.1: three names inside the free VAR_NAMES_VALUES cell of a run matrix are the package's: GEOMETRY, SYMMETRY and PERIODIC_COPIES. If a cell of yours already spells one of them, the package reads it, so rename your key or stage the file the id names. The match is on the exact key, so a cell spelling it SYMMETRY_TYPE is untouched, and a row that names none of the three renders the script it always did.

What v0.8.1 fixed, and it is why a patch followed v0.8.0 by two days. A run matrix had no way to name a geometry at all, so a workflow built a script with no OPEN in it: the solver solved whatever it already had in memory, and reported numbers with nothing said. A row names its geometry now, and declares the symmetry a periodic sector needs, which was fixed at NONE so a sector ran as a one-bladed rotor and converged. Separately, pyfs-matrix run could not run at all under its own documented default: --workspace defaults to "." and every path was then spelled from your directory while the solver resolved it from the run's.

Everything each earlier release broke or added is described under its own heading in CHANGELOG.md, which carries the reasoning, the measurements and the rejected alternatives behind every entry. The word "unchanged" used to stand here about v0.8.0's four breaking changes, and a review pointed out that a reader cannot check it: the four were never enumerated, and v0.9.0 has just changed the same file format again.

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 was solver-blocked on 26.120 and 26.121 (reports/RPT-007), which reports/RPT-025 measures fixed in 26.122. The capability status below says what the FSI subpackage does and does not claim.

Optional extras: [fsi] (aeroelastic coupling, PyNiteFEA), [geom] (the SPATIAL INDEX behind probe-survey geometry gating, rtree and scipy; the mesh reader itself, trimesh, left this extra and is a runtime dependency since v0.8.0), [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. Every status that rests on a RUN (verified, broken, and a removed the solver refused) can only be promoted by citing a committed probe report from a licensed machine; a removed read off an edition is a hand-written row carrying a note and a page. 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, upgrade, convert, pre-flight, and run the pipe-delimited 13-column matrix format. Each row states its whole flow condition in one mandatory FLIGHT_CONDITION cell, and WORKFLOW names the run type the package builds for that row. A matrix written under any older layout is RECOGNISED and refused naming its converter: pyfs-matrix upgrade <path> --in-place.
• 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 design 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 reuses a release name across builds, so a release name may name more than one, and the families it has produced are not all alike: one is a release with its hotfixes, the other is two separate releases that happen to share a name. Which builds sit in either is a fact about the registry rather than about this page, so it is not written here; the refusal enumerates them from the registry and the generated build page carries the tally. 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: no tracked file here reads a named environment variable to configure this package, and a fresh clone is owed no list of them. The wording is careful and the earlier draft was not: the run layer does hand the AMBIENT environment to the solver subprocess, because the solver's own licence server address and installation variables live there, and a sentence saying this repository reads nothing at all would send a maintainer hunting a licence failure that is not a bug. What no tracked file does is read a NAMED variable to decide how this package behaves. The licensed solver is located by a required argument that is never guessed, --fs-exe on the quality-assurance command line; a run matrix locates it instead through its workspace's own executables table. An earlier version of this paragraph said a few machine-specific variables located the solver and its manuals for the licensed tiers, and pointed at a file that stopped being published. Both halves were wrong, and the paragraph shipped inside the package metadata, so it reached every reader of the published page.

The contributor rules a clone does need are the numbered hard invariants in CONTRIBUTING.md.

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.