pyflightstream 0.44.0__tar.gz → 0.45.0__tar.gz

pyflightstream-0.45.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include tools/check_shipped_surface.py
+include tools/shipped_surface.conf

{pyflightstream-0.44.0/src/pyflightstream.egg-info → pyflightstream-0.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyflightstream
-Version: 0.44.0
+Version: 0.45.0
 Summary: Version-aware, didactic Python driver for the FlightStream panel-method solver
 Author: Geovana Neves
 License: MIT

{pyflightstream-0.44.0 → pyflightstream-0.45.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyflightstream"
-version = "0.44.0"
+version = "0.45.0"
 description = "Version-aware, didactic Python driver for the FlightStream panel-method solver"
 readme = "README.md"
 license = {text = "MIT"}
@@ -170,10 +170,6 @@ Issues = "https://github.com/nevesgeovana/pyflightstream/issues"
 [tool.setuptools.packages.find]
 where = ["src"]
 
-# Keep the artifact scanner and its policy available with the distribution.
-[tool.setuptools.data-files]
-"share/pyflightstream/tools" = ["tools/check_shipped_surface.py", "tools/shipped_surface.conf"]
-
 [tool.setuptools.package-data]
 "pyflightstream.commands" = ["*.yaml"]
 "pyflightstream.qa" = ["references/*.yaml", "references/pressure-drag/*.yaml"]

{pyflightstream-0.44.0 → pyflightstream-0.45.0}/src/pyflightstream/_deprecations.py

@@ -658,16 +658,6 @@ INFLOW_STATION_HARMONICS = DeprecatedFunction(
     advice="use pyflightstream.post.inflow_tools.InflowStationHarmonics",
 )
 
-#: ``polar_row`` called without ``beta_deg`` keeps zero sideslip and warns; from
-#: the removal version the argument is required.
-POLAR_ROW_OMITTED_BETA = DeprecatedFunction(
-    function="pyflightstream.post.polar.polar_row called without beta_deg",
-    deprecated_since="0.43.0",
-    removal_version="0.45.0",
-    advice="pass beta_deg explicitly; zero sideslip is used until then",
-)
-
-
 MATRIX_REFINE = DeprecatedFunction(
     function="pyfs-matrix refine",
     deprecated_since="0.40.0",
@@ -706,6 +696,5 @@ DEPRECATIONS: tuple[Deprecation, ...] = (
     PLAN_MATRIX_FS_VERSION,
     RUN_MATRIX_FS_VERSION,
     INFLOW_STATION_HARMONICS,
-    POLAR_ROW_OMITTED_BETA,
     *MATRIX_GEOMETRY_ALIASES,
 )

{pyflightstream-0.44.0 → pyflightstream-0.45.0}/src/pyflightstream/cases/_farfield_spec.py

@@ -1,4 +1,4 @@
-"""The ``[farfield]`` table of the pproc artifact and the lattice shape of ``[[probes]]``.
+"""The ``[[farfields]]`` entries of the pproc artifact and the lattice shape of ``[[probes]]``.
 
 Pipeline role: the input model of the far-field family (FR-454) and of the
 survey-lattice probe shape (FR-1072), validated at load with
@@ -12,9 +12,11 @@ states none leaves the geometry to the plan's reuse rule (FR-1042, FR-455).
 
 from __future__ import annotations
 
-from typing import Annotated, Literal
+import json
+import re
+from typing import Annotated, Any, Literal
 
-from pydantic import BaseModel, BeforeValidator, ConfigDict, Field, model_validator
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field, ValidationError, model_validator
 
 from pyflightstream.probes.lattice import ProbeLattice, build_lattice
 
@@ -29,7 +31,7 @@ __all__ = [
 ]
 
 #: The three accepted Trefftz variants.
-TREFFTZ_VARIANTS: tuple[str, ...] = ("sections", "wake", "plane")
+TREFFTZ_VARIANTS: tuple[str, ...] = ("sections", "wake", "plane", "power")
 #: The six balances of FR-479, in the order the ledgers table writes them.
 BALANCES: tuple[str, ...] = (
     "mass",
@@ -39,6 +41,10 @@ BALANCES: tuple[str, ...] = (
     "in_plane_moment",
     "crossflow_energy",
 )
+#: The balance names a ``balances`` key accepts; a test pins it to :data:`BALANCES`.
+BalanceName = Literal[
+    "mass", "axial", "transverse", "torque", "in_plane_moment", "crossflow_energy"
+]
 #: The defaults of FR-1039 that a table may leave unstated:
 #: the plan's station count per side, the plane's distance behind the
 #: families and, for the wing plane, its half extents and spacing, all in BREF.
@@ -80,7 +86,7 @@ def _unique(words: list[str], what: str) -> list[str]:
 class LatticeShape(BaseModel):
     """A survey lattice, by its rotor or its frame and the ``build_lattice`` parameters.
 
-    The keys of ``[farfield.ledgers]`` geometry and of one entry of a
+    The keys of ``[[farfields]]`` lattice geometry and of one entry of a
     ``[[probes]]`` entry's ``lattices`` (FR-1072): ``rotor`` names the rotor
     whose hub frame and tip radius place the lattice, or ``frame`` and
     ``tip_radius_m`` place a lattice that belongs to no rotor; the rest are the
@@ -164,11 +170,13 @@ class LatticeShape(BaseModel):
         stated = {
             key: getattr(self, key) for key in _LATTICE_KEYS if getattr(self, key) is not None
         }
+        if self.lateral_radius is None:
+            stated["lateral_radius"] = max(2.5, self.r_outer or 2.5)
         return build_lattice(tip_radius=tip_radius, **stated)
 
 
 class TrefftzSpec(BaseModel):
-    """The ``[farfield.trefftz]`` sub-table: the Trefftz variants and their geometry (FR-454).
+    """The internal translation of ``[[farfields]]`` Trefftz variants and geometry (FR-454).
 
     Attributes
     ----------
@@ -190,7 +198,7 @@ class TrefftzSpec(BaseModel):
     model_config = ConfigDict(extra="forbid", allow_inf_nan=False)
 
     variant: Annotated[
-        list[Literal["sections", "wake", "plane"]], BeforeValidator(_one_or_list)
+        list[Literal["sections", "wake", "plane", "power"]], BeforeValidator(_one_or_list)
     ] = Field(
         min_length=1,
         description=(
@@ -226,7 +234,7 @@ class TrefftzSpec(BaseModel):
 
     @model_validator(mode="after")
     def _each_variant_once(self) -> TrefftzSpec:
-        _unique(list(self.variant), "[farfield.trefftz] variant")
+        _unique(list(self.variant), "Trefftz variant")
         return self
 
     @property
@@ -247,7 +255,7 @@ class TrefftzSpec(BaseModel):
 
 
 class LedgersSpec(LatticeShape):
-    """The ``[farfield.ledgers]`` sub-table: the balances and their survey lattice (FR-38, FR-454).
+    """The internal translation of ``[[farfields]]`` balances and lattice (FR-38, FR-454).
 
     Attributes
     ----------
@@ -258,11 +266,8 @@ class LedgersSpec(LatticeShape):
         the lattice's azimuth count.
     """
 
-    balances: list[
-        Literal["mass", "axial", "transverse", "torque", "in_plane_moment", "crossflow_energy"]
-    ] = Field(
+    balances: list[BalanceName] = Field(
         default_factory=lambda: list(BALANCES),  # type: ignore[arg-type]
-        min_length=1,
         description="The balances written: any of the six, all six by default.",
     )
     m_max: int = Field(
@@ -271,7 +276,7 @@ class LedgersSpec(LatticeShape):
 
     @model_validator(mode="after")
     def _the_orders_fit_the_azimuths(self) -> LedgersSpec:
-        _unique(list(self.balances), "[farfield.ledgers] balances")
+        _unique(list(self.balances), "balances")
         n_psi = self.build(1.0).n_psi
         if 2 * self.m_max >= n_psi:
             raise ValueError(
@@ -288,37 +293,224 @@ def _family_selection(value: object) -> object:
 
 
 class FarfieldSpec(BaseModel):
-    """The ``[farfield]`` table: what the far field is computed over, and how (FR-454).
+    """One named analysis in ``[[farfields]]``; geometry keys belong to their variant.
+
+    ``sections`` requires families and accepts a station count. ``wake`` and
+    ``plane`` read the whole field. ``power`` requires a rotor or a frame
+    lattice and optionally writes balances. Names default to the variant.
 
     Attributes
     ----------
+    variant : str
+        One analysis: sections (A), wake (B), plane (C), or power (D).
+    name : str
+        Unique entry label, defaulting to the variant word.
+    export_type : str
+        last_step, avg_window, or default; default reads the last unsteady step.
     families : str or list of str
-        A selector word, an alias, a family name or a list, the grammar of
-        ``[sections]``.
-    trefftz : TrefftzSpec, optional
-        The Trefftz variants.
-    ledgers : LedgersSpec, optional
-        The survey balances.
+        Required selection for sections; the other variants read the whole field.
+    stations : int or tuple of float
+        A station count per side for sections; lattice positions x/R for power.
+    distance_bref : float
+        Wake or plane distance behind the whole geometry in BREF.
+    half_width_bref, half_height_bref, spacing_bref : float
+        Plane half extents and uniform spacing in BREF.
+    station : float
+        Power station x/R; defaults to the last lattice station.
+    rotor : str
+        Reference rotor whose hub and radius place the power lattice.
+    frame, tip_radius_m : str and float
+        Alternative power lattice placement: frame and reference radius in metres.
+    n_r, r_inner, r_outer, n_psi : int or float
+        Power lattice ring count, radial bounds r/R, and uniform azimuth count.
+    lateral_radius, lateral_stations : float or tuple of float
+        Power lattice closure cylinder radius r/R and ring positions x/R.
+    hub_width, tip_width : float
+        Power lattice clustering widths r/R near the hub and tip.
+    m_max : int
+        Highest azimuthal harmonic, strictly below half the lattice azimuth count.
+    balances : list of str
+        Optional ledger balances; omitted, no ledger table is requested.
+    last_revs : float, optional
+        Positive trailing revolutions on the row's rotor clock, for this entry's average.
+    last_steps : int, optional
+        Positive trailing step count, exclusive with last_revs; omitted, use the row window.
     """
 
     model_config = ConfigDict(extra="forbid", allow_inf_nan=False)
+    variant: Literal["sections", "wake", "plane", "power"]
+    name: str = Field(default="", min_length=1)
+    export_type: Literal["last_step", "avg_window", "default"] = "default"
+    families: Annotated[str | list[str] | None, BeforeValidator(_family_selection)] = None
+    stations: int | tuple[float, ...] | None = None
+    distance_bref: float = Field(default=0.25, gt=0)
+    half_width_bref: float | None = Field(default=None, gt=0)
+    half_height_bref: float | None = Field(default=None, gt=0)
+    spacing_bref: float | None = Field(default=None, gt=0)
+    station: float | None = None
+    rotor: str | None = None
+    frame: str | None = None
+    tip_radius_m: float | None = None
+    n_r: int | None = None
+    r_inner: float | None = None
+    r_outer: float | None = None
+    n_psi: int | None = None
+    lateral_radius: float | None = None
+    lateral_stations: tuple[float, ...] | None = None
+    hub_width: float | None = None
+    tip_width: float | None = None
+    m_max: int = 6
+    balances: list[BalanceName] = Field(default_factory=list)
+    last_revs: float | None = Field(default=None, gt=0, strict=True)
+    last_steps: int | None = Field(default=None, gt=0, strict=True)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _keys_belong_to_the_variant(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        variant = value.get("variant")
+        if not isinstance(variant, str) or variant not in TREFFTZ_VARIANTS:
+            return value
+        for key in value:
+            readers = _KEY_VARIANTS.get(key)
+            if readers is not None and variant not in readers:
+                reason = ""
+                if key == "families":
+                    reason = (
+                        "; wake, plane and power read the whole field, "
+                        "so there is no family selection"
+                    )
+                raise ValueError(f"{key} is read by {', '.join(readers)}, not {variant!r}{reason}")
+        return value
 
-    families: Annotated[str | list[str], BeforeValidator(_family_selection)] = Field(
-        description=(
-            "What the far field is computed over: a selector word, an alias, a family name or "
-            "a list, the grammar of [sections]."
+    @model_validator(mode="after")
+    def _analysis_geometry(self) -> FarfieldSpec:
+        if self.last_revs is not None and self.last_steps is not None:
+            raise ValueError("state only one window, not both last_revs and last_steps")
+        if not self.name:
+            self.name = self.variant
+        if self.variant == "sections":
+            if self.families is None:
+                raise ValueError('variant = "sections" requires families')
+            if self.stations is not None and (
+                not isinstance(self.stations, int) or self.stations < 2
+            ):
+                raise ValueError('variant = "sections" reads stations as a count of at least 2')
+        if self.variant == "power":
+            if isinstance(self.stations, int):
+                raise ValueError('variant = "power" reads stations as a list of x/R positions')
+            _ = self.ledgers
+        return self
+
+    @property
+    def trefftz(self) -> TrefftzSpec:
+        """Return the numerical trace parameters of this single analysis."""
+        keys = ("distance_bref", "half_width_bref", "half_height_bref", "spacing_bref", "station")
+        values = {key: getattr(self, key) for key in keys}
+        values.update(
+            variant=[self.variant], stations=self.stations if self.variant == "sections" else 80
         )
-    )
-    trefftz: TrefftzSpec | None = Field(default=None, description="The Trefftz-plane analyses.")
-    ledgers: LedgersSpec | None = Field(
-        default=None, description="The conservation balances of a survey lattice."
-    )
+        if values["stations"] is None:
+            values["stations"] = 80
+        try:
+            return TrefftzSpec.model_validate(values)
+        except ValidationError as error:
+            raise self._entry_error(error) from error
 
-    @model_validator(mode="after")
-    def _selects_an_analysis(self) -> FarfieldSpec:
-        if self.trefftz is None and self.ledgers is None:
+    @property
+    def ledgers(self) -> LedgersSpec | None:
+        """Return the power analysis's validated lattice, or None for a trace."""
+        if self.variant != "power":
+            return None
+        keys = (*_LATTICE_KEYS, "rotor", "frame", "tip_radius_m", "m_max", "balances")
+        try:
+            return LedgersSpec.model_validate({key: getattr(self, key) for key in keys})
+        except ValidationError as error:
+            raise self._entry_error(error) from error
+
+    def _entry_error(self, error: ValidationError) -> ValueError:
+        parts = []
+        for item in error.errors():
+            key = ".".join(str(part) for part in item["loc"])
+            message = str(item["msg"]).removeprefix("Value error, ")
+            parts.append(f"{key}: {message}" if key else message)
+        return ValueError(f"[[farfields]] entry {self.name!r}: " + "; ".join(parts))
+
+
+_KEY_VARIANTS = {
+    "families": ("sections",),
+    "stations": ("sections", "power"),
+    "distance_bref": ("wake", "plane"),
+    **{key: ("plane",) for key in ("half_width_bref", "half_height_bref", "spacing_bref")},
+    **{
+        key: ("power",)
+        for key in (
+            *_LATTICE_KEYS[1:],
+            "station",
+            "rotor",
+            "frame",
+            "tip_radius_m",
+            "m_max",
+            "balances",
+        )
+    },
+}
+
+
+def farfield_entries(value: Any) -> Any:
+    """Refuse the retired table with equivalent array entries."""
+    if not isinstance(value, dict):
+        return value
+    if value.get("farfield") is not None:
+        old = value["farfield"]
+        entries = []
+        if isinstance(old, dict):
+            trace = old.get("trefftz", {})
+            variants = trace.get("variant", [])
+            for variant in [variants] if isinstance(variants, str) else variants:
+                entry = {"variant": variant}
+                entry.update(
+                    {k: v for k, v in trace.items() if variant in _KEY_VARIANTS.get(k, ())}
+                )
+                if variant == "sections":
+                    entry["families"] = old.get("families", "all")
+                entries.append(entry)
+            if "ledgers" in old:
+                power = {"variant": "power", "balances": list(BALANCES), **old["ledgers"]}
+                if "station" in trace:
+                    power["station"] = trace["station"]
+                entries.append(power)
+        replacement = "\n\n".join(
+            "[[farfields]]\n"
+            + "\n".join(f"{key} = {json.dumps(val)}" for key, val in entry.items())
+            for entry in entries
+        )
+        raise ValueError(
+            "[farfield] was replaced by [[farfields]], one analysis per entry:\n"
+            + replacement
+            + '\nA 0.44.0 "plane" with ledgers on a rotor row becomes the "power" entry (D), '
+            'not the "plane" entry (C); keep C only to request the velocity plane as well.'
+        )
+    return value
+
+
+def _refuse_filename_collisions(entries: Any) -> None:
+    """Refuse sanitized filename collisions even on case-insensitive filesystems."""
+    names: dict[str, str] = {}
+    for entry in entries if isinstance(entries, list | tuple) else ():
+        name = (
+            entry.name
+            if isinstance(entry, FarfieldSpec)
+            else (entry.get("name", entry.get("variant")) if isinstance(entry, dict) else None)
+        )
+        if not isinstance(name, str):
+            continue
+        spelling = re.sub(r"[^A-Za-z0-9_.+-]", "_", name).casefold()
+        previous = names.get(spelling)
+        if previous is not None and previous != name:
             raise ValueError(
-                "[farfield] selects no analysis: state [farfield.trefftz] with a variant, "
-                "[farfield.ledgers], or both"
+                f"[[farfields]] names {previous!r} and {name!r} share file spelling "
+                f"{spelling!r} ignoring case; choose names with distinct file spellings"
             )
-        return self
+        names[spelling] = name

{pyflightstream-0.44.0 → pyflightstream-0.45.0}/src/pyflightstream/cases/farfield_inputs.py

@@ -70,6 +70,8 @@ class FarfieldInput:
         The declaration reused, or what the plan adds.
     reason : str
         Why the input is not applicable or refused; empty otherwise.
+    entry, variant : str
+        The requesting entry's name and public variant, assigned by the workflow.
     """
 
     analysis: str
@@ -77,10 +79,14 @@ class FarfieldInput:
     state: str
     source: str = ""
     reason: str = ""
+    entry: str = ""
+    variant: str = ""
 
     def as_record(self) -> dict[str, str]:
         """Return the input as the plan output states it (FR-1047)."""
         return {
+            "entry": self.entry,
+            "variant": self.variant,
             "analysis": self.analysis,
             "input": self.input,
             "state": self.state,
@@ -145,11 +151,22 @@ def applies(analysis: str, run_type: str, *, rotor: bool = False) -> str:
     >>> bool(applies('trefftz:wake', 'unsteady_rotor'))
     True
     """
-    if analysis in ("trefftz:sections", "trefftz:wake"):
+    if analysis == "trefftz:plane" and run_type == "qsteady_rotor":
+        return (
+            "Trefftz C requires a uniform freestream; qsteady_rotor uses a rotating frame: "
+            'select "power"'
+        )
+    if analysis == "trefftz:sections" and run_type == "qsteady_rotor":
+        return (
+            "Trefftz A on qsteady_rotor has no lifting surface outside the rotor: "
+            "state the A entry on a steady or unsteady_rotor row that carries the lifting "
+            'surfaces, or select "power" for the rotor on this row'
+        )
+    if analysis == "trefftz:wake":
         if rotor or run_type in ROTOR_RUN_TYPES:
             return "a rotor's helical wake is not a streamwise sheet"
         if run_type in UNSTEADY_RUN_TYPES:
-            return "variants A and B serve steady rows"
+            return "variant B serves steady rows"
     return ""
 
 
@@ -184,7 +201,7 @@ def few_stations_warning(family: str, per_side: int, stations: int) -> str:
     """Return the WARNING of a family traced on fewer stations than asked (FR-1019).
 
     One sentence, said by the plan and by post alike: the family, its station
-    count per side, the count ``[farfield.trefftz] stations`` asks for, and the
+    count per side, the count its ``[[farfields]]`` sections entry asks for, and the
     strip bias of ``E_T`` the definitions page measured at the nearest count
     (:data:`STRIP_BIAS_PERCENT`).
 
@@ -195,7 +212,7 @@ def few_stations_warning(family: str, per_side: int, stations: int) -> str:
     per_side : int
         Its station count per side of the symmetry plane.
     stations : int
-        The count per side ``[farfield.trefftz] stations`` asks for.
+        The count per side its ``[[farfields]]`` sections entry asks for.
 
     Returns
     -------
@@ -206,8 +223,9 @@ def few_stations_warning(family: str, per_side: int, stations: int) -> str:
         return ""
     nearest = min(STRIP_BIAS_PERCENT, key=lambda count: (abs(count - per_side), count))
     return (
-        f"family {family} has {per_side} stations per side, fewer than the {stations} of "
-        f"[farfield.trefftz]; the strip bias of E_T measured on the definitions page is "
+        f"family {family} has {per_side} stations per side, fewer than the {stations} its "
+        "[[farfields]] sections entry asks for; the strip bias of E_T measured on the "
+        "definitions page is "
         f"{STRIP_BIAS_PERCENT[nearest]} percent at {nearest} stations per side (FR-1019)"
     )
 
@@ -216,7 +234,7 @@ def _analyses(spec: FarfieldSpec) -> list[str]:
     out = []
     if spec.trefftz is not None:
         out += [f"trefftz:{variant}" for variant in spec.trefftz.variant]
-    if spec.ledgers is not None:
+    if spec.balances:
         out.append("ledgers")
     return out
 
@@ -240,7 +258,7 @@ def resolve_farfield(
     Parameters
     ----------
     spec : FarfieldSpec
-        The row's ``[farfield]`` table.
+        The row's named ``[[farfields]]`` entry.
     run_type : str
         The row's run type (``steady``, ``unsteady``, ``unsteady_rotor``,
         ``qsteady_rotor``).
@@ -248,7 +266,7 @@ def resolve_farfield(
         The families a declared ``[sections]`` distribution cuts in plane XZ of a
         reference-axes frame (FR-1045).
     selected_families : sequence of str
-        The families ``[farfield] families`` resolves to on the row's geometry.
+        The families the ``[[farfields]]`` entry resolves to on the row's geometry.
     exports : dict of str to bool
         The artifact's ``[exports]`` table, as stated.
     declares_lattice, declares_plane : bool
@@ -282,13 +300,17 @@ def resolve_farfield(
                 analysis,
                 "families",
                 "refused",
-                reason=f"[farfield] families = {spec.families!r} names no family of the geometry",
+                reason=(
+                    f"[[farfields]] entry {spec.name!r}: families = {spec.families!r} "
+                    "names no family of the geometry"
+                ),
             )
         return FarfieldResolution(tuple(resolver.inputs))
     for analysis in _analyses(spec):
         why = applies(analysis, run_type, rotor=rotor)
         if why:
-            resolver.item(analysis, "run_type", "not_applicable", reason=why)
+            state = "refused" if analysis != "trefftz:wake" else "not_applicable"
+            resolver.item(analysis, "run_type", state, reason=why)
         elif analysis == "trefftz:sections":
             resolver.sections(analysis, selected_families, coupled)
         elif analysis == "trefftz:wake":
@@ -305,7 +327,7 @@ def resolve_farfield(
             )
         else:
             # A rotor's Trefftz C reads a lattice station, as _Resolver.probes says (PFS-2081.101).
-            reads_lattice = analysis == "ledgers" or resolver.rotor
+            reads_lattice = analysis in ("ledgers", "trefftz:power")
             declared = declares_lattice if reads_lattice else declares_plane
             resolver.probes(analysis, declared)
     return FarfieldResolution(tuple(resolver.inputs))
@@ -330,8 +352,6 @@ class _Resolver:
 
     def lacks(self, analysis: str, name: str) -> bool:
         command = _COMMANDS[name]
-        if name == "probe_points" and self.run_type in UNSTEADY_RUN_TYPES:
-            command = "UNSTEADY_SOLVER_NEW_FLUID_PLOT"
         if self.has_command(command):
             return False
         self.item(analysis, name, "refused", reason=f"the selected build has no {command}")
@@ -387,7 +407,7 @@ class _Resolver:
         self.export(analysis, "sectional_loads", "sectional_loads_export", True)
 
     def probes(self, analysis: str, declared: bool) -> None:
-        shape = "lattice" if analysis == "ledgers" or self.rotor else "plane"
+        shape = "lattice" if analysis in ("ledgers", "trefftz:power") else "plane"
         self.needed(
             analysis,
             "probe_points",
@@ -395,7 +415,4 @@ class _Resolver:
             f"the declared [[probes]] {shape}",
             f"the far-field {shape} as probe points",
         )
-        if self.run_type in UNSTEADY_RUN_TYPES:
-            self.item(analysis, "probe_export", "added", "per-step fluid plots of every point")
-        else:
-            self.export(analysis, "probes", "probe_export", True)
+        self.item(analysis, "probe_export", "added", "the dedicated farfield_probes export")

{pyflightstream-0.44.0 → pyflightstream-0.45.0}/src/pyflightstream/cases/pproc.py

@@ -44,7 +44,12 @@ from pyflightstream._tokens import REDUCTION_COLUMNS
 
 # The quasi-steady wheel's correction choice, a table of the pproc; its
 # module imports only the floor, so the package may import it while it loads.
-from pyflightstream.cases._farfield_spec import FarfieldSpec, LatticeShape
+from pyflightstream.cases._farfield_spec import (
+    FarfieldSpec,
+    LatticeShape,
+    _refuse_filename_collisions,
+    farfield_entries,
+)
 from pyflightstream.cases.corrections import QsteadyCorrectionSpec
 from pyflightstream.cases.reference_blocks import CampaignConfigError
 from pyflightstream.cases.selection import EVERY_FAMILY
@@ -127,6 +132,7 @@ EXPORT_KINDS: tuple[tuple[str, str, str, bool], ...] = (
     ("sections", "_cp.txt", "EXPORT_ALL_SURFACE_SECTIONS", False),
     ("sectional_loads", "_sloads.txt", "EXPORT_SURFACE_SECTIONAL_LOADS", False),
     ("probes", "_probes.txt", "EXPORT_PROBE_POINTS", False),
+    ("farfield_probes", "_farfield_survey.txt", "EXPORT_PROBE_POINTS", False),
     ("plots", "_plots.txt", "UNSTEADY_SOLVER_EXPORT_PLOTS", True),
     ("plot_residuals", "_plot_residuals.txt", "SAVE_PLOT_TO_FILE", False),
     ("plot_loads", "_plot_loads.txt", "SAVE_PLOT_TO_FILE", False),
@@ -148,7 +154,7 @@ EXPORT_KINDS: tuple[tuple[str, str, str, bool], ...] = (
 #: (FR-460) and the trajectory of a row's ``SIXDOF`` input (FR-461). Each is
 #: written once, where its command sits, and never by a per-step action.
 TABLE_DECLARED_KINDS: frozenset[str] = frozenset(
-    {"streamlines_surface", "streamlines_off_body", "trajectory_6dof"}
+    {"streamlines_surface", "streamlines_off_body", "trajectory_6dof", "farfield_probes"}
 )
 
 #: The plot each solver-plot kind chooses with ``SET_PLOT_TYPE`` before its
@@ -2034,8 +2040,8 @@ class PprocSpec(BaseModel):
         families.
     probes : list of ProbesSpec
         The fluid probe entries, one per frame sampled.
-    farfield : FarfieldSpec, optional
-        The far-field analyses and what they are computed over (FR-454);
+    farfields : list of FarfieldSpec
+        Named far-field entries, one variant and optional window each (FR-454);
         absent, the artifact plans and posts as before.
     products : ProductsSpec
         Which post-processed tables the campaign writes.
@@ -2157,7 +2163,28 @@ class PprocSpec(BaseModel):
     #: Native surface-property histories, separate from fluid samples and field products.
     surface_probes: list[SurfaceProbeSpec] = Field(default_factory=list)
     #: FR-454: the far-field family's table; absent, nothing changes.
-    farfield: FarfieldSpec | None = None
+    farfields: list[FarfieldSpec] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _farfield_entries(cls, value: object) -> object:
+        return farfield_entries(value)
+
+    @field_validator("farfields")
+    @classmethod
+    def _unique_farfield_names(cls, entries: list[FarfieldSpec]) -> list[FarfieldSpec]:
+        names = [entry.name for entry in entries]
+        if len(names) != len(set(names)):
+            raise ValueError(
+                f"[[farfields]] names {names!r} must be unique; name repeated variants separately"
+            )
+        _refuse_filename_collisions(entries)
+        return entries
+
+    @property
+    def farfield(self) -> FarfieldSpec | None:
+        """Return the entry of an analysis-specific planning or post context."""
+        return self.farfields[0] if self.farfields else None
 
     @field_validator("surface_probes")
     @classmethod