Configuration

Configuration#

Windmapper depends heavily upon GDAL to handle the geospatial data. Any 1-band raster that GDAL can open is valid. Input rasters need to have a coordinate system.

Warning

There cannot be missing data in the raster

Note

Only the items in the Required section are needed for a valid configuration file.

Required#

Windmapper can be used in one of two modes:

  1. With a user-supplied DEM (default)

  2. With an automatically downloaded SRTM DEM based on user-provided bounding box.

User-supplied DEM#

use_existing_dem#
Default:

true

Use an existing DEM file. Requires dem_filename to be provided

dem_filename#
Type:

string

Absolute or relative path to the DEM to open. Any GDAL supported single-band raster is supported. Must have a coordinate system.

Warning

A user-supplied DEM must be in UTM coordinates.

# Flag to use existing DEM (DEM must be in UTM for WindNinja)
use_existing_dem = True

# name of the DEM file if use_existing_dem = True
dem_filename = '../data/srtm_snowcast.tif'
wn_exe#
Default:

string

Path to the WindNinja CLI executable WindNinja_cli. If WindMapper was installed with BUILD_WINDNINJA=TRUE this is not needed.

Downloaded DEM#

Set use_existing_dem to be False. Then

lat_min#

Southern latitude bound

lat_max#

Northern latitude bound

lon_min#

Western longitude bound

long_max#

Eastern longitude bound

# Example for a region in the Jura, France
lat_min = 46.5
lat_max = 46.7
lon_min = 5.80
lon_max = 6.15

Optional#

res_wind#
Default:

150 m

Spatial resolution of the WindNinja simulations

ncat#
Default:

4

Number of wind speed categories (every 360/ncat degrees)

fic_config_WN#

Path to WindNinja cli_massSolver.cfg file. By default, Windmapper produces this file on-demand. However, if extra customization is required, it can be specified by the user.

The contents are:

#
#   This is an example command line interface (cli) configuration file.
#
#   This particular file illustrates the necessary settings to
#   for the mass conserving version of Wond Ninja
#       See https://github.com/firelab/windninja for more details
#
#

num_threads              = 4    # May be changed depending on the machine used to run WN
initialization_method    = domainAverageInitialization
units_mesh_resolution    = m
input_speed              = 10.0
input_speed_units        = mps
input_wind_height        = 40.0
units_input_wind_height  = m
output_wind_height       = 40.0
units_output_wind_height = m
output_speed_units       = mps
vegetation               = grass
diurnal_winds            = false
write_goog_output        = false
write_shapefile_output   = false
write_ascii_output       = true
write_farsite_atm        = false
num_threads#
Default:

Number of threads for the underlying Windninja call. Defaults to 1 thread as parallelism via the MPI ranks is more scalable. However, if each Windninja run is large enough to have memory pressure, reducing the number of MPI ranks and increasing threads may be more optimal. num_threads * MPI_nworkers must not exceed the total number of logical CPUs available.

wind_average#
Default:

‘grid’

Averaging method to compute the transfer function in the downscaling method:

  • “mean_tile”: the wind speed is average over the whole domain for each WN simulation (as in Marsh et al, 2020)

  • “grid”: the wind speed is averaged over a squared area of size targ_res (as in Vionnet et al., 2020)

Over domains of O(1 km^2 +), ‘grid’ should be used.

targ_res#
Default:

1000 m

Used when wind_average=’grid’, the windspeed is averaged over a squared area of size targ_res.

user_output_dir#
Type:

string

Default:

./configuration-script-name

Output directory.

MPI#

By default Windmapper will use MPI to launch the WindNinja tasks.

MPI_nworkers#
Type:

int

Default:

Number of cores on machine (e.g., 4, 8, 10, etc)

Set this to limit the number of processors used.

If Windmapper is used on a cluster to process a large domain, the use of a job scheduler, such as SLURM, may be optimal. However, if each Windninja run is large enough to have memory pressure, reducing the number of MPI ranks and increasing threads may be more optimal. num_threads * MPI_nworkers must not exceed the total number of logical CPUs available.

MPI_exec_str#
Type:

string

Default:

None

Set this to a command to use to invoked the MPI job. For example MPI_exec_str=’./submit_job.sh job.sh’ where submit_job.sh invokes the queue submission, e.g., sbatch “$@” and job.sh contains srun –label –unbuffered python “$@”

The exec string used is f”””{MPI_exec_str} {MPI_runWM_path} pickled_param_args_RANK.pickle False””” where MPI_runWM_path holds the path to the helper script that is run with python.

If MPI_exec_str is provided MPI_nworkers must also be provided.

Contents