pyflightstream 0.45.0__tar.gz → 0.45.1__tar.gz

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

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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyflightstream"
-version = "0.45.0"
+version = "0.45.1"
 description = "Version-aware, didactic Python driver for the FlightStream panel-method solver"
 readme = "README.md"
 license = {text = "MIT"}

{pyflightstream-0.45.0 → pyflightstream-0.45.1}/src/pyflightstream/cases/fsi_workspace.py

@@ -876,7 +876,7 @@ def wire_workspace_fsi(
     blades = list(rotor.families_blades)
     if len(blades) != cfg.blade_count or len(set(blades)) != len(blades):
         raise CampaignConfigError("FSI blade count differs from the unique resolved rotor blades.")
-    if rotor.axis != "X" or rotor.blade1.zero != "Z":
+    if rotor.axis_vector != (1.0, 0.0, 0.0) or rotor.blade1.zero != "Z":
         raise CampaignConfigError(
             "FSI rotor_frame requires shaft X and blade datum Z; another node/load basis "
             "has not been established by this adapter."
@@ -1211,7 +1211,7 @@ def wire_quasi_steady_sector_fsi(
             "blade, blade one, and the others are its periodic images."
         )
     if (
-        rotor.axis != "X"
+        rotor.axis_vector != (1.0, 0.0, 0.0)
         or rotor.blade1.zero != "Z"
         or abs(rotor.blade1.azimuth_deg) > 1e-12
         or any(abs(value) > _ORIGIN_TOLERANCE_M for value in rotor.origin)

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

@@ -37,7 +37,7 @@ from pydantic import (
 )
 
 from pyflightstream._deprecations import ROW_EACH_BLADE, refusal_text
-from pyflightstream._errors import InputArtifactError
+from pyflightstream._errors import InputArtifactError, PyflightstreamWarning, warn
 from pyflightstream._expressions import ALLOWED_FUNCTIONS, expression_symbols
 from pyflightstream._retired_names import PROBE_SCALE_PROPELLER_RADIUS
 from pyflightstream._tokens import REDUCTION_COLUMNS
@@ -51,7 +51,6 @@ from pyflightstream.cases._farfield_spec import (
     farfield_entries,
 )
 from pyflightstream.cases.corrections import QsteadyCorrectionSpec
-from pyflightstream.cases.reference_blocks import CampaignConfigError
 from pyflightstream.cases.selection import EVERY_FAMILY
 from pyflightstream.commands import CommandRegistry
 from pyflightstream.probes.planar import PlanarProbeGrid
@@ -146,6 +145,7 @@ EXPORT_KINDS: tuple[tuple[str, str, str, bool], ...] = (
     # FR-461: a free body's trajectory, declared only by a row's SIXDOF
     # input. Its command is a setup command, emitted with the motion it names.
     ("trajectory_6dof", "_trajectory_6dof.txt", "EXPORT_6DOF_TRAJECTORY", True),
+    ("debug_fsm", "_debug.fsm", "SAVEAS", False),
     ("log", "_log.txt", "EXPORT_LOG", False),
 )
 
@@ -202,17 +202,15 @@ EXPORT_KIND_SINCE: dict[str, tuple[int, int]] = {
 #: are saved once after the march (GOAL-033 T40, 26.124 build 8172026).
 STEADY_ONLY_EXPORT_KINDS: frozenset[str] = frozenset({"probes"})
 
-#: FR-417: the probe kinds a ``[[probes]]`` entry may state. ``unsteady`` (the
-#: default) samples through fluid plots at every time step; ``normal`` creates
-#: probe points after the time march and exports them once.
-ProbeKind = Literal["unsteady", "normal"]
+#: PFS-2167: default samples once; instantaneous requests an unsteady history.
+ProbeKind = Literal["default", "instantaneous"]
 PROBE_KINDS: tuple[str, ...] = get_args(ProbeKind)
 
 #: The kinds a pproc must switch ON: every other kind is on unless its
 #: ``[exports]`` entry says false. The surface fields and the per-panel force
 #: distribution (G10) grow with the mesh, so they are asked for
 #: where they are wanted.
-OPT_IN_EXPORT_KINDS: tuple[str, ...] = ("vtk", "csv", "force_distributions")
+OPT_IN_EXPORT_KINDS: tuple[str, ...] = ("vtk", "csv", "force_distributions", "debug_fsm")
 
 #: What each kind an ``[exports]`` table may name leaves, one sentence each,
 #: for the generated input glossary ``INPUTS.md`` (G08). The command
@@ -221,6 +219,7 @@ OPT_IN_EXPORT_KINDS: tuple[str, ...] = ("vtk", "csv", "force_distributions")
 #: The two volume-section kinds are not here: ``[exports]`` cannot name them.
 EXPORT_KIND_MEANINGS: dict[str, str] = {
     "simulation": "The point's final saved simulation, its solver state after the solve.",
+    "debug_fsm": "The solver state before output setup, for inspection only.",
     "loads": "The loads table, the export every run is judged by.",
     "tecplot": (
         "The surface solution in Tecplot format, written by the package from the VTK "
@@ -1186,10 +1185,10 @@ class ProbesSpec(_LocatedSpec):
     points_file : str, optional
         The name of a points file of ``inputs/profiles/``, cited instead of
         drawing lines and planes.
-    kind : {'unsteady', 'normal'}
-        How an unsteady row samples the entry: ``unsteady``, one
+    kind : {'default', 'instantaneous'}
+        How an unsteady row samples the entry: ``instantaneous``, one
         fluid plot per point and parameter evaluated at every time step, or
-        ``normal``, probe points created after the time march and exported
+        ``default`` (also when absent), probe points created after the time march and exported
         once, at the last time step. A steady row accepts either and samples
         probe points.
     """
@@ -1238,26 +1237,35 @@ class ProbesSpec(_LocatedSpec):
     #: committed report).
     #: Excluded from every dump, so no machine path reaches a record or a plan.
     resolved_points_file: str | None = Field(default=None, exclude=True)
-    #: FR-417: how an unsteady row samples this entry. ``unsteady`` (the
-    #: default) is one fluid plot per point and
-    #: parameter, a history at every time step; ``normal`` is probe points
+    #: How an unsteady row samples this entry. ``instantaneous`` is one fluid
+    #: plot per point and parameter, a history at every time step; ``default`` is probe points
     #: created after the time march with the steady commands, updated and
     #: exported once, so they hold the solution at the end of the march (RPT-153,
     #: "normal probes after an unsteady march", 2026-10-05; not the same sample as
     #: the last fluid-plot step). A steady row samples
     #: probe points whatever the entry states.
-    kind: ProbeKind = "unsteady"
+    kind: ProbeKind = "default"
 
     @field_validator("kind", mode="before")
     @classmethod
     def _a_known_probe_kind(cls, value: object) -> object:
         """Refuse a probe kind other than the two, naming both (FR-888)."""
+        aliases = {"normal": "default", "unsteady": "instantaneous"}
+        if isinstance(value, str) and value in aliases:
+            canonical = aliases[value]
+            warn(
+                f"probe kind {value!r} is deprecated; use kind = {canonical!r} instead.",
+                PyflightstreamWarning,
+                stacklevel=2,
+            )
+            return canonical
         if value not in PROBE_KINDS:
             raise ValueError(
                 f"probe kind {value!r} is not one of {' or '.join(map(repr, PROBE_KINDS))}: "
-                'write kind = "unsteady" for a fluid plot per point and parameter, '
-                'evaluated at every time step, or kind = "normal" for probe points '
-                "sampled once, at the last time step"
+                'write kind = "instantaneous" for a fluid plot per point and parameter, '
+                'evaluated at every time step, or kind = "default" for probe points '
+                "sampled once, at the last time step. Deprecated aliases: 'unsteady' "
+                "and 'normal', respectively."
             )
         return value
 
@@ -2462,12 +2470,7 @@ class PprocSpec(BaseModel):
             # history is in the plots export whatever the [[probes]] kind is
             # (PFS-2105.002).
             sources.append("{name}_plots.txt")
-        if self.volume_section is not None or any(
-            entry.field_formats or entry.reusable_inflow for entry in self.probes
-        ):
-            # FR-418: a NORMAL entry's field is read from the probe-points
-            # export on an unsteady row too, not from the plots history.
-            sources.append("{name}_plots.txt" if unsteady and not normal else "{name}_probes.txt")
+        sources.extend(self._field_exports(unsteady))
         for source in sources:
             if source not in names:
                 names.append(source)
@@ -2476,6 +2479,20 @@ class PprocSpec(BaseModel):
                 names.append(name)
         return names
 
+    def _field_exports(self, unsteady: bool) -> list[str]:
+        """Request both native sources when mixed entries require sampled fields."""
+        sources = []
+        if self.volume_section is not None:
+            sources.append("{name}_plots.txt" if unsteady else "{name}_probes.txt")
+        for entry in self.probes:
+            if entry.field_formats or entry.reusable_inflow:
+                sources.append(
+                    "{name}_plots.txt"
+                    if unsteady and entry.kind != "default"
+                    else "{name}_probes.txt"
+                )
+        return sources
+
     def _streamline_exports(self) -> list[str]:
         """Return the files the streamline traces are exported to (FR-1078)."""
         if self.streamlines is None:
@@ -2487,31 +2504,15 @@ class PprocSpec(BaseModel):
         return [f"{{name}}{suffix[kind]}" for kind in traced]
 
     def samples_normal_probes(self) -> bool:
-        """Whether an unsteady row samples this artifact's probes as NORMAL probe points.
+        """Whether an unsteady row has entries sampled as normal probe points.
 
         True when the artifact declares at least one ``[[probes]]`` entry and
-        every entry states ``kind = "normal"`` (FR-417); an entry that states no
-        kind and a volume section are ``unsteady``. A mixture is refused here,
-        naming the entries of each kind. Steady callers do not ask this question.
+        at least one entry states ``kind = "default"``. Mixed entries keep their
+        independent sampling routes. Steady callers do not ask this question.
 
         Returns
         -------
         bool
-            Whether the entries are all normal probes.
+            Whether any entry needs the final probe-points export.
         """
-        normal = [str(n) for n, entry in enumerate(self.probes, 1) if entry.kind == "normal"]
-        if not normal:
-            return False
-        unsteady = [str(n) for n, entry in enumerate(self.probes, 1) if entry.kind != "normal"]
-        if self.volume_section is not None:
-            unsteady.append("[volume_section]")
-        if unsteady:
-            raise CampaignConfigError(
-                "mixes probe kinds on an unsteady row: unsteady (fluid plots at every time step) "
-                f"{', '.join(unsteady)}; normal (probe points at the last time step) "
-                f"{', '.join(normal)}. One unsteady row samples every [[probes]] entry one "
-                'way, an entry stating no kind counting as kind = "unsteady", and a '
-                "[volume_section] is sampled through fluid plots. State one kind on every "
-                "entry, or move the other entries to a second pproc on their own row."
-            )
-        return True
+        return any(entry.kind == "default" for entry in self.probes)

{pyflightstream-0.45.0 → pyflightstream-0.45.1}/src/pyflightstream/cases/reference_blocks.py

@@ -116,6 +116,29 @@ class BladeDatum(BaseModel):
         return token
 
 
+class _RotorAxis(BaseModel):
+    """The named shaft axis and its installed direction in global coordinates."""
+
+    model_config = ConfigDict(extra="forbid", allow_inf_nan=False)
+    shaft: Literal["X", "Y", "Z"]
+    vector_wrt_global: tuple[float, float, float]
+
+    @model_validator(mode="after")
+    def _usable_direction(self) -> _RotorAxis:
+        scale = max(abs(value) for value in self.vector_wrt_global)
+        if scale == 0:
+            raise ValueError("vector_wrt_global has zero length; state the shaft direction")
+        scaled = tuple(value / scale for value in self.vector_wrt_global)
+        component = scaled["XYZ".index(self.shaft)] / math.hypot(*scaled)
+        angle = math.degrees(math.acos(max(-1.0, min(1.0, component))))
+        if angle > 45.0 + 1e-10:
+            raise ValueError(
+                f"vector_wrt_global is {angle:.2f} degrees from shaft {self.shaft}; "
+                "at most 45 degrees is accepted. Choose the matching shaft letter"
+            )
+        return self
+
+
 class RotorBlock(BaseModel):
     """One rotor, declared as one block of the reference artifact (FR-60).
 
@@ -151,8 +174,8 @@ class RotorBlock(BaseModel):
         a type check is what found it.
     x_m, y_m, z_m : float
         The hub, in the geometry's own frame.
-    axis : str
-        The axis it turns about.
+    axis : str or mapping
+        A shaft letter or ``{shaft, vector_wrt_global}`` installation declaration.
     rpm_sign : int
         ``+1`` is the right-hand rule about ``axis``, which is the one
         reading that does not depend on where the reader stands.
@@ -178,7 +201,7 @@ class RotorBlock(BaseModel):
     model_config = ConfigDict(extra="forbid", allow_inf_nan=False)
 
     alias: str
-    axis: str | tuple[float, float, float] | list[float]
+    axis: str | _RotorAxis
     diameter_m: float = Field(gt=0.0)
     families_blades: list[str]
     x_m: float = 0.0
@@ -207,14 +230,7 @@ class RotorBlock(BaseModel):
     @field_validator("axis", mode="before")
     @classmethod
     def _an_axis(cls, value: object) -> object:
-        """Accept a LETTER or a three-component VECTOR.
-
-        The letter keeps its exact meaning: `Z` IS the vector (0, 0, 1), so the
-        letter spelling is a special case of a vector. A mesh can arrive
-        with its pitch and toe
-        already in it, and a shaft installed at an angle lies on no geometry
-        axis at all.
-        """
+        """Accept a letter or an explicit shaft table; translate retired bare vectors."""
         if isinstance(value, str):
             token = value.strip().upper()
             if token not in ("X", "Y", "Z"):
@@ -223,8 +239,8 @@ class RotorBlock(BaseModel):
                 # documentation carries. Widening what `axis` accepts may add to
                 # the sentence and may not replace it.
                 raise ValueError(
-                    f"axis = {value!r} is not an axis; write X, Y or Z, or the three "
-                    "components of the shaft direction for a rotor installed at an angle"
+                    f"axis = {value!r} is not an axis; write X, Y or Z, or a table "
+                    "with shaft and vector_wrt_global for a rotor installed at an angle"
                 )
             return token
         if isinstance(value, (list, tuple)):
@@ -244,9 +260,18 @@ class RotorBlock(BaseModel):
                     f"axis = {value!r} has no length, so it names no direction, and a rotor "
                     "turns about a direction"
                 )
-            return components
+            nearest = "XYZ"[max(range(3), key=lambda i: abs(components[i]))]
+            raise ValueError(
+                f"axis = {list(value)!r} did not say which frame axis is the shaft; "
+                f'write axis = {{ shaft = "{nearest}", vector_wrt_global = {list(value)!r} }}'
+            )
         return value
 
+    @property
+    def shaft(self) -> str:
+        """The rotor-frame axis named as the shaft."""
+        return self.axis if isinstance(self.axis, str) else self.axis.shaft
+
     @property
     def axis_vector(self) -> tuple[float, float, float]:
         """The shaft direction as a UNIT vector, whichever way it was written.
@@ -258,7 +283,8 @@ class RotorBlock(BaseModel):
         stated = self.axis
         if isinstance(stated, str):
             return AXIS_UNIT_VECTORS[stated]
-        components = tuple(float(component) for component in stated)
+        scale = max(abs(value) for value in stated.vector_wrt_global)
+        components = tuple(value / scale for value in stated.vector_wrt_global)
         length = math.hypot(*components)
         return (components[0] / length, components[1] / length, components[2] / length)
 
@@ -277,9 +303,9 @@ class RotorBlock(BaseModel):
     def _an_alias_no_frame_can_be_mistaken_for(cls, value: str) -> str:
         if not value.strip() or value != value.strip() or any(c.isspace() for c in value):
             raise ValueError(f"alias = {value!r} must be one word, with no blank or space in it")
-        if value.upper().endswith(("_SMRP", "_RMRP")):
+        if value.upper().endswith(("_SMRP", "_RMRP", "_BMRP")):
             raise ValueError(
-                f"alias = {value!r} ends in _SMRP or _RMRP, the radical of the frames the "
+                f"alias = {value!r} ends in _SMRP or _RMRP or _BMRP, the radical of the frames the "
                 "package builds from a rotor's name, so a rotor and a frame would spell the "
                 "same; choose another name"
             )
@@ -302,6 +328,11 @@ class RotorBlock(BaseModel):
         # Compare directions by angle, not spelling. An axis (0, 0.02, 0.9998)
         # is only one degree from a Z datum even though their strings differ.
         # A nearly parallel datum cannot define a useful azimuth and is refused.
+        if self.blade1.zero.lstrip("+-") == self.shaft:
+            raise ValueError(
+                f"blade1.zero {self.blade1.zero} equals shaft {self.shaft}; "
+                "choose one of the two remaining axes"
+            )
         shaft = self.axis_vector
         datum = AXIS_UNIT_VECTORS[self.blade1.zero.lstrip("+-")]
         alignment = abs(sum(a * b for a, b in zip(shaft, datum, strict=True)))

{pyflightstream-0.45.0 → pyflightstream-0.45.1}/src/pyflightstream/cases/workflows/_clock.py

@@ -282,11 +282,11 @@ def _action_export_kinds(
         for kind, name in classify_outputs(names).items()
         if whole_run or kind not in (*WHOLE_RUN_EXPORT_KINDS, *END_OF_RUN_EXPORT_KINDS)
     }
+    kinds.pop("debug_fsm", None)  # Saved once at the window start, never on every step.
     # FR-890: the per-step exports of a row whose probes are NORMAL update and
     # export them at every step of the window; the wall clock's rescue does not,
     # since the points may not exist when it fires.
-    normal = not whole_run and case.pproc is not None and case.pproc.samples_normal_probes()
-    if declared_run_type(case) in _UNSTEADY_RECIPES and not normal:
+    if declared_run_type(case) in _UNSTEADY_RECIPES:
         for kind in STEADY_ONLY_EXPORT_KINDS:
             kinds.pop(kind, None)
     # G05: an action fires during the march and a volume section is cut after

{pyflightstream-0.45.0 → pyflightstream-0.45.1}/src/pyflightstream/cases/workflows/_exports.py

@@ -29,6 +29,7 @@ from pyflightstream.cases import (
 from pyflightstream.cases import (
     windows as _windows,
 )
+from pyflightstream.cases._unsteady_actions import UNSTEADY_EXPORTS_ACTION
 from pyflightstream.probes.layouts import emit_probe_export
 from pyflightstream.script import (
     Script,
@@ -429,6 +430,21 @@ def _export_block(
         _export_log(conventions, case, script, claimed=tuple(claimed))
 
 
+def _debug_fsm(case: SimCase, script: Script, *, clocking: int | None = None) -> None:
+    """Save the opt-in inspection state before post-solve output setup."""
+    if case.pproc is None or not case.pproc.exports.get("debug_fsm", False):
+        return
+    if any(action.name == UNSTEADY_EXPORTS_ACTION for action in script.unsteady_actions):
+        return  # The window-start action owns this save.
+    names = [name for name in case.outputs if name.endswith("_debug.fsm")]
+    if not names:
+        return
+    if clocking is None and any(name.endswith("_c0_debug.fsm") for name in names):
+        clocking = 0
+    name = next((name for name in names if name.endswith(f"_c{clocking}_debug.fsm")), names[0])
+    script.emit("SAVEAS", name)
+
+
 def _export_each_kind(
     script: Script,
     case: SimCase,
@@ -457,6 +473,8 @@ def _export_each_kind(
         if kind == "log" and skip_log:
             continue
         claimed.append(names.index(kinds[kind]) + 1)
+        if kind == "debug_fsm":
+            continue  # Already saved before output setup, or at the window start.
         if kind == "probes":
             # THE PROBES HOME'S EXPORT (PFS-2140.001): the public emitter is what
             # the workspace runs. UPDATE_PROBE_POINTS was emitted with the other