grid-generator 0.2.0__tar.gz → 0.3.0__tar.gz

{grid_generator-0.2.0 → grid_generator-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grid-generator
-Version: 0.2.0
+Version: 0.3.0
 Summary: Structured grid generation utilities for Python
 Author-email: Christoph Hader <christoph.hader@gmail.com>
 License-Expression: GPL-3.0-or-later

{grid_generator-0.2.0 → grid_generator-0.3.0}/pyproject.toml

@@ -54,6 +54,10 @@ Documentation = "https://uahypersonics.github.io/grid-generator"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+# bundled example cases: examples/<geometry type>/<name>/<files>
+"grid_generator" = ["examples/*/*/*"]
+
 [tool.setuptools_scm]
 
 [tool.pytest.ini_options]

{grid_generator-0.2.0 → grid_generator-0.3.0}/src/grid_generator/body_fitted.py

@@ -12,8 +12,17 @@ polar about the nose centre), then the configured body distribution starting fro
 the nose spacing, so the spacing is continuous across the junction. The body may be
 straight (plate, wedge, cone) or curved (tangent ogive, with an optional cylinder).
 
-No shock alignment yet: H is constant, and the user picks it large enough to
-clear the bow shock.
+H is either constant ([domain] height, picked large enough to clear the bow shock),
+or the grid has a shock-aligned outer boundary ([outer]): a smooth curve a margin
+beyond the shock, with the outer points spaced smoothly along it (see
+grid_generator.outer). Each line then leaves the wall along the normal and bends
+toward its outer point,
+
+    x(i, j) = wall(s_i) + n_j * normal(s_i) + (n_j / h_i)^2 * shift_i,
+
+with h_i the outer point's distance along the normal and shift_i its offset across
+it. The wall-normal distribution keeps its first spacing and point count on every
+line; only its stretching follows the line's height.
 
 With a [span] table (plate and wedge), the 2D plane is extruded in z: the same
 (x, y) plane at every z of the span distribution, giving a 3D grid.
@@ -37,26 +46,27 @@ from grid_generator.config.body_fitted import (
     load_body_fitted_config,
 )
 from grid_generator.distributions import DistributionSpec, EquidistantSpec, build_distribution
+from grid_generator.outer import outer_points, read_shock_curve
 
 # --------------------------------------------------
 # constants
 # --------------------------------------------------
 
-# SU2 / Gmsh boundary names for the four sides of the grid: imin is the stagnation
-# line ahead of the nose, imax the outflow at x_end, jmin the wall, jmax the outer
-# boundary
-BOUNDARY_MARKERS = {
-    "imin": "symmetry",
-    "imax": "outflow",
-    "jmin": "wall",
-    "jmax": "farfield",
+# grid side of each [markers] key (the names themselves come from the config): imin is
+# the stagnation line ahead of the nose, imax the outflow at x_end, jmin the wall,
+# jmax the outer boundary
+MARKER_SIDES = {
+    "symmetry": "imin",
+    "outflow": "imax",
+    "wall": "jmin",
+    "outer": "jmax",
 }
 
-# boundary names for the two extra sides of an extruded (3D) grid: the first and last
-# z-planes; the solver decides what they are (periodic, symmetry, ...)
-SPAN_MARKERS = {
-    "kmin": "span_min",
-    "kmax": "span_max",
+# the two extra sides of an extruded (3D) grid: the first and last z-planes; the
+# solver decides what they are (periodic, symmetry, ...)
+SPAN_MARKER_SIDES = {
+    "span_min": "kmin",
+    "span_max": "kmax",
 }
 
 
@@ -88,16 +98,12 @@ def generate_body_fitted(source: BodyFittedConfig | str | Path) -> Dataset:
     # arc lengths of the wall points: nose, then body
     s_wall = wall_arc_lengths(profile, config.points.nose.n_points, config.body_distribution())
 
-    # wall-normal distances: from the wall up to the height
-    n_dist = build_distribution(config.normal_distribution())
-
     # exact wall points and normals
     x_wall, y_wall = profile.point(s_wall)
     nx, ny = profile.normal(s_wall)
 
-    # j-lines straight out along the wall normals: (ni, nj)
-    x_plane = x_wall[:, None] + n_dist[None, :] * nx[:, None]
-    y_plane = y_wall[:, None] + n_dist[None, :] * ny[:, None]
+    # j-lines from the wall out to the outer boundary: (ni, nj)
+    x_plane, y_plane = build_grid_lines(config, x_wall, y_wall, nx, ny)
 
     # span: the z-planes to extrude to, or the single plane z = 0 for a 2D grid
     if config.span is not None:
@@ -112,10 +118,13 @@ def generate_body_fitted(source: BodyFittedConfig | str | Path) -> Dataset:
     z = np.broadcast_to(z_axis[None, None, :], x.shape).copy()
     grid = StructuredGrid(x=x, y=y, z=z)
 
-    # markers: four sides in 2D, plus the two z-planes in 3D
-    markers = dict(BOUNDARY_MARKERS)
+    # markers: four sides in 2D, plus the two z-planes in 3D, named by [markers]
+    markers = {}
+    for key, side in MARKER_SIDES.items():
+        markers[side] = getattr(config.markers, key)
     if nk > 1:
-        markers.update(SPAN_MARKERS)
+        for key, side in SPAN_MARKER_SIDES.items():
+            markers[side] = getattr(config.markers, key)
     dimensionality = 3 if nk > 1 else 2
 
     # describe the grid; markers are what cfd-io's SU2 writer needs
@@ -139,6 +148,88 @@ def generate_body_fitted(source: BodyFittedConfig | str | Path) -> Dataset:
     return dataset
 
 
+def build_grid_lines(
+    config: BodyFittedConfig,
+    x_wall: NDArray[np.float64],
+    y_wall: NDArray[np.float64],
+    nx: NDArray[np.float64],
+    ny: NDArray[np.float64],
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """The j-lines: from each wall point out to the outer boundary.
+
+    Args:
+        config: Validated configuration.
+        x_wall: Wall points x [m].
+        y_wall: Wall points y [m].
+        nx: Unit wall normals, x component.
+        ny: Unit wall normals, y component.
+
+    Returns:
+        Grid x and y [m], shape (ni, nj).
+
+    Raises:
+        ValueError: If a wall normal misses the outer boundary, or [points.normal]
+            doesn't give every line the same number of points.
+    """
+
+    # constant height: straight lines along the wall normals, all with the same distribution
+    if config.outer is None:
+        n_line = build_distribution(config.normal_distribution())
+        x_plane = x_wall[:, None] + n_line[None, :] * nx[:, None]
+        y_plane = y_wall[:, None] + n_line[None, :] * ny[:, None]
+        return x_plane, y_plane
+
+    # shock-aligned: the outer end of every line, on a smooth curve beyond the shock
+    shock_x, shock_y = read_shock_curve(config.outer.shock)
+    outer_x, outer_y = outer_points(
+        x_wall,
+        y_wall,
+        nx,
+        ny,
+        shock_x,
+        shock_y,
+        config.outer.margin_factor,
+        config.outer.min_offset,
+    )
+
+    # each line: along the normal at the wall, bending toward its outer point
+    lines_x = []
+    lines_y = []
+    for i in range(x_wall.size):
+        # split the reach into a part along the normal and a shift across it
+        reach_x = outer_x[i] - x_wall[i]
+        reach_y = outer_y[i] - y_wall[i]
+        height = reach_x * nx[i] + reach_y * ny[i]
+        shift_x = reach_x - height * nx[i]
+        shift_y = reach_y - height * ny[i]
+
+        # the same normal distribution (first spacing, points) stretched to this height
+        try:
+            n_line = build_distribution(config.normal_distribution(float(height)))
+        except ValueError as error:
+            raise ValueError(
+                f"[points.normal] at a line height of {height:.4g} m: {error}"
+            ) from None
+
+        # the shift grows quadratically, so the line leaves the wall along the normal
+        fraction = n_line / height
+        lines_x.append(x_wall[i] + n_line * nx[i] + fraction**2 * shift_x)
+        lines_y.append(y_wall[i] + n_line * ny[i] + fraction**2 * shift_y)
+
+    # check: a structured grid needs the same number of points on every line
+    counts = {line.size for line in lines_x}
+    if len(counts) > 1:
+        raise ValueError(
+            "[points.normal] gives the lines different numbers of points "
+            f"({min(counts)} to {max(counts)}); set n_points for a shock-aligned grid"
+        )
+
+    x_plane = np.vstack(lines_x)
+    y_plane = np.vstack(lines_y)
+
+    return x_plane, y_plane
+
+
 def wall_arc_lengths(
     profile: Profile2D, n_nose: int, body_spec: DistributionSpec
 ) -> NDArray[np.float64]:

{grid_generator-0.2.0 → grid_generator-0.3.0}/src/grid_generator/cartesian.py

@@ -11,8 +11,22 @@ import numpy as np
 from cfd_io import Dataset, StructuredGrid
 
 from grid_generator.config import CartesianConfig, load_cartesian_config
+from grid_generator.config.cartesian import AXIS_MARKER_KEYS
 from grid_generator.distributions import build_distribution
 
+# --------------------------------------------------
+# constants
+# --------------------------------------------------
+# grid side of each [markers] key (the names themselves come from the config)
+MARKER_SIDES = {
+    "x_min": "imin",
+    "x_max": "imax",
+    "y_min": "jmin",
+    "y_max": "jmax",
+    "z_min": "kmin",
+    "z_max": "kmax",
+}
+
 
 # --------------------------------------------------
 # public API
@@ -24,7 +38,8 @@ def generate_cartesian(source: CartesianConfig | str | Path) -> Dataset:
         source: Validated configuration or configuration file path.
 
     Returns:
-        Grid-only CFD dataset with physical coordinate arrays.
+        Grid-only CFD dataset with physical coordinate arrays and the boundary markers
+        of the axes the grid has.
     """
 
     # load configuration when the caller supplied an artifact path
@@ -42,6 +57,15 @@ def generate_cartesian(source: CartesianConfig | str | Path) -> Dataset:
     grid_x, grid_y, grid_z = np.meshgrid(x_axis, y_axis, z_axis, indexing="ij")
     grid = StructuredGrid(x=grid_x, y=grid_y, z=grid_z)
 
+    # markers: both ends of each axis the grid has, named by [markers]
+    active_axes = {"x": config.x, "y": config.y, "z": config.z}
+    markers = {}
+    for axis_name, axis_spec in active_axes.items():
+        if axis_spec is None:
+            continue
+        for key in AXIS_MARKER_KEYS[axis_name]:
+            markers[MARKER_SIDES[key]] = getattr(config.markers, key)
+
     dimensionality = 1 + int(config.y is not None) + int(config.z is not None)
     dataset = Dataset(
         grid=grid,
@@ -54,6 +78,7 @@ def generate_cartesian(source: CartesianConfig | str | Path) -> Dataset:
             "ni": grid.shape[0],
             "nj": grid.shape[1],
             "nk": grid.shape[2],
+            "markers": {"structured": markers},
         },
     )
     return dataset

{grid_generator-0.2.0 → grid_generator-0.3.0}/src/grid_generator/cli/app.py

@@ -7,7 +7,7 @@ from typing import Annotated
 
 import typer
 
-from grid_generator.cli.callbacks import version_callback
+from grid_generator.cli.callbacks import verbose_callback, version_callback
 from grid_generator.cli.cmd_cartesian import cartesian_app
 from grid_generator.cli.cmd_distribution import distribution_app
 from grid_generator.cli.cmd_geometry import GEOMETRY_HELP, build_geometry_app
@@ -38,20 +38,31 @@ def main(
             help="Show version and exit.",
         ),
     ] = False,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            callback=verbose_callback,
+            help="Enable verbose (debug) output.",
+        ),
+    ] = False,
 ) -> None:
     """Generate structured computational grids."""
 
-    del version
+    del version, verbose
 
 
 # --------------------------------------------------
-# register subcommands
+# register subcommands (note: order of registration is order of appearance in the CLI help)
 # --------------------------------------------------
+
+# 1D point distributions: reference (info) and 1D point files (init / run)
+app.add_typer(distribution_app, name="distribution")
+
+# Cartesian grids: structured grids aligned with the coordinate axes
 app.add_typer(cartesian_app, name="cartesian")
 
-# body-fitted grids, one command group per geometry: plate, wedge, cone
+# body-fitted grids, one command group per geometry: plate, wedge, cone, ogive, ... (add more as needed)
 for geometry_type in GEOMETRY_HELP:
     app.add_typer(build_geometry_app(geometry_type), name=geometry_type)
-
-# 1D point distributions: reference (info) and 1D point files (init / run)
-app.add_typer(distribution_app, name="distribution")

grid_generator-0.3.0/src/grid_generator/cli/callbacks.py

@@ -0,0 +1,47 @@
+"""Shared callbacks for the grid-generator CLI."""
+
+# --------------------------------------------------
+# load necessary modules
+# --------------------------------------------------
+import logging
+
+import typer
+
+from grid_generator import __version__
+
+
+# --------------------------------------------------
+# callbacks
+# --------------------------------------------------
+def version_callback(value: bool) -> None:
+    """Print the installed package version and exit."""
+
+    if value:
+        typer.echo(f"grid-generator {__version__}")
+        raise typer.Exit()
+
+
+# --------------------------------------------------
+# verbose callback
+# --------------------------------------------------
+
+# loggers that --verbose switches to debug: this tool and the uahypersonics
+# packages it calls
+DEBUG_LOGGERS = ("grid_generator", "canonical_geometries", "cfd_io")
+
+
+def verbose_callback(value: bool) -> None:
+    """Configure console logging; --verbose adds debug output from our own packages.
+
+    By default only warnings are shown. With --verbose, this tool and the
+    packages it calls (e.g. cfd-io writing a grid) log at debug level, while
+    third-party libraries (h5py, ...) stay quiet.
+    """
+
+    # default console logging for every logger: warnings only
+    logging.basicConfig(level=logging.WARNING, 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)

{grid_generator-0.2.0 → grid_generator-0.3.0}/src/grid_generator/cli/cmd_geometry.py

@@ -12,6 +12,7 @@ from typing import Annotated
 import typer
 
 from grid_generator.body_fitted import generate_body_fitted
+from grid_generator.cli.examples_command import build_examples_command, list_examples
 from grid_generator.cli.help_text import format_examples
 from grid_generator.config import (
     BODY_BLOCKS,
@@ -187,4 +188,8 @@ def build_geometry_app(geometry_type: str) -> typer.Typer:
         typer.echo(quality.summary())
         typer.echo(f"Wrote: {output_path}")
 
+    # examples: bundled cases, copied into ./<name>/ to run (only types that ship some)
+    if list_examples(geometry_type):
+        geometry_app.command("examples")(build_examples_command(geometry_type))
+
     return geometry_app

grid_generator-0.3.0/src/grid_generator/cli/examples_command.py

@@ -0,0 +1,179 @@
+"""Bundled example cases and the `grid-generator <type> examples` command.
+
+Each example is a folder under ``grid_generator/examples/<type>/`` holding the
+files of one case, with the config named like run's default (e.g. ``cone.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.
+"""
+
+# --------------------------------------------------
+# load necessary modules
+# --------------------------------------------------
+from __future__ import annotations
+
+from collections.abc import Callable
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+
+# --------------------------------------------------
+# helpers
+# --------------------------------------------------
+def _type_root(geometry_type: str) -> Traversable:
+    """Folder of one geometry type's examples inside the installed package."""
+    return files("grid_generator") / "examples" / geometry_type
+
+
+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(geometry_type: str) -> dict[str, str]:
+    """Return a name -> description mapping of one geometry type's examples.
+
+    Args:
+        geometry_type: Geometry type, e.g. "cone".
+
+    Returns:
+        Dict of {name: description}, sorted by name (empty without examples).
+    """
+
+    # a type without examples has no folder
+    root = _type_root(geometry_type)
+    if not root.is_dir():
+        return {}
+
+    # every folder with the type's config is an example
+    examples: dict[str, str] = {}
+    config_name = f"{geometry_type}.toml"
+    for folder in sorted(root.iterdir(), key=lambda item: item.name):
+        config = folder / config_name
+        if folder.is_dir() and config.is_file():
+            examples[folder.name] = _description(config.read_text(encoding="utf-8"))
+
+    return examples
+
+
+def copy_example(
+    geometry_type: str, name: str, destination: str | Path, force: bool = False
+) -> list[Path]:
+    """Copy one example's files into a folder.
+
+    Args:
+        geometry_type: Geometry type, e.g. "cone".
+        name: Example name (see list_examples).
+        destination: Folder to create and copy the files into.
+        force: Overwrite files that already exist in the folder.
+
+    Returns:
+        The paths of the written files.
+
+    Raises:
+        KeyError: If the type has no example of that name.
+        FileExistsError: If the folder exists and force is False.
+    """
+
+    # check: a known example
+    if name not in list_examples(geometry_type):
+        raise KeyError(name)
+
+    # check: don't overwrite an earlier copy unless asked to
+    destination = Path(destination)
+    if destination.exists() and not force:
+        raise FileExistsError(f"{destination} already exists (use --force to overwrite)")
+
+    # copy every file of the example folder
+    destination.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    source = _type_root(geometry_type) / name
+    for item in sorted(source.iterdir(), key=lambda entry: entry.name):
+        if item.is_file():
+            target = destination / item.name
+            target.write_bytes(item.read_bytes())
+            written.append(target)
+
+    return written
+
+
+def build_examples_command(geometry_type: str) -> Callable[..., None]:
+    """Build the `examples` subcommand of one geometry type.
+
+    Args:
+        geometry_type: Geometry type, e.g. "cone" (also the examples folder).
+
+    Returns:
+        The command function to register as ``<geometry_app>.command("examples")``.
+    """
+
+    def cmd_examples(
+        name: Annotated[
+            str | None,
+            typer.Argument(help="Example to copy into ./<name>/. Omit to list the examples."),
+        ] = None,
+        force: Annotated[
+            bool,
+            typer.Option("--force", "-f", help="Overwrite an existing ./<name>/ folder."),
+        ] = False,
+    ) -> None:
+        """List the bundled examples, or copy one into a new folder to run."""
+
+        # list: name and description of every example
+        examples = list_examples(geometry_type)
+        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(f"     grid-generator {geometry_type} examples <name>")
+            typer.echo("  - change into its folder")
+            typer.echo("     cd <name>")
+            typer.echo("  - run the example")
+            typer.echo(f"     grid-generator {geometry_type} run")
+            typer.echo("")
+            return
+
+        # copy the example into ./<name>/
+        try:
+            written = copy_example(geometry_type, name, Path(name), 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(f"then: cd {name} && grid-generator {geometry_type} run")
+
+    return cmd_examples