# Turbulence Quantities

Turbulence quantities can be specified for certain boundary conditions (Freestream and Inflow) to better control the turbulence characteristics of the flow entering the domain. These settings are particularly important for accurately capturing boundary layer development and transition.

Important: You can specify at most two turbulence parameters at once. If more are provided, the specification will be invalid.

# 📋 Available Methods

You can specify turbulence quantities using one of the following methods, depending on your turbulence model:

# For Both Spalart-Allmaras and k-ω SST Models:

Parameter Description Unit
Turbulent Viscosity Ratio The ratio between turbulent viscosity and laminar viscosity

# For Spalart-Allmaras Model Only:

Parameter Description Unit
Modified Viscosity Ratio The ratio between modified turbulent viscosity (nuHat) and freestream laminar viscosity
Modified Viscosity The absolute value of the modified turbulent viscosity (nuHat) viscosity (e.g. m²/s)

# For k-ω SST Model Only:

Parameter Description Unit
Turbulent Intensity Relative turbulence level (as a decimal, not percentage) dimensionless (-)
Turbulent Length Scale Characteristic size of turbulent eddies length (e.g. m)
Turbulent Kinetic Energy Energy per unit mass in turbulent fluctuations specific energy (e.g. m²/s²)
Specific Dissipation Rate Rate at which turbulence energy converts to thermal energy frequency (e.g. 1/s)

# 🔍 Detailed Descriptions

# Viscosity Ratio

The ratio between turbulent viscosity and laminar viscosity.

  • Default: Model-dependent
  • Example: 5.0
  • Notes: Suitable for both Spalart-Allmaras and k-ω SST turbulence models. For Spalart-Allmaras, this value is converted to Modified Viscosity Ratio. Typical values: 0.1-10 for external aerodynamics, 10-100 for internal flows.

# Modified Viscosity Ratio

The ratio between modified turbulent viscosity (nuHat) and freestream laminar viscosity.

  • Default: 3.0 without transition model, 0.1 with transition model
  • Example: 5.0
  • Notes: Applicable only to Spalart-Allmaras model. Typical range: 1-10 for most applications.

# Modified Viscosity

The absolute value of the modified turbulent viscosity (nuHat).

  • Default: Depends on freestream conditions
  • Example: 1e-4 * u.m**2 / u.s
  • Notes: Applicable only to Spalart-Allmaras model. Units: Dimensional value with units of viscosity.

# Turbulent Intensity

Relative turbulence level (as a decimal, not percentage).

  • Default: Model-dependent
  • Example: 0.01 (1%)
  • Notes: Used in formula: k = 1.5(U_ref × I)² where k is turbulent kinetic energy, U_ref is reference velocity, I is intensity. Typical values: 0.001-0.01 (0.1-1%) for external flows, 0.01-0.1 (1-10%) for internal flows.

# Turbulent Length Scale

Characteristic size of turbulent eddies.

  • Default: Proportional to domain size
  • Example: 0.1 * u.m
  • Notes: Typically proportional to characteristic length of the domain. For example, 10% of inlet diameter for internal flows.

# Turbulent Kinetic Energy

Energy per unit mass in turbulent fluctuations.

  • Default: Calculated based on other parameters if not specified
  • Example: 0.003 * u.m**2 / u.s**2
  • Notes: Most precise method when specific k value is known. Requires dimensional value in consistent units.

# Specific Dissipation Rate

Rate at which turbulence energy converts to thermal energy.

  • Default: Calculated as MachRef/L_box where L_box is the geometric mean of the bounding box dimensions for wall boundaries
  • Example: 50.0 / u.s
  • Notes: Requires dimensional value in consistent units.

# 💡 Valid Parameter Combinations

The following combinations are valid:

  • Single parameter:

    • viscosity_ratio (both SA and SST)
    • modified_viscosity_ratio (SA only)
    • modified_viscosity (SA only)
    • turbulent_kinetic_energy (SST only)
    • turbulent_intensity (SST only)
    • turbulent_length_scale (SST only)

  • Two parameter combinations for SST model:

    • turbulent_kinetic_energy + specific_dissipation_rate
    • turbulent_kinetic_energy + viscosity_ratio
    • turbulent_kinetic_energy + turbulent_length_scale
    • turbulent_intensity + specific_dissipation_rate
    • turbulent_intensity + viscosity_ratio
    • turbulent_intensity + turbulent_length_scale
    • specific_dissipation_rate + viscosity_ratio
    • specific_dissipation_rate + turbulent_length_scale
    • viscosity_ratio + turbulent_length_scale

❓ Frequently Asked Questions

  • What happens if I don't specify any turbulence quantities?

    Default values will be used. For Spalart-Allmaras model without transition: Equivalent to Modified Viscosity Ratio = 3.0. For Spalart-Allmaras model with transition: Equivalent to Modified Viscosity Ratio = 0.1. For k-ω SST model: Equivalent to Viscosity Ratio = 0.01 with Specific Dissipation Rate calculated based on domain size.

  • When should I specify custom turbulence quantities?

    Consider specifying when accurate turbulence properties at boundaries are critical to your simulation, when simulating flows with known turbulence characteristics (e.g., wind tunnel experiments), when default turbulence initialization is insufficient for your application, or when modeling transitional flows or flows with specific turbulence levels.

  • What are recommended values for external aerodynamics?

    For external aerodynamics (Freestream), lower turbulence levels are typically appropriate. For viscosity ratio, values between 0.1-10 are common. For turbulent intensity, values between 0.001-0.01 (0.1-1%) are typical.

  • What are recommended values for internal flows?

    For internal flows (Inflow), higher turbulence levels may be needed depending on upstream conditions. For viscosity ratio, values between 10-100 are common. For turbulent intensity, values between 0.01-0.1 (1-10%) are typical.

  • How is the default specific dissipation rate calculated?

    For SST model, the default specific dissipation rate is calculated as MachRef/L_box where L_box is the geometric mean of the bounding box dimensions for wall boundaries.

🐍 Python Example Usage

# Creating Turbulence Quantities Objects

# Import required modules
from flow360 import u
from flow360 import SimulationParams, TurbulenceQuantities

# 1. Basic turbulence quantity specifications
# --------------------------------------------

# For Spalart-Allmaras model - single parameter
turb_quantities_sa1 = TurbulenceQuantities(
    viscosity_ratio=5.0  # Works for both SA and SST
)

turb_quantities_sa2 = TurbulenceQuantities(
    modified_viscosity_ratio=10.0  # SA model only
)

turb_quantities_sa3 = TurbulenceQuantities(
    modified_viscosity=1e-4 * u.m**2 / u.s  # SA model only
)

# For k-ω SST model - single parameter
turb_quantities_sst1 = TurbulenceQuantities(
    turbulent_intensity=0.01  # 1% intensity, SST model only
)

turb_quantities_sst2 = TurbulenceQuantities(
    turbulent_length_scale=0.1 * u.m  # SST model only
)

turb_quantities_sst3 = TurbulenceQuantities(
    turbulent_kinetic_energy=0.003 * u.m**2 / u.s**2  # SST model only
)

turb_quantities_sst4 = TurbulenceQuantities(
    specific_dissipation_rate=50.0 / u.s  # SST model only
)

# 2. Combined parameter specifications for SST model
# -------------------------------------------------

# Turbulent kinetic energy combinations
turb_quantities_sst5 = TurbulenceQuantities(
    turbulent_kinetic_energy=0.003 * u.m**2 / u.s**2,
    specific_dissipation_rate=50.0 / u.s
)

turb_quantities_sst6 = TurbulenceQuantities(
    turbulent_kinetic_energy=0.003 * u.m**2 / u.s**2,
    viscosity_ratio=10.0
)

turb_quantities_sst7 = TurbulenceQuantities(
    turbulent_kinetic_energy=0.003 * u.m**2 / u.s**2,
    turbulent_length_scale=0.05 * u.m
)

# Turbulent intensity combinations
turb_quantities_sst8 = TurbulenceQuantities(
    turbulent_intensity=0.01,  # 1%
    specific_dissipation_rate=50.0 / u.s
)

turb_quantities_sst9 = TurbulenceQuantities(
    turbulent_intensity=0.01,  # 1%
    viscosity_ratio=10.0
)

turb_quantities_sst10 = TurbulenceQuantities(
    turbulent_intensity=0.01,  # 1%
    turbulent_length_scale=0.05 * u.m
)

# Other combinations
turb_quantities_sst11 = TurbulenceQuantities(
    specific_dissipation_rate=50.0 / u.s,
    viscosity_ratio=10.0
)

turb_quantities_sst12 = TurbulenceQuantities(
    specific_dissipation_rate=50.0 / u.s,
    turbulent_length_scale=0.05 * u.m
)

turb_quantities_sst13 = TurbulenceQuantities(
    viscosity_ratio=10.0,
    turbulent_length_scale=0.05 * u.m
)

# Using Turbulence Quantities with Boundary Conditions

# Import required modules
import flow360 as fl
from flow360 import u
from flow360 import TurbulenceQuantities


# 1. Freestream boundary with turbulence quantities
# -------------------------------------------------

# External aerodynamics example with Spalart-Allmaras turbulence model
freestream_sa = fl.Freestream(
    entities=volume_mesh["farfield"],
    turbulence_quantities=TurbulenceQuantities(
        modified_viscosity_ratio=3.0  # Common for external aerodynamics with SA model
    )
)

# External aerodynamics example with k-ω SST turbulence model
freestream_sst = fl.Freestream(
    entities=volume_mesh["farfield"],
    # Override default velocity if needed
    velocity=[200.0 * u.m / u.s, 0.0 * u.m / u.s, 0.0 * u.m / u.s],
    turbulence_quantities=TurbulenceQuantities(
        turbulent_intensity=0.001,  # 0.1% - low turbulence external flow
        turbulent_length_scale=1.0 * u.m  # Based on characteristic length
    )
)

# 2. Inflow boundary with turbulence quantities
# ---------------------------------------------

# Subsonic inlet for internal flow with SA model
inflow_sa = fl.Inflow(
    entities=volume_mesh["inlet"],
    total_temperature=300 * u.K,
    spec=fl.TotalPressure(
        value=101325 * u.Pa,
        velocity_direction=(1, 0, 0)  # Flow direction
    ),
    turbulence_quantities=TurbulenceQuantities(
        viscosity_ratio=50.0  # Higher turbulence for internal flow
    )
)

# Subsonic inlet for internal flow with k-ω SST model
inflow_sst1 = fl.Inflow(
    entities=volume_mesh["inlet"],
    total_temperature=300 * u.K,
    spec=fl.TotalPressure(
        value=101325 * u.Pa,
        velocity_direction=(1, 0, 0)
    ),
    turbulence_quantities=TurbulenceQuantities(
        turbulent_intensity=0.05,  # 5% - moderate turbulence
        specific_dissipation_rate=100.0 / u.s
    )
)

# Mass flow inlet with turbulence quantities
inflow_sst2 = fl.Inflow(
    entities=volume_mesh["inlet"],
    total_temperature=350 * u.K,
    spec=fl.MassFlowRate(
        value=1.0 * u.kg / u.s,
        ramp_steps=100  # Gradually increase to target mass flow
    ),
    turbulence_quantities=TurbulenceQuantities(
        turbulent_kinetic_energy=0.01 * u.m**2 / u.s**2,
        turbulent_length_scale=0.01 * u.m  # 1cm - typical for small ducts
    )
)

# 3. Complete simulation setup example
# -----------------------------------

# Create simulation parameters with boundary conditions that include turbulence quantities
sim_params = fl.SimulationParams(
    # Other simulation parameters would be here
    models=[
        # External flow example (e.g., airfoil in freestream)
        fl.Freestream(
            entities=volume_mesh["farfield"],
            turbulence_quantities=TurbulenceQuantities(
                viscosity_ratio=1.0  # Moderate turbulence for external flow
            )
        ),
        fl.Wall(
            entities=volume_mesh["airfoil_surface"],
            use_wall_function=False  # Resolve boundary layer
        ),
        
        # Internal flow example (e.g., duct with inlet and outlet)
        fl.Inflow(
            entities=volume_mesh["duct_inlet"],
            total_temperature=300 * u.K,
            spec=fl.TotalPressure(value=120000 * u.Pa),
            turbulence_quantities=TurbulenceQuantities(
                turbulent_intensity=0.05,  # 5%
                turbulent_length_scale=0.02 * u.m  # Based on inlet diameter
            )
        ),
        fl.Outflow(
            entities=volume_mesh["duct_outlet"],
            spec=fl.Pressure(value=101325 * u.Pa)
        ),
        fl.Wall(
            entities=volume_mesh["duct_walls"],
            use_wall_function=True  # Use wall function for efficiency
        )
    ]
)

# 4. Automated farfield with turbulence quantities
# -----------------------------------------------

# Create an automated farfield
auto_farfield = fl.AutomatedFarfield()

# Use the generated farfield boundary with turbulence quantities
freestream_with_auto_farfield = fl.Freestream(
    entities=[auto_farfield.farfield],
    turbulence_quantities=TurbulenceQuantities(
        turbulent_intensity=0.001,  # 0.1%
        turbulent_length_scale=10.0 * u.m  # Large length scale for farfield
    )
)

# Complete setup with automated farfield
sim_params_with_auto_farfield = fl.SimulationParams(
    # Other parameters would go here
    models=[
        freestream_with_auto_farfield,
        # Other boundaries would go here
    ]
)

# Notes on Usage

  1. For Spalart-Allmaras model:

    • viscosity_ratio, modified_viscosity_ratio, or modified_viscosity can be specified
    • Only one parameter should be provided

  2. For k-ω SST model:

    • Many combinations are valid (see "Valid Parameter Combinations" section)
    • Most common: turbulent intensity + length scale or k + omega
    • Single parameters will use defaults for the other required values

  3. Best practices:

    • For external aerodynamics (Freestream), use lower turbulence levels
    • For internal flows (Inflow), use higher turbulence levels
    • When working with experimental data, try to match measured turbulence quantities

← 3D Models →