pyflightstream 0.2.0__tar.gz

pyflightstream-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geovana Neves
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyflightstream-0.2.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: pyflightstream
+Version: 0.2.0
+Summary: Version-aware, didactic Python driver for the FlightStream panel-method solver
+Author: Geovana Neves
+License: MIT
+Project-URL: Repository, https://github.com/nevesgeovana/pyflightstream
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pydantic
+Requires-Dist: pyyaml
+Requires-Dist: xarray
+Provides-Extra: plot
+Requires-Dist: matplotlib; extra == "plot"
+Provides-Extra: geom
+Requires-Dist: trimesh; extra == "geom"
+Requires-Dist: rtree; extra == "geom"
+Requires-Dist: scipy; extra == "geom"
+Provides-Extra: fsi
+Requires-Dist: PyNiteFEA>=3.0; extra == "fsi"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: mkdocs-material; extra == "dev"
+Requires-Dist: mkdocstrings[python]; extra == "dev"
+Requires-Dist: mkdocs-gen-files; extra == "dev"
+Requires-Dist: mkdocs-literate-nav; extra == "dev"
+Dynamic: license-file
+
+# pyflightstream
+
+Version-aware, didactic Python driver for the FlightStream panel-method solver.
+Successor of the author's legacy research scripts. MIT licensed.
+
+Status: pre-alpha, milestone M0 (repository skeleton). The package installs and
+imports, but no functionality ships yet. See the milestone plan below.
+
+## Why this package
+
+FlightStream is scripted through an ASCII command file whose commands change
+between solver versions, and not every change reaches the changelog. 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.
+
+## What is each folder?
+
+| Folder | Purpose in plain language |
+|---|---|
+| `src/pyflightstream/` | The package itself, one subpackage per pipeline stage |
+| `src/pyflightstream/commands/` | The command database: what exists in which FlightStream version, with manual page citations |
+| `tests/` | Tier 1 tests, runnable anywhere, no FlightStream needed |
+| `reports/` | Committed evidence from licensed machines: which commands actually work (compat) and physics regression results |
+| `docs/` | Documentation source (mkdocs) |
+| `examples/` | Runnable example scripts in percent format |
+| `.claude/skills/` | Maintenance procedures (version updates, command additions, QA runs, releases) |
+| `_private/` | Local only, never committed: FlightStream manuals and research geometry |
+
+## Supported FlightStream versions
+
+Planned at launch: 26.000, 26.100, 26.120 (canonical 26.XXX scheme; the last
+digit indexes vendor hotfix builds). The ordered list in
+`src/pyflightstream/commands/_meta.yaml` is the only ordering authority.
+
+## Development setup
+
+```
+pip install -e .[dev]
+pre-commit install
+pytest
+```
+
+Tier 2 (command validity probes) and Tier 3 (physics regression) require a
+local FlightStream license and are documented in CONTRIBUTING.md.
+
+## Milestones
+
+M0 skeleton (this) > M1 command database > M2 builder, runner, parser >
+M3 compat report > M4 physics cases > M5 docs and example > v0.1.0 (private).
+
+## License
+
+MIT. Contributions must be original or MIT-compatible; code derived from the
+AGPL pyFlightscript package is not accepted. See CONTRIBUTING.md.

pyflightstream-0.2.0/README.md

@@ -0,0 +1,55 @@
+# pyflightstream
+
+Version-aware, didactic Python driver for the FlightStream panel-method solver.
+Successor of the author's legacy research scripts. MIT licensed.
+
+Status: pre-alpha, milestone M0 (repository skeleton). The package installs and
+imports, but no functionality ships yet. See the milestone plan below.
+
+## Why this package
+
+FlightStream is scripted through an ASCII command file whose commands change
+between solver versions, and not every change reaches the changelog. 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.
+
+## What is each folder?
+
+| Folder | Purpose in plain language |
+|---|---|
+| `src/pyflightstream/` | The package itself, one subpackage per pipeline stage |
+| `src/pyflightstream/commands/` | The command database: what exists in which FlightStream version, with manual page citations |
+| `tests/` | Tier 1 tests, runnable anywhere, no FlightStream needed |
+| `reports/` | Committed evidence from licensed machines: which commands actually work (compat) and physics regression results |
+| `docs/` | Documentation source (mkdocs) |
+| `examples/` | Runnable example scripts in percent format |
+| `.claude/skills/` | Maintenance procedures (version updates, command additions, QA runs, releases) |
+| `_private/` | Local only, never committed: FlightStream manuals and research geometry |
+
+## Supported FlightStream versions
+
+Planned at launch: 26.000, 26.100, 26.120 (canonical 26.XXX scheme; the last
+digit indexes vendor hotfix builds). The ordered list in
+`src/pyflightstream/commands/_meta.yaml` is the only ordering authority.
+
+## Development setup
+
+```
+pip install -e .[dev]
+pre-commit install
+pytest
+```
+
+Tier 2 (command validity probes) and Tier 3 (physics regression) require a
+local FlightStream license and are documented in CONTRIBUTING.md.
+
+## Milestones
+
+M0 skeleton (this) > M1 command database > M2 builder, runner, parser >
+M3 compat report > M4 physics cases > M5 docs and example > v0.1.0 (private).
+
+## License
+
+MIT. Contributions must be original or MIT-compatible; code derived from the
+AGPL pyFlightscript package is not accepted. See CONTRIBUTING.md.

pyflightstream-0.2.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyflightstream"
+version = "0.2.0"
+description = "Version-aware, didactic Python driver for the FlightStream panel-method solver"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "Geovana Neves"}]
+requires-python = ">=3.11"
+# xarray confirmed as a runtime dependency by the author's far-field
+# extraction instruction of 2026-07-21 (PLN-006 closed): the farfield
+# ledgers live on labeled (station, r, psi) arrays.
+dependencies = [
+    "numpy",
+    "pandas",
+    "pydantic",
+    "pyyaml",
+    "xarray",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib"]
+# Geometry gate of the probe planner: containment culling and
+# distance-to-surface queries (license evidence reports/RPT-003).
+geom = ["trimesh", "rtree", "scipy"]
+# FSI structural coupling (M6, DLV-007). PyNiteFEA is MIT; license
+# evidence: reports/RPT-002_pynitefea-license_2026-07-21.md (NFR-02).
+fsi = ["PyNiteFEA>=3.0"]
+dev = [
+    "pytest",
+    "ruff",
+    "pre-commit",
+    "mkdocs-material",
+    "mkdocstrings[python]",
+    "mkdocs-gen-files",
+    "mkdocs-literate-nav",
+]
+
+[project.scripts]
+pyfs-qa = "pyflightstream.qa.cli:main"
+pyfs-fsi = "pyflightstream.fsi.cli:main"
+
+[project.urls]
+Repository = "https://github.com/nevesgeovana/pyflightstream"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"pyflightstream.commands" = ["*.yaml"]
+"pyflightstream.qa" = ["references/*.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "needs_flightstream: requires a local FlightStream installation and license",
+    "validity: tier 2 per-command probe tests",
+    "physics: tier 3 physics regression matrix (slow)",
+]
+addopts = "-m 'not needs_flightstream'"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "N", "D"]
+# N803/N806 exempted so aerodynamic symbols (CL, CDi, J, alpha_deg) keep
+# their standard names (SAD Section 12).
+ignore = ["N803", "N806"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]

pyflightstream-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyflightstream-0.2.0/src/pyflightstream/__init__.py

@@ -0,0 +1,27 @@
+"""pyflightstream: version-aware, didactic Python driver for FlightStream.
+
+The package automates the FlightStream panel-method solver through its ASCII
+scripting interface. The FlightStream version is an explicit input: every
+command emitted is validated against the per-version command database in
+``pyflightstream.commands``.
+
+Pipeline layers, dependencies flowing strictly downward:
+
+- ``versions``: canonical 26.XXX version identifiers and ordering.
+- ``commands``: the command database and per-version registry.
+- ``script``: the validating ASCII script builder.
+- ``results``: anchor-based parsers for solver output files.
+- ``cases``: simulation and campaign definitions.
+- ``run`` and ``files``: execution, run manifest, managed file layout.
+- ``post``: results into engineering data (sweep assembly, PLTET, exports).
+- ``qa``: probe harness and physics regression tooling.
+- ``fsi``: seam for the future fluid-structure interaction coupling.
+
+Milestone M0: skeleton only; functionality arrives from milestone M1 on.
+"""
+
+__version__ = "0.0.1.dev0"
+
+from pyflightstream.reference import help  # noqa: E402
+
+__all__ = ["__version__", "help"]

pyflightstream-0.2.0/src/pyflightstream/cases/__init__.py

@@ -0,0 +1,332 @@
+"""Simulation and campaign definitions.
+
+Pipeline role: describes what to run. A :class:`SimCase` (identified
+by ``sim_id``) is one solver configuration with its sweep; a
+:class:`Campaign` groups cases with the FlightStream version and the
+executable path, both required and explicit: nothing is read from
+environment variables or guessed (SAD Section 5). Native persistence
+is ``campaign.toml``; the legacy pipe-delimited ``matriz.fs`` matrix
+of the predecessor scripts will be read unchanged, forever, by the
+legacy reader (FR-10, next step of milestone M2).
+
+Script recipes are explicitly imported functions satisfying the
+:class:`ScriptRecipe` protocol: ``build(case, script) -> None``. The
+campaign loop specializes the case per sweep point (filling
+:attr:`SimCase.point`) and the recipe translates it into script
+emissions, usually through the curated helpers. Recipe references are
+``"package.module:function"`` strings, replacing the historical
+import-by-number system (PP-7, FR-12).
+"""
+
+from __future__ import annotations
+
+import tomllib
+from collections.abc import Callable, Iterator
+from importlib import import_module
+from pathlib import Path
+from typing import Literal, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from pyflightstream.script import Script
+from pyflightstream.versions import resolve
+
+_TAG_PREFIXES = (("alpha", "a"), ("beta", "b"), ("advance_ratio", "j"))
+
+
+@runtime_checkable
+class ScriptRecipe(Protocol):
+    """A function that turns one case point into script emissions.
+
+    Implementations receive the per-point specialized case (the
+    campaign loop fills :attr:`SimCase.point` and stages the geometry)
+    and an empty :class:`~pyflightstream.script.Script` bound to the
+    campaign's FlightStream version; they emit the whole script,
+    usually through the curated helpers. Output files must use paths
+    relative to the execution directory, so the collected evidence
+    stays inside the managed simulation folder.
+    """
+
+    def __call__(self, case: SimCase, script: Script) -> None:
+        """Emit the complete script for one case point."""
+        ...
+
+
+class SweepAxis(BaseModel):
+    """The sweep of one case: which axis varies and its values.
+
+    Attributes
+    ----------
+    type : str
+        ``alpha`` (angle of attack, deg), ``beta`` (side slip, deg),
+        ``alpha_beta`` (paired values), or ``advance_ratio``
+        (propeller advance ratio J, dimensionless).
+    values : list
+        Axis values; for ``alpha_beta`` each entry is an
+        ``[alpha, beta]`` pair in deg.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["alpha", "beta", "alpha_beta", "advance_ratio"]
+    values: list[float] | list[tuple[float, float]]
+
+    @model_validator(mode="after")
+    def _values_match_the_axis_type(self) -> SweepAxis:
+        pairs = self.type == "alpha_beta"
+        for value in self.values:
+            if pairs != isinstance(value, tuple):
+                expected = "[alpha, beta] pairs" if pairs else "scalar values"
+                raise ValueError(f"a {self.type} sweep takes {expected}, got {value!r}")
+        return self
+
+    def points(self) -> Iterator[dict[str, float]]:
+        """Iterate the sweep as named point coordinates.
+
+        Yields
+        ------
+        dict of str to float
+            One mapping per point, keyed ``alpha``, ``beta``, or
+            ``advance_ratio`` (both keys for ``alpha_beta``).
+        """
+        for value in self.values:
+            if self.type == "alpha_beta":
+                alpha, beta = value
+                yield {"alpha": alpha, "beta": beta}
+            else:
+                yield {self.type: value}
+
+
+def point_tag(point: dict[str, float]) -> str:
+    """Return the stable file-name tag of one sweep point.
+
+    The tag encodes the point coordinates in a fixed axis order with
+    signed fixed-width values, for example ``a+02.0_b+00.0``; it names
+    the generated script and ends the ``run_id``.
+
+    Parameters
+    ----------
+    point : dict of str to float
+        Point coordinates as produced by :meth:`SweepAxis.points`.
+    """
+    parts = [f"{prefix}{point[axis]:+05.1f}" for axis, prefix in _TAG_PREFIXES if axis in point]
+    if not parts:
+        raise ValueError(f"point {point!r} has no known axis (alpha, beta, advance_ratio)")
+    return "_".join(parts)
+
+
+class ReferenceData(BaseModel):
+    """Reference quantities for coefficient normalization.
+
+    Attributes
+    ----------
+    area : float
+        Reference area S_ref in simulation length units squared.
+    length : float
+        Reference length L_ref in simulation length units.
+    velocity : float, optional
+        Reference velocity in m/s; None lets the recipe default it to
+        the free-stream velocity (steady runs) or a characteristic
+        velocity such as the rotor tip speed (SRC-003 p.201).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    area: float
+    length: float
+    velocity: float | None = None
+
+
+class SolverSettings(BaseModel):
+    """Solver runtime settings of one case.
+
+    Field names match the keyword arguments of
+    :func:`pyflightstream.script.helpers.solver_settings`, so recipes
+    can forward them directly.
+
+    Attributes
+    ----------
+    iterations : int
+        Solver iteration limit.
+    convergence : float
+        Residual threshold declaring convergence (SRC-003 p.200).
+    forced_iterations : bool, optional
+        Run the full iteration count regardless of convergence.
+    boundary_layer : str, optional
+        ``LAMINAR``, ``TRANSITIONAL``, or ``TURBULENT``.
+    viscous_coupling : bool, optional
+        Couple the boundary layer model to the potential solution.
+    max_threads : int, optional
+        Parallel core count.
+    timeout_s : float, optional
+        Wall-clock limit for one point's solver process; enforced by
+        the executor, not by FlightStream.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    iterations: int = 500
+    convergence: float = 1e-5
+    forced_iterations: bool | None = None
+    boundary_layer: str | None = None
+    viscous_coupling: bool | None = None
+    max_threads: int | None = None
+    timeout_s: float | None = None
+
+
+class SimCase(BaseModel):
+    """One solver configuration with its sweep (SAD Section 5).
+
+    Attributes
+    ----------
+    sim_id : str
+        Case identity; also names the managed folder
+        ``sims/sim_<sim_id>``.
+    aircraft : str
+        Aircraft or configuration name.
+    description : str
+        Free-text description.
+    reynolds : float, optional
+        Chord Reynolds number of the condition.
+    mach : float, optional
+        Free-stream Mach number.
+    velocity : float, optional
+        Free-stream velocity in m/s.
+    geometry : str, optional
+        Path of the simulation (.fsm) file; the campaign loop stages
+        it into ``inputs/`` and rewrites this field to the staged
+        copy, so recipes OPEN exactly what the manifest hashed.
+    sweep : SweepAxis
+        The sweep of this case.
+    reference : ReferenceData, optional
+        Coefficient normalization references.
+    solver : SolverSettings
+        Runtime settings; defaults apply when omitted.
+    recipe : str
+        Script recipe reference, ``"package.module:function"``, or a
+        name registered with the campaign loop.
+    variables : dict
+        Free per-case variables for the recipe (strings, numbers, or
+        booleans), for example a symmetry declaration.
+    outputs : list of str
+        Output files the recipe's script exports, relative to the
+        execution directory; the loop collects them into ``raw/`` and
+        a missing one marks the point FAILED_INCOMPLETE_OUTPUT.
+    point : dict of str to float
+        The current sweep point; filled by the campaign loop before
+        the recipe builds, empty on the authored case.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    sim_id: str
+    aircraft: str
+    description: str = ""
+    reynolds: float | None = None
+    mach: float | None = None
+    velocity: float | None = None
+    geometry: str | None = None
+    sweep: SweepAxis
+    reference: ReferenceData | None = None
+    solver: SolverSettings = Field(default_factory=SolverSettings)
+    recipe: str
+    variables: dict[str, str | float | int | bool] = Field(default_factory=dict)
+    outputs: list[str] = Field(default_factory=list)
+    point: dict[str, float] = Field(default_factory=dict)
+
+
+class Campaign(BaseModel):
+    """A named group of cases bound to one FlightStream installation.
+
+    Attributes
+    ----------
+    name : str
+        Campaign name; prefixes every ``run_id``.
+    fs_version : str
+        FlightStream version, canonical or alias; validated against
+        the registered versions at load time, resolved to canonical in
+        the manifest.
+    fs_exe : str
+        Explicit path of the FlightStream executable; existence is
+        checked by the executor at construction, not here, so a
+        campaign file can be authored away from the licensed machine.
+    sims : list of SimCase
+        The cases of the campaign.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    fs_version: str
+    fs_exe: str
+    sims: list[SimCase]
+
+    @field_validator("fs_version")
+    @classmethod
+    def _version_is_registered(cls, value: str) -> str:
+        resolve(value)
+        return value
+
+
+def load_campaign(path: str | Path) -> Campaign:
+    """Load and validate a ``campaign.toml`` file.
+
+    The file holds one ``[campaign]`` table (name, fs_version,
+    fs_exe) and one ``[[sim]]`` array entry per case, as in SAD
+    Section 5.
+
+    Parameters
+    ----------
+    path : str or Path
+        Location of the TOML file.
+
+    Returns
+    -------
+    Campaign
+        Validated campaign; version aliases are checked against the
+        registered versions immediately, so a typo fails at load
+        time, not at the first point.
+    """
+    with open(path, "rb") as handle:
+        data = tomllib.load(handle)
+    if "campaign" not in data:
+        raise ValueError(
+            f"{path} has no [campaign] table; campaign.toml needs [campaign] with "
+            "name, fs_version, and fs_exe, plus one [[sim]] entry per case"
+        )
+    return Campaign(**data["campaign"], sims=data.get("sim", []))
+
+
+def resolve_recipe(reference: str) -> Callable[[SimCase, Script], None]:
+    """Import the recipe function a reference string names.
+
+    Parameters
+    ----------
+    reference : str
+        ``"package.module:function"``; the module must be importable
+        and the attribute callable. Explicit references replace the
+        historical import-by-number system (PP-7, FR-12).
+
+    Returns
+    -------
+    callable
+        The recipe function, satisfying :class:`ScriptRecipe`.
+    """
+    module_name, separator, function_name = reference.partition(":")
+    if not separator or not module_name or not function_name:
+        raise ValueError(
+            f"recipe reference {reference!r} is not of the form 'package.module:function'"
+        )
+    try:
+        module = import_module(module_name)
+    except ImportError as error:
+        raise ValueError(
+            f"recipe module {module_name!r} cannot be imported: {error}. Recipes are "
+            "explicitly imported functions; check the module path and the environment."
+        ) from error
+    recipe = getattr(module, function_name, None)
+    if not callable(recipe):
+        raise ValueError(
+            f"recipe {reference!r} does not name a callable in {module_name!r}; found {recipe!r}"
+        )
+    return recipe