nrel / ssrs

A stochastic agent-based model for predicting raptor movements during updraft-subsidized directional flights

Stochastic Soaring Raptor Simulator (SSRS)

The goal of SSRS is to predict movements of soaring raptors (such as Golden Eagles) for a given wind conditions with the aim of determining potential negative conflict between soaring raptors and wind turbines. SSRS uses a stochastic agent-based model for predicting raptor movements through an orographic updraft field estimated using the spatially varying wind conditions and ground features (altitude, slope, aspect). SSRS can be applied to any rectangular region within the US without the need for any eagle-centric or atmosphere-related data collection efforts, using only the publicly available data sources. SSRS implements and extends the capability of the fluid-flow model from 'Brandes, D., & Ombalski, D. (2004). Modelling raptor migration pathways using a fluid-flow analogy. The Journal of Raptor Research, 38(3), 195-207.' More details can be found in the publication:

Rimple Sandhu, Charles Tripp, Eliot Quon, Regis Thedin, Michael Lawson, David Brandes, Christopher J. Farmer, Tricia A. Miller, Caroline Draxl, Paula Doubrawa, Lindy Williams, Adam E. Duerr, Melissa A. Braham, Todd Katzner, Stochastic agent-based model for predicting turbine-scale raptor movements during updraft-subsidized directional flights, Ecological Modelling, Volume 466, 109876, 2022.

SSRS uses the following publically available data sources:

• USGS's 3D Elevation Program (3DEP) dataset for terrain altitude, slope and aspect at a spatial resolution of 10 meters within the US.
• USGS's United States Wind Turbine Database (USWTDB) for up-to-date turbine locations within the US.
• NREL's Wind ToolKit (WTK) dataset for atmospheric conditions such as wind speed and direction at 1-hour temporal resolution and 2 km spatial resolution within the US.

SSRS operates under three modes:

• Uniform: Uses uniform wind speed and direction across the target region.
• Snapshot: Uses wind conditions for a specific time imported from WTK dataset.
• Seasonal: Uses wind conditions randomly sampled from a range of dates or months or time of day from the WTK dataset.

Installation

Clone the GitHub repository on local machine, cd into the SSRS directory and using conda virtual environments from Anaconda, do:

conda env create -f environment.yml
conda activate ssrs_env
pip install .

For editable install (for development purpose), do

conda env create -f environment.yml
conda activate ssrs_env
pip install -e .

For running conda environment ssrs_env in Jupyter Notebook (Comes with Anaconda),

conda install ipykernel
ipython kernel install --user --name=ssrs_env

Without Anaconda (requires python>=3.8 and pip>21.3):

pip install git+https://github.com/NREL/SSRS.git#egg=ssrs

For SSRS to access NREL's WTK dataset in the snapshot mode, need to get an API key from https://developer.nrel.gov/signup/ and save it in .hscfg file located in the working directory. Both examples/ and notebooks/ directories contain a sample .hscfg_need_api_key file. Make sure to rename this file as .hscfg after inserting your API key in this file.

Usage

The Jupyter notebooks in notebooks/ and python scripts in examples/ show the usage of SSRS for a given region. For instance, ssrs simulation in uniform mode for a 60 km by 50 km region in Wyoming and simulating 1000 eagles travelling north can be implemented using the following code:

config_wy_uniform = Config(
    run_name='run_wy',
    southwest_lonlat=(-106.21, 42.78),
    region_width_km=(60., 50.),
    resolution=100.,
    sim_mode='uniform',
    uniform_winddirn=270.,
    uniform_windspeed=10.,
    track_direction=0.,
    track_count = 1000,
    track_start_region=(5, 55, 1, 2)
)
sim = Simulator(config_wy_uniform)
sim.simulate_tracks()
sim.plot_terrain_elevation(show=True)
sim.plot_updrafts(show=True)
sim.plot_simulated_tracks(show=True)
sim.plot_presence_map(show=True)

This will produce the following figures:

Ground elevation and turbine locations:

Orographic updrafts:

1000 simulated tracks travelling towards north:

Relative eagle presence density

Configuration

SSRS settings can be changed through a set of parameters defined using ssrs.Config attribute. The default setting can be viewed through following code:

from ssrs import Config
print(Config())

Here is a description of the parameters available to the users to vary:

run_name: str = 'default'  # name of this run, determines directory names
out_dir: str = os.path.join(os.path.abspath(os.path.curdir), 'output')
max_cores: int = 8  # maximum number of cores to use
sim_seed: int = -1  # random number seed
sim_mode: str = 'uniform'  # snapshot, seasonal, uniform
print_verbose: bool = False # if want to print verbose

Parameters for setting up the region:

southwest_lonlat: Tuple[float, float] = (-106.21, 42.78)
projected_crs: str = 'ESRI:102008'  # ESRI, EPSG, PROJ4 or WKT string
region_width_km: Tuple[float, float] = (60., 50.)
resolution: int = 100.  # desired terrain resolution (meters)

Parameters for setting up the uniform mode:

uniform_winddirn: float = 270.  # northerly = 0., easterly = 90, westerly=270
uniform_windspeed: float = 10.  # uniform wind speed in m/s

Parameters for setting up the snapshot mode:

snapshot_datetime: Tuple[int, int, int, int] = (2010, 6, 17, 13)

Parameters for setting up the seasonal mode:

seasonal_start: Tuple[int, int] = (3, 20)  # start of season (month, day)
seasonal_end: Tuple[int, int] = (5, 15)  # end of season (month, day)
seasonal_timeofday: str = 'daytime'  # morning, afternoon, evening, daytime
seasonal_count: int = 8  # number of seasonal updraft computations

Parameters for importing data from NREL's WTK dataset:

wtk_source: str = 'AWS'  # 'EAGLE', 'AWS', 'EAGLE_LED'
wtk_orographic_height: int = 100  # WTK wind conditions at this height
wtk_thermal_height: int = 100  # WTK pressure, temperature, at this height
wtk_interp_type: str = 'linear'  # 'nearest' 'linear' 'cubic'

Parameters for simulating tracks:

track_direction: str = 0.  # movement direction measured clockwise from north
track_count: str = 1000  # number of simulated eagle tracks
track_start_region: Tuple[float, float, float, float] = (5, 55, 1, 2)  # xmin, xmax, ymin, ymax [km]
track_start_type: str = 'random'  # uniform, random
track_stochastic_nu: float = 1.  # scaling of move probs, 0 = random walk
track_dirn_restrict: int = 3  # restrict within 45 deg of this previous moves

Parameters for plotting:

fig_height: float = 6. # height of the figure window
fig_dpi: int = 200  # increase this to get finer plots
turbine_minimum_hubheight: float = 50.  # for plotting turbine locations
turbine_mrkr_styles = ('1k', '2k', '3k', '4k',
                       '+k', 'xk', '*k', '.k', 'ok')
turbine_mrkr_size: float = 3. # marker size for plotting turbines

Developers

• Rimple Sandhu, National Renewable Energy Laboratory [email protected]
• Charles Tripp, National Renewable Energy Laboratory, [email protected]
• Eliot Quon, National Renewable Energy Laboratory
• Regis Thedin, National Renewable Energy Laboratory
• Lindy Williams, National Renewable Energy Laboratory
• Paula Doubrawa, National Renewable Energy Laboratory
• Caroline Draxl, National Renewable Energy Laboratory
• Mike Lawson, National Renewable Energy Laboratory

Citation

Sandhu, Rimple, Tripp, Charles, Quon, Eliot, Thedin, Regis, Williams, Lindy, Doubrawa, Paula, Draxl, Caroline, and Lawson, Mike. SSRS (Stochastic Soaring Raptor Simulator). Computer Software. https://github.com/NREL/SSRS. USDOE Office of Energy Efficiency and Renewable Energy (EERE), Renewable Power Office. Wind Energy Technologies Office. 18 Oct. 2021. Web. doi:10.11578/dc.20210903.2.

ssrs's Issues

Rectify differences between master/dev/alt_study

Simulator.plot_updrafts() throws an error

FileNotFoundError: [Errno 2] No such file or directory: '.../output/alt_test/data/uniform/s8d225th2_thermal.npy'

when simulating with fluid-flow model, without thermals.

Some refactoring suggestions

I have some suggestions that I think it will improve code maintenance and debugging. None of this is exactly needed at this point, but if time becomes available, it would be nice to have.

1. Exception handling. When the code checks if a file already exists in order to load it (instead of downloading or computing it again), it is done in a try/except way. The exceptions are also caught generically, on a catch-all umbrella (e.g. except Exception as _).
   

   SSRS/ssrs/simulator.py

   Lines 161 to 165 in 1cda662

   	try:
   	slope = self.get_terrain_layer('Slope')
   	except Exception as _:
   	elev = self.get_terrain_elevation()
   	slope = compute_slope_degrees(elev, self.resolution)

   I think we should first check if the file exists, then read it if it does. Only then, we can handle exceptions if something goes wrong. We should not fall into an exception if the file does not exist, since that will happen the first time running it. These functions should return some False/True, instead of carrying over a generic exception. In some other instances, computations are performed within a try/except block and I think that should really be removed. When something goes bad, the actual exception is never given to the user.

2. We should really consider moving grid data to an xarray format. The rasterio operations can probably be handled by rioxarray . Problems with orientation of aspect and wind direction conventions are handled ad-hoc. For example, this should be removed:
   

   SSRS/ssrs/layers.py

   Line 560 in 1cda662

   wdir_sx = (np.mean(wdirn)+90)%360 # wdir for sx due to weird convention

   
   

   SSRS/ssrs/layers.py

   Line 579 in 1cda662

   w0 = wspeedAtRefHeight * np.sin(np.deg2rad(slope)) * np.cos(np.deg2rad(((-np.mean(wdirn)+90)%360)-aspect))

3. The simulator class has too many methods that should not be there. For example, all the plotting routines should be moved to another file/class.

4. kwargs keywords should be added to plotting functions, which are then passed to the actual pcolormesh calls.

Pressure levels for heights AGL between 100 and 250 m in HRRR

Working my way through PR #16, I noticed some problems on the HRRR interface.

When getting data from HRRR using wind_velocity_direction_at_altitude, at any height AGL height_above_ground above 100 m, we fall into the following else to get the appropriate pressure level:

SSRS/ssrs/hrrr/hrrr.py

Lines 350 to 363 in a9114c7

	if height_above_ground_m > 0.0 and height_above_ground_m < 45.0:
	grib_field = f'{varname}:10 m above ground:anl'
	u_data_var = 'u10'
	v_data_var = 'v10'
	elif height_above_ground_m >= 45.0 and height_above_ground_m < 100.0:
	grib_field = f'{varname}:80 m above ground:anl'
	u_data_var = 'u'
	v_data_var = 'v'
	else:
	nearest_pressures = self.nearest_pressures(ground_level_m)
	closest_pressure_above = nearest_pressures['closest_pressure_above']
	grib_field = f'{varname}:{closest_pressure_above} mb'
	u_data_var = 'u'
	v_data_var = 'v'

where ground_level_m is used as an argument to nearest_pressures. However, oftentimes the call to wind_velocity_direction_at_altitude does not include ground_level_m, but rather height_above_ground_m. The ground_level_m is zero by default:

SSRS/ssrs/hrrr/hrrr.py

Line 260 in a9114c7

ground_level_m=0.0,

According to the nearest_pressures function's docstring, h is the height above sea level:

SSRS/ssrs/hrrr/hrrr.py

Lines 92 to 93 in a9114c7

	h: float
	Height above sea level in meters

so I'm not sure if it is appropriate to use height_above_ground_m

What should we use here? Not specifying ground_level_m does not work because of the default 0 (and would not even be appropriate). Should we first get the ground level and then combine it with the height AGL?

Right now, in the latest commit from PR #16, I replaced line 359 above with

SSRS/ssrs/hrrr/hrrr.py

Line 376 in 43a728f

nearest_pressures = self.nearest_pressures(height_above_ground_m)

However, I do understand that this is not really appropriate.

What would be appropriate path forward here?

Cleanup inputs

• sim-movement and movement_model appear redundant
• need to fix output sections, e.g., random walk parameters currently get lumped under "terrain"
• add heuristics_ or hssrs_ prefix to H-SSRS-specific parameters
• recommend renaming wtk_source options with "EAGLE" to "NRELHPC" for generality / clarity
• add parameters for improved orographic updraft model, e.g., https://github.com/rthedin/SSRS/blob/feature/w0i_option/ssrs/config.py#L65-L70

https://github.com/NREL/SSRS/blob/dev/ssrs/config.py#L11-L82

Fix dependencies for HRRR

SSRS Simulator cannot be initialized with from .hrrr import HRRR lines in code. The error may be reproduced with the following single line:

from ssrs.hrrr.hrrr import HRRR

which results in

RuntimeError: Cannot find the ecCodes library

Diving deeper, this can actually be traced back to:

import gribapi

which is called by the eccodes library.

Issue when checking saved terrain data

When in the Terrain class we check if the data exists in the bound specified by the user, it does not consider the pad which may have been changed from when the original data was downloaded..