Usage

Running the Solver

Pass an input file to the wind_solver executable:

./build/wind_solver inputs.i

Or supply parameters directly on the command line:

./build/wind_solver terrain_file=terrain.csv U_ref=8.0 z0=0.05

Command-line key=value pairs override values in the input file.

Input File Format

The input file uses AMReX ParmParse syntax — one key = value pair per line. Lines beginning with # are comments.

Example inputs.i:

# Mass-consistent wind solver input file

terrain_file  = terrain.csv   # X Y Z point cloud

U_ref         = 8.0           # reference x-wind [m/s]
V_ref         = 0.0           # reference y-wind [m/s]
z_ref         = 10.0          # reference height above local terrain [m]
z0            = 0.05          # aerodynamic roughness length [m]

dx            = 30.0          # grid spacing x [m]
dy            = 30.0          # grid spacing y [m]
dz            = 10.0          # grid spacing z [m]
domain_height = 300.0         # vertical extent above max terrain [m]

alpha_h       = 1.0           # horizontal anisotropy coefficient
alpha_v       = 1.0           # vertical anisotropy coefficient

mlmg_verbose  = 1             # MLMG verbosity (0=silent, 4=max)
tol_rel       = 1.e-8         # relative convergence tolerance
max_grid_size = 32            # max AMReX box size per dimension

plot_file     = plt_wind      # output plotfile prefix

extract_agl   = 15.0          # extract CSV at 15 m AGL
extract_file  = wind_extract.csv

Parameter Reference

Parameter	Default	Description
`terrain_file`	`terrain.csv`	Path to terrain point-cloud file (X Y Z, whitespace or comma separated; `#` comments supported).
`U_ref`	`10.0`	Reference wind x-component [m/s] at height `z_ref`.
`V_ref`	`0.0`	Reference wind y-component [m/s] at height `z_ref`.
`z_ref`	`10.0`	Reference height above the local terrain surface [m].
`z0`	`0.1`	Aerodynamic roughness length [m].
`dx`	`30.0`	Horizontal grid spacing in x [m].
`dy`	`30.0`	Horizontal grid spacing in y [m].
`dz`	`30.0`	Vertical grid spacing [m]. Reduce for finer near-surface resolution.
`domain_height`	`300.0`	Vertical domain extent above the maximum terrain elevation [m].
`alpha_h`	`1.0`	Horizontal Lagrange anisotropy coefficient α_h.
`alpha_v`	`1.0`	Vertical Lagrange anisotropy coefficient α_v.
`mlmg_verbose`	`1`	MLMG solver verbosity (0 = silent, 4 = maximum).
`tol_rel`	`1.0e-8`	MLMG relative convergence tolerance.
`max_grid_size`	`32`	Maximum AMReX box size per spatial dimension.
`plot_file`	`plt_wind`	Output plotfile prefix.
`extract_agl`	`-1.0`	Sample the corrected wind at this AGL height [m] and write a CSV slice. Negative value disables extraction.
`extract_k`	`-1`	Alternative: sample at explicit k-index (0 = lowest level). `extract_agl` takes priority when both are set.
`extract_file`	`wind_extract.csv`	Output filename for the terrain-aligned CSV slice.

Terrain File Format

The terrain file must contain one data point per line with columns X Y Z (in metres, UTM or local coordinates). Both whitespace and comma-separated formats are accepted. Lines beginning with # are comments:

# X [m]  Y [m]  Z [m]
0.0      0.0    5.2
30.0     0.0    8.1
60.0     0.0   12.7
...

The horizontal domain extents (x_lo, x_hi, y_lo, y_hi) are derived automatically from the min/max of the terrain data. The grid dimensions are:

nx = round((x_hi - x_lo) / dx)
ny = round((y_hi - y_lo) / dy)
nz = round((z_hi - z_lo) / dz)

where z_lo = min terrain elevation and z_hi = max terrain elevation + domain_height.

Output Files

AMReX plotfile (plt_wind)

The output plotfile contains the following cell-centred components:

Variable	Description
`u`	Corrected x-wind [m/s]
`v`	Corrected y-wind [m/s]
`w`	Corrected z-wind [m/s]
`vel_magnitude`	Wind speed \|u\| [m/s]
`u0`	Initial log-law x-wind [m/s]
`v0`	Initial log-law y-wind [m/s]
`w0`	Initial log-law z-wind [m/s]
`lambda`	Lagrange multiplier λ [m²/s]
`div_before`	∇·u₀ before correction [s⁻¹]
`div_after`	∇·u after correction [s⁻¹]
`terrain_z`	Terrain elevation at the column centre [m]

Plotfiles can be visualised with VisIt or ParaView (AMReX reader plugin).

Terrain-aligned CSV slice (wind_extract.csv)

When extract_agl or extract_k is set, a 2-D CSV slice is written with columns:

x, y, z_terrain, z_physical, z_agl, u, v, w, speed

Typical Workflow

Prepare terrain — create a CSV from a DEM or generate synthetically:

# Gaussian hill example (already provided in regtest/)
cat regtest/gaussian_hill/terrain.csv

Write an inputs file (or reuse a regtest one):

terrain_file = terrain.csv
U_ref = 8.0
z0    = 0.05
dx    = 30.0
dy    = 30.0
dz    = 10.0
domain_height = 300.0
extract_agl   = 10.0
extract_file  = wind_10m.csv
plot_file     = plt_wind

Run the solver:
```
./build/wind_solver inputs.i
```
Check convergence — MLMG prints iteration residuals when mlmg_verbose ≥ 1.

Visualise — open the plotfile in VisIt or ParaView, or load the CSV extract in Python:

import pandas as pd
import matplotlib.pyplot as plt
df = pd.read_csv("wind_10m.csv")
plt.quiver(df.x, df.y, df.u, df.v)
plt.show()