Skip to content

Commit b1002b7

Browse files
sbryngelsonclaude
sbryngelson
and
claude
committed
Add dimensional analysis documentation to equations reference
Add Section 1b to equations.md documenting how MFC handles dimensions: unit-agnostic flow solver, non-dimensional bubble dynamics, reference scales, non-dimensionalization formulas for all bub_pp parameters, the two different viscosity parameters (fluid_pp%Re vs bub_pp%mu_l), and a worked example. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent ef6998d commit b1002b7

1 file changed

Lines changed: 141 additions & 0 deletions

File tree

‎docs/documentation/equations.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,147 @@ The parameter `model_eqns` (1, 2, 3, or 4) selects the governing equation set.
2929

3030
---
3131

32+
## 1b. Units, Dimensions, and Non-Dimensionalization
33+
34+
### Dimensional Handling in the Flow Solver
35+
36+
The main flow solver (Navier-Stokes equations, Riemann solvers, viscous stress, body forces, surface tension, etc.) is **unit-agnostic**: whatever units the user provides for the initial and boundary conditions, the solver preserves them throughout the computation. If the user inputs SI units, the outputs are in SI units. If the user inputs CGS, the outputs are in CGS. No internal non-dimensionalization is performed by the flow solver.
37+
38+
This means that for simulations **without** sub-grid bubble models, the user can work in any consistent unit system without additional effort.
39+
40+
### Non-Dimensional Bubble Dynamics
41+
42+
The sub-grid bubble models (`bubbles_euler = .true.` or `bubbles_lagrange = .true.`) solve the bubble wall dynamics in **non-dimensional form**. The bubble wall pressure equation as implemented is:
43+
44+
\f[p_{bw} = \left(\text{Ca} + \frac{2}{\text{We}_b\,R_0}\right)\left(\frac{R_0}{R}\right)^{3\gamma} - \text{Ca} - \frac{4\,\text{Re}_{\text{inv}}\,\dot{R}}{R} - \frac{2}{R\,\text{We}_b}\f]
45+
46+
where the dimensionless groups are:
47+
48+
| Dimensionless group | Definition | Code variable | Computed from |
49+
|---|---|---|---|
50+
| \f$\text{Ca}\f$ (Cavitation number) | \f$p_{0,\text{ref}} - p_v\f$ | `Ca` | `bub_pp%p0ref - bub_pp%pv` |
51+
| \f$\text{Eu}\f$ (Euler number) | \f$p_{0,\text{ref}}\f$ | `Eu` | `bub_pp%p0ref` |
52+
| \f$\text{We}_b\f$ (bubble Weber number) | \f$1/\sigma\f$ | `Web` | `1 / bub_pp%ss` |
53+
| \f$\text{Re}_{\text{inv}}\f$ (inverse bubble Reynolds number) | \f$\mu_l\f$ | `Re_inv` | `bub_pp%mu_l` |
54+
55+
These groups are computed in `src/common/m_helper.fpp` (lines 143--194). Because the bubble equations use these dimensionless numbers directly, **all** `bub_pp%` parameters must be provided in non-dimensional form by the user. The code does not perform any internal non-dimensionalization of these inputs.
56+
57+
### Reference Scales
58+
59+
When using bubble models, the user must choose reference scales and non-dimensionalize **all** inputs (flow and bubble) consistently. The standard convention used in the MFC examples is:
60+
61+
| Reference quantity | Symbol | Typical choice |
62+
|---|---|---|
63+
| Length | \f$x_0\f$ | \f$R_{0,\text{ref}}\f$ (reference bubble radius) |
64+
| Pressure | \f$p_0\f$ | \f$p_{0,\text{ref}}\f$ (reference bubble pressure) |
65+
| Density | \f$\rho_0\f$ | \f$\rho_{0,\text{ref}}\f$ (reference liquid density) |
66+
| Velocity | \f$u_0\f$ | \f$\sqrt{p_0 / \rho_0}\f$ (derived) |
67+
| Time | \f$t_0\f$ | \f$x_0 / u_0\f$ (derived) |
68+
| Temperature | \f$T_0\f$ | \f$T_{0,\text{ref}}\f$ (reference temperature) |
69+
70+
### Non-Dimensionalization of Input Parameters
71+
72+
The following table lists every `bub_pp%` parameter and its required non-dimensionalization:
73+
74+
| Parameter | Physical meaning | Non-dimensional form |
75+
|---|---|---|
76+
| `bub_pp%R0ref` | Reference bubble radius | \f$R_{0,\text{ref}} / x_0\f$ |
77+
| `bub_pp%p0ref` | Reference bubble pressure | \f$p_{0,\text{ref}} / p_0\f$ |
78+
| `bub_pp%rho0ref` | Reference liquid density | \f$\rho_{0,\text{ref}} / \rho_0\f$ |
79+
| `bub_pp%T0ref` | Reference temperature | \f$T_{0,\text{ref}} / T_0\f$ (typically 1) |
80+
| `bub_pp%ss` | Surface tension \f$\sigma\f$ | \f$\sigma / (\rho_0\,x_0\,u_0^2)\f$ |
81+
| `bub_pp%pv` | Vapor pressure | \f$p_v / p_0\f$ |
82+
| `bub_pp%mu_l` | Liquid dynamic viscosity | \f$\mu_l / (\rho_0\,x_0\,u_0)\f$ |
83+
| `bub_pp%mu_v` | Vapor dynamic viscosity | \f$\mu_v / (\rho_0\,x_0\,u_0)\f$ |
84+
| `bub_pp%mu_g` | Gas dynamic viscosity | \f$\mu_g / (\rho_0\,x_0\,u_0)\f$ |
85+
| `bub_pp%k_v` | Vapor thermal conductivity | \f$k_v\,T_0 / (x_0\,\rho_0\,u_0^3)\f$ |
86+
| `bub_pp%k_g` | Gas thermal conductivity | \f$k_g\,T_0 / (x_0\,\rho_0\,u_0^3)\f$ |
87+
| `bub_pp%cp_v` | Vapor specific heat | \f$c_{p,v}\,T_0 / u_0^2\f$ |
88+
| `bub_pp%cp_g` | Gas specific heat | \f$c_{p,g}\,T_0 / u_0^2\f$ |
89+
| `bub_pp%R_v` | Vapor gas constant | \f$R_v\,T_0 / u_0^2\f$ |
90+
| `bub_pp%R_g` | Gas gas constant | \f$R_g\,T_0 / u_0^2\f$ |
91+
| `bub_pp%gam_v` | Vapor heat capacity ratio | Already dimensionless (no scaling) |
92+
| `bub_pp%gam_g` | Gas heat capacity ratio | Already dimensionless (no scaling) |
93+
| `bub_pp%M_v` | Vapor molar mass | Already dimensionless (no scaling) |
94+
| `bub_pp%M_g` | Gas molar mass | Already dimensionless (no scaling) |
95+
96+
When the reference scales match the bubble reference values (e.g., \f$x_0 = R_{0,\text{ref}}\f$, \f$p_0 = p_{0,\text{ref}}\f$, \f$\rho_0 = \rho_{0,\text{ref}}\f$), the reference parameters simplify to unity: `bub_pp%R0ref = 1`, `bub_pp%p0ref = 1`, `bub_pp%rho0ref = 1`.
97+
98+
### Flow Parameters with Bubbles
99+
100+
When bubbles are enabled, the flow-level parameters must also be non-dimensionalized with the same reference scales:
101+
102+
| Parameter | Non-dimensional form |
103+
|---|---|
104+
| `x_domain%beg`, `x_domain%end` | Domain bounds divided by \f$x_0\f$ |
105+
| `patch_icpp(i)%pres` | Pressure divided by \f$p_0\f$ |
106+
| `patch_icpp(i)%alpha_rho(j)` | Partial density divided by \f$\rho_0\f$ |
107+
| `patch_icpp(i)%vel(j)` | Velocity divided by \f$u_0\f$ |
108+
| `fluid_pp(i)%gamma` | \f$1/(\gamma_i - 1)\f$ (dimensionless, same as without bubbles) |
109+
| `fluid_pp(i)%pi_inf` | \f$\gamma_i\,\pi_{\infty,i} / [(\gamma_i - 1)\,p_0]\f$ (scaled by reference pressure) |
110+
| `fluid_pp(i)%Re(1)` | \f$\rho_0\,x_0\,u_0 / \mu_i\f$ (Reynolds number, inverse viscosity) |
111+
| `dt` | Time step divided by \f$t_0\f$ |
112+
113+
### Two Different Viscosity Parameters
114+
115+
MFC has two conceptually distinct viscosity-related parameters that serve different physical roles:
116+
117+
1. **`fluid_pp(i)%Re(1)`** — Used for the **macroscopic flow viscous stress tensor** (Navier-Stokes equations). This is \f$1/\mu\f$ in dimensional simulations, or \f$\rho_0 x_0 u_0 / \mu\f$ (a Reynolds number) when non-dimensionalized. It appears as a **divisor** in the viscous stress computation:
118+
\f[\tau_{ij} \propto \frac{\nabla u}{\text{Re}}\f]
119+
Stored in the `physical_parameters` derived type (`src/common/m_derived_types.fpp`).
120+
121+
2. **`bub_pp%mu_l`** — Used for **microscale bubble wall viscous damping** (Rayleigh-Plesset / Keller-Miksis equations). This is the non-dimensional liquid viscosity \f$\mu_l / (\rho_0 x_0 u_0)\f$. It appears as a **multiplier** in the bubble wall pressure:
122+
\f[p_{bw} \ni -\frac{4\,\text{Re}_{\text{inv}}\,\dot{R}}{R}\f]
123+
Stored in the `subgrid_bubble_physical_parameters` derived type (`src/common/m_derived_types.fpp`).
124+
125+
These two parameters represent viscous effects at fundamentally different scales — bulk flow dissipation vs. single-bubble-wall damping — and are stored in separate derived types with separate code paths. They are **not** interchangeable: `fluid_pp%Re(1)` is an inverse viscosity while `bub_pp%mu_l` is a viscosity (non-dimensionalized).
126+
127+
### Example: Non-Dimensionalizing a Bubble Case
128+
129+
A typical bubble case setup in `case.py` follows this pattern:
130+
131+
```python
132+
import math
133+
134+
# Physical properties (SI units)
135+
rho_l = 1.0e03 # liquid density [kg/m³]
136+
mu_l = 1.002e-03 # liquid viscosity [kg/(m·s)]
137+
ss = 0.07275 # surface tension [kg/s²]
138+
pv = 2.3388e03 # vapor pressure [Pa]
139+
gam_l = 7.15 # liquid stiffened gas gamma
140+
pi_inf = 306.0e06 # liquid stiffened gas pi_inf [Pa]
141+
142+
# Bubble reference values (SI)
143+
R0ref = 10.0e-06 # reference bubble radius [m]
144+
p0ref = 112.9e03 # reference bubble pressure [Pa]
145+
rho0ref = rho_l # reference density [kg/m³]
146+
147+
# Derived reference scales
148+
x0 = R0ref
149+
p0 = p0ref
150+
rho0 = rho0ref
151+
u0 = math.sqrt(p0 / rho0)
152+
t0 = x0 / u0
153+
154+
# Non-dimensional inputs
155+
params = {
156+
"bub_pp%R0ref": R0ref / x0, # = 1.0
157+
"bub_pp%p0ref": p0ref / p0, # = 1.0
158+
"bub_pp%rho0ref": rho0ref / rho0, # = 1.0
159+
"bub_pp%ss": ss / (rho0 * x0 * u0**2), # surface tension
160+
"bub_pp%pv": pv / p0, # vapor pressure
161+
"bub_pp%mu_l": mu_l / (rho0 * x0 * u0), # liquid viscosity
162+
163+
"fluid_pp(1)%gamma": 1.0 / (gam_l - 1.0),
164+
"fluid_pp(1)%pi_inf": gam_l * (pi_inf / p0) / (gam_l - 1.0),
165+
"fluid_pp(1)%Re(1)": rho0 * x0 * u0 / mu_l, # flow Re (inverse!)
166+
}
167+
```
168+
169+
Note the inverse relationship: `fluid_pp%Re(1) = 1 / bub_pp%mu_l` when both use the same reference scales and the same physical viscosity. This is expected — they encode the same physical viscosity but in reciprocal forms for their respective equations.
170+
171+
---
172+
32173
## 2. Governing PDEs
33174

34175
### 2.1 Five-Equation Model (`model_eqns = 2`)

0 commit comments

Comments
 (0)