diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml new file mode 100644 index 00000000..49337a97 --- /dev/null +++ b/.github/workflows/docs-check.yml @@ -0,0 +1,68 @@ +name: Documentation Checks + +on: + push: + branches: ['docs_site', 'docs/user-guides', 'docs/naca0021'] + pull_request: + branches: ['docs_site', 'develop', 'docs/user-guides'] + workflow_dispatch: + inputs: + su2_ref: + description: SU2 commit SHA or branch + default: docs/developer-guides + +permissions: + contents: read + +concurrency: + group: docs-check-${{ github.event_name }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + check: + runs-on: ubuntu-24.04 + steps: + - name: Checkout website under review + uses: actions/checkout@v4 + with: + path: site + fetch-depth: 0 + filter: blob:none + persist-credentials: false + - name: Checkout SU2 documentation tools + uses: actions/checkout@v4 + with: + repository: rois1995/SU2 + ref: ${{ inputs.su2_ref || 'docs/developer-guides' }} + path: su2 + fetch-depth: 0 + filter: blob:none + persist-credentials: false + - name: Get release tags for migration reference + run: git -C su2 fetch --quiet --filter=blob:none https://github.com/su2code/SU2.git 'refs/tags/v7.*:refs/tags/v7.*' 'refs/tags/v8.*:refs/tags/v8.*' + - name: Setup Node for search checks + uses: actions/setup-node@v4 + with: + node-version: '22' + - name: Check search behavior + run: node site/tools/test_search.js + - name: Setup Ruby and locked gems + uses: ruby/setup-ruby@v1 + with: + working-directory: site + ruby-version: .ruby-version + bundler: '2.4.22' + bundler-cache: true + - name: Install code reference tools + run: sudo apt-get update && sudo apt-get install -y doxygen graphviz + - name: Build and check website + env: + GITHUB_REPOSITORY: rois1995/SU2 + BUNDLE_PATH: ${{ github.workspace }}/site/vendor/bundle + run: python3 su2/Docs/website/tools/build_docs.py --su2 su2 --site site --build-dir "$RUNNER_TEMP/docs-site" --baseurl /SU2 --mark-changes + - name: Upload checked preview + uses: actions/upload-artifact@v4 + with: + name: docs-preview + path: ${{ runner.temp }}/docs-site/site + retention-days: 7 diff --git a/.gitignore b/.gitignore index b8098178..b4a2a154 100644 --- a/.gitignore +++ b/.gitignore @@ -2,8 +2,11 @@ # https://jekyllrb.com/docs/structure/ /_site -# bundler snapshot of all gems and versions that it installed -# https://bundler.io/rationale.html -Gemfile.lock +# Keep Gemfile.lock tracked so local and CI builds use the same gems. .jekyll-metadata + +# Local/CI dependency and Jekyll caches +.bundle/ +vendor/bundle/ +.jekyll-cache/ diff --git a/.ruby-version b/.ruby-version new file mode 100644 index 00000000..4d541eb2 --- /dev/null +++ b/.ruby-version @@ -0,0 +1 @@ +3.3.12 diff --git a/Gemfile.lock b/Gemfile.lock new file mode 100644 index 00000000..f94a6015 --- /dev/null +++ b/Gemfile.lock @@ -0,0 +1,282 @@ +GEM + remote: https://rubygems.org/ + specs: + activesupport (7.1.6) + base64 + benchmark (>= 0.3) + bigdecimal + concurrent-ruby (~> 1.0, >= 1.0.2) + connection_pool (>= 2.2.5) + drb + i18n (>= 1.6, < 2) + logger (>= 1.4.2) + minitest (>= 5.1) + mutex_m + securerandom (>= 0.3) + tzinfo (~> 2.0) + addressable (2.9.0) + public_suffix (>= 2.0.2, < 8.0) + base64 (0.2.0) + benchmark (0.5.0) + bigdecimal (4.1.3) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.12.2) + colorator (1.1.0) + commonmarker (0.23.12) + concurrent-ruby (1.3.8) + connection_pool (2.5.5) + dnsruby (1.72.3) + base64 (~> 0.2.0) + simpleidn (~> 0.2.1) + drb (2.2.3) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + ethon (0.18.0) + ffi (>= 1.15.0) + logger + eventmachine (1.2.7) + execjs (2.10.2) + json (>= 2) + faraday (2.8.1) + base64 + faraday-net_http (>= 2.0, < 3.1) + ruby2_keywords (>= 0.0.4) + faraday-net_http (3.0.2) + ffi (1.17.4) + forwardable-extended (2.6.0) + gemoji (4.1.0) + github-pages (231) + github-pages-health-check (= 1.18.2) + jekyll (= 3.9.5) + jekyll-avatar (= 0.8.0) + jekyll-coffeescript (= 1.2.2) + jekyll-commonmark-ghpages (= 0.4.0) + jekyll-default-layout (= 0.1.5) + jekyll-feed (= 0.17.0) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.16.1) + jekyll-include-cache (= 0.2.1) + jekyll-mentions (= 1.6.0) + jekyll-optional-front-matter (= 0.3.2) + jekyll-paginate (= 1.1.0) + jekyll-readme-index (= 0.3.0) + jekyll-redirect-from (= 0.16.0) + jekyll-relative-links (= 0.6.1) + jekyll-remote-theme (= 0.4.3) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.8.0) + jekyll-sitemap (= 1.4.0) + jekyll-swiss (= 1.0.0) + jekyll-theme-architect (= 0.2.0) + jekyll-theme-cayman (= 0.2.0) + jekyll-theme-dinky (= 0.2.0) + jekyll-theme-hacker (= 0.2.0) + jekyll-theme-leap-day (= 0.2.0) + jekyll-theme-merlot (= 0.2.0) + jekyll-theme-midnight (= 0.2.0) + jekyll-theme-minimal (= 0.2.0) + jekyll-theme-modernist (= 0.2.0) + jekyll-theme-primer (= 0.6.0) + jekyll-theme-slate (= 0.2.0) + jekyll-theme-tactile (= 0.2.0) + jekyll-theme-time-machine (= 0.2.0) + jekyll-titles-from-headings (= 0.5.3) + jemoji (= 0.13.0) + kramdown (= 2.4.0) + kramdown-parser-gfm (= 1.1.0) + liquid (= 4.0.4) + mercenary (~> 0.3) + minima (= 2.5.1) + nokogiri (>= 1.13.6, < 2.0) + rouge (= 3.30.0) + terminal-table (~> 1.4) + github-pages-health-check (1.18.2) + addressable (~> 2.3) + dnsruby (~> 1.60) + octokit (>= 4, < 8) + public_suffix (>= 3.0, < 6.0) + typhoeus (~> 1.3) + html-pipeline (2.14.3) + activesupport (>= 2) + nokogiri (>= 1.4) + http_parser.rb (0.8.1) + i18n (1.14.8) + concurrent-ruby (~> 1.0) + jekyll (3.9.5) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (>= 0.7, < 2) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 2.0) + kramdown (>= 1.17, < 3) + liquid (~> 4.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (>= 1.7, < 4) + safe_yaml (~> 1.0) + jekyll-avatar (0.8.0) + jekyll (>= 3.0, < 5.0) + jekyll-coffeescript (1.2.2) + coffee-script (~> 2.2) + coffee-script-source (~> 1.12) + jekyll-commonmark (1.4.0) + commonmarker (~> 0.22) + jekyll-commonmark-ghpages (0.4.0) + commonmarker (~> 0.23.7) + jekyll (~> 3.9.0) + jekyll-commonmark (~> 1.4.0) + rouge (>= 2.0, < 5.0) + jekyll-default-layout (0.1.5) + jekyll (>= 3.0, < 5.0) + jekyll-feed (0.17.0) + jekyll (>= 3.7, < 5.0) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.16.1) + jekyll (>= 3.4, < 5.0) + octokit (>= 4, < 7, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-mentions (1.6.0) + html-pipeline (~> 2.3) + jekyll (>= 3.7, < 5.0) + jekyll-optional-front-matter (0.3.2) + jekyll (>= 3.0, < 5.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.3.0) + jekyll (>= 3.0, < 5.0) + jekyll-redirect-from (0.16.0) + jekyll (>= 3.3, < 5.0) + jekyll-relative-links (0.6.1) + jekyll (>= 3.3, < 5.0) + jekyll-remote-theme (0.4.3) + addressable (~> 2.0) + jekyll (>= 3.5, < 5.0) + jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) + rubyzip (>= 1.3.0, < 3.0) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-sitemap (1.4.0) + jekyll (>= 3.7, < 5.0) + jekyll-swiss (1.0.0) + jekyll-theme-architect (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-cayman (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-dinky (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-hacker (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-leap-day (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-merlot (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-midnight (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-minimal (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-modernist (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-primer (0.6.0) + jekyll (> 3.5, < 5.0) + jekyll-github-metadata (~> 2.9) + jekyll-seo-tag (~> 2.0) + jekyll-theme-slate (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-tactile (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-time-machine (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-titles-from-headings (0.5.3) + jekyll (>= 3.3, < 5.0) + jekyll-twitter-plugin (2.1.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + jemoji (0.13.0) + gemoji (>= 3, < 5) + html-pipeline (~> 2.2) + jekyll (>= 3.0, < 5.0) + json (3.1.0) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.10.1) + logger + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + logger (1.7.0) + mercenary (0.3.6) + mini_portile2 (2.8.9) + minima (2.5.1) + jekyll (>= 3.5, < 5.0) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.26.1) + mutex_m (0.3.0) + nokogiri (1.15.7) + mini_portile2 (~> 2.8.2) + racc (~> 1.4) + octokit (4.25.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (5.1.1) + racc (1.8.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rexml (3.4.4) + rouge (3.30.0) + ruby2_keywords (0.0.5) + rubyzip (2.4.1) + safe_yaml (1.0.5) + sass (3.7.4) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + sawyer (0.9.3) + addressable (>= 2.3.5) + faraday (>= 0.17.3, < 3) + securerandom (0.3.2) + simpleidn (0.2.3) + terminal-table (1.8.0) + unicode-display_width (~> 1.1, >= 1.1.1) + typhoeus (1.6.0) + ethon (>= 0.18.0) + tzinfo (2.0.6) + concurrent-ruby (~> 1.0) + unicode-display_width (1.8.0) + webrick (1.9.2) + +PLATFORMS + ruby + +DEPENDENCIES + github-pages + jekyll-twitter-plugin + webrick + +BUNDLED WITH + 2.4.22 diff --git a/README.md b/README.md index f6bb3996..2d2d394b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,23 @@ -# su2code.github.io -[Link to Website](https://su2code.github.io/) +# SU2 website -## For Developers +[Official website](https://su2code.github.io/) · [Documentation preview](https://rois1995.github.io/SU2/) -In order to make any changes in the documentation of SU2, the files in [_docs_v7/](_docs_v7) should be touched. This is the documentation which is currently online. +## Editing documentation + +User guide, setup and model pages live in `_docs_v7/`; worked examples live in `_tutorials/`; verification and validation comparisons live in `_vandv/`. Navigation is in `_data/`, and `search.json` indexes those three collections. The `docs_v7` URL is retained for compatibility; check the version stated on each page. + +Keep each explanation in the appropriate section and link to related pages. See `_docs_v7/Using-the-Documentation.md` for their roles and evidence conventions. The nine setup guides share `_includes/setup-guide-intro.md`; retain draft labels and review marks until the stated review is complete. + +Developer pages and generated references are overlaid from the SU2 repository. Edit developer pages in `Docs/website/pages/` there and option descriptions in the source; do not create competing copies here. + +## Building and checking + +Use Ruby **3.3.12** from `.ruby-version` and Bundler **2.4.22** with the tracked `Gemfile.lock`. The combined build entry point is `Docs/website/tools/build_docs.py` in the SU2 checkout. Its README, `Docs/website/README.md`, gives the local commands and output-directory rules. It builds and checks the same staged site locally and in CI, including red preview highlighting when `--mark-changes` is passed. + +`.github/workflows/docs-check.yml` checks pushes to `docs_site`, `docs/user-guides` and `docs/naca0021`, and pull requests targeting `develop`, `docs_site` or `docs/user-guides`. It uses SU2 branch `docs/developer-guides` by default and uploads `docs-preview`. A manual run accepts an exact SU2 SHA through `su2_ref`. It checks internal references, search coverage, documented option names and source descriptions for new options. Historical findings are tracked explicitly in SU2's `check-baseline.json`; new findings fail. + +Search behavior is checked separately with Node.js 22: run `node tools/test_search.js` from this repository. CI runs the same check before building the site. No npm packages are needed. + +Website-only changes do not publish directly to SU2's Pages site. Publishing is currently restricted to `docs_site` in `rois1995/SU2`. First ensure that branch contains the reviewed SU2 tools, then start **Docs Website** there with the reviewed website commit SHA as `site_ref`. Check both recorded source revisions against the reviewed build before accepting the deployment. The result records both commit SHAs and tool versions in `build-info.json` and check results in `docs-check.json`. This avoids requiring a token with cross-repository write access for website pull requests. + +The current preview uses the `rois1995` forks. Website PR branches are `docs/user-guides` and `docs/naca0021`; `docs_site` is the existing published preview branch. Submit upstream changes through pull requests to `develop`. Do not push development branches directly to the official repositories. diff --git a/_config.yml b/_config.yml index e63bd734..88220e7f 100644 --- a/_config.yml +++ b/_config.yml @@ -18,12 +18,17 @@ markdown: kramdown highlighter: rouge plugins: - jekyll-feed + - jekyll-gist - jekyll-redirect-from - jekyll-seo-tag - jekyll-sitemap whitelist: + - jekyll-feed + - jekyll-gist - jekyll-redirect-from + - jekyll-seo-tag + - jekyll-sitemap exclude: @@ -32,6 +37,7 @@ exclude: - .idea/ - .gitignore - README.md + - tools/ timezone: Europe/Berlin defaults: - scope: @@ -56,6 +62,8 @@ defaults: values: layout: docs sectionid: docs + # Old v6 documentation: kept for old links, not listed for search engines. + sitemap: false seo: type: "WebPage" @@ -120,6 +128,3 @@ collections: # Google Analytics google_analytics: UA-28187985-1 - -plugins: - - jekyll-gist diff --git a/_data/docs_v7.yml b/_data/docs_v7.yml index 69224b75..dc8e3404 100644 --- a/_data/docs_v7.yml +++ b/_data/docs_v7.yml @@ -1,10 +1,12 @@ - title: Introduction to SU2 docs_v7: - home + - Using-the-Documentation - contribute -- title: New in Version 7 +- title: What's New docs_v7: + - Guide-to-v8 - Guide-to-v7 - title: Quick Start @@ -47,6 +49,25 @@ - Multizone - Execution +- title: Physical Models + docs_v7: + - Turbulence-Models + - Transition-Models + - Hybrid-RANS-LES + - Wall-Treatment + +- title: Case Setup Guides + docs_v7: + - Setup-Guide-RANS-External-Aero + - Setup-Guide-Incompressible + - Setup-Guide-Unsteady-DES + - Setup-Guide-Transition + - Setup-Guide-Turbomachinery + - Setup-Guide-Heat-Transfer-CHT + - Setup-Guide-Species-Combustion + - Setup-Guide-Shape-Optimization + - Setup-Guide-NICFD + - title: Developer Docs docs_v7: - Gitting-Started @@ -62,6 +83,7 @@ - title: FAQ docs_v7: - FAQ + - Troubleshooting - title: Contact docs_v7: diff --git a/_data/tutorials.yml b/_data/tutorials.yml index 873857e1..0c62d7d0 100644 --- a/_data/tutorials.yml +++ b/_data/tutorials.yml @@ -19,7 +19,7 @@ - NICFD_nozzle - NICFD_nozzle_datadriven - Aachen_Turbine - - Actuator_Disk + - ActuatorDisk_VariableLoad - title: Incompressible Flow tutorials: diff --git a/_docs_v7/Advanced-AD-Techniques.md b/_docs_v7/Advanced-AD-Techniques.md index e79f30a7..f39f3435 100644 --- a/_docs_v7/Advanced-AD-Techniques.md +++ b/_docs_v7/Advanced-AD-Techniques.md @@ -3,6 +3,8 @@ title: Advanced AD Techniques permalink: /docs_v7/Advanced-AD-Techniques/ --- +> **Note.** Parts of this page are from 2019 and out of date (build options, tape types, the list of `AD::` functions, how adjoints are read back). The current guide is [Automatic Differentiation (AD)](../Automatic-Differentiation/). + [Algorithmic Differentiation](https://en.wikipedia.org/wiki/Automatic_differentiation) (AD) is a frequently used method to calculate the derivative of a function by means of the transformation of the underlying program which calculates the numerical values of this function. As distinguished from symbolic differentiation an explicit expression for the diff --git a/_docs_v7/Configuration-File.md b/_docs_v7/Configuration-File.md index 7ea2aa7b..13a8aa98 100644 --- a/_docs_v7/Configuration-File.md +++ b/_docs_v7/Configuration-File.md @@ -12,7 +12,7 @@ The SU2 configuration file name typically carries a name of the form *filename.c The configuration file consists of only three elements: - **Options**. An option in the file has the following syntax: option_name = value, where option_name is the name of the option and value is the desired option value. The value element may be a scalar data type, a list of data types, or a more complicated structure. The "=" sign must come immediately after the option_name element and is not optional. Lists of data types may be formatted for appearance using commas, ()-braces, {}-braces, and []-braces, though this is not required. Semicolons are semantically relevant for several option types and may not be used as convenience delimiters. SU2 will exit with an error if there are options in the config file which do not exist or if there are options with improper formatting. Some example option formats are given below. - `FREESTREAM_VELOCITY = ( 5.0, 0.00, 0.00 ) % braces and commas can be used for list options` - - `REF_ORIGIN_MOMENT= 0.25 0.0 0.0 % however, braces and commas are optional for lists` + - `MOTION_ORIGIN= 0.25 0.0 0.0 % however, braces and commas are optional for lists` - `KIND_TURB_MODEL = NONE % space between elements is not significant` - **Comments**. On a given line in the file, any text appearing after a % is considered a comment and is ignored by SU2. Additional % signs after the first on a given line are not significant. - **White space**. Empty lines are ignored. On text lines that define options, white space (tabs, spaces) can be used to format the appearance of the file diff --git a/_docs_v7/Convective-Schemes.md b/_docs_v7/Convective-Schemes.md index 62d25c6d..3c37b3c7 100755 --- a/_docs_v7/Convective-Schemes.md +++ b/_docs_v7/Convective-Schemes.md @@ -15,7 +15,7 @@ The options listed here do not apply to the high order DG solver. - [Incompressible Flow](#incompressible-flow) - [Central Schemes](#central-schemes-1) - [Upwind Schemes](#upwind-schemes-1) -- [Turbulence Equations](#turbulence-equations) +- [Turbulence and Scalar/Species Equations](#turbulence-and-scalarspecies-equations) --- @@ -100,7 +100,7 @@ Some of the schemes above have tunning parameters or accept extra options, the f | --- | --- | | `RANS`, `INC_RANS` | 8.0.0 | -For compressible flows the only method available is `SCALAR_UPWIND` which must be selected via option `CONV_NUM_METHOD_TURB`. -For incompressible flows the `BOUNDED_SCALAR` method is also available, this includes a divergence correction to prevent spurious production/destruction of the transported scalar while convergence is not reached. +The method is selected via option `CONV_NUM_METHOD_TURB`. Two methods are available, for both compressible and incompressible flows: `SCALAR_UPWIND` and `BOUNDED_SCALAR`. +The `BOUNDED_SCALAR` method includes a divergence correction to prevent spurious production/destruction of the transported scalar while convergence is not reached. These methods do not have any special parameters. diff --git a/_docs_v7/Developing-SU2-on-GitHub-(Internal-Developers).md b/_docs_v7/Developing-SU2-on-GitHub-(Internal-Developers).md index f14cfdd6..2cd45896 100644 --- a/_docs_v7/Developing-SU2-on-GitHub-(Internal-Developers).md +++ b/_docs_v7/Developing-SU2-on-GitHub-(Internal-Developers).md @@ -22,7 +22,7 @@ After cloning, you should have a new SU2/ folder in your current working directo ``` git log ``` -To setup the local copy of SU2 for development purposes, one must follow the steps mentioned in [Build-SU2-Windows](_docs_v7/Build-SU2-Windows.md) and [Build-SU2-Linux-MacOS](_docs_v7/Build-SU2-Linux-MacOS.md). +To setup the local copy of SU2 for development purposes, one must follow the steps mentioned in [Build-SU2-Windows](/docs_v7/Build-SU2-Windows/) and [Build-SU2-Linux-MacOS](/docs_v7/Build-SU2-Linux-MacOS/). ## Typical Workflow with Git diff --git a/_docs_v7/Execution.md b/_docs_v7/Execution.md index 03b1032b..3563213a 100644 --- a/_docs_v7/Execution.md +++ b/_docs_v7/Execution.md @@ -10,11 +10,11 @@ Once downloaded and installed, and now that you know the basics for setting up y - [C++ Modules](#c-modules) - [Python Scripts](#python-scripts) - - [Parallel Computation Script (parallel_computation.py)](#parallel-computation-script-parallelcomputationpy) - - [Continuous Adjoint Gradient Calculation (continuous_adjoint.py)](#continuous-adjoint-gradient-calculation-continuousadjointpy) - - [Discrete Adjoint Gradient Calculation (discrete_adjoint.py)](#discrete-adjoint-gradient-calculation-discreteadjointpy) - - [Finite Difference Gradient Calculation (finite_differences.py)](#finite-difference-gradient-calculation-finitedifferencespy) - - [Shape Optimization Script (shape_optimization.py)](#shape-optimization-script-shapeoptimizationpy) + - [Parallel Computation Script (parallel_computation.py)](#parallel-computation-script-parallel_computationpy) + - [Continuous Adjoint Gradient Calculation (continuous_adjoint.py)](#continuous-adjoint-gradient-calculation-continuous_adjointpy) + - [Discrete Adjoint Gradient Calculation (discrete_adjoint.py)](#discrete-adjoint-gradient-calculation-discrete_adjointpy) + - [Finite Difference Gradient Calculation (finite_differences.py)](#finite-difference-gradient-calculation-finite_differencespy) + - [Shape Optimization Script (shape_optimization.py)](#shape-optimization-script-shape_optimizationpy) - [Python wrapper scripts](#python-wrapper-scripts) --- @@ -107,8 +107,10 @@ Options: * `-f FILE, --file=FILE` read config from FILE * `-r NAME, --name=NAME` try to restart from project file NAME * `-n PARTITIONS, --partitions=PARTITIONS` number of PARTITIONS -* `-g GRADIENT, --gradient=GRADIENT` Method for computing the GRADIENT (ADJOINT, DISCRETE_ADJOINT, FINDIFF, NONE) +* `-g GRADIENT, --gradient=GRADIENT` Method for computing the GRADIENT (CONTINUOUS_ADJOINT, DISCRETE_ADJOINT, FINDIFF, NONE), default DISCRETE_ADJOINT +* `-o OPTIMIZATION, --optimization=OPTIMIZATION` OPTIMIZATION technique (SLSQP, CG, BFGS, POWELL), default SLSQP * `-q QUIET, --quiet=QUIET` True/False Quiet all SU2 output (optimizer output only) +* `-z ZONES, --zones=ZONES` Number of ZONES ### Python wrapper scripts diff --git a/_docs_v7/Guide-to-v7.md b/_docs_v7/Guide-to-v7.md index 0eaea27d..8545ff20 100644 --- a/_docs_v7/Guide-to-v7.md +++ b/_docs_v7/Guide-to-v7.md @@ -86,7 +86,7 @@ Below are the options that have changed or are removed: | `RESIDUAL_MINVAL` | `CONV_RESIDUAL_MINVAL` | - | | `CAUCHY_ELEMS` | `CONV_CAUCHY_ELEMS` | - | | `CAUCHY_EPS` | `CONV_CAUCHY_EPS` | - | -| `CONV_CRITERIA` | `CONV_FIELD` | Accepts all fields available as output for the current solver (see [Solver Setup](/docs_v7/Solver-Setup#setting-convergence-critera))| +| `CONV_CRITERIA` | `CONV_FIELD` | Accepts all fields available as output for the current solver (see [Solver Setup](/docs_v7/Solver-Setup#setting-convergence-criteria))| | `RESIDUAL_REDUCTION` | - | Removed. Equivalent behavior can be achieved by choosing a relative residual field for `CONV_FIELD` and setting `CONV_RESIDUAL_MINVAL` appropriately. diff --git a/_docs_v7/Guide-to-v8.md b/_docs_v7/Guide-to-v8.md new file mode 100644 index 00000000..b2e9b254 --- /dev/null +++ b/_docs_v7/Guide-to-v8.md @@ -0,0 +1,206 @@ +--- +title: Changes in Version 8 +permalink: /docs_v7/Guide-to-v8/ +--- + +SU2 version 8 ("Harrier") started with v8.0.0 in August 2023. Most v7 config files still run in v8. A few options were renamed or removed, some defaults changed, and several fixes change the results of turbulent cases. The Python wrapper and the build system also changed. + +How to read this page: + +- Read [Breaking changes](#breaking-changes) first. These can stop a v7 config from running or change its results. +- [New features](#new-features-by-area) lists what v8 adds, by area. Each item gives the release that added it. +- Use the [checklist](#migrating-a-v7-config) at the end to update a config. + +When SU2 finds a removed option in a config file, it stops and names the option. For many options it also names the replacement. The full list of renamed and removed options is on [Renamed and Removed Options](../Renamed-Options/). The changes from v6 to v7 (`EXT_ITER`, `PHYSICAL_PROBLEM`, output options and so on) are on [Guide to Version v7](../Guide-to-v7/). + +--- + +- [Breaking changes](#breaking-changes) + - [Renamed and removed options](#renamed-and-removed-options) + - [Changed defaults and behaviour](#changed-defaults-and-behaviour) + - [Changes that affect results](#changes-that-affect-results) + - [Python wrapper](#python-wrapper) + - [Build and tools](#build-and-tools) +- [New features by area](#new-features-by-area) +- [Migrating a v7 config](#migrating-a-v7-config) + +--- + +## Breaking changes + +### Renamed and removed options + +These are the most common ones. See [Renamed and Removed Options](../Renamed-Options/) for all of them. + +| Old option | New option | Release | +| --- | --- | --- | +| `DYNAMIC_ANALYSIS` | `TIME_DOMAIN` | v8.0.0 | +| `DYN_TIMESTEP` | `TIME_STEP` | v8.0.0 | +| `DYN_TIME` | `MAX_TIME` | v8.0.0 | +| `SINGLEZONE_DRIVER` | Removed, no replacement | v8.0.0 | +| `SPECIES_USE_STRONG_BC= YES` | `MARKER_SPECIES_STRONG_BC= (marker1, ...)` | v8.0.0 | +| `DEAD_LOAD` | `GRAVITY_FORCE` or `BODY_FORCE` | v8.2.0 | +| `SMOOTH_GEOMETRY` | Removed (it had no effect) | v8.2.0 | +| `INC_INLET_USENORMAL` | `INLET_USE_NORMAL` (now works for all solvers) | v8.3.0 | +| `RAMP_OUTLET_PRESSURE`, `RAMP_OUTLET_PRESSURE_COEFF` | `RAMP_OUTLET`, `RAMP_OUTLET_COEFF` | v8.3.0 | +| `RAMP_ROTATING_FRAME`, `RAMP_ROTATING_FRAME_COEFF` | `RAMP_MOTION_FRAME`, `RAMP_MOTION_FRAME_COEFF` | v8.3.0 | +| `DATADRIVEN_INITIAL_DENSITY`, `DATADRIVEN_INITIAL_ENERGY` (added in v8.2.0) | Removed, no replacement | v8.5.0 | + +The FEA solver now uses the same time options as the flow solver. A dynamic structural case needs `TIME_DOMAIN= YES`, `TIME_STEP` and `MAX_TIME`. + +Removed option values (v8.0.0): + +- `CONV_NUM_METHOD_FLOW= CUSP`. Use `JST` or an upwind scheme. +- `TIME_DISCRE_FEA= CD_EXPLICIT` and `GENERALIZED_ALPHA`. Only `NEWMARK_IMPLICIT` is left. +- `DV_KIND= FFD_TWIST_2D`. It was never implemented. +- `OBJECTIVE_FUNCTION= FLOW_ANGLE_OUT` and `MASS_FLOW_IN` (turbomachinery). + +These turbulence settings changed in v7.4.0. The v7 guide does not cover them, and older v7 configs may still use them: + +| Old setting | New setting | +| --- | --- | +| `KIND_TURB_MODEL= SA_NEG` | `KIND_TURB_MODEL= SA`, `SA_OPTIONS= NEGATIVE, WITHFT2` | +| `KIND_TURB_MODEL= SA_E` | `KIND_TURB_MODEL= SA`, `SA_OPTIONS= EDWARDS` | +| `KIND_TURB_MODEL= SA_COMP` | `KIND_TURB_MODEL= SA`, `SA_OPTIONS= COMPRESSIBILITY` | +| `KIND_TURB_MODEL= SA_E_COMP` | `KIND_TURB_MODEL= SA`, `SA_OPTIONS= EDWARDS, COMPRESSIBILITY, EXPERIMENTAL` | +| `KIND_TURB_MODEL= SST_SUST` | `KIND_TURB_MODEL= SST`, `SST_OPTIONS= SUSTAINING` | +| `KIND_TRANS_MODEL= BC` | `KIND_TURB_MODEL= SA`, `SA_OPTIONS= BCM` | + +The `SA_NEG` row selects standard SA-neg, including ft2. To request negative SA without ft2, use +`SA_OPTIONS= NEGATIVE, EXPERIMENTAL`; this is a different formulation and can change the results. +Edwards with a compressibility correction also needs `EXPERIMENTAL`, because it is not a standard TMR +combination. See [Turbulence Models](../Turbulence-Models/#combinations-that-su2-accepts). + +### Changed defaults and behaviour + +| What | Before | Now | Release | +| --- | --- | --- | --- | +| SST version when `SST_OPTIONS` names none | SST-1994m | SST-2003m | v8.0.0 | +| `MUSCL_FLOW= YES` (or `MUSCL_ADJFLOW= YES`) with a centered scheme | Ignored | Error. Remove the line or set it to `NO`. | v8.0.0 | +| Restart files (`WRT_RESTART_COMPACT`, new option, default `YES`) | All volume output fields | Only the fields needed to restart | v8.2.0 | +| Default file names (`RESTART_FILENAME`, `SOLUTION_FILENAME`, ...) | `restart.dat`, `solution.dat`, ... | `restart`, `solution`, ... SU2 adds the extension. | v8.3.0 | +| `MGLEVEL` | Exact number of coarse levels | Maximum. Levels with fewer than `MG_MIN_MESHSIZE` (500) points are dropped. | v8.5.0 | +| `MG_PRE_SMOOTH`, `MG_POST_SMOOTH` | Fixed number of smoothing steps | Maximum. The smoother stops early (`MG_SMOOTH_EARLY_EXIT= YES`). | v8.5.0 | +| `MG_DAMP_RESTRICTION`, `MG_DAMP_PROLONGATION` | 0.75, fixed | 0.5, used as a start value and adapted during the run | v8.5.0 | + +Notes: + +- **SST.** To keep the old model, set `SST_OPTIONS= V1994m`. In v8.0.0 the 1994m model itself also changed to match the literature, so old SST-1994m results are not reproduced exactly. +- **Restart files.** With compact restarts, extra fields such as pressure or skin friction are no longer in the restart file. They are still in the visualization files. Set `WRT_RESTART_COMPACT= NO` if your scripts read these fields from the restart file. See [Restart File](../Restart-File/). +- **File names.** Give file names without an extension. If you give the expected extension, SU2 removes it. A different extension stays part of the name. +- **Multigrid.** `MG_SMOOTH_EARLY_EXIT= NO` gives fixed smoothing and fixed damping again. To also get the old damping values, set `MG_DAMP_RESTRICTION` and `MG_DAMP_PROLONGATION` to 0.75. + +### Changes that affect results + +Many fixes in v8 change the converged solution a little, mostly for turbulent flows. Do not expect v7 and v8 to give the same forces. The main ones: + +- SST: the default changed to SST-2003m and SST-1994m was corrected (v8.0.0). SST-2003 had important fixes (v8.2.0). The cross-diffusion term has a new discretization (v8.3.0). +- SA: corrections to the SA and SA-neg models (v8.0.0, v8.1.0). The nonlinear diffusion term has a new discretization (v8.3.0). +- Symmetry planes: corrected (v8.1.0). Intersecting and curved symmetry planes and inviscid walls work better (v8.2.0). +- Multigrid: new smoothing and damping rules (v8.5.0), see above. + +### Python wrapper + +The Python wrapper was rewritten in v8.0.0. Scripts written for v7 need changes. Many methods have new names, for example: + +| v7 | v8 | +| --- | --- | +| `Postprocessing()` | `Finalize()` | +| `GetNumberVertices(iMarker)` | `GetNumberMarkerNodes(iMarker)` | +| `SetVertexTemperature(...)` | `SetMarkerCustomTemperature(...)` | + +Methods that set boundary conditions now start with `SetMarkerCustom`. The [Python wrapper test cases](https://github.com/su2code/SU2/tree/master/TestCases/py_wrapper) show the current interface. + +### Build and tools + +- The old autotools build (`configure`, `make`) was removed in v8.0.0. Build with meson. See [Build SU2 on Linux/MacOS](../Build-SU2-Linux-MacOS/). +- Some old Python scripts were removed in v8.0.0: `compute_multipoint.py`, `compute_stability.py`, `config_gui.py` and `convert_to_csv.py`. +- v8.5.0 uses PaStiX version 6 (`-Denable-pastix=true`) and CoolProp 7.2.0. The release binaries now include OpenMP, and the default compiler optimization is stronger. + +--- + +## New features by area + +Many bug fixes and small improvements are not listed. See the [GitHub release notes](https://github.com/su2code/SU2/releases) for all changes. + +### Solvers and models + +- **Combustion.** Flamelet model for premixed flames: `KIND_SCALAR_MODEL= FLAMELET` with `FLUID_MODEL= FLUID_FLAMELET` (v8.0.0). Preferential diffusion (`PREFERENTIAL_DIFFUSION`) and spark ignition (`FLAME_INIT_METHOD= SPARK`) (v8.1.0). See [Species Transport and Combustion](../Setup-Guide-Species-Combustion/) and the tutorials [Laminar Combustion](/tutorials/Inc_Combustion/) and [Counterflow Diffusion Flame](https://su2code.github.io/tutorials/Inc_Laminar_Diffusion_Flame/). +- **Data-driven fluid model.** `FLUID_MODEL= DATADRIVEN_FLUID` with look-up tables or neural networks (`INTERPOLATION_METHOD= LUT` or `MLP`) (v8.0.0). Physics-informed networks with `USE_PINN` (v8.2.0). See [NICFD](../Setup-Guide-NICFD/) and the tutorial [Physics-informed neural networks](/tutorials/NICFD_nozzle_datadriven/). +- **Species transport.** Custom wall conditions with `MARKER_WALL_SPECIES` (v8.4.0). Adaptive CFL now also covers species (v8.1.0). +- **NEMO.** Ionization for viscous flows (v8.0.0). See [Thermochemical Nonequilibrium](../Thermochemical-Nonequilibrium/). +- **SST.** Compressibility corrections `SST_OPTIONS= COMPRESSIBILITY-WILCOX` or `COMPRESSIBILITY-SARKAR` (v8.1.0). Lower limits relative to the free stream with `SST_OPTIONS= DIMENSIONLESS_LIMIT`, `LOWER_LIMIT_K_FACTOR` and `LOWER_LIMIT_OMEGA_FACTOR` (v8.1.0). Rough-wall models with `KIND_ROUGHSST_MODEL` and `WALL_ROUGHNESS` (v8.4.0). +- **SA.** Source terms for 2D axisymmetric flows (v8.1.0). +- **Hybrid RANS/LES.** Stochastic backscatter model (`STOCHASTIC_BACKSCATTER`), `ENFORCE_LES`, `LES_FILTER_WIDTH` and the low-dissipation scheme `LD2` (v8.5.0). See [Unsteady and DES](../Setup-Guide-Unsteady-DES/). +- **Compressible flow.** Conductivity models other than `CONSTANT_PRANDTL` (`CONDUCTIVITY_MODEL`) (v8.4.0). +- **Incompressible flow.** Temperature limits with `TEMPERATURE_LIMITS` (v8.4.0). Preconditioning for multicomponent flows (v8.4.0). See [Incompressible](../Setup-Guide-Incompressible/). +- **Boundary conditions.** SA inlet based on local conditions (v8.0.0). Supersonic inlet profiles (v8.1.0). `INLET_USE_NORMAL` for compressible inlets (v8.3.0). +- **Actuator disks and engines.** Blade element actuator disk, `ACTDISK_TYPE= BLADE_ELEMENT` (v8.0.1). Engine mass flow coupling for zero-thrust cases, `ENGINE_EXHAUST_TO_INLET` (v8.5.0). +- **Gusts.** Gust encounter for 3D meshes and free-flying elastic aircraft, `GUST_DIR= Z_DIR` (v8.0.0). +- **Turbomachinery.** New turbomachinery outputs (v8.0.1). New interfaces between rows and `TURBO_PERF_KIND` (v8.1.0). New ramps (v8.3.0, v8.4.0). See [Turbomachinery](../Setup-Guide-Turbomachinery/) and the tutorial [Aachen Turbine](/tutorials/Aachen_Turbine/). +- **Structural solver.** Thermal expansion (`MATERIAL_THERMAL_EXPANSION_COEFF`, `MATERIAL_REFERENCE_TEMPERATURE`) and centrifugal forces (`CENTRIFUGAL_FORCE`) (v8.2.0). +- **Stopping a run.** SIGTERM stops the run and writes the output files (v8.1.0). + +### Numerics + +- **Limiters.** Nishikawa limiters `NISHIKAWA_R3`, `NISHIKAWA_R4` and `NISHIKAWA_R5` (v8.0.0). See [Slope Limiters](../Slope-Limiters-and-Shock-Resolution/). +- **MUSCL.** Kappa scheme with `MUSCL_KAPPA_FLOW`, `MUSCL_KAPPA_TURB` and related options (v8.4.0). The default 0 keeps the previous scheme. MUSCL ramp with `RAMP_MUSCL` and `KIND_MUSCL_RAMP` (v8.4.0). +- **MSW scheme.** Uses a pressure sensor, set with `MSW_ALPHA` (v8.5.0). See [Convective Schemes](../Convective-Schemes/). +- **CFL.** `CFL_ADAPT_PARAM` takes a sixth value: the iteration where adaptation starts (v8.2.0). +- **Robustness.** Limits on the solution update: `MAX_UPDATE_FLOW`, `MAX_UPDATE_SA`, `MAX_UPDATE_SST`. Exact turbulence Jacobians with `USE_ACCURATE_TURB_JACOBIANS` (v8.3.0). +- **Linear solvers.** `LINEAR_SOLVER= FGCRODR` with `LINEAR_SOLVER_RESTART_DEFLATION` (v8.4.0). Nested preconditioning with `LINEAR_SOLVER_INNER` (v8.4.0). Newton-Krylov improvements (v8.4.0). Level scheduling for OpenMP ILU, `LINEAR_SOLVER_ILU_LEVEL_SCHEDULING` (v8.5.0). See [Linear Solvers and Preconditioners](../Linear-Solvers-and-Preconditioners/). +- **Multigrid.** New options `MG_MIN_MESHSIZE`, `MG_SMOOTH_EARLY_EXIT`, `MG_SMOOTH_RES_THRESHOLD` and `MG_SMOOTH_COEFF` (v8.5.0). +- **Mesh deformation and shape design.** RBF mesh deformation, `DEFORM_KIND= RBF` (v8.3.0). Camber line Hicks-Henne design variable, `DV_KIND= HICKS_HENNE_CAMBER` (v8.3.0). See [Shape Optimization](../Setup-Guide-Shape-Optimization/). + +### Output + +- Custom outputs (functions of other outputs) with `CUSTOM_OUTPUTS`, for all solvers (v8.0.0). See [Custom Output](../Custom-Output/). +- New volume fields: local time step and CFL, velocity for compressible flow, thermal conductivity, heat capacity and diffusivity (v8.0.0). +- `CUR_TIME` is in the default history output of unsteady runs (v8.0.1). `ITER_TIME` gives the wall time per iteration (v8.5.0). +- Compact restart files and `VOLUME_OUTPUT= COMPACT` (v8.2.0). +- Wall heat fluxes are reported as imposed by the wall boundary condition (v8.2.0). + +### Adjoint and AD + +- Faster hybrid parallel (MPI + OpenMP) discrete adjoint (v8.0.0, v8.0.1). +- Tape debug mode with `CHECK_TAPE_TYPE` and `CHECK_TAPE_VARIABLES` (v8.3.0). +- Discrete adjoint of thermoelastic problems (v8.5.0). The Newton-Krylov adjoint uses FGCRODR (v8.5.0). +- The FADO optimization framework is installed with SU2 (v8.2.0). + +### Multizone and multiphysics + +- Solid-to-solid heat transfer with contact resistance, `CHT_INTERFACE_CONTACT_RESISTANCE` (v8.1.0). See the tutorial [Contact Resistance CHT](/tutorials/SS_CR_CHT/). +- Coupled thermoelasticity (v8.2.0). `MARKER_CREATE_COPY` makes thermoelastic setups simpler (v8.5.0). +- See [Multizone](../Multizone/) and [Heat Transfer and CHT](../Setup-Guide-Heat-Transfer-CHT/). + +### Performance + +- FGMRES on GPUs with CUDA: build with `-Denable-cuda=true` and set `ENABLE_CUDA= YES` (v8.3.0). +- Better OpenMP performance: adaptive edge color group size (v8.0.1) and more parallel regions. +- Profiling with Tracy (v8.3.0) and gprof (`-Denable-gprof=true`, v8.1.0). See [Tracy Integration](../Tracy-Integration/). + +### Python wrapper + +- Rewritten in v8.0.0. Python scripts can deform the mesh in memory, read and set the solution and primitive variables in the volume and on markers, read all history outputs, set custom boundary conditions, set the angles of attack and sideslip, and choose the zone in multizone cases. +- Custom inlets (v8.1.0). Custom source terms for all solvers with `PYTHON_CUSTOM_SOURCE` (v8.3.0). Source terms for the heat solver (v8.4.0). +- See [Execution](../Execution/) and the tutorials [Dynamic FSI with Python](/tutorials/Dynamic_FSI_Python/) and [User Defined Combustion Model](/tutorials/TFC_python/). + +--- + +## Migrating a v7 config + +1. Run the config with v8. SU2 lists every unknown option and often the replacement. Fix them with the tables above and [Renamed and Removed Options](../Renamed-Options/). +2. For FEA dynamic cases, replace `DYNAMIC_ANALYSIS`, `DYN_TIMESTEP` and `DYN_TIME` with `TIME_DOMAIN`, `TIME_STEP` and `MAX_TIME`. +3. For SST cases, decide on the version. Add `SST_OPTIONS= V1994m` only if you must stay close to old results. Otherwise use the new default, SST-2003m. +4. Replace `KIND_TURB_MODEL` values like `SA_NEG` or `SST_SUST` with `SA_OPTIONS` or `SST_OPTIONS`. +5. Remove `MUSCL_FLOW= YES` from cases with a centered scheme (`JST`, `LAX-FRIEDRICH`). Replace `CUSP` with another scheme. +6. If you read fields other than the solution from restart files, set `WRT_RESTART_COMPACT= NO`. +7. Write file names without an extension. +8. With multigrid, check the number of levels SU2 prints at the start. Set `MG_SMOOTH_EARLY_EXIT= NO` if you need the old smoothing. +9. Update Python wrapper scripts to the new method names. +10. Build from source with meson, not autotools. +11. Compare the results with your v7 results. Small differences are expected for turbulent cases. + +--- + +Last checked against SU2 release v8.5.0. diff --git a/_docs_v7/Hybrid-RANS-LES.md b/_docs_v7/Hybrid-RANS-LES.md new file mode 100644 index 00000000..6e8eac33 --- /dev/null +++ b/_docs_v7/Hybrid-RANS-LES.md @@ -0,0 +1,236 @@ +--- +title: "Hybrid RANS/LES (DES)" +permalink: /docs_v7/Hybrid-RANS-LES/ +--- + +This page explains the model and its SU2 implementation. For numerical setup choices, see the [setup guide](../Setup-Guide-Unsteady-DES/); use its tutorial and V&V links for worked examples and comparisons. + +Hybrid RANS/LES methods run a RANS model in attached boundary layers and a large-eddy simulation (LES) away from the walls. In LES, the mesh and the time step resolve the large turbulent eddies, and the model only handles the small ones. Detached eddy simulation (DES) and its variants are the hybrid methods in SU2. Use them for massively separated, unsteady flows where URANS is not accurate enough and a full LES is too expensive. + +For a step-by-step case setup, see [Setup Guide: Unsteady Flows and DES](../Setup-Guide-Unsteady-DES/). For the SA model itself, see [Turbulence Models](../Turbulence-Models/). + +--- + +- [How DES works in SU2](#how-des-works-in-su2) +- [How to select it](#how-to-select-it) + - [DES variant](#des-variant) + - [DES length scale options](#des-length-scale-options) + - [Low-dissipation convective scheme](#low-dissipation-convective-scheme) + - [Stochastic backscatter model](#stochastic-backscatter-model) + - [Time averages](#time-averages) +- [What SU2 does differently from the literature](#what-su2-does-differently-from-the-literature) +- [Equations and references](#equations-and-references) +- [Recommended use](#recommended-use) +- [Output fields](#output-fields) +- [Verification and test cases](#verification-and-test-cases) +- [Known limits](#known-limits) +- [Links](#links) + +--- + +## How DES works in SU2 + +In SU2, all DES variants modify the Spalart-Allmaras (SA) model. The SA model uses the wall distance in its destruction term. DES replaces this distance with a *DES length scale*: + +- In original DES, the length scale is min(d, C_DES Δ), using wall distance d and the local grid measure Δ. +- In the delayed variants it is d − f_d·max(0, d − C_DES Δ). Shielding f_d near zero retains the RANS wall distance; f_d near one recovers the DES limit. +- With a suitable mesh and time step, the shortened scale lets the model act as an LES subgrid model. Distance from the wall alone does not select the mode. + +The variants differ in two points: how they protect attached boundary layers from switching to LES, and how they measure the cell size. + +The DES length scale is computed only in the SA solver (`CTurbSASolver::SetDES_LengthScale`). The SST solver never reads `HYBRID_RANSLES`. So in SU2 develop, DES needs `KIND_TURB_MODEL= SA`. The options on this page describe the checked source revision; do not infer SST-DES support from an option being accepted by the parser. + +DES works with the compressible (`RANS`) and the incompressible (`INC_RANS`) solvers. Both pass the DES length scale and the LES sensor to the output. + +## How to select it + +### DES variant + +Set the turbulence model to SA and pick a variant with `HYBRID_RANSLES`: + +``` +SOLVER= RANS +KIND_TURB_MODEL= SA +HYBRID_RANSLES= SA_DDES +DES_CONST= 0.65 +TIME_DOMAIN= YES +``` + +| `HYBRID_RANSLES` | Method | Cell size used in LES mode | +|---|---|---| +| `NONE` (default) | No DES. The SA model runs as RANS or URANS. | – | +| `SA_DES` | Original DES (Spalart et al. 1997). Switches to LES wherever `DES_CONST` times the cell size is smaller than the wall distance. | Longest edge from the node | +| `SA_DDES` | Delayed DES (Spalart et al. 2006). A *shielding function* f_d keeps attached boundary layers in RANS mode. | Longest edge from the node | +| `SA_ZDES` | DDES with the vorticity-based cell size of the zonal DES (Deck 2012). | Cell size seen across the vorticity vector | +| `SA_EDDES` | DDES with the shear-layer-adapted cell size of Shur et al. (2015). Meant to switch faster from RANS to LES in separated shear layers. | Shear-layer-adapted size | + +### DES length scale options + +| Option | Default | What it does | +|---|---|---| +| `DES_CONST` | `0.65` | The DES constant. The LES length scale is `DES_CONST` times the cell size. | +| `LES_FILTER_WIDTH` | `-1.0` | If positive, SU2 uses this value as the cell size at every node, for all variants. It replaces the local cell size. Give it in mesh length units. A negative value uses the local cell size. | +| `ENFORCE_LES` | `NO` | `YES` sets the length scale to `DES_CONST` times the cell size everywhere, also near walls. The whole domain then runs as LES with an SA-based subgrid model. SU2 stops with an error if `HYBRID_RANSLES= NONE`. | + +`LES_FILTER_WIDTH` and `ENFORCE_LES` are mainly for LES test problems, such as decaying isotropic turbulence. + +### Low-dissipation convective scheme + +Upwind schemes add numerical dissipation. In LES regions, this dissipation damps the resolved eddies. `ROE_LOW_DISSIPATION` blends the upwind dissipation with a central flux: full upwind in RANS regions, little upwind in LES regions. + +| `ROE_LOW_DISSIPATION` | Blending sensor | +|---|---| +| `NONE` (default) | No blending. | +| `FD` | Based on the DDES shielding function f_d. Full upwind where f_d = 0 (RANS), down to 5% upwind where f_d = 1. | +| `NTS` | The sensor of Travin et al. (2002), as written in Xiao et al. (2012). Uses `DES_CONST`, the cell size and the eddy viscosity. | +| `FD_DUCROS` | `FD` plus the Ducros shock sensor: full upwind near shocks. | +| `NTS_DUCROS` | `NTS` plus the Ducros shock sensor, combined as in Xiao et al. (2015). | + +Facts from the code: + +- The blending acts only with `CONV_NUM_METHOD_FLOW= ROE`, `SLAU` or `SLAU2`. With any other scheme, SU2 ignores the option without a warning. +- The sensor is computed in the compressible Navier-Stokes solver (`CNSSolver::SetRoe_Dissipation`). The incompressible solver does not use this option. +- The minimum upwind fraction is fixed at 0.05 in the code. The Ducros threshold for `FD_DUCROS` is fixed at 0.65. +- `FD` computes its own f_d from the wall distance and the eddy viscosity. It does not need `HYBRID_RANSLES`. +- With the option on, the volume output gets the field `ROE_DISSIPATION`. + +For incompressible LES regions, SU2 has the centered scheme `CONV_NUM_METHOD_FLOW= LD2` (low dissipation, low dispersion). It works only with the incompressible solver and a constant-density fluid. The backscatter test case uses it. + +### Stochastic backscatter model + +In the "grey area" just after separation, a DES has neither modeled nor resolved turbulence: the RANS eddy viscosity is gone and the resolved eddies have not grown yet. The stochastic backscatter model (Kok 2017) adds random forcing in LES regions to speed up the growth of resolved eddies. *Backscatter* means energy that flows from the small, modeled scales back to the large, resolved ones. + +SU2 adds a random stress to the momentum equations. The random field comes from three extra equations (Langevin equations) for a random vector, solved together with the SA equation. + +| Option | Default | What it does | +|---|---|---| +| `STOCHASTIC_BACKSCATTER` | `NO` | Turns the model on. Needs `HYBRID_RANSLES` other than `NONE` and a 3D mesh, else SU2 stops with an error. | +| `SBS_INTENSITY_COEFF` | `1.0` | Strength of the random stress. Must not be negative. | +| `SBS_TIMESCALE_COEFF` | `0.05` | Time scale coefficient of the Langevin equations. If `0` or less, SU2 does not solve them. It then uses a new, uncorrelated random field at every time step. | +| `SBS_LENGTHSCALE_COEFF` | `0.02` | Strength of the spatial smoothing of the random source. The smoothing length grows with this coefficient times the squared cell size. | +| `SBS_MAX_ITER_SMOOTH` | `100` | Maximum iterations of the smoothing. `0` turns smoothing off. | +| `SBS_FD_LOWER_THRESHOLD` | `0.9` | The model acts only where the LES sensor is above this value. | +| `SBS_SOURCE_NU_EQUATION` | `YES` | Also adds a random source to the SA equation, so that modeled and resolved energy stay in balance. | +| `SBS_RELAXATION_FACTOR` | `0.0` | If positive, the intensity ramps up from zero at the start (or restart) of the run. The ramp time is this factor times `REYNOLDS_LENGTH` divided by the free-stream speed. | +| `SBS_IN_BOX` | `NO` | `YES` limits the model to a box. | +| `SBS_BOX_BOUNDS` | none | The box: `( x_min, x_max, y_min, y_max, z_min, z_max )`. It has no default, so always set it with `SBS_IN_BOX= YES`. | +| `SBS_SOURCE_DIAGNOSTICS` | `NO` | Prints statistics of the smoothed random source on screen. | + +Facts from the code: + +- The model is part of the SA solver. With `SBS_TIMESCALE_COEFF` positive, the SA solver has 4 variables instead of 1: ν̃ and the three components of the random vector. The history output then has `RMS_STOCH_VAR-X`, `-Y` and `-Z`. +- The random numbers come from a hash of the global node index, the direction and the time step. A run gives the same random field for any number of MPI ranks. +- The smoothing is an implicit Laplacian filter solved with successive over-relaxation at the first inner iteration of each time step. SU2 prints its residual on screen at every time step. After smoothing, SU2 rescales the field to keep its variance. +- The box is set at the first time step of the run. It does not follow mesh motion. +- With backscatter on, SU2 does not apply the SA under-relaxation (the `MAX_UPDATE_SA` limit on the update of ν̃). + +### Time averages + +A DES result is a time average. In a time-domain run, add `TIME_AVERAGE` to `VOLUME_OUTPUT`: + +``` +VOLUME_OUTPUT= ( COORDINATES, SOLUTION, PRIMITIVE, DDES, VORTEX_IDENTIFICATION, TIME_AVERAGE ) +WINDOW_START_ITER= 2000 +``` + +- SU2 averages density, velocity, pressure and skin friction (`MEAN_*`), and computes the resolved Reynolds stresses (`UUPRIME`, `VVPRIME`, `UVPRIME`, ...) and `PPRIME`. +- With a turbulence model, it also averages the modeled Reynolds stresses (`MODELED_REYNOLDS_STRESS_*`). With backscatter, it averages the random stresses (`STOCHASTIC_REYNOLDS_STRESS_*`). +- The average starts at `WINDOW_START_ITER` and gives every time step the same weight. `WINDOW_FUNCTION` does not apply to the volume averages. +- SU2 updates the averages at every time step, not only when it writes a file. +- The averages are not read back from a restart file. A restarted run starts a new average. This is why `WINDOW_START_ITER` defaults to `RESTART_ITER` and must not be smaller. + +History averages (`TAVG_*`) and the windowed Cauchy criterion are explained in the [unsteady setup guide](../Setup-Guide-Unsteady-DES/#time-averages-and-convergence-in-time). + +## What SU2 does differently from the literature + +All facts below are from `SU2_CFD/src/solvers/CTurbSASolver.cpp` (`SetDES_LengthScale`) unless stated. + +**Cell size.** The papers define the DES cell size on cells, for example the largest cell dimension Δmax = max(Δx, Δy, Δz). SU2 is vertex-based. It uses the longest edge from the node to any neighbor node (`CPhysicalGeometry::SetMaxLength`). On a hexahedral mesh this is close to the largest cell dimension. On a tetrahedral or prismatic mesh, it is the longest edge. + +**No low-Reynolds-number correction.** DDES (Spalart et al. 2006) multiplies the LES length scale by a function Ψ. Ψ stops the SA damping terms from reducing the subgrid viscosity when the eddy viscosity is small. SU2 computes Ψ (the variable `psi_2`) but never uses it. The LES length scale is always `DES_CONST` times the cell size. + +**`SA_DES` sensor.** The LES sensor is a switch: 0 where the wall distance is smaller than the LES length scale, 1 elsewhere. + +**`SA_ZDES` is not the full zonal method.** Deck (2012) describes a zonal method with several modes that the user assigns to regions. SU2 has one automatic mode: DDES with the vorticity-based cell size. The cell size per direction is the largest distance to a neighbor node along x, y and z. SU2 switches back to the longest-edge cell size where f_d < 0.99. Deck's mode 2 uses its own threshold for this switch (to be reviewed). + +**`SA_EDDES` cell size.** Shur et al. (2015) project the cell vertices onto the plane normal to the vorticity. SU2 uses the edges from the node to its neighbors instead. It takes the absolute value of each edge component before the cross product with the vorticity direction. The vortex tilting measure is averaged over the node and its neighbors. SU2 uses the longest-edge cell size where f_d < 0.999. The other constants (F_min = 0.1, F_max = 1, a1 = 0.15, a2 = 0.3) are those of the paper. + +**Shielding function.** `SA_DDES`, `SA_ZDES` and `SA_EDDES` use the DDES shielding function f_d with the constants 8 and 3 of the paper. The LES sensor output is f_d where the LES length scale is smaller than the wall distance, and 0 elsewhere. + +**Roughness.** With DES on, the SA source term uses the DES length scale and ignores `WALL_ROUGHNESS`. The rough-wall boundary condition and the eddy viscosity still use it. See [Wall Treatment](../Wall-Treatment/#roughness-with-sa). + +**Backscatter inside the SA equation.** Where the backscatter model is active (LES sensor above `SBS_FD_LOWER_THRESHOLD`), the SA source term uses fv1 = 1, fv2 = 0 and fw = 0 (`SU2_CFD/include/numerics/turbulent/turb_sources.hpp`). With fw = 0, the SA destruction term is switched off there. The random source added to the SA equation is limited to 5 times the production term. + +**Backscatter energy estimate.** The random stress scales with an estimate of the subgrid kinetic energy, (eddy viscosity / DES length scale)². In the momentum equations, SU2 uses the dynamic eddy viscosity μt for this estimate (`SU2_CFD/src/numerics/flow/flow_diffusion.cpp`). In the SA equation and in the averaged output, it uses the kinematic eddy viscosity νt (to be reviewed). + +## Equations and references + +This page does not repeat the model equations. See the original papers: + +- DES: P. R. Spalart, W.-H. Jou, M. Strelets, S. R. Allmaras, "Comments on the feasibility of LES for wings, and on a hybrid RANS/LES approach", *Advances in DNS/LES*, Greyden Press, 1997. +- DDES: P. R. Spalart et al., "A new version of detached-eddy simulation, resistant to ambiguous grid densities", *Theor. Comput. Fluid Dyn.* 20, 181–195, 2006. [doi:10.1007/s00162-006-0015-0](https://doi.org/10.1007/s00162-006-0015-0) +- ZDES: S. Deck, "Recent improvements in the Zonal Detached Eddy Simulation (ZDES) formulation", *Theor. Comput. Fluid Dyn.* 26, 523–550, 2012. [doi:10.1007/s00162-011-0240-z](https://doi.org/10.1007/s00162-011-0240-z) +- EDDES: M. L. Shur et al., "An enhanced version of DES with rapid transition from RANS to LES in separated flows", *Flow Turbul. Combust.* 95, 709–737, 2015. [doi:10.1007/s10494-015-9618-0](https://doi.org/10.1007/s10494-015-9618-0) +- NTS blending: A. Travin et al., "Physical and numerical upgrades in the detached-eddy simulation of complex turbulent flows", *Advances in LES of Complex Flows*, 239–254, 2002. [doi:10.1007/0-306-48383-1_16](https://doi.org/10.1007/0-306-48383-1_16) +- NTS form used in SU2: Z. Xiao et al., "Numerical dissipation effects on massive separation around tandem cylinders", *AIAA J.* 50(5), 1119–1136, 2012. [doi:10.2514/1.J051299](https://doi.org/10.2514/1.J051299) +- NTS with Ducros sensor: Z. Xiao et al., *Int. J. Heat Fluid Flow* 51, 138–150, 2015. [doi:10.1016/j.ijheatfluidflow.2014.10.007](https://doi.org/10.1016/j.ijheatfluidflow.2014.10.007) +- Stochastic backscatter: J. C. Kok, "A stochastic backscatter model for grey-area mitigation in detached eddy simulations", *Flow Turbul. Combust.* 99, 119–150, 2017. [doi:10.1007/s10494-017-9809-y](https://doi.org/10.1007/s10494-017-9809-y) +- SA model: [NASA Turbulence Modeling Resource, SA page](https://tmbwg.github.io/turbmodels/spalart.html). + +## Recommended use + +All advice in this section is general practice, not checked in SU2 (to be reviewed). + +- **Variant.** Prefer `SA_DDES` or `SA_EDDES` over `SA_DES`. Plain DES can switch to LES inside an attached boundary layer if the mesh is fine along the wall. The flow can then separate because of the mesh (to be reviewed). +- **Mesh.** Run DES in 3D. Resolve the boundary layer as for RANS (y+ about 1, no wall functions). In the separated region, use nearly cubic cells: the cell size sets the LES filter. In the spanwise direction, the domain must be large enough to hold the largest eddies (to be reviewed). +- **Time step.** Choose a time step so that the convective CFL number, based on the local cell size and velocity, is about 1 or less in the LES region (to be reviewed). +- **Time marching.** Use `TIME_MARCHING= DUAL_TIME_STEPPING-2ND_ORDER`, as in the test cases. Converge the inner iterations by 2 to 3 orders per time step (to be reviewed). +- **Convective scheme.** Use a second-order scheme (`MUSCL_FLOW= YES`) without a slope limiter where there are no shocks. With `ROE`, `SLAU` or `SLAU2`, try `ROE_LOW_DISSIPATION= FD` or `NTS`. Add a `_DUCROS` variant if there are shocks (to be reviewed). +- **Statistics.** Exclude the start-up transient with `WINDOW_START_ITER`, then sample over many characteristic times. Compare separate sampling blocks and extend the interval; a flat cumulative average or passing Cauchy criterion alone does not establish statistical convergence (advice, to be reviewed). +- **Check the switch.** Plot `LES_SENSOR` and `DES_LENGTHSCALE`. Attached boundary layers should stay at sensor 0 (RANS). Separated regions should show sensor near 1 (LES). + +## Output fields + +| Group | Fields | When | +|---|---|---| +| `DDES` | `DES_LENGTHSCALE`, `WALL_DISTANCE`, `LES_SENSOR` | `HYBRID_RANSLES` is not `NONE` | +| `BACKSCATTER` | `STOCHSOURCE_X/Y/Z`, `ENERGY_BACKSCATTER_RATIO` | Backscatter on | +| `SOLUTION`, `RESIDUAL` | `STOCHVAR_X/Y/Z`, `RES_STOCHVAR_X/Y/Z` | Backscatter on with `SBS_TIMESCALE_COEFF` > 0 | +| `ROE_DISSIPATION` | `ROE_DISSIPATION` | Compressible solver with `ROE_LOW_DISSIPATION` set | +| `TIME_AVERAGE` | `MEAN_*`, `RMS_*`, `*PRIME`, `MODELED_REYNOLDS_STRESS_*`, `STOCHASTIC_REYNOLDS_STRESS_*` | Time-domain run | + +Note: the `RMS_U`, `RMS_V`, ... fields hold the mean of the squared value (for example the mean of u²), not the root mean square. The fluctuations are in `UUPRIME`, `VVPRIME`, and so on. + +The full list is in the [Output Fields Reference](../Output-Fields-Reference/). + +## Verification and test cases + +There is no verification case for DES in the [V&V section](/vandv/home/). The regression tests only check that the options run: + +- [`TestCases/ddes/flatplate/ddes_flatplate.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/ddes/flatplate/ddes_flatplate.cfg): `SA_EDDES` on a 2D flat plate, compressible, `SLAU2`. A 2D flat plate is not a real DES case. +- [`TestCases/backscatter/backward_step/backwardStep.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/backscatter/backward_step/backwardStep.cfg): `SA_DDES` with stochastic backscatter in a box, incompressible, `LD2` scheme, periodic in the spanwise direction. It shows all `SBS_*` options and the `TIME_AVERAGE` output. + +Background: [An Overview of DDES in SU2: Implementation and Recent Results](/documents/dev_meeting_2017/su2_dev_molina.pdf) (2017 developers meeting). + +## Known limits + +- **DES with SST runs as URANS, without a warning.** SU2 accepts `HYBRID_RANSLES` with `KIND_TURB_MODEL= SST`. The SST solver ignores it, and the run is plain URANS. The screen still prints the DES variant, and `DES_LENGTHSCALE` and `LES_SENSOR` are written as zero. +- **No check for steady runs.** SU2 does not stop if `HYBRID_RANSLES` is set with `TIME_DOMAIN= NO`. A steady DES has no physical meaning. +- **`ROE_LOW_DISSIPATION` is ignored** with schemes other than `ROE`, `SLAU` and `SLAU2`, and in the incompressible solver, without a warning. +- **Backscatter is 3D only** and needs the SA model. +- **Wall roughness is only partly used with DES** (see [Roughness](#what-su2-does-differently-from-the-literature)). +- **Time averages restart from zero** after a restart. + +## Links + +- [Setup Guide: Unsteady Flows and DES](../Setup-Guide-Unsteady-DES/) +- [Setup Guide: RANS External Aerodynamics](../Setup-Guide-RANS-External-Aero/) +- [Turbulence Models](../Turbulence-Models/) +- [Wall Treatment: Wall Functions and Roughness](../Wall-Treatment/) +- [Option Reference](../Option-Reference/) +- [Output Fields Reference](../Output-Fields-Reference/) +- [Markers and Boundary Conditions](../Markers-and-BC/) + +--- + +Source review: 22 October 2026, against [SU2 `docs_site` at `41ea6a219a`](https://github.com/rois1995/SU2/tree/41ea6a219ac038574f3d4a5b130c0c1d8af66457). See the [review scope and outstanding validation](../Documentation-Status/#guide-and-model-review). Setup recommendations remain draft where indicated. diff --git a/_docs_v7/Multizone.md b/_docs_v7/Multizone.md index f902f15a..ef802df2 100644 --- a/_docs_v7/Multizone.md +++ b/_docs_v7/Multizone.md @@ -7,7 +7,7 @@ SU2 is capable of solving physical problems in distinct zones coupled through in --- -- [What is a Zone ?](#what-is-a-zone) +- [What is a Zone?](#what-is-a-zone) - [Multi-zone and Multi-physics](#multi-zone-and-multi-physics) - [How to set up a single-physics problem](#how-to-set-up-a-single-physics-problem) - [Sub-config files](#sub-config-files) @@ -16,7 +16,7 @@ SU2 is capable of solving physical problems in distinct zones coupled through in --- -## What is a Zone ? ## +## What is a Zone? ## We refer to a Zone as a subdomain in your physical problem. For example consider a heated cylinder immersed into a fluid. In this case, the solid cylinder would be refered to as zone 0 and the fluid domain as zone 1. All zones can be discretized independently and do not need to be matching at the interfaces. See the figure below. ![Definition of a Zone](../../docs_files/zones.png) @@ -80,13 +80,13 @@ ROTATION_RATE = 0.0 0.0 160.0 ### How to set up a multi-physics problem ### -While for the single-physics problems the usage of sub-config files is optional, setting up a multi-physics problem heavily relies on this feature. A good way to start is to first create a separate config file for each individual zone. If it is possible, also try to run each zone independently (with appropriate boundary conditions) to find proper numerical settings. To couple the zones create a new config file with the option `MATH_PROBLEM` set to `MULTIPHYSICS`. Then specify the list of config files with `CONFIG_LIST`. These two options are mandatory. To set a coupling between the zones the `MARKER_ZONE_INTERFACE` option can be used (same way as for the [single-physics problem](#singlephysics)). As an example consider the following main config file: +While for the single-physics problems the usage of sub-config files is optional, setting up a multi-physics problem heavily relies on this feature. A good way to start is to first create a separate config file for each individual zone. If it is possible, also try to run each zone independently (with appropriate boundary conditions) to find proper numerical settings. To couple the zones create a new config file with the option `SOLVER` set to `MULTIPHYSICS`. Then specify the list of config files with `CONFIG_LIST`. These two options are mandatory. To set a coupling between the zones the `MARKER_ZONE_INTERFACE` option can be used (same way as for the [single-physics problem](#how-to-set-up-a-single-physics-problem)). As an example consider the following main config file: ``` % main_config.cfg % ------------------------ MULTI-PHYSICS SETUP --------------------------------% % Problem definition -PHYSICAL_PROBLEM= MULTIPHYSICS +SOLVER= MULTIPHYSICS % The list of config files CONFIG_LIST = (configFlow.cfg, configSolid.cfg) diff --git a/_docs_v7/Physical-Definition.md b/_docs_v7/Physical-Definition.md index 09d52bf7..d3ad5364 100644 --- a/_docs_v7/Physical-Definition.md +++ b/_docs_v7/Physical-Definition.md @@ -24,8 +24,8 @@ SU2 offers different ways of setting and computing this definition. This documen - [Thermodynamic and Gauge Pressure](#thermodynamic-and-gauge-pressure) - [Initial State and Non-Dimensionalization](#initial-state-and-non-dimensionalization) - [Turbulence Models](#turbulence-models) - - [Spalart-Allmaras (SA)](#spalart-allmaras-model) - - [Shear Stress Transport (SST)](#shear-stress-transport) + - [Spalart-Allmaras (SA)](#spalart-allmaras-sa) + - [Shear Stress Transport (SST)](#shear-stress-transport-sst) - [Transition Models](#transition-models) --- @@ -127,7 +127,7 @@ The NEMO solvers require a specification of thermochemical nonequilibrium librar A chemistry model, consisting of a set of flow species, thermochemical properties, and chemical reactions, is specified using `GAS_MODEL`. The names of these models are specific to the thermochemical library. If using the `SU2_NONEQ` option the choices are `ARGON`, `N2`, `AIR-5`, and `AIR-7`. -Free-stream mass fractions must also be specified in list using the option `GAS_COMPOSITION`. The mass fractions are specified as decimal values in the order of the species in the gas model. For example, an AIR-5 mixture of 77% oxygen and 23% nitrogen would be expressed as (0.77, 0.23, 0.00, 0.00, 0.00). +Free-stream mass fractions must also be specified in list using the option `GAS_COMPOSITION`. The mass fractions are specified as decimal values in the order of the species in the gas model. With `FLUID_MODEL= SU2_NONEQ` and `GAS_MODEL= AIR-5`, the species order is N2, O2, NO, N, O. A mixture of 77% nitrogen and 23% oxygen by mass is therefore `GAS_COMPOSITION= (0.77, 0.23, 0.00, 0.00, 0.00)`. ## Transport Coefficient Model (Thermochemical Nonequilibrium) ## @@ -163,81 +163,19 @@ The reference values $$\rho_{ref}, T_{ref}, v_{ref}$$ equal the initial state va ## Turbulence Models ## -| Solver | Version | -| --- | --- | -| `*_RANS` | 7.4.0 | - -This section describes how to setup turbulence models for RANS simulations. Turbulence is activated using the option `KIND_SOLVER= RANS`, or `KIND_SOLVER= INC_RANS` -A turbulence model can then be selected via the option `KIND_TURB_MODEL` -Different submodels and parameters are specified via the different options listed below. -The turbulent Prandtl number can be modified with the option `PRANDTL_TURB` (the default is 0.9). - -### Spalart-Allmaras (SA) ### - -SU2 implements several versions and corrections of the SA model. -The model is selected using `KIND_TURB_MODEL= SA` and the modifications via the `SA_OPTIONS` list. If this list is empty, then SU2 defaults to `SA-noft2`. -The freestream and inlet conditions are specified via the option `FREESTREAM_NU_FACTOR= 3` (ratio of SA variable to freestream kinematic viscosity). - -The following modifications are allowed (refer to [NASA's TMR](https://turbmodels.larc.nasa.gov/spalart.html) for further info): -- Versions: - - `NEGATIVE` - Negative SA model. - - `EDWARDS` - Edwards modification. - - `BCM` - BCM transitional model. - - `WITHFT2` - SA model **with** ft2 term, note that by default we omit this term. -- Corrections: - - `QCR2000` - Quadratic contitutive relation used in the stress tensor. - - `COMPRESSIBILITY` - Mixing layer compressibility correction. - - `ROTATION` - Dacles-Mariani et al. rotation correction. - -All the modifications can be combined with each other expect `NEGATIVE` and `EDWARDS`. -For example, to specify `SA-neg-R-comp-QCR2000` use `SA_OPTIONS= NEGATIVE, WITHFT2, ROTATION, COMPRESSIBILITY, QCR2000`. -**However, some combinations are not considered standard**, e.g. `SA-neg` should have the ft2 term, whereas `SA-noft2-Edwards` and `SA-noft2-BCM` should not have the ft2 term, and they are usually not combined with other corrections (see TMR for more details). To use non-standard combinations it is necessary to add `EXPERIMENTAL` to the option list, e.g. `SA_OPTIONS= NEGATIVE, BCM, EXPERIMENTAL`. +Set `SOLVER= RANS` or `SOLVER= INC_RANS`, and choose the model with `KIND_TURB_MODEL= SA` or `KIND_TURB_MODEL= SST`. +Choose the variant with `SA_OPTIONS` or `SST_OPTIONS`. The defaults are SA without the ft2 term and SST-2003m. -The rough wall correction is implicitly turned on by specifying roughness values for wall markers via the `WALL_ROUGHNESS` option. +### Spalart-Allmaras (SA) -### Shear Stress Transport (SST) ### +See [SA variants and inlet values](../Turbulence-Models/#spalart-allmaras-sa), including the differences between SU2 and the published models. -SU2 implements the "Standard" (1994) and 2003 versions of the SST model along with several modifications. +### Shear Stress Transport (SST) -**Note:** Currently all versions are "modified" i.e. the turbulence kinetic energy (TKE) is not included in the viscous stress tensor. - -The main model is selected using `KIND_TURB_MODEL= SST` and the version and modifications via the `SST_OPTIONS` list. If this list is empty SU2 defaults to the baseline 1994 model, `V1994m` (see warning below). The options allow for a version and a set of modifiers to the version. -The freestream and inlet conditions are specified via the options `FREESTREAM_TURBULENCEINTENSITY= 0.05` (5%) and `FREESTREAM_TURB2LAMVISCRATIO= 10` (ratio of turbulent to laminar viscosity). - -**Note:** The default values for these options are suitable for internal flows but may be too high for external aerodynamics problems. - -The following modifications are allowed: -- Versions: - - `V1994m` - SSTm **WARNING:** Our implementation has a small [inconsistency with the literature](https://github.com/su2code/SU2/issues/1551), which will be resolved in the next major SU2 update (i.e. version 8). - - `V2003m` - SST-2003m (no known inconsistencies). -- Production modifications: - - `VORTICITY` - Uses vorticity to compute the source term instead of strain-rate magnitude. - - `KATO_LAUNDER` - Uses the Kato-Launder modification (vorticity times strain-rate). - - `UQ` - Production is computed using a modified stress tensor for [uncertainty quantification](https://su2code.github.io/tutorials/UQ_NACA0012/). **Note** with this modification TKE is always included in the stress tensor. -- Corrections: - - `SUSTAINING` - SST with controlled decay. - - Curvature corrections are currently not implemented. - -Modifications from each of these three groups can be combined, for example `SST_OPTIONS= V2003m, VORTICITY, SUSTAINING` +See [SST variants and inlet values](../Turbulence-Models/#shear-stress-transport-sst), including the differences between SU2 and the published models. ## Transition Models ## -| Solver | Version | -| --- | --- | -| `*_RANS` | 7.5.0 | - -This section describes how to setup transition models for RANS simulations. Transition is activated using the option `KIND_SOLVER= RANS`, or `KIND_SOLVER= INC_RANS` together with a choice of `KIND_TRANS_MODEL` (different from `NONE`). -Currently, the only valid option for `KIND_TRANS_MODEL` is `LM`, for Langtry-Menter transition models. -Different submodels and correlations are then specified via `LM_OPTIONS` (for example `LM_OPTIONS= LM2015, MENTER_LANGTRY`). - -The following modifications are allowed: -- Versions: - - `LM2015` - Correction to include stationary crossflow instabilities. It has to be used only in 3D problems. The RMS of roughness used in this model has to be set through the separate option `HROUGHNESS`. -- Correlations (only one can be specified): - - `MALAN` - This is the default correlation when the LM model is coupled with the `SA` turbulence model. - - `SULUKSNA` - This should be used only if the `SST` model is used. It should require a formulation of the Re_theta_t correlation that omits the pressure gradient parameter, however it is not clear. - - `KRAUSE` - This correlation should be used for hypersonic flows. Its implementation at the moment is unclear due to inconsistencies in the literature. - - `KRAUSE_HYPER` - This correlation should be used for hypersonic flows. Its implementation at the moment is unclear due to inconsistencies in the literature. - - `MEDIDA` - Designed for `SA` turbulence model. Has problems when dealing with separation induced transition. - - `MEDIDA_BAEDER` - Designed for `SA` turbulence model. Has problems when dealing with separation induced transition. - - `MENTER_LANGTRY` - This is the default correlation when the LM model is coupled with the `SST` turbulence model. +Set `KIND_TRANS_MODEL= LM` for the Langtry-Menter model, with SST or SA, and choose the version and correlation with `LM_OPTIONS`. +For the algebraic SA-BCM model, set `KIND_TURB_MODEL= SA` and `SA_OPTIONS= BCM`. +[Transition Models](../Transition-Models/) describes both models and their options. diff --git a/_docs_v7/Running-Unit-Tests.md b/_docs_v7/Running-Unit-Tests.md index 85ebfde5..842ed305 100644 --- a/_docs_v7/Running-Unit-Tests.md +++ b/_docs_v7/Running-Unit-Tests.md @@ -17,7 +17,7 @@ code. Unit tests are only supported with meson builds. You must build from source to build the unit tests. They are not part of the pre-compiled -executables. For more information, see [Installation](/docs_v7/Installation.md), +executables. For more information, see [Installation](/docs_v7/Installation/), and [Build SU2 on Linux/MacOS](/docs_v7/Build-SU2-Linux-MacOS/). In order to compile the unit tests, add the flag `-Denable-tests=true` diff --git a/_docs_v7/Setup-Guide-Heat-Transfer-CHT.md b/_docs_v7/Setup-Guide-Heat-Transfer-CHT.md new file mode 100644 index 00000000..09d85d14 --- /dev/null +++ b/_docs_v7/Setup-Guide-Heat-Transfer-CHT.md @@ -0,0 +1,296 @@ +--- +title: "Setup Guide: Heat Transfer and Conjugate Heat Transfer" +permalink: /docs_v7/Setup-Guide-Heat-Transfer-CHT/ +--- + +{% include setup-guide-intro.md %} + +--- + +- [When to use this guide](#when-to-use-this-guide) +- [Start from](#start-from) +- [Settings that matter](#settings-that-matter) +- [Check convergence and results](#check-convergence-and-results) +- [Common problems](#common-problems) +- [Related tutorials and test cases](#related-tutorials-and-test-cases) + +--- + +## When to use this guide + +Use this guide when temperature matters in your simulation: + +- a fluid with heated or cooled walls, +- heat conduction in a solid alone, +- conjugate heat transfer (CHT): heat flows between a fluid zone and one or more solid zones, and SU2 solves all zones together. + +The examples use the incompressible solver. CHT also works with the compressible `NAVIER_STOKES` solver; see the test case [`coupled_cht/comp_2d`](https://github.com/su2code/SU2/blob/develop/TestCases/coupled_cht/comp_2d/cht_2d_3cylinders.cfg). +For the fluid settings, read [Setup Guide: Incompressible Flows](../Setup-Guide-Incompressible/) first. +For the general multizone setup, read [Basics of Multi-Zone Computations](../Multizone/). + +Every option is listed in the [option reference](../Option-Reference/). +Every output field is listed in the [output fields reference](../Output-Fields-Reference/). + +## Start from + +This setup is a 2D laminar air flow around three cylinders. Each cylinder is a solid zone with a hot core at 350 K. +It is the test case [`coupled_cht/incomp_2d`](https://github.com/su2code/SU2/blob/develop/TestCases/coupled_cht/incomp_2d/cht_2d_3cylinders.cfg) with fewer options. The [steady CHT tutorial](/tutorials/Static_CHT/) uses the same case. +Changes to the test case: `OUTER_ITER` is raised from 11 to 2000, and `HISTORY_OUTPUT` and `OUTPUT_FILES` are added to the main file. +The mesh `mesh_cht_3cyl.su2` holds all four zones. It is in the folder `coupled_cht/incomp_2d` of the [TestCases repository](https://github.com/su2code/TestCases). + +Main config file `cht_2d_3cylinders.cfg`: + +``` +SOLVER= MULTIPHYSICS +CONFIG_LIST= (flow_cylinder.cfg, solid_cylinder1.cfg, solid_cylinder2.cfg, solid_cylinder3.cfg) +% +% Pairs of markers that touch: fluid side, solid side +MARKER_ZONE_INTERFACE= (cylinder_outer1, cylinder_inner1, cylinder_outer2, cylinder_inner2, cylinder_outer3, cylinder_inner3) +MARKER_CHT_INTERFACE= (cylinder_outer1, cylinder_inner1, cylinder_outer2, cylinder_inner2, cylinder_outer3, cylinder_inner3) +CHT_COUPLING_METHOD= DIRECT_TEMPERATURE_ROBIN_HEATFLUX +% +TIME_DOMAIN= NO +OUTER_ITER= 2000 +% +MESH_FILENAME= mesh_cht_3cyl.su2 +MESH_FORMAT= SU2 +HISTORY_OUTPUT= (ITER, BGS_RES[0], BGS_RES[1], HEAT[0]) +OUTPUT_FILES= (RESTART, PARAVIEW_MULTIBLOCK) +``` + +Fluid zone `flow_cylinder.cfg`: + +``` +SOLVER= INC_NAVIER_STOKES +KIND_TURB_MODEL= NONE +% +INC_DENSITY_MODEL= VARIABLE +INC_ENERGY_EQUATION= YES +INC_DENSITY_INIT= 0.000210322 +INC_VELOCITY_INIT= ( 3.40297, 0.0, 0.0 ) +INC_TEMPERATURE_INIT= 288.15 +INC_NONDIM= DIMENSIONAL +FLUID_MODEL= INC_IDEAL_GAS +SPECIFIC_HEAT_CP= 1004.703 +MOLECULAR_WEIGHT= 28.96 +VISCOSITY_MODEL= CONSTANT_VISCOSITY +MU_CONSTANT= 1.7893e-05 +CONDUCTIVITY_MODEL= CONSTANT_PRANDTL +PRANDTL_LAM= 0.72 +% +MARKER_FAR= ( farfield ) +MARKER_MONITORING= ( cylinder_outer1, cylinder_outer2, cylinder_outer3 ) +% +NUM_METHOD_GRAD= GREEN_GAUSS +CONV_NUM_METHOD_FLOW= FDS +MUSCL_FLOW= YES +SLOPE_LIMITER_FLOW= NONE +TIME_DISCRE_FLOW= EULER_IMPLICIT +CFL_NUMBER= 10.0 +LINEAR_SOLVER= FGMRES +LINEAR_SOLVER_PREC= ILU +LINEAR_SOLVER_ERROR= 1E-15 +LINEAR_SOLVER_ITER= 5 +``` + +Solid zone `solid_cylinder1.cfg` (zones 2 and 3 are the same, with `core2` and `core3`): + +``` +SOLVER= HEAT_EQUATION +INC_NONDIM= DIMENSIONAL +FREESTREAM_TEMPERATURE= 350.0 +% +MATERIAL_DENSITY= 0.000210322 +SPECIFIC_HEAT_CP= 1004.703 +THERMAL_CONDUCTIVITY_CONSTANT= 0.1028 +% +MARKER_ISOTHERMAL= ( core1, 350.0 ) +% +NUM_METHOD_GRAD= GREEN_GAUSS +TIME_DISCRE_HEAT= EULER_IMPLICIT +CFL_NUMBER= 10.0 +LINEAR_SOLVER= FGMRES +LINEAR_SOLVER_PREC= ILU +LINEAR_SOLVER_ERROR= 1E-15 +LINEAR_SOLVER_ITER= 5 +``` + +The zone files do not list the interface markers as boundary conditions. `MARKER_CHT_INTERFACE` in the main file sets them, and the zone files inherit every option of the main file ([Multizone](../Multizone/#how-to-set-up-a-multi-physics-problem)). + +## Settings that matter + +### Thermal wall conditions in the fluid + +These conditions need the energy equation in the fluid: `INC_ENERGY_EQUATION= YES` for the incompressible solver. + +- `MARKER_ISOTHERMAL= ( marker, T [K] )`: fixed wall temperature. Use it when you know the wall temperature. +- `MARKER_HEATFLUX= ( marker, q [W/m²] )`: fixed heat flux. Zero gives an adiabatic wall. With `INTEGRATED_HEATFLUX= YES`, the value is a total heat rate in W, spread over the marker area ([Markers and BC](../Markers-and-BC/#constant-heatflux-no-slip-wall)). In these finite-volume thermal boundary conditions, a positive value adds heat to the domain (code). For a planar 2D case, integrated heat rates represent a unit out-of-plane depth. +- `MARKER_HEATTRANSFER= ( marker, h [W/(m² K)], T_inf [K] )`: the wall heat flux is h·(T_inf − T_wall). Use it to model a wall that you do not mesh, such as a thin wall to an outside fluid. h = 0 gives an adiabatic wall; a very large h gives a wall at T_inf ([Markers and BC](../Markers-and-BC/#heat-transfer-or-convection-no-slip-wall)). + +Only the flow solvers implement `MARKER_HEATTRANSFER`. The heat equation solver for solids does not (code). + +### Temperature without coupling to the flow + +If the temperature does not change the flow (constant density and constant properties), you have two options: + +- `INC_DENSITY_MODEL= CONSTANT` with `INC_ENERGY_EQUATION= YES`: the flow solver solves for enthalpy and recovers temperature from the fluid model ([laminar flat plate tutorial](/tutorials/Inc_Laminar_Flat_Plate/)). +- `WEAKLY_COUPLED_HEAT_EQUATION= YES` with `INC_ENERGY_EQUATION= NO`: SU2 solves the temperature with the separate heat solver, using the flow velocity (code). Its numerics use `CONV_NUM_METHOD_HEAT`, `MUSCL_HEAT`, `TIME_DISCRE_HEAT` and `TIMESTEP_HEAT`. Example: [`disc_adj_heat/primal.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/disc_adj_heat/primal.cfg). + +For incompressible CHT, SU2 stops unless the fluid zone has `INC_ENERGY_EQUATION= YES` (code). So in CHT, use the energy equation, not the weakly coupled heat equation. + +### Heat conduction in a solid + +Set `SOLVER= HEAT_EQUATION` in the solid zone. This solver solves for temperature only. + +- `THERMAL_CONDUCTIVITY_CONSTANT` [W/(m K)], `MATERIAL_DENSITY` [kg/m³] and `SPECIFIC_HEAT_CP` [J/(kg K)] define the material. +- The defaults are meant for other uses: 0.0257 W/(m K) for air, 7854 kg/m³ for steel, 1004.703 J/(kg K) for air (code). So always set all three. +- `FREESTREAM_TEMPERATURE` (default 288.15 K) is the initial solid temperature (code). +- Boundary conditions: `MARKER_ISOTHERMAL`, `MARKER_HEATFLUX`, `MARKER_PERIODIC`, and the CHT interface. +- All solid test cases use `INC_NONDIM= DIMENSIONAL` (test case). + +For steady conduction with prescribed thermal boundary data, density and specific heat drop out of the physical heat equation; they still affect the numerical convergence. Conductivity sets the heat flux and, with flux or Robin data, the temperature gradients. A uniform conductivity cancels from a source-free, purely prescribed-temperature problem. Density and specific heat set the thermal response time in an unsteady run. + +A solid alone runs as a normal single-zone case, for example [`solid_heat_conduction/periodic_pins/configSolid.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/solid_heat_conduction/periodic_pins/configSolid.cfg). + +### Zones and config files + +A CHT case is a multiphysics case ([Multizone](../Multizone/#how-to-set-up-a-multi-physics-problem)): + +1. Write one config file per zone. Each one sets `SOLVER`, and the boundary conditions and numerics of the zone. +2. Write a main config file with `SOLVER= MULTIPHYSICS` and `CONFIG_LIST`, the list of zone files. The order in `CONFIG_LIST` gives the zone number, starting at 0. +3. Options that are the same in all zones can go in the main file. The zone files inherit them ([Multizone](../Multizone/#how-to-set-up-a-multi-physics-problem)). + +The mesh: + +- One file for all zones: `MULTIZONE_MESH= YES` (default). This works with the SU2 mesh format, with `NZONE=` and `IZONE=` in the mesh file ([Multizone](../Multizone/#providing-mesh-information-for-a-multi-zone-problem)). +- One file per zone: `MULTIZONE_MESH= NO`, and `MESH_FILENAME` in each zone file. The [contact resistance tutorial](/tutorials/SS_CR_CHT/) uses three mesh files. + +Run each zone alone first, with a fixed temperature or heat flux at the interface, to find numerical settings that work (advice). The [Multizone](../Multizone/#how-to-set-up-a-multi-physics-problem) page gives the same advice. + +### Interface markers + +Each interface has two markers, one on each side. List the pairs in the main file: + +- `MARKER_ZONE_INTERFACE`: pairs of markers that exchange data. +- `MARKER_CHT_INTERFACE`: the same pairs, marked as heat transfer interfaces. + +All CHT test cases and tutorials list the pairs in both options (test case, tutorial). + +### Coupling method + +`CHT_COUPLING_METHOD` decides what crosses the interface (code): + +- `DIRECT_TEMPERATURE_ROBIN_HEATFLUX` (default): the fluid gets the solid wall temperature. The solid gets a heat flux computed from its own wall temperature and the fluid temperature next to the wall. This is a Robin condition, which mixes temperature and heat flux. All CHT test cases use this method (test case). +- `DIRECT_TEMPERATURE_NEUMANN_HEATFLUX`: the solid gets the heat flux computed by the fluid. This is a Neumann condition, a prescribed flux. +- `AVERAGED_TEMPERATURE_ROBIN_HEATFLUX` and `AVERAGED_TEMPERATURE_NEUMANN_HEATFLUX`: the fluid wall temperature is a conductivity-weighted average of the temperatures on both sides. + +The Robin methods need the fluid conductivity. With `CONDUCTIVITY_MODEL= POLYNOMIAL_CONDUCTIVITY` in an incompressible fluid zone, SU2 stops (code). +Start with the default, because it is the only method used in the tests (advice, to be reviewed). + +### Interface interpolation + +The two sides of an interface do not need matching meshes ([Multizone](../Multizone/)). +`KIND_INTERPOLATION` chooses how SU2 moves values between them (code): + +- `NEAREST_NEIGHBOR` (default): each point takes the value of the closest point on the other side. `NUM_NEAREST_NEIGHBORS` (default 1) sets how many neighbors SU2 uses. +- `ISOPARAMETRIC`: interpolation inside the faces of the other side. +- `RADIAL_BASIS_FUNCTION`: smooth interpolation with radial basis functions (`KIND_RADIAL_BASIS_FUNCTION`). + +`WEIGHTED_AVERAGE` is the sliding mesh method for fluid-fluid interfaces, not for CHT. +SU2 uses the method of the donor zone, so set it in the main file to apply it everywhere (code). +No CHT test case changes the default (test case). +With very different mesh sizes on the two sides, `ISOPARAMETRIC` or `RADIAL_BASIS_FUNCTION` can give a smoother interface temperature than `NEAREST_NEIGHBOR` (advice, to be reviewed). + +### Contact resistance between solids + +`CHT_INTERFACE_CONTACT_RESISTANCE` models imperfect contact between two solids: the temperature jumps across the interface ([tutorial](/tutorials/SS_CR_CHT/)). + +These rules come from the code (code): + +- Give one value per interface pair, or one value for all pairs. Values must not be negative. +- It acts only between two `HEAT_EQUATION` zones, and only with the two `..._ROBIN_HEATFLUX` coupling methods. On fluid-solid interfaces it has no effect. +- The heat flux is (T − T_wall) / (d/k + R), where d is the distance from the wall to the next point and k the conductivity. So R is in m²·K/W, the inverse of a heat transfer coefficient. + +The tutorial gives the values in the order of the pairs in `MARKER_CHT_INTERFACE`: `CHT_INTERFACE_CONTACT_RESISTANCE= (1e-4, 0, 0)` (tutorial). + +### Outer and inner iterations + +SU2 solves the zones one after the other and exchanges interface data between them. One pass over all zones is an outer iteration. + +- `OUTER_ITER` (main file): the number of outer iterations of a steady case, or per time step of an unsteady case. +- `INNER_ITER` (default 1): the iterations of each zone inside one outer iteration (code, tutorial). You can set it per zone file. +- `MULTIZONE_SOLVER`: `BLOCK_GAUSS_SEIDEL` (default) or `BLOCK_JACOBI` (code). Gauss-Seidel uses the newest data of the zones already solved, and Jacobi uses the data of the previous outer iteration (advice). +- `RELAXATION_FACTOR_CHT` (default 1.0, no relaxation): the new interface value is factor × new + (1 − factor) × old (code). +- `ITER` is not allowed in multizone cases: SU2 stops. Use `OUTER_ITER` and `INNER_ITER` (code). + +The solid often converges more slowly than the fluid, because heat conduction has no convection to carry information. A larger `CFL_NUMBER` can accelerate the solid solve if the linear system remains adequately solved; the solid-only test case `solid_heat_conduction/periodic_pins` uses 1e8 (advice, to be reviewed). + +### Unsteady CHT + +Set the time settings in the main file ([unsteady CHT tutorial](/tutorials/Inc_Heated_Cylinders_Unsteady/)): + +``` +TIME_DOMAIN= YES +TIME_MARCHING= DUAL_TIME_STEPPING-2ND_ORDER +TIME_STEP= 0.05 +MAX_TIME= 100.0 +TIME_ITER= 3 +OUTER_ITER= 10 +``` + +These values are from the test case [`coupled_cht/incomp_2d_unsteady`](https://github.com/su2code/SU2/blob/develop/TestCases/coupled_cht/incomp_2d_unsteady/cht_2d_3cylinders.cfg) (test case). The tutorial uses `OUTER_ITER= 200` to converge the coupling in each time step (tutorial). + +- Choose `TIME_STEP` from the time scale of the flow, for example the vortex shedding period ([tutorial](/tutorials/Inc_Heated_Cylinders_Unsteady/)). +- In unsteady runs, the solid density and specific heat matter, so set real material values. +- Solids often respond much more slowly than the fluid. Reaching a periodic state can take many time steps (advice, to be reviewed). + +## Check convergence and results + +- **Coupling residuals.** In a multizone case, SU2 prints for each zone how much the solution changed since the last outer iteration. These are the block Gauss-Seidel (BGS) residuals. Fields such as `BGS_PRESSURE[0]` and `BGS_TEMPERATURE[1]` are per zone; the number in brackets is the zone. Add the group `BGS_RES[i]` to `HISTORY_OUTPUT` for zone i. +- **Default stop rule.** Without `CONV_FIELD`, a multizone case monitors `AVG_BGS_RES[0]`, the averaged BGS residual of zone 0 (code). Set `CONV_FIELD` and `CONV_RESIDUAL_MINVAL` in the main file to monitor what you need, for example the solid temperature. The pin array test case sets `CONV_RESIDUAL_MINVAL` in its main file (test case). +- **Field names.** SU2 ignores unknown names in `CONV_FIELD` and prints `Ignoring Convergence Field(s)` at the start (code). +- **Heat balance.** Monitor `TOTAL_HEATFLUX` and `AVG_TEMPERATURE` (group `HEAT`) on the interface markers, through `MARKER_MONITORING` in each zone. At steady convergence, integrate conductive heat flux on both sides with a consistent normal convention: heat leaving the solid equals heat entering the fluid. With outward normals for both domains, their signed interface rates sum to zero. Non-matching interpolation also needs a conservation check (advice). +- **Per-zone history.** `WRT_ZONE_HIST= YES` writes a history file per zone. `WRT_ZONE_CONV= YES` prints the convergence of each zone (code). +- **Visual check.** `OUTPUT_FILES= (RESTART, PARAVIEW_MULTIBLOCK)` writes one ParaView file with all zones. The temperature should be continuous across solid-fluid interfaces ([contact resistance tutorial](/tutorials/SS_CR_CHT/)). + +## Common problems + +| Symptom | Likely cause | What to try | +|---|---|---| +| SU2 stops: "You probably want to set INC_ENERGY_EQUATION= YES for the fluid solver". | The incompressible fluid zone has no energy equation (code). | Set `INC_ENERGY_EQUATION= YES` in the fluid zone file. | +| SU2 stops: "ITER must not be used when running multizone". | `ITER` in a zone file or in the main file (code). | Use `OUTER_ITER` in the main file, and `INNER_ITER` if needed. | +| SU2 stops: "Polynomial Conductivity model not implemented for CHT interface". | `POLYNOMIAL_CONDUCTIVITY` with a Robin coupling method (code). | Use `CONSTANT_CONDUCTIVITY` or `CONSTANT_PRANDTL` in the fluid, or a Neumann coupling method. | +| SU2 stops: "Number of CHT interfaces does not match number of contact resistances". | Wrong number of values in `CHT_INTERFACE_CONTACT_RESISTANCE` (code). | Give one value per interface pair, or a single value. | +| The solid stays at its initial temperature. | The interface markers are missing from `MARKER_CHT_INTERFACE` or `MARKER_ZONE_INTERFACE`, or the marker names do not match the mesh (advice). | Check the start-up output: it prints the interface type between each pair of zones. Check the marker names. | +| A wall with `MARKER_HEATTRANSFER` in a solid zone behaves as adiabatic. | The heat equation solver does not implement this condition (code). | Mesh the outer fluid, or use `MARKER_HEATFLUX` or `MARKER_ISOTHERMAL`. | +| The solid temperatures settle far too slowly. | A small CFL number in the solid, or `INNER_ITER= 1` with a very stiff solid (advice). | Raise `CFL_NUMBER` in the solid zone, or raise `INNER_ITER` in the solid zone file (to be reviewed). | +| The outer iterations oscillate. | Strong coupling between zones (advice). | Try `RELAXATION_FACTOR_CHT` below 1, for example 0.5 (to be reviewed). | +| The solid material behaves like steel or like air. | `MATERIAL_DENSITY`, `SPECIFIC_HEAT_CP` or `THERMAL_CONDUCTIVITY_CONSTANT` left at their defaults (code). | Set all three in each solid zone file. | +| The temperature looks blocky along a non-matching interface. | `NEAREST_NEIGHBOR` interpolation between very different meshes (advice). | Try `KIND_INTERPOLATION= ISOPARAMETRIC` (to be reviewed). | +| The result files of different zones overwrite each other. | `MULTIZONE_ADAPT_FILENAME= NO` (advice). | Keep the default `YES`, which adds the zone number to the restart and solution file names (code). | + +## Related tutorials and test cases + +Tutorials: + +- [Laminar Flat Plate with Heat Transfer](/tutorials/Inc_Laminar_Flat_Plate/): isothermal wall, energy equation with constant density. +- [Laminar Buoyancy-driven Cavity](/tutorials/Inc_Laminar_Cavity/): natural convection. +- [Steady CHT, heated cylinders](/tutorials/Static_CHT/): the start setup above. +- [Unsteady CHT, heated cylinders](/tutorials/Inc_Heated_Cylinders_Unsteady/). +- [Solid-to-Solid CHT with Contact Resistance](/tutorials/SS_CR_CHT/). +- [Streamwise Periodic Flow](/tutorials/Inc_Streamwise_Periodic/): includes a CHT pin array. + +Test cases: + +- [`coupled_cht/incomp_2d`](https://github.com/su2code/SU2/blob/develop/TestCases/coupled_cht/incomp_2d/cht_2d_3cylinders.cfg): steady incompressible CHT. +- [`coupled_cht/incomp_2d_unsteady`](https://github.com/su2code/SU2/blob/develop/TestCases/coupled_cht/incomp_2d_unsteady/cht_2d_3cylinders.cfg): unsteady incompressible CHT. +- [`coupled_cht/comp_2d`](https://github.com/su2code/SU2/blob/develop/TestCases/coupled_cht/comp_2d/cht_2d_3cylinders.cfg): compressible CHT. +- [`incomp_navierstokes/streamwise_periodic/chtPinArray_2d/configMaster.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_navierstokes/streamwise_periodic/chtPinArray_2d/configMaster.cfg) and [`chtPinArray_3d`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_navierstokes/streamwise_periodic/chtPinArray_3d/configMaster.cfg): CHT with streamwise periodic flow and heat flux in the pins. +- [`incomp_navierstokes/streamwise_periodic/chtPinArray_2d/BC_HeatTransfer.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_navierstokes/streamwise_periodic/chtPinArray_2d/BC_HeatTransfer.cfg): the fluid alone, with `MARKER_HEATTRANSFER` in place of the solid. +- [`solid_heat_conduction/periodic_pins/configSolid.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/solid_heat_conduction/periodic_pins/configSolid.cfg): a solid alone. +- [`disc_adj_heat/primal.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/disc_adj_heat/primal.cfg): weakly coupled heat equation. +- [`flamelet/03_laminar_premixed_ch4_flame_cht_cfd`](https://github.com/su2code/SU2/blob/develop/TestCases/flamelet/03_laminar_premixed_ch4_flame_cht_cfd/lam_prem_ch4_cht_cfd_master.cfg): CHT with a flame. + +User guide pages: [Basics of Multi-Zone Computations](../Multizone/), [Markers and BC](../Markers-and-BC/), [Theory: Heat Conduction](../Theory/#heat-conduction), [Solver Setup](../Solver-Setup/), [Custom Output](../Custom-Output/). + +Source review: 22 October 2026, against [SU2 `docs_site` at `41ea6a219a`](https://github.com/rois1995/SU2/tree/41ea6a219ac038574f3d4a5b130c0c1d8af66457). See the [review scope and outstanding validation](../Documentation-Status/#guide-and-model-review). Setup recommendations remain draft where indicated. diff --git a/_docs_v7/Setup-Guide-Incompressible.md b/_docs_v7/Setup-Guide-Incompressible.md new file mode 100644 index 00000000..3b7d9833 --- /dev/null +++ b/_docs_v7/Setup-Guide-Incompressible.md @@ -0,0 +1,300 @@ +--- +title: "Setup Guide: Incompressible Flows" +permalink: /docs_v7/Setup-Guide-Incompressible/ +--- + +{% include setup-guide-intro.md %} + +--- + +- [When to use this guide](#when-to-use-this-guide) +- [Start from](#start-from) +- [Settings that matter](#settings-that-matter) +- [Check convergence and results](#check-convergence-and-results) +- [Common problems](#common-problems) +- [Related tutorials and test cases](#related-tutorials-and-test-cases) + +--- + +## When to use this guide + +Use this guide for a flow where the density does not depend on the pressure. +This covers liquids and low-speed gas flows, also with heat transfer, where density may depend on temperature and composition while remaining independent of the hydrodynamic pressure. +As a rule of thumb, the Mach number is below about 0.3 (advice). + +This guide covers the solvers `INC_EULER`, `INC_NAVIER_STOKES` and `INC_RANS`. +For mixing gases and flames, continue with [Setup Guide: Species Transport and Combustion](../Setup-Guide-Species-Combustion/). +For coupled heat transfer between fluid and solid, continue with [Setup Guide: Heat Transfer and Conjugate Heat Transfer](../Setup-Guide-Heat-Transfer-CHT/). + +Every option is listed in the [option reference](../Option-Reference/). +Every output field is listed in the [output fields reference](../Output-Fields-Reference/). + +## Start from + +This config is a laminar flow through a pipe bend. It has a velocity inlet, a pressure outlet, adiabatic walls and a symmetry plane. +It is the test case [`incomp_navierstokes/bend/lam_bend.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_navierstokes/bend/lam_bend.cfg) with fewer options. +Changes to the test case: `ITER` is raised from 11 to 2000, and `MARKER_ANALYZE` and `HISTORY_OUTPUT` are added to check the mass flow. +The mesh `mesh_bend_coarse.cgns` is in the folder `incomp_navierstokes/bend` of the [TestCases repository](https://github.com/su2code/TestCases). + +``` +% ------------- Problem -------------% +SOLVER= INC_NAVIER_STOKES +KIND_TURB_MODEL= NONE +MATH_PROBLEM= DIRECT +RESTART_SOL= NO +% +% ------------- Fluid and initial state -------------% +INC_DENSITY_MODEL= CONSTANT +INC_ENERGY_EQUATION= NO +INC_DENSITY_INIT= 1.2886 +INC_VELOCITY_INIT= ( 0.1, 0.0, 0.0 ) +INC_TEMPERATURE_INIT= 288.15 +INC_NONDIM= INITIAL_VALUES +VISCOSITY_MODEL= CONSTANT_VISCOSITY +MU_CONSTANT= 1.716E-5 +% +% ------------- Boundary conditions -------------% +INC_INLET_TYPE= VELOCITY_INLET +MARKER_INLET= ( INLET, 288.15, 0.1, 1.0, 0.0, 0.0 ) +INC_OUTLET_TYPE= PRESSURE_OUTLET +MARKER_OUTLET= ( OUTLET, 0.0 ) +MARKER_HEATFLUX= ( WALL1, 0.0, WALL2, 0.0 ) +MARKER_SYM= ( SYMMETRY ) +MARKER_MONITORING= ( WALL1, WALL2 ) +MARKER_ANALYZE= ( INLET, OUTLET ) +% +% ------------- Numerics -------------% +NUM_METHOD_GRAD= GREEN_GAUSS +CONV_NUM_METHOD_FLOW= FDS +MUSCL_FLOW= YES +SLOPE_LIMITER_FLOW= NONE +TIME_DISCRE_FLOW= EULER_IMPLICIT +CFL_NUMBER= 1e2 +LINEAR_SOLVER= FGMRES +LINEAR_SOLVER_PREC= ILU +LINEAR_SOLVER_ERROR= 1E-15 +LINEAR_SOLVER_ITER= 5 +% +% ------------- Convergence and output -------------% +ITER= 2000 +CONV_FIELD= RMS_PRESSURE +CONV_RESIDUAL_MINVAL= -8 +CONV_STARTITER= 10 +MESH_FILENAME= mesh_bend_coarse.cgns +MESH_FORMAT= CGNS +SCREEN_OUTPUT= (INNER_ITER, RMS_PRESSURE, RMS_VELOCITY-X, SURFACE_MASSFLOW) +HISTORY_OUTPUT= (ITER, RMS_RES, FLOW_COEFF, FLOW_COEFF_SURF) +``` + +## Settings that matter + +### Solver + +Choose the solver with `SOLVER`: + +- `INC_EULER`: no viscosity. Use it for quick checks of pressure fields, for example on a hydrofoil. SU2 stops if you combine it with a density model other than `CONSTANT`, or with `INC_ENERGY_EQUATION= YES` (code). +- `INC_NAVIER_STOKES`: laminar flow. +- `INC_RANS`: turbulent flow. Choose the turbulence model with `KIND_TURB_MODEL` (`SA` or `SST`). + +For `INC_RANS` with SST, the free-stream turbulence comes from `FREESTREAM_TURBULENCEINTENSITY` (default 0.05, a fraction) and `FREESTREAM_TURB2LAMVISCRATIO` (default 10, the eddy-to-laminar viscosity ratio). With SA, `FREESTREAM_NU_FACTOR` (default 3.0) sets nu-tilde divided by the kinematic viscosity (code). +Inlets use these settings unless overridden with `MARKER_INLET_TURBULENT`: two values per marker for SST (intensity, viscosity ratio), or one for SA (nu-tilde divided by the local kinematic viscosity). The SA factor is not the eddy-to-laminar viscosity ratio. With `SA_OPTIONS= BCM`, SU2 also multiplies nu-tilde by 0.005 (code). See [Turbulence Models](../Turbulence-Models/#free-stream-and-inlet-values). + +### Density-based or pressure-based solver + +`KIND_INCOMP_SYSTEM` selects how SU2 couples pressure and velocity (code): + +- `DENSITY_BASED` (default): SU2 adds a pseudo-time derivative of the pressure to the continuity equation. This is called artificial compressibility, a form of preconditioning. SU2 solves pressure and velocity together, with enthalpy in the coupled system when the energy equation is enabled; temperature is recovered from the fluid model. All tutorials on this page use it. +- `PRESSURE_BASED`: a segregated method of the SIMPLE type, which solves the equations one after the other. Choose `SIMPLE` (default) or `SIMPLEC` with `KIND_PB_ITER`. It uses `CONV_NUM_METHOD_FLOW= UDS` (upwind) or `CDS` (centered). + +With `PRESSURE_BASED`, SU2 stops if you use multigrid (`MGLEVEL` above 0), an adjoint, `MARKER_PERIODIC`, streamwise periodic flow, or `TIME_MARCHING= TIME_STEPPING` (code). +If you need the pressure-based solver, start from the test case [`incomp_navierstokes/bend/pb_lam_bend.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_navierstokes/bend/pb_lam_bend.cfg). +The rest of this page is about the density-based solver. + +### Density model and energy equation + +`INC_DENSITY_MODEL` decides how the density can change. `INC_ENERGY_EQUATION` switches the temperature equation on or off. The table shows what the code does (code): + +| `INC_DENSITY_MODEL` | Density | Energy equation | `FLUID_MODEL` | +|---|---|---|---| +| `CONSTANT` (default) | constant | your choice | SU2 sets `CONSTANT_DENSITY` | +| `BOUSSINESQ` | constant, plus a buoyancy force from temperature | always on | SU2 sets `CONSTANT_DENSITY` | +| `VARIABLE` | from the ideal gas law, changes with temperature | always on without species | `INC_IDEAL_GAS`, `INC_IDEAL_GAS_POLY`, `FLUID_MIXTURE` or `FLUID_FLAMELET` | +| `FLAMELET` | read from a flamelet table | handled by the flamelet solver | `FLUID_FLAMELET` | + +How to choose: + +- **No heat transfer, or temperature as a passive quantity.** Use `CONSTANT`. With `INC_ENERGY_EQUATION= YES`, SU2 solves the energy equation for enthalpy and recovers temperature. Temperature is passive only when properties affecting momentum, notably viscosity, are independent of temperature and no thermal buoyancy is present. Constant density alone does not ensure one-way coupling: `POLYNOMIAL_VISCOSITY` can still make viscosity temperature-dependent (code). Constant-property one-way coupling is used in the [laminar flat plate tutorial](/tutorials/Inc_Laminar_Flat_Plate/) (tutorial). Set `SPECIFIC_HEAT_CP` (default 1004.703 J/(kg K)). +- **Small temperature differences with buoyancy.** Use `BOUSSINESQ`. The buoyancy force uses `THERMAL_EXPANSION_COEFF` (default 0.00347 1/K) and the difference to `INC_TEMPERATURE_INIT`. Gravity is fixed at 9.81 m/s², along the negative y axis in 2D and the negative z axis in 3D. You cannot add `BODY_FORCE= YES`: SU2 stops (code). +- **Large temperature differences in a gas.** Use `VARIABLE` with `FLUID_MODEL= INC_IDEAL_GAS` (constant specific heat) or `INC_IDEAL_GAS_POLY` (specific heat as a polynomial of temperature, set with `CP_POLYCOEFFS`, five coefficients). Set `MOLECULAR_WEIGHT` in g/mol (default 28.96) and `SPECIFIC_HEAT_CP`. +- **Mixtures of gases.** Use `VARIABLE` with `FLUID_MODEL= FLUID_MIXTURE`. See the [species guide](../Setup-Guide-Species-Combustion/). + +When you set `INC_DENSITY_MODEL` to `CONSTANT` or `BOUSSINESQ`, SU2 replaces your `FLUID_MODEL` with `CONSTANT_DENSITY`. Other fluid models only take effect with `VARIABLE` or `FLAMELET` (code). + +### Operating pressure of an ideal gas + +With `VARIABLE` density, SU2 computes the density from an operating pressure, the molecular weight and the temperature. +The operating (thermodynamic) pressure is constant in space. The flow pressure in SU2 is a gauge pressure on top of it ([Theory](../Theory/#incompressible-navier-stokes)). + +`INIT_OPTION_INC` decides which of the two you prescribe (code): + +- `DENSITY_INIT`: SU2 scales `THERMODYNAMIC_PRESSURE` so that the density at `INC_TEMPERATURE_INIT` equals `INC_DENSITY_INIT`. This is the default for `INC_IDEAL_GAS` and `INC_IDEAL_GAS_POLY`. +- `OPERATING_PRESSURE`: SU2 uses `THERMODYNAMIC_PRESSURE` (default 101325 Pa) and computes the density. This is the default for `FLUID_MIXTURE` and `FLUID_FLAMELET`. + +The buoyancy cavity test case uses `DENSITY_INIT` with a very small `INC_DENSITY_INIT` to reach a chosen Rayleigh number (test case). + +### Gravity for variable density + +For natural convection with `VARIABLE` density, set `BODY_FORCE= YES` and `BODY_FORCE_VECTOR= ( 0.0, -9.81, 0.0 )` (an acceleration in m/s²), as in the [buoyancy cavity tutorial](/tutorials/Inc_Laminar_Cavity/). +With variable density, the force is (ρ − ρ₀)·g, where ρ₀ is the initial density. So the computed pressure does not contain the hydrostatic pressure of the initial density (code). + +### Viscosity and conductivity + +- `VISCOSITY_MODEL`: the default is `SUTHERLAND`. SU2 stops if you use it with constant density, so set `VISCOSITY_MODEL= CONSTANT_VISCOSITY` and `MU_CONSTANT` (default 1.716e-5 kg/(m s)) (code). Sutherland's law is allowed with `INC_IDEAL_GAS`, `INC_IDEAL_GAS_POLY` and `FLUID_MIXTURE`. `POLYNOMIAL_VISCOSITY` uses `MU_POLYCOEFFS`. +- `CONDUCTIVITY_MODEL`: the default `CONSTANT_PRANDTL` computes the conductivity from viscosity, specific heat and `PRANDTL_LAM` (default 0.72). `CONSTANT_CONDUCTIVITY` uses `THERMAL_CONDUCTIVITY_CONSTANT` (default 0.0257 W/(m K)). `POLYNOMIAL_CONDUCTIVITY` uses `KT_POLYCOEFFS`. +- `TURBULENT_CONDUCTIVITY_MODEL`: `CONSTANT_PRANDTL_TURB` (default) uses `PRANDTL_TURB` (default 0.9). `NONE` switches the turbulent heat transport off. + +The defaults are values for air. For water or another liquid, set all of them (advice). + +### Initial state and non-dimensionalization + +`INC_DENSITY_INIT`, `INC_VELOCITY_INIT` and `INC_TEMPERATURE_INIT` set the initial field. The initial pressure is always zero. +They also set the free-stream state used at `MARKER_FAR` markers, the Reynolds number printed on screen, and the free-stream turbulence level (code). + +`INC_NONDIM` chooses the reference values that SU2 divides by internally (code): + +- `INITIAL_VALUES` (default): the reference density, velocity and temperature are the initial values. The reference velocity is the magnitude of `INC_VELOCITY_INIT`. +- `REFERENCE_VALUES`: you set `INC_DENSITY_REF`, `INC_VELOCITY_REF` and `INC_TEMPERATURE_REF` (all default to 1.0). +- `DIMENSIONAL`: all reference values are 1, so SU2 works in SI units. + +The reference pressure is the reference density times the reference velocity squared. +The inputs in the config file are always in SI units ([NACA 0012 tutorial](/tutorials/Inc_Turbulent_NACA0012/)). +The flow energy solution field is `ENTHALPY` in `SOLUTION`; `TEMPERATURE` is a recovered field in `PRIMITIVE`. The separate weakly coupled heat solver instead uses `TEMPERATURE` as its solution variable (`CFlowIncOutput`, code). Output and restart fields depend on the requested groups; do not read an enthalpy column as temperature. Pressure, velocity and recovered temperature are divided by their respective reference values unless you use `DIMENSIONAL` (code). +SU2 prints the reference values and the non-dimensional values at the start of the run. Use them to convert results back to SI units. + +Advice: + +- Use `DIMENSIONAL` if you want SI values in the output files. Almost all CHT, species, flamelet and streamwise periodic test cases use it (test case). The choice should not change the converged solution (advice, to be reviewed). +- Do not use `INITIAL_VALUES` with a zero `INC_VELOCITY_INIT`, for example in a closed cavity: the reference velocity becomes zero. Set a small non-zero velocity (the buoyancy cavity test uses 1 m/s), or use `DIMENSIONAL` (code). +- Streamwise periodic flow needs `INC_NONDIM= DIMENSIONAL` (code). + +### Inlets + +`MARKER_INLET` sets the inlet markers. `INC_INLET_TYPE` gives one type per inlet marker, in the same order (code): + +- `VELOCITY_INLET`: `MARKER_INLET= ( marker, temperature [K], velocity magnitude [m/s], nx, ny, nz )`. SU2 normalizes the nonzero direction vector, so it does not need unit length (code). The temperature is needed even without the energy equation, but then SU2 does not use it ([Markers and BC](../Markers-and-BC/)). +- `PRESSURE_INLET`: `MARKER_INLET= ( marker, temperature [K], total gauge pressure [Pa], nx, ny, nz )`. SU2 adjusts the inlet velocity to reach the total pressure. `INC_INLET_DAMPING` (default 0.1) damps these updates. + +The incompressible solver has no mass flow inlet (code). +To prescribe a mass flow, use a velocity inlet (velocity = mass flow / (density × area)) or a mass flow outlet. + +For a measured or computed inlet profile, set `SPECIFIED_INLET_PROFILE= YES` and `INLET_FILENAME`, as in the [laminar step tutorial](/tutorials/Inc_Laminar_Step/). + +### Outlets + +`MARKER_OUTLET` sets the outlet markers. `INC_OUTLET_TYPE` gives one type per outlet marker (code): + +- `PRESSURE_OUTLET`: `MARKER_OUTLET= ( marker, gauge pressure [Pa] )`. This is the usual choice. Zero is a good value, because the pressure level is arbitrary in incompressible flow (advice). +- `MASS_FLOW_OUTLET`: `MARKER_OUTLET= ( marker, mass flow [kg/s] )`. In a planar 2D case, this is the rate for a unit out-of-plane depth. SU2 adjusts the outlet pressure to reach the target. `INC_OUTLET_DAMPING` (default 0.1) damps these updates. + +Put the outlet far enough downstream that no recirculation crosses it (advice, to be reviewed). + +### Walls and far field + +- `MARKER_HEATFLUX= ( marker, heat flux [W/m²] )`: no-slip wall. Zero means adiabatic. +- `MARKER_ISOTHERMAL= ( marker, temperature [K] )`: no-slip wall at a fixed temperature. +- `MARKER_HEATTRANSFER= ( marker, h [W/(m² K)], T_inf [K] )`: wall with a heat transfer coefficient. +- `MARKER_EULER`: slip wall, for `INC_EULER`. +- `MARKER_SYM`: symmetry plane. +- `MARKER_FAR`: far field. It uses `INC_VELOCITY_INIT`, zero gauge pressure and `INC_TEMPERATURE_INIT` (code). + +The [heat transfer guide](../Setup-Guide-Heat-Transfer-CHT/) explains the thermal wall conditions. + +### Convective scheme and gradients + +For the density-based solver, `CONV_NUM_METHOD_FLOW` accepts these schemes (code): + +- `FDS` (flux difference splitting, an upwind scheme). Almost all incompressible test cases use it. It has no tuning parameters ([Convective Schemes](../Convective-Schemes/#incompressible-flow)). +- `JST` and `LAX-FRIEDRICH` (centered schemes with artificial dissipation). + +`MUSCL_FLOW= YES` (default) enables second-order reconstruction for the upwind `FDS` scheme; it does not change the centered schemes. The default limiter is `VENKATAKRISHNAN`, but most incompressible test cases use `SLOPE_LIMITER_FLOW= NONE` (code, test case). +Add a limiter only if the solution shows wiggles, or if the run diverges near sharp gradients (advice, to be reviewed). + +For `INC_RANS`, the test cases use `CONV_NUM_METHOD_TURB= SCALAR_UPWIND`. `BOUNDED_SCALAR` is also available for incompressible flow. It corrects for a non-zero velocity divergence during convergence ([Convective Schemes](../Convective-Schemes/#turbulence-and-scalarspecies-equations)). + +### Artificial compressibility factor + +The density-based solver scales its pseudo-time pressure term with β² = max(4.1, `BETA_FACTOR`) × (maximum velocity)². So `BETA_FACTOR` (default 4.1) changes the result only when you set it above 4.1 (code). +A larger value can make the pressure-velocity coupling more robust, but slower (advice, to be reviewed). Most users keep the default. + +### Streamwise periodic flow + +Use streamwise periodic flow for one module of a repeating geometry, such as a channel with a row of pins. Read [Streamwise Periodicity](../Streamwise-Periodicity/) and the [tutorial](/tutorials/Inc_Streamwise_Periodic/). + +- Join the periodic faces with `MARKER_PERIODIC= ( periodic, donor, rotation center (3), rotation angles (3), translation (3) )`. +- Use `KIND_STREAMWISE_PERIODIC= PRESSURE_DROP` with `STREAMWISE_PERIODIC_PRESSURE_DROP` [Pa] (default 1.0), or `MASSFLOW` with `STREAMWISE_PERIODIC_MASSFLOW` [kg/s]. With `MASSFLOW`, SU2 adapts the pressure drop and damps the update with `INC_OUTLET_DAMPING` (code). +- With the energy equation, `STREAMWISE_PERIODIC_TEMPERATURE= YES` makes the temperature periodic too. It allows only `MARKER_HEATFLUX` and `MARKER_SYM`, no `MARKER_ISOTHERMAL` (code). With `NO`, SU2 removes heat at the outlet; set the amount with `STREAMWISE_PERIODIC_OUTLET_HEAT` [W]. +- SU2 stops unless `INC_NONDIM= DIMENSIONAL`. `INC_EULER` and `AXISYMMETRIC= YES` are not supported (code). + +### Iterations and CFL number + +- Steady runs: set `ITER` (default 1000) or `INNER_ITER`. `CFL_NUMBER` sets the pseudo-time step (default 1.25) (code). The incompressible test cases use CFL numbers from 10 to 1000, and up to 50000 in a streamwise periodic case, all with `TIME_DISCRE_FLOW= EULER_IMPLICIT` (test case). +- `CFL_ADAPT= YES` with `CFL_ADAPT_PARAM` lets SU2 raise the CFL number while the residuals fall, as in the NACA 0012 RANS test case (test case). +- Unsteady runs: set `TIME_DOMAIN= YES`, `TIME_MARCHING= DUAL_TIME_STEPPING-2ND_ORDER`, `TIME_STEP`, `TIME_ITER` and `INNER_ITER`. See the [von Karman tutorial](/tutorials/Inc_Von_Karman/) and [Solver Setup](../Solver-Setup/). +- `MGLEVEL` (default 0) adds multigrid levels. Some inviscid and laminar test cases use 3 levels (test case). + +## Check convergence and results + +- **Residuals.** The default convergence field is `RMS_PRESSURE` for the density-based solver and `RMS_VELOCITY-X` for the pressure-based solver (code). Set `CONV_FIELD` and `CONV_RESIDUAL_MINVAL` (log10 of the residual, default −14). A drop of 4 to 6 orders is a common target for steady engineering cases (advice, to be reviewed). +- **Field names.** SU2 ignores unknown names in `CONV_FIELD` and prints `Ignoring Convergence Field(s)` at the start. If all names are unknown, the convergence check is off and the run goes on to `ITER` (code). +- **Integrated values.** Monitor a value you care about, for example `DRAG` on `MARKER_MONITORING` markers, or `SURFACE_PRESSURE_DROP` on `MARKER_ANALYZE` markers. A stop based on a coefficient uses `CONV_CAUCHY_ELEMS` and `CONV_CAUCHY_EPS` ([Solver Setup](../Solver-Setup/#setting-convergence-criteria)). +- **Mass balance.** Add the inlets and outlets to `MARKER_ANALYZE`, and `FLOW_COEFF_SURF` to `HISTORY_OUTPUT`. The history file then has the mass flow of each marker. Inlet and outlet mass flows should agree to a small fraction of a percent at convergence (advice, to be reviewed). +- **Reference values.** Read the table of reference and non-dimensional values printed at the start of the run. Check that density, viscosity and Reynolds number are what you intended. +- **Energy equation.** With the energy equation, `RMS_ENTHALPY` is the residual of the energy equation (code). `TOTAL_HEATFLUX` gives the heat flux through the `MARKER_MONITORING` markers. + +## Common problems + +| Symptom | Likely cause | What to try | +|---|---|---| +| SU2 stops: "Sutherland's law only valid for ideal gases in incompressible flows". | The default `VISCOSITY_MODEL` is `SUTHERLAND` (code). | Set `VISCOSITY_MODEL= CONSTANT_VISCOSITY` and `MU_CONSTANT`. | +| SU2 stops: "Inlet types for incompressible problem improperly specified". | `INC_INLET_TYPE` has fewer entries than `MARKER_INLET` has markers (code). | Give one type per inlet marker, for example `INC_INLET_TYPE= VELOCITY_INLET, PRESSURE_INLET`. The same applies to `INC_OUTLET_TYPE`. | +| SU2 stops: "Variable density incompressible solver limited to ideal gases". | `INC_DENSITY_MODEL= VARIABLE` with the default `FLUID_MODEL= STANDARD_AIR` (code). | Set `FLUID_MODEL= INC_IDEAL_GAS` or `INC_IDEAL_GAS_POLY`. | +| SU2 stops: "Inviscid incompressible problems must be constant density". | `INC_EULER` with variable density or with the energy equation (code). | Use `INC_NAVIER_STOKES`, or `INC_DENSITY_MODEL= CONSTANT` and `INC_ENERGY_EQUATION= NO`. | +| The density does not follow `THERMODYNAMIC_PRESSURE`. | With `INC_IDEAL_GAS`, the default `INIT_OPTION_INC= DENSITY_INIT` rescales the operating pressure to match `INC_DENSITY_INIT` (code). | Set `INIT_OPTION_INC= OPERATING_PRESSURE`, or choose an `INC_DENSITY_INIT` that matches your pressure. | +| `FLUID_MODEL` seems to have no effect. | `INC_DENSITY_MODEL` is `CONSTANT` or `BOUSSINESQ`, so SU2 uses `CONSTANT_DENSITY` (code). | Use `INC_DENSITY_MODEL= VARIABLE`. | +| Non-physical values or a division by zero at the start of a closed-cavity case. | `INC_VELOCITY_INIT` is zero with `INC_NONDIM= INITIAL_VALUES` (code). | Set a small non-zero initial velocity, or use `INC_NONDIM= DIMENSIONAL`. | +| The temperature hits a limit; SU2 reports non-physical points. | The temperature left `TEMPERATURE_LIMITS` (default 0 K to 5000 K), so SU2 rejects the update in those points (code). | Lower the CFL number and check the thermal boundary values. Widen `TEMPERATURE_LIMITS` only if the range is physical. | +| The residuals stall or oscillate. | The CFL number is too high, or the flow is really unsteady (advice). | Lower `CFL_NUMBER` or use `CFL_ADAPT`. If the flow sheds vortices, run it unsteady (to be reviewed). | +| A pressure inlet case converges slowly. | `INC_INLET_DAMPING` slows down the update of the inlet velocity (code). | Try a larger `INC_INLET_DAMPING` (to be reviewed). | +| A streamwise periodic case stops at the start. | `INC_NONDIM` is not `DIMENSIONAL`, or an isothermal wall is used with `STREAMWISE_PERIODIC_TEMPERATURE= YES` (code). | Set `INC_NONDIM= DIMENSIONAL`. Use `MARKER_HEATFLUX`, or set `STREAMWISE_PERIODIC_TEMPERATURE= NO`. | +| The flow from a pressure inlet or a far field goes the wrong way. | The direction vector or `INC_VELOCITY_INIT` points the wrong way (advice). | Check the signs of the direction components against the mesh axes. | + +## Related tutorials and test cases + +Tutorials: + +- [Inviscid Hydrofoil](/tutorials/Inc_Inviscid_Hydrofoil/): `INC_EULER`. +- [Laminar Flat Plate with Heat Transfer](/tutorials/Inc_Laminar_Flat_Plate/): constant density with the energy equation. +- [Laminar Buoyancy-driven Cavity](/tutorials/Inc_Laminar_Cavity/): `VARIABLE` density, `INC_IDEAL_GAS`, gravity. +- [Laminar Backward-facing Step](/tutorials/Inc_Laminar_Step/): inlet profile from a file. +- [Turbulent Flat Plate](/tutorials/Inc_Turbulent_Flat_Plate/) and [Turbulent NACA 0012](/tutorials/Inc_Turbulent_NACA0012/): `INC_RANS` and non-dimensionalization. +- [Turbulent Bend with wall functions](/tutorials/Inc_Turbulent_Bend/). +- [Unsteady von Karman vortex shedding](/tutorials/Inc_Von_Karman/): unsteady incompressible flow. +- [Streamwise Periodic Flow](/tutorials/Inc_Streamwise_Periodic/). +- [Wind velocity and pollutant dispersion in a city](/tutorials/Inc_Urban_City/). + +Test cases (density-based unless noted): + +- [`incomp_euler/naca0012/incomp_NACA0012.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_euler/naca0012/incomp_NACA0012.cfg): inviscid airfoil. +- [`incomp_euler/nozzle/inv_nozzle.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_euler/nozzle/inv_nozzle.cfg): `PRESSURE_INLET` with `MASS_FLOW_OUTLET`. +- [`incomp_navierstokes/bend/lam_bend.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_navierstokes/bend/lam_bend.cfg): the start config above. +- [`incomp_navierstokes/cylinder/incomp_cylinder.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_navierstokes/cylinder/incomp_cylinder.cfg): laminar external flow with `MARKER_FAR`. +- [`incomp_navierstokes/cylinder/poly_cylinder.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_navierstokes/cylinder/poly_cylinder.cfg): `INC_IDEAL_GAS_POLY` with polynomial viscosity and conductivity. +- [`incomp_navierstokes/buoyancy_cavity/lam_buoyancy_cavity.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_navierstokes/buoyancy_cavity/lam_buoyancy_cavity.cfg): natural convection. +- [`incomp_navierstokes/streamwise_periodic/pipeSlice_3d/sp_pipeSlice_3d_dp_hf_tp.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_navierstokes/streamwise_periodic/pipeSlice_3d/sp_pipeSlice_3d_dp_hf_tp.cfg): streamwise periodic pipe. +- [`incomp_rans/naca0012/naca0012.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_rans/naca0012/naca0012.cfg): `INC_RANS` with `SA` and `CFL_ADAPT`. +- [`incomp_rans/naca0012/naca0012_SST_SUST.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_rans/naca0012/naca0012_SST_SUST.cfg): `INC_RANS` with `SST`. +- [`incomp_navierstokes/bend/pb_lam_bend.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_navierstokes/bend/pb_lam_bend.cfg): pressure-based solver. + +User guide pages: [Physical Definition](../Physical-Definition/#flow-condition-incompressible), [Markers and BC](../Markers-and-BC/), [Theory](../Theory/#incompressible-navier-stokes), [Convective Schemes](../Convective-Schemes/), [Solver Setup](../Solver-Setup/), [Custom Output](../Custom-Output/). + +Source review: 22 October 2026, against [SU2 `docs_site` at `41ea6a219a`](https://github.com/rois1995/SU2/tree/41ea6a219ac038574f3d4a5b130c0c1d8af66457). See the [review scope and outstanding validation](../Documentation-Status/#guide-and-model-review). Setup recommendations remain draft where indicated. diff --git a/_docs_v7/Setup-Guide-NICFD.md b/_docs_v7/Setup-Guide-NICFD.md new file mode 100644 index 00000000..f4b17724 --- /dev/null +++ b/_docs_v7/Setup-Guide-NICFD.md @@ -0,0 +1,280 @@ +--- +title: "Setup Guide: Non-Ideal Compressible Flows" +permalink: /docs_v7/Setup-Guide-NICFD/ +--- + +{% include setup-guide-intro.md %} + +--- + +- [When to use this guide](#when-to-use-this-guide) +- [Start from](#start-from) +- [Settings that matter](#settings-that-matter) +- [Check convergence and results](#check-convergence-and-results) +- [Common problems](#common-problems) +- [Related tutorials and test cases](#related-tutorials-and-test-cases) + +--- + +## When to use this guide + +Use this guide when the ideal gas law does not describe your fluid well. This happens for dense vapours and for gases near their critical point: for example organic fluids in ORC turbines, supercritical CO2 in compressors, or refrigerants in nozzles. This field is called NICFD (non-ideal compressible fluid dynamics). + +The guide covers the compressible solvers (`SOLVER= EULER`, `NAVIER_STOKES` or `RANS`) with a non-ideal fluid model. These solvers do not model phase change: the fluid must stay a single-phase gas or a supercritical fluid. + +Terms used below: + +- **Equation of state (EOS)**: the relation between pressure, density, temperature and energy of the fluid. +- **Critical point**: the endpoint of the liquid-vapour coexistence curve, where the two phases become identical. A supercritical state has both temperature and pressure above their critical values. Properties can vary rapidly nearby. +- **Acentric factor**: a dimensionless parameter defined from the reduced saturation pressure at a reduced temperature of 0.7. Peng-Robinson uses it to represent departures from simple-fluid behaviour. +- **Two-phase region**: states where liquid and vapour coexist in equilibrium. A cubic EOS may return a metastable or unstable single-phase continuation there. Positive pressure and sound-speed squared do not establish phase stability; check the saturation boundary separately. + +In this guide, (advice) also covers general thermodynamics practice. + +## Start from + +The block below is built from the regression test [nicf/coolprop/fluidModel.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/nicf/coolprop/fluidModel.cfg). That test runs the supersonic nozzle of the [NICFD nozzle tutorial](/tutorials/NICFD_nozzle/) with CoolProp. + +- We replaced the CoolProp fluid with the Peng-Robinson fluid block of the tutorial (siloxane MDM), so that the fluid model needs no CoolProp build. This modified combination has not been run as a new validation case. +- We set `RESTART_SOL= NO`, and removed the comments and the file names. +- We replaced `LIFT` and `DRAG` in the screen output with `NONPHYSICAL_POINTS`. +- The mesh `coolprop_nozzle.su2` is in the [TestCases repository](https://github.com/su2code/TestCases). + +``` +SOLVER= RANS +KIND_TURB_MODEL= SST +MATH_PROBLEM= DIRECT +RESTART_SOL= NO +% +MACH_NUMBER= 1E-9 +INIT_OPTION= TD_CONDITIONS +FREESTREAM_OPTION= TEMPERATURE_FS +FREESTREAM_PRESSURE= 904388 +FREESTREAM_TEMPERATURE= 542.13 +REF_DIMENSIONALIZATION= DIMENSIONAL +% +FLUID_MODEL= PR_GAS +GAMMA_VALUE= 1.01767 +GAS_CONSTANT= 35.17 +CRITICAL_TEMPERATURE= 565.3609 +CRITICAL_PRESSURE= 1437500 +ACENTRIC_FACTOR= 0.524 +% +VISCOSITY_MODEL= CONSTANT_VISCOSITY +MU_CONSTANT= 1.21409E-05 +CONDUCTIVITY_MODEL= CONSTANT_CONDUCTIVITY +THERMAL_CONDUCTIVITY_CONSTANT= 0.030542828 +% +MARKER_HEATFLUX= ( WALL, 0.0 ) +MARKER_SYM= ( SYMMETRY ) +MARKER_RIEMANN= ( INFLOW, TOTAL_CONDITIONS_PT, 904388, 542.13, 1.0, 0.0, 0.0, OUTFLOW, STATIC_PRESSURE, 200000.0, 0.0, 0.0, 0.0, 0.0 ) +% +NUM_METHOD_GRAD= GREEN_GAUSS +CFL_NUMBER= 10.0 +CFL_ADAPT= YES +CFL_ADAPT_PARAM= ( 0.1, 2.0, 10.0, 1000.0 ) +MAX_DELTA_TIME= 1E6 +LINEAR_SOLVER= FGMRES +LINEAR_SOLVER_PREC= ILU +LINEAR_SOLVER_ILU_FILL_IN= 0 +LINEAR_SOLVER_ERROR= 1E-6 +LINEAR_SOLVER_ITER= 10 +CONV_NUM_METHOD_FLOW= ROE +ENTROPY_FIX_COEFF= 0.1 +MUSCL_FLOW= YES +SLOPE_LIMITER_FLOW= NONE +CONV_NUM_METHOD_TURB= SCALAR_UPWIND +MUSCL_TURB= NO +% +% The test stops after 101 iterations. Raise ITER for a converged result. +ITER= 101 +CONV_RESIDUAL_MINVAL= -24 +CONV_STARTITER= 10 +SCREEN_OUTPUT= (INNER_ITER, RMS_DENSITY, RMS_TKE, RMS_DISSIPATION, NONPHYSICAL_POINTS) +MESH_FILENAME= coolprop_nozzle.su2 +MESH_FORMAT= SU2 +OUTPUT_WRT_FREQ= 50 +``` + +To use CoolProp instead, replace the fluid block with the one of the test case: `FLUID_MODEL= COOLPROP` and `FLUID_NAME= nitrogen` (test case). The inlet and outlet values of the test then describe nitrogen, not MDM. + +## Settings that matter + +### Build options + +These rules come from the code (code): + +- CoolProp needs `-Denable-coolprop=true` at configure time. +- The data-driven model with neural networks needs `-Denable-mlpcpp=true`. The data-driven tutorial uses it too (tutorial). +- CoolProp cannot be used with the AD builds, so there is no discrete adjoint with CoolProp. +- `VW_GAS` and `PR_GAS` need no extra build option. + +See [Build SU2 on Linux/MacOS](../Build-SU2-Linux-MacOS/). + +### Fluid model + +Choose the equation of state with `FLUID_MODEL` (code): + +| Value | Model | Parameters | +|---|---|---| +| `STANDARD_AIR`, `IDEAL_GAS` | ideal gas | `GAMMA_VALUE`, `GAS_CONSTANT` | +| `VW_GAS` | van der Waals | `GAMMA_VALUE`, `GAS_CONSTANT`, `CRITICAL_TEMPERATURE`, `CRITICAL_PRESSURE` | +| `PR_GAS` | Peng-Robinson | as `VW_GAS`, plus `ACENTRIC_FACTOR` | +| `COOLPROP` | multiparameter EOS from the CoolProp library | `FLUID_NAME` | +| `DATADRIVEN_FLUID` | look-up table or neural network | `INTERPOLATION_METHOD`, `FILENAMES_INTERPOLATOR`, `USE_PINN`, `DATADRIVEN_NEWTON_RELAXATION` | + +How to choose (advice, to be reviewed): + +- `VW_GAS` is the simplest non-ideal model. It is mainly useful for qualitative studies and code tests. +- `PR_GAS` is a common choice for organic fluids. It gives fair accuracy away from the critical point. The NICFD nozzle tutorial uses it (tutorial). +- `COOLPROP` provides fluid-specific multiparameter equations of state. Check the underlying EOS reference, validity range and uncertainty for the fluid and states of interest; neither accuracy nor evaluation cost has a universal ranking. +- `DATADRIVEN_FLUID` approximates a reference EOS with a table or network. Establish property and derivative errors over the intended state range and measure cost; closeness to the reference and a speedup are not guaranteed. + +For background on the EOS families and their limits, see the primary [CoolProp fluid-property documentation](https://coolprop.org/fluid_properties/PurePseudoPure.html) and [cubic-EOS documentation](https://coolprop.org/coolprop/Cubics.html). These describe the library, not a guarantee about SU2 coupling. + +Parameters and their defaults (code): + +- `GAMMA_VALUE` (default 1.4) and `GAS_CONSTANT` (default 287.058 J/(kg K)). For `VW_GAS` and `PR_GAS`, take the ratio of specific heats in the dilute-gas limit, that is, at low pressure (tutorial). These models use a constant ideal-gas heat capacity, derived from `GAMMA_VALUE`. `GAS_CONSTANT` is the universal gas constant divided by the molar mass of the fluid (advice). +- `CRITICAL_TEMPERATURE` (default 131.00 K), `CRITICAL_PRESSURE` (default 3588550.0 Pa), `ACENTRIC_FACTOR` (default 0.035). The defaults do not describe your fluid, so always set these values. +- `CRITICAL_DENSITY` exists (default 263.0) and the test cases set it, but the finite-volume solvers do not use it. +- `FLUID_NAME` (default `nitrogen`) is the CoolProp name of the fluid. With `COOLPROP`, SU2 takes the critical point and the acentric factor from CoolProp, so the `CRITICAL_*` options are not needed. + +Data-driven options (code): + +- `INTERPOLATION_METHOD`: `LUT` (look-up table, default) or `MLP` (multi-layer perceptron, a neural network). The comment in the code says that the default is `MLP`, but the code sets `LUT`. +- `FILENAMES_INTERPOLATOR`: the `.mlp` files of the networks, or one `.drg` table file for `LUT`. The file types are from `config_template.cfg`. +- `USE_PINN= YES` uses a physics-informed network, default `NO`. The network gives the entropy as a function of density and internal energy. SU2 computes the other properties from its derivatives, which keeps them consistent (tutorial). +- `DATADRIVEN_NEWTON_RELAXATION` (default 1.0) relaxes a Newton solver. The model takes density and internal energy as inputs. When SU2 knows another pair of properties, for example pressure and temperature, this Newton solver finds the matching density and energy. +- The [data-driven tutorial](/tutorials/NICFD_nozzle_datadriven/) shows how to make the network with SU2 DataMiner. + +### Reference values + +- `REF_DIMENSIONALIZATION` (default `DIMENSIONAL`) sets how SU2 scales the variables. See [Physical Definition](../Physical-Definition/). +- `COOLPROP` must run with `DIMENSIONAL`. Otherwise SU2 stops with "CoolProp can not be used with non-dimensionalization" (code). +- `DATADRIVEN_FLUID`: the test case and the tutorial use `DIMENSIONAL` (test case, tutorial). The code builds this model without reference scaling, so keep `DIMENSIONAL` (code, to be reviewed). +- `PR_GAS` and `VW_GAS` work with both. The transonic stator test uses `DIMENSIONAL`, and the LS89 cascade test uses `FREESTREAM_PRESS_EQ_ONE` (test case). + +### Transport properties + +Viscosity, `VISCOSITY_MODEL` (code): + +- `CONSTANT_VISCOSITY` with `MU_CONSTANT` (default 1.716E-5 Pa s, the value of air). +- `SUTHERLAND` with `MU_REF`, `MU_T_REF`, `SUTHERLAND_CONSTANT` (default model). Sutherland's law is a fit for dilute gases (advice). +- `COOLPROP`: viscosity from CoolProp, for the fluids listed in the code. `FLUID_NAME` must match the list exactly, for example `Nitrogen`, `CarbonDioxide`, `R134a`. +- `POLYNOMIAL_VISCOSITY` works only with the incompressible solvers. + +Thermal conductivity, `CONDUCTIVITY_MODEL` (code): + +- `CONSTANT_CONDUCTIVITY` with `THERMAL_CONDUCTIVITY_CONSTANT` (default 0.0257 W/(m K), the value of air). +- `CONSTANT_PRANDTL` with `PRANDTL_LAM` (default 0.72) (default model). +- `COOLPROP`: conductivity from CoolProp, with the same exact-name rule as the viscosity. +- `POLYNOMIAL_CONDUCTIVITY` works only with the incompressible solvers. + +`PRANDTL_TURB` (default 0.9) sets the turbulent heat conduction in RANS (code). + +What the examples use: + +- `PR_GAS` tests and tutorial: `CONSTANT_VISCOSITY` and `CONSTANT_CONDUCTIVITY` (test case, tutorial). The tutorial says that these are the only models available with `PR_GAS`. The current code accepts the other models too (code). Whether they suit a dense gas is to be reviewed. +- Data-driven test: `CONSTANT_VISCOSITY` and `CONSTANT_PRANDTL` (test case). +- CoolProp test `transportModel.cfg`: `COOLPROP` for both (test case). + +With `CONDUCTIVITY_MODEL= COOLPROP`, also set `TURBULENT_CONDUCTIVITY_MODEL= NONE`. With the default `CONSTANT_PRANDTL_TURB`, the code replaces the CoolProp conductivity with `THERMAL_CONDUCTIVITY_CONSTANT` (code, to be reviewed). `NONE` does not remove the turbulent heat flux: the compressible solvers add it from `PRANDTL_TURB` in any case (code). + +### Boundary conditions + +- With a non-ideal fluid, `MARKER_INLET`, `MARKER_OUTLET` and `MARKER_FAR` are not allowed. SU2 stops with "Riemann Boundary conditions or Giles must be used ..." (code). +- Use `MARKER_RIEMANN` for inlets and outlets. It is a characteristic condition, built on the waves that enter and leave the domain, and it uses the fluid model (tutorial). Format: (marker, kind, value 1, value 2, direction 1, direction 2, direction 3) (code). + +Riemann kinds accepted by the general Riemann condition (code): + +| Kind | Use | Values | +|---|---|---| +| `TOTAL_CONDITIONS_PT` | subsonic inlet | total pressure, total temperature, flow direction | +| `DENSITY_VELOCITY` | inlet | density, velocity magnitude, flow direction | +| `STATIC_PRESSURE` | subsonic outlet | static pressure, then four zeros | +| `STATIC_SUPERSONIC_INFLOW_PT` | supersonic inlet | static pressure, static temperature, Mach number components | +| `STATIC_SUPERSONIC_INFLOW_PD` | supersonic inlet | static pressure, static density, Mach number components | + +Other kinds in the Riemann list, such as `SUPERSONIC_OUTFLOW`, stop the run with "Invalid Riemann input!" unless turbomachinery markers are set (code). The supersonic edge test uses `STATIC_PRESSURE` with a low value at its supersonic outlet (test case). + +- `MARKER_GILES` is a non-reflecting condition. It needs `MARKER_TURBOMACHINERY` (code). The [data-driven tutorial](/tutorials/NICFD_nozzle_datadriven/) uses it on a nozzle, with an outlet pressure ramp (tutorial). See [Setup Guide: Turbomachinery](../Setup-Guide-Turbomachinery/) for its kinds and options. +- Walls: `MARKER_HEATFLUX`, `MARKER_EULER` and `MARKER_SYM` work as usual (test case). + +### Initialization + +- Use `INIT_OPTION= TD_CONDITIONS` (test case, tutorial). The default `REYNOLDS` recomputes the pressure from the Reynolds number (code), which does not suit internal flows (advice). +- The nozzle tests start from the inlet total state at rest: `FREESTREAM_PRESSURE` and `FREESTREAM_TEMPERATURE` equal to the inlet total values, and `MACH_NUMBER= 1E-9` (test case). +- `FREESTREAM_OPTION= DENSITY_FS` gives the state from pressure and density, instead of pressure and temperature. The supersonic edge tests use it (test case). +- Make sure that the initial state lies in the single-phase region, away from the saturation curve (advice). +- Check the initial state that SU2 prints before the first iteration (tutorial). + +### Schemes and limiters + +- With a non-ideal fluid, only `ROE`, `HLLC` and `JST` are allowed for `CONV_NUM_METHOD_FLOW` (code). The test cases use `ROE` (test case). +- The nozzle tests raise `ENTROPY_FIX_COEFF` to 0.1 (default 0.001) (test case). The entropy fix adds dissipation to the Roe scheme where wave speeds are close to zero (advice). +- Second order: the nozzle tutorial uses `MUSCL_FLOW= YES` with `SLOPE_LIMITER_FLOW= NONE` (tutorial). The LS89 cascade test, with shocks, uses `VENKATAKRISHNAN` (test case). Use a limiter when the flow has shocks (advice). +- The nozzle tests use `CFL_ADAPT= YES` with `CFL_ADAPT_PARAM= ( 0.1, 2.0, 10.0, 1000.0 )` (test case). The four values are the factor down, the factor up, and the minimum and maximum CFL (code). +- The edge and LS89 tests use multigrid (`MGLEVEL= 3`) (test case). + +Near the critical point (advice, to be reviewed): + +- The speed of sound and the heat capacity change fast there. Small errors in the reconstructed states can give non-physical states. Start first order (`MUSCL_FLOW= NO`) or with `RAMP_MUSCL`, then switch to second order. +- Start with a low CFL number, and let `CFL_ADAPT` raise it. +- Use a limiter, for example `VENKATAKRISHNAN`, if non-physical points appear near steep gradients. +- Refine the mesh where the flow passes close to the critical point. + +What SU2 does with non-physical states (code): + +- After each update, SU2 checks the density, pressure, temperature and square of the speed of sound of each point. If one is negative, SU2 goes back to the previous solution at that point and counts the point. The count is the history field `NONPHYSICAL_POINTS`. +- When a second-order reconstruction gives a negative pressure or density on an edge, SU2 uses first-order values on that edge. +- At start-up, SU2 prints "Warning. The original solution contains N points that are not physical." when the initial state is non-physical. + +## Check convergence and results + +- **Non-physical points.** Watch `NONPHYSICAL_POINTS`. It should drop to zero long before convergence (advice). +- **Residuals.** Watch the residuals (`RMS_DENSITY`, ...) as for any compressible case. See [Solver Setup](../Solver-Setup/). +- **Mass flow.** Check the mass flow balance between inlet and outlet, for example with `MARKER_ANALYZE` and `SURFACE_MASSFLOW` (advice). +- **Phase.** Check where the flow lies on a pressure-temperature or temperature-entropy diagram of the fluid. All points must stay outside the two-phase region (advice). +- **Non-ideal effects.** Compute the compressibility factor Z = p / (rho R T) in post-processing. Values far from 1 show where the non-ideal effects matter (tutorial). SU2 does not write Z as an output field (code). +- **Data-driven model.** With `DATADRIVEN_FLUID`, look at the volume field `EXTRAPOLATION`. It marks points where the state is outside the range of the training data. `FLUIDMODEL_NEWTONITER` shows how many Newton iterations the fluid model needed (code). +- **Experiments.** Compare with experiments where you can. The NICFD nozzle tutorial compares pressure and Mach number on the nozzle axis with measurements (tutorial). + +## Common problems + +| Symptom | Likely cause | What to try | +|---|---|---| +| SU2 stops: "Riemann Boundary conditions or Giles must be used for inlet and outlet with Not Ideal Compressible Fluids". | `MARKER_INLET`, `MARKER_OUTLET` or `MARKER_FAR` with a non-ideal fluid (code). | Use `MARKER_RIEMANN` or `MARKER_GILES`. | +| SU2 stops: "Only ROE Upwind, HLLC Upwind scheme, and JST scheme can be used for Non-Ideal Compressible Fluids". | Another convective scheme (code). | Use `ROE`, `HLLC` or `JST`. | +| SU2 stops: "CoolProp can not be used with non-dimensionalization." | `REF_DIMENSIONALIZATION` is not `DIMENSIONAL` (code). | Set `REF_DIMENSIONALIZATION= DIMENSIONAL`. | +| SU2 stops: "SU2 was not compiled with CoolProp (-Denable-coolprop=true)". | A build without CoolProp (code). | Rebuild with `-Denable-coolprop=true`, without AD. | +| SU2 stops: "SU2 was not compiled with MLPCpp enabled (-Denable-mlpcpp=true)." | A build without MLPCpp (code). | Rebuild with `-Denable-mlpcpp=true`. | +| SU2 stops: "Viscosity model not available for this fluid in CoolProp library." (or the same for conductivity). | `FLUID_NAME` is not in the list of the transport model, or is spelled with other capitals (code). | Use the exact name, for example `Nitrogen`, or use a constant model. | +| SU2 stops: "POLYNOMIAL_VISCOSITY and POLYNOMIAL_CONDUCTIVITY are for incompressible only currently." | A polynomial transport model with a compressible solver (code). | Use a constant model or `COOLPROP`. | +| `NONPHYSICAL_POINTS` stays above zero, or sound-speed squared is negative. | An invalid single-phase state, a metastable/unstable EOS branch, or too large a step at start-up (advice). | Check the boundary values against the saturation curve. Lower the CFL, start first order, and refine near the critical point (to be reviewed). | +| Strange results close to saturation with `COOLPROP`. | In a two-phase state, the code raises the temperature by 0.1 K and evaluates the speed of sound of the gas phase (code). | Keep the flow out of the two-phase region: the results there are not reliable. | +| The results look like air. | `CRITICAL_*`, `ACENTRIC_FACTOR`, `GAMMA_VALUE`, `GAS_CONSTANT`, `MU_CONSTANT` or `THERMAL_CONDUCTIVITY_CONSTANT` left at their defaults, which do not collectively describe the intended fluid (code). | Set all fluid and transport parameters for your fluid. | +| The CoolProp conductivity has no effect. | `TURBULENT_CONDUCTIVITY_MODEL` is left at `CONSTANT_PRANDTL_TURB` (code). | Set `TURBULENT_CONDUCTIVITY_MODEL= NONE` (to be reviewed). | +| `EXTRAPOLATION` is 1 in parts of the domain. | The data-driven model is used outside its training range (code). | Generate data and retrain over a wider range of density and energy. | +| The inlet flow angle is wrong on a 2D inlet that is not normal to x. | In 2D, SU2 reads the direction of the Riemann `TOTAL_CONDITIONS_PT` inlet relative to the boundary normal. In 3D, it reads it as x, y, z components (code, to be reviewed). | In 2D, give the direction as (normal, tangential) components. | +| The run diverges at the start with a large pressure ratio. | The outlet pressure is applied at once (advice). | With `MARKER_GILES`, use `RAMP_OUTLET` as in the data-driven tutorial (tutorial). With `MARKER_RIEMANN`, start with a higher outlet pressure and lower it in steps (to be reviewed). | + +## Related tutorials and test cases + +Tutorials: + +- [Non-ideal compressible flow in a supersonic nozzle](/tutorials/NICFD_nozzle/): Peng-Robinson, Riemann boundaries, comparison with experiments. +- [Non-ideal compressible flows with physics-informed neural networks](/tutorials/NICFD_nozzle_datadriven/): data-driven model, SU2 DataMiner, Giles boundaries. +- [Aachen turbine stage with mixing plane](/tutorials/Aachen_Turbine/): turbomachinery setup, which also applies to non-ideal fluids. + +Test cases (SU2 repository): + +- [nicf/coolprop](https://github.com/su2code/SU2/tree/develop/TestCases/nicf/coolprop): CoolProp fluid model (`fluidModel.cfg`) and CoolProp transport models (`transportModel.cfg`). +- [nicf/datadriven](https://github.com/su2code/SU2/blob/develop/TestCases/nicf/datadriven/datadriven_nozzle.cfg): data-driven model with a physics-informed network. +- [nicf/edge](https://github.com/su2code/SU2/tree/develop/TestCases/nicf/edge): supersonic flow over an edge with `PR_GAS` and `VW_GAS`, Euler, multigrid. +- [nicf/LS89](https://github.com/su2code/SU2/tree/develop/TestCases/nicf/LS89): turbine cascade with `PR_GAS`, SA and SST models. +- [turbomachinery/transonic_stator_2D](https://github.com/su2code/SU2/blob/develop/TestCases/turbomachinery/transonic_stator_2D/transonic_stator_restart.cfg): stator with `PR_GAS` and Giles boundaries. +- [turbomachinery/centrifugal_stage](https://github.com/su2code/SU2/blob/develop/TestCases/turbomachinery/centrifugal_stage/centrifugal_stage.cfg) uses `PR_GAS` but old option names; it is not part of the regression tests. + +User guide pages: [Physical Definition](../Physical-Definition/), [Markers and Boundary Conditions](../Markers-and-BC/), [Convective Schemes](../Convective-Schemes/), [Slope Limiters and Shock Resolution](../Slope-Limiters-and-Shock-Resolution/), [Theory](../Theory/), [Option reference](../Option-Reference/), [Output fields](../Output-Fields-Reference/). + +Source review: 22 October 2026, against [SU2 `docs_site` at `41ea6a219a`](https://github.com/rois1995/SU2/tree/41ea6a219ac038574f3d4a5b130c0c1d8af66457). See the [review scope and outstanding validation](../Documentation-Status/#guide-and-model-review). Setup recommendations remain draft where indicated. diff --git a/_docs_v7/Setup-Guide-RANS-External-Aero.md b/_docs_v7/Setup-Guide-RANS-External-Aero.md new file mode 100644 index 00000000..07b06851 --- /dev/null +++ b/_docs_v7/Setup-Guide-RANS-External-Aero.md @@ -0,0 +1,345 @@ +--- +title: "Setup Guide: Steady RANS for External Aerodynamics" +permalink: /docs_v7/Setup-Guide-RANS-External-Aero/ +--- + +{% include setup-guide-intro.md %} + +--- + +- [When to use this guide](#when-to-use-this-guide) +- [Start from](#start-from) +- [Settings that matter](#settings-that-matter) +- [Check convergence and results](#check-convergence-and-results) +- [Common problems](#common-problems) +- [Related tutorials and test cases](#related-tutorials-and-test-cases) + +--- + +## When to use this guide + +Use this guide for a steady, compressible, turbulent flow around a body in open air: an airfoil, a wing, a fuselage or a full aircraft. +"Steady" means that the flow settles to one state that does not change in time. + +Use another guide if: + +- the flow does not settle, for example with vortex shedding or large separated regions. See [Setup Guide: Unsteady Flows and DES](../Setup-Guide-Unsteady-DES/). +- large laminar regions matter, for example at low Reynolds numbers. See [Setup Guide: Laminar-Turbulent Transition](../Setup-Guide-Transition/). + +## Start from + +This config comes from the ONERA M6 wing tutorial: `compressible_flow/Turbulent_ONERAM6/turb_ONERAM6.cfg` in the [Tutorials repository](https://github.com/su2code/Tutorials/blob/develop/compressible_flow/Turbulent_ONERAM6/turb_ONERAM6.cfg). +We removed the adjoint, design and output file name options, and the options that have no effect with these settings. All other values are unchanged. +The mesh file is in the same tutorial folder. + +``` +% ------------- Problem ------------------------------------------------% +SOLVER= RANS +KIND_TURB_MODEL= SA +MATH_PROBLEM= DIRECT +RESTART_SOL= NO +% +% ------------- Free stream (from Mach and Reynolds number) ------------% +MACH_NUMBER= 0.8395 +AOA= 3.06 +SIDESLIP_ANGLE= 0.0 +INIT_OPTION= REYNOLDS +FREESTREAM_OPTION= TEMPERATURE_FS +FREESTREAM_TEMPERATURE= 288.15 +REYNOLDS_NUMBER= 11.72E6 +REYNOLDS_LENGTH= 0.64607 +REF_DIMENSIONALIZATION= FREESTREAM_VEL_EQ_ONE +% +% ------------- Gas and viscosity --------------------------------------% +FLUID_MODEL= STANDARD_AIR +VISCOSITY_MODEL= SUTHERLAND +MU_REF= 1.716E-5 +MU_T_REF= 273.15 +SUTHERLAND_CONSTANT= 110.4 +CONDUCTIVITY_MODEL= CONSTANT_PRANDTL +PRANDTL_LAM= 0.72 +PRANDTL_TURB= 0.90 +% +% ------------- Reference values for the coefficients ------------------% +REF_ORIGIN_MOMENT_X= 0.25 +REF_ORIGIN_MOMENT_Y= 0.00 +REF_ORIGIN_MOMENT_Z= 0.00 +REF_LENGTH= 0.64607 +REF_AREA= 0 +% +% ------------- Boundary conditions ------------------------------------% +MARKER_HEATFLUX= ( WING, 0.0 ) +MARKER_FAR= ( FARFIELD ) +MARKER_SYM= ( SYMMETRY ) +MARKER_PLOTTING= ( WING ) +MARKER_MONITORING= ( WING ) +% +% ------------- Numerics -----------------------------------------------% +NUM_METHOD_GRAD= GREEN_GAUSS +CFL_NUMBER= 100.0 +CFL_ADAPT= NO +ITER= 999999 +LINEAR_SOLVER= FGMRES +LINEAR_SOLVER_PREC= ILU +LINEAR_SOLVER_ERROR= 1E-10 +LINEAR_SOLVER_ITER= 10 +MGLEVEL= 0 +CONV_NUM_METHOD_FLOW= JST +JST_SENSOR_COEFF= ( 0.5, 0.02 ) +TIME_DISCRE_FLOW= EULER_IMPLICIT +CONV_NUM_METHOD_TURB= SCALAR_UPWIND +MUSCL_TURB= NO +TIME_DISCRE_TURB= EULER_IMPLICIT +% +% ------------- Convergence: stop when the drag stops changing ---------% +CONV_FIELD= DRAG +CONV_STARTITER= 10 +CONV_CAUCHY_ELEMS= 100 +CONV_CAUCHY_EPS= 1E-6 +% +% ------------- Input and output ---------------------------------------% +MESH_FILENAME= mesh_ONERAM6_turb_hexa_43008.su2 +MESH_FORMAT= SU2 +SCREEN_OUTPUT= (INNER_ITER, WALL_TIME, RMS_DENSITY, RMS_NU_TILDE, LIFT, DRAG) +``` + +The tutorial page [Turbulent ONERA M6](/tutorials/Turbulent_ONERAM6/) explains the free-stream and convergence options of this config. + +## Settings that matter + +### Turbulence model: SA or SST + +Set `SOLVER= RANS` and pick the model with `KIND_TURB_MODEL`. With `SOLVER= RANS`, SU2 stops with an error if `KIND_TURB_MODEL` is `NONE` (code). + +**Spalart-Allmaras (`SA`).** SA solves one transport equation, for a modified eddy viscosity. + +- With an empty `SA_OPTIONS`, SU2 runs SA without the ft2 term ("SA-noft2") (docs, code). +- `SA_OPTIONS` accepts `NEGATIVE`, `EDWARDS`, `WITHFT2`, `QCR2000`, `COMPRESSIBILITY`, `ROTATION`, `BCM` and `EXPERIMENTAL` (code). +- SA-neg needs the ft2 term: write `SA_OPTIONS= NEGATIVE, WITHFT2`. Without `WITHFT2`, SU2 stops with an error unless you add `EXPERIMENTAL` (code). The test cases use both forms (test case). +- The free-stream value of the SA variable is `FREESTREAM_NU_FACTOR` times the free-stream kinematic viscosity. The default is `3.0` (code, docs). +- Most SU2 external aerodynamics tests use SA: ONERA M6, the SA versions of RAE2822, and 30P30N (test case). + +**Menter SST (`SST`).** SST solves two transport equations: one for the turbulent kinetic energy k, one for the specific dissipation rate omega. + +- With an empty `SST_OPTIONS`, SU2 runs the 2003 version, "SST-2003m", as set in `ParseSSTOptions` in `option_structure.hpp` (code). Some older pages give `V1994m` as the default; this is out of date. +- The other `SST_OPTIONS` values are `V1994m`, `V2003m`, `SUSTAINING`, `VORTICITY`, `KATO-LAUNDER`, `UQ`, `COMPRESSIBILITY-WILCOX`, `COMPRESSIBILITY-SARKAR` and `DIMENSIONLESS_LIMIT`. Write `KATO-LAUNDER` with a dash (code). +- SST needs free-stream values for k and omega. They come from `FREESTREAM_TURBULENCEINTENSITY` (a fraction: `0.001` means 0.1 %) and `FREESTREAM_TURB2LAMVISCRATIO` (eddy viscosity over laminar viscosity). The defaults are `0.05` and `10.0` (code). These are parser defaults, not calibrated inlet conditions. Choose values for the actual flow and check their decay to the body; see the [TMR SST boundary conditions](https://tmbwg.github.io/turbmodels/sst.html) (reference, advice). +- External aerodynamics tests use, for example, `FREESTREAM_TURBULENCEINTENSITY= 0.001` with `FREESTREAM_TURB2LAMVISCRATIO= 100.0` (RAE2822 SST), or `0.001` with `0.1` (NACA0012 SST with `SUSTAINING`) (test case). +- In SST, k decays between the far field and the body. Two options control this decay. `SST_OPTIONS= SUSTAINING` supplies a floor to production using the ambient values; SU2 uses a maximum rather than the additive sustaining terms of the TMR definition (code). See [the implementation difference](../Turbulence-Models/#sst). `TURB_FIXED_VALUES= YES` holds k and omega at the far-field values in an upstream region set by `TURB_FIXED_VALUES_DOMAIN` (code). The test `rans/naca0012/turb_NACA0012_sst_fixedvalues.cfg` uses the second one (test case). + +**Which one to pick.** + +- SA is robust and widely used for attached flows over wings and airfoils (advice). +- SST is often preferred when adverse pressure gradients and separation matter (advice, to be reviewed). +- Differences between SA and SST are evidence of model sensitivity, not a quantified uncertainty bound. First check iterative and mesh convergence, then examine the regions where the models differ (advice). + +See [Turbulence Models](../Turbulence-Models/) for the full option list. + +### Convective scheme: JST or an upwind scheme + +The convective scheme computes the flux of mass, momentum and energy through each cell face. Set it with `CONV_NUM_METHOD_FLOW`. It has no default, so always set it (code). + +**JST** (Jameson-Schmidt-Turkel) is a central scheme with added artificial dissipation. + +- The two dissipation coefficients are `JST_SENSOR_COEFF= (2nd order, 4th order)`. The default is `( 0.5, 0.02 )` (code, docs). +- JST is robust and allows high CFL numbers. It over-predicts viscous drag on coarse meshes or at low Reynolds numbers (docs). +- `JST_MAT` uses matrix dissipation and gives better viscous drag on such meshes (docs). +- The ONERA M6 tutorial and the RAE2822 tests use JST (tutorial, test case). + +**Upwind schemes** use the direction of the waves in the flow. `ROE` is the most used (test case). The others are `L2ROE` and `LMROE` (low Mach number variants), `AUSMPLUSUP`, `AUSMPLUSUP2`, `SLAU`, `SLAU2`, `HLLC` and `MSW` (docs, code). + +- An upwind scheme is first order unless you turn on MUSCL reconstruction, see the next section (docs). +- `ENTROPY_FIX_COEFF` sets a lower bound on the Roe dissipation. The default is `0.001` (code). The 30P30N validation case uses `1e-5` (test case). +- The tests `rans/oneram6/turb_ONERAM6.cfg` and `rans/naca0012/turb_NACA0012_sst.cfg` use `ROE` (test case). + +**Turbulence equations.** Use `CONV_NUM_METHOD_TURB= SCALAR_UPWIND`, as most external aerodynamics tests do (test case). The code also accepts `BOUNDED_SCALAR`; the tests `turb_SA_RAE2822.cfg` and `turb_SST_RAE2822.cfg` use it (code, test case). `MUSCL_TURB` defaults to `NO`, so the turbulence convection is first order unless you change it (code). Most tests keep `MUSCL_TURB= NO` (test case). + +See [Convective Schemes](../Convective-Schemes/). + +### MUSCL reconstruction and slope limiters + +MUSCL reconstruction makes an upwind scheme second order. It uses the solution gradient to compute the values on each side of a face. A slope limiter reduces this gradient near shocks and steep changes, so that the solution does not oscillate. + +- `MUSCL_FLOW` defaults to `YES` and `SLOPE_LIMITER_FLOW` defaults to `VENKATAKRISHNAN` (code). MUSCL has no effect on central schemes such as JST (docs). +- For transonic flows with shocks, keep a limiter. The ONERA M6 test uses `VENKATAKRISHNAN` with `VENKAT_LIMITER_COEFF= 1.0` (test case). +- For subsonic flows without shocks, you can turn the limiter off. The NACA0012 SST test at Mach 0.15 uses `SLOPE_LIMITER_FLOW= NONE` and `MUSCL_KAPPA_FLOW= 0.5` (test case). +- `VENKAT_LIMITER_COEFF` defaults to `0.05`. Larger values limit less (code). For `VENKATAKRISHNAN`, its effect depends on the cell size in mesh units. So the right value changes with the mesh and with the non-dimensional scaling (docs). +- `VAN_ALBADA_EDGE` is another option. The 30P30N validation case uses it (test case). +- `LIMITER_ITER` freezes the limiter after this many iterations. The default is `999999` (code). Freezing can help when the residuals stall because the limiter keeps switching (advice, to be reviewed). +- `NUM_METHOD_GRAD` sets the gradient method (default `WEIGHTED_LEAST_SQUARES`). `NUM_METHOD_GRAD_RECON` can set a different method for MUSCL only. By default MUSCL uses `NUM_METHOD_GRAD` (code). + +See [Slope Limiters and Shock Resolution](../Slope-Limiters-and-Shock-Resolution/). + +### CFL number and adaptive CFL + +SU2 marches a steady case in pseudo-time. The CFL number sets the local pseudo-time step. A higher CFL can reduce the iteration count, but can also make the linear solve harder or destabilize the nonlinear iteration. + +- The default `CFL_NUMBER` is `1.25` (code). Implicit RANS runs use much higher values: `100` in the ONERA M6 tutorial, `1000` in the RAE2822 SA and NACA0012 SST tests (tutorial, test case). +- `CFL_ADAPT= YES` lets SU2 change the CFL during the run. `CFL_NUMBER` is then the starting value (code). +- `CFL_ADAPT_PARAM` has up to six values: factor down, factor up, minimum CFL, maximum CFL, acceptable linear solver residual, start iteration. Missing values take the defaults `( 0.1, 1.2, 10.0, 100.0, 0.001, 0 )` (code). +- The comments in `config_template.cfg` explain the rules. The CFL goes up by the "factor up" while the solution update is not limited and the linear solver converges well enough. It goes down when the update is limited, when the linear solver does not converge enough, or when the residuals stall or oscillate. It returns to the minimum if the linear solver diverges or the residuals grow too much (code). +- Examples: the E387 transition tutorial uses `CFL_NUMBER= 1` with `CFL_ADAPT_PARAM= ( 0.1, 2.0, 40.0, 1e10, 0.001 )`. The 30P30N case uses `CFL_ADAPT_PARAM= ( 1, 1.05, 10, 400 )` (tutorial, test case). +- `CFL_REDUCTION_TURB` scales the CFL of the turbulence equations. The default is `1.0` (code). The RAE2822 SST test uses `0.5` (test case). +- Add `AVG_CFL` to `SCREEN_OUTPUT` to see the CFL during the run (test case). + +### Multigrid + +Multigrid also solves the equations on coarser versions of the mesh. This removes large-scale errors faster. + +- `MGLEVEL` sets the number of coarse levels. The default is `0` (off) (code). +- `MGCYCLE` is `V_CYCLE` (default), `W_CYCLE` or `FULLMG_CYCLE` (code). +- The RAE2822 tests use `MGLEVEL= 3` with `JST`, `MGCYCLE= V_CYCLE`, `MG_DAMP_RESTRICTION= 0.75` and `MG_DAMP_PROLONGATION= 0.75` (test case). The code default for both damping factors is `0.5` (code). +- With a central scheme, the coarse levels always use the Lax-Friedrich scheme. MUSCL has no effect on coarse levels (docs). +- If the run is unstable with multigrid, reduce `MGLEVEL` or turn multigrid off (advice). + +### Linear solver and preconditioner + +Each implicit iteration solves a linear system. You do not need to solve it exactly: only the final nonlinear residual matters for accuracy (docs). + +The defaults are `LINEAR_SOLVER= FGMRES`, `LINEAR_SOLVER_PREC= ILU`, `LINEAR_SOLVER_ERROR= 1E-6` and `LINEAR_SOLVER_ITER= 10` (code). + +The [Linear Solvers and Preconditioners](../Linear-Solvers-and-Preconditioners/) page gives this advice (docs): + +- Use the loosest tolerance that keeps the run stable, usually between `0.05` and `0.001`. +- About 10 linear iterations are enough for upwind schemes. Central schemes may need up to 50. +- Use `ILU` at high CFL. `LU_SGS` can be faster at low CFL because it has no setup cost. +- If memory is a problem, use `RESTARTED_FGMRES` or `BCGSTAB`. + +From the test cases (test case): + +- Add `LINSOL_ITER` and `LINSOL_RESIDUAL` to `SCREEN_OUTPUT` to see how well the linear solver converges. +- A Newton-Krylov method is also available with `NEWTON_KRYLOV= YES`. The 30P30N validation case shows its parameters. + +### Convergence criteria + +`CONV_FIELD` names the output fields that decide when the run stops. For the compressible solver the default is `RMS_DENSITY` (code). If you list several fields, all of them must meet their criterion (code). + +**Residual fields** (such as `RMS_DENSITY`): the run stops when the log10 of the residual falls below `CONV_RESIDUAL_MINVAL`. The default is `-14` (code). + +**Coefficient fields** (such as `LIFT` or `DRAG`) use a Cauchy criterion. This criterion looks at how much the coefficient changes from one iteration to the next (code): + +- At each iteration, SU2 computes the change of the coefficient divided by the coefficient. If the coefficient is smaller than 0.1 in size, SU2 divides by 0.1 instead. +- SU2 averages this value over the last `CONV_CAUCHY_ELEMS` iterations (default `100`). +- The run stops when the average is below `CONV_CAUCHY_EPS` (default `1E-10`). +- `CONV_STARTITER` (default `5`) sets the first iteration where SU2 checks the criteria. + +The ONERA M6 tutorial stops on `CONV_FIELD= DRAG` with `CONV_CAUCHY_EPS= 1E-6` (tutorial). +A coefficient can look converged while the residuals are still high, so check both (advice). + +`ITER` sets the maximum number of iterations. The default is `1000` (code). + +See [Solver Setup](../Solver-Setup/#setting-convergence-criteria). + +### Fixed lift (fixed CL) + +In fixed-CL mode, SU2 changes the angle of attack until the lift coefficient reaches a target. These rules come from the code (code): + +- `FIXED_CL_MODE= YES` turns it on. `TARGET_CL` is the target (default `0.0`). `AOA` is the starting angle. +- `DCL_DALPHA` is your estimate of the lift slope, per degree. The default is `0.2`, also in `config_template.cfg`. SU2 changes the angle by (target CL − current CL) / `DCL_DALPHA`. +- SU2 updates the angle when the convergence criteria are met but CL is still away from the target. It also updates it at the latest every `UPDATE_AOA_ITER_LIMIT` iterations (default `200`). +- The lift counts as reached when it is within `CONV_CAUCHY_EPS`/2 of the target. So `CONV_CAUCHY_EPS` sets both the convergence tolerance and the lift tolerance. +- At the end, SU2 runs `ITER_DCL_DALPHA` more iterations (default `500`) to compute dCL/dalpha by finite differences. These are added to `ITER`. Set `ITER_DCL_DALPHA= 0` to skip this step. +- Fixed-CL mode is for compressible solvers only. +- Add the `AOA` history field to see the angle during the run. + +The RAE2822 design tutorial runs SA in fixed-CL mode with `TARGET_CL= 0.724`, `DCL_DALPHA= 0.2`, `UPDATE_AOA_ITER_LIMIT= 100`, `ITER_DCL_DALPHA= 500` and `CONV_CAUCHY_EPS= 1E-6` (tutorial). The fixed-CL test case `fixed_cl/naca0012/inv_NACA0012.cfg` is inviscid (test case). + +### Free stream from Mach and Reynolds number + +With `INIT_OPTION= REYNOLDS` (the default), SU2 builds the free stream from the Mach number and the Reynolds number (code, tutorial): + +1. It computes the speed of sound from `FREESTREAM_TEMPERATURE` and the gas constants. +2. It computes the velocity from `MACH_NUMBER`, `AOA` and `SIDESLIP_ANGLE`. +3. It computes the viscosity with the viscosity model. +4. It computes the density from `REYNOLDS_NUMBER` and `REYNOLDS_LENGTH`. +5. It computes the pressure from the gas law. `FREESTREAM_PRESSURE` is ignored. + +Things to check: + +- With `SYSTEM_MEASUREMENTS= SI` (the default), give mesh lengths in metres. `REYNOLDS_LENGTH` is the length (in mesh units) that the Reynolds number refers to, for example the chord (tutorial). +- With `INIT_OPTION= TD_CONDITIONS`, SU2 uses `FREESTREAM_PRESSURE` and `FREESTREAM_TEMPERATURE` instead, and ignores the Reynolds number (tutorial). +- SU2 prints a table of free-stream values before the first iteration. Check it (tutorial). +- `REF_DIMENSIONALIZATION` sets the scaling of the equations. The default is `DIMENSIONAL` (code). The tests also use `FREESTREAM_VEL_EQ_ONE`, `FREESTREAM_VEL_EQ_MACH` and `FREESTREAM_PRESS_EQ_ONE` (tutorial, test case). + +**Reference values for the coefficients** (code). `REF_LENGTH` is used for moments. `REF_AREA` is used for all force coefficients. With `REF_AREA= 0`, SU2 computes the area as the projection of the body on the y plane (2D) or the z plane (3D). `REF_ORIGIN_MOMENT_X`, `_Y` and `_Z` set the moment reference point. + +See [Physical Definition](../Physical-Definition/#free-stream-definition-compressible). + +### Far-field and wall boundary conditions + +- `MARKER_FAR` sets a far-field boundary. SU2 imposes the free-stream state there with a characteristic-based condition (docs, tutorial). +- Place the far-field boundary far from the body, often 50 to 100 chords for airfoils, so that it does not change the lift (advice, to be reviewed). +- `MARKER_HEATFLUX= ( wall, 0.0 )` is an adiabatic no-slip wall. All external aerodynamics tests use it (test case). `MARKER_ISOTHERMAL` sets a wall temperature instead (docs). +- `MARKER_SYM` is a symmetry plane, for example at the root of a half wing (tutorial). +- `MARKER_MONITORING` lists the surfaces whose forces give `LIFT`, `DRAG` and the other coefficients (code). `MARKER_PLOTTING` lists the surfaces written to the surface output files (tutorial). + +See [Markers and Boundary Conditions](../Markers-and-BC/). + +### Near-wall mesh, y+ and wall functions + +y+ is the distance of the first point from the wall, in wall units. It tells you if the mesh resolves the thin layer next to the wall. + +- Without wall functions, the first point must be in the viscous sublayer: y+ below 5 (docs). y+ about 1 is the usual target (advice). +- With wall functions, SU2 models the near-wall layer, so the first point can be further from the wall. Turn them on per marker: `MARKER_WALL_FUNCTIONS= ( wall, STANDARD_WALL_FUNCTION )`. They work with SA and SST, compressible and incompressible (docs). +- For RANS, only `NO_WALL_FUNCTION` and `STANDARD_WALL_FUNCTION` are tested. `ADAPTIVE_WALL_FUNCTION`, `SCALABLE_WALL_FUNCTION` and `NONEQUILIBRIUM_WALL_MODEL` stop SU2 with an error (code, test case). +- The wall function is active only where y+ is above `WALLMODEL_MINYPLUS` (default `5.0`) (code, docs). The activation threshold is not a mesh-accuracy target. See [Wall Treatment](../Wall-Treatment/#recommended-use) for log-layer placement and the current restrictions on mixed wall treatments. +- Wall functions and `WALL_ROUGHNESS` cannot be used together (code). +- Wall functions assume an attached boundary layer in equilibrium. They are less accurate near separation and strong pressure gradients (advice). +- Check the `Y_PLUS` output field on the wall. It is in the default `PRIMITIVE` output group (code). + +See [Markers and Boundary Conditions](../Markers-and-BC/#wall-functions) and the test cases in `TestCases/wallfunctions/flatplate/`. + +## Check convergence and results + +- **Residuals.** Plot `RMS_DENSITY` and the turbulence residual (`RMS_NU_TILDE` for SA, `RMS_TKE` and `RMS_DISSIPATION` for SST). A drop of several orders of magnitude is a good sign (advice). +- **Coefficients.** `LIFT`, `DRAG` and the moments must be flat at the end of the run. Add the `CAUCHY` group to `HISTORY_OUTPUT` to see the Cauchy values (code). +- **Linear solver and CFL.** `LINSOL_RESIDUAL` is log10 of the final linear residual: compare it with log10(`LINEAR_SOLVER_ERROR`), for example −6 for a tolerance of 1e-6 (code). With `CFL_ADAPT= YES`, `AVG_CFL` should grow and stay high (advice). +- **Free stream.** Read the free-stream table that SU2 prints at the start: Reynolds number, density, pressure, velocity (tutorial). +- **y+.** Look at `Y_PLUS` on the walls (code). +- **Surface data.** Put `SURFACE_PARAVIEW` or `SURFACE_CSV` in `OUTPUT_FILES`, and plot `PRESSURE_COEFF` and `SKIN_FRICTION-X` along the wall (code, tutorial). +- **Force breakdown.** `WRT_FORCES_BREAKDOWN= YES` writes a file that splits the forces into pressure and viscous parts, per surface (code, tutorial). +- **Mesh.** Run at least two, better three, meshes of different size. Check that the coefficients change less and less (advice). + +See [History and Solution Output](../Custom-Output/) and the [Output Fields Reference](../Output-Fields-Reference/). + +## Common problems + +| Symptom | Likely cause | What to try | +| --- | --- | --- | +| The run diverges in the first iterations. | The CFL is too high for the initial flow. | Start with a low `CFL_NUMBER` and use `CFL_ADAPT= YES`. Check the free-stream table (tutorial). | +| SU2 stops: "A non-standard version of SA-neg was requested". | `NEGATIVE` without the ft2 term. | Use `SA_OPTIONS= NEGATIVE, WITHFT2` (code). | +| The residuals stop dropping and the coefficients oscillate a little. | The limiter keeps switching, or the flow is not steady (buffet, separation). | Raise `VENKAT_LIMITER_COEFF` or freeze the limiter with `LIMITER_ITER` (advice, to be reviewed). If the flow is really unsteady, see [Setup Guide: Unsteady Flows and DES](../Setup-Guide-Unsteady-DES/). | +| `LINSOL_RESIDUAL` stays near 1. | The linear system is too hard at this CFL. | Lower the CFL, use `ILU`, raise `LINEAR_SOLVER_ITER` (docs). | +| The drag is too high with `JST` on a coarse mesh. | Too much numerical dissipation. | Try `JST_MAT`, or an upwind scheme with MUSCL (docs). Refine the mesh. | +| The skin friction or drag is far from the expected value. | Wrong Reynolds number: the mesh is not in meters, or `REYNOLDS_LENGTH` is wrong. | Check the mesh units and the free-stream table (tutorial). | +| SST results depend on the far-field distance. | The free-stream k decays before it reaches the body. | Check the incoming turbulence and domain-size sensitivity. If decay is the cause, consider `SST_OPTIONS= SUSTAINING` or `TURB_FIXED_VALUES= YES` with its upstream plane set; these do not fix pressure-field interference from a close far field (advice). | +| The run stops at iteration 1000. | `ITER` has a default of `1000`. | Set `ITER` (code). | +| A fixed-CL run ends before CL reaches the target. | The angle is updated too rarely, or `CONV_CAUCHY_EPS` is too large. | Lower `UPDATE_AOA_ITER_LIMIT` and check `CONV_CAUCHY_EPS` (code). | + +## Related tutorials and test cases + +Tutorials: + +- [Turbulent ONERA M6](/tutorials/Turbulent_ONERAM6/): 3D transonic wing, SA, JST, Cauchy criterion on drag. +- [Turbulent Flat Plate](/tutorials/Turbulent_Flat_Plate/): zero pressure gradient flat plate with SA. +- [Constrained shape design of a transonic turbulent airfoil](/tutorials/Turbulent_2D_Constrained_RAE2822/): RAE2822 with SA in fixed-CL mode, used for shape design. +- [UQ NACA0012](/tutorials/UQ_NACA0012/): SST with the `UQ` option. + +Test cases (develop branch): + +- [rans/oneram6/turb_ONERAM6.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/rans/oneram6/turb_ONERAM6.cfg): ONERA M6 with `ROE`, MUSCL and `VENKATAKRISHNAN`. +- [rans/rae2822/turb_SA_RAE2822.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/rans/rae2822/turb_SA_RAE2822.cfg) and [turb_SST_RAE2822.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/rans/rae2822/turb_SST_RAE2822.cfg): transonic airfoil with `JST` and multigrid. +- [rans/naca0012/turb_NACA0012_sst.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/rans/naca0012/turb_NACA0012_sst.cfg): subsonic airfoil, SST, `ROE` without limiter. +- [rans/naca0012/turb_NACA0012_sst_fixedvalues.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/rans/naca0012/turb_NACA0012_sst_fixedvalues.cfg): `TURB_FIXED_VALUES`. +- [turbulence_models/sa/rae2822/](https://github.com/su2code/SU2/tree/develop/TestCases/turbulence_models/sa/rae2822): SA variants (`NEGATIVE`, `EDWARDS`, `QCR2000`, `COMPRESSIBILITY`). +- [vandv/rans/30p30n/config.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/vandv/rans/30p30n/config.cfg): high-lift airfoil, `ROE` with `VAN_ALBADA_EDGE`, adaptive CFL, Newton-Krylov. +- [vandv/rans/swbli/config_sst.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/vandv/rans/swbli/config_sst.cfg): Mach 5 shock-boundary layer interaction with SST. +- [fixed_cl/naca0012/inv_NACA0012.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/fixed_cl/naca0012/inv_NACA0012.cfg): fixed-CL mode (inviscid). +- [wallfunctions/flatplate/compressible_SA/turb_SA_flatplate.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/wallfunctions/flatplate/compressible_SA/turb_SA_flatplate.cfg): wall functions with SA. + +User guide pages: + +- [Physical Definition](../Physical-Definition/), [Convective Schemes](../Convective-Schemes/), [Slope Limiters and Shock Resolution](../Slope-Limiters-and-Shock-Resolution/), [Linear Solvers and Preconditioners](../Linear-Solvers-and-Preconditioners/), [Markers and Boundary Conditions](../Markers-and-BC/), [Solver Setup](../Solver-Setup/), [Governing Equations](../Theory/), [History and Solution Output](../Custom-Output/). +- All options: [Option Reference](../Option-Reference/). All output fields: [Output Fields Reference](../Output-Fields-Reference/). + +Source review: 22 October 2026, against [SU2 `docs_site` at `41ea6a219a`](https://github.com/rois1995/SU2/tree/41ea6a219ac038574f3d4a5b130c0c1d8af66457). See the [review scope and outstanding validation](../Documentation-Status/#guide-and-model-review). Setup recommendations remain draft where indicated. diff --git a/_docs_v7/Setup-Guide-Shape-Optimization.md b/_docs_v7/Setup-Guide-Shape-Optimization.md new file mode 100644 index 00000000..0d19432c --- /dev/null +++ b/_docs_v7/Setup-Guide-Shape-Optimization.md @@ -0,0 +1,319 @@ +--- +title: "Setup Guide: Shape Optimization with the Discrete Adjoint" +permalink: /docs_v7/Setup-Guide-Shape-Optimization/ +--- + +{% include setup-guide-intro.md %} + +--- + +- [When to use this guide](#when-to-use-this-guide) +- [Start from](#start-from) +- [Settings that matter](#settings-that-matter) +- [Check convergence and results](#check-convergence-and-results) +- [Common problems](#common-problems) +- [Related tutorials and test cases](#related-tutorials-and-test-cases) + +--- + +## When to use this guide + +Use this guide to change the shape of a body or a duct so that an output of the flow improves: for example less drag at a fixed lift, or a lower pressure drop. + +SU2 computes the gradient of the output with respect to the shape parameters with the **adjoint method**: one adjoint solve gives the sensitivity of one scalar output to all shape parameters. Its cost does not grow by one flow solve per parameter, but runtime and memory depend on the solver, convergence and recording strategy. + +SU2 has two adjoint solvers: + +- The **discrete adjoint** differentiates the SU2 code itself with algorithmic differentiation (AD). Its gradient matches the discretized flow equations, including turbulence models and most boundary conditions. This guide focuses on it. +- The **continuous adjoint** solves separate adjoint equations derived by hand. It runs with the normal build, but supports fewer cases. + +In this guide, the (code) tag also covers the Python scripts of SU2. + +## Start from + +The block below comes from the test case [multiple_ffd/naca0012](https://github.com/su2code/SU2/blob/develop/TestCases/multiple_ffd/naca0012/inv_NACA0012_ffd.cfg). It is an inviscid NACA 0012 airfoil with two FFD boxes, one on each side. The regression tests run it with `discrete_adjoint.py`. + +- We removed the comments, the continuous adjoint options, the options that have no effect in this setup, and most file names. +- We added `GEO_MARKER` and `GEO_DESCRIPTION` from [optimization_euler/steady_naca0012](https://github.com/su2code/SU2/blob/develop/TestCases/optimization_euler/steady_naca0012/inv_NACA0012_adv.cfg), because the thickness constraint needs SU2_GEO. +- The mesh `mesh_NACA0012_multiFFD.su2` already contains the FFD boxes. It is in the [TestCases repository](https://github.com/su2code/TestCases). + +``` +SOLVER= EULER +MATH_PROBLEM= DIRECT +RESTART_SOL= NO +READ_BINARY_RESTART= NO +% +MACH_NUMBER= 0.8 +AOA= 1.25 +FREESTREAM_PRESSURE= 101325.0 +FREESTREAM_TEMPERATURE= 288.15 +REF_ORIGIN_MOMENT_X= 0.25 +REF_ORIGIN_MOMENT_Y= 0.00 +REF_ORIGIN_MOMENT_Z= 0.00 +REF_LENGTH= 1.0 +REF_AREA= 1.0 +REF_DIMENSIONALIZATION= FREESTREAM_PRESS_EQ_ONE +% +MARKER_EULER= ( airfoil_upper, airfoil_lower ) +MARKER_FAR= ( farfield ) +MARKER_PLOTTING= ( airfoil_upper, airfoil_lower ) +MARKER_MONITORING= ( airfoil_upper, airfoil_lower ) +% +NUM_METHOD_GRAD= GREEN_GAUSS +CFL_NUMBER= 5.0 +LINEAR_SOLVER= FGMRES +LINEAR_SOLVER_PREC= ILU +LINEAR_SOLVER_ERROR= 1E-1 +LINEAR_SOLVER_ITER= 3 +MGLEVEL= 3 +MGCYCLE= V_CYCLE +MG_PRE_SMOOTH= ( 2, 2, 2, 2 ) +MG_POST_SMOOTH= ( 2, 2, 2, 2 ) +MG_CORRECTION_SMOOTH= ( 1, 1, 1, 1 ) +MG_DAMP_RESTRICTION= 0.5 +MG_DAMP_PROLONGATION= 0.5 +CONV_NUM_METHOD_FLOW= JST +JST_SENSOR_COEFF= ( 0.5, 0.02 ) +TIME_DISCRE_FLOW= EULER_IMPLICIT +% +OBJECTIVE_FUNCTION= DRAG +% +% The test stops after 10 iterations. A useful gradient needs a converged +% flow and adjoint solution: raise ITER. +ITER= 10 +CONV_RESIDUAL_MINVAL= -9 +CONV_STARTITER= 10 +% +DV_KIND= FFD_SETTING +DV_MARKER= ( airfoil_upper, airfoil_lower ) +DV_PARAM= ( UPPER, 1, 0, 0, 0.0, 1.0, 0.0 ) +DV_VALUE= 0.001 +DEFORM_LINEAR_SOLVER_ITER= 500 +DEFORM_NONLINEAR_ITER= 1 +DEFORM_CONSOLE_OUTPUT= YES +DEFORM_LINEAR_SOLVER_ERROR= 1E-14 +DEFORM_STIFFNESS_TYPE= INVERSE_VOLUME +% +FFD_TOLERANCE= 1E-10 +FFD_ITERATIONS= 500 +FFD_DEFINITION= ( LOWER, 0.075, -0.075, 0.0, 0.625, -0.075, 0.0, 0.625, -0.02, 0.0, 0.075, -0.02, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ); ( UPPER, 0.075, 0.02, 0.0, 0.625, 0.02, 0.0, 0.625, 0.075, 0.0, 0.075, 0.075, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ) +FFD_DEGREE= ( 4, 1, 0 ); ( 4, 1, 0 ) +FFD_CONTINUITY= USER_INPUT +FFD_FIX_I= (0,4) +FFD_FIX_J= (15) +FFD_FIX_K= (15) +% +GEO_MARKER= ( airfoil_upper, airfoil_lower ) +GEO_DESCRIPTION= AIRFOIL +% +MESH_FILENAME= mesh_NACA0012_multiFFD.su2 +MESH_FORMAT= SU2 +HISTORY_OUTPUT= (ITER, RMS_RES, AERO_COEFF) +OUTPUT_FILES= (RESTART_ASCII) +% +OPT_OBJECTIVE= DRAG * 0.001 +OPT_CONSTRAINT= ( LIFT > 0.327 ) * 0.001; ( MOMENT_Z > 0.0 ) * 0.001; ( AIRFOIL_THICKNESS > 0.12 ) * 0.001 +OPT_ITERATIONS= 1 +OPT_ACCURACY= 1E-6 +OPT_BOUND_UPPER= 0.1 +OPT_BOUND_LOWER= -0.1 +% This test uses the 3D kind 11 (FFD_CONTROL_POINT) on a 2D mesh. +% The 2D tutorials use kind 19 (FFD_CONTROL_POINT_2D). +DEFINITION_DV= ( 11, 1.0 | airfoil_upper | UPPER, 1, 0, 0, 0.0, 1.0, 0.0 ); ( 11, 1.0 | airfoil_lower | LOWER, 1, 0, 0, 0.0, 1.0, 0.0 ) +``` + +Run the gradient only: + +``` +discrete_adjoint.py -f inv_NACA0012_ffd.cfg +``` + +Run an optimization (raise `OPT_ITERATIONS` first): + +``` +shape_optimization.py -g DISCRETE_ADJOINT -f inv_NACA0012_ffd.cfg +``` + +For a RANS case, start from the [RAE 2822 tutorial](/tutorials/Turbulent_2D_Constrained_RAE2822/) or the test case [optimization_rans/steady_rae2822](https://github.com/su2code/SU2/blob/develop/TestCases/optimization_rans/steady_rae2822/turb_SA_RAE2822.cfg). For a 3D wing, start from the [ONERA M6 tutorial](/tutorials/Inviscid_3D_Constrained_ONERAM6/). + +## Settings that matter + +### Build SU2 with AD + +- Configure with `./meson.py setup build -Denable-autodiff=true` (code). See [Build SU2 on Linux/MacOS](../Build-SU2-Linux-MacOS/). +- This build gives the AD programs `SU2_CFD_AD` and `SU2_DOT_AD`, next to the normal `SU2_CFD`, `SU2_DEF`, `SU2_DOT` and `SU2_GEO` (tutorial). The optimization loop needs all of them. +- `SU2_CFD` stops with "MATH_PROBLEM= DISCRETE_ADJOINT requires AD support" if you give it a discrete adjoint config (code). Use `SU2_CFD_AD` for the adjoint run. +- The Python scripts need NumPy and SciPy (tutorial). +- The CoolProp fluid models cannot be used with the AD build (code). +- To check gradients with forward-mode AD, also build with `-Denable-directdiff=true` (code). + +### Discrete or continuous adjoint + +- `MATH_PROBLEM` takes `DIRECT`, `CONTINUOUS_ADJOINT` or `DISCRETE_ADJOINT` (code). +- With the Python scripts, keep `MATH_PROBLEM= DIRECT` in your file. The scripts set the adjoint value themselves, from the gradient method you choose on the command line (code). +- To run by hand: run `SU2_CFD` for the flow, and copy the restart file to the name in `SOLUTION_FILENAME`. Then run `SU2_CFD_AD` with `MATH_PROBLEM= DISCRETE_ADJOINT`. Then run `SU2_DOT_AD`, which turns the surface sensitivities into the gradient for the design variables (tutorial, to be reviewed: check the file names against the scripts). +- The discrete adjoint uses the numerical settings of the flow solver. It ignores the continuous adjoint options, such as `CONV_NUM_METHOD_ADJFLOW`, `ADJ_JST_SENSOR_COEFF`, `CFL_REDUCTION_ADJFLOW` and `LIMIT_ADJFLOW` (tutorial). `INCONSISTENT_DISC= YES` (default `NO`) makes the discrete adjoint use the adjoint scheme options `CONV_NUM_METHOD_ADJFLOW` and `ADJ_JST_SENSOR_COEFF` instead (code). The tutorial text calls this switch `INCONSISTENT_AD`. +- `FROZEN_VISC_DISC` (default `NO`) freezes the turbulence model in the adjoint. `FROZEN_LIMITER_DISC` (default `NO`) freezes the slope limiter (code). These differentiate a frozen model or limiter rather than the fully coupled, recomputed residual. For a gradient comparison, make the derivative definition and frozen settings agree on both sides; otherwise disagreement is expected (advice). +- `QUASI_NEWTON_NUM_SAMPLES` above 1 adds a quasi-Newton correction to the adjoint iterations. The default is 0 (off) (code). It can speed up the adjoint convergence (to be reviewed). + +### Objective function + +- `OBJECTIVE_FUNCTION` sets the output to differentiate. `MARKER_MONITORING` sets the surfaces where SU2 evaluates it (code). Examples of values: `DRAG`, `LIFT`, `MOMENT_Z`, `EFFICIENCY`, `TOTAL_HEATFLUX`, `SURFACE_TOTAL_PRESSURE`, `SURFACE_PRESSURE_DROP`, `SURFACE_UNIFORMITY`, `TOTAL_PRESSURE_LOSS`, `ENTROPY_GENERATION`, `CUSTOM_OBJFUNC` (code). The full list is on the [option reference](../Option-Reference/) page. +- The `SURFACE_*` objectives use the markers in `MARKER_ANALYZE`. List the same marker in `MARKER_MONITORING` too (tutorial). +- **Weighted sum.** Give several objectives separated by commas, with `OBJECTIVE_WEIGHT` and `MARKER_MONITORING` in the same order (code). See the [multi-objective tutorial](/tutorials/Multi_Objective_Shape_Design/). +- **Custom expression.** With `OBJECTIVE_FUNCTION= CUSTOM_OBJFUNC`, `CUSTOM_OBJFUNC` holds a formula of history outputs, for example `'DRAG + 10 * pow(fmax(0.4-LIFT, 0), 2)'` (code). +- **In the Python scripts**, `OPT_OBJECTIVE` sets the objective and its scale, for example `DRAG * 0.001` (tutorial). Separate several objectives with semicolons. With `OPT_COMBINE_OBJECTIVE= YES`, SU2 solves one adjoint for the weighted sum, instead of one per objective (tutorial). +- **Fixed lift.** To minimize drag at a given lift, use `FIXED_CL_MODE= YES` with `TARGET_CL`: the flow solver then changes the angle of attack. The adjoint gives the drag gradient at fixed lift, so you need no lift constraint and no extra adjoint for it (tutorial). + +### Constraints + +- `OPT_CONSTRAINT` lists constraints separated by semicolons, in the form `( NAME > value ) * scale`, with `>`, `<` or `=` (tutorial). +- Each flow constraint (for example `LIFT`) needs its own adjoint solution (tutorial). +- Geometric constraints come from SU2_GEO: `AIRFOIL_THICKNESS` for airfoils, `STATION1_THICKNESS`, `STATION2_THICKNESS`, ... for wings (tutorial). Set `GEO_MARKER`, `GEO_DESCRIPTION` (`AIRFOIL`, `WING`, `FUSELAGE` or `NACELLE`) and, for wings, `GEO_LOCATION_STATIONS` and `GEO_BOUNDS` (code, tutorial). Run `SU2_GEO` once on the baseline to check the values (tutorial). +- **Penalty.** You can also write a constraint inside `OPT_OBJECTIVE`, for example `(DRAG = 0.05)*1E6`. SU2 then adds a quadratic penalty when the constraint is violated (tutorial). +- The scale of each constraint sets how strongly the optimizer reacts when the constraint is violated. The tutorials use 0.001 (tutorial). + +### Design variables + +`DEFINITION_DV` lists the design variables for the Python scripts. Each one has the form `( kind, scale | markers | parameters )`. Separate them with semicolons, with no semicolon after the last one (tutorial). The kind is a number (code): + +| Number | Kind | Parameters | +|---|---|---| +| 1 | `TRANSLATION` | x, y, z | +| 11 | `FFD_CONTROL_POINT` | box tag, i, j, k, x, y, z direction | +| 14 | `FFD_CAMBER` | box tag, i, j | +| 15 | `FFD_TWIST` | box tag, j, axis end points | +| 16 | `FFD_THICKNESS` | box tag, i, j | +| 19 | `FFD_CONTROL_POINT_2D` | box tag, i, j, x, y direction | +| 20 | `FFD_CAMBER_2D` | box tag, i | +| 21 | `FFD_THICKNESS_2D` | box tag, i | +| 30 | `HICKS_HENNE` | lower (0) or upper (1) side, x position on a unit chord | +| 34 | `CST` | see the test case [deformation/cst](https://github.com/su2code/SU2/tree/develop/TestCases/deformation/cst) | +| 35 | `SURFACE_BUMP` | x start, x end, x location of the bump | +| 101 | `ANGLE_OF_ATTACK` | 1.0 | + +These points come from the tutorials (tutorial): + +- Hicks-Henne bumps (kind 30) are simple for 2D airfoils. FFD control points (kinds 11 and 19) work for any shape, in 2D and 3D. +- `set_ffd_design_var.py` writes the `DEFINITION_DV` list for all control points of a box, for example `set_ffd_design_var.py -i 10 -j 8 -k 1 -b WING -m 'UPPER_SIDE, LOWER_SIDE, TIP'`. Add `--dimension 2` in 2D. Remove the points that should not move. +- `DV_KIND`, `DV_MARKER`, `DV_PARAM` and `DV_VALUE` define one deformation for `SU2_DEF` alone, for example to test a mesh deformation by hand. + +### FFD boxes + +FFD (free-form deformation) puts a box of control points around the surface. Moving a control point bends the surface inside the box smoothly (tutorial). + +- `FFD_DEFINITION` = (tag, then the 8 corner points x, y, z) in 3D. In 2D, give 4 corners with z = 0, and fill the other 12 values with zeros (tutorial). Start at the corner with the lowest x, y, z. Go along x, then along y, then to the remaining corner of that face. In 3D, repeat for the top face (tutorial). +- `FFD_DEGREE` = (i, j, k) degrees. The box has degree + 1 control points in each direction. In 2D, use (i, j, 0) (tutorial). +- Several boxes: separate them with semicolons in `FFD_DEFINITION` and `FFD_DEGREE` (test case). +- `FFD_CONTINUITY` keeps the surface smooth where it leaves the box: `2ND_DERIVATIVE` (default), `1ST_DERIVATIVE`, `NO_DERIVATIVE`, or `USER_INPUT` (code). With `USER_INPUT`, you choose the fixed planes of control points with `FFD_FIX_I`, `FFD_FIX_J` and `FFD_FIX_K`. A plane index larger than the degree fixes nothing (tutorial, test case). +- Other options: `FFD_BLENDING` (`BEZIER` default, or `BSPLINE_UNIFORM` with `FFD_BSPLINE_ORDER`), `FFD_COORD_SYSTEM` (`CARTESIAN` default, `CYLINDRICAL`, `SPHERICAL`, `POLAR`, with `FFD_AXIS`), `FFD_SYMMETRY_PLANE` (default `NO`) (code). +- `FFD_TOLERANCE` (default 1E-10) and `FFD_ITERATIONS` (default 500) control how SU2 finds the position of each surface point inside the box (code). +- `FFD_INTPREV= YES` (default `NO`) checks the box for self-intersection after a deformation. If SU2 finds one, it reduces the deformation step by step (`FFD_INTPREV_ITER`, default 10; `FFD_INTPREV_DEPTH`, default 3) (code). + +To add the boxes to your mesh (tutorial): + +1. Set `DV_KIND= FFD_SETTING`, `DV_PARAM= ( 1.0 )` and `DV_MARKER` to the surfaces to deform. +2. Run `SU2_DEF config.cfg`. +3. SU2_DEF writes the mesh with the boxes to the file in `MESH_OUT_FILENAME` (default `mesh_out`). Use that file as `MESH_FILENAME` from now on. + +The box moves only the surface points that lie inside it (tutorial). Make the box enclose the whole region that should change (advice). + +### Mesh deformation + +After the surface moves, `SU2_DEF` moves the volume mesh by treating it as an elastic solid (tutorial). + +- `DEFORM_STIFFNESS_TYPE`: `WALL_DISTANCE` (default), `INVERSE_VOLUME` or `CONSTANT_STIFFNESS` (code). `WALL_DISTANCE` stiffens elements near a wall; `INVERSE_VOLUME` stiffens small elements wherever they occur. These can help preserve boundary-layer cells, but do not guarantee positive volumes (code, advice). +- `DEFORM_LINEAR_SOLVER` (default `FGMRES`), `DEFORM_LINEAR_SOLVER_PREC` (default `ILU`), `DEFORM_LINEAR_SOLVER_ITER` (default 1000), `DEFORM_LINEAR_SOLVER_ERROR` (default 1E-14) (code). +- `DEFORM_NONLINEAR_ITER` (default 1) splits the deformation into this many smaller steps (code). More steps help with large deformations (advice, to be reviewed). +- `DEFORM_LIMIT` (default 1E6) deforms only the cells closer to the wall than this distance (code). +- With the default legacy `SU2_DEF` path (`DEFORM_MESH= NO`), `CLinearElasticity` uses `DEFORM_COEFF` as its Poisson ratio. The parser default is 1E6, outside the physical isotropic-elastic interval −1 < ν < 0.5; do not interpret that default as a material recommendation. The [species transport tutorial](/tutorials/Species_Transport/) sets 0.0. With `DEFORM_MESH= YES`, `SU2_DEF` instead uses `CMeshSolver`, whose Poisson ratio is `DEFORM_POISSONS_RATIO` (default 0.3). These options belong to different deformation paths (code). +- `DEFORM_KIND= RBF` uses radial basis functions instead of the elastic solid (default `ELASTIC`) (code). See the test case [deformation/naca0012](https://github.com/su2code/SU2/blob/develop/TestCases/deformation/naca0012/def_NACA0012_rbf.cfg) (test case). +- Boundaries that are not in `DV_MARKER` stay fixed. Points on `MARKER_SYM` boundaries can slide in their plane. If a separate deformation configuration uses `MARKER_SYM` to allow a planar end boundary to slide, retain the actual inlet/outlet conditions in the flow configuration. Changing a flow outlet into a symmetry boundary changes the physical problem (advice). +- `HOLD_GRID_FIXED= YES` with `HOLD_GRID_FIXED_COORD` keeps the mesh outside a box fixed (code). +- Set `DEFORM_CONSOLE_OUTPUT= YES` to see the minimum cell volume after each step (code). + +`DEFORM_MESH` also selects the newer mesh-solver path in `SU2_DEF`; it is not exclusive to `SU2_CFD`. In a flow run, use `DEFORM_MESH` and `MARKER_DEFORM_MESH` for deforming moving boundaries. The Python shape-optimization workflow calls `SU2_DEF` (code). + +### Python scripts + +All scripts are in `SU2_PY`. They take the config file with `-f` and the number of MPI ranks with `-n` (code). See also [Execution](../Execution/). + +- `shape_optimization.py`: the full loop of flow, adjoint, gradient, deformation and optimizer (tutorial). Its arguments (code): + - `-g`: the gradient method, `DISCRETE_ADJOINT` (default), `CONTINUOUS_ADJOINT`, `FINDIFF` or `NONE`. + - `-o`: the optimizer from SciPy, `SLSQP` (default), `CG`, `BFGS` or `POWELL`. + - `-q`: quiet mode, default `True`. + - Each design is written to `DESIGNS/DSN_001`, `DSN_002`, ... The history of the optimization is in the `history_project` file (tutorial). +- `discrete_adjoint.py`: one flow solution, one adjoint solution and the gradient. `-m adj` reuses an existing flow solution; `-m grad` reuses both solutions (code). +- `continuous_adjoint.py`: the same with the continuous adjoint (code). +- `finite_differences.py`: the gradient by finite differences, with one flow solution per design variable (code). +- `set_ffd_design_var.py`: writes `DEFINITION_DV` lists for FFD boxes (tutorial). + +Optimizer settings (tutorial): + +- `OPT_ITERATIONS`, `OPT_ACCURACY`: the maximum number of iterations and the requested accuracy. +- `OPT_BOUND_UPPER`, `OPT_BOUND_LOWER`: the bounds of each design variable. The script divides them by `OPT_RELAX_FACTOR` before it passes them to the optimizer (code). +- `OPT_GRADIENT_FACTOR`: scales objective and gradient. The tutorials aim at a gradient norm near 1E-6 for SLSQP (the GNORM column of the optimizer output). +- `OPT_RELAX_FACTOR`: scales the first step. Check the size of the first deformation in `DESIGNS/DSN_002/DEFORM/log_Deform.out` (the `Max Diff` line in the ONERA M6 tutorial). +- `OPT_LINE_SEARCH_BOUND` (default 1E6) bounds the line search in SU2_DEF (code). + +**FADO.** The tutorials [Species Transport](/tutorials/Species_Transport/) and [Turbulent 3D pipe bend](/tutorials/Inc_Turbulent_Bend_Opt/) use [FADO](https://github.com/su2code/FADO), a separate Python framework, instead of `shape_optimization.py` (tutorial). FADO gives more control over the steps and over the optimizer. The Species Transport tutorial shows a full workflow: restart check, FFD setup, mesh deformation test, gradient check, optimization (tutorial). + +## Check convergence and results + +**Converge the flow first.** The adjoint linearizes the flow around the current solution. A poorly converged flow gives a wrong gradient (advice). Set `CONV_RESIDUAL_MINVAL` low, and check that the objective no longer changes. + +**Converge the adjoint.** With the compressible solver, the adjoint run stops on `RMS_ADJ_DENSITY` by default (code). Watch it, and the sensitivity outputs (`SENS_GEO`, `SENS_AOA`, `SENS_MACH`) in the adjoint history (code). The sensitivities should settle to steady values (advice). + +**Check the restart.** Before a gradient check, verify that a flow restart and an adjoint restart reproduce the residuals of a continuous run. The [Species Transport tutorial](/tutorials/Species_Transport/) shows a script for this (tutorial). + +**Check the gradient against finite differences** before you optimize (tutorial): + +1. Run `discrete_adjoint.py -f config.cfg`. The gradient is in a file named after `GRAD_OBJFUNC_FILENAME` (default `of_grad`) plus a short name of the objective, for example `of_grad_cd.csv` for `DRAG`. The extension follows `TABULAR_FORMAT` (code). +2. Run `finite_differences.py -f config.cfg`. The gradient is in `of_grad_findiff`, with the same extension. The step comes from `FIN_DIFF_STEP`; the script uses 0.001 when the option is missing. The template suggests 0.001 times `REF_LENGTH` (code). +3. Compare the two files, design variable by design variable. Signs and orders of magnitude must agree. Try two or three step sizes: a step that is too large adds truncation error, and a step that is too small adds noise from the incomplete convergence (advice). + +`discrete_adjoint.py` accepts `-v True`, but the forward-mode AD calculation and comparison report in `discrete_design` are commented out in this version. That flag does not validate the gradient. Use the finite-difference workflow above; a forward-mode comparison needs a separately verified driver (code). + +**Check each new design.** Look at the deformed meshes in `DESIGNS/DSN_*/DEFORM`, the flow solutions in `DESIGNS/DSN_*/DIRECT`, and the history in `history_project` (tutorial). + +## Common problems + +| Symptom | Likely cause | What to try | +|---|---|---| +| SU2 stops: "MATH_PROBLEM= DISCRETE_ADJOINT requires AD support". | The adjoint config was given to `SU2_CFD` (code). | Use `SU2_CFD_AD`, or let the Python scripts call it. Build with `-Denable-autodiff=true`. | +| The gradient differs from finite differences. | The flow or the adjoint is not converged; the finite difference step is too large or too small; the turbulence or the limiter is frozen (advice). | Converge both deeper. Try several `FIN_DIFF_STEP` values. Set `FROZEN_VISC_DISC= NO` and `FROZEN_LIMITER_DISC= NO`. | +| The adjoint diverges or stalls. | The flow solution oscillates (limiter, shock, separation), so the adjoint iterations have no steady solution to converge to (advice, to be reviewed). | Converge the flow deeper. Freeze the limiter in the flow with `LIMITER_ITER`. Try `FROZEN_LIMITER_DISC= YES` or `QUASI_NEWTON_NUM_SAMPLES` (to be reviewed). | +| The flow does not converge on a new design. | The step was too large, or the shape became unphysical (advice). | Lower `OPT_RELAX_FACTOR` or the bounds. Restart the optimization from its project file with `-r` (to be reviewed). | +| SU2_DEF reports: "There are N elements with negative volume". | The deformation is too large for the mesh (code). | Lower the step (`OPT_RELAX_FACTOR`, bounds). Raise `DEFORM_NONLINEAR_ITER`. Try another `DEFORM_STIFFNESS_TYPE` or `DEFORM_KIND= RBF`. `FFD_INTPREV= YES` checks FFD-box intersections; it does not guarantee a valid volume mesh (code, advice). | +| The mesh is torn at an outlet or a side boundary. | That boundary is fixed while its neighbour moves (tutorial). | Allow planar sliding in a separate deformation configuration where appropriate; preserve the physical inlet/outlet types in the flow configuration. | +| Kinks at the edge of the FFD box. | Control points on the box faces move (tutorial). | Use `FFD_CONTINUITY= 2ND_DERIVATIVE`, or fix the outer planes with `FFD_FIX_I`, `FFD_FIX_J`, `FFD_FIX_K`. | +| Part of the surface does not move. | It lies outside the FFD box (tutorial). | Enlarge the box and run the `FFD_SETTING` step again. | +| The FFD point inversion does not converge. | The box is badly shaped, or points sit near its faces (advice, to be reviewed). | Raise `FFD_ITERATIONS`. Make the box larger and closer to a regular hexahedron. | +| The optimizer stops after one step. | The gradient norm is far from the scale that the optimizer expects (tutorial). | Change `OPT_GRADIENT_FACTOR` so that GNORM is near 1E-6. | +| The thickness constraint has no value. | `GEO_MARKER` or `GEO_DESCRIPTION` is missing (test case). | Set them, and run `SU2_GEO` on the baseline. | + +## Related tutorials and test cases + +Tutorials: + +- [Unconstrained shape design of a transonic inviscid airfoil](/tutorials/Inviscid_2D_Unconstrained_NACA0012/): Hicks-Henne bumps, `shape_optimization.py`. +- [Constrained shape design of a transonic inviscid wing](/tutorials/Inviscid_3D_Constrained_ONERAM6/): FFD boxes, SU2_GEO thickness constraints, fixed lift. +- [Constrained shape design of a transonic turbulent airfoil](/tutorials/Turbulent_2D_Constrained_RAE2822/): RANS discrete adjoint, moment and thickness constraints. +- [Shape design with multiple objectives and penalty functions](/tutorials/Multi_Objective_Shape_Design/): weighted objectives, `OPT_COMBINE_OBJECTIVE`, penalties. +- [Unconstrained shape design of a two way mixing channel](/tutorials/Species_Transport/): FADO, FFD setup, gradient check. +- [Adjoint design optimization of a turbulent 3D pipe bend](/tutorials/Inc_Turbulent_Bend_Opt/): FADO, incompressible RANS. +- [Unsteady shape optimization NACA0012](/tutorials/Unsteady_Shape_Opt_NACA0012/): unsteady discrete adjoint. + +Test cases (SU2 repository): + +- [multiple_ffd/naca0012](https://github.com/su2code/SU2/blob/develop/TestCases/multiple_ffd/naca0012/inv_NACA0012_ffd.cfg): two FFD boxes, `discrete_adjoint.py`. +- [optimization_euler/steady_naca0012](https://github.com/su2code/SU2/blob/develop/TestCases/optimization_euler/steady_naca0012/inv_NACA0012_adv.cfg): `shape_optimization.py` with the continuous adjoint. +- [optimization_rans/steady_rae2822](https://github.com/su2code/SU2/blob/develop/TestCases/optimization_rans/steady_rae2822/turb_SA_RAE2822.cfg): RANS airfoil with constraints. +- [optimization_rans/naca0012](https://github.com/su2code/SU2/blob/develop/TestCases/optimization_rans/naca0012/naca0012.cfg): unsteady RANS, `shape_optimization.py` restarted from a solution. +- [disc_adj_euler](https://github.com/su2code/SU2/tree/develop/TestCases/disc_adj_euler) and [disc_adj_rans](https://github.com/su2code/SU2/tree/develop/TestCases/disc_adj_rans): discrete adjoint runs. +- [disc_adj_turbomachinery](https://github.com/su2code/SU2/tree/develop/TestCases/disc_adj_turbomachinery): adjoint of turbomachinery objectives. +- [deformation](https://github.com/su2code/SU2/tree/develop/TestCases/deformation): SU2_DEF with many kinds of design variables. + +User guide pages: [Build SU2 on Linux/MacOS](../Build-SU2-Linux-MacOS/), [Execution](../Execution/), [Advanced AD Techniques](../Advanced-AD-Techniques/), [Solver Setup](../Solver-Setup/), [Setup Guide: Turbomachinery](../Setup-Guide-Turbomachinery/). + +Source review: 22 October 2026, against [SU2 `docs_site` at `41ea6a219a`](https://github.com/rois1995/SU2/tree/41ea6a219ac038574f3d4a5b130c0c1d8af66457). See the [review scope and outstanding validation](../Documentation-Status/#guide-and-model-review). Setup recommendations remain draft where indicated. diff --git a/_docs_v7/Setup-Guide-Species-Combustion.md b/_docs_v7/Setup-Guide-Species-Combustion.md new file mode 100644 index 00000000..966928e1 --- /dev/null +++ b/_docs_v7/Setup-Guide-Species-Combustion.md @@ -0,0 +1,407 @@ +--- +title: "Setup Guide: Species Transport and Combustion" +permalink: /docs_v7/Setup-Guide-Species-Combustion/ +--- + +{% include setup-guide-intro.md %} + +--- + +- [When to use this guide](#when-to-use-this-guide) +- [Start from](#start-from) +- [Settings that matter](#settings-that-matter) +- [Check convergence and results](#check-convergence-and-results) +- [Common problems](#common-problems) +- [Related tutorials and test cases](#related-tutorials-and-test-cases) + +--- + +## When to use this guide + +Use this guide when the flow carries more than one chemical species, or a flame: + +- **Species transport**: mixing of gases, or a pollutant in air, without reactions. SU2 transports the mass fraction of each species: the mass of that species divided by the total mass. +- **Flamelet model** (FGM, flamelet-generated manifold): laminar premixed, partially premixed and diffusion flames. SU2 transports a few controlling variables. It reads the gas properties and the reaction rates from a table computed beforehand. + +`KIND_SCALAR_MODEL` selects one of the two. Both run on top of the flow solver, so read [Setup Guide: Incompressible Flows](../Setup-Guide-Incompressible/) first. +For flames next to solid walls that conduct heat, also read [Setup Guide: Heat Transfer and Conjugate Heat Transfer](../Setup-Guide-Heat-Transfer-CHT/). + +Every option is listed in the [option reference](../Option-Reference/). +Every output field is listed in the [output fields reference](../Output-Fields-Reference/). + +## Start from + +### Species transport: two gas streams mixing + +This config mixes two gas streams in a 2D venturi, with the SST turbulence model. +The mixture density depends on the composition (`FLUID_MIXTURE`). +It is the test case [`species_transport/venturi_primitive_3species/species2_primitiveVenturi_mixingmodel.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/species_transport/venturi_primitive_3species/species2_primitiveVenturi_mixingmodel.cfg) with fewer options. +One change from the test case: here `CONV_FIELD` uses `RMS_SPECIES_0`. The test case lists `RMS_SPECIES`, which is not an output field, so SU2 ignores it. +The mesh `primitiveVenturi.su2` is in the same folder of the [TestCases repository](https://github.com/su2code/TestCases). + +``` +% ------------- Problem -------------% +SOLVER= INC_RANS +KIND_TURB_MODEL= SST +% +% ------------- Flow and mixture -------------% +INC_DENSITY_MODEL= VARIABLE +INC_ENERGY_EQUATION= YES +INC_DENSITY_INIT= 1.1766 +INC_VELOCITY_INIT= ( 1.00, 0.0, 0.0 ) +INC_TEMPERATURE_INIT= 300.0 +INC_NONDIM= DIMENSIONAL +FLUID_MODEL= FLUID_MIXTURE +THERMODYNAMIC_PRESSURE= 101325.0 +MOLECULAR_WEIGHT= 28.96, 16.043 +SPECIFIC_HEAT_CP= 1009.39, 1009.39 +CONDUCTIVITY_MODEL= CONSTANT_CONDUCTIVITY +THERMAL_CONDUCTIVITY_CONSTANT= 0.0357, 0.0357 +PRANDTL_LAM= 0.72, 0.72 +TURBULENT_CONDUCTIVITY_MODEL= NONE +PRANDTL_TURB= 0.90, 0.90 +VISCOSITY_MODEL= CONSTANT_VISCOSITY +MU_CONSTANT= 1.716E-5, 1.716E-5 +% +% ------------- Species -------------% +KIND_SCALAR_MODEL= SPECIES_TRANSPORT +DIFFUSIVITY_MODEL= CONSTANT_DIFFUSIVITY +DIFFUSIVITY_CONSTANT= 0.001 +SPECIES_INIT= 1.0 +SPECIES_CLIPPING= YES +SPECIES_CLIPPING_MIN= 0.0 +SPECIES_CLIPPING_MAX= 1.0 +% +% ------------- Boundary conditions -------------% +MARKER_HEATFLUX= ( wall, 0.0 ) +MARKER_SYM= ( axis ) +INC_INLET_TYPE= VELOCITY_INLET, VELOCITY_INLET +MARKER_INLET= ( gas_inlet, 300, 1.0, 1.0, 0.0, 0.0, air_axial_inlet, 300, 1.0, 0.0, -1.0, 0.0 ) +MARKER_INLET_SPECIES= ( gas_inlet, 1.0, air_axial_inlet, 0.6 ) +INC_OUTLET_TYPE= PRESSURE_OUTLET +MARKER_OUTLET= ( outlet, 0.0 ) +MARKER_ANALYZE= ( outlet, gas_inlet, air_axial_inlet ) +% +% ------------- Numerics -------------% +NUM_METHOD_GRAD= WEIGHTED_LEAST_SQUARES +CFL_NUMBER= 60 +CONV_NUM_METHOD_FLOW= FDS +MUSCL_FLOW= YES +SLOPE_LIMITER_FLOW= NONE +TIME_DISCRE_FLOW= EULER_IMPLICIT +CONV_NUM_METHOD_TURB= SCALAR_UPWIND +MUSCL_TURB= NO +CFL_REDUCTION_TURB= 1.0 +CONV_NUM_METHOD_SPECIES= SCALAR_UPWIND +MUSCL_SPECIES= NO +SLOPE_LIMITER_SPECIES= NONE +TIME_DISCRE_SPECIES= EULER_IMPLICIT +CFL_REDUCTION_SPECIES= 1.0 +LINEAR_SOLVER= FGMRES +LINEAR_SOLVER_PREC= ILU +LINEAR_SOLVER_ERROR= 1E-8 +LINEAR_SOLVER_ITER= 5 +% +% ------------- Convergence and output -------------% +ITER= 1000 +CONV_FIELD= RMS_PRESSURE, RMS_VELOCITY-X, RMS_VELOCITY-Y, RMS_TKE, RMS_SPECIES_0 +CONV_RESIDUAL_MINVAL= -18 +CONV_STARTITER= 10 +MESH_FILENAME= primitiveVenturi.su2 +SCREEN_OUTPUT= INNER_ITER, RMS_PRESSURE, RMS_VELOCITY-X, RMS_TKE, RMS_SPECIES_0, SURFACE_SPECIES_VARIANCE +HISTORY_OUTPUT= RMS_RES, FLOW_COEFF, LINSOL, SPECIES_COEFF, SPECIES_COEFF_SURF +VOLUME_OUTPUT= RESIDUAL, PRIMITIVE +``` + +With two species, SU2 solves one species equation. The first value of each property list belongs to species 0, the one SU2 solves for. The last species fills the rest of the mass (code). + +### Flamelet: laminar premixed methane flame + +This config is a laminar premixed methane flame on a burner, with a wall at 450 K. +It is the test case [`flamelet/01_laminar_premixed_ch4_flame_cfd/lam_prem_ch4_cfd.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/flamelet/01_laminar_premixed_ch4_flame_cfd/lam_prem_ch4_cfd.cfg) with fewer options. +The mesh `mesh_structured.cgns` and the table `fgm_ch4.drg` are in the same folder of the [TestCases repository](https://github.com/su2code/TestCases). + +Changes to the test case: the test restarts from a converged solution, with `RESTART_SOL= YES` and `FLAME_INIT_METHOD= NONE`. +Here the run starts from scratch, so `RESTART_SOL= NO` and `FLAME_INIT_METHOD= FLAME_FRONT`, with the `FLAME_INIT` values of the test case. The regression tests do not run this combination (to be reviewed). + +``` +% ------------- Problem -------------% +SOLVER= INC_NAVIER_STOKES +KIND_TURB_MODEL= NONE +RESTART_SOL= NO +% +% ------------- Flow and flamelet fluid model -------------% +INC_DENSITY_MODEL= FLAMELET +INC_DENSITY_INIT= 1.00 +INC_VELOCITY_INIT= ( 0.5, 0.0, 0.0 ) +INC_TEMPERATURE_INIT= 300.0 +INC_NONDIM= DIMENSIONAL +FLUID_MODEL= FLUID_FLAMELET +KIND_SCALAR_MODEL= FLAMELET +DIFFUSIVITY_MODEL= FLAMELET +VISCOSITY_MODEL= FLAMELET +CONDUCTIVITY_MODEL= FLAMELET +% +% ------------- Manifold -------------% +FILENAMES_INTERPOLATOR= (fgm_ch4.drg) +CONTROLLING_VARIABLE_NAMES= (ProgressVariable, EnthalpyTot) +CONTROLLING_VARIABLE_SOURCE_NAMES= (ProdRateTot_PV, NULL) +USER_SCALAR_NAMES= (CO, NOx) +USER_SOURCE_NAMES= (ProdRatePos_Y-CO, ProdRateNegScaled_Y-CO, ProdRateTot_Y-NOx, NULL) +LOOKUP_NAMES= (MolarWeightMix, Conductivity, Cp, HeatRelease, Diffusivity) +% +% ------------- Initial state and ignition -------------% +SPECIES_INIT= (0.0, -210000, 0.0, 0.0) +FLAME_INIT_METHOD= FLAME_FRONT +FLAME_INIT= (0.0032, 0.00, 0.00, 1.0, 0.1, 0.0, 1.0e-3, 0.1) +% +% ------------- Boundary conditions -------------% +INC_INLET_TYPE= VELOCITY_INLET +MARKER_INLET= (inlet, 300.0, 0.20, 1.0, 0.0, 0.0) +MARKER_INLET_SPECIES= (inlet, 0, -193600.0, 0.0, 0.0) +INC_OUTLET_TYPE= PRESSURE_OUTLET +MARKER_OUTLET= (outlet, 0.0) +MARKER_ISOTHERMAL= (wall, 450) +MARKER_SYM= (symmetry, symmetry_2-part-fluid) +MARKER_SPECIES_STRONG_BC= (inlet, outlet, wall) +MARKER_ANALYZE= (inlet, outlet) +% +% ------------- Numerics -------------% +NUM_METHOD_GRAD= WEIGHTED_LEAST_SQUARES +CONV_NUM_METHOD_FLOW= FDS +MUSCL_FLOW= YES +SLOPE_LIMITER_FLOW= NONE +TIME_DISCRE_FLOW= EULER_IMPLICIT +CONV_NUM_METHOD_SPECIES= BOUNDED_SCALAR +MUSCL_SPECIES= YES +SLOPE_LIMITER_SPECIES= NONE +TIME_DISCRE_SPECIES= EULER_IMPLICIT +CFL_NUMBER= 100 +CFL_ADAPT= YES +CFL_ADAPT_PARAM= ( 0.95, 1.01, 10.0, 1000, 0.01, 0 ) +MGLEVEL= 0 +LINEAR_SOLVER= FGMRES +LINEAR_SOLVER_PREC= ILU +LINEAR_SOLVER_ERROR= 1E-03 +LINEAR_SOLVER_ITER= 10 +% +% ------------- Convergence and output -------------% +ITER= 10000 +CONV_FIELD= RMS_PRESSURE +CONV_RESIDUAL_MINVAL= -15 +MESH_FILENAME= mesh_structured.cgns +MESH_FORMAT= CGNS +SCREEN_OUTPUT= INNER_ITER, RMS_VELOCITY-X, RMS_PRESSURE, RMS_ProgressVariable, RMS_EnthalpyTot, RMS_CO, RMS_NOx +VOLUME_OUTPUT= SOLUTION, PRIMITIVE, SOURCE, LOOKUP +``` + +With the default `FLAME_ENTHALPY_BC= FLOW_MARKERS`, SU2 does not use the enthalpy value −193600 in `MARKER_INLET_SPECIES`. It computes the inlet enthalpy from the 300 K of `MARKER_INLET` instead. In the same way, it replaces the initial enthalpy of `SPECIES_INIT` with the value at `INC_TEMPERATURE_INIT` (code). + +## Settings that matter + +### Choose the scalar model + +`KIND_SCALAR_MODEL` takes these values (code): + +- `NONE` (default): no species. +- `SPECIES_TRANSPORT`: transport of N species mass fractions. It works with `INC_NAVIER_STOKES`, `INC_RANS`, `NAVIER_STOKES` and `RANS`. +- `FLAMELET`: the flamelet model. All tutorials and test cases use it with `INC_NAVIER_STOKES`. + +### Number of species and list lengths + +For N species, SU2 solves N−1 transport equations. The last mass fraction is 1 minus the sum of the others ([Theory](../Theory/#species-transport)). + +SU2 counts the equations from `SPECIES_INIT`. These lists need exactly one value per equation (code): + +- `SPECIES_INIT`, +- `SPECIES_CLIPPING_MIN` and `SPECIES_CLIPPING_MAX` (when clipping is on), +- the values after each marker in `MARKER_INLET_SPECIES` and `MARKER_WALL_SPECIES`. + +With `FLUID_MODEL= FLUID_MIXTURE`, these lists need one value per species, that is N values, including the last species (code): + +- `MOLECULAR_WEIGHT` and `SPECIFIC_HEAT_CP`, +- `MU_CONSTANT` (or `MU_REF`, `MU_T_REF`, `SUTHERLAND_CONSTANT` for Sutherland's law), +- `THERMAL_CONDUCTIVITY_CONSTANT` or `PRANDTL_LAM`, depending on `CONDUCTIVITY_MODEL`, +- `PRANDTL_TURB` with `TURBULENT_CONDUCTIVITY_MODEL= CONSTANT_PRANDTL_TURB`, +- `CONSTANT_LEWIS_NUMBER` with `DIFFUSIVITY_MODEL= CONSTANT_LEWIS`. + +SU2 checks that each mass fraction in `SPECIES_INIT` and `MARKER_INLET_SPECIES`, and their sum, lies between 0 and 1. If not, it prints a message but does not stop (code). Read the start-up output. + +### Passive scalar or active mixture + +- **Passive scalar** (the species does not change the flow, for example a dilute pollutant): use `INC_DENSITY_MODEL= CONSTANT`. The flow properties are those of a single fluid. Example: [`passive_transport.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/species_transport/passive_transport_validation/passive_transport.cfg) (test case). +- **Active mixture** (density and properties depend on the composition): use `FLUID_MODEL= FLUID_MIXTURE`. It requires `INC_DENSITY_MODEL= VARIABLE` and `KIND_SCALAR_MODEL= SPECIES_TRANSPORT`. The density follows from the ideal gas law, using the mixture molecular weight and `THERMODYNAMIC_PRESSURE` (default 101325 Pa). For this model, `INIT_OPTION_INC` defaults to `OPERATING_PRESSURE`, so `INC_DENSITY_INIT` does not change the operating pressure (code). + +For a mixture ([composition-dependent tutorial](/tutorials/Inc_Species_Transport_Composition_Dependent_Model/)): + +- The mean molecular weight is a mole-fraction average, equivalently 1/M_mix = Σ(Y_i/M_i) for mass fractions Y_i. Specific heat is a mass-fraction average (tutorial, code). +- `MIXING_VISCOSITY_MODEL` sets the mixing rule for viscosity: `DAVIDSON` (default) or `WILKE` (code). +- With a species model and variable density, SU2 does not switch the energy equation on for you (code). If all streams have the same temperature and the walls are adiabatic, `INC_ENERGY_EQUATION= NO` is possible, as in the tutorial. Otherwise set `INC_ENERGY_EQUATION= YES`. + +### Mass diffusivity + +`DIFFUSIVITY_MODEL` sets the laminar diffusion coefficient D, in m²/s (code): + +| Value | D | Options | +|---|---|---| +| `CONSTANT_DIFFUSIVITY` (default) | constant | `DIFFUSIVITY_CONSTANT`. You must set it; SU2 stops otherwise. | +| `CONSTANT_SCHMIDT` | μ / (ρ Sc) | `SCHMIDT_NUMBER_LAMINAR` (default 1.0) | +| `UNITY_LEWIS` | k / (ρ c_p) | none | +| `CONSTANT_LEWIS` | k / (Le ρ c_p) | `CONSTANT_LEWIS_NUMBER`, one value per species | +| `FLAMELET` | read from the flamelet table | only with `FLUID_FLAMELET` | + +Here μ is the viscosity, k the thermal conductivity, c_p the specific heat, Sc the Schmidt number and Le the Lewis number. +For RANS, turbulence adds μ_t / Sc_t to ρD, with `SCHMIDT_NUMBER_TURBULENT` (default 0.7) as Sc_t ([Theory](../Theory/#species-transport)). + +For gases that diffuse fast, such as hydrogen, the [composition-dependent tutorial](/tutorials/Inc_Species_Transport_Composition_Dependent_Model/) suggests `CONSTANT_LEWIS` (tutorial). +`UNITY_LEWIS` and `CONSTANT_LEWIS` prescribe the ratio of thermal to mass diffusivity; they do not reproduce general multicomponent diffusion or thermal diffusion. Hydrogen-rich mixtures can require differential-diffusion treatment, but choose coefficients for the actual composition and state (advice, to be reviewed). + +### Species boundary conditions + +Species boundary conditions sit on top of the flow boundary conditions (code): + +- **Inlet**: every `MARKER_INLET` marker needs an entry in `MARKER_INLET_SPECIES= ( marker, Y_1, ..., Y_N-1, ... )`. The values are mass fractions. Inlet profiles from a file are possible, see [`species3_primitiveVenturi_inletFile.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/species_transport/venturi_primitive_3species/species3_primitiveVenturi_inletFile.cfg). +- **Outlet**: zero gradient. Nothing to set. +- **Far field**: the values of `SPECIES_INIT`. +- **Walls**: zero flux by default. `MARKER_WALL_SPECIES= ( marker, FLUX, value, VALUE, value, ... )` sets, per species, a flux (`FLUX`) or a fixed mass fraction (`VALUE`). The pairs follow the species order, for example `MARKER_WALL_SPECIES= ( wall, VALUE, 1.0, FLUX, 0.01 )` (test case). The `FLUX` value enters `CSpeciesSolver::BC_Wall_Generic` directly as a scalar mass flux per area, with positive values adding the species to the domain. With `INC_NONDIM= DIMENSIONAL` its units are kg/(m² s). Otherwise normalize by the reference density times reference velocity; this boundary routine performs no automatic dimensional conversion (code). + +`MARKER_SPECIES_STRONG_BC` lists markers where SU2 imposes the species values directly in the solution: a strong, or Dirichlet, condition. By default, SU2 imposes them through the boundary flux: a weak condition (code). + +- At an inlet, the strong condition fixes the inlet mass fractions. +- At an outlet, it copies the value of the neighbor point inside. +- For the flamelet model, at an isothermal wall it fixes the enthalpy that matches the wall temperature. + +The sources give different advice: + +- The [composition-dependent tutorial](/tutorials/Inc_Species_Transport_Composition_Dependent_Model/) advises strong conditions with `SCALAR_UPWIND`, and no strong conditions with `BOUNDED_SCALAR` (tutorial). +- The flamelet test cases use strong conditions at inlets, outlets and walls together with `BOUNDED_SCALAR` (test case). + +Start from the test case closest to your problem (to be reviewed). + +### Numerics for the species equations + +- `CONV_NUM_METHOD_SPECIES`: `SCALAR_UPWIND` (default) or `BOUNDED_SCALAR`. Centered schemes are not available for scalars (code). `BOUNDED_SCALAR` subtracts the effect of a non-zero velocity divergence during convergence, which helps avoid scalar overshoots from an unconverged continuity equation; it is not a general bound-preservation guarantee ([Convective Schemes](../Convective-Schemes/#turbulence-and-scalarspecies-equations)). The [combustion tutorial](/tutorials/Inc_Combustion/) highly recommends it for flamelet runs. +- `MUSCL_SPECIES` (default `NO`) makes the scheme second order. `SLOPE_LIMITER_SPECIES` (default `NONE`) adds a limiter (code). +- `TIME_DISCRE_SPECIES`: `EULER_IMPLICIT` (default) or `EULER_EXPLICIT`. No other value is allowed (code). +- `CFL_REDUCTION_SPECIES` (default 1.0) multiplies the CFL number for the species equations (code). +- `SPECIES_CLIPPING= YES` clips each transported mass fraction to `SPECIES_CLIPPING_MIN` and `SPECIES_CLIPPING_MAX`. For more than two species, clipping individual fractions to [0,1] does not guarantee their sum is at most one or that the reconstructed last species stays nonnegative. Clipping can also disturb species conservation; inspect all fractions and balances. SU2 stops if you switch it on without both limits (code). The composition-dependent tutorial uses clipping with `SCALAR_UPWIND` only; that example uses `BOUNDED_SCALAR` without clipping (tutorial). +- Unsteady runs with dual time stepping and a density that depends on the species cannot use multigrid (`MGLEVEL` above 0) (code). + +### Flamelet model: required options + +`KIND_SCALAR_MODEL= FLAMELET` requires all of these (code): + +- `FLUID_MODEL= FLUID_FLAMELET`, +- `DIFFUSIVITY_MODEL= FLAMELET`, `VISCOSITY_MODEL= FLAMELET`, `CONDUCTIVITY_MODEL= FLAMELET`, +- `INC_DENSITY_MODEL= FLAMELET` (density read from the table, column `Density`) or `VARIABLE` (density from the ideal gas law with the table column `MolarWeightMix`), +- no `WEAKLY_COUPLED_HEAT_EQUATION`. + +SU2 switches the energy equation of the flow solver off. The flamelet solver transports the total enthalpy and reads the temperature from the table. So `INC_ENERGY_EQUATION` has no effect (code). + +### Flamelet model: the manifold + +The manifold is the table of flame data. The [combustion tutorial](/tutorials/Inc_Combustion/) explains how to build it. + +- `INTERPOLATION_METHOD`: `LUT` (default, a look-up table in a `.drg` file) or `MLP` (one or more neural networks in `.mlp` files) (code). +- `FILENAMES_INTERPOLATOR`: the file name(s). +- The table must contain `Temperature`, `Cp`, `ViscosityDyn`, `Conductivity` and `DiffusionCoefficient`, plus `Density` or `MolarWeightMix` (see the density model above) (code). +- SU2 divides `MolarWeightMix` by 1000, so it expects g/mol (code). + +A look-up table is faster to query, but a 3D table can need a lot of memory per core. Neural networks need less memory and give smoother data, but they are harder to train ([combustion tutorial](/tutorials/Inc_Combustion/)). + +### Flamelet model: controlling variables and extra scalars + +- `CONTROLLING_VARIABLE_NAMES`: the transported variables, with the names used in the table. The order is progress variable, total enthalpy, then optionally mixture fraction (code, tutorial). The progress variable measures how far combustion has advanced. The mixture fraction measures how much of the mixture came from the fuel stream. +- `CONTROLLING_VARIABLE_SOURCE_NAMES`: one table column per controlling variable, for its reaction source term. Write `NULL` when there is none, for example for enthalpy (tutorial). +- `USER_SCALAR_NAMES`: extra species to transport, such as CO or NO. +- `USER_SOURCE_NAMES`: two names per extra species, a production term and a consumption term. The source is production + consumption × Y. Use `NULL` or `zero` for a missing term (code). +- `LOOKUP_NAMES`: table columns to write in the volume output, with `LOOKUP` in `VOLUME_OUTPUT` (tutorial). +- `PREFERENTIAL_DIFFUSION= YES` adds the preferential diffusion model for hydrogen flames. The table must then contain `Beta_ProgVar`, `Beta_Enth_Thermal`, `Beta_Enth` and `Beta_MixFrac`. This is stated in the config template and used in the tutorial (code, tutorial). +- `THICKENED_FLAME_CORRECTION` (default `YES`) lowers the source terms and raises the diffusion in cells that are larger than the flame thickness. This is intended to improve resolution of an under-resolved flame, but does not guarantee stability or mesh-independent flame properties (code, advice). + +`SPECIES_INIT` and `MARKER_INLET_SPECIES` need one value per controlling variable, plus one per extra species (code). In the start config, these are: progress variable, enthalpy, CO, NOx. + +### Flamelet model: ignition + +The solver must start ("ignite") the flame. `FLAME_INIT_METHOD` takes these values (code, tutorial): + +- `NONE` (default): no ignition. Use it for cold flow and for restarts. +- `FLAME_FRONT`: a flat flame front at the start. `FLAME_INIT= ( x, y, z, nx, ny, nz, thickness, burnt length )`: a point on the front, the normal that points to the burnt side, the thickness of the transition, and the length of the burnt zone. This works well when the flow is simple at the start (tutorial). +- `SPARK`: a sphere where SU2 adds source terms for a few iterations. `SPARK_INIT= ( x, y, z, radius, start iteration, number of iterations )`. This works well when the flow needs many iterations to develop, such as in partially premixed flames (tutorial). + +Rules (code): + +- `SPARK` needs both `SPARK_INIT` and `SPARK_REACTION_RATES`, with at least one rate per transported scalar (controlling variables and extra species). +- `FLAME_INIT_IGNITION` (default 5000 K) is the burnt temperature for `FLAME_FRONT`, and the upper temperature inside the spark. It must be higher than `INC_TEMPERATURE_INIT`. +- The ignition also runs when you restart, unless `FLAME_INIT_METHOD= NONE`. + +### Flamelet model: thermal boundary conditions + +`FLAME_ENTHALPY_BC` decides where the enthalpy boundary values come from (code): + +- `FLOW_MARKERS` (default): from temperatures and heat fluxes. The inlet enthalpy follows from the temperature in `MARKER_INLET`. Walls use `MARKER_ISOTHERMAL` or `MARKER_HEATFLUX`. SU2 finds the enthalpy that gives the wall temperature with a Newton iteration on the table. +- `SPECIES_MARKERS`: the enthalpy and all other scalars come directly from `MARKER_INLET_SPECIES` and `MARKER_WALL_SPECIES`. You must give values that match the temperature you want. + +Some pages write `FLAMELET_ENTHALPY_BC`; the option name is `FLAME_ENTHALPY_BC`. +For wall values set per point from Python, see [`SU2_CFD/flamelet_python_bc.md`](https://github.com/su2code/SU2/blob/develop/SU2_CFD/flamelet_python_bc.md) in the code. + +Use `FLOW_MARKERS` when you know the temperatures, which is the usual case. It avoids an enthalpy that does not match the table ([diffusion flame tutorial](https://su2code.github.io/tutorials/Inc_Laminar_Diffusion_Flame/)). + +## Check convergence and results + +- **Residual names.** Species transport: `RMS_SPECIES_0`, `RMS_SPECIES_1`, ... Flamelet: `RMS_` plus the name of the controlling variable or extra species, for example `RMS_ProgressVariable` or `RMS_CO` (code). In multizone runs, `BGS_` fields are available too. +- **Field names.** SU2 ignores unknown names in `CONV_FIELD` and prints `Ignoring Convergence Field(s)` at the start. `RMS_SPECIES` without a number is not a field (code). +- **Linear solver.** `LINSOL_ITER_SPECIES` and `LINSOL_RESIDUAL_SPECIES` (or `LINSOL_ITER_FLAMELET` and `LINSOL_RESIDUAL_FLAMELET`) show whether SU2 solves the species linear systems well (code). +- **Mixing quality.** With `MARKER_ANALYZE`, `SURFACE_SPECIES_0` gives the average mass fraction on those markers, and `SURFACE_SPECIES_VARIANCE` measures how uneven the mixture is there. Add the groups `SPECIES_COEFF` and `SPECIES_COEFF_SURF` to `HISTORY_OUTPUT` (code, tutorial). +- **Mass balance of a species.** For a steady non-reacting case with no volume source and impermeable walls, the advective plus diffusive species influx must balance the outflux. Include prescribed wall fluxes and reaction/volume sources when present; an inlet/outlet-only balance is then insufficient (advice). No output field gives this species mass flow directly. A `CUSTOM_OUTPUTS` expression, such as the one in [`passive_transport.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/species_transport/passive_transport_validation/passive_transport.cfg), can compute a mass-flow-averaged value (to be reviewed). +- **Table misses (flamelet).** Add `LOOKUP` to `VOLUME_OUTPUT` and check the field `TABLE_MISSES`. Points with misses have controlling variables outside the table (code). +- **Flame position (flamelet).** Look at the progress variable and the temperature in ParaView. The flame should not move between the last outputs of a steady run (advice, to be reviewed). + +## Common problems + +| Symptom | Likely cause | What to try | +|---|---|---| +| SU2 stops: "Make sure all species inputs have the same size". | A species list has a different length from `SPECIES_INIT` (code). | Give N−1 values in `SPECIES_INIT`, in the clipping limits, and per marker in `MARKER_INLET_SPECIES` and `MARKER_WALL_SPECIES`. | +| SU2 stops: "The use of FLUID_MIXTURE requires the number of entries for MOLECULAR_WEIGHT and SPECIFIC_HEAT_CP". | A mixture property list does not have N values (code). | Give one value per species, the last species included. | +| SU2 stops: "The use of FLUID_MIXTURE requires the INC_DENSITY_MODEL option to be VARIABLE". | `FLUID_MIXTURE` with constant density (code). | Set `INC_DENSITY_MODEL= VARIABLE`. For a passive scalar, use constant density without `FLUID_MIXTURE`. | +| SU2 stops: "A DIFFUSIVITY_CONSTANT= has to be set". | `CONSTANT_DIFFUSIVITY` without a value (code). | Set `DIFFUSIVITY_CONSTANT` in m²/s. | +| SU2 stops: "SPECIES_CLIPPING= YES requires the options SPECIES_CLIPPING_MIN/MAX". | Clipping is on without limits (code). | Add both lists. | +| The run never stops at the residual target. | A `CONV_FIELD` name is unknown, for example `RMS_SPECIES` (code). | Use `RMS_SPECIES_0` and the other numbered names. | +| Mass fractions go below 0 or above 1. | Unbounded convection during convergence (advice). | Use `BOUNDED_SCALAR`, or `SPECIES_CLIPPING= YES` with limits 0 and 1 (to be reviewed). | +| Message "... is out of bounds [0,1]" at start-up. | A mass fraction, or a sum of mass fractions, in `SPECIES_INIT` or `MARKER_INLET_SPECIES` is outside 0 to 1. SU2 continues anyway (code). | Fix the values. | +| SU2 stops: "Number of initial species incompatible with number of controlling variables and user scalars". | `SPECIES_INIT` does not have one value per controlling variable and extra species (code). | Count `CONTROLLING_VARIABLE_NAMES` plus `USER_SCALAR_NAMES`. | +| SU2 stops: "Flame ignition temperature must be higher than the initial temperature". | `FLAME_INIT_IGNITION` is not above `INC_TEMPERATURE_INIT` (code). | Raise `FLAME_INIT_IGNITION`. | +| SU2 stops with an error about `FLAME_INIT_METHOD= SPARK`. | `SPARK_INIT` or `SPARK_REACTION_RATES` is missing, or there are too few rates (code). | Give both, with one rate per transported scalar. | +| No flame appears. | `FLAME_INIT_METHOD= NONE` (the default) on a fresh start (code). | Use `FLAME_FRONT` or `SPARK`. | +| The converged flame is reset after a restart. | Ignition runs again on restart, unless `FLAME_INIT_METHOD= NONE` (code). | Set `FLAME_INIT_METHOD= NONE` when you restart. | +| The inlet enthalpy in `MARKER_INLET_SPECIES` has no effect. | `FLAME_ENTHALPY_BC= FLOW_MARKERS` (default) uses the inlet temperature instead (code). | Set the temperature in `MARKER_INLET`, or use `FLAME_ENTHALPY_BC= SPECIES_MARKERS`. | +| SU2 stops with an unknown option `FLAMELET_ENTHALPY_BC`. | Wrong option name, from an older page (code). | Use `FLAME_ENTHALPY_BC`. | +| Many table misses; the temperature jumps. | Controlling variables outside the table, often an enthalpy below the table range at cold walls (advice). | Check the wall and inlet temperatures. Extend the table to lower enthalpy ([diffusion flame tutorial](https://su2code.github.io/tutorials/Inc_Laminar_Diffusion_Flame/)). | +| SU2 stops: "Dual-time stepping with species-dependent variable density does not support MGLEVEL > 0". | Multigrid in an unsteady mixture run (code). | Set `MGLEVEL= 0`. | + +## Related tutorials and test cases + +Tutorials: + +- [Species Transport](/tutorials/Inc_Species_Transport/): mixing in a venturi, species options and output. +- [Composition-Dependent model for Species Transport](/tutorials/Inc_Species_Transport_Composition_Dependent_Model/): `FLUID_MIXTURE`, Lewis number models, `BOUNDED_SCALAR`. +- [Wind velocity and pollutant dispersion in a city](/tutorials/Inc_Urban_City/): smoke as a species, with a source term set from the Python wrapper. +- [Incompressible, Laminar Combustion Simulation](/tutorials/Inc_Combustion/): premixed hydrogen flame with neural networks, preferential diffusion and spark ignition. +- [Incompressible, Laminar counterflow diffusion flame](https://su2code.github.io/tutorials/Inc_Laminar_Diffusion_Flame/): mixture fraction and enthalpy, `FLAME_ENTHALPY_BC`. + +Test cases: + +- [`species_transport/venturi_primitive_3species`](https://github.com/su2code/SU2/blob/develop/TestCases/species_transport/venturi_primitive_3species/species2_primitiveVenturi_mixingmodel.cfg): mixing, with variants for `BOUNDED_SCALAR`, Wilke viscosity mixing, wall species fluxes and inlet files. +- [`species_transport/passive_transport_validation/passive_transport.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/species_transport/passive_transport_validation/passive_transport.cfg): passive scalar with strong boundary conditions. +- [`species_transport/multizone/configMaster.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/species_transport/multizone/configMaster.cfg): species across two fluid zones. +- [`flamelet/01_laminar_premixed_ch4_flame_cfd`](https://github.com/su2code/SU2/blob/develop/TestCases/flamelet/01_laminar_premixed_ch4_flame_cfd/lam_prem_ch4_cfd.cfg): the flamelet start config. +- [`flamelet/03_laminar_premixed_ch4_flame_cht_cfd`](https://github.com/su2code/SU2/blob/develop/TestCases/flamelet/03_laminar_premixed_ch4_flame_cht_cfd/lam_prem_ch4_cht_cfd_master.cfg): flame with conjugate heat transfer. +- [`flamelet/05_laminar_premixed_ch4_flame_cfd_axi`](https://github.com/su2code/SU2/blob/develop/TestCases/flamelet/05_laminar_premixed_ch4_flame_cfd_axi/lam_prem_ch4_cfd_axi.cfg): axisymmetric flame. +- [`flamelet/06_laminar_partial_premixed_ch4_flame_cfd`](https://github.com/su2code/SU2/blob/develop/TestCases/flamelet/06_laminar_partial_premixed_ch4_flame_cfd/lam_partial_prem_ch4_cfd.cfg): partially premixed flame with a 3D table and mixture fraction. +- [`flamelet/07_laminar_premixed_h2_flame_cfd`](https://github.com/su2code/SU2/blob/develop/TestCases/flamelet/07_laminar_premixed_h2_flame_cfd/laminar_premixed_h2_flame_cfd.cfg): hydrogen flame with neural networks. +- [`flamelet/08_flame_init_method/flamelet_initialization.py`](https://github.com/su2code/SU2/blob/develop/TestCases/flamelet/08_flame_init_method/flamelet_initialization.py): flame front and spark ignition. +- [`flamelet/09_laminar_premixed_ch4_flame_unsteady`](https://github.com/su2code/SU2/blob/develop/TestCases/flamelet/09_laminar_premixed_ch4_flame_unsteady/lam_prem_ch4_unsteady.cfg): unsteady flame. + +User guide pages: [Theory: Species Transport and Combustion](../Theory/#species-transport), [Convective Schemes](../Convective-Schemes/), [Markers and BC](../Markers-and-BC/), [Custom Output](../Custom-Output/). + +Source review: 22 October 2026, against [SU2 `docs_site` at `41ea6a219a`](https://github.com/rois1995/SU2/tree/41ea6a219ac038574f3d4a5b130c0c1d8af66457). See the [review scope and outstanding validation](../Documentation-Status/#guide-and-model-review). Setup recommendations remain draft where indicated. diff --git a/_docs_v7/Setup-Guide-Transition.md b/_docs_v7/Setup-Guide-Transition.md new file mode 100644 index 00000000..ba4c1fed --- /dev/null +++ b/_docs_v7/Setup-Guide-Transition.md @@ -0,0 +1,287 @@ +--- +title: "Setup Guide: Laminar-Turbulent Transition" +permalink: /docs_v7/Setup-Guide-Transition/ +--- + +{% include setup-guide-intro.md %} + +--- + +- [When to use this guide](#when-to-use-this-guide) +- [Start from](#start-from) +- [Settings that matter](#settings-that-matter) +- [Check convergence and results](#check-convergence-and-results) +- [Common problems](#common-problems) +- [Related tutorials and test cases](#related-tutorials-and-test-cases) + +--- + +## When to use this guide + +A standard RANS run treats the boundary layer as turbulent from the leading edge. A transition model lets the boundary layer start laminar and become turbulent further downstream. The model damps the production of turbulence until a transition criterion is met (tutorial). + +Use a transition model when laminar flow covers a large part of the surface, for example (advice): + +- airfoils and blades at Reynolds numbers from about 10^5 to a few 10^6, +- wind turbine blades, gliders, natural laminar flow wings, +- cases with laminar separation bubbles. + +A fully turbulent model cannot represent the laminar region and its transition mechanisms. It can overpredict local skin friction there, but the change in total drag also depends on separation and pressure drag (advice). + +Limits of the Langtry-Menter (LM) model in SU2 (tutorial): + +- It is built from subsonic experiments: transition caused by Tollmien-Schlichting waves, by free-stream turbulence ("bypass" transition) and by laminar separation. +- It does not predict crossflow transition (except through the `LM2015` option, see below), nor supersonic and hypersonic transition mechanisms. + +LM has no discrete adjoint in this code version. Do not use `KIND_TRANS_MODEL= LM` with +`MATH_PROBLEM= DISCRETE_ADJOINT`; see [Transition Models](../Transition-Models/#known-limits) (code). + +For the RANS settings that are not specific to transition, see [Setup Guide: Steady RANS for External Aerodynamics](../Setup-Guide-RANS-External-Aero/). + +## Start from + +This config comes from the E387 airfoil tutorial with SA and LM: `compressible_flow/Transitional_Airfoil/Langtry_and_Menter/E387/transitional_SA_LM_model_ConfigFile.cfg` in the [Tutorials repository](https://github.com/su2code/Tutorials/tree/develop/compressible_flow/Transitional_Airfoil/Langtry_and_Menter/E387). The SU2 tutorial regression tests run it. +We removed the output file name options and `JST_SENSOR_COEFF` (it has no effect with `ROE`). All other values are unchanged. + +``` +% ------------- Problem ------------------------------------------------% +SOLVER= RANS +KIND_TURB_MODEL= SA +KIND_TRANS_MODEL= LM +FREESTREAM_TURBULENCEINTENSITY= 0.001 +MATH_PROBLEM= DIRECT +RESTART_SOL= NO +% +% ------------- Free stream --------------------------------------------% +MACH_NUMBER= 0.06 +AOA= 2 +FREESTREAM_TEMPERATURE= 288.15 +REYNOLDS_NUMBER= 200000.0 +REYNOLDS_LENGTH= 1.0 +REF_ORIGIN_MOMENT_X= 0.25 +REF_ORIGIN_MOMENT_Y= 0.00 +REF_ORIGIN_MOMENT_Z= 0.00 +REF_LENGTH= 1.0 +REF_AREA= 0 +REF_DIMENSIONALIZATION= FREESTREAM_VEL_EQ_MACH +% +% ------------- Boundary conditions ------------------------------------% +MARKER_HEATFLUX= ( Airfoil, 0.0 ) +MARKER_FAR= ( Farfield ) +MARKER_PLOTTING= ( Airfoil ) +MARKER_MONITORING= ( Airfoil ) +% +% ------------- Numerics -----------------------------------------------% +NUM_METHOD_GRAD= GREEN_GAUSS +CFL_NUMBER= 1 +CFL_ADAPT= YES +CFL_ADAPT_PARAM= ( 0.1, 2.0, 40.0, 1e10, 0.001 ) +ITER= 100000 +LINEAR_SOLVER= FGMRES +LINEAR_SOLVER_PREC= LU_SGS +LINEAR_SOLVER_ERROR= 1E-6 +LINEAR_SOLVER_ITER= 5 +CONV_NUM_METHOD_FLOW= ROE +USE_VECTORIZATION= NO +MUSCL_FLOW= YES +SLOPE_LIMITER_FLOW= VENKATAKRISHNAN +VENKAT_LIMITER_COEFF= 0.05 +LIMITER_ITER= 99999 +TIME_DISCRE_FLOW= EULER_IMPLICIT +CONV_NUM_METHOD_TURB= SCALAR_UPWIND +MUSCL_TURB= NO +SLOPE_LIMITER_TURB= NONE +TIME_DISCRE_TURB= EULER_IMPLICIT +CFL_REDUCTION_TURB= 1.0 +% +% ------------- Convergence --------------------------------------------% +CONV_FIELD= ( RMS_DENSITY ) +CONV_RESIDUAL_MINVAL= -13 +CONV_STARTITER= 500 +% +% ------------- Input and output ---------------------------------------% +MESH_FILENAME= ogrid_e387.su2 +MESH_FORMAT= SU2 +OUTPUT_FILES= (RESTART, PARAVIEW, SURFACE_PARAVIEW) +WRT_FORCES_BREAKDOWN= YES +VOLUME_OUTPUT= (COORDINATES, SOLUTION, PRIMITIVE, RESIDUAL) +HISTORY_OUTPUT= (ITER, LINSOL, RMS_RES, MAX_RES, AERO_COEFF, CFL_NUMBER) +OUTPUT_WRT_FREQ= 500 +SCREEN_WRT_FREQ_INNER= 10 +SCREEN_OUTPUT= (INNER_ITER, WALL_TIME, RMS_DENSITY, RMS_INTERMITTENCY, RMS_RE_THETA_T, LIFT, DRAG, LINSOL_ITER_TRANS, LINSOL_RESIDUAL_TRANS) +WRT_PERFORMANCE= YES +``` + +The same tutorial folder has an SST version, `transitional_SST_LM_model_ConfigFile.cfg`. It differs in three lines (tutorial): + +``` +KIND_TURB_MODEL= SST +SST_OPTIONS= V1994m +MUSCL_TURB= YES +``` + +## Settings that matter + +### Turn on the LM model + +- `KIND_TRANS_MODEL= LM` turns on the Langtry-Menter model. `NONE` (the default) and `LM` are the only values (code). +- LM needs a turbulence model. With `KIND_TURB_MODEL= NONE`, SU2 stops with an error (code). +- LM adds two transport equations (code): + - the intermittency, gamma: 0 where the boundary layer is laminar, 1 where it is turbulent; + - the transition onset Reynolds number, Re_theta_t: a Reynolds number based on the momentum thickness, at which transition starts. +- The model uses gamma to damp the production term of the turbulence model (tutorial). + +### Base turbulence model: SST or SA + +The develop branch of SU2 supports LM with both SST and SA (code, docs). The two couplings differ in how they get the turbulence intensity Tu. Tu drives the transition correlations, the empirical formulas that predict where transition starts: + +| | `KIND_TURB_MODEL= SST` | `KIND_TURB_MODEL= SA` | +| --- | --- | --- | +| Turbulence intensity used by LM | Local value from k: Tu = 100·sqrt(2k/3)/U, not below 0.027 % (code) | `FREESTREAM_TURBULENCEINTENSITY` everywhere (code) | +| Default correlation | `MENTER_LANGTRY` (code) | `MALAN` (code) | +| Tutorials | T3A and T3A- flat plates, E387 airfoil (tutorial) | E387 airfoil (tutorial) | + +What this means (advice, to be reviewed): + +- With SST, the intensity at the body depends on how much k decays on its way from the far field. You control it with `FREESTREAM_TURBULENCEINTENSITY` and `FREESTREAM_TURB2LAMVISCRATIO`. +- With SA, LM uses the same intensity everywhere, so nothing decays. Set `FREESTREAM_TURBULENCEINTENSITY` to the intensity you expect at the leading edge. + +The original LM model was published with SST; see the [TMR model definition](https://tmbwg.github.io/turbmodels/langtrymenter_4eqn.html) (reference). + +The supported variants here are those registered in this source revision; check the generated reference before using options from another branch. + +### LM_OPTIONS + +`LM_OPTIONS` takes a list. With an empty list, SU2 runs the 2009 version of the model with the default correlation of the base turbulence model (code). + +**Version.** + +- `LM2015` adds a correction for stationary crossflow instabilities (docs). It works in 3D only; in 2D SU2 stops with an error (code). +- `LM2015` uses the surface roughness `HROUGHNESS` (RMS roughness height, default `1e-6`) (code, docs). The code divides it by a momentum thickness, so give it in the same length unit as the mesh (code, to be reviewed). + +**Correlation.** The correlation computes the transition onset Reynolds number. Choose at most one; two or more stop SU2 with an error (code). + +| Value | Notes | +| --- | --- | +| `MENTER_LANGTRY` | Default with SST (code). | +| `MALAN` | Default with SA (code, docs). | +| `SULUKSNA` | Use with SST only (docs). | +| `KRAUSE`, `KRAUSE_HYPER` | Meant for hypersonic flows. The docs say their implementation is unclear because of inconsistencies in the literature (docs). | +| `MEDIDA_BAEDER` | Designed for SA. Has problems with separation-induced transition (docs). | +| `DEFAULT` | Same as leaving the correlation out (code). | + +Some pages also list `MEDIDA`. The develop code does not accept it as a keyword (code). + +Keep the default correlation unless you have a reason to change it, for example a validation for your type of flow (advice). + +Example: `LM_OPTIONS= LM2015, MENTER_LANGTRY` (docs). + +### Free-stream turbulence intensity and viscosity ratio + +The free-stream turbulence intensity is the main input of the transition correlations (tutorial). + +- `FREESTREAM_TURBULENCEINTENSITY` is a fraction, not a percentage: `0.001` means 0.1 %. SU2 multiplies it by 100 inside the correlations (code). +- The default is `0.05` (5 %) (code). This is high for most external flows (docs). +- SU2 computes the far-field value of Re_theta_t from this intensity with the Langtry-Menter correlation (code). +- `FREESTREAM_INTERMITTENCY` has no effect on LM: SU2 prints it, but the far-field intermittency is fixed at 1 (code). + +**With SST.** + +- SU2 builds the far-field k from the intensity, and omega from `FREESTREAM_TURB2LAMVISCRATIO` (eddy viscosity over laminar viscosity, default `10.0`) (code). +- k decays between the far field and the body. A larger viscosity ratio gives a slower decay (advice, to be reviewed). +- The T3A tutorial sets `FREESTREAM_TURBULENCEINTENSITY= 0.05855` and `FREESTREAM_TURB2LAMVISCRATIO= 11.9` at the inflow (tutorial). +- Check the intensity just upstream of the body. Compute it from the `TKE` output field: Tu = sqrt(2k/3)/U (advice). +- `SST_OPTIONS= SUSTAINING` adds ambient sustaining terms through a production floor in SU2. `TURB_FIXED_VALUES= YES` with `TURB_FIXED_VALUES_DOMAIN` fixes the turbulence variables in a specified upstream region (code). These change the turbulence environment; match the measured intensity and decay rather than removing decay automatically (advice). No transition test case uses them with LM (to be reviewed). + +**With SA.** + +- `FREESTREAM_TURB2LAMVISCRATIO` is not used. The free-stream SA variable comes from `FREESTREAM_NU_FACTOR` (default `3.0`) (code, docs). +- The E387 tutorial uses `FREESTREAM_TURBULENCEINTENSITY= 0.001` (0.1 %) (tutorial). + +### Mesh + +General points for the mesh of an LM run (advice, to be reviewed): + +- First-cell y+ about 1 or below, all along the walls. Do not use wall functions. +- A smooth wall-normal growth in the boundary layer, with a growth ratio near 1.1. +- Enough points along the wall where transition or a laminar separation bubble is expected. The transition location moves on meshes that are too coarse in this direction. +- Check the transition location on at least two meshes. Transition models are more sensitive to the mesh than fully turbulent RANS. + +### Numerics + +- The transition equations use the settings of the turbulence equations: `CONV_NUM_METHOD_TURB`, `MUSCL_TURB`, `SLOPE_LIMITER_TURB` and `TIME_DISCRE_TURB` (code). +- The tutorials use `ROE` with MUSCL and `VENKATAKRISHNAN` (E387), and `L2ROE` with MUSCL (T3A) for the flow (tutorial). `L2ROE` is a Roe scheme with low dissipation at low Mach number (docs). +- Both E387 configs start at `CFL_NUMBER= 1` with `CFL_ADAPT= YES` and use `LU_SGS` (tutorial). +- Transition cases often run at low Mach numbers (0.06 for E387, 0.2 for T3A) (tutorial). The compressible solver converges more slowly at very low Mach numbers (advice, to be reviewed). +- Add `RMS_INTERMITTENCY`, `RMS_RE_THETA_T`, `LINSOL_ITER_TRANS` and `LINSOL_RESIDUAL_TRANS` to `SCREEN_OUTPUT` to follow the transition equations (tutorial, code). + +### The algebraic BC model: a lighter option with SA + +The develop branch also has an algebraic transition model for SA, the Bas-Cakmakcioglu (BC) model: `KIND_TURB_MODEL= SA` with `SA_OPTIONS= BCM` (tutorial, code). + +- It adds no transport equation. It damps the SA production term until a local criterion is met (tutorial). +- It also uses `FREESTREAM_TURBULENCEINTENSITY` as a fraction (code). The tutorial uses `0.0018` for 0.18 % (tutorial). +- Do not combine `BCM` with other SA options. SU2 stops with an error unless you add `EXPERIMENTAL` (code). +- The old option `KIND_TRANS_MODEL= BC` is removed. SU2 stops with a message that points to `SA_OPTIONS= BCM` (code). +- The SA-BCM `INTERMITTENCY` output currently returns zero instead of the computed intermittency. Do not use it to locate transition; inspect the skin friction and eddy viscosity instead (code, advice). See [Transition Models](../Transition-Models/#bas-cakmakcioglu-sa-bcm). +- See the tutorial [Transitional Flat Plate](/tutorials/Transitional_Flat_Plate/). + +## Check convergence and results + +**Convergence.** + +- Residuals: `RMS_DENSITY`, the turbulence residuals, `RMS_INTERMITTENCY` and `RMS_RE_THETA_T` (code). +- Lift and drag must be flat at the end (advice). +- The transition location must stop moving. Compare the skin friction plots of the last saved solutions (advice). + +**Where transition happens.** The default output groups `SOLUTION` and `PRIMITIVE` contain the fields below (code). + +| Field | Group | What to look for | +| --- | --- | --- | +| `SKIN_FRICTION-X` (surface) | `PRIMITIVE` | Low in the laminar part, then a sharp rise at transition. For flow aligned with +x, negative values indicate reversed wall shear, which can occur in either laminar or turbulent separation. Use the local streamwise shear component on a curved or inclined surface (advice). | +| `INTERMITTENCY` | `SOLUTION` | Transported intermittency: 0 laminar, 1 turbulent (code). | +| `INTERMITTENCY_EFF` | `PRIMITIVE` | Effective intermittency that multiplies the production term. It can exceed 1 in separated regions (advice, to be reviewed). | +| `INTERMITTENCY_SEP` | `PRIMITIVE` | Extra intermittency for separation-induced transition (advice, to be reviewed). | +| `RE_THETA_T` | `SOLUTION` | Transported transition onset Reynolds number (code). | +| `EDDY_VISCOSITY` | `PRIMITIVE` | Rises where the boundary layer becomes turbulent (advice). | +| `TURB_INDEX` | `PRIMITIVE` | Turbulence index on wall nodes: near 0 laminar, near 1 turbulent. Use it only as a rough indicator (code, to be reviewed). | + +Plot `SKIN_FRICTION-X` from the surface output (`SURFACE_PARAVIEW` or `SURFACE_CSV` in `OUTPUT_FILES`) along the wall, and compare it with experiments. The T3A tutorial compares it with ERCOFTAC data as a function of the local Reynolds number (tutorial). + +See the [Output Fields Reference](../Output-Fields-Reference/). + +## Common problems + +| Symptom | Likely cause | What to try | +| --- | --- | --- | +| The boundary layer is turbulent from the leading edge. | Turbulence intensity too high; or given in percent (for example `3.0` instead of `0.03`). | Give `FREESTREAM_TURBULENCEINTENSITY` as a fraction (code). Check the intensity near the body (advice). | +| Transition happens too late, or not at all. | With SST, k has decayed to a very low value before the body. Or the mesh is too coarse at the wall. | Check Tu near the leading edge from `TKE`; adjust `FREESTREAM_TURB2LAMVISCRATIO` (advice, to be reviewed). Check y+ (advice). | +| The transition location moves when you refine the mesh. | Too few points along the wall in the transition region. | Refine along the wall (advice). | +| The residuals stall or oscillate. | A laminar separation bubble that is unsteady, or a CFL that is too high. | Start at a low CFL with `CFL_ADAPT= YES` (tutorial). If the bubble is unsteady, run time-accurate, see [Setup Guide: Unsteady Flows and DES](../Setup-Guide-Unsteady-DES/) (advice, to be reviewed). | +| SU2 stops: "LM2015 is available only for 3D problems". | `LM2015` in a 2D case. | Remove `LM2015` (code). | +| SU2 stops: "Two correlations selected for LM_OPTIONS". | More than one correlation in `LM_OPTIONS`. | Keep one (code). | +| SU2 stops: "KIND_TURB_MODEL cannot be NONE to use a transition model". | No base turbulence model. | Set `KIND_TURB_MODEL= SST` or `SA` (code). | +| SU2 stops: "Option KIND_TRANS_MODEL=BC is deprecated". | Old config. | Use `KIND_TURB_MODEL= SA` with `SA_OPTIONS= BCM` (code). | +| Changing `FREESTREAM_INTERMITTENCY` does nothing. | The option is not used by the solver. | Leave it out (code). | +| An old config stops with "invalid option name" for `EXT_ITER`. | `EXT_ITER` was replaced. | Use `ITER` for steady runs (code). | + +## Related tutorials and test cases + +Tutorials: + +- [Transitional Flat Plate for T3A and T3A-](/tutorials/Transitional_Flat_Plate_T3A/): SST with LM, comparison with ERCOFTAC skin friction data. +- [Transitional Flat Plate](/tutorials/Transitional_Flat_Plate/): SA with the BC model (`SA_OPTIONS= BCM`), Schubauer and Klebanoff flat plate. +- E387 airfoil with LM, SA and SST versions: [Tutorials repository folder](https://github.com/su2code/Tutorials/tree/develop/compressible_flow/Transitional_Airfoil/Langtry_and_Menter/E387) (no tutorial page yet). + +Test cases (develop branch): + +- [transition/Schubauer_Klebanoff/transitional_BC_model_ConfigFile.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/transition/Schubauer_Klebanoff/transitional_BC_model_ConfigFile.cfg): BC model, incompressible, regression test. +- [rans/s809/trans_s809.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/rans/s809/trans_s809.cfg): S809 airfoil with SA and LM. This config is older and is not in the regression tests. It uses options that develop no longer accepts: `EXT_ITER` (replace it with `ITER`), `SOLUTION_LIN_FILENAME`, `RESTART_LIN_FILENAME` and `SURFACE_LIN_FILENAME` (delete them) (code). Its `FREESTREAM_INTERMITTENCY` line has no effect (code). + +User guide pages: + +- [Transition Models](../Transition-Models/) and [Turbulence Models](../Turbulence-Models/). +- [Governing Equations](../Theory/), [Convective Schemes](../Convective-Schemes/), [History and Solution Output](../Custom-Output/). +- All options: [Option Reference](../Option-Reference/). All output fields: [Output Fields Reference](../Output-Fields-Reference/). + +Source review: 22 October 2026, against [SU2 `docs_site` at `41ea6a219a`](https://github.com/rois1995/SU2/tree/41ea6a219ac038574f3d4a5b130c0c1d8af66457). See the [review scope and outstanding validation](../Documentation-Status/#guide-and-model-review). Setup recommendations remain draft where indicated. diff --git a/_docs_v7/Setup-Guide-Turbomachinery.md b/_docs_v7/Setup-Guide-Turbomachinery.md new file mode 100644 index 00000000..1d247f2e --- /dev/null +++ b/_docs_v7/Setup-Guide-Turbomachinery.md @@ -0,0 +1,307 @@ +--- +title: "Setup Guide: Turbomachinery" +permalink: /docs_v7/Setup-Guide-Turbomachinery/ +--- + +{% include setup-guide-intro.md %} + +--- + +- [When to use this guide](#when-to-use-this-guide) +- [Start from](#start-from) +- [Settings that matter](#settings-that-matter) +- [Check convergence and results](#check-convergence-and-results) +- [Common problems](#common-problems) +- [Related tutorials and test cases](#related-tutorials-and-test-cases) + +--- + +## When to use this guide + +Use this guide to set up a steady simulation of a blade row, or of a machine with several blade rows: compressors, turbines, stages of axial or radial machines, and linear cascades. The guide covers the turbomachinery features of the compressible solvers (`SOLVER= EULER`, `NAVIER_STOKES` or `RANS`). + +Terms used below: + +- **Blade row** (or zone): the mesh of one blade passage of one row, for example a stator or a rotor. +- **Mixing plane**: an interface between two rows that passes averaged flow values from one row to the next. It makes a steady stage simulation possible. +- **Span-wise section**: a band at constant height between hub and shroud. SU2 averages the flow on each band of an inlet, outlet or mixing plane. +- **Non-reflecting boundary**: a boundary that lets pressure waves leave the domain instead of bouncing back. + +## Start from + +The block below comes from the regression test [turbomachinery/axial_stage_2D](https://github.com/su2code/SU2/blob/develop/TestCases/turbomachinery/axial_stage_2D/Axial_stage2D.cfg). It is a 2D axial stage (a stator and a moving row) with a mixing plane, Giles boundaries and the SST model. We removed the comments, most output settings, and the options that are at their default value or have no effect in this setup. The mesh file `mesh_axial_stage_2d_turb.su2` is in the [TestCases repository](https://github.com/su2code/TestCases). + +Main file, `Axial_stage2D.cfg`: + +``` +MULTIZONE= YES +CONFIG_LIST= (zone_1.cfg, zone_2.cfg) +% +SOLVER= RANS +KIND_TURB_MODEL= SST +MATH_PROBLEM= DIRECT +RESTART_SOL= NO +% +MACH_NUMBER= 0.05 +FREESTREAM_PRESSURE= 140000.0 +FREESTREAM_TEMPERATURE= 300.0 +FREESTREAM_OPTION= TEMPERATURE_FS +FREESTREAM_TURBULENCEINTENSITY= 0.03 +FREESTREAM_TURB2LAMVISCRATIO= 100.0 +INIT_OPTION= TD_CONDITIONS +REF_DIMENSIONALIZATION= DIMENSIONAL +% +FLUID_MODEL= IDEAL_GAS +GAMMA_VALUE= 1.4 +GAS_CONSTANT= 287.058 +VISCOSITY_MODEL= SUTHERLAND +MU_REF= 1.716E-5 +MU_T_REF= 273.15 +SUTHERLAND_CONSTANT= 110.4 +CONDUCTIVITY_MODEL= CONSTANT_PRANDTL +% +MARKER_HEATFLUX= (wall1, 0.0, wall2, 0.0) +MARKER_PERIODIC= (periodic1, periodic2, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.04463756775, 0.0, periodic3, periodic4, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.04463756775, 0.0) +% +MARKER_TURBOMACHINERY= (inflow, outmix, inmix, outflow) +MARKER_ANALYZE= (outflow) +MARKER_ZONE_INTERFACE= (outmix, inmix) +MARKER_MIXINGPLANE_INTERFACE= (outmix, inmix) +MARKER_GILES= (inflow, TOTAL_CONDITIONS_PT, 169623.33, 305.76, 1.0, 0.0, 0.0, 1.0, 1.0, outmix, MIXING_OUT, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 1.0, inmix, MIXING_IN, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 1.0, outflow, STATIC_PRESSURE, 99741.00, 0.0, 0.0, 0.0, 0.0, 1.0, 1.0) +SPATIAL_FOURIER= NO +TURBOMACHINERY_KIND= AXIAL AXIAL +TURBO_PERF_KIND= TURBINE TURBINE +TURBULENT_MIXINGPLANE= YES +AVERAGE_PROCESS_KIND= MIXEDOUT +PERFORMANCE_AVERAGE_PROCESS_KIND= MIXEDOUT +MIXEDOUT_COEFF= (1.0, 1.0E-05, 15) +AVERAGE_MACH_LIMIT= 0.05 +% +NUM_METHOD_GRAD= WEIGHTED_LEAST_SQUARES +CFL_NUMBER= 10.0 +LINEAR_SOLVER= FGMRES +LINEAR_SOLVER_PREC= LU_SGS +LINEAR_SOLVER_ERROR= 1E-4 +LINEAR_SOLVER_ITER= 10 +CONV_NUM_METHOD_FLOW= ROE +MUSCL_FLOW= YES +RAMP_MUSCL= YES +RAMP_MUSCL_COEFF= (0.0, 1.0, 20.0) +SLOPE_LIMITER_FLOW= VAN_ALBADA_EDGE +ENTROPY_FIX_COEFF= 0.01 +CONV_NUM_METHOD_TURB= SCALAR_UPWIND +MUSCL_TURB= NO +% +% The test stops after 21 outer iterations. Raise OUTER_ITER for a converged result. +OUTER_ITER= 21 +CONV_RESIDUAL_MINVAL= -16 +CONV_STARTITER= 10 +SCREEN_OUTPUT= OUTER_ITER, AVG_BGS_RES[0], AVG_BGS_RES[1], RMS_DENSITY[0], RMS_ENERGY[0], RMS_DENSITY[1], RMS_ENERGY[1], SURFACE_TOTAL_PRESSURE[1], MassFlowOut_2[1], TotalStaticEfficiency[1] +MESH_FILENAME= mesh_axial_stage_2d_turb.su2 +MESH_FORMAT= SU2 +OUTPUT_WRT_FREQ= 1000 +``` + +Zone file of the fixed row, `zone_1.cfg`: + +``` +GRID_MOVEMENT= NONE +``` + +Zone file of the moving row, `zone_2.cfg`. In 2D the rotor is a row that translates along y: + +``` +GRID_MOVEMENT= STEADY_TRANSLATION +MACH_MOTION= 0.35 +TRANSLATION_RATE= 0.0 -150.0 0.0 +``` + +For a 3D machine, start from the [Aachen turbine tutorial](/tutorials/Aachen_Turbine/) or from the test case [turbomachinery/Aachen_turbine](https://github.com/su2code/SU2/blob/develop/TestCases/turbomachinery/Aachen_turbine/aachen_3D_MP_restart.cfg). That case restarts from a solution file (`RESTART_SOL= YES`). Set `RESTART_SOL= NO` to start from scratch. + +## Settings that matter + +### Mesh and machine axis + +- For 3D turbomachinery, align the machine axis with z. The Aachen axial-flow example uses flow along positive z; radial machines also have a radial flow component, and the 2D translating-row example uses the x–y plane (tutorial, code). The code computes the radius as the distance from the z-axis when it builds the span-wise sections. The rotation ramp changes only the z component of `ROTATION_RATE` (code). +- Mesh one blade passage per row, and connect its sides with `MARKER_PERIODIC` (tutorial). For a rotational periodicity, give the rotation centre and the rotation angle about each axis, in degrees. The Aachen case has 41 blades per row and uses an angle of 360/41 = 8.7804878 about z (test case). +- In 3D, list the periodic pairs in `MARKER_PERIODIC` in zone order: the first pair for zone 1, the second pair for zone 2, and so on. The code that finds the span-wise sections of zone *n* looks at the *n*-th periodic pair (code, to be reviewed). All 3D test cases follow this order (test case). + +### Single row or several rows + +- **One row.** Use a single config file. Even with one row, you need `MARKER_TURBOMACHINERY= (inlet, outlet)` to use Giles boundaries or turbomachinery outputs (code). Example: [transonic_stator_2D](https://github.com/su2code/SU2/blob/develop/TestCases/turbomachinery/transonic_stator_2D/transonic_stator_restart.cfg) (test case). +- **Several rows.** Put each row in its own zone. Set `MULTIZONE= YES` and list one sub-config file per zone in `CONFIG_LIST`, in stream-wise order (tutorial). A sub-config file holds only the options that differ from the main file, usually the grid motion. See [Basics of Multi-Zone Computations](../Multizone/). +- In multizone runs, `OUTER_ITER` sets the number of iterations. `INNER_ITER` (default 1) is the number of iterations of each zone per outer iteration (code). + +### Rotating frame or moving mesh + +Choose the motion of each zone with `GRID_MOVEMENT` in its sub-config file (code): + +- `ROTATING_FRAME`: the mesh does not move. SU2 solves the flow in a frame that turns with the rotor. Use it for steady simulations of rotors (tutorial). Set `ROTATION_RATE` (rad/s, vector), `MOTION_ORIGIN` and `MACH_MOTION`. +- `STEADY_TRANSLATION`: the 2D version of `ROTATING_FRAME`, for a row that moves along a straight line. Set `TRANSLATION_RATE` (m/s) (test case). +- `RIGID_MOTION`: the mesh really moves. This needs a time-accurate simulation (`TIME_DOMAIN= YES`) and sliding interfaces between zones (`MARKER_FLUID_INTERFACE`). See the [sliding_interface](https://github.com/su2code/SU2/tree/develop/TestCases/sliding_interface) test cases (test case). This guide does not cover unsteady rotor-stator runs. +- `NONE`: no motion, for stators. + +`MACH_MOTION` is a Mach number based on the speed of the moving mesh. The [multizone page](../Multizone/) says that SU2 uses it to initialize a viscous flow from the Reynolds number, and to compute force coefficients on moving meshes (docs). The test cases use 0.35 (test case). + +For the stator zones, the Aachen and APU turbocharger test cases set `GRID_MOVEMENT= ROTATING_FRAME` with no rotation rate, and the 2D axial stage uses `NONE`. Both work (test case). + +Use `MARKER_SHROUD` to list the shroud walls. In a rotating zone, SU2 sets the grid velocity to zero on these markers, so that the shroud does not turn with the rotor (code, tutorial). + +### Interfaces between rows + +Every interface between two zones needs two lists. Give the markers in pairs (upstream marker, downstream marker), in stream-wise order (tutorial): + +- `MARKER_ZONE_INTERFACE` tells SU2 that the two markers are connected. +- One of these two options sets the kind of interface (code): + - `MARKER_MIXINGPLANE_INTERFACE`: mixing plane. SU2 passes averaged values for each span-wise section from one row to the next. + - `MARKER_FLUID_INTERFACE`: frozen rotor, where the rows keep a fixed position relative to each other. SU2 interpolates the local values, with no averaging (to be reviewed). The test case [multi_interface](https://github.com/su2code/SU2/blob/develop/TestCases/turbomachinery/multi_interface/multi_interface_rst.cfg) uses one interface of each kind (test case). + +Mixing-plane options: + +- `MIXINGPLANE_INTERFACE_KIND` sets how SU2 maps the span-wise sections of one side onto the other: `NEAREST_SPAN` (default), `LINEAR_INTERPOLATION` or `MATCHING` (code). The test cases use `LINEAR_INTERPOLATION` (test case). `MATCHING` probably needs the same span-wise sections on both sides (to be reviewed). +- `TURBULENT_MIXINGPLANE= YES` also passes the turbulence variables across the mixing plane. The default is `NO` (code). All turbulent test cases set `YES` (test case). +- On the mixing-plane markers, also set a Giles condition: `MIXING_OUT` on the upstream side and `MIXING_IN` on the downstream side (tutorial). + +### Turbomachinery markers + +- `MARKER_TURBOMACHINERY`: the inlet and the outlet marker of every zone, zone by zone, in stream-wise order: (inlet zone 1, outlet zone 1, inlet zone 2, outlet zone 2, ...) (tutorial). +- `TURBOMACHINERY_KIND`: the shape of each row, one entry per zone: `AXIAL`, `CENTRIFUGAL`, `CENTRIPETAL`, `CENTRIPETAL_AXIAL` or `AXIAL_CENTRIFUGAL`. SU2 uses it to decide which coordinate measures the span (code). Example: the radial turbine of the APU turbocharger test uses `CENTRIPETAL CENTRIPETAL_AXIAL` (test case). +- `TURBO_PERF_KIND`: the kind of machine for the performance outputs, one entry per zone: `TURBINE`, `COMPRESSOR` or `PROPELLOR`. SU2 stops with "Insufficient TURBO_PERF_KIND options" if there are fewer entries than zones (code). +- `MARKER_ANALYZE`: markers where SU2 writes surface-averaged values such as `SURFACE_TOTAL_PRESSURE` (tutorial). `MARKER_ANALYZE_AVERAGE` chooses `AREA` or `MASSFLUX` (default) averaging for these outputs (code). + +### Inlet and outlet boundaries: Giles or Riemann + +Both conditions are based on characteristics, that is, on the waves that enter and leave the domain. They work with any fluid model. The plain `MARKER_INLET` and `MARKER_OUTLET` work only with ideal gases (code). + +**`MARKER_GILES`** is the non-reflecting condition for turbomachinery (tutorial). + +- It works only together with `MARKER_TURBOMACHINERY`. Without it, SU2 stops with "Giles Boundary conditions can only be used with turbomachinery markers" (code). +- Format, 9 values per marker: (marker, kind, value 1, value 2, direction 1, direction 2, direction 3, average relaxation, Fourier relaxation) (tutorial). +- The last two values under-relax the update of the averaged state and of the Fourier modes: SU2 applies only this fraction of each update. The test cases use 1.0 in 2D. On most boundaries of the 3D Aachen case they use 0.3 (average) and 0.0 (Fourier) (test case). +- `SPATIAL_FOURIER= YES` makes the condition non-reflecting for the circumferential waves too. With `NO` (default), it acts as a 1D characteristic condition (code). The Aachen tutorial keeps it off (tutorial). +- `GILES_EXTRA_RELAXFACTOR` = (relaxation factor, span fraction) adds extra under-relaxation near hub and shroud in 3D. The default is (0.1, 0.1). SU2 limits the span fraction to 0.5 (code). The Aachen case uses (0.05, 0.05) (test case). + +Kinds of Giles boundary (code): + +| Kind | Use | Values | +|---|---|---| +| `TOTAL_CONDITIONS_PT` | inlet | total pressure, total temperature, flow direction (normal, tangential, span-wise components) | +| `TOTAL_CONDITIONS_PT_1D` | inlet | same, imposed on the average of the whole boundary | +| `STATIC_PRESSURE` | outlet | static pressure, imposed on each span-wise section | +| `STATIC_PRESSURE_1D` | outlet | static pressure, imposed on the average of the whole boundary | +| `RADIAL_EQUILIBRIUM` | outlet (3D) | static pressure at mid-span; SU2 builds the span-wise pressure profile from the radial equilibrium of the averaged flow | +| `MASS_FLOW_OUTLET` | outlet | target mass flow (value 1) and a relaxation factor (value 2) | +| `MIXING_IN`, `MIXING_OUT` | mixing plane, averages for each span-wise section | none (write zeros) | +| `MIXING_IN_1D`, `MIXING_OUT_1D` | mixing plane, average of the whole boundary | none (write zeros) | + +The `_1D` kinds impose only the average over the whole boundary, so the span-wise profile is free to develop. The tutorial uses `STATIC_PRESSURE_1D` on an outlet "where the flow is in radial equilibrium" (tutorial). + +**`MARKER_RIEMANN`** is a characteristic condition with 7 values per marker: (marker, kind, value 1, value 2, direction 1, direction 2, direction 3). It accepts these kinds (code): + +- Without turbomachinery markers: `TOTAL_CONDITIONS_PT`, `STATIC_PRESSURE`, `DENSITY_VELOCITY`, `STATIC_SUPERSONIC_INFLOW_PT` and `STATIC_SUPERSONIC_INFLOW_PD`. +- With turbomachinery markers, SU2 uses an averaged version of the condition on the finest mesh. It accepts `TOTAL_CONDITIONS_PT`, `STATIC_PRESSURE`, `RADIAL_EQUILIBRIUM`, `MIXING_IN` and `MIXING_OUT`. +- Any other kind stops the run with "Invalid Riemann input!". + +Which one to choose: the turbomachinery test cases and the Aachen tutorial use `MARKER_GILES` (test case, tutorial). Giles boundaries can sit closer to the blades than reflecting ones (advice, to be reviewed). + +### Averaging + +- `AVERAGE_PROCESS_KIND` sets how SU2 averages the flow on Giles boundaries and mixing planes: `ALGEBRAIC`, `AREA` (default), `MASSFLUX` or `MIXEDOUT` (code). The tutorial says that only `MIXEDOUT` makes the mixing plane conservative (tutorial). All test cases use `MIXEDOUT` (test case). +- `PERFORMANCE_AVERAGE_PROCESS_KIND` sets the same for the performance outputs. The default is `AREA` (code). +- `MIXEDOUT_COEFF` = (relaxation factor, tolerance, maximum iterations) of the Newton method for the mixed-out average. The default is (1.0, 1.0E-05, 15) (code). +- `AVERAGE_MACH_LIMIT` (default 0.03): when the Mach number normal to the boundary is below this value, the `MASSFLUX` and `MIXEDOUT` averages fall back to the `AREA` average. This matters at the start of a run, when the flow is still slow. Below this limit SU2 also skips the Fourier part of the Giles condition (code). + +### Span-wise sections (3D) + +SU2 builds the span-wise sections as follows (code): + +- `SPANWISE_KIND= AUTOMATIC` (default): SU2 counts the mesh points along the span where the inlet or outlet meets the periodic boundary, and makes one section per point. This suits meshes with the same span-wise point distribution on both sides of an interface (to be reviewed). +- `SPANWISE_KIND= EQUISPACED`: SU2 makes `NUM_SPANWISE_SECTIONS` sections of equal height between hub and shroud. +- In 2D, SU2 always uses one section. + +### Ramps + +Ramps help when the machine has a high pressure ratio or a high rotation speed (tutorial). A ramp approaches the final value from a prescribed start value, using the configured update interval and ramp length. + +The ramp options (code): + +- `RAMP_MOTION_FRAME= YES` ramps the rotation speed (z component of `ROTATION_RATE`) or, with `STEADY_TRANSLATION`, the y component of `TRANSLATION_RATE`. +- `RAMP_OUTLET= YES` ramps the outlet value of Giles `STATIC_PRESSURE`, `STATIC_PRESSURE_1D`, `RADIAL_EQUILIBRIUM` and `MASS_FLOW_OUTLET` boundaries. The Aachen tutorial text calls this option `RAMP_OUTLET_PRESSURE`, but the option in the code is `RAMP_OUTLET`. +- `RAMP_MOTION_FRAME_COEFF` and `RAMP_OUTLET_COEFF` = (start value, update every N iterations, length of the ramp in iterations). The defaults are (100.0, 1.0, 1000.0) and (100000.0, 1.0, 1000.0). Always set them. + +The test values are `RAMP_MOTION_FRAME_COEFF= (0.0, 39.0, 500)` and `RAMP_OUTLET_COEFF= (140000.0, 150.0, 2000)` (test case). + +Limits of the ramps (code): + +- In multizone runs, the ramp follows the outer iteration. +- The rotation ramp acts only when `MARKER_TURBOMACHINERY` is set. +- The outlet ramp does not work on `MARKER_RIEMANN` outlets. SU2 stops with "Outlet pressure ramp only implemented for NRBC". +- SU2 does not set up these two ramps in discrete adjoint runs. + +`RAMP_MUSCL` is a different ramp: it blends from first-order to second-order space discretization. The 2D stage uses `RAMP_MUSCL_COEFF= (0.0, 1.0, 20.0)` = (start iteration, update every N iterations, ramp length) (test case). + +### Initialization and numerics + +- Use `INIT_OPTION= TD_CONDITIONS` with `FREESTREAM_PRESSURE` and `FREESTREAM_TEMPERATURE` near the inlet state, and a small `MACH_NUMBER` (0.05 in the test cases) (test case). The default `INIT_OPTION= REYNOLDS` recomputes the pressure from the Reynolds number (code), which does not suit internal flows (advice). Check the initial state that SU2 prints before the first iteration (tutorial). +- The test cases use `ROE` with `MUSCL_FLOW= YES` (2D stage, transonic stator) or `JST` (Aachen). Their CFL numbers range from 2 (Aachen) to 50 (transonic stator) (test case). +- SU2 applies the Giles and the averaged Riemann conditions only on the finest mesh (code). Most turbomachinery test cases run without multigrid; the Aachen restart test uses `MGLEVEL= 1` (test case). If a run with multigrid is unstable, try `MGLEVEL= 0` (to be reviewed). +- Wall functions (`MARKER_WALL_FUNCTIONS`) let the Aachen tutorial run on a coarse mesh with high y+ (tutorial). + +### Performance outputs + +- Add `TURBO_PERF` to `HISTORY_OUTPUT` to write the performance values to the history file (test case). +- Values per row carry the row number, starting at 1: `MassFlowIn_1`, `MassFlowOut_1`, `TotalPressureIn_1`, `AbsFlowAngleOut_1`, `KineticEnergyLoss_1`, `TotPressureLoss_1`, ... (code). +- Values for the whole machine: `TotalStaticEfficiency`, `TotalTotalEfficiency`, `PressureRatioTS`, `PressureRatioTT`, `EulerianWork`, `EntropyGeneration`, `KineticEnergyLoss_Stage`, `TotPressureLoss_Stage` (code). +- In multizone runs, these fields belong to the last zone. Write them with the index of the last zone, for example `TotalStaticEfficiency[1]` for two zones (test case). +- Every 100 iterations, SU2 prints a table of the performance of each row and of the machine (code). +- SU2 writes span-wise profiles (`inflow_spanwise_thermodynamic_values*.dat`, `outflow_spanwise_kinematic_values*.dat`, ...) and mixing-plane interpolation details into a folder named `TURBOMACHINERY` (code). SU2 does not create this folder. Create it in the run directory before you start, otherwise these files are not written (to be reviewed). +- `WRT_ZONE_HIST= YES` writes one history file per zone (tutorial). + +The full list of fields is on the [output fields](../Output-Fields-Reference/) page. The options are on the [option reference](../Option-Reference/) page. + +## Check convergence and results + +- **Stop criterion.** Use residuals, for example `CONV_FIELD= RMS_ENERGY[0]` with `CONV_RESIDUAL_MINVAL` (test case). SU2 checks convergence only on residual fields and coefficient fields. The turbomachinery performance fields are neither, so do not put them in `CONV_FIELD`. The `MARKER_ANALYZE` fields, such as `SURFACE_MASSFLOW`, are coefficients and work with the Cauchy criterion (`CONV_CAUCHY_ELEMS`, `CONV_CAUCHY_EPS`) (code). +- **Residuals.** Watch the residuals of every zone (`RMS_DENSITY[0]`, `RMS_DENSITY[1]`, ...) and the coupling residuals (`AVG_BGS_RES[0]`, ...) (test case). +- **Mass flow.** `MassFlowIn_n` and `MassFlowOut_n` of each row should agree, and the outlet of one row should match the inlet of the next (advice). +- **Performance.** Efficiency and pressure ratio should no longer change over the last few hundred iterations (advice). +- **Span-wise profiles.** Compare the profiles in the `TURBOMACHINERY` folder with the values you imposed, for example the outlet pressure (advice). +- **Ramps.** If you used ramps, run well past the end of the ramp before you read the results (advice). + +See [Solver Setup](../Solver-Setup/) for the convergence options. + +## Common problems + +| Symptom | Likely cause | What to try | +|---|---|---| +| SU2 stops: "Giles Boundary conditions can only be used with turbomachinery markers". | `MARKER_TURBOMACHINERY` is missing (code). | Add the inlet and outlet markers of every zone. | +| SU2 stops: "Insufficient TURBO_PERF_KIND options specified with turbomachinery markers". | There are fewer `TURBO_PERF_KIND` entries than zones (code). | Give one entry per zone. Do the same for `TURBOMACHINERY_KIND`. | +| SU2 stops: "Outlet pressure ramp only implemented for NRBC". | `RAMP_OUTLET= YES` with a `MARKER_RIEMANN` static-pressure outlet (code). | Use a Giles outlet (NRBC means non-reflecting boundary condition), or switch the ramp off. | +| SU2 stops: "Invalid Riemann input!" | A Riemann kind that this boundary does not support (code). | Check the lists in [Inlet and outlet boundaries](#inlet-and-outlet-boundaries-giles-or-riemann). | +| The run diverges in the first iterations. | A large pressure ratio or a high rotation speed at start-up (tutorial). | Use `RAMP_OUTLET` and `RAMP_MOTION_FRAME`, lower `CFL_NUMBER`, start first order and use `RAMP_MUSCL` (advice, to be reviewed). | +| The flow near hub or shroud is unstable in 3D with Giles. | Strong span-wise gradients at the endwalls (advice, to be reviewed). | Lower `GILES_EXTRA_RELAXFACTOR` and the average relaxation factor of the Giles markers, as in the Aachen case (0.05 and 0.3) (test case). | +| Efficiency or mass flow look wrong in the first iterations. | The flow is slow, so the averages use the area average (code). | Wait until the flow develops. Check `AVERAGE_MACH_LIMIT`. | +| The ramp has no effect. | A discrete adjoint run, or no `MARKER_TURBOMACHINERY` for the rotation ramp, or the machine axis is not z (code). | Run the direct solver, with turbomachinery markers and the z-axis as machine axis. | +| Wrong or missing span-wise sections, or a crash while SU2 sets up the turbomachinery boundaries. | The periodic pairs are not in zone order, or the mesh has no matching span-wise points for `AUTOMATIC` (code, to be reviewed). | Order `MARKER_PERIODIC` by zone. Try `SPANWISE_KIND= EQUISPACED`. | +| No span-wise `.dat` files. | The `TURBOMACHINERY` folder does not exist (code). | Create it in the run directory. | +| Reverse flow at the outlet. | The outlet is too close to the blade, or the outlet pressure is too high (advice, to be reviewed). | Move the outlet downstream. Check the outlet pressure value. | + +## Related tutorials and test cases + +Tutorials: + +- [Aachen turbine stage with mixing plane](/tutorials/Aachen_Turbine/): 3D, three rows, Giles boundaries, ramps, wall functions, performance outputs. +- [Non-ideal compressible flows with physics-informed neural networks](/tutorials/NICFD_nozzle_datadriven/): uses Giles boundaries and an outlet ramp on a nozzle. + +Test cases (SU2 repository): + +- [turbomachinery/axial_stage_2D](https://github.com/su2code/SU2/blob/develop/TestCases/turbomachinery/axial_stage_2D/Axial_stage2D.cfg): 2D stage, mixing plane, translating row. +- [turbomachinery/Aachen_turbine](https://github.com/su2code/SU2/blob/develop/TestCases/turbomachinery/Aachen_turbine/aachen_3D_MP_restart.cfg): 3D, three rows, rotating frame, wall functions. +- [turbomachinery/APU_turbocharger](https://github.com/su2code/SU2/blob/develop/TestCases/turbomachinery/APU_turbocharger/Jones_restart.cfg): radial turbine, rotation ramp. +- [turbomachinery/multi_interface](https://github.com/su2code/SU2/blob/develop/TestCases/turbomachinery/multi_interface/multi_interface_rst.cfg): one frozen-rotor and one mixing-plane interface. +- [turbomachinery/transonic_stator_2D](https://github.com/su2code/SU2/blob/develop/TestCases/turbomachinery/transonic_stator_2D/transonic_stator_restart.cfg): single row, Peng-Robinson gas, Giles boundaries with `SPATIAL_FOURIER= YES`. +- [disc_adj_turbomachinery](https://github.com/su2code/SU2/tree/develop/TestCases/disc_adj_turbomachinery): discrete adjoint of a stator and of a stage, with the objectives `TOTAL_PRESSURE_LOSS` and `ENTROPY_GENERATION`. + +User guide pages: [Basics of Multi-Zone Computations](../Multizone/), [Markers and Boundary Conditions](../Markers-and-BC/), [Solver Setup](../Solver-Setup/), [History and Solution Output](../Custom-Output/), [Setup Guide: Non-Ideal Compressible Flows](../Setup-Guide-NICFD/). + +Source review: 22 October 2026, against [SU2 `docs_site` at `41ea6a219a`](https://github.com/rois1995/SU2/tree/41ea6a219ac038574f3d4a5b130c0c1d8af66457). See the [review scope and outstanding validation](../Documentation-Status/#guide-and-model-review). Setup recommendations remain draft where indicated. diff --git a/_docs_v7/Setup-Guide-Unsteady-DES.md b/_docs_v7/Setup-Guide-Unsteady-DES.md new file mode 100644 index 00000000..e95199df --- /dev/null +++ b/_docs_v7/Setup-Guide-Unsteady-DES.md @@ -0,0 +1,382 @@ +--- +title: "Setup Guide: Unsteady Flows and DES" +permalink: /docs_v7/Setup-Guide-Unsteady-DES/ +--- + +{% include setup-guide-intro.md %} + +--- + +- [When to use this guide](#when-to-use-this-guide) +- [Start from](#start-from) +- [Settings that matter](#settings-that-matter) +- [Check convergence and results](#check-convergence-and-results) +- [Common problems](#common-problems) +- [Related tutorials and test cases](#related-tutorials-and-test-cases) + +--- + +## When to use this guide + +Use this guide when the flow changes in time and you want to follow that change. Typical cases are: + +- vortex shedding behind a bluff body or a stalled airfoil, +- buffet, large separated regions, wakes, +- bodies that move, such as a pitching airfoil. + +Unsteady simulations can also use `SOLVER= EULER` for inviscid flow, or `SOLVER= NAVIER_STOKES` for laminar viscous flow. The general time-stepping controls below apply to these cases too. + +The examples below focus on two turbulence-modelling approaches: + +- **URANS** (unsteady RANS): the RANS equations solved in time. The turbulence model still models all turbulent eddies. URANS captures large, regular unsteadiness such as vortex shedding (advice). +- **DES** (detached eddy simulation), a hybrid RANS/LES method: RANS near the walls, large-eddy simulation (LES) in separated regions. In LES, the mesh and the time step resolve the large turbulent eddies and the model handles only the small ones (advice). + +A steady RANS run that does not converge can be a sign that the flow is unsteady (advice). For steady settings, see [Setup Guide: Steady RANS for External Aerodynamics](../Setup-Guide-RANS-External-Aero/). + +## Start from + +### URANS + +This config comes from the unsteady NACA0012 tutorial: `compressible_flow/Unsteady_NACA0012/unsteady_naca0012.cfg` in the [Tutorials repository](https://github.com/su2code/Tutorials/blob/develop/compressible_flow/Unsteady_NACA0012/unsteady_naca0012.cfg). +We changed `RESTART_SOL` to `NO` and removed `RESTART_ITER`, so the run starts from the free stream. The tutorial restarts at time step 499 to skip the start-up phase. We also removed the adjoint and file name options. All other values are unchanged. + +``` +% ------------- Problem ------------------------------------------------% +SOLVER= RANS +KIND_TURB_MODEL= SA +REF_DIMENSIONALIZATION= DIMENSIONAL +MATH_PROBLEM= DIRECT +RESTART_SOL= NO +% +% ------------- Free stream --------------------------------------------% +MACH_NUMBER= 0.3 +AOA= 17.0 +FREESTREAM_TEMPERATURE= 293.0 +FREESTREAM_PRESSURE= 101325.0 +REYNOLDS_NUMBER= 1000.0 +REYNOLDS_LENGTH= 1.0 +REF_ORIGIN_MOMENT_X= 0.25 +REF_ORIGIN_MOMENT_Y= 0.00 +REF_ORIGIN_MOMENT_Z= 0.00 +REF_LENGTH= 1.0 +REF_AREA= 1.0 +% +% ------------- Boundary conditions ------------------------------------% +MARKER_HEATFLUX= ( airfoil, 0.0 ) +MARKER_FAR= ( farfield ) +MARKER_PLOTTING= ( airfoil ) +MARKER_MONITORING= ( airfoil ) +% +% ------------- Time integration (dual time stepping) ------------------% +TIME_DOMAIN= YES +TIME_MARCHING= DUAL_TIME_STEPPING-2ND_ORDER +TIME_STEP= 5e-4 +TIME_ITER= 2000 +INNER_ITER= 10 +% +% ------------- Numerics -----------------------------------------------% +NUM_METHOD_GRAD= WEIGHTED_LEAST_SQUARES +CONV_NUM_METHOD_FLOW= JST +JST_SENSOR_COEFF= ( 0.5, 0.005 ) +CONV_NUM_METHOD_TURB= SCALAR_UPWIND +MUSCL_TURB= NO +TIME_DISCRE_FLOW= EULER_IMPLICIT +TIME_DISCRE_TURB= EULER_IMPLICIT +CFL_NUMBER= 1e12 +CFL_ADAPT= NO +LINEAR_SOLVER= FGMRES +LINEAR_SOLVER_ERROR= 0.1 +LINEAR_SOLVER_ITER= 10 +% +% ------------- Convergence inside each time step ----------------------% +CONV_FIELD= REL_RMS_DENSITY +CONV_RESIDUAL_MINVAL= -3 +CONV_STARTITER= 0 +% +% ------------- Time averages and convergence in time ------------------% +WINDOW_CAUCHY_CRIT= YES +WINDOW_START_ITER= 500 +WINDOW_FUNCTION= HANN_SQUARE +CONV_WINDOW_FIELD= ( TAVG_DRAG, TAVG_LIFT ) +CONV_WINDOW_STARTITER= 0 +CONV_WINDOW_CAUCHY_EPS= 1E-4 +CONV_WINDOW_CAUCHY_ELEMS= 10 +% +% ------------- Input and output ---------------------------------------% +MESH_FILENAME= unsteady_naca0012_mesh.su2 +MESH_FORMAT= SU2 +HISTORY_WRT_FREQ_INNER= 0 +SCREEN_WRT_FREQ_INNER= 100 +SCREEN_OUTPUT= ( TIME_ITER, INNER_ITER, RMS_DENSITY, REL_RMS_DENSITY, DRAG, LIFT, CAUCHY_TAVG_DRAG, CAUCHY_TAVG_LIFT ) +HISTORY_OUTPUT= ( TIME_ITER, INNER_ITER, REL_RMS_RES, RMS_RES, AERO_COEFF, TAVG_AERO_COEFF, CAUCHY ) +OUTPUT_FILES= ( RESTART, PARAVIEW ) +OUTPUT_WRT_FREQ= ( 1, 1 ) +``` + +The tutorial page [Unsteady NACA0012](/tutorials/Unsteady_NACA0012/) explains dual time stepping and the windowed averages. + +### DES + +This config comes from the DDES regression test [`TestCases/ddes/flatplate/ddes_flatplate.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/ddes/flatplate/ddes_flatplate.cfg). We removed the adjoint and file name options, and options that have no effect with these settings. All other values are unchanged. +This is a 2D flat plate. It checks that the DES options run. It is not a realistic DES: real DES runs are 3D (see [Mesh for DES](#mesh-for-des)). + +``` +% ------------- Problem ------------------------------------------------% +SOLVER= RANS +KIND_TURB_MODEL= SA +HYBRID_RANSLES= SA_EDDES +MATH_PROBLEM= DIRECT +RESTART_SOL= NO +% +% ------------- Free stream --------------------------------------------% +MACH_NUMBER= 0.2 +AOA= 0.0 +SIDESLIP_ANGLE= 0.0 +FREESTREAM_TEMPERATURE= 300.0 +REYNOLDS_NUMBER= 5000000.0 +REYNOLDS_LENGTH= 1.0 +REF_ORIGIN_MOMENT_X= 0.25 +REF_ORIGIN_MOMENT_Y= 0.00 +REF_ORIGIN_MOMENT_Z= 0.00 +REF_LENGTH= 1.0 +REF_AREA= 2.0 +% +% ------------- Time integration ---------------------------------------% +TIME_DOMAIN= YES +TIME_MARCHING= DUAL_TIME_STEPPING-2ND_ORDER +TIME_STEP= 0.000288 +MAX_TIME= 10 +UNST_CFL_NUMBER= 0.0 +INNER_ITER= 20 +TIME_ITER= 500 +% +% ------------- Boundary conditions ------------------------------------% +MARKER_HEATFLUX= ( wall, 0.0 ) +MARKER_INLET= ( inlet, 302.4, 118309.784, 1.0, 0.0, 0.0 ) +MARKER_OUTLET= ( outlet, 115056.0, farfield, 115056.0 ) +MARKER_SYM= ( symmetry ) +MARKER_PLOTTING= ( wall ) +MARKER_MONITORING= ( wall ) +% +% ------------- Numerics -----------------------------------------------% +NUM_METHOD_GRAD= GREEN_GAUSS +CFL_NUMBER= 10.0 +CFL_ADAPT= NO +CONV_NUM_METHOD_FLOW= SLAU2 +MUSCL_FLOW= YES +SLOPE_LIMITER_FLOW= NONE +TIME_DISCRE_FLOW= EULER_IMPLICIT +CONV_NUM_METHOD_TURB= SCALAR_UPWIND +MUSCL_TURB= NO +TIME_DISCRE_TURB= EULER_IMPLICIT +CONV_RESIDUAL_MINVAL= -15 +CONV_STARTITER= 0 +% +% ------------- Input and output ---------------------------------------% +MESH_FILENAME= mesh_flatplate_turb_137x97.su2 +MESH_FORMAT= SU2 +OUTPUT_WRT_FREQ= 1000 +SCREEN_OUTPUT= (TIME_ITER, INNER_ITER, RMS_DENSITY, RMS_NU_TILDE, LIFT, DRAG, TOTAL_HEATFLUX) +``` + +For a real DES run, also write the DES and time-average fields (code): + +``` +VOLUME_OUTPUT= ( COORDINATES, SOLUTION, PRIMITIVE, DDES, VORTEX_IDENTIFICATION, TIME_AVERAGE ) +``` + +The mesh files of the test cases are in the [TestCases repository](https://github.com/su2code/TestCases). + +## Settings that matter + +### Dual time stepping + +Dual time stepping splits the run into physical time steps. Inside each time step, SU2 runs "inner iterations" to find the new solution, the same way it converges a steady problem (tutorial, docs). + +- `TIME_DOMAIN= YES` turns on the time-accurate solver (docs). `TIME_MARCHING= DUAL_TIME_STEPPING-2ND_ORDER` is used by all URANS and DES test cases (test case). `DUAL_TIME_STEPPING-1ST_ORDER` and `TIME_STEPPING` (one update per time step, no inner iterations) also exist (code). +- `TIME_STEP` is the physical time step. It is always in seconds, also when the equations are non-dimensional: SU2 divides it by the reference time (code). +- `TIME_ITER` is the number of time steps. The default is `1` (code). +- `MAX_TIME` is the final physical time in seconds. The default is `1.0`. SU2 stops at `MAX_TIME` or at `TIME_ITER`, whichever comes first (code, docs). Set `MAX_TIME` larger than `TIME_STEP` × `TIME_ITER` if you want `TIME_ITER` steps. +- `INNER_ITER` is the maximum number of inner iterations per time step. The default is `1` (code). Always set it. +- Do not use `ITER` in an unsteady run. SU2 stops with an error and asks for `TIME_ITER` and `INNER_ITER` (code). +- With `UNST_CFL_NUMBER` other than `0.0`, SU2 computes the time step from this CFL number and ignores `TIME_STEP`, as the comments in `config_template.cfg` say. The default is `0.0` (code). + +See [Solver Setup](../Solver-Setup/#time-dependent-simulation). + +### Time step size + +- The time step must resolve the fastest change you care about (advice). For vortex shedding, estimate the period from the Strouhal number St = f D / U. St is about 0.2 for many bluff bodies (advice, to be reviewed). +- Use at least 50 to 100 time steps per shedding period for URANS (advice, to be reviewed). +- Check the result by halving the time step: the period and the averaged forces should not change much (advice). +- Examples: the NACA0012 tutorial uses `TIME_STEP= 5e-4`. The square cylinder test uses `TIME_STEP= 0.0015` with `MAX_TIME= 3.75`. The von Karman cylinder tutorial uses `TIME_STEP= 0.005` with 20 inner iterations (tutorial, test case). + +### Convergence inside each time step + +Each time step needs converged inner iterations. If not, the time history is wrong even if the run looks stable (tutorial). + +- The inner loop uses the same criteria as a steady run: `CONV_FIELD`, `CONV_RESIDUAL_MINVAL`, `CONV_STARTITER` (docs). It stops at the criterion or at `INNER_ITER`. +- `REL_RMS_DENSITY` is the residual relative to its value at the first inner iteration of the time step (code). `CONV_FIELD= REL_RMS_DENSITY` with `CONV_RESIDUAL_MINVAL= -3` asks for a drop of three orders of magnitude in each time step (tutorial). +- Set `CONV_STARTITER= 0` so the check starts at the first inner iteration (tutorial). The default is `5` (code). +- The inner iterations use `CFL_NUMBER` as in a steady run. The NACA0012 tutorial uses `CFL_NUMBER= 1e12` with `JST` (tutorial). The DES test uses `10` with `SLAU2`, the square cylinder test `2.0` with `ROE` (test case). +- Watch `INNER_ITER` on the screen. If most time steps end at the maximum without reaching the criterion, raise `INNER_ITER` or the CFL, or lower the time step (advice). +- In a time-domain run, SU2 writes the history file once per time step by default. Set `HISTORY_WRT_FREQ_INNER` to also write inner iterations (code). + +### Restarting an unsteady run + +SU2 writes one restart file per saved time step, with the step number in the name, for example `restart_flow_00499.dat` (tutorial, docs). + +- `OUTPUT_WRT_FREQ` sets how often (in time steps) SU2 writes files (docs). With second-order time stepping, SU2 also writes the step before, because a restart needs two old solutions (code). +- To restart, set `RESTART_SOL= YES` and `RESTART_ITER` to the first new time step. With second order, SU2 reads the files of steps `RESTART_ITER`−2 and `RESTART_ITER`−1. With first order, it reads step `RESTART_ITER`−1 (code, docs). +- SU2 reads the files named after `SOLUTION_FILENAME`, so rename or copy the restart files first (docs). +- `TIME_ITER` counts from the start of the whole simulation, not from the restart. SU2 runs `TIME_ITER` − `RESTART_ITER` more steps (code). `TIME_ITER` must be larger than `RESTART_ITER` (code). +- To start URANS from a converged steady solution, copy the steady restart file to the two file names that SU2 reads for `RESTART_ITER= 2` (for example `solution_flow_00000.dat` and `solution_flow_00001.dat`) (advice, to be reviewed). The square cylinder test restarts with `RESTART_ITER= 2` (test case). + +See [Restart File](../Restart-File/). + +### Time averages and convergence in time + +**History averages.** In a time-domain run, SU2 adds a time-averaged version of every coefficient, with the prefix `TAVG_`, for example `TAVG_DRAG` (code, tutorial). + +- The average starts at time step `WINDOW_START_ITER`. If you do not set it, it starts at `RESTART_ITER`. It must not be smaller than `RESTART_ITER`, or SU2 stops with an error (code). +- Start the average after the start-up phase, when the signal is periodic or statistically steady (tutorial). +- `WINDOW_FUNCTION` sets the weight of each sample: `SQUARE` (equal weights, the default), `HANN`, `HANN_SQUARE` or `BUMP` (code). For a periodic signal, the windowed averages converge faster than `SQUARE` (tutorial). + +**Stop when the average stops changing.** `WINDOW_CAUCHY_CRIT= YES` turns on a Cauchy criterion on the averages (docs). This criterion looks at how much the average changes from step to step. + +- `CONV_WINDOW_FIELD` lists the averaged fields, for example `( TAVG_DRAG, TAVG_LIFT )` (tutorial). +- `CONV_WINDOW_CAUCHY_EPS` (default `1E-3`), `CONV_WINDOW_CAUCHY_ELEMS` (default `100`) and `CONV_WINDOW_STARTITER` (default `15`, counted from `WINDOW_START_ITER`) play the same role as `CONV_CAUCHY_EPS`, `CONV_CAUCHY_ELEMS` and `CONV_STARTITER` in a steady run (code, docs). +- The tutorial uses `CONV_WINDOW_CAUCHY_EPS= 1E-4` with `CONV_WINDOW_CAUCHY_ELEMS= 10` (tutorial). + +**Volume averages.** Add `TIME_AVERAGE` to `VOLUME_OUTPUT` (code). SU2 then writes: + +- mean values: `MEAN_DENSITY`, `MEAN_VELOCITY-X`, `MEAN_VELOCITY-Y`, `MEAN_VELOCITY-Z`, `MEAN_PRESSURE`, `MEAN_SKIN_FRICTION-X`, `MEAN_SKIN_FRICTION-Y`, `MEAN_SKIN_FRICTION-Z`; +- mean squares and products: `RMS_U`, `RMS_V`, `RMS_W`, `RMS_UV`, `RMS_UW`, `RMS_VW`, `RMS_P`; +- Reynolds stresses and pressure fluctuations: `UUPRIME`, `VVPRIME`, `WWPRIME`, `UVPRIME`, `UWPRIME`, `VWPRIME`, `PPRIME` (code). + +How these averages work (code): + +- They start at `WINDOW_START_ITER` and use equal weights. `WINDOW_FUNCTION` does not apply to them. +- SU2 only computes them if `TIME_AVERAGE` is in `VOLUME_OUTPUT`. +- SU2 keeps them in memory. They are not read back from the restart files, so after a restart they start again from `RESTART_ITER`. + +So average over one continuous run, without restarts (advice). + +### Hybrid RANS/LES: which DES variant + +All DES variants in SU2 develop build on the SA model. Set `KIND_TURB_MODEL= SA` and pick a variant with `HYBRID_RANSLES` (code). + +In original `SA_DES`, the length scale is min(d, C_DES Δ), where d is wall distance and Δ the grid measure. The delayed variants use d − f_d·max(0, d − C_DES Δ): f_d near zero protects attached boundary layers, and f_d near one recovers the DES limit. The grid measure also changes with the variant. Thus distance from the wall alone does not determine the RANS/LES mode (code, reference). See [Hybrid RANS/LES](../Hybrid-RANS-LES/#what-su2-does-differently-from-the-literature). + +| `HYBRID_RANSLES` | What it is (code) | +| --- | --- | +| `NONE` | No DES (default). | +| `SA_DES` | Original DES (Spalart 1997). Switches to LES wherever the cell size times `DES_CONST` is below the wall distance. | +| `SA_DDES` | Delayed DES (Spalart et al. 2006). A shielding function keeps attached boundary layers in RANS mode. | +| `SA_ZDES` | DDES with a cell size based on the vorticity direction (Deck 2012). | +| `SA_EDDES` | DDES with a cell size adapted to shear layers (Shur et al. 2015). Meant to switch faster from RANS to LES in separated shear layers. | + +Advice: + +- `SA_DES` can switch to LES inside an attached boundary layer if the mesh is fine along the wall. The mesh, not the flow, can then cause separation. `SA_DDES` and `SA_EDDES` add shielding to reduce this risk; the result still needs mesh and sensor checks (advice). +- `SA_ZDES` in SU2 is DDES with the ZDES cell size. It is not the full zonal method of the reference, where the user picks RANS and LES zones (code, to be reviewed). +- SU2 does not stop with an error if you set `HYBRID_RANSLES` with `KIND_TURB_MODEL= SST`. Only the SA solver uses the DES length scale, so such a run is plain URANS (code). + +Related options (code): + +- `DES_CONST`: the DES constant. The default is `0.65`. +- `LES_FILTER_WIDTH`: a fixed LES filter width. The default `-1.0` means SU2 uses the local cell size (the largest distance from a point to its neighbours). +- `ENFORCE_LES= YES`: LES mode everywhere. It needs `HYBRID_RANSLES` other than `NONE`. +- `STOCHASTIC_BACKSCATTER= YES` and the `SBS_` options: a stochastic backscatter model, which feeds energy from the modelled to the resolved scales. It works only in 3D and only with `HYBRID_RANSLES` set. The test case `backscatter/backward_step/backwardStep.cfg` shows all its options (code, test case). + +### Mesh for DES + +General points for the DES mesh (advice, to be reviewed): + +- DES resolves turbulent eddies, which are three-dimensional. Run DES in 3D. 2D DES runs do not give physical turbulence. +- Near the walls, the mesh must be fine enough for RANS: first-cell y+ about 1. +- In the regions you want in LES mode (wakes, separated zones), use cells of similar size in all directions. Original DES/DDES use the longest edge from a node to its neighbours; ZDES/EDDES use the variant-specific measures described in [Hybrid RANS/LES](../Hybrid-RANS-LES/#what-su2-does-differently-from-the-literature) (code). Stretched cells can limit LES resolution; inspect the chosen grid measure and the RANS/LES sensor rather than assuming that refinement in one direction is sufficient. +- Keep the cell size changes smooth between the RANS and LES regions. +- For a body with a spanwise direction, the spanwise extent must hold the largest eddies of interest. + +### Time step for DES + +- The time step must resolve the eddies the mesh can hold. A common target is a convective CFL number of about 1 in the LES region, that is, a time step of about cell size / local velocity (advice, to be reviewed). +- Use `DUAL_TIME_STEPPING-2ND_ORDER` (test case). +- The DES and backscatter tests use `INNER_ITER= 20` (test case). Check the inner convergence as for URANS. + +### Numerical dissipation + +Reduce numerical dissipation where you can. Upwind schemes and limiters add it, and in the LES region it damps the resolved eddies (advice). + +**Compressible solver.** `ROE_LOW_DISSIPATION` lowers the upwind part of the flux where the flow is resolved (code, docs). Details from the code (code): + +- It works with `ROE`, `SLAU` and `SLAU2`. +- `FD`: uses the DDES shielding function, computed from the wall distance. +- `NTS`: the blending of Travin and Shur. It uses `DES_CONST` and the cell size. +- `FD_DUCROS` and `NTS_DUCROS`: as above, plus the Ducros sensor, which keeps the full dissipation at shocks (code, docs). +- SU2 keeps at least 5 % of the upwind dissipation for stability. +- Write the `ROE_DISSIPATION` output group to see where the dissipation is reduced. + +No test case in develop uses `ROE_LOW_DISSIPATION` (test case). + +**Incompressible solver.** The `LD2` central scheme (low dissipation, low dispersion) is available for constant density flows only. With the energy equation on, SU2 uses JST for the energy equation (code). The backscatter test uses `CONV_NUM_METHOD_FLOW= LD2` with `JST_SENSOR_COEFF= ( 0.0, 0.002 )` and `MUSCL_FLOW= NO` (test case). + +**Limiters.** The DES flat plate test uses MUSCL without a limiter (`SLOPE_LIMITER_FLOW= NONE`) (test case). A limiter adds dissipation where it is active (advice). + +### Averaging a DES run + +- Wait until the start-up phase has left the domain before you start averaging. A common rule is a few flow-through times (advice, to be reviewed). +- Then average over many characteristic times, so that the mean and the fluctuations settle (advice). +- Use `WINDOW_START_ITER` and the `TIME_AVERAGE` volume group described above (code). +- To record time signals at points, the history output can include probes defined with `CUSTOM_OUTPUTS`. The von Karman cylinder tutorial shows how (tutorial). + +## Check convergence and results + +- **Inner convergence.** `REL_RMS_DENSITY` (or your `CONV_FIELD`) reaches the criterion in each time step before `INNER_ITER` (tutorial). +- **Start-up phase over.** Plot `LIFT` and `DRAG` against time. The signal should be periodic or statistically steady before `WINDOW_START_ITER` (tutorial). +- **Averages settled.** Compare averages from separate sampling blocks and extend the sampling interval. A slowly changing cumulative average alone does not establish statistical convergence, especially for DES. Monitor `TAVG_LIFT` and `TAVG_DRAG`. With `WINDOW_CAUCHY_CRIT= YES`, the `CAUCHY_TAVG_` values are below `CONV_WINDOW_CAUCHY_EPS` (tutorial). +- **Time step and mesh.** Halve the time step and refine the mesh. The frequency and the averages should change little (advice). +- **DES regions.** Write the `DDES` group: `DES_LENGTHSCALE`, `WALL_DISTANCE` and `LES_SENSOR`. `LES_SENSOR` is 0 where the model acts as RANS. In LES mode it is 1 for `SA_DES` and the value of the shielding function for the DDES variants (code). Attached boundary layers should stay at 0 (advice). +- **Resolved eddies.** Write the `VORTEX_IDENTIFICATION` group: `VORTICITY` (2D) or `VORTICITY_X`, `VORTICITY_Y`, `VORTICITY_Z` (3D), and `Q_CRITERION` (code). Iso-surfaces of `Q_CRITERION` show the resolved eddies (advice). + +See [History and Solution Output](../Custom-Output/) and the [Output Fields Reference](../Output-Fields-Reference/). + +## Common problems + +| Symptom | Likely cause | What to try | +| --- | --- | --- | +| The run stops at 1 s of physical time. | `MAX_TIME` has a default of `1.0`. | Set `MAX_TIME` (code). | +| Only one inner iteration per time step. | `INNER_ITER` has a default of `1`. | Set `INNER_ITER` (code). | +| SU2 stops: "ITER must not be used when running multizone and/or unsteady problems". | `ITER` in an unsteady config. | Use `TIME_ITER` and `INNER_ITER` (code). | +| SU2 stops: "TIME_DOMAIN must be set to YES ..." | `TIME_MARCHING` set without `TIME_DOMAIN= YES`. | Add `TIME_DOMAIN= YES` (code). | +| SU2 stops: "Invalid value for TIME_STEP". | `TIME_STEP` is zero and `UNST_CFL_NUMBER` is `0.0`. | Set `TIME_STEP` (code). | +| The restart fails to find a file. | Wrong file names or missing step. | For `RESTART_ITER= N` with second order, provide steps N−2 and N−1, named after `SOLUTION_FILENAME` (code, docs). | +| SU2 stops: "WINDOW_START_ITER must be larger than or equal to: RESTART_ITER!" | The average would start before the restart. | Set `WINDOW_START_ITER` at or after `RESTART_ITER` (code). | +| `MEAN_` fields are missing or zero. | `TIME_AVERAGE` not in `VOLUME_OUTPUT`, or the run has not reached `WINDOW_START_ITER`. | Add `TIME_AVERAGE` and check `WINDOW_START_ITER` (code). | +| The flow stays steady and symmetric, no shedding. | Symmetric start, too much numerical dissipation, too large time step, or a coarse wake mesh. | Lower the dissipation, reduce the time step, refine the wake (advice, to be reviewed). | +| The inner iterations never reach the criterion. | Time step too large, or CFL too low for the inner loop. | Reduce `TIME_STEP`, raise `CFL_NUMBER` or `INNER_ITER` (advice). | +| DES: the boundary layer separates too early. | LES mode inside the attached boundary layer (check `LES_SENSOR`). | Use `SA_DDES` or `SA_EDDES` instead of `SA_DES`; check the cell size along the wall (advice). | +| DES: the wake looks smooth, with no resolved eddies. | Too much dissipation, or the mesh is too coarse or too stretched in the wake. | Use `ROE_LOW_DISSIPATION` or `LD2`, remove the limiter, refine the wake with near-cubic cells (advice, to be reviewed). | +| DES has no effect at all. | `HYBRID_RANSLES` set with `KIND_TURB_MODEL= SST`. | Use `KIND_TURB_MODEL= SA` (code). | + +## Related tutorials and test cases + +Tutorials: + +- [Unsteady NACA0012](/tutorials/Unsteady_NACA0012/): URANS, dual time stepping, windowed averages, restart after the start-up phase. +- [Unsteady von Karman vortex shedding](/tutorials/Inc_Von_Karman/): laminar incompressible cylinder; time step, inner iterations, probes. +- [Unsteady shape optimization NACA0012](/tutorials/Unsteady_Shape_Opt_NACA0012/): unsteady adjoint with windowed objective functions. + +Test cases (develop branch): + +- [unsteady/square_cylinder/turb_square.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/unsteady/square_cylinder/turb_square.cfg): URANS with SST and `ROE`, restart from step 2. +- [unsteady/pitching_naca64a010_rans/turb_NACA64A010.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/unsteady/pitching_naca64a010_rans/turb_NACA64A010.cfg): URANS of a pitching airfoil with SA and rigid mesh motion. +- [ddes/flatplate/ddes_flatplate.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/ddes/flatplate/ddes_flatplate.cfg): `SA_EDDES` with `SLAU2`. +- [backscatter/backward_step/backwardStep.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/backscatter/backward_step/backwardStep.cfg): incompressible `SA_DDES` with stochastic backscatter, `LD2` scheme and time-average output. + +User guide pages: + +- [Solver Setup](../Solver-Setup/), [Restart File](../Restart-File/), [History and Solution Output](../Custom-Output/), [Convective Schemes](../Convective-Schemes/), [Physical Definition](../Physical-Definition/). +- All options: [Option Reference](../Option-Reference/). All output fields: [Output Fields Reference](../Output-Fields-Reference/). + +Source review: 22 October 2026, against [SU2 `docs_site` at `41ea6a219a`](https://github.com/rois1995/SU2/tree/41ea6a219ac038574f3d4a5b130c0c1d8af66457). See the [review scope and outstanding validation](../Documentation-Status/#guide-and-model-review). Setup recommendations remain draft where indicated. diff --git a/_docs_v7/Solver-Setup.md b/_docs_v7/Solver-Setup.md index 65a0c996..71f35c45 100644 --- a/_docs_v7/Solver-Setup.md +++ b/_docs_v7/Solver-Setup.md @@ -13,8 +13,9 @@ This is a basic introduction on how to set up a simulation using SU2. We disting - [Time-dependent Simulation](#time-dependent-simulation) - [Steady-state Simulation](#steady-state-simulation) - [Setting convergence criteria](#setting-convergence-criteria) - - [Residual](#residual) - - [Coefficient](#coefficient) + - [Steady-state Residual](#steady-state-residual) + - [Steady-state Coefficient](#steady-state-coefficient) + - [Time-dependent Coefficient](#time-dependent-coefficient) --- @@ -36,7 +37,7 @@ SU2 is capable of dealing with different kinds of physical problems. The kind of |`INC_EULER` | **Incompressible Euler's equation** | Finite-Volume method | |`INC_NAVIER_STOKES` | **Incompressible Navier-Stokes' equation** | Finite-Volume method| |`INC_RANS` | **Incompressible Reynolds-averaged Navier-Stokes' equation** | Finite-Volume method| -|`HEAT_EQUATION_FVM` | **Heat equation** | Finite-Volume method | +|`HEAT_EQUATION` | **Heat equation** | Finite-Volume method | |`ELASTICITY` | **Equations of elasticity** | Finite-Element method | |`FEM_EULER` | **Euler's equation** | Discontinuous Galerkin FEM | |`FEM_NAVIER_STOKES`| **Navier-Stokes' equation** | Discontinuous Galerkin FEM | diff --git a/_docs_v7/Streamwise-Periodicity.md b/_docs_v7/Streamwise-Periodicity.md index e239e87b..9b2b336f 100644 --- a/_docs_v7/Streamwise-Periodicity.md +++ b/_docs_v7/Streamwise-Periodicity.md @@ -14,10 +14,10 @@ This page contains an overview of the theory behind streamwise periodic flow and - [Limitations](#limitations) - [Introduction](#introduction) -- [Pressure and Velocity Periodiciy](#pandv-periodiciy) - - [Massflow prescription](#massflow) -- [Temperature Periodiciy](#T-periodiciy) - - [Fake temperature periodicity via outlet heat sink](#fake-temperature-periodicity-via-outlet-heat-sink) +- [Pressure and Velocity Periodicity](#pressure-and-velocity-periodicity) + - [Massflow prescription](#massflow-prescription) +- [Temperature Periodicity](#temperature-periodicity) + - [Temperature periodicity via outlet heat sink](#temperature-periodicity-via-outlet-heat-sink) - [References](#references) --- @@ -71,7 +71,7 @@ $$\Delta p_0^{n+1} = \Delta p_0^{n} + \phi \Delta \left( \Delta p_0 \right).$$ ## Temperature Periodicity -The here presented approach for periodicity in temperature is only possible if only heatflux or symmetry boundary conditions are used, isothermal walls in particular are not allowed. In that case use the [method described below](#fake-temperature-periodicity-via-outlet-heat-sink) is used: +The here presented approach for periodicity in temperature is only possible if only heatflux or symmetry boundary conditions are used, isothermal walls in particular are not allowed. In that case use the [method described below](#temperature-periodicity-via-outlet-heat-sink): Similar to the pressure term for the momentum equation the Temperature can be split in a periodic and a linear part: diff --git a/_docs_v7/Theory.md b/_docs_v7/Theory.md index c03d7ddc..b6515ca3 100644 --- a/_docs_v7/Theory.md +++ b/_docs_v7/Theory.md @@ -233,7 +233,7 @@ Within the `INC_EULER` solver, we discretize the equations in space using a fini Available for `RANS`, `INC_RANS`. -SU2 implements several variants of the SST and SA turbulence models, for specifics of the models please see the [NASA Turbulence Modeling Resource](https://turbmodels.larc.nasa.gov/index.html) (TMR). +SU2 implements several variants of the SST and SA turbulence models, for specifics of the models please see the [NASA Turbulence Modeling Resource](https://tmbwg.github.io/turbmodels/index.html) (TMR). For information on how to use turbulence models in SU2 see the [users guide](https://su2code.github.io/docs_v7/Physical-Definition/). The edge-based finite volume discretization of flow solvers is also used in turbulence solvers. Convective fluxes are evaluated using a scalar upwind scheme (1st or 2nd order). diff --git a/_docs_v7/Tracy-Integration.md b/_docs_v7/Tracy-Integration.md index ba95983c..8a62dbd9 100644 --- a/_docs_v7/Tracy-Integration.md +++ b/_docs_v7/Tracy-Integration.md @@ -21,7 +21,7 @@ To compile SU2 with Tracy support, follow these steps: - Configure the build with Tracy enabled using Meson: ```bash - ./meson.py setup build -Dwith-mpi=disabled --buildtype=debugoptimized -Denable-tracy=true --prefix= + ./meson.py setup build -Dwith-mpi=disabled --buildtype=debugoptimized -Dtracy_enable=true --prefix= ``` - Build and install SU2: ```bash diff --git a/_docs_v7/Transition-Models.md b/_docs_v7/Transition-Models.md new file mode 100644 index 00000000..2c9f984b --- /dev/null +++ b/_docs_v7/Transition-Models.md @@ -0,0 +1,186 @@ +--- +title: Transition Models +permalink: /docs_v7/Transition-Models/ +--- + +This page explains the model and its SU2 implementation. For numerical setup choices, see the [setup guide](../Setup-Guide-Transition/); use its tutorial and V&V links for worked examples and comparisons. + +A turbulence model alone treats the boundary layer as turbulent from the leading edge. A transition model lets the boundary layer start laminar and become turbulent further downstream, where a transition criterion is met. SU2 has two transition models: the Langtry-Menter (LM) model, which adds two transport equations and works with SST or SA, and the algebraic Bas-Cakmakcioglu model (SA-BCM), which only changes the SA equation. + +--- + +- [Select a model](#select-a-model) +- [Langtry-Menter (LM)](#langtry-menter-lm) +- [Bas-Cakmakcioglu (SA-BCM)](#bas-cakmakcioglu-sa-bcm) +- [What SU2 does differently from the literature](#what-su2-does-differently-from-the-literature) +- [Free-stream and inlet values](#free-stream-and-inlet-values) +- [Verification and test cases](#verification-and-test-cases) +- [Known limits](#known-limits) +- [Related pages](#related-pages) + +--- + +## Select a model + +Both models need `SOLVER= RANS` or `SOLVER= INC_RANS` and a turbulence model (see [Turbulence Models](../Turbulence-Models/)). + +| Model | Settings | +| --- | --- | +| LM with SST | `KIND_TURB_MODEL= SST`, `KIND_TRANS_MODEL= LM` | +| LM with SA | `KIND_TURB_MODEL= SA`, `KIND_TRANS_MODEL= LM` | +| SA-BCM | `KIND_TURB_MODEL= SA`, `SA_OPTIONS= BCM` (leave `KIND_TRANS_MODEL` at `NONE`) | + +- `KIND_TRANS_MODEL` takes `NONE` (the default) or `LM`. With `KIND_TURB_MODEL= NONE`, SU2 stops with an error. +- The old setting `KIND_TRANS_MODEL= BC` is no longer accepted. SU2 stops and tells you to use `SA_OPTIONS= BCM`. + + + +This page describes the SU2 develop branch. Availability here is determined by this source revision; options from another branch may differ. + +## Langtry-Menter (LM) + +The LM model solves two extra equations: + +- the intermittency gamma (`INTERMITTENCY` in the output): 0 where the boundary layer is laminar, 1 where it is turbulent; +- the transition onset momentum-thickness Reynolds number Re_theta_t (`RE_THETA_T`): the value of Re_theta at which transition starts, carried from the free stream into the boundary layer. + +The model uses gamma to damp the production of turbulence in the boundary layer. The [TMR page of the LM model](https://tmbwg.github.io/turbmodels/langtrymenter_4eqn.html) gives the equations. + +Original papers: + +- R. B. Langtry and F. R. Menter, "Correlation-Based Transition Modeling for Unstructured Parallelized Computational Fluid Dynamics Codes", AIAA Journal 47(12), 2009, pp. 2894-2906. +- Crossflow extension (`LM2015`): R. B. Langtry, K. Sengupta, D. T. Yeh and A. J. Dorgan, AIAA 2015-2474. + +### LM_OPTIONS keywords + +`LM_OPTIONS` takes a list. With an empty list, SU2 runs the 2009 model with the default correlation of the turbulence model. + +**Version.** + +- `LM2015` adds the correction for stationary crossflow instabilities. It works only in 3D; in 2D SU2 stops with an error. +- `LM2015` uses `HROUGHNESS`, the RMS height of the surface roughness (default `1e-6`). SU2 divides it by a momentum thickness, so give it in the length unit of the mesh (to be reviewed). + +**Correlation** (at most one; SU2 stops with an error if you give two). The correlations give the critical Reynolds number Re_theta_c and the length of the transition zone from Re_theta_t. The table shows the reference that SU2 prints at start-up. + +| Keyword | Reference printed by SU2 | Notes | +| --- | --- | --- | +| `MENTER_LANGTRY` | Menter and Langtry (2009) | Default with SST. | +| `MALAN` | Malan et al. (2009) | Default with SA. | +| `SULUKSNA` | Suluksna et al. (2009) | | +| `KRAUSE` | Krause et al. (2008) | Meant for hypersonic flows (to be reviewed). | +| `KRAUSE_HYPER` | Krause et al. (2008, paper) | Meant for hypersonic flows (to be reviewed). Depends on the turbulence intensity. | +| `MEDIDA_BAEDER` | Medida and Baeder (2011) | Developed for SA (to be reviewed). Depends on the turbulence intensity. | +| `DEFAULT` | | Same as giving no correlation. | +| `NONE` | | No effect. | + + + +The code also contains a `MEDIDA` correlation (Medida PhD, 2014), but `MEDIDA` is not an accepted keyword in develop. + +Example: `LM_OPTIONS= LM2015, MENTER_LANGTRY`. + +Keep the default correlation unless a validation for your type of flow supports another one (to be reviewed). + +## Bas-Cakmakcioglu (SA-BCM) + +SA-BCM is an algebraic model: it solves no extra equation. It multiplies the production term of SA by an intermittency function, gamma_BC. This function depends on the local vorticity Reynolds number, the eddy viscosity and the free-stream turbulence intensity. SU2 implements the 2020 version listed on the [TMR SA-BCM page](https://tmbwg.github.io/turbmodels/sa-bc_1eqn.html). + +- SA-BCM is built on SA-noft2. SU2 stops with an error if you combine `BCM` with `WITHFT2`, `ROTATION`, `COMPRESSIBILITY`, `QCR2000` or `NEGATIVE`, unless you add `EXPERIMENTAL`. +- The volume field `INTERMITTENCY` (group `INTERMITTENCY`) is registered for SA-BCM, but currently reads a getter that returns zero. It does not show the computed BCM intermittency; do not use it to locate transition. The LM intermittency fields are separate and do not have this getter problem. + + + +Original papers: + +- S. C. Cakmakcioglu, O. Bas, R. Mura and U. Kaynak, AIAA 2020-2706. +- R. Mura and S. C. Cakmakcioglu, AIAA 2020-2714. + +## What SU2 does differently from the literature + +### LM with SST + +- **Base model.** The TMR LM model is built on SST-2003. In SU2 the SST model is always the "m" form (no turbulent kinetic energy in the stress tensor), and the default is `V2003m`. The T3A tutorial uses the default; the E387 tutorial with SST uses `V1994m`. See [Turbulence Models](../Turbulence-Models/#what-su2-does-differently-from-the-literature). +- **Coupling to SST**, as in the TMR: SU2 multiplies the production of k by the effective intermittency gamma_eff, and the destruction of k by min(max(gamma_eff, 0.1), 1). gamma_eff is the larger of gamma and the separation-induced intermittency gamma_sep. The omega equation is unchanged. The blending function F1 is replaced by max(F1, F3), with F3 = exp(-(Ry/120)^8) and Ry = rho y sqrt(k) / mu, where y is the wall distance. +- **Turbulence intensity.** SU2 computes the local intensity from k: Tu = 100 sqrt(2k/3) / U, in percent, and keeps it at 0.027 % or above. + +### LM with SA + +The LM model was published for SST. SU2 also couples it to SA, which has no k. This coupling differs from the SST one: + +- **Turbulence intensity.** Tu is `FREESTREAM_TURBULENCEINTENSITY` (times 100) everywhere in the domain. It does not decay. +- **Onset and length functions.** For the ratio R_t, SU2 uses mu_t/mu in place of rho k/(mu omega). The onset function is capped at 4 instead of 2, and its third part is max(2 - (R_t/2.5)^3, 0) instead of max(1 - (R_t/2.5)^3, 0). The length function has no sublayer blending, and the wake function is 1. +- **Coupling to SA.** SU2 multiplies the SA production by gamma_eff, and the SA destruction by min(max(gamma, 0.5), 1), where gamma is the transported intermittency. The closest TMR model, [SA-noft2-Gamma-Retheta](https://tmbwg.github.io/turbmodels/sa_gamma_retheta_3eqn.html), puts no intermittency factor on the destruction term. The TMR says an older form of that factor, max(min(gamma, 0.5), 1), is always 1. A comment in the SU2 code makes the same point and asks whether the published form is wrong. +- SU2 does not check which SA variant you use with LM. + + + +### Both LM couplings + +- **Free-stream values.** The free-stream intermittency is always 1. SU2 computes the free-stream Re_theta_t from `FREESTREAM_TURBULENCEINTENSITY` with the zero-pressure-gradient Langtry-Menter correlation. `FREESTREAM_INTERMITTENCY` is printed at start-up but has no effect. +- **Inlets.** At inlets, SU2 uses the free-stream values of gamma and Re_theta_t. `MARKER_INLET_TURBULENT` changes the inlet k and omega (or nu-tilde), but not the LM variables. +- **Walls.** No flux of gamma or Re_theta_t crosses a wall (zero normal gradient). +- **LM2015.** The crossflow correction also limits the time scale of the Re_theta_t equation with the local grid length. + +### SA-BCM + +SU2 follows the TMR description: + +- the critical Reynolds number is Re_theta_c = 803.73 (Tu + 0.6067)^-1.027, with Tu in percent from `FREESTREAM_TURBULENCEINTENSITY` (times 100), constant in the domain; +- chi_1 = 0.002; SU2 multiplies mu_t/mu by 50 in the second intermittency term, equivalent to dividing by the TMR value chi_2 = 0.02; +- the destruction term is not changed; +- the free-stream nu-tilde is 0.005 times the usual SA value. With the default `FREESTREAM_NU_FACTOR= 3`, this gives 0.015 times the kinematic viscosity, the low end of the TMR range (0.015 to 0.025). + + + +If you set both `SA_OPTIONS= BCM` and `KIND_TRANS_MODEL= LM`, SU2 gives no error. It solves the LM equations, but the SA source term uses the BCM intermittency. Do not combine them. + +## Free-stream and inlet values + +| Option | Default | Used by | Meaning | +| --- | --- | --- | --- | +| `FREESTREAM_TURBULENCEINTENSITY` | `0.05` | LM, SA-BCM, SST | Turbulence intensity as a fraction: `0.001` means 0.1 %. SU2 multiplies it by 100 inside the correlations. | +| `FREESTREAM_TURB2LAMVISCRATIO` | `10.0` | SST | Eddy viscosity over laminar viscosity, used for the free-stream omega. | +| `FREESTREAM_NU_FACTOR` | `3.0` | SA | Free-stream nu-tilde over kinematic viscosity (times 0.005 with BCM). | +| `HROUGHNESS` | `1e-6` | LM with `LM2015` | RMS roughness height. | +| `FREESTREAM_INTERMITTENCY` | `1.0` | none | No effect on LM or BCM. | + + + +- The default intensity of 5 % is high for most external flows. Set it to the value of your experiment or flight condition (to be reviewed). +- With SST, k decays between the far field and the body, so the intensity at the leading edge is lower than the far-field value. Check it in the output (Tu = sqrt(2k/3)/U from the `TKE` field) (to be reviewed). +- With SA (LM or BCM), the intensity is the same everywhere. Give the value expected at the body (to be reviewed). + +[Setup Guide: Laminar-Turbulent Transition](../Setup-Guide-Transition/) gives more advice on these values, on the mesh and on convergence. + +## Verification and test cases + +- V&V page: [Langtry and Menter transition model](/vandv/LM_transition/) (T3A, T3B, T3A-, NLF0416 and E387 cases, compared with another code). +- Tutorials: + - [Transitional Flat Plate](/tutorials/Transitional_Flat_Plate/): SA-BCM on the Schubauer-Klebanoff flat plate. + - [Transitional Flat Plate for T3A and T3A-](/tutorials/Transitional_Flat_Plate_T3A/): LM with SST. + - E387 airfoil with LM, with SA and with SST: config files in the [Tutorials repository](https://github.com/su2code/Tutorials/tree/develop/compressible_flow/Transitional_Airfoil/Langtry_and_Menter/E387). The tutorial regression tests run both. +- Test cases: + - SA-BCM, incompressible: [TestCases/transition](https://github.com/su2code/SU2/tree/develop/TestCases/transition) (Schubauer-Klebanoff, T3A, E387). The regression tests run the Schubauer-Klebanoff case. Note: these configs give `FREESTREAM_TURBULENCEINTENSITY` as a percent value (`0.18`, `3.0`, `0.1`), while SU2 reads it as a fraction. The tutorial sets `0.0018` for the same Schubauer-Klebanoff flow. Do not copy these values. + - LM with SA on the S809 airfoil: [trans_s809.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/rans/s809/trans_s809.cfg). The regression scripts do not run it. + + + +## Known limits + +- Only LM and SA-BCM are available in develop. +- **LM has no discrete adjoint.** Do not combine `KIND_TRANS_MODEL= LM` with `MATH_PROBLEM= DISCRETE_ADJOINT`: the required transition solver is not created, and the run can crash during setup. See [the developer guide](../Adding-a-Transition-Model/#discrete-adjoint). +- **SA-BCM intermittency output is zero** in this code version, so it is not a transition-location diagnostic (see [SA-BCM](#bas-cakmakcioglu-sa-bcm)). +- LM uses the velocity magnitude and its streamwise gradient. The TMR notes that the model is therefore not Galilean invariant: results depend on the frame of reference (to be reviewed for moving walls and rotating frames). +- `LM2015` works only in 3D. +- LM with SA uses one constant turbulence intensity in the whole domain. So does SA-BCM. +- The LM correlations are built from low-speed experiments. For crossflow, supersonic and hypersonic transition, check the model against data for your flow (to be reviewed). + +## Related pages + +- [Setup Guide: Laminar-Turbulent Transition](../Setup-Guide-Transition/) and [Setup Guide: Steady RANS for External Aerodynamics](../Setup-Guide-RANS-External-Aero/) +- [Turbulence Models](../Turbulence-Models/) +- All options: [Option Reference](../Option-Reference/). All output fields: [Output Fields Reference](../Output-Fields-Reference/) (`INTERMITTENCY`, `RE_THETA_T`, `INTERMITTENCY_SEP`, `INTERMITTENCY_EFF`, `TURB_INDEX`). +- For developers: [Adding a Transition Model](../Adding-a-Transition-Model/) +- [NASA Turbulence Modeling Resource](https://tmbwg.github.io/turbmodels/). It moved from turbmodels.larc.nasa.gov in 2026; the old links now lead to a NASA landing page. + +Source review: 22 October 2026, against [SU2 `docs_site` at `41ea6a219a`](https://github.com/rois1995/SU2/tree/41ea6a219ac038574f3d4a5b130c0c1d8af66457). See the [review scope and outstanding validation](../Documentation-Status/#guide-and-model-review). Setup recommendations remain draft where indicated. diff --git a/_docs_v7/Troubleshooting.md b/_docs_v7/Troubleshooting.md new file mode 100644 index 00000000..b9bab52d --- /dev/null +++ b/_docs_v7/Troubleshooting.md @@ -0,0 +1,228 @@ +--- +title: Troubleshooting +permalink: /docs_v7/Troubleshooting/ +--- + +This page helps when a run does not do what you expect. Each problem has three parts: what you see, why it happens, and what to do. For short general answers, see the [FAQ](/docs_v7/FAQ/). To look up any message that stops SU2, search the [Error Messages](/docs_v7/Error-Messages/) page. + +**(to be reviewed)** at the end of a statement means that the statement is general advice and needs a check by an experienced user. The rest was checked against the SU2 code, or comes from the linked pages. + +--- + +- [How SU2 reports an error](#how-su2-reports-an-error) +- [SU2 stops while it reads the config file](#su2-stops-while-it-reads-the-config-file) +- [SU2 stops while it reads the mesh](#su2-stops-while-it-reads-the-mesh) +- [The restart does not work](#the-restart-does-not-work) +- [The solution diverges](#the-solution-diverges) +- [The residuals stop going down](#the-residuals-stop-going-down) +- [An output field or file is missing](#an-output-field-or-file-is-missing) +- [Parallel runs](#parallel-runs) + +--- + +## How SU2 reports an error + +When SU2 finds a problem it cannot fix, it prints a block like this and stops: + +``` +Error in "void CConfig::SetConfig_Parsing(std::istream&)": +------------------------------------------------------------------------- +Line 98 CFL_NUMBR: invalid option name. Check current SU2 options in config_template.cfg. +Did you mean CFL_NUMBER? +------------------------------ Error Exit ------------------------------- +``` + +The first line names the function in the code that found the problem. Its exact text depends on your compiler. The lines between the dashes are the message. With MPI, the launcher (`mpirun`) usually adds a few lines about `MPI_ABORT` after the block. You can ignore them. + +## SU2 stops while it reads the config file + +SU2 reads the whole config file first. It collects all the problems it finds, up to 30, and prints them in one error block. + +**What you see:** `Line 98 CFL_NUMBR: invalid option name. Check current SU2 options in config_template.cfg.` + +- **Why:** SU2 does not know this option name. Either the name has a typo, or the option was renamed or removed in a newer version. +- **What to do:** SU2 prints a guess on the next line (`Did you mean CFL_NUMBER?`). The guess is based on shared letters at the start and end of the name, so it can be wrong. Look for the old name on [Renamed and Removed Options](/docs_v7/Renamed-Options/), and check the current name in the [Option Reference](/docs_v7/Option-Reference/). For a few old names, SU2 tells you the new one directly, for example `DYN_TIMESTEP is deprecated. Use TIME_STEP instead.` + +**What you see:** a wrong value for an option with a fixed list of values: + +``` +MGCYCLE: invalid option value W_CYCLES. +Did you mean, FULLMG_CYCLE, V_CYCLE, W_CYCLE? +``` + +- **Why:** the value is not one of the allowed words. Values are case sensitive. +- **What to do:** pick one of the values that SU2 lists after "Did you mean". + +**What you see:** `CONV_NUM_METHOD_FLOW: improper option value for type convect`, or `MACH_NUMBER: multiple values for type su2double`. + +- **Why:** the value does not have the expected form. For example, a number option got text or two numbers. +- **What to do:** check the type and the allowed values of the option in the [Option Reference](/docs_v7/Option-Reference/). + +**What you see:** `Line 102 CFL_NUMBER: option appears twice` + +- **Why:** the option is set on two lines. SU2 does not pick one of them; it stops. +- **What to do:** delete one of the two lines. + +**What you see:** `configfile: File does not exist: case.cfg` + +- **Why:** SU2 cannot find the config file you named on the command line. +- **What to do:** check the file name, and run SU2 from the folder that holds the file. + +## SU2 stops while it reads the mesh + +**What you see:** `The SU2 mesh file named mesh.su2 was not found.` + +- **Why:** the file in `MESH_FILENAME` is not in the folder where you run SU2. Note that SU2 sets the file extension from `MESH_FORMAT`. It removes `.su2`, `.su2b` or `.cgns` from the name you give, and adds the extension of the format. So `MESH_FILENAME= wing.cgns` with the default `MESH_FORMAT= SU2` makes SU2 look for `wing.su2`. +- **What to do:** check the file name and the folder, and set `MESH_FORMAT` to the real format of the file: + +``` +MESH_FILENAME= wing.cgns +MESH_FORMAT= CGNS +``` + +**What you see:** `wing.cgns was not found or is not a properly formatted CGNS file.` followed by `Note that SU2 expects unstructured CGNS files in ADF data format.` + +- **Why:** the file is missing, or it is not a CGNS file that SU2 can read. SU2 reads unstructured CGNS meshes only. +- **What to do:** check the name and the folder, then check that the file is a valid unstructured CGNS mesh supported by the reader. The ADF-only wording in this error is outdated: the bundled CGNS library supports both ADF and HDF5. A valid HDF5 mesh does not need conversion to ADF. See [Mesh File](/docs_v7/Mesh-File/). + +**What you see:** `mesh.su2 is not an SU2 mesh file or has the wrong format` and `('NDIME=' not found). Please check.`, or `Could not find the keyword "NPOIN=".` + +- **Why:** the file is not a native SU2 mesh, or a keyword is missing. A common cause is a mesh in another format with `MESH_FORMAT= SU2`. +- **What to do:** set `MESH_FORMAT` to the real format, or convert the mesh. The [Mesh File](/docs_v7/Mesh-File/) page shows the native format. + +**What you see:** `The configuration file doesn't have any definition for marker farfield` + +- **Why:** the mesh has a boundary marker (a named group of boundary faces) called `farfield`, but no `MARKER_*` option in the config file uses that name. +- **What to do:** give every mesh marker a boundary condition. Marker names must match the mesh exactly. SU2 prints the marker names it finds in the mesh just before the error, for example `50 boundary elements in index 1 (Marker = farfield).` See [Markers and BC](/docs_v7/Markers-and-BC/). + +The opposite case does not stop SU2: a marker named in the config file but not present in the mesh is accepted without a warning. It shows in the boundary table at the start of the run, but no faces use it. So check the names in that table if a boundary condition seems to have no effect. + +## The restart does not work + +With `RESTART_SOL= YES`, SU2 reads the file named in `SOLUTION_FILENAME`, not the one in `RESTART_FILENAME`. The [Restart File](/docs_v7/Restart-File/) page explains the file names. + +**What you see:** `Unable to open SU2 restart file solution_flow.dat` + +- **Why:** the file does not exist. SU2 adds the extension itself: `.dat` when `READ_BINARY_RESTART= YES` (the default), `.csv` when `READ_BINARY_RESTART= NO`. A common cause is that the previous run saved the restart as `restart_flow.dat`, and nobody copied or renamed it. +- **What to do:** copy the restart file to the solution name, or point `SOLUTION_FILENAME` to it: + +``` +RESTART_SOL= YES +SOLUTION_FILENAME= restart_flow +``` + +**What you see:** `SU2 ASCII restart file solution_flow.csv not found.`, or `File solution_flow.dat is not a binary SU2 restart file.` + +- **Why:** the restart format does not match `READ_BINARY_RESTART`. `OUTPUT_FILES= RESTART` writes a binary `.dat` file. `OUTPUT_FILES= RESTART_ASCII` writes a text `.csv` file. +- **What to do:** set `READ_BINARY_RESTART= NO` to read a `.csv` file, and `YES` to read a `.dat` file. + +**What you see:** the restart comes from a different mesh. + +- **Why:** the number of points in the file does not match the mesh. +- **What to do:** use a binary restart file. SU2 then prints `The number of points in the restart file (...) does not match the mesh (...).` and maps the old solution onto the new mesh, using the nearest points. With MPI, this needs a single rank or an even number of ranks. Otherwise SU2 stops with `Number of ranks must be multiple of 2.` An ASCII restart file stops with `The solution file does not match the mesh, currently only binary files can be interpolated.` + +**What you see:** the restart file comes from a different solver or turbulence model, and the run starts badly. + +- **Why:** SU2 reads the restart values by their column position, not by their name. If the file has fewer turbulence columns than the new model needs, SU2 sets the missing turbulence values to zero. A file from another turbulence model can put the wrong values into the turbulence variables, without any error. +- **What to do:** restart only from a solution of the same solver and model. If you change the model, start from the free-stream values instead (to be reviewed). + +## The solution diverges + +**What you see:** `SU2 has diverged (NaN detected).` or `SU2 has diverged (Residual > 10^20 detected).` SU2 stops and does not save the solution of that iteration. Before this, the residuals often grow quickly, and the history field `NONPHYSICAL_POINTS` grows. A non-physical point is a point with a negative density, pressure or temperature. When a run ends normally, SU2 also prints `Warning: there are ... non-physical points in the solution.` + +**Why:** the most common causes are a time step that is too large for the current solution, a bad mesh, or wrong free-stream or boundary values. + +**What to do:** try these steps, one at a time. + +1. **Check the input values.** At the start of the run, SU2 prints a table called `-- Initial and free-stream conditions:`. Check that pressure, temperature, velocity and Mach number are what you meant. Check also the boundary values on each `MARKER_*` option, and their units. +2. **Check the mesh.** At the start of the run, SU2 prints the mesh quality table: `Orthogonality Angle (deg.)`, `CV Face Area Aspect Ratio` and `CV Sub-Volume Ratio`, with their minimum and maximum. A very small angle or very large ratios point to bad cells (to be reviewed). To see where these cells are, add the `MESH_QUALITY` group to the volume output and open the file in ParaView: + +``` +VOLUME_OUTPUT= (SOLUTION, PRIMITIVE, MESH_QUALITY) +``` + +3. **Lower the CFL number.** The CFL number sets the size of the pseudo time step (a step that only drives the solution to steady state). Lower `CFL_NUMBER`, or let SU2 change it as the run goes with `CFL_ADAPT= YES`. The values of `CFL_ADAPT_PARAM` are: factor down, factor up, minimum CFL, maximum CFL. See the [Glossary](/docs_v7/Glossary/) and [Solver Setup](/docs_v7/Solver-Setup/). + +``` +CFL_NUMBER= 10 +CFL_ADAPT= YES +CFL_ADAPT_PARAM= ( 0.5, 1.1, 1.0, 100.0 ) +``` + +4. **Start with a first-order scheme.** A first-order scheme is less accurate but more robust. Run first with `MUSCL_FLOW= NO`, then restart from that solution with `MUSCL_FLOW= YES`. Instead of two runs, `RAMP_MUSCL= YES` blends from first to second order over the iterations set in `RAMP_MUSCL_COEFF` (start iteration, update frequency, length of the ramp). See [Convective Schemes](/docs_v7/Convective-Schemes/). +5. **Use a limiter near shocks.** In flows with shocks, keep `SLOPE_LIMITER_FLOW` set to a limiter, not `NONE`. See [Slope Limiters and Shock Resolution](/docs_v7/Slope-Limiters-and-Shock-Resolution/). +6. **Look at the solution before it fails.** SU2 does not save the solution once it finds a NaN. Write the files more often, for example `OUTPUT_WRT_FREQ= 10`, and look at the last file written. The problem usually starts in one region. + +The setup guides, such as [RANS External Aerodynamics](/docs_v7/Setup-Guide-RANS-External-Aero/), list safe starting values for each kind of case. + +## The residuals stop going down + +**What you see:** the residuals drop for a while, then stay flat or go up and down. At the end, SU2 prints `Maximum number of iterations reached (ITER = ...) before convergence.` + +**Why and what to do:** + +- **The linear solver does not converge.** Each iteration of an implicit solver solves a linear system. Add `LINSOL_ITER` and `LINSOL_RESIDUAL` to `SCREEN_OUTPUT` to watch it. If the linear residual stays high, raise `LINEAR_SOLVER_ITER` or lower the CFL number. See the advice in [Linear Solvers and Preconditioners](/docs_v7/Linear-Solvers-and-Preconditioners/#setup-advice). + +``` +SCREEN_OUTPUT= (INNER_ITER, RMS_RES, LINSOL_ITER, LINSOL_RESIDUAL, AVG_CFL) +``` + +- **The CFL number is too high.** Large CFL values can make the residuals go up and down without settling. Lower `CFL_NUMBER`, or lower the maximum CFL in `CFL_ADAPT_PARAM` (to be reviewed). +- **The limiter switches on and off.** This can stop the residual drop in flows with shocks. A larger `VENKAT_LIMITER_COEFF` limits less. `LIMITER_ITER` freezes the limiter after the given number of iterations (to be reviewed). See [Slope Limiters and Shock Resolution](/docs_v7/Slope-Limiters-and-Shock-Resolution/). +- **The flow is not steady.** Some flows, for example with large separation, never reach a steady state. In that case, run an unsteady simulation (to be reviewed). See the [Unsteady and DES setup guide](/docs_v7/Setup-Guide-Unsteady-DES/). +- **Unsteady runs: the time step is too large.** In an unsteady run, the inner iterations must converge in each time step. If they do not, lower `TIME_STEP` or raise `INNER_ITER` (to be reviewed). + +**The run never stops early, or stops too early.** SU2 stops before `ITER` only when every field in `CONV_FIELD` meets its criterion, and not before `CONV_STARTITER` iterations: + +- A residual field stops the run when its value goes below `CONV_RESIDUAL_MINVAL`. The `RMS_*` fields are log10 values, not a drop from the start. To ask for a drop, use the `REL_RMS_*` fields. They measure the drop from the largest value seen so far. +- A coefficient field, such as `DRAG`, stops the run when its average relative change over the last `CONV_CAUCHY_ELEMS` iterations is below `CONV_CAUCHY_EPS`. + +``` +% Stop when the density residual has dropped by 6 orders +CONV_FIELD= REL_RMS_DENSITY +CONV_RESIDUAL_MINVAL= -6 +``` + +If a name in `CONV_FIELD` does not exist for your solver, SU2 prints `Ignoring Convergence Field(s):` with the name. If no valid field is left, SU2 prints `Warning: No (valid) fields chosen for convergence monitoring. Convergence monitoring inactive.` and runs until `ITER`. See [Setting convergence criteria](/docs_v7/Solver-Setup/#setting-convergence-criteria). + +## An output field or file is missing + +**What you see:** a field you asked for is not in the screen, history or volume output. At the start of the run, SU2 prints lines such as `Info: Ignoring the following screen output fields:`. + +- **Why:** the field does not exist for this solver, or its name has a typo. The fields depend on the solver and the models. +- **What to do:** list the fields that exist for your exact config file with a dry run. A dry run sets up the case without solving it. It still needs the mesh file. It prints the tables `Available volume output fields for the current configuration` and `Available screen/history output fields for the current configuration`, and stops: + +``` +SU2_CFD -d case.cfg +``` + +The [Output Fields Reference](/docs_v7/Output-Fields-Reference/) lists all fields of every solver. [Custom Output](/docs_v7/Custom-Output/) explains how to choose them. + +**What you see:** a volume or surface file is not written. + +- **Why:** `OUTPUT_FILES` sets which files SU2 writes. If you set it, only the listed files are written. Without it, SU2 writes `RESTART`, `PARAVIEW` and `SURFACE_PARAVIEW`. `OUTPUT_WRT_FREQ` sets how often the files are written: by default every 250 iterations in steady runs, and every time step in unsteady runs. Steady runs also write the files at the end. +- **What to do:** add the file type to `OUTPUT_FILES`. Give one frequency per file type. If you give fewer frequencies than file types, SU2 repeats the last one: + +``` +OUTPUT_FILES= (RESTART, PARAVIEW, SURFACE_CSV) +OUTPUT_WRT_FREQ= (100, 500) +``` + +In unsteady runs, a file every time step can fill your disk. Set a larger `OUTPUT_WRT_FREQ`. + +## Parallel runs + +**What you see:** with `mpirun -n 4 SU2_CFD case.cfg`, every line of output appears four times. + +- **Why:** SU2 was built without MPI, so each process runs the whole case alone. See the [FAQ](/docs_v7/FAQ/). +- **What to do:** build SU2 with MPI (`-Dwith-mpi=enabled`, see [Build from Source](/docs_v7/Build-SU2-Linux-MacOS/)), and use the `mpirun` that belongs to the same MPI library as the build (to be reviewed). + +**What you see:** the run stops, or the system kills it, while SU2 reads the mesh or builds the solver. + +- **Why:** the run needs more memory than the machine has. Memory grows with the number of mesh points, the number of equations, and some settings (to be reviewed). +- **What to do:** + - Spread the run over more nodes, so that each part of the mesh is smaller (to be reviewed). + - `FGMRES` keeps one vector per linear iteration, so its memory grows with `LINEAR_SOLVER_ITER`. Lower `LINEAR_SOLVER_ITER`, or use `RESTARTED_FGMRES` or `BCGSTAB`. See [Linear Solvers and Preconditioners](/docs_v7/Linear-Solvers-and-Preconditioners/#setup-advice). + - Each multigrid level (`MGLEVEL`) adds a coarser copy of the mesh and its own data. Use fewer levels (to be reviewed). + +If SU2 crashes without an error block, for example with a segmentation fault, the [Debugging](/docs_v7/Debugging/) page shows how to find the cause. If you think you found a bug, report it on [GitHub](https://github.com/su2code/SU2/issues) with the config file and, if possible, the mesh. diff --git a/_docs_v7/Turbulence-Models.md b/_docs_v7/Turbulence-Models.md new file mode 100644 index 00000000..e4bfc1b0 --- /dev/null +++ b/_docs_v7/Turbulence-Models.md @@ -0,0 +1,261 @@ +--- +title: Turbulence Models +permalink: /docs_v7/Turbulence-Models/ +--- + +This page explains the model and its SU2 implementation. For numerical setup choices, see the [setup guide](../Setup-Guide-RANS-External-Aero/); use its tutorial and V&V links for worked examples and comparisons. + +A RANS simulation does not resolve turbulent eddies. A turbulence model adds transport equations that give the eddy viscosity, which models the extra mixing caused by turbulence. SU2 has two model families: the one-equation Spalart-Allmaras (SA) model and the two-equation k-omega Shear Stress Transport (SST) model, each with several variants. + +--- + +- [Select a model](#select-a-model) +- [Spalart-Allmaras (SA)](#spalart-allmaras-sa) +- [Shear Stress Transport (SST)](#shear-stress-transport-sst) +- [What SU2 does differently from the literature](#what-su2-does-differently-from-the-literature) +- [Free-stream and inlet values](#free-stream-and-inlet-values) +- [Verification and test cases](#verification-and-test-cases) +- [Known limits](#known-limits) +- [Related pages](#related-pages) + +--- + +## Select a model + +- Set `SOLVER= RANS` (compressible) or `SOLVER= INC_RANS` (incompressible). The discrete adjoint of both solvers uses the same model options. +- Set `KIND_TURB_MODEL` to `SA` or `SST`. The default is `NONE`. +- SU2 stops with an error if `SOLVER` is `RANS` or `INC_RANS` and `KIND_TURB_MODEL= NONE`. It also stops if `SOLVER` is `NAVIER_STOKES` or `INC_NAVIER_STOKES` and a turbulence model is set. +- Choose the variant with `SA_OPTIONS` (for SA) or `SST_OPTIONS` (for SST). Both take a list of keywords. An empty list gives the default variant. +- SU2 prints the full name of the variant it runs at the start of the run, for example `Spalart-Allmaras-noft2` or `Menter's k-omega SST-2003m`. + + + +Other options that act on all turbulence models: + +| Option | Default | What it does | +| --- | --- | --- | +| `PRANDTL_TURB` | `0.9` | Turbulent Prandtl number. It turns the eddy viscosity into a turbulent heat conductivity. Takes one value per species for mixtures. | +| `TURBULENT_CONDUCTIVITY_MODEL` | `CONSTANT_PRANDTL_TURB` | In incompressible flow, `NONE` switches off the fluid model's turbulent heat conductivity. Compressible viscous fluxes still add Cp × mu_t / `PRANDTL_TURB`, independently of this setting. | +| `TURB_FIXED_VALUES` | `NO` | Keeps the turbulence variables at their free-stream values in the region upstream of a plane. | +| `TURB_FIXED_VALUES_DOMAIN` | none | Position of that plane, as a distance along the free-stream direction. Required with `TURB_FIXED_VALUES= YES`. | + + + +Old values of `KIND_TURB_MODEL` (`SST_SUST`, `SA_NEG`, `SA_E`, `SA_COMP`, `SA_E_COMP`) and `KIND_TRANS_MODEL= BC` are no longer accepted. SU2 stops and prints the new option to use. + +Hybrid RANS-LES models (DES, DDES and stochastic backscatter) build on these models. See [Hybrid RANS-LES](../Hybrid-RANS-LES/). Wall functions and wall roughness, including the SST roughness boundary conditions, are on [Wall Treatment](../Wall-Treatment/). + +## Spalart-Allmaras (SA) + +Select it with `KIND_TURB_MODEL= SA`. The model solves one equation for the SA working variable, nu-tilde (`NU_TILDE` in the output). The [NASA Turbulence Modeling Resource (TMR) SA page](https://tmbwg.github.io/turbmodels/spalart.html) gives the equations of every variant. + +### SA_OPTIONS keywords + +| Keyword | Effect | TMR name | +| --- | --- | --- | +| (empty list) or `NONE` | SA without the ft2 term. This is the SU2 default. | [SA-noft2](https://tmbwg.github.io/turbmodels/spalart.html#sanoft2) | +| `WITHFT2` | Adds the ft2 term (the laminar suppression term). | [SA](https://tmbwg.github.io/turbmodels/spalart.html#sa) | +| `NEGATIVE` | Negative SA: allows negative nu-tilde with modified source and diffusion terms. | [SA-neg](https://tmbwg.github.io/turbmodels/spalart.html#saneg) | +| `EDWARDS` | Edwards modification: uses the strain rate instead of the vorticity. | [SA-noft2-Edwards](https://tmbwg.github.io/turbmodels/spalart.html#saEdwards) | +| `ROTATION` | Rotation correction of Dacles-Mariani et al. | [SA-R](https://tmbwg.github.io/turbmodels/spalart.html#saR) | +| `COMPRESSIBILITY` | Mixing-layer compressibility correction. | [SA-comp](https://tmbwg.github.io/turbmodels/spalart.html#sacomp) | +| `QCR2000` | Quadratic constitutive relation: adds a nonlinear term to the turbulent stresses. | [SA-QCR2000](https://tmbwg.github.io/turbmodels/spalart.html#qcr2000) | +| `BCM` | Bas-Cakmakcioglu algebraic transition model. See [Transition Models](../Transition-Models/). | [SA-BCM](https://tmbwg.github.io/turbmodels/sa-bc_1eqn.html) | +| `EXPERIMENTAL` | Turns off the checks on combinations (see below). | none | + + + +### Combinations that SU2 accepts + +SU2 follows the variant names of the TMR. It stops with an error for combinations that the TMR does not list: + +- `NEGATIVE` and `EDWARDS` cannot be used together, even with `EXPERIMENTAL`. +- `NEGATIVE` needs `WITHFT2`, because SA-neg is defined with the ft2 term. It cannot be combined with `BCM`. +- `EDWARDS` must be alone. It cannot be combined with `WITHFT2`, `ROTATION`, `COMPRESSIBILITY`, `QCR2000` or `BCM`. +- `BCM` cannot be combined with `WITHFT2`, `ROTATION`, `COMPRESSIBILITY` or `QCR2000`. +- Without `NEGATIVE`, `EDWARDS` or `BCM`, any mix of `WITHFT2`, `ROTATION`, `COMPRESSIBILITY` and `QCR2000` is accepted. + +Add `EXPERIMENTAL` to the list to run a combination that SU2 rejects, for example `SA_OPTIONS= NEGATIVE, EXPERIMENTAL` (SA-neg without ft2). + +Examples: + +| TMR name | Setting | +| --- | --- | +| SA-noft2 | `SA_OPTIONS= NONE` (or leave the option out) | +| SA | `SA_OPTIONS= WITHFT2` | +| SA-neg | `SA_OPTIONS= NEGATIVE, WITHFT2` | +| SA-noft2-R-comp | `SA_OPTIONS= ROTATION, COMPRESSIBILITY` | +| SA-neg-R-comp-QCR2000 | `SA_OPTIONS= NEGATIVE, WITHFT2, ROTATION, COMPRESSIBILITY, QCR2000` | +| SA-noft2-Edwards | `SA_OPTIONS= EDWARDS` | +| SA-BCM | `SA_OPTIONS= BCM` | + +Original papers: + +- SA: P. R. Spalart and S. R. Allmaras, "A One-Equation Turbulence Model for Aerodynamic Flows", La Recherche Aérospatiale, No. 1, 1994, pp. 5-21. +- SA-neg: S. R. Allmaras, F. T. Johnson and P. R. Spalart, "Modifications and Clarifications for the Implementation of the Spalart-Allmaras Turbulence Model", ICCFD7-1902, 2012. +- SA-R: J. Dacles-Mariani, G. G. Zilliac, J. S. Chow and P. Bradshaw, AIAA Journal 33(9), 1995, pp. 1561-1568. +- SA-comp: P. R. Spalart, "Trends in Turbulence Treatments", AIAA 2000-2306. +- SA-QCR2000: P. R. Spalart, "Strategies for Turbulence Modelling and Simulation", Int. J. Heat and Fluid Flow 21, 2000, pp. 252-263. +- SA-noft2-Edwards: J. R. Edwards and S. Chandra, AIAA Journal 34(4), 1996, pp. 756-763. + +## Shear Stress Transport (SST) + +Select it with `KIND_TURB_MODEL= SST`. The model solves two equations: the turbulent kinetic energy k (`TKE` in the output) and the specific dissipation rate omega (`DISSIPATION`). The [TMR SST page](https://tmbwg.github.io/turbmodels/sst.html) gives the equations of every variant. + +### SST_OPTIONS keywords + +The keywords fall into four groups. SU2 has only the "m" forms of SST ([see below](#sst)). + +**Version** (at most one): + +| Keyword | Effect | TMR name | +| --- | --- | --- | +| `V2003m` | 2003 version, "m" form. This is the default when no version is given. | [SST-2003m](https://tmbwg.github.io/turbmodels/sst.html#sst-2003) | +| `V1994m` | Original 1994 version, "m" form. | [SSTm](https://tmbwg.github.io/turbmodels/sst.html#sst-std) | + +**Production term** (at most one): what SU2 uses in place of the strain rate magnitude S in the production of k. + +| Keyword | Effect | TMR name | +| --- | --- | --- | +| `VORTICITY` | Uses the vorticity magnitude. | [SST-Vm](https://tmbwg.github.io/turbmodels/sst.html#sst-v) | +| `KATO-LAUNDER` | Replaces S² in production by SΩ, the product of strain-rate and vorticity magnitudes. | [SST-KLm](https://tmbwg.github.io/turbmodels/sst.html#sst-kl) | +| `UQ` | Uses a perturbed Reynolds stress tensor, for uncertainty quantification. See the [UQ tutorial](/tutorials/UQ_NACA0012/) and the options `UQ_COMPONENT` (default `1`), `UQ_DELTA_B` (`1.0`), `UQ_URLX` (`0.1`), `UQ_PERMUTE` (`NO`). | none | + +**Compressibility correction** (at most one, only with `SOLVER= RANS`): + +| Keyword | Effect | +| --- | --- | +| `COMPRESSIBILITY-WILCOX` | Wilcox dilatation-dissipation correction. Active where the turbulent Mach number sqrt(2k)/a is above 0.25. | +| `COMPRESSIBILITY-SARKAR` | Sarkar correction: dilatation dissipation plus a pressure-dilatation term. Same threshold. | + +**Other modifiers** (combine with anything): + +| Keyword | Effect | TMR name | +| --- | --- | --- | +| `SUSTAINING` | Controlled decay: keeps k and omega from decaying below their free-stream values. | [SST-sust](https://tmbwg.github.io/turbmodels/sst.html#sst-sust) | +| `DIMENSIONLESS_LIMIT` | Sets the lower limits of k and omega relative to their free-stream values (see below). | none | +| `NONE` | No effect. | none | + + + +SU2 stops with an error if you give two versions, two production keywords or two compressibility keywords. + +Examples: + +| TMR name | Setting | +| --- | --- | +| SST-2003m | `SST_OPTIONS= V2003m` (or leave the option out) | +| SSTm | `SST_OPTIONS= V1994m` | +| SST-Vm | `SST_OPTIONS= V1994m, VORTICITY` | +| SST-KLm | `SST_OPTIONS= V1994m, KATO-LAUNDER` | +| SST-sust-m | `SST_OPTIONS= V1994m, SUSTAINING` | + +Original papers: + +- SST (1994): F. R. Menter, "Two-Equation Eddy-Viscosity Turbulence Models for Engineering Applications", AIAA Journal 32(8), 1994, pp. 1598-1605. +- SST-2003: F. R. Menter, M. Kuntz and R. Langtry, "Ten Years of Industrial Experience with the SST Turbulence Model", Turbulence, Heat and Mass Transfer 4, 2003, pp. 625-632. +- SST-V: F. R. Menter, "Improved Two-Equation k-omega Turbulence Models for Aerodynamic Flows", NASA TM 103975, 1992. +- SST-KL: M. Kato and B. E. Launder, 9th Symposium on Turbulent Shear Flows, Kyoto, 1993, paper 10-4. +- SST-sust: P. R. Spalart and C. L. Rumsey, "Effective Inflow Conditions for Turbulence Models in Aerodynamic Calculations", AIAA Journal 45(10), 2007, pp. 2544-2553. + +## What SU2 does differently from the literature + +This section lists where SU2 departs from the TMR definitions, or where the SU2 defaults differ from what the TMR calls "standard". + +### SA + +- **The default is SA-noft2, not standard SA.** The TMR calls the version with the ft2 term "standard". SU2 leaves ft2 out unless you add `WITHFT2`. The TMR notes that SA-noft2 gives almost the same results for most practical problems. +- **Limiting of the modified vorticity.** In all variants except Edwards, SU2 limits the modified vorticity S-hat as in note 1(c) of Allmaras et al. (2012), and keeps it above 1e-10. In SA-neg, where nu-tilde is negative, S-hat is the vorticity. +- **Rotation correction with SA-neg.** With `ROTATION`, SU2 takes the absolute value of the production term where nu-tilde is negative. The correction constant is 2. +- **Compressibility correction.** `COMPRESSIBILITY` uses C5 = 3.5. SU2 computes the speed of sound from the ideal-gas relation sqrt(gamma p / rho), whatever the fluid model. In axisymmetric runs it adds the matching axisymmetric term. SU2 does not stop you from using it with `INC_RANS` (to be reviewed: check whether the result makes sense there). +- **QCR2000.** SU2 adds the QCR term (constant 0.3) to the stress tensor, scaled by the fraction of eddy viscosity in the total viscosity. It is available only with SA. +- **Rough walls.** SU2 applies the Aupoix-Spalart roughness correction when a wall has a roughness height. See [Wall Treatment](../Wall-Treatment/). + +### SST + +- **SST is always the "m" form.** SU2 does not include the turbulent kinetic energy in the viscous stress tensor of the mean flow equations. The production of k is mu_t S^2 (or the vorticity or Kato-Launder form). The unmodified keywords `V1994` and `V2003` are not available. +- **Exception: `UQ`.** With `UQ`, SU2 uses the perturbed Reynolds stress tensor, which includes k, both in the mean flow equations and in the production of k. +- **`V1994m` is consistent with the TMR since SU2 v8.** Before, SU2 dropped k from the stress tensor but kept a divergence term in the production ([issue #1551](https://github.com/su2code/SU2/issues/1551), now closed). [Pull request #2062](https://github.com/su2code/SU2/pull/2062), merged in July 2023, removed that term and made `V2003m` the default. +- **1994 versus 2003.** As in the TMR: 1994 uses the vorticity in the eddy viscosity limiter, a production limiter of 20 and the unlimited production in the omega equation; 2003 uses the strain rate, a limiter of 10 and the limited production in the omega equation. The 2003 version also uses its own values of the constants gamma_1 = 5/9 and gamma_2 = 0.44. +- **Sustaining terms.** The TMR adds the sustaining terms to the sources. SU2 instead takes the larger of the production and the sustaining term, for k and for omega. Where production is larger, the model is unchanged. The ambient values are the free-stream k and omega that SU2 computes from `FREESTREAM_TURBULENCEINTENSITY` and `FREESTREAM_TURB2LAMVISCRATIO` (see below). The TMR recommends specific ambient values; SU2 does not set them for you. +- **Compressibility corrections replace the production keyword.** In the code, `COMPRESSIBILITY-WILCOX` and `COMPRESSIBILITY-SARKAR` overwrite the production setting. If you combine them with `VORTICITY`, `KATO-LAUNDER` or `UQ`, SU2 gives no error, but the production uses the strain rate. The start-up message shows only the compressibility correction. With `UQ`, the mean flow stress tensor is still perturbed. Do not combine the two groups. +- **Lower limits of k and omega.** By default SU2 keeps k above 1e-10 and omega above 1e-4 (in the non-dimensional units of the solver). With `DIMENSIONLESS_LIMIT`, the limits become `LOWER_LIMIT_K_FACTOR` (default `1e-15`) times the free-stream k and `LOWER_LIMIT_OMEGA_FACTOR` (default `1e-05`) times the free-stream omega. +- **No curvature correction.** SST-RC and similar variants are not implemented. + +## Free-stream and inlet values + +SU2 starts the whole field from the free-stream values of the turbulence variables, and uses them at far-field boundaries. + +**SA.** + +| Option | Default | Meaning | +| --- | --- | --- | +| `FREESTREAM_NU_FACTOR` | `3.0` | Free-stream nu-tilde divided by the free-stream kinematic viscosity. | +| `ENGINE_NU_FACTOR` | `3.0` | Same ratio at engine and actuator disk boundaries. | + +With `BCM`, SU2 multiplies the free-stream, inlet and engine values (not the actuator disk value) by 0.005. The default free-stream nu-tilde is then 0.015 times the kinematic viscosity. + +**SST.** + +| Option | Default | Meaning | +| --- | --- | --- | +| `FREESTREAM_TURBULENCEINTENSITY` | `0.05` | Turbulence intensity Tu as a fraction (0.05 means 5 %). | +| `FREESTREAM_TURB2LAMVISCRATIO` | `10.0` | Ratio of eddy viscosity to laminar viscosity. | + +SU2 computes k = 1.5 (Tu U)^2 from the free-stream speed U, and then omega = rho k / (mu × ratio). + +The defaults (5 % and 10) are not calibrated inlet conditions. Choose the intensity and length/time scale for the actual flow, and check their decay between the boundary and the body. The TMR gives recommended far-field values for each model, and [Setup Guide: Steady RANS for External Aerodynamics](../Setup-Guide-RANS-External-Aero/) discusses the choice. + +**Inlets.** `MARKER_INLET_TURBULENT` sets values per inlet marker: + +- SA: `MARKER_INLET_TURBULENT= (inlet, 3.0)`. The value is nu-tilde divided by the kinematic viscosity at the inlet, like `FREESTREAM_NU_FACTOR`. (The SU2 error message calls it a viscosity ratio, but the code uses it as the nu-tilde factor.) +- SST: `MARKER_INLET_TURBULENT= (inlet, 0.05, 10.0)`: turbulence intensity, then viscosity ratio. SU2 computes k and omega from the inlet velocity, density and viscosity. +- An inlet not listed in `MARKER_INLET_TURBULENT` uses the free-stream values of the options above. +- With an inlet profile file, the file gives nu-tilde (SA) or k and omega (SST) in dimensional units. + + + +## Verification and test cases + +Verification and validation (V&V) pages, with configs in [TestCases/vandv](https://github.com/su2code/SU2/tree/develop/TestCases/vandv/rans): + +| Page | Models | Config | +| --- | --- | --- | +| [Flat plate](/vandv/Flat_Plate/) | SA, SST 1994m and 2003m | [turb_flatplate_sst.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/vandv/rans/flatplate/turb_flatplate_sst.cfg) (`V1994m`) | +| [Bump in channel](/vandv/Bump_Channel/) | SST | [turb_bump_sst.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/vandv/rans/bump_in_channel/turb_bump_sst.cfg) (`V1994m`) | +| [DSMA661 airfoil wake](/vandv/dsma661/) | SA, SST | [dsma661_sa_config.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/vandv/rans/dsma661/dsma661_sa_config.cfg) (SA-noft2), [dsma661_sst_config.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/vandv/rans/dsma661/dsma661_sst_config.cfg) (`V2003m`) | +| [30P30N high-lift airfoil](/vandv/30p30n/) | SA-noft2 | [config.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/vandv/rans/30p30n/config.cfg) | +| [Shock-wave boundary-layer interaction](/vandv/swbli/) | SA-neg, SST-2003m with Wilcox correction | [config_sa.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/vandv/rans/swbli/config_sa.cfg), [config_sst.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/vandv/rans/swbli/config_sst.cfg) | +| [Sandia jet](/vandv/SANDIA_jet/) | SST-2003m, incompressible | [validation.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/vandv/species_transport/sandia_jet/validation.cfg) | + +Test cases that show the option keywords: + +- SA variants on the RAE2822 airfoil, in [TestCases/turbulence_models/sa/rae2822](https://github.com/su2code/SU2/tree/develop/TestCases/turbulence_models/sa/rae2822): baseline, `COMPRESSIBILITY`, `EDWARDS`, `EDWARDS, COMPRESSIBILITY, EXPERIMENTAL`, `NEGATIVE, EXPERIMENTAL` (SA-neg without ft2) and `QCR2000`. `TestCases/parallel_regression.py` runs all six configs as the `turbmod_sa_*_rae2822` tests. +- SST variants on the NACA 0012, in [TestCases/rans/naca0012](https://github.com/su2code/SU2/tree/develop/TestCases/rans/naca0012): `turb_NACA0012_sst.cfg` (`V1994m`), `turb_NACA0012_sst_2003m.cfg`, `turb_NACA0012_sst_2003-Vm.cfg`, `turb_NACA0012_sst_1994-KLm.cfg`, `turb_NACA0012_sst_sust.cfg` and `turb_NACA0012_sst_fixedvalues.cfg` (`TURB_FIXED_VALUES`). +- SST compressibility corrections on a flat plate: [turb_SST_flatplate_compressibility_Wilcox.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/rans/flatplate/turb_SST_flatplate_compressibility_Wilcox.cfg) and [turb_SST_flatplate_compressibility_Sarkar.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/rans/flatplate/turb_SST_flatplate_compressibility_Sarkar.cfg). +- SST with sustaining terms on the RAE2822: [turb_SST_SUST_RAE2822.cfg](https://github.com/su2code/SU2/blob/develop/TestCases/rans/rae2822/turb_SST_SUST_RAE2822.cfg). +- SST with `UQ`: [TestCases/rans_uq/naca0012](https://github.com/su2code/SU2/tree/develop/TestCases/rans_uq/naca0012). + +Tutorials: + +- SA: [Turbulent Flat Plate](/tutorials/Turbulent_Flat_Plate/), [Turbulent ONERA M6](/tutorials/Turbulent_ONERAM6/), [Incompressible Turbulent Flat Plate](/tutorials/Inc_Turbulent_Flat_Plate/), [Incompressible Turbulent NACA 0012](/tutorials/Inc_Turbulent_NACA0012/) +- SST with `UQ`: [Uncertainty quantification of RANS predictions (NACA 0012)](/tutorials/UQ_NACA0012/) + +## Known limits + +- Only SA and SST are available. There are no k-epsilon, Reynolds stress or algebraic models. +- SST has no unmodified (non-"m") form and no curvature correction. +- The SST compressibility corrections work only with `SOLVER= RANS`. +- Some SA combinations need `EXPERIMENTAL`. Results with those combinations are not verified against the TMR. +- `FEM_RANS` (the high-order finite element solver) does not use these models. +- RANS models predict a fully turbulent boundary layer. For laminar regions and transition, see [Transition Models](../Transition-Models/). + +## Related pages + +- [Setup Guide: Steady RANS for External Aerodynamics](../Setup-Guide-RANS-External-Aero/) +- [Transition Models](../Transition-Models/), [Hybrid RANS-LES](../Hybrid-RANS-LES/), [Wall Treatment](../Wall-Treatment/) +- All options: [Option Reference](../Option-Reference/). All output fields: [Output Fields Reference](../Output-Fields-Reference/). +- For developers: [Adding a Turbulence Model](../Adding-a-Turbulence-Model/) +- [NASA Turbulence Modeling Resource](https://tmbwg.github.io/turbmodels/). It moved from turbmodels.larc.nasa.gov in 2026; the old links now lead to a NASA landing page. + +Source review: 22 October 2026, against [SU2 `docs_site` at `41ea6a219a`](https://github.com/rois1995/SU2/tree/41ea6a219ac038574f3d4a5b130c0c1d8af66457). See the [review scope and outstanding validation](../Documentation-Status/#guide-and-model-review). Setup recommendations remain draft where indicated. diff --git a/_docs_v7/Using-the-Documentation.md b/_docs_v7/Using-the-Documentation.md new file mode 100644 index 00000000..f454aee9 --- /dev/null +++ b/_docs_v7/Using-the-Documentation.md @@ -0,0 +1,45 @@ +--- +title: Using the Documentation +permalink: /docs_v7/Using-the-Documentation/ +--- + +Choose a page by the question you need to answer. The setup guides, tutorials and verification and validation (V&V) cases complement each other; they serve different purposes. + +| Your question | Where to start | What to expect | +| --- | --- | --- | +| How do I install SU2 and run a first case? | [Installation](../Installation/) and [Quick Start](../Quick-Start/) | Installation steps and a first run. | +| Which settings matter for my kind of problem? | **Case Setup Guides** in the menu | Choices, their consequences, convergence checks and common problems; links to worked cases. | +| How do I run a complete example? | [Tutorials]({{ '/tutorials/home/' | relative_url }}) | Meshes, configurations, commands and post-processing for a particular problem. | +| What evidence supports a model or discretization? | [V&V]({{ '/vandv/home/' | relative_url }}) | Comparisons with exact or manufactured solutions, other codes or physical data, within the scope of each case. | +| What does SU2 implement? | [Theory](../Theory/) and **Physical Models** in the menu | Model definitions, assumptions, variants, implementation differences and references. | +| What does an option or output field mean? | [Option Reference](../Option-Reference/) and [Output Fields Reference](../Output-Fields-Reference/) | Facts extracted from the source, with the limits of extraction stated on each reference. | +| Where do I change or extend the implementation? | [Code Structure](../Code-Structure/), **Developer Docs** and **How to Add...** | Source locations, implementation steps and relevant tests; [Code Reference](../Code-Reference/) for class details. | + +## Versions and applicability + +Check the version information on the page and the SU2 version used by its linked case. The `docs_v7` URL is retained for existing links; it does not mean every page describes SU2 v7. New model and setup pages state the source commit they were checked against, while older tutorials may describe an earlier release. Use the [migration guide](../Guide-to-v8/) and [renamed options](../Renamed-Options/) when moving an older configuration to a newer version. + +A setting accepted by the parser may still be unsupported for a particular solver, model combination or adjoint calculation. Read the model's limitations and the conditions attached to an option. Template values and regression configurations are examples; they need not be defaults or suitable settings for your problem. + +## Sources and review status + +Setup guides use these tags to distinguish evidence from recommendations. A tag on a list or table introduction applies to that whole list or table. + +| Tag | Meaning | Limit | +| --- | --- | --- | +| **(code)** | Checked in the SU2 source. | Describes implementation; does not establish numerical accuracy. Defaults are taken from registration or initialization, not inferred from a template example. | +| **(test case)** | Used in a regression configuration. | A regression detects changes in selected results. Its settings and iteration count need not produce a converged engineering solution. | +| **(tutorial)** | Used or explained in a tutorial. | Applies to that example and its stated version and conditions. | +| **(docs)** | Stated in another documentation page. | Follow the link for its scope and evidence. | +| **(advice)** | A practical CFD recommendation. | Requires judgment for the flow, model, mesh and numerical scheme. | +| **(to be reviewed)** | An explicit request for expert review. | Applies to the statement beside it, regardless of its other source tag. | + +A **Draft** label means that review remains incomplete. A successful configuration run or website build does not remove that label. Verification asks whether the implementation solves the specified equations correctly; validation asks how well the model represents the physical situation. Neither supports unrestricted claims for other meshes, models or flows. + +## How the pages fit together + +For example, start with the [external RANS setup guide](../Setup-Guide-RANS-External-Aero/) to understand the choices, use [Turbulence Models](../Turbulence-Models/) and [Wall Treatment](../Wall-Treatment/) to check model assumptions, then follow the linked tutorial to run a case. Use the V&V comparisons relevant to that model and flow when assessing its accuracy. + +When contributing, keep worked case instructions in Tutorials and numerical comparisons in V&V. Explain general choices in setup guides, and link to those cases instead of copying their full instructions. Model pages should identify the exact variant, define symbols and units, cite the relevant paper or equation, and distinguish the published model from SU2's implementation. Developer pages should connect implementation steps to the source and an appropriate test. + +See [Documentation Improvements and Status](../Documentation-Status/) for what has changed, outstanding review and maintenance work, and the next priorities. diff --git a/_docs_v7/Wall-Treatment.md b/_docs_v7/Wall-Treatment.md new file mode 100644 index 00000000..0d9d1d0a --- /dev/null +++ b/_docs_v7/Wall-Treatment.md @@ -0,0 +1,234 @@ +--- +title: "Wall Treatment: Wall Functions and Roughness" +permalink: /docs_v7/Wall-Treatment/ +--- + +This page explains the model and its SU2 implementation. For numerical setup choices, see the [setup guide](../Setup-Guide-RANS-External-Aero/); use its tutorial and V&V links for worked examples and comparisons. + +This page covers two ways to change what a turbulence model does at a viscous wall. *Wall functions* replace the resolved near-wall layer with an analytical law of the wall, so the first mesh point can be further from the wall. *Roughness models* change the wall boundary condition of the turbulence model to represent roughness effects on turbulence and wall friction. Heat transfer is then affected through the coupled solution and heat-transport closure; these are not universal correlations for rough-wall heat transfer. + +For the SA and SST models themselves, see [Turbulence Models](../Turbulence-Models/). For the basic wall boundary conditions, see [Markers and Boundary Conditions](../Markers-and-BC/). + +--- + +- [Wall functions](#wall-functions) + - [How to select them](#how-to-select-them) + - [What SU2 does](#what-su2-does) + - [LES wall models for the DG solver](#les-wall-models-for-the-dg-solver) +- [Wall roughness](#wall-roughness) + - [How to select it](#how-to-select-it) + - [Roughness with SA](#roughness-with-sa) + - [Roughness with SST](#roughness-with-sst) +- [What SU2 does differently from the literature](#what-su2-does-differently-from-the-literature) +- [Equations and references](#equations-and-references) +- [Recommended use](#recommended-use) +- [Verification and test cases](#verification-and-test-cases) +- [Known limits](#known-limits) +- [Links](#links) + +--- + +## Wall functions + +### How to select them + +List the wall markers and the wall function type in `MARKER_WALL_FUNCTIONS`: + +``` +SOLVER= RANS +KIND_TURB_MODEL= SST +MARKER_HEATFLUX= ( wall, 0.0 ) +MARKER_WALL_FUNCTIONS= ( wall, STANDARD_WALL_FUNCTION ) +``` + +The format is `( marker, type, marker, type, ... )`. Some types need extra values after the type (see [LES wall models](#les-wall-models-for-the-dg-solver)). + +| Type | Status in SU2 develop | +|---|---| +| `NO_WALL_FUNCTION` | No wall function on this marker (the default for unlisted markers). | +| `STANDARD_WALL_FUNCTION` | The wall function of the finite-volume solvers. Only with `SOLVER= RANS` or `INC_RANS`, else SU2 stops with an error. Works with SA and SST. | +| `EQUILIBRIUM_WALL_MODEL` | LES wall model of the high-order DG solver. Not used by the finite-volume solvers. | +| `LOGARITHMIC_WALL_MODEL` | LES wall model of the high-order DG solver. Not used by the finite-volume solvers. | +| `ADAPTIVE_WALL_FUNCTION`, `SCALABLE_WALL_FUNCTION`, `NONEQUILIBRIUM_WALL_MODEL` | Not implemented. SU2 stops with an error. | + +The `STANDARD_WALL_FUNCTION` has five expert options: + +| Option | Default | What it does | +|---|---|---| +| `WALLMODEL_KAPPA` | `0.41` | Von Karman constant of the law of the wall. Also used by the SST wall function and by the `LIMITER_KNOPP` roughness model. | +| `WALLMODEL_B` | `5.5` | Additive constant B of the law of the wall. | +| `WALLMODEL_MINYPLUS` | `5.0` | The wall function acts only where y+ is at or above this value. | +| `WALLMODEL_MAXITER` | `200` | Maximum Newton iterations for the friction velocity (and for ν̃ in SA). | +| `WALLMODEL_RELFAC` | `0.5` | Relaxation factor of the Newton iterations. The SST wall function also uses it to relax the new k and ω values. | + +### What SU2 does + +The wall function follows Nichols and Nelson (2004). At each time step or iteration, for each wall node with a wall function: + +1. SU2 takes the tangential velocity at the first interior node along the wall normal. +2. It solves Spalding's law of the wall for the friction velocity with a damped Newton method. The compressible solver uses the White–Christoph form, which includes compressibility and heat transfer. The incompressible solver uses the incompressible, adiabatic form. +3. In the compressible solver, on walls that are not isothermal, it updates the wall temperature with the Crocco–Busemann relation (frictional heating). +4. It stores the wall shear stress from the law. On the edges that connect the wall node to interior nodes, the viscous flux is scaled so that the wall shear stress equals this value. The velocity at the wall stays zero (no-slip). +5. The turbulence solver sets its variables at the first interior node: + - **SA**: ν̃ is found from the eddy viscosity of the law of the wall (Newton method on the fv1 relation). + - **SST**: ω is the blend of the viscous-sublayer and log-layer values of Nichols and Nelson. k follows from ω and the eddy viscosity of the law of the wall. Both are relaxed with `WALLMODEL_RELFAC`. + +Where y+ is below `WALLMODEL_MINYPLUS`, the flow solver uses the normal no-slip wall. SU2 then prints how many points have a small y+. If the Newton method does not converge, SU2 prints a warning with the number of points. + +The y+ in the output (`Y_PLUS`) is the y+ from the wall function on these markers. + +The [Markers and BC](../Markers-and-BC/#wall-functions) and [Theory](../Theory/#wall-functions) pages also describe the wall function. + +### LES wall models for the DG solver + +`EQUILIBRIUM_WALL_MODEL` and `LOGARITHMIC_WALL_MODEL` are used only by the high-order discontinuous Galerkin (DG) solver (`FEM_NAVIER_STOKES`, `FEM_LES`), on isothermal and heat flux walls. Each needs three values after the type: + +``` +MARKER_WALL_FUNCTIONS= ( wall, EQUILIBRIUM_WALL_MODEL, 0.05, 1.1, 30 ) +``` + +The values are the height of the exchange point (where the model reads the outer flow), the stretching factor of the 1D wall-model grid, and its number of points. `LOGARITHMIC_WALL_MODEL` uses the Reichardt law for velocity and the Kader law for temperature. The values in the example are only placeholders (to be reviewed). + +## Wall roughness + +### How to select it + +Give each rough marker its roughness height in `WALL_ROUGHNESS`: + +``` +MARKER_HEATFLUX= ( wall, 0.0 ) +WALL_ROUGHNESS= ( wall, 400e-6 ) +``` + +- The value is the *equivalent sand-grain roughness* k_s: the grain size of a sand-covered surface with the same friction. It is not the measured height of the real roughness. Conversion from real surfaces needs a correlation from the literature. +- Give k_s in the length unit of the mesh (metres for a mesh in metres). +- A marker with k_s = 0, or not listed, is smooth. +- The marker must be a viscous wall: `MARKER_HEATFLUX`, `MARKER_ISOTHERMAL`, `MARKER_HEATTRANSFER` or a CHT interface. Else SU2 stops with an error. +- At each node, SU2 uses the roughness of the nearest wall (found with the wall distance search). +- `WALL_ROUGHNESS` cannot be combined with `STANDARD_WALL_FUNCTION` on any marker. SU2 stops with an error. + +There is no separate on/off switch. Setting a positive k_s turns on the rough-wall model of the active turbulence model. + +`HROUGHNESS` is a different option: it is a roughness input of the LM transition model, not a wall roughness. See [Transition Models](../Transition-Models/). + +### Roughness with SA + +SU2 uses the rough-wall extension of Aupoix and Spalart (2003), in the form of the [NASA Turbulence Modeling Resource](https://tmbwg.github.io/turbmodels/spalart.html#sarough). No option selects it: it is always on for SA when k_s > 0. + +- The wall distance in the SA model becomes d + 0.03 k_s. +- χ = ν̃/ν gets the extra term c_R1 k_s / d, with c_R1 = 0.5. +- The wall condition ν̃ = 0 is replaced by a gradient condition: dν̃/dn = ν̃ / (0.03 k_s). So ν̃ and the eddy viscosity are not zero at a rough wall. +- The skin friction on a rough wall uses the laminar plus the eddy viscosity at the wall. + +### Roughness with SST + +For SST, the roughness model only changes the wall values of k and ω. Choose the model with `KIND_ROUGHSST_MODEL`: + +| `KIND_ROUGHSST_MODEL` | Wall values | +|---|---| +| `WILCOX1998` (default) | k = 0. ω from the roughness function S_R of Wilcox (1998). | +| `WILCOX2006` | k = 0. ω from the roughness function S_R of Wilcox (2006). | +| `LIMITER_KNOPP` | k > 0 and ω from Knopp et al. (2009). | +| `LIMITER_AUPOIX` | k ≥ 0 and ω from Aupoix (2015). | + +All four use the roughness in wall units, k+ = u_τ k_s / ν, at the wall node. `KIND_ROUGHSST_MODEL` has no effect without a positive `WALL_ROUGHNESS`. + +## What SU2 does differently from the literature + +All facts below are from the SU2 code, in the files `SU2_CFD/src/solvers/CNSSolver.cpp`, `CIncNSSolver.cpp`, `CTurbSASolver.cpp`, `CTurbSSTSolver.cpp`, `SU2_CFD/include/numerics/turbulent/turb_sources.hpp`. + +**Wall functions** + +- **Vertex-based grid.** Nichols and Nelson use the first cell center. SU2 uses the first interior node along the wall normal. The wall node itself stays on the wall with zero velocity. The law sets the stress on the edges from the wall node, not a slip velocity. +- **Heat flux in the law.** In the compressible solver, the heat flux term of the White–Christoph law uses the `MARKER_HEATFLUX` value. On isothermal walls, SU2 sets this heat flux to zero inside the law and keeps the wall temperature fixed. +- **Incompressible solver.** The law has no compressibility or heat transfer terms. Wall functions on a CHT interface stop with an error in the incompressible solver. +- **Below `WALLMODEL_MINYPLUS`** the flow solver falls back to the no-slip wall. The turbulence solver then sets no wall condition at all at that node: ν̃ (SA) or k and ω (SST) at the wall are left free. A wall-resolved RANS sets ν̃ = 0, or k = 0 and a large ω, at the wall (to be reviewed). +- **Non-converged Newton method.** SU2 falls back to fixed values (y+ = 30, friction velocity 1, eddy viscosity 1) in the units of the run. Watch for the warning message. +- **SST ω and k.** ω follows Nichols and Nelson (eqs. 19–21). k = ω μt / ρ uses the density at the wall. A code comment asks whether this is right, because the paper writes ρ, not ρ_wall. + +**SA roughness** + +- The modified χ enters fv1 and ft2. fv2 uses the unmodified χ = ν̃/ν. The code comment says this keeps the modified vorticity unchanged, following the TMR page and the 2003 paper (to be reviewed). +- With DES (`HYBRID_RANSLES`), the SA source term uses the DES length scale and ignores the roughness. The rough-wall condition and the eddy viscosity still use it. See [Hybrid RANS/LES](../Hybrid-RANS-LES/). + +**SST roughness** + +- k+ uses the wall shear stress from the previous force evaluation, so it lags by one iteration. +- `LIMITER_KNOPP` limits ω at the wall to the smooth-wall value 60ν/(β1 d1²), where d1 is the distance from the wall node to its nearest neighbor node. It uses `WALLMODEL_KAPPA` as the von Karman constant (to be reviewed). +- Roughness changes only the wall values. The SST source terms are unchanged. + +## Equations and references + +This page does not repeat the equations. See: + +- Wall functions: R. H. Nichols, C. C. Nelson, "Wall function boundary conditions including heat transfer and compressibility", *AIAA J.* 42(6), 1107–1114, 2004. [doi:10.2514/1.3539](https://doi.org/10.2514/1.3539) +- Law of the wall: D. B. Spalding, "A single formula for the law of the wall", *J. Appl. Mech.* 28, 455–458, 1961. [doi:10.1115/1.3641728](https://doi.org/10.1115/1.3641728) +- SA roughness: B. Aupoix, P. R. Spalart, "Extensions of the Spalart–Allmaras turbulence model to account for wall roughness", *Int. J. Heat Fluid Flow* 24, 454–462, 2003. [doi:10.1016/S0142-727X(03)00043-2](https://doi.org/10.1016/S0142-727X(03)00043-2). Summary: [TMR, SA rough-wall extension](https://tmbwg.github.io/turbmodels/spalart.html#sarough). +- SST roughness, `WILCOX1998` and `WILCOX2006`: D. C. Wilcox, *Turbulence Modeling for CFD*, DCW Industries, 2nd edition 1998 and 3rd edition 2006. +- SST roughness, `LIMITER_KNOPP`: T. Knopp, B. Eisfeld, J. B. Calvo, "A new extension for k–ω turbulence models to account for wall roughness", *Int. J. Heat Fluid Flow* 30, 54–65, 2009. [doi:10.1016/j.ijheatfluidflow.2008.09.009](https://doi.org/10.1016/j.ijheatfluidflow.2008.09.009) +- SST roughness, `LIMITER_AUPOIX`: B. Aupoix, "Roughness corrections for the k–ω shear stress transport model: status and proposals", *J. Fluids Eng.* 137(2), 021202, 2015. [doi:10.1115/1.4028122](https://doi.org/10.1115/1.4028122) +- SA and SST models: [NASA Turbulence Modeling Resource](https://tmbwg.github.io/turbmodels/). + +## Recommended use + +All advice in this section is general practice, not checked in SU2 (to be reviewed). + +**Wall functions** + +- Aim for the first interior node in the log layer: y+ about 30 to 100. The upper limit grows with the Reynolds number. The [Markers and BC](../Markers-and-BC/#wall-functions) page gives a broader 100 to 500 range. Neither range is a universal upper accuracy bound: verify log-layer placement for the Reynolds number, pressure gradient and wall treatment in use (advice, to be reviewed). +- Avoid a first node in the buffer layer (y+ about 5 to 30) on large parts of the wall (to be reviewed). +- Wall functions assume an attached boundary layer in equilibrium. Expect lower accuracy near separation, reattachment and strong pressure gradients (to be reviewed). +- List every viscous wall in `MARKER_WALL_FUNCTIONS` (see [Known limits](#known-limits)). +- If the "did not converge" warning stays, increase `WALLMODEL_MAXITER` or decrease `WALLMODEL_RELFAC` (from the [Markers and BC](../Markers-and-BC/#wall-functions) page). +- Check the y+ field (`Y_PLUS`) on the walls after the run. + +**Roughness** + +- Resolve the wall as for a smooth wall: y+ about 1 at the first node (to be reviewed). +- `LIMITER_KNOPP` and `LIMITER_AUPOIX` were proposed to fix known weaknesses of the Wilcox wall values on fine meshes and at small roughness (to be reviewed). +- Check k+ against the range the chosen model was calibrated for (to be reviewed). + +## Verification and test cases + +There is no verification case for wall functions or roughness in the [V&V section](/vandv/home/). The regression tests check that the options run. + +Wall functions (all on a flat plate, `STANDARD_WALL_FUNCTION`): + +- [`wallfunctions/flatplate/compressible_SA/turb_SA_flatplate.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/wallfunctions/flatplate/compressible_SA/turb_SA_flatplate.cfg), and [`turb_SA_flatplate_restart.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/wallfunctions/flatplate/compressible_SA/turb_SA_flatplate_restart.cfg) +- [`wallfunctions/flatplate/compressible_SST/turb_SST_flatplate.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/wallfunctions/flatplate/compressible_SST/turb_SST_flatplate.cfg) +- [`wallfunctions/flatplate/incompressible_SA/turb_SA_flatplate.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/wallfunctions/flatplate/incompressible_SA/turb_SA_flatplate.cfg) +- [`wallfunctions/flatplate/incompressible_SST/turb_SST_flatplate.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/wallfunctions/flatplate/incompressible_SST/turb_SST_flatplate.cfg) + +Roughness: + +- SA, incompressible: [`incomp_rans/rough_flatplate/rough_flatplate_incomp.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_rans/rough_flatplate/rough_flatplate_incomp.cfg) and [`pb_rough_flatplate_incomp.cfg`](https://github.com/su2code/SU2/blob/develop/TestCases/incomp_rans/rough_flatplate/pb_rough_flatplate_incomp.cfg) (pressure-based solver). +- SST, compressible: [`WILCOX2006`](https://github.com/su2code/SU2/blob/develop/TestCases/rans/flatplate/roughness/bc_wilcox2006/turb_SST_flatplate_roughBCWilcox2006.cfg), [`LIMITER_KNOPP`](https://github.com/su2code/SU2/blob/develop/TestCases/rans/flatplate/roughness/bc_knopp/turb_SST_flatplate_roughBCKnopp.cfg), [`LIMITER_AUPOIX`](https://github.com/su2code/SU2/blob/develop/TestCases/rans/flatplate/roughness/bc_aupoix/turb_SST_flatplate_roughBCAupoix.cfg). No test uses the default `WILCOX1998`. +- No test uses SA roughness in the compressible solver. + +Tutorials with wall functions: + +- [Turbulent Bend with wall functions](/tutorials/Inc_Turbulent_Bend/): incompressible, SST, compared with measurements. +- [Aachen Turbine](/tutorials/Aachen_Turbine/): compressible turbomachinery, SA. + +## Known limits + +- **List all viscous walls.** The turbulence solvers check one global flag: "does any marker have a wall function?" If yes, they apply the wall-function condition on every heat flux and isothermal wall, also on walls not listed in `MARKER_WALL_FUNCTIONS`. The flow solver applies the law of the wall only on the listed markers. A mix of listed and unlisted walls is therefore inconsistent (code, `CTurbSASolver::BC_HeatFlux_Wall`, `CTurbSSTSolver::BC_HeatFlux_Wall`). +- **Small y+.** Below `WALLMODEL_MINYPLUS`, the turbulence variables at the wall get no boundary condition (see [What SU2 does differently](#what-su2-does-differently-from-the-literature)). A mesh with y+ much below 5 should be run without wall functions (to be reviewed). +- **DG wall model types in RANS.** `EQUILIBRIUM_WALL_MODEL` passes the config check in a finite-volume RANS run, but the finite-volume flow solver ignores it. The turbulence solver still switches to its wall-function condition. +- **Wall functions and roughness** cannot be combined. +- **SA roughness and DES**: the SA source term ignores the roughness. Only the rough-wall condition and the eddy viscosity use it. +- **Incompressible CHT interfaces** do not support wall functions. + +## Links + +- [Markers and Boundary Conditions](../Markers-and-BC/) +- [Turbulence Models](../Turbulence-Models/) +- [Hybrid RANS/LES (DES)](../Hybrid-RANS-LES/) +- [Setup Guide: RANS External Aerodynamics](../Setup-Guide-RANS-External-Aero/) +- [Setup Guide: Unsteady Flows and DES](../Setup-Guide-Unsteady-DES/) +- [Option Reference](../Option-Reference/) +- [Output Fields Reference](../Output-Fields-Reference/) + +--- + +Source review: 22 October 2026, against [SU2 `docs_site` at `41ea6a219a`](https://github.com/rois1995/SU2/tree/41ea6a219ac038574f3d4a5b130c0c1d8af66457). See the [review scope and outstanding validation](../Documentation-Status/#guide-and-model-review). Setup recommendations remain draft where indicated. diff --git a/_docs_v7/contribute.md b/_docs_v7/contribute.md index 6c8af16a..8611e5df 100644 --- a/_docs_v7/contribute.md +++ b/_docs_v7/contribute.md @@ -3,31 +3,42 @@ title: Contribute permalink: /docs_v7/contribute/ --- -Do you want to contribute to the SU2 documentation? It's easy! Just create a fork of the [SU2 Project Website repository](https://github.com/su2code/su2code.github.io), write your documentation, and open a pull request. +Documentation contributions include correcting explanations, checking examples, improving source comments and reviewing draft guidance. Start with [Using the Documentation](../Using-the-Documentation/) for the role of each section and [Documentation Improvements and Status](../Documentation-Status/) for completed work, remaining gaps and priorities. -## Writing content +## Choose the owning repository -The documentation in this site is stored under the `_docs` folder. To add your contributions: +| Content | Where to edit | +| --- | --- | +| User guide, model explanations and setup guides | `_docs_v7/` in the website repository. | +| Complete worked examples | `_tutorials/` in the website repository. | +| Verification and validation comparisons | `_vandv/` in the website repository. | +| Developer pages and the documentation status record | `Docs/website/pages/` in the SU2 source repository. The build overlays these pages onto the website. | +| Option descriptions | The registration comments in `Common/src/CConfig.cpp`, with consistent examples in `config_template.cfg`. | +| Generated references and checks | Their tools in `Docs/website/tools/`; do not edit generated website copies. | -**1.** Add a new Markdown file inside the subfolder, as `_docs/Your_Documentation.md`. Add the following [front matter](https://jekyllrb.com/docs_v7/frontmatter/) to your file: +The current overhaul is maintained on the `docs_site` branches of [rois1995/SU2](https://github.com/rois1995/SU2/tree/docs_site) and [rois1995/su2code.github.io](https://github.com/rois1995/su2code.github.io/tree/docs_site). The fork preview does not imply official adoption. Proposals for the official repositories need a separate review through their contribution process. -``` +## Write and connect the page + +Use a focused explanation and link to related material instead of duplicating it. State the applicable version, assumptions and evidence; retain draft labels where review is incomplete. + +A user-guide page needs front matter such as: + +```markdown --- title: Your Documentation Page -permalink: /docs_v7/Your_Documentation/ +permalink: /docs_v7/Your-Documentation/ --- - -I'm contributing to SU2! Don't forget the trailing '/' on the permalink! ``` -**2.** Add the documentation pagename to the `_data/docs.yml` file, in order to list it in the navigation panel (create a new subgroup if necessary): +Add its file stem to the relevant section of `_data/docs_v7.yml`. Tutorials and V&V use their corresponding collections and navigation files. Developer pages in `Docs/website/pages/` are added to the built menu by the generator. Put website images in `docs_files/`; developer-page assets can use `Docs/website/pages/img/`. Keep relative links valid under the preview's `/SU2` base path. -``` -- title: Your Subgroup of Documentation - docs: - - Your_Documentation -``` +For theoretical claims, identify the model variant and cite the relevant paper or equation. For implementation claims, identify the source and checked version. A short regression run is evidence of that check, not proof of convergence or physical validation. + +## Check and record the change + +Use the shared build described in [Docs/website/README.md](https://github.com/rois1995/SU2/blob/docs_site/Docs/website/README.md). It runs the regression checks, generates references, builds the site and checks internal links, configuration facts and search coverage. Both repositories' pull-request workflows also build checked previews. -**3.** If you have supporting images or other auxiliary files, please add them to the folder `docs_files` in the root directory of the repository. Don't forget to add the correct relative links to these files in your docs, if necessary. +When a batch is completed, update the relevant status/backlog row and dated history in [Documentation Improvements and Status](../Documentation-Status/#keeping-this-page-current), with links to its changes and the checks actually performed. Remove a historical baseline entry only when its finding is resolved. Do not mark scientific guidance as reviewed or validated based only on a successful website build. -**4.** When you are ready, submit a pull request to the **develop** branch of the [repository](https://github.com/su2code/su2code.github.io)... and it's all done! Thanks for your contribution! +For website-only changes, publish the reviewed website commit through the SU2 **Docs Website** workflow. The build manifest records both source revisions; the status page explains the current publishing and review limits. diff --git a/_docs_v7/index.md b/_docs_v7/index.md index 9f630b3d..fc48d325 100644 --- a/_docs_v7/index.md +++ b/_docs_v7/index.md @@ -11,3 +11,5 @@ disable_comments: true The SU2 suite is an open-source collection of C++ based software tools for performing Partial Differential Equation (PDE) analysis and solving PDE-constrained optimization problems. The toolset is designed with Computational Fluid Dynamics (CFD) and aerodynamic shape optimization in mind, but is extensible to treat arbitrary sets of governing equations such as potential flow, elasticity, electrodynamics, chemically-reacting flows, and many others. SU2 is under active development by individuals all around the world on [GitHub](https://github.com/su2code/SU2) and is released under an open-source license. For a detailed description of the code philosophy, components, and implementations, please see our [SU2 AIAA Journal article](http://arc.aiaa.org/doi/abs/10.2514/1.J053813). + +Start with [Using the Documentation](../Using-the-Documentation/) to find setup guidance, worked tutorials, model explanations and verification and validation cases. diff --git a/_includes/setup-guide-intro.md b/_includes/setup-guide-intro.md new file mode 100644 index 00000000..8ac266fd --- /dev/null +++ b/_includes/setup-guide-intro.md @@ -0,0 +1,5 @@ +> **Draft.** These settings are drawn from SU2 source, tutorials and regression cases. Recommendations marked **(to be reviewed)** still need an experienced user's review. + +Use this guide to choose settings and understand their consequences. Follow the linked [Tutorials]({{ '/tutorials/home/' | relative_url }}) for worked examples and consult [V&V]({{ '/vandv/home/' | relative_url }}) for numerical and physical comparisons. Example settings are starting points, not evidence that a case is converged or validated. + +The [documentation guide]({{ '/docs_v7/Using-the-Documentation/' | relative_url }}#sources-and-review-status) explains the source tags used below: **(code)**, **(test case)**, **(tutorial)**, **(docs)**, **(advice)** and **(to be reviewed)**. diff --git a/_includes/topnav.html b/_includes/topnav.html index 60e22f64..dfd1642c 100644 --- a/_includes/topnav.html +++ b/_includes/topnav.html @@ -26,6 +26,7 @@