flowstate 0.6.2__tar.gz → 0.7.0__tar.gz

{flowstate-0.6.2 → flowstate-0.7.0}/.github/workflows/publish.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@v6
 

{flowstate-0.6.2 → flowstate-0.7.0}/.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v6

{flowstate-0.6.2 → flowstate-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowstate
-Version: 0.6.2
+Version: 0.7.0
 Summary: Lightweight utility for computing flow states
 Author-email: Christoph Hader <christoph.hader@gmail.com>
 License-Expression: GPL-3.0-or-later
@@ -13,6 +13,8 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Physics
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -20,6 +22,7 @@ License-File: LICENSE
 Requires-Dist: h5py>=3.10.0
 Requires-Dist: typer>=0.9.0
 Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: pydantic>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
@@ -105,7 +108,7 @@ contributors can focus on the physics rather than inventing formatting rules.
 |---|---|---|
 | [PEP 8](https://peps.python.org/pep-0008/) | Code formatting, naming, whitespace | Python standard style guide |
 | [PEP 257](https://peps.python.org/pep-0257/) | Docstring structure (triple-quoted, imperative mood) | Python standard docstring conventions |
-| [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) | Docstring sections (`Parameters`, `Returns`, `Attributes`) | NumPy/SciPy docstring standard — the norm for scientific Python |
+| [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) | Docstring sections (`Args`, `Returns`, `Raises`) | Google Python style guide |
 | [Ruff](https://docs.astral.sh/ruff/) | Automated linting and formatting | Enforces PEP 8 compliance automatically |
 | [typing / TYPE_CHECKING](https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING) | Type hints for IDE support and static analysis | Python standard library |
 

{flowstate-0.6.2 → flowstate-0.7.0}/README.md

@@ -75,7 +75,7 @@ contributors can focus on the physics rather than inventing formatting rules.
 |---|---|---|
 | [PEP 8](https://peps.python.org/pep-0008/) | Code formatting, naming, whitespace | Python standard style guide |
 | [PEP 257](https://peps.python.org/pep-0257/) | Docstring structure (triple-quoted, imperative mood) | Python standard docstring conventions |
-| [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) | Docstring sections (`Parameters`, `Returns`, `Attributes`) | NumPy/SciPy docstring standard — the norm for scientific Python |
+| [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) | Docstring sections (`Args`, `Returns`, `Raises`) | Google Python style guide |
 | [Ruff](https://docs.astral.sh/ruff/) | Automated linting and formatting | Enforces PEP 8 compliance automatically |
 | [typing / TYPE_CHECKING](https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING) | Type hints for IDE support and static analysis | Python standard library |
 

{flowstate-0.6.2 → flowstate-0.7.0}/pyproject.toml

@@ -20,6 +20,8 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering :: Physics",
 ]
 keywords = ["compressible-flow", "aerodynamics", "gas-dynamics", "cfd"]
@@ -28,6 +30,7 @@ dependencies = [
     "h5py>=3.10.0",
     "typer>=0.9.0",
     "tomli-w>=1.0.0",
+    "pydantic>=2.0",
 ]
 
 [project.optional-dependencies]
@@ -51,7 +54,7 @@ Documentation = "https://uahypersonics.github.io/flow-state"
 where = ["src"]
 
 [tool.setuptools.package-data]
-"flow_state" = ["examples/*.toml"]
+"flow_state" = ["examples/*/*"]
 
 [tool.setuptools_scm]
 

flowstate-0.7.0/src/flow_state/cli/__init__.py

@@ -0,0 +1,15 @@
+"""Command-line interface for flow-state."""
+
+# --------------------------------------------------
+# load necessary modules
+# --------------------------------------------------
+from flow_state.cli.app import app
+
+# --------------------------------------------------
+# cli public api
+# --------------------------------------------------
+
+# Preserve the existing ``flow_state.cli:cli`` console entry point.
+cli = app
+
+__all__ = ["app", "cli"]

flowstate-0.7.0/src/flow_state/cli/app.py

@@ -0,0 +1,75 @@
+"""Typer application for the flow-state command-line interface."""
+
+# --------------------------------------------------
+# load necessary modules
+# --------------------------------------------------
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from flow_state.cli.callbacks import verbose_callback, version_callback
+from flow_state.cli.cmd_examples import cmd_examples
+from flow_state.cli.cmd_init import cmd_init
+from flow_state.cli.cmd_recover import cmd_recover
+from flow_state.cli.cmd_run import cmd_run
+
+# --------------------------------------------------
+# app
+# --------------------------------------------------
+app = typer.Typer(
+    name="flow-state",
+    help="Compute flow states.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+
+# --------------------------------------------------
+# callback for --version and --verbose options
+# version_callback and verbose_callback are defined in callbacks.py
+# --------------------------------------------------
+@app.callback()
+def main(
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show version and exit.",
+            callback=version_callback,
+            is_eager=True,
+        ),
+    ] = None,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Enable verbose (debug) output.",
+            callback=verbose_callback,
+        ),
+    ] = False,
+) -> None:
+    """Compute flow states from freestream, stagnation, or atmospheric inputs."""
+
+    # both options act through their callbacks; nothing left to do here
+    del version, verbose
+
+
+# --------------------------------------------------
+# register subcommands
+# notes:
+# - the order at which they are registered is the order in which they display
+# --------------------------------------------------
+app.command(name="init")(cmd_init)
+app.command(name="run")(cmd_run)
+app.command(name="recover")(cmd_recover)
+app.command(name="examples")(cmd_examples)
+
+# --------------------------------------------------
+# main entry point
+# --------------------------------------------------
+if __name__ == "__main__":
+    app()

flowstate-0.7.0/src/flow_state/cli/callbacks.py

@@ -0,0 +1,51 @@
+"""Shared callbacks for the flow-state command-line interface."""
+
+# --------------------------------------------------
+# load necessary modules
+# --------------------------------------------------
+from __future__ import annotations
+
+import logging
+
+import typer
+
+from flow_state import __version__
+
+# --------------------------------------------------
+# module constants
+# --------------------------------------------------
+
+# loggers that --verbose switches to debug: this tool and the uahypersonics
+# packages it calls
+DEBUG_LOGGERS = ("flow_state",)
+
+
+# --------------------------------------------------
+# verbose callback
+# --------------------------------------------------
+def verbose_callback(value: bool) -> None:
+    """Configure console logging; --verbose adds debug output from our own packages.
+
+    Third-party libraries stay at the default level, so --verbose shows our
+    debug messages without theirs.
+    """
+
+    # default console logging for every logger
+    logging.basicConfig(level=logging.INFO, format="%(levelname)-8s %(message)s")
+
+    # debug output from this tool and the uahypersonics packages it calls
+    if value:
+        for logger_name in DEBUG_LOGGERS:
+            logging.getLogger(logger_name).setLevel(logging.DEBUG)
+
+
+# --------------------------------------------------
+# version callback
+# --------------------------------------------------
+def version_callback(value: bool) -> None:
+    """Print the installed package version and exit."""
+
+    # print the version and stop before any command runs
+    if value:
+        typer.echo(f"flow-state version {__version__}")
+        raise typer.Exit()

flowstate-0.7.0/src/flow_state/cli/cmd_examples.py

@@ -0,0 +1,63 @@
+"""List bundled example cases, or copy one into the current folder."""
+
+# --------------------------------------------------
+# load necessary modules
+# --------------------------------------------------
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from flow_state.io.examples import copy_example, list_examples
+
+
+# --------------------------------------------------
+# subcommand: examples
+# --------------------------------------------------
+def cmd_examples(
+    name: Annotated[
+        str | None,
+        typer.Argument(help="Example to copy into the current folder. Omit to list the examples."),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Overwrite files of the same name in this folder."),
+    ] = False,
+) -> None:
+    """List the bundled examples, or copy one into the current folder to run."""
+
+    # list: name and description of every example
+    examples = list_examples()
+    if name is None:
+        width = max(len(example_name) for example_name in [*examples, "<name>"])
+        typer.echo("")
+        typer.echo(f"  {'<name>':<{width}}  description")
+        typer.echo(f"  {'-'*width}  {'-'*11}")
+        for example_name, description in examples.items():
+            typer.echo(f"  {example_name:<{width}}  {description}")
+        typer.echo("")
+        typer.echo("command sequence:")
+        typer.echo("  - check out the example")
+        typer.echo("     flow-state examples <name>")
+        typer.echo("  - run the example")
+        typer.echo("     flow-state run")
+        typer.echo("")
+        return
+
+    # copy the example into the current folder
+    try:
+        written = copy_example(name, Path("."), force=force)
+    except KeyError:
+        known = ", ".join(examples)
+        typer.echo(f"error: unknown example {name!r}; available: {known}", err=True)
+        raise typer.Exit(1) from None
+    except FileExistsError as error:
+        typer.echo(f"error: {error}", err=True)
+        raise typer.Exit(1) from None
+
+    # report the files and the next step
+    for path in written:
+        typer.echo(f"wrote {path}")
+    typer.echo("then: flow-state run")

{flowstate-0.6.2 → flowstate-0.7.0}/src/flow_state/cli/cmd_init.py

@@ -1,5 +1,8 @@
 """Generate a starter flow-state configuration."""
 
+# --------------------------------------------------
+# load necessary modules
+# --------------------------------------------------
 from __future__ import annotations
 
 from pathlib import Path
@@ -11,6 +14,9 @@ from flow_state.cli.constants import DEFAULT_CONFIG
 from flow_state.cli.templates import CONFIG_TEMPLATE
 
 
+# --------------------------------------------------
+# subcommand: init
+# --------------------------------------------------
 def cmd_init(
     output: Annotated[
         Path,
@@ -23,10 +29,12 @@ def cmd_init(
 ) -> None:
     """Generate a documented template configuration file."""
 
+    # check: don't overwrite an existing configuration unless asked to
     if output.exists() and not force:
         typer.echo(f"Error: {output} already exists. Use --force to overwrite", err=True)
         raise typer.Exit(1)
 
+    # write the template and tell the user the next step
     output.write_text(CONFIG_TEMPLATE)
     typer.echo(f"Created {output}")
-    typer.echo("Edit the file, then run: flow-state solve")
+    typer.echo("Edit the file, then run: flow-state run")

{flowstate-0.6.2 → flowstate-0.7.0}/src/flow_state/cli/cmd_recover.py

@@ -1,5 +1,8 @@
 """Recover and write flow conditions from HDF5 metadata."""
 
+# --------------------------------------------------
+# load necessary modules
+# --------------------------------------------------
 from __future__ import annotations
 
 from pathlib import Path
@@ -12,6 +15,9 @@ from flow_state.io import write_json
 from flow_state.recover import recover_from_hdf5
 
 
+# --------------------------------------------------
+# subcommand: recover
+# --------------------------------------------------
 def cmd_recover(
     input_file: Annotated[
         Path,
@@ -31,14 +37,19 @@ def cmd_recover(
     ] = False,
 ) -> None:
     """Recover flow_conditions.json from HDF5 root attributes."""
+
+    # read: rebuild the flow state from the HDF5 root attributes
     try:
         state = recover_from_hdf5(input_file)
     except (FileNotFoundError, OSError, TypeError, ValueError) as error:
         typer.echo(f"Error recovering flow state: {error}", err=True)
         raise typer.Exit(1) from error
 
+    # write the flow-state JSON
     write_json(state, output)
     typer.echo(f"Wrote {output}")
+
+    # print the summary unless --quiet
     if not quiet:
         typer.echo("")
         typer.echo(str(state))

flowstate-0.6.2/src/flow_state/cli/cmd_solve.py → flowstate-0.7.0/src/flow_state/cli/cmd_run.py

@@ -1,5 +1,8 @@
 """Compute and write a flow state from CLI or TOML inputs."""
 
+# --------------------------------------------------
+# load necessary modules
+# --------------------------------------------------
 from __future__ import annotations
 
 import logging
@@ -12,10 +15,16 @@ from flow_state.cli.constants import DEFAULT_CONFIG, DEFAULT_OUTPUT
 from flow_state.io import read_config, write_flow_conditions_dat, write_json
 from flow_state.solvers import solve
 
+# --------------------------------------------------
+# set up logger
+# --------------------------------------------------
 logger = logging.getLogger(__name__)
 
 
-def cmd_solve(
+# --------------------------------------------------
+# subcommand: run
+# --------------------------------------------------
+def cmd_run(
     mach: Annotated[float | None, typer.Option("--mach", "-m", help="Mach number")] = None,
     pres_stag: Annotated[
         float | None,
@@ -93,8 +102,10 @@ def cmd_solve(
 ) -> None:
     """Compute a flow state from direct options or a configuration file."""
 
+    # check: direct options on the command line take precedence over a config file
     has_direct_options = any([mach, pres_stag, temp_stag, altitude, pres, temp, re1])
 
+    # build the solver inputs from the direct options given (units as (value, unit) tuples)
     if has_direct_options:
         solve_kwargs: dict[str, object] = {}
         if mach is not None:
@@ -118,7 +129,10 @@ def cmd_solve(
         if lref is not None:
             solve_kwargs["lref"] = lref
     else:
+        # read the solver inputs from the config file (default: flow_config.toml)
         config_path = config if config else Path(DEFAULT_CONFIG)
+
+        # check: the config exists, otherwise point to `flow-state init`
         if not config_path.exists():
             typer.echo(f"Error: {config_path} not found.", err=True)
             typer.echo(
@@ -127,32 +141,38 @@ def cmd_solve(
             )
             raise typer.Exit(1)
 
+        # read and parse the config
         try:
             solve_kwargs = read_config(config_path)
-        except Exception as error:
+        except (OSError, ValueError) as error:
             typer.echo(f"Error parsing {config_path}: {error}", err=True)
             raise typer.Exit(1) from error
 
+    # compute the flow state
     try:
         state = solve(**solve_kwargs)
     except (ValueError, TypeError) as error:
         typer.echo(f"Error computing flow state: {error}", err=True)
         raise typer.Exit(1) from error
 
+    # debug output for devs
     if state.provenance:
         for key, value in state.provenance.items():
             logger.debug("%s: %s", key, value)
     logger.debug("gas_model:       %s", state.gas_model)
     logger.debug("transport_model: %s", state.transport_model)
 
+    # write the flow-state JSON
     write_json(state, output)
     typer.echo(f"Wrote {output}")
 
+    # write the legacy flow_conditions.dat when asked for
     if dat:
         dat_path = Path("flow_conditions.dat")
         write_flow_conditions_dat(state, dat_path)
         typer.echo(f"Wrote {dat_path}")
 
+    # print the summary unless --quiet
     if not quiet:
         typer.echo("")
         typer.echo(str(state))

flowstate-0.7.0/src/flow_state/cli/constants.py

@@ -0,0 +1,11 @@
+"""Shared constants for flow-state CLI commands."""
+
+# --------------------------------------------------
+# default file names
+# --------------------------------------------------
+
+# configuration file written by `flow-state init` and read by `flow-state run`
+DEFAULT_CONFIG = "flow_config.toml"
+
+# flow-state JSON written by `flow-state run` and `flow-state recover`
+DEFAULT_OUTPUT = "flow_conditions.json"

{flowstate-0.6.2 → flowstate-0.7.0}/src/flow_state/cli/templates.py

@@ -1,9 +1,14 @@
 """Configuration templates emitted by flow-state CLI commands."""
 
+# --------------------------------------------------
+# configuration template
+# --------------------------------------------------
+
+# starter flow_config.toml written by `flow-state init`
 CONFIG_TEMPLATE = """\
 # flow_state configuration file
 # =============================
-# Edit the values below and run: flow-state solve
+# Edit the values below and run: flow-state run
 
 # Supported units:
 #   pressure    : Pa, psi, atm, bar, torr

flowstate-0.6.2/src/flow_state/examples/aedc_t9.toml → flowstate-0.7.0/src/flow_state/examples/aedc_t9/flow_config.toml

@@ -1,7 +1,7 @@
 # --------------------------------------------------
 # AEDC Tunnel 9 (Arnold Engineering Development Complex)
 #
-# Run: flow-state solve --config flow_config.toml
+# Run: flow-state run --config flow_config.toml
 # --------------------------------------------------
 
 # --------------------------------------------------

flowstate-0.6.2/src/flow_state/examples/bam6qt.toml → flowstate-0.7.0/src/flow_state/examples/bam6qt/flow_config.toml

@@ -1,7 +1,7 @@
 # --------------------------------------------------
 # BAM6QT — Boeing/AFOSR Mach 6 Quiet Tunnel (Purdue University)
 #
-# Run: flow-state solve --config flow_config.toml
+# Run: flow-state run --config flow_config.toml
 # --------------------------------------------------
 
 # --------------------------------------------------

flowstate-0.6.2/src/flow_state/examples/sandia.toml → flowstate-0.7.0/src/flow_state/examples/sandia/flow_config.toml

@@ -1,7 +1,7 @@
 # --------------------------------------------------
 # Sandia Hypersonic Wind Tunnel
 #
-# Run: flow-state solve --config flow_config.toml
+# Run: flow-state run --config flow_config.toml
 # --------------------------------------------------
 
 # --------------------------------------------------

flowstate-0.6.2/src/flow_state/examples/stort.toml → flowstate-0.7.0/src/flow_state/examples/stort/flow_config.toml

@@ -1,7 +1,7 @@
 # --------------------------------------------------
 # STORT (Short Range Transition)
 #
-# Run: flow-state solve --config flow_config.toml
+# Run: flow-state run --config flow_config.toml
 # --------------------------------------------------
 
 # --------------------------------------------------

flowstate-0.7.0/src/flow_state/io/examples.py

@@ -0,0 +1,122 @@
+"""Bundled example cases for the flow-state CLI.
+
+Each example is a folder under ``flow_state/examples/`` holding the files of
+one case (here a ``flow_config.toml``). The folder name is the example's name
+and the first text line of its config is the description, so the folders are
+the registry: adding an example means adding a folder.
+
+Adding a new example
+--------------------
+1. Add ``src/flow_state/examples/<name>/flow_config.toml``.
+2. Start the file with a comment that names the case (shown in the listing).
+"""
+
+# --------------------------------------------------
+# load necessary modules
+# --------------------------------------------------
+from __future__ import annotations
+
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+# --------------------------------------------------
+# module constants
+# --------------------------------------------------
+
+# config file every example holds (run's default config name)
+EXAMPLE_CONFIG = "flow_config.toml"
+
+
+# --------------------------------------------------
+# helpers
+# --------------------------------------------------
+def _examples_root() -> Traversable:
+    """Folder of the bundled examples inside the installed package."""
+    return files("flow_state") / "examples"
+
+
+def _description(config_text: str) -> str:
+    """First text line of a config's header comment (dividers skipped)."""
+
+    # walk the leading comment block
+    for line in config_text.splitlines():
+        stripped = line.strip()
+
+        # the header ends at the first line that isn't a comment
+        if stripped and not stripped.startswith("#"):
+            break
+
+        # skip blank comment lines and dividers like "# -----"
+        text = stripped.lstrip("#").strip()
+        if text and set(text) - set("-=#"):
+            return text
+
+    return ""
+
+
+# --------------------------------------------------
+# public API
+# --------------------------------------------------
+def list_examples() -> dict[str, str]:
+    """Return a name -> description mapping of the bundled examples.
+
+    Returns:
+        Dict of {name: description}, sorted by name.
+    """
+
+    # every folder with a config is an example
+    examples: dict[str, str] = {}
+    for folder in sorted(_examples_root().iterdir(), key=lambda item: item.name):
+        config = folder / EXAMPLE_CONFIG
+        if folder.is_dir() and config.is_file():
+            examples[folder.name] = _description(config.read_text(encoding="utf-8"))
+
+    return examples
+
+
+def copy_example(name: str, destination: str | Path, force: bool = False) -> list[Path]:
+    """Copy a bundled example's files into a folder.
+
+    Args:
+        name: Example name (see list_examples).
+        destination: Folder to copy the files into (created if missing).
+        force: Overwrite files of the same name in the folder.
+
+    Returns:
+        The paths of the written files.
+
+    Raises:
+        KeyError: If there is no example of that name.
+        FileExistsError: If a file of the example already exists there and force
+            is False (nothing is written then).
+    """
+
+    # check: a known example
+    if name not in list_examples():
+        raise KeyError(name)
+
+    # the example's files
+    source = _examples_root() / name
+    items = sorted(
+        (entry for entry in source.iterdir() if entry.is_file()),
+        key=lambda entry: entry.name,
+    )
+
+    # check: don't overwrite the user's files unless asked to (before writing any)
+    destination = Path(destination)
+    existing = [item.name for item in items if (destination / item.name).exists()]
+    if existing and not force:
+        raise FileExistsError(
+            f"would overwrite {', '.join(existing)} (use --force to overwrite)"
+        )
+
+    # copy every file of the example folder
+    destination.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    for item in items:
+        target = destination / item.name
+        target.write_bytes(item.read_bytes())
+        written.append(target)
+
+    return written