Skip to content

Commit 2c4d57e

Browse files
ZwFinkritvikrao
ZwFink
and
ritvikrao
authored
miniweather (#295)
Co-authored-by: Ritvik Rao <rsrao2@illinois.edu>
1 parent e4c23a5 commit 2c4d57e

File tree

5 files changed

+1401
-0
lines changed

5 files changed

+1401
-0
lines changed

‎examples/miniapps/MiniWeather/README.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# MiniWeather - Distributed Weather Simulation Mini-App
2+
3+
MiniWeather is a high-performance atmospheric dynamics simulation mini-app that demonstrates distributed computing and GPU acceleration techniques using Charm4Py. This example showcases how to combine Charm4Py's distributed parallel computing capabilities with Numba CUDA for GPU acceleration to simulate atmospheric flows with various physical phenomena.
4+
5+
## Features
6+
7+
- **Charm4Py Distributed Computing**: Demonstrates scalable parallel execution across multiple processes/nodes
8+
- **GPU Acceleration**: Leverages Numba CUDA for high-performance computation on NVIDIA GPUs
9+
- **Multiple Physics Models**: Supports various atmospheric phenomena including:
10+
- Collision dynamics
11+
- Thermal convection
12+
- Mountain wave propagation
13+
- Turbulence modeling
14+
- Density current flows
15+
- Injection dynamics
16+
- **Domain Decomposition**: Automatic 2D domain decomposition for distributed memory parallelism
17+
- **Conservation Tracking**: Monitors mass and energy conservation throughout simulation
18+
- **Flexible Output**: Configurable data output at specified intervals
19+
- **Visualization Support**: Built-in tools for creating animated visualizations
20+
21+
## Requirements
22+
23+
### Dependencies
24+
- Python 3.7+
25+
- NumPy
26+
- Numba (with CUDA support)
27+
- Matplotlib (for visualization)
28+
- imageio (for GIF creation)
29+
30+
### Hardware Requirements
31+
- NVIDIA GPU with CUDA support (for GPU acceleration)
32+
- Multiple CPU cores recommended for distributed execution
33+
34+
## Installation
35+
36+
1. Install required Python packages:
37+
```bash
38+
pip install numpy numba matplotlib imageio
39+
```
40+
41+
2. Ensure CUDA is properly installed and configured for Numba:
42+
```bash
43+
python -c "from numba import cuda; print(cuda.gpus)"
44+
```
45+
46+
## Usage
47+
48+
### Basic Simulation
49+
50+
Run a basic thermal convection simulation:
51+
```bash
52+
python3 -m charmrun.start +p4 miniweather/miniweather.py --data_spec thermal --sim_time 10.0 --nx_glob 400 --nz_glob 200
53+
```
54+
55+
### Distributed Execution
56+
57+
Run with domain decomposition across multiple chares:
58+
```bash
59+
python3 -m charmrun.start +p8 miniweather/miniweather.py \
60+
--data_spec mountain_waves \
61+
--num_chares_x 2 \
62+
--num_chares_z 2 \
63+
--nx_glob 800 \
64+
--nz_glob 400 \
65+
--sim_time 20.0 \
66+
--output_freq 50 \
67+
--output_dir simulation_output
68+
```
69+
70+
### Command Line Options
71+
72+
| Option | Default | Description |
73+
|--------|---------|-------------|
74+
| `--nx_glob` | 200 | Number of global cells in x-direction |
75+
| `--nz_glob` | 100 | Number of global cells in z-direction |
76+
| `--sim_time` | 1.0 | Simulation time in seconds |
77+
| `--max_iters` | 10000 | Maximum number of iterations |
78+
| `--data_spec` | thermal | Physics model to simulate |
79+
| `--num_chares_x` | 1 | Number of chares in x-direction |
80+
| `--num_chares_z` | 1 | Number of chares in z-direction |
81+
| `--output_freq` | 0 | Output frequency (0 = no output) |
82+
| `--output_dir` | output_data_charm | Output directory |
83+
84+
### Physics Models
85+
86+
Available `--data_spec` options:
87+
- `collision`: Collision dynamics
88+
- `thermal`: Thermal convection (default)
89+
- `mountain_waves`: Mountain wave propagation
90+
- `turbulence`: Turbulence modeling
91+
- `density_current`: Density current flows
92+
- `injection`: Injection dynamics
93+
94+
## Output Format
95+
96+
When `--output_freq` > 0, the simulation outputs `.npz` files containing:
97+
- `state`: 4D array with simulation variables (density, momentum, temperature)
98+
- `etime`: Simulation time
99+
- `chare_nx`, `chare_nz`: Local domain sizes
100+
- `chare_i_beg`, `chare_k_beg`: Global starting indices
101+
102+
File naming convention: `data_iter_XXXXXX_chare_YY_ZZ.npz`
103+
104+
## Visualization
105+
106+
### Creating Animated GIFs
107+
108+
Use the visualization script to create animated GIFs from simulation output:
109+
110+
```bash
111+
python miniweather/create_visualization.py simulation_output --out density_evolution.gif --qoi 0
112+
```
113+
114+
### Visualization Options
115+
116+
| Option | Default | Description |
117+
|--------|---------|-------------|
118+
| `input_dir` | (required) | Directory containing .npz output files |
119+
| `--out` | simulation_qoi0.gif | Output GIF filename |
120+
| `--qoi` | 0 | Quantity of Interest index to visualize |
121+
122+
### Quantities of Interest (QoI)
123+
124+
The simulation tracks 4 primary variables:
125+
- **QoI 0**: Density perturbations
126+
- **QoI 1**: Horizontal wind velocity (u-component)
127+
- **QoI 2**: Vertical wind velocity (w-component)
128+
- **QoI 3**: Potential temperature perturbations
129+
130+
### Visualization Examples
131+
132+
Create visualizations for different variables:
133+
```bash
134+
# Density evolution
135+
python miniweather/create_visualization.py output_data_charm --out density.gif --qoi 0
136+
137+
# Horizontal wind patterns
138+
python miniweather/create_visualization.py output_data_charm --out u_wind.gif --qoi 1
139+
140+
# Vertical wind patterns
141+
python miniweather/create_visualization.py output_data_charm --out w_wind.gif --qoi 2
142+
143+
# Temperature perturbations
144+
python miniweather/create_visualization.py output_data_charm --out temperature.gif --qoi 3
145+
```
146+
147+
## Example Workflows
148+
149+
### Medium Size Simulation
150+
```bash
151+
# High-resolution thermal convection study
152+
python3 -m charmrun.start +p16 miniweather/miniweather.py \
153+
--data_spec thermal \
154+
--nx_glob 1600 \
155+
--nz_glob 800 \
156+
--num_chares_x 4 \
157+
--num_chares_z 4 \
158+
--sim_time 100.0 \
159+
--output_freq 100 \
160+
--output_dir thermal_highres
161+
162+
# Create visualization
163+
python miniweather/create_visualization.py thermal_highres --out thermal_simulation.gif --qoi 0
164+
```
165+
166+
### Mountain Wave Study
167+
```bash
168+
# Mountain wave propagation
169+
python3 -m charmrun.start +p8 miniweather/miniweather.py \
170+
--data_spec mountain_waves \
171+
--nx_glob 800 \
172+
--nz_glob 400 \
173+
--num_chares_x 2 \
174+
--num_chares_z 2 \
175+
--sim_time 50.0 \
176+
--output_freq 25
177+
178+
# Visualize vertical velocity (mountain waves)
179+
python miniweather/create_visualization.py output_data_charm --out mountain_waves.gif --qoi 2
180+
```

‎examples/miniapps/MiniWeather/constants.py‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
import numpy as np
2+
3+
pi = 3.14159265358979323846264338327; #Pi
4+
grav = 9.8; #Gravitational acceleration (m / s^2)
5+
cp = 1004.; #Specific heat of dry air at constant pressure
6+
cv = 717.; #Specific heat of dry air at constant volume
7+
rd = 287.; #Dry air constant for equation of state (P=rho*rd*T)
8+
p0 = 1.e5; #Standard pressure at the surface in Pascals
9+
C0 = 27.5629410929725921310572974482; #Constant to translate potential temperature into pressure (P=C0*(rho*theta)**gamma)
10+
gamm = 1.40027894002789400278940027894; #gamma=cp/Rd , have to call this gamm because "gamma" is taken (I hate C so much)
11+
#Define domain and stability-related constants
12+
xlen = 2.e4; #Length of the domain in the x-direction (meters)
13+
zlen = 1.e4; #Length of the domain in the z-direction (meters)
14+
hv_beta = 0.25; #How strong to diffuse the solution: hv_beta \in [0:1]
15+
cfl = 1.50; #"Courant, Friedrichs, Lewy" number (for numerical stability)
16+
max_speed = 450; #Assumed maximum wave speed during the simulation (speed of sound + speed of wind) (meter / sec)
17+
hs = 2; #"Halo" size: number of cells beyond the MPI tasks's domain needed for a full "stencil" of information for reconstruction
18+
sten_size = 4; #Size of the stencil used for interpolation
19+
20+
# Parameters for indexing and flags
21+
NUM_VARS = 4; #Number of fluid state variables
22+
ID_DENS = 0; #index for density ("rho")
23+
ID_UMOM = 1; #index for momentum in the x-direction ("rho * u")
24+
ID_WMOM = 2; #index for momentum in the z-direction ("rho * w")
25+
ID_RHOT = 3; #index for density * potential temperature ("rho * theta")
26+
DIR_X = 1; #Integer constant to express that this operation is in the x-direction
27+
DIR_Z = 2; #Integer constant to express that this operation is in the z-direction
28+
DATA_SPEC_COLLISION = 1;
29+
DATA_SPEC_THERMAL = 2;
30+
DATA_SPEC_MOUNTAIN = 3;
31+
DATA_SPEC_TURBULENCE = 4;
32+
DATA_SPEC_DENSITY_CURRENT = 5;
33+
DATA_SPEC_INJECTION = 6;
34+
35+
nqpoints = 3;
36+
qpoints = np.array([0.112701665379258311482073460022E0 , 0.500000000000000000000000000000E0 , 0.887298334620741688517926539980E0], dtype=np.float64)
37+
qweights = np.array([0.277777777777777777777777777779E0 , 0.444444444444444444444444444444E0 , 0.277777777777777777777777777779E0], dtype=np.float64)

0 commit comments

Comments
 (0)