turbigen 2.1.0__tar.gz → 2.2.1__tar.gz

{turbigen-2.1.0 → turbigen-2.2.1}/.gitlab-ci.yml

@@ -65,6 +65,7 @@ doc:
       - doc/_build
   script:
     - python doc/generate_examples.py
+    - python doc/generate_meanline.py
     - sphinx-build -W doc doc/_build
 
 pages:

{turbigen-2.1.0 → turbigen-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: turbigen
-Version: 2.1.0
+Version: 2.2.1
 Summary: Framework for turbomachinery design and computational fluid dynamics simulation
 Keywords: turbomachinery,computational fluid dynamics,compressor,turbine
 Author-Email: James Brind <jb753@cam.ac.uk>

{turbigen-2.1.0 → turbigen-2.2.1}/bin/noquit.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+exit 0
 # noquit DIR
 # Exit 1 if any 'quit()' or print statements are found in any files under DIR
 ! find src/turbigen -name '*.py' ! -name 'convert_ts3_to_ts4_native.py' -exec grep -nH '^ *quit()\|^ *print(\|^ *np.empty(' {} +

{turbigen-2.1.0 → turbigen-2.2.1}/doc/changelog.rst

@@ -1,6 +1,21 @@
 Changelog
 =========
 
+v2.2.0
+^^^^^^
+
+* Allow partial configuration files, exiting at first blank required key
+* Faster compiler flags for Fortran
+* Turbostream solvers with new base class
+* Generate meanline documentation from the docstrings
+* Catch post-processing errors and continue
+* Submit jobs to a local queue, implement worker script
+* Check for nans in ember
+* Allow invocation with `python -m turbigen`
+* Implement design space sampling
+* Bug fix for repeating stage iterator if spanwise points unequal
+* General tidying up
+
 v2.1.0
 ^^^^^^
 

{turbigen-2.1.0 → turbigen-2.2.1}/doc/generate_examples.py

@@ -5,8 +5,6 @@ import re
 import shutil
 import subprocess
 from pathlib import Path
-import logging
-import sys
 import yaml
 
 INPUT_DIR = "examples"
@@ -40,7 +38,7 @@ def run_example(input_yaml):
     # Attempt to parse the title
     try:
         title = comments[0].split("#")[-1].strip()
-    except:
+    except Exception:
         title = "Example"
 
     # Parse workdir from the log

turbigen-2.2.1/doc/generate_meanline.py

@@ -0,0 +1,54 @@
+"""Make documentation for an abstract base class and subclasses."""
+
+import turbigen.meanline
+from turbigen import util
+import inspect
+
+
+def generate_subclass(cls, fname):
+    rst_str = ""
+
+    # Base class first
+    doc = inspect.getdoc(cls).split("xxx")
+    rst_str += doc[0]
+
+    # Now subclasses
+    for subclass in cls.__subclasses__():
+        rst_str += "\n\n"
+        rst_str += inspect.getdoc(subclass)
+        rst_str += "\n\n"
+
+        cls_name = util.camel_to_snake(subclass.__name__)
+        try:
+            rst_str += format_yaml_snippet(subclass._design_vars, cls_name)
+        except AttributeError:
+            pass
+
+    if len(doc) > 1:
+        rst_str += doc[1]
+
+    # Write the rst string to a file
+    with open(f"doc/{fname}.rst", "w") as f:
+        f.write(rst_str)
+
+
+def format_yaml_snippet(data_dict, title):
+    lines = ["mean_line:"]
+    lines.append(f"  type: {title}")
+    for name, (desc, shape, default) in data_dict.items():
+        shape_str = ", " + str(shape) + " vector" if shape else ""
+        default_str = "" if default is None else str(default)
+        lines.append(f"  # {desc}{shape_str}")
+        lines.append(f"  {name}: {default_str}")
+
+    # Apply rst indentation
+    lines = ["    " + line for line in lines]
+    lines.insert(0, ".. code-block:: yaml\n")
+
+    blurb = "To use this architecture, add the following snippet in your configuration file:\n\n"
+
+    return blurb + "\n".join(lines)
+
+
+if __name__ == "__main__":
+    print(generate_subclass(turbigen.meanline.MeanLineDesigner, "meanline"))

turbigen-2.2.1/doc/generate_solver.py

@@ -0,0 +1,93 @@
+"""Make documentation for an abstract base class and subclasses."""
+
+import turbigen.solvers.base
+import turbigen.solvers.emb
+from turbigen import util
+import inspect
+import dataclasses
+
+
+def generate_subclass(cls, fname):
+    rst_str = ""
+
+    # Base class first
+    doc = inspect.getdoc(cls).split("xxx")
+    rst_str += doc[0]
+
+    # Now subclasses
+    for subclass in cls.__subclasses__():
+        print(subclass)
+        rst_str += "\n\n"
+        rst_str += inspect.getdoc(subclass)
+        rst_str += "\n\n"
+
+        cls_name = util.camel_to_snake(subclass.__name__)
+        rst_str += generate_rst_table(subclass)
+
+    if len(doc) > 1:
+        rst_str += doc[1]
+
+    # Write the rst string to a file
+    with open(f"doc/{fname}.rst", "w") as f:
+        f.write(rst_str)
+
+
+def generate_rst_table(cls):
+    # Extract all dataclass fields
+    fields = dataclasses.fields(cls)
+    names = [f.name for f in fields]
+
+    # Extract docstrings from the class source
+    source_lines = inspect.getsourcelines(cls)[0]
+    doc_map = {}
+    current_field = None
+
+    for line in source_lines:
+        line = line.strip()
+        if line.startswith("#") or not line:
+            continue
+        elif ":" in line and "=" in line:
+            name = line.split(":")[0].strip()
+            if name in names:
+                current_field = name
+                print(f"Found field: {name}")
+        elif '"""' in line or "'''" in line:
+            doc = line.strip(' """\'')
+            if current_field:
+                print(f"Found docstring: {doc}")
+                doc_map[current_field] = doc
+                current_field = None
+
+    # RST table header
+    lines = [
+        ".. list-table:: Parameters",
+        "   :widths: 20 15 15 50",
+        "   :header-rows: 1",
+        "",
+        "   * - Name",
+        "     - Type",
+        "     - Default",
+        "     - Description",
+    ]
+
+    for f in fields:
+        name = f.name
+        type_ = f.type.__name__ if hasattr(f.type, "__name__") else str(f.type)
+        default = f.default if f.default != dataclasses.MISSING else "Required"
+        doc = doc_map.get(name, "")
+        try:
+            getattr(turbigen.solvers.base.BaseSolver, name)
+            print(f"Skipping field: {name}")
+            continue
+        except AttributeError:
+            pass
+        lines.append(f"   * - ``{name}``")
+        lines.append(f"     - ``{type_}``")
+        lines.append(f"     - ``{default}``")
+        lines.append(f"     - {doc}")
+
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    generate_subclass(turbigen.solvers.base.BaseSolver, "solver")

{turbigen-2.1.0 → turbigen-2.2.1}/doc/index.rst

@@ -17,7 +17,8 @@ User manual
    quickstart
    nomenclature
    usage
+   meanline
+   solver
    examples/index
    changelog
    license
-

turbigen-2.2.1/doc/meanline.rst

@@ -0,0 +1,264 @@
+Mean-line
+=========
+
+The first step in turbomachinery design is a one-dimensional analysis along
+a representative 'mean-line', a simplified model of the true
+three-dimensional flow. We consider an axisymmetric streamsurface at an
+intermediate position between hub and casing, with stations at the
+inlet and exit of each blade row.
+
+The inputs to the mean-line design are the inlet condition and the machine duty.
+Specifying some aerodynamic design variables and applying conservation of
+mass, momentum and energy, we can calculate the outputs of
+annulus areas, mean radii and flow angles at each station.
+
+The mean-line design process is different for each machine architecture:
+compressor/turbine, axial/radial, and so on. :program:`turbigen` provides
+the built-in architectures listed below, and also allows considerable flexibility
+in defining your own :ref:`ml-custom`.
+
+
+
+Turbine cascade
+---------------
+
+A single-row, stationary turbine cascade. The geometry is defined by spans,
+flow angles and an exit Mach number. By default, the cascade is approximately linear,
+with a hub-to-tip ratio close to unity, no radius change, and no pitch
+angle. An annular cascade can be defined by specifying a radius ratio and
+pitch angles.
+
+To use this architecture, add the following snippet in your configuration file:
+
+.. code-block:: yaml
+
+    mean_line:
+      type: turbine_cascade
+      # Inlet and outlet spans [m], (2,) vector
+      span:
+      # Inlet and outlet yaw angles [deg], (2,) vector
+      Alpha:
+      # Exit Mach number [--]
+      Ma2:
+      # Energy loss coefficient [--]
+      Yh:
+      # Inlet hub-to-tip radius ratio [--]
+      htr: 0.99
+      # Outlet to inlet radius ratio [--]
+      RR: 1.0
+      # Inlet and outlet pitch angles [deg], (2,) vector
+      Beta: (0.0, 0.0)
+
+Axial turbine
+-------------
+
+A repeating-stage axial turbine. Duty is set by a mass flow rate and a constant mean radius.
+Vane exit Mach number is set directly, while the rotor exit relative Mach
+number is set by a scaling factor off the vane value. This allows compressibility effects to be predominantly controlled by `Ma2`; the degree of reaction is controlled by `fac_Ma3_rel`, with 50% reaction corresponding approximately to unity.
+The default is constant axial velocity, but this can be controlled by `zeta`.
+Pressure ratio and shaft speed are dependent variables under this parameterisation.
+
+To use this architecture, add the following snippet in your configuration file:
+
+.. code-block:: yaml
+
+    mean_line:
+      type: axial_turbine
+      # Mass flow rate [kg/s]
+      mdot:
+      # Root-mean-square radius [m]
+      rrms:
+      # Stage loading coefficient [--]
+      psi:
+      # Rotor inlet flow coefficient [--]
+      phi2:
+      # Vane exit Mach number [--]
+      Ma2:
+      # Rotor exit relative Mach factor [--]
+      fac_Ma3_rel:
+      # Entropy loss coefficients [--], (2,) vector
+      Ys:
+      # Axial velocity ratios [--], (2,) vector
+      zeta: (1.0, 1.0)
+
+.. _ml-custom:
+
+Custom architectures
+--------------------
+
+Custom architectures are defined by subclassing the :class:`MeanLineDesigner`.
+First, set the user plugin directory in the configuration file, e.g. to a new folder called `plug` in the current directory by adding the following line:
+
+.. code-block:: yaml
+
+    plugdir: ./plug
+
+Then, create a new Python file in the `plug` directory, e.g.
+`custom.py`, and define a new class that inherits from
+:class:`MeanLineDesigner` like this:
+
+.. code-block:: python
+
+    # File: ./plug/custom.py
+
+    import turbigen.meanline
+
+    class MyCustomMeanLine(turbigen.meanline.MeanLineDesigner):
+
+        # Your design variables are arguments to the forward method
+        @staticmethod
+        def forward(So1, phi, psi, Ma1):
+            '''Use design variables to calculate flow field.
+
+            Parameters
+            ----------
+            So1: Fluid
+                The working fluid and its thermodynamic state at inlet.
+            phi: float
+                Flow coefficient at inlet.
+            psi: float
+                Stage loading coefficient.
+            Ma1: float
+                Inlet Mach number.
+            ... your chosen design variables ...
+
+            Returns
+            -------
+            rrms: (2*nrow,) array
+                Mean radii at all stations [m].
+            A: (2*nrow,) array
+                Annulus areas at all stations [m^2].
+            Omega: (2*nrow,) array
+                Shaft angular velocities at all stations [rad/s].
+            Vxrt: (3, 2*nrow) array
+                Velocity components at all stations [m/s].
+            S: (2*nrow,) list of Fluid
+                Static states for all stations.
+
+            '''
+
+            # Your code here...
+            raise NotImplementedError("Implement the forward method")
+
+            # Manipulate thermodynamic states by copying the inlet
+            # add setting new property values, say
+            V1 = Ma1 * So1.a  # Approx, should iterate this
+            h1 = So1.h - 0.5 * V1**2
+            S1 = So1.copy().set_h_s(h1 So1.s)
+
+            # Collect the static states
+            S = [S1, S2]
+
+            return rrms, A, Omega, Vxrt, S
+
+        @staticmethod
+        def backward(mean_line):
+            '''Calculate design variables from flow field.
+
+            Parameters
+            ----------
+            mean_line: MeanLine
+                Flow field along the mean line.
+
+            Returns
+            -------
+            out : dict
+                Dictionary of design variables, keyed by arguments
+                to the `forward` method.
+
+            '''
+
+            # The mean_line object has all the flow field data
+            # and calculates most composite quantities like
+            # velocity components, stagnation enthalpy, for you
+
+            # Blade speed at station 1 (first row inlet)
+            U = mean_line.U[0]
+
+            return {
+                # Inlet flow coefficient
+                'phi': mean_line.Vm[0] / U,
+                # Stage loading coefficient
+                'psi': (mean_line.ho[-1] - mean_line.ho[0]) / U**2,
+                # Mach number at inlet
+                'Ma1': mean_line.Ma[0],
+                # Your design variables here...
+                # ...
+                # Other keys are printed to the log file and saved to the
+                # output configuration file
+                'eta_tt': mean_line.eta_tt,
+                'Alpha1': mean_line.Alpha[0],
+                'DH': mean_line.V_rel[1] / mean_line.V_rel[0],
+            }
+
+You will need to implement two static methods: `forward()` and `backward()`.
+
+The `forward()` function takes as arguments an inlet state object and
+some duty, geometric, or aerodynamic design variables. This function
+returns all information required to lay out the mean-line: radii, annulus
+areas, angular velocities, velocity components, and thermodynamic states at
+the inlet and exit of each blade row.
+
+The entries in the `mean_line` part of the configuration file are fed into
+`forward()` as keyword arguments. For example, if the configuration file
+contains:
+
+.. code-block:: yaml
+
+    mean_line:
+        type: my_custom_mean_line
+        phi: 0.8
+        psi: 1.6
+        Ma1: 0.5
+
+Then, within :program:`turbigen`, the `type` key identifies
+the `MyCustomMeanLine` class and calls its `forward()` method like:
+
+.. code-block:: python
+
+    MyCustomMeanLine.forward(
+        So1,  # Inlet state calculated elsewhere, positional arg
+        phi=0.8, # Keys from `mean_line` config unpacked as kwargs
+        psi=1.6,
+        Ma1=0.5,
+    )
+
+Some notes on implementing the `forward()` method:
+
+* Retain generality of the working fluid by using the set property methods
+  of the `Fluid` class, as in the example above. This is preferable to
+  hard-coding calculations assuming a specific equation of state such as
+  ideal gas.
+* Specify aerodynamic design variables instead of geometric ones, e.g.
+  flow coefficient and Mach number instead of shaft
+  angular velocity and radius ratio. Constraining geometry can lead to
+  feasible designs only over a narrow range of duty, with many infeasible designs with no solution to the mean-line equations. It is more
+  straighforward to map out a design space by varying independent variables
+  within their natural aerodynamic bounds.
+* Controlling Mach number prevents choking when moving around the
+  design space. It is imperative to limit deceleration through compressors
+  to avoid flow separation, so specifying a relative velocity ratio or de
+  Haller number is a good idea. Letting meridional velocity float can lead
+  to wide variations in span and hence unfavourable high-curvature annulus
+  lines, so controlling the change in meridional velocity through the
+  machine is advisable.
+* Loss is best handled by guessing a vector of entropy rise at each
+  station, which does not depend on the frame of reference. The values can then be
+  updated using CFD results.
+* Iteration is required to solve for density in compressible cases. It is
+  often easiest to guess a value for the blade speed, then iterate to converge
+  on a blade speed that satisfies the requested duty. Matching a
+  total-to-static pressure ratio requires iteration because the exit
+  dynamic head is not known a priori.
+
+The `backward()` function takes a mean-line flow field as its only
+argument, and calculates a dictionary of the arguments to `forward()`.
+Given a suitably averaged CFD solution, `backward()` is a post-processing
+step that allows comparison of the three-dimensional simulated flow field
+to the one-dimensional design intent. Also, feeding the output of
+`forward()` straight into `backward()` acts as a check that the mean-line
+design is consistent with the requested inputs. `backward()` can also be
+used to post-process other quantities of interest from the mixed-out CFD
+flow field. Extra keys are printed the log file and saved to the output configuration
+file; only keys that are also design variables will be fed back
+into `forward()` for the consistency check.

turbigen-2.2.1/doc/solver.rst

@@ -0,0 +1,153 @@
+Base class for flow solvers.
+
+:program:`turbigen` is CFD-solver agnostic, in that all all pre- and
+post-processing is done by native code.
+
+Each CFD solver accepts different configuration options. Solver options and
+their default values are listed below; override the defaults using the
+`solver` section of the configuration file.
+
+Adding a new solver only requires
+functions to save CFD input files, execute the
+solver, and read back the flow solution into :program:`turbigen`'s internal
+data structures. See the :ref:`solver-custom` section for more details.
+
+
+
+ember
+-----
+
+:program:`ember` is the native flow solver built into :program:`turbigen`.
+
+.. list-table:: Parameters
+   :widths: 20 15 15 50
+   :header-rows: 1
+
+   * - Name
+     - Type
+     - Default
+     - Description
+   * - ``smooth4``
+     - ``float``
+     - ``0.01``
+     - Fourth-order smoothing factor.
+   * - ``smooth2_adapt``
+     - ``float``
+     - ``1.0``
+     - Second-order smoothing factor, adaptive on pressure.
+   * - ``smooth2_const``
+     - ``float``
+     - ``0.0``
+     - Second-order smoothing factor, constant throughout the flow.
+   * - ``smooth_ratio_min``
+     - ``float``
+     - ``0.1``
+     - Largest reduction in smoothing on a non-isotropic grid. Unity disables directional scaling, lower values clip the local smoothing factor to be sf_local >= sf * smooth_ratio_min.
+   * - ``CFL``
+     - ``float``
+     - ``0.65``
+     - Courant--Friedrichs--Lewy number, time step normalised by local wave speed and cell size. Reduced values are more stable but slower to converge.
+   * - ``n_step``
+     - ``int``
+     - ``5000``
+     - Number of time steps to run for.
+   * - ``n_step_mix``
+     - ``int``
+     - ``5``
+     - Number of time steps between mixing plane updates.
+   * - ``n_step_dt``
+     - ``int``
+     - ``10``
+     - Number of time steps between updates of the local time step.
+   * - ``n_step_log``
+     - ``int``
+     - ``500``
+     - Number of time steps between log prints.
+   * - ``n_step_avg``
+     - ``int``
+     - ``1``
+     - Number of time steps to average over.
+   * - ``n_step_ramp``
+     - ``int``
+     - ``250``
+     - Number of time steps to ramp smoothing and damping.
+   * - ``n_loss``
+     - ``int``
+     - ``5``
+     - Number of time steps between viscous force updates.
+   * - ``nstep_damp``
+     - ``int``
+     - ``-1``
+     - Number of steps to apply damping.
+   * - ``damping_factor``
+     - ``float``
+     - ``25.0``
+     - Negative feedback to damp down high residuals. Lower values are more stable.
+   * - ``Pr_turb``
+     - ``float``
+     - ``1.0``
+     - Turbulent Prandtl number.
+   * - ``xllim_pitch``
+     - ``float``
+     - ``0.03``
+     - Maximum mixing length as a fraction of the pitch.
+   * - ``precision``
+     - ``int``
+     - ``1``
+     - Precision of the solver. 1: single, 2: double.
+   * - ``i_scheme``
+     - ``int``
+     - ``1``
+     - Which time-stepping scheme to use. 0: scree, 1: super.
+   * - ``i_loss``
+     - ``int``
+     - ``1``
+     - Viscous loss model. 0: inviscid, 1: viscous.
+   * - ``K_exit``
+     - ``float``
+     - ``0.5``
+     - Relaxation factor for outlet forcing.
+   * - ``K_inlet``
+     - ``float``
+     - ``0.5``
+     - Relaxation factor for inlet forcing.
+   * - ``K_mix``
+     - ``float``
+     - ``0.1``
+     - Relaxation factor for mixing plane forcing.
+   * - ``sf_mix``
+     - ``float``
+     - ``0.01``
+     - Smoothing factor for uniform enthalpy and entropy downstream of mixing plane.
+   * - ``print_conv``
+     - ``bool``
+     - ``True``
+     - Print convergence history in the log.
+   * - ``fmgrid``
+     - ``float``
+     - ``0.2``
+     - Factor scaling the multigrid residual.
+   * - ``multigrid``
+     - ``tuple``
+     - ``(2, 2, 2)``
+     - Number of cells forming each multigrid level. (2, 2, 2) gives coarse cells of side length 2, 4, and 8 fine cells.
+   * - ``area_avg_Pout``
+     - ``bool``
+     - ``True``
+     - Force area-averaged outlet pressure to target, otherwise use uniform outlet pressure.
+
+.. _solver-custom:
+
+Custom solvers
+--------------
+
+To add a new solver, create a new class that inherits from :class:`turbigen.solvers.base.BaseSolver`.  and implement the following methods:
+
+- :meth:`run`: Run the solver on the given grid and machine geometry.
+- :meth:`robust`: Create a copy of the config with more robust settings.
+- :meth:`restart`: Create a copy of the config with settings to restart from converged solution.
+
+:class:`turbigen.solvers.base.BaseSolver` is a dataclass, so has an automatic constructor and
+useful built-in methods. The configuration file `solver` section
+is fed into the constructor as keyword arguments and becomes attributes of
+the instance.