[FXC-4820] Supersonic

docs/02.simulation-setup/03.flow-solver/01.boundary-conditions/03.inflow.md

@@ -8,13 +8,14 @@
 
 | *Option* | *Description* | *Applicable* |
 |------------|----------------------------------|----------|
-| **Total temperature** | Stagnation temperature at the inlet | always |
-| **Inflow specification** | Method to specify the inflow | always |
-| **Total pressure** | Stagnation pressure at the inlet | **Inflow specification** is `Total pressure` |
-| **Mass flow rate (value)** | Mass flow through the inlet | **Inflow specification** is `Mass flow rate` |
-| **Ramp steps** | Number of steps to gradually apply mass flow rate | **Inflow specification** is `Mass flow rate` |
-| **Turbulence quantity** | Specification of turbulence parameters | always |
-| **Assigned surfaces** | Geometric boundaries to apply the inflow condition | always |
+| **Total temperature** | Stagnation temperature at the inlet | Total Pressure, Mass Flow Rate, Supersonic |
+| **Velocity direction** | Primary direction of the incoming flow | Total Pressure, Mass Flow Rate, Supersonic |
+| **Total pressure** | Stagnation pressure at the inlet | Total Pressure, Supersonic |
+| **Static pressure** | Static pressure at the inlet | Supersonic |
+| **Mass flow rate (value)** | Mass flow through the inlet | Mass Flow Rate |
+| **Ramp steps** | Number of steps to gradually apply mass flow rate | Mass Flow Rate |
+| **Turbulence quantity** | Specification of turbulence parameters | Total Pressure, Mass Flow Rate, Supersonic |
+| **Assigned surfaces** | Geometric boundaries to apply the inflow condition | Total Pressure, Mass Flow Rate, Supersonic |
 
 ---
 
@@ -24,52 +25,56 @@
 
 *The stagnation (total) temperature of the flow at the inlet boundary.*
 
-- **Default:** None (must be specified)
-- **Example:** `300 K`
->**Note:** This is the temperature the flow would have if brought to rest adiabatically.
+- **Required:** Yes
+- **Example (constant):** `300 K`
+- **Example (expression, Python API only):** `"1.0+0.2*pow(0.1*(1.0-y*y),2.0)"` (nondimensionalized by operating condition temperature)
 
-### **Inflow specification**
+### **Velocity direction**
 
-*Method used to specify the inflow conditions.*
+*The primary direction of the incoming flow at the inlet boundary.*
 
-- **Options:**
-  - `Total Pressure`
-  - `Mass Flow Rate`
-- **Default:** None (one must be selected)
->**Note:** Choose the method that best matches your known boundary conditions.
+- **Default:** If not specified, the boundary patch normal is used
+- **Example:** `(1, 0, 0)`
 
 ### **Total pressure**
 
-*The stagnation (total) pressure of the flow at the inlet boundary.*
+*The stagnation (total) pressure of the flow at the inlet boundary. This is the pressure the flow would have if brought to rest isentropically.*
 
-- **Required when `Total Pressure` is selected.**
-- **Example:** `101325 Pa`
->**Note:** This is the pressure the flow would have if brought to rest isentropically.
+- **Required:** Yes (when Inflow is `Total Pressure` or `Supersonic`)
+- **Example (constant):** `101325 Pa`
+- **Example (expression, Python API only):** `"pow(1.0+0.2*pow(0.1*(1.0-y*y),2.0),1.4/0.4)"` (nondimensionalized by operating condition pressure)
+
+>**Important:** For subsonic flows (Total Pressure specification), the full flow state is not specified at the inflow boundary. When total temperature, velocity direction, and total pressure are specified, the static pressure at the inflow is only determined after convergence of the solution. This occurs because in subsonic flow, one of the characteristics travels upstream, so information cannot be fully determined at the upstream boundary.
+
+### **Static pressure**
+
+*The static pressure for supersonic inflow conditions. This is the actual pressure of the flowing fluid at the inlet boundary.*
+
+- **Required:** Yes (when Inflow specification is `Supersonic`)
+- **Example:** `1.01e6 Pa`
+>**Notes:** 
+>- For supersonic flows, both total and static pressure are directly specified, fully determining the flow state at the inlet
+>- This is necessary because in supersonic flows, information cannot propagate upstream, so the complete flow state must be prescribed at the boundary
+>- It is useful to use the isentropic relations to specify the velocity when setting up supersonic inflow conditions
 
 ### **Mass flow rate (value)**
 
-*The mass flow rate through the inlet boundary.*
+*The mass flow rate through the inlet boundary. The solver adjusts the inlet velocity profile to achieve the specified mass flow rate.*
 
-- **Required when `Mass Flow Rate` is selected.**
+- **Required:** Yes (when Inflow specification is `Mass Flow Rate`)
 - **Example:** `10 kg/s`
->**Note:** The solver will adjust the inlet velocity to achieve the specified mass flow rate.
 
 ### **Ramp steps**
 
 *The number of pseudo time steps over which to gradually increase the mass flow rate to the specified value.*
 
 - **Default:** `0` (full mass flow rate applied immediately)
 - **Example:** `100`
->**Notes:** 
->- Only available when using Mass Flow Rate specification
->- Helps with simulation stability for high flow rates
->- The flow rate increases linearly from zero to the target value over the specified number of steps
 
 ### **Turbulence quantity**
 
 *Optional specification of turbulence parameters at the boundary.*
 
-- **Options:** Various parameter combinations
 - **Default:** Uses global defaults based on turbulence model
 - **Example:** `Turbulence Intensity = 0.05`, `Turbulent Length Scale = 0.01 m`
 >**Notes:** 
@@ -103,6 +108,11 @@ For recommendations on turbulence parameter values for various flow conditions,
   - You know the precise flow rate (e.g., from a pump or fan).
   - You are modeling HVAC, engine inlets, or other applications with known flow rates.
   - You need to match experimental flow conditions.
+
+- **Supersonic:** This specification is required when:
+  - The incoming flow is supersonic (Mach number > 1).
+  - You know both the total and static pressure at the inlet.
+  - You are modeling high-speed flows such as jet engines, rocket nozzles, or supersonic wind tunnels.
 
 ### **Inlet Placement**
 
@@ -124,8 +134,8 @@ For recommendations on turbulence parameter values for various flow conditions,
 <details>
 <summary><h3 style="display:inline-block"> ❓ Frequently Asked Questions</h3></summary>
 
-- **Should I use Total Pressure or Mass Flow Rate specification?**  
-  > Use Total Pressure when you know the driving pressure but not the exact flow rate. Use Mass Flow Rate when you need to ensure a specific flow rate regardless of the pressure required.
+- **Should I use Total Pressure, Mass Flow Rate, or Supersonic specification?**  
+  > Use Total Pressure when you know the driving pressure but not the exact flow rate (subsonic flows). Use Mass Flow Rate when you need to ensure a specific flow rate regardless of the pressure required. Use Supersonic when the incoming flow is supersonic (Mach > 1) and you know both total and static pressure.
 
 - **What happens if my inlet is too close to an obstacle?**  
   > Placing an inlet too close to obstacles can cause unrealistic flow patterns and convergence issues. Try to maintain at least 5 characteristic lengths of straight, uniform flow upstream of complex geometry.
@@ -178,7 +188,7 @@ mass_flow_inlet = fl.Inflow(
 # Example with turbulence specifications for k-ω SST model
 turbulent_inlet = fl.Inflow(
     name="turbulent_inlet",
-    entities=[volume_mesh["fluid/inflow"]],
+    entities=[volume_mesh["fluid/inlet"]],
     total_temperature=300 * fl.u.K,
     spec=fl.TotalPressure(
         value=200000 * fl.u.Pa
@@ -192,7 +202,7 @@ turbulent_inlet = fl.Inflow(
 # Example for Spalart-Allmaras model
 sa_inlet = fl.Inflow(
     name="sa_inlet",
-    entities=[volume_mesh["fluid/inflow"]],
+    entities=[volume_mesh["fluid/inlet"]],
     total_temperature=300 * fl.u.K,
     spec=fl.MassFlowRate(
         value=10 * fl.u.kg / fl.u.s
@@ -201,6 +211,28 @@ sa_inlet = fl.Inflow(
         modified_viscosity_ratio=5.0
     )
 )
+
+# Example of a supersonic inlet
+supersonic_inlet = fl.Inflow(
+    name="supersonic_inlet",
+    entities=[volume_mesh["fluid/inlet"]],
+    total_temperature=500 * fl.u.K,
+    spec=fl.Supersonic(
+        total_pressure=7.90e6 * fl.u.Pa,
+        static_pressure=1.01e6 * fl.u.Pa
+    ),
+    velocity_direction=(1.0, 0.0, 0.0)  # Flow in x-direction
+)
+
+# Example of expressions in Inflow setup
+inflow_var = fl.Inflow(
+    entities=[volumeMesh["fluid/inlet"]],
+    total_temperature="1.0+0.2*pow(0.1*(1.0-y*y),2.0)",
+    velocity_direction=(1.0, 0.0, 0.0),
+    spec=fl.TotalPressure(
+        value="pow(1.0+0.2*pow(0.1*(1.0-y*y),2.0),1.4/0.4)",
+    ),
+)
 ```
 
 </details>