Skip to content

Commit 14fe775

Browse files
sbryngelsonsbryngelson
committed
constraints
1 parent 9d283e5 commit 14fe775

File tree

5 files changed

+915
-1
lines changed

5 files changed

+915
-1
lines changed

‎docs/Doxyfile.in‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1163,7 +1163,8 @@ HTML_STYLESHEET =
11631163
# list). For an example see the documentation.
11641164
# This tag requires that the tag GENERATE_HTML is set to YES.
11651165

1166-
HTML_EXTRA_STYLESHEET = @DOXYGEN_HTML_EXTRA_STYLESHEET@
1166+
HTML_EXTRA_STYLESHEET = @DOXYGEN_HTML_EXTRA_STYLESHEET@ \
1167+
@CMAKE_SOURCE_DIR@/docs/custom-dark-fixes.css
11671168

11681169
# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
11691170
# other source files which should be copied to the HTML output directory. Note

‎docs/documentation/case.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,15 @@ For example, to run the `scaling` case in "weak-scaling" mode:
6868

6969
## Parameters
7070

71+
## Feature Compatibility
72+
73+
Before diving into parameter details, check the **[Feature Compatibility Guide](case_constraints.md)** to understand:
74+
- Which features work together (MHD, bubbles, phase change, etc.)
75+
- Common configuration patterns with copy-paste examples
76+
- Requirements for each model equation and Riemann solver
77+
78+
💡 **Tip:** If you get a validation error, the compatibility guide explains what each parameter requires.
79+
7180
There are multiple sets of parameters that must be specified in the python input file:
7281
1. [Runtime Parameters](#1-runtime)
7382
2. [Computational Domain Parameters](#2-computational-domain)

‎docs/documentation/case_constraints.md‎

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
# MFC Feature Compatibility Guide
2+
3+
> **Quick reference** for understanding which MFC features work together and configuration requirements.
4+
5+
> Auto-generated from validation rules in `case_validator.py`.
6+
7+
## 🚀 Common Configuration Patterns
8+
9+
Start with these proven combinations:
10+
11+
12+
<details open>
13+
<summary><b>💧 Multiphase Flow (Bubbles)</b></summary>
14+
15+
```python
16+
'model_eqns': 2, # 5-equation model
17+
'num_fluids': 2, # Two-phase
18+
'bubbles_euler': 'T', # Ensemble-averaged bubbles
19+
'riemann_solver': 2, # HLLC
20+
'avg_state': 2, # Arithmetic average
21+
```
22+
</details>
23+
24+
<details>
25+
<summary><b>⚡ Magnetohydrodynamics (MHD)</b></summary>
26+
27+
```python
28+
'model_eqns': 2, # 5-equation model
29+
'num_fluids': 1, # Single component
30+
'mhd': 'T', # Enable MHD
31+
'riemann_solver': 1, # HLL (or 4 for HLLD)
32+
```
33+
</details>
34+
35+
<details>
36+
<summary><b>🌡️ Phase Change</b></summary>
37+
38+
```python
39+
'model_eqns': 3, # 6-equation model
40+
'num_fluids': 2, # Two-phase
41+
'relax': 'T', # Phase change
42+
'riemann_solver': 2, # HLLC
43+
```
44+
</details>
45+
46+
<details>
47+
<summary><b>💎 Elastic Materials</b></summary>
48+
49+
```python
50+
'model_eqns': 2, # 5-equation model
51+
'hypoelasticity': 'T', # Elastic solids
52+
'riemann_solver': 1, # HLL
53+
```
54+
</details>
55+
56+
## 📊 Feature Compatibility
57+
58+
What works together:
59+
60+
61+
### Physics Models
62+
63+
| Feature | Requirements | Notes |
64+
|---------|-------------|-------|
65+
| Magnetohydrodynamics (MHD) | — | ✓ General use |
66+
| Surface Tension Model | Specific model | ✓ General use |
67+
| Hypoelasticity | — | ✓ General use |
68+
| Hyperelasticity | — | ✓ General use |
69+
| Phase Change (Relaxation) | — | ✓ General use |
70+
| Viscosity | — | ✓ General use |
71+
| Acoustic Sources | — | ✓ General use |
72+
73+
74+
### Bubble Models
75+
76+
| Feature | Requirements | Notes |
77+
|---------|-------------|-------|
78+
| Euler–Euler Bubble Model | — | ✓ General use |
79+
| Euler–Lagrange Bubble Model | — | ✓ General use |
80+
| Quadrature-Based Moment Method (QBMM) | — | ✓ General use |
81+
| Polydisperse Bubble Dynamics | — | ✓ General use |
82+
| adv_n | — | ✓ General use |
83+
84+
85+
### Numerics
86+
87+
| Feature | Requirements | Notes |
88+
|---------|-------------|-------|
89+
| Riemann Solver | Specific model | ✓ General use |
90+
| WENO Order | — | ✓ General use |
91+
| MUSCL Order | — | ✓ General use |
92+
93+
94+
### Geometry
95+
96+
| Feature | Requirements | Notes |
97+
|---------|-------------|-------|
98+
| Immersed Boundaries | — | ✓ General use |
99+
| Cylindrical Coordinates | — | ✓ General use |
100+
101+
## 🔢 Model Equations
102+
103+
Choose your governing equations:
104+
105+
106+
<details>
107+
<summary><b>Model 1: π-γ (Compressible Euler)</b></summary>
108+
109+
- **Use for:** Single-fluid compressible flow
110+
- **Value:** `model_eqns = 1`
111+
- **Note:** Cannot use `num_fluids`, bubbles, or certain WENO variants
112+
</details>
113+
114+
<details>
115+
<summary><b>Model 2: 5-Equation (Most versatile)</b></summary>
116+
117+
- **Use for:** Multiphase, bubbles, elastic materials, MHD
118+
- **Value:** `model_eqns = 2`
119+
- **Requirements:** Set `num_fluids`
120+
- **Compatible with:** Most physics models
121+
</details>
122+
123+
<details>
124+
<summary><b>Model 3: 6-Equation (Phase change)</b></summary>
125+
126+
- **Use for:** Phase change, cavitation
127+
- **Value:** `model_eqns = 3`
128+
- **Requirements:** `riemann_solver = 2` (HLLC), `avg_state = 2`, `wave_speeds = 1`
129+
- **Note:** Not compatible with bubbles or 3D cylindrical
130+
</details>
131+
132+
<details>
133+
<summary><b>Model 4: 4-Equation (Single component)</b></summary>
134+
135+
- **Use for:** Single-component flows with bubbles
136+
- **Value:** `model_eqns = 4`
137+
- **Requirements:** `num_fluids = 1`, set `rhoref` and `pref`
138+
</details>
139+
140+
## ⚙️ Riemann Solvers
141+
142+
| Solver | `riemann_solver` | Best For | Requirements |
143+
|--------|-----------------|----------|-------------|
144+
| **HLL** | `1` | MHD, elastic materials | — |
145+
| **HLLC** | `2` | Bubbles, phase change, multiphase | `avg_state=2` for bubbles |
146+
| **Exact** | `3` | High accuracy (expensive) | — |
147+
| **HLLD** | `4` | MHD (advanced) | MHD only, no relativity |
148+
| **Lax-Friedrichs** | `5` | Robust fallback | Not with cylindrical+viscous |
149+
150+
## 💧 Bubble Models
151+
152+
153+
<details>
154+
<summary><b>Euler-Euler (`bubbles_euler`)</b></summary>
155+
156+
**Requirements:**
157+
- `model_eqns = 2` or `4`
158+
- `riemann_solver = 2` (HLLC)
159+
- `avg_state = 2`
160+
- Set `nb` (number of bins) ≥ 1
161+
162+
**Extensions:**
163+
- `polydisperse = T`: Multiple bubble sizes (requires odd `nb > 1`)
164+
- `qbmm = T`: Quadrature method (requires `nnode = 4`)
165+
- `adv_n = T`: Number density advection (requires `num_fluids = 1`)
166+
</details>
167+
168+
<details>
169+
<summary><b>Euler-Lagrange (`bubbles_lagrange`)</b></summary>
170+
171+
**Requirements:**
172+
- `n > 0` (2D or 3D only)
173+
- `file_per_process = F`
174+
- Not compatible with `model_eqns = 3`
175+
176+
**Note:** Tracks individual bubbles
177+
</details>
178+
179+
## 📖 Quick Parameter Reference
180+
181+
Key parameters and their constraints:
182+
183+
184+
<details>
185+
<summary><b>MHD</b> (`mhd`)</summary>
186+
187+
**Requirements:**
188+
- relativity requires mhd to be enabled
189+
- Powell's method requires mhd to be enabled
190+
191+
**Incompatibilities:**
192+
- Bx0 must not be set if MHD is not enabled
193+
- Bx0 must not be set in 2D/3D MHD simulations
194+
195+
</details>
196+
197+
198+
<details>
199+
<summary><b>Surface Tension</b> (`surface_tension`)</summary>
200+
201+
**Requirements:**
202+
- sigma must be set if surface_tension is enabled
203+
- The surface tension model requires model_eqns = 2 or model_eqns = 3
204+
- The surface tension model requires num_fluids = 2
205+
206+
**Valid values:**
207+
- sigma must be greater than or equal to zero
208+
209+
</details>
210+
211+
212+
<details>
213+
<summary><b>Number of Fluids</b> (`num_fluids`)</summary>
214+
215+
**Requirements:**
216+
- 5-equation model (model_eqns = 2) requires num_fluids to be set
217+
- 6-equation model (model_eqns = 3) requires num_fluids to be set
218+
- 4-equation model (model_eqns = 4) requires num_fluids to be set
219+
220+
**Incompatibilities:**
221+
- num_fluids is not supported for model_eqns = 1
222+
- num_fluids = 1 does not support mpp_lim
223+
224+
**Valid values:**
225+
- num_fluids must be positive
226+
- perturb_flow_fluid must be between 0 and num_fluids
227+
228+
</details>
229+
230+
231+
<details>
232+
<summary><b>Cylindrical Coordinates</b> (`cyl_coord`)</summary>
233+
234+
**Incompatibilities:**
235+
- 6-equation model (model_eqns = 3) does not support cylindrical coordinates (cyl_coord = T and p != 0)
236+
- Bubble models untested in cylindrical coordinates
237+
- Acoustic source is not supported in 3D cylindrical simulations
238+
239+
**Valid values:**
240+
- p must be odd for cylindrical coordinates
241+
242+
</details>
243+
244+
245+
<details>
246+
<summary><b>Immersed Boundaries</b> (`ib`)</summary>
247+
248+
**Requirements:**
249+
- Immersed Boundaries do not work in 1D (requires n > 0)
250+
251+
**Incompatibilities:**
252+
- output_partial_domain is incompatible with certain output flags
253+
254+
**Valid values:**
255+
- num_ibs must be between 1 and num_patches_max (10)
256+
257+
</details>
258+
259+
260+
---
261+
262+
💡 **Tip:** If you encounter a validation error, check the relevant section above or
263+
review [`case_validator.py`](../../toolchain/mfc/case_validator.py) for complete validation logic.
264+

‎docs/gen_constraints.sh‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
#!/bin/bash
2+
# Generate case constraints documentation from case_validator.py
3+
4+
set -e
5+
6+
REPO_ROOT="$1"
7+
8+
if [ -z "$REPO_ROOT" ]; then
9+
echo "Usage: $0 <repo_root>"
10+
exit 1
11+
fi
12+
13+
echo "Generating case constraints documentation..."
14+
python3 "$REPO_ROOT/toolchain/mfc/gen_case_constraints_docs.py" > "$REPO_ROOT/docs/documentation/case_constraints.md"
15+
echo "✓ Generated docs/documentation/case_constraints.md"
16+
17+

0 commit comments

Comments
 (0)