reVX.setbacks.setbacks_cli.compute_setbacks

compute_setbacks(excl_fpath, node_feature_type, node_file_path, node_multiplier, out_dir, tag, hub_height=None, rotor_diameter=None, base_setback_dist=None, regulations_fpath=None, weights_calculation_upscale_factor=None, replace=False, hsds=False, out_layers=None, feature_specs=None, max_workers=None)[source]

Compute Setbacks.

Setbacks can be computed for a specific turbine (hub height and rotor diameter) or more generally using a base setback distance.

Setbacks can be computed either locally (on a per-county basis with given distances/multipliers) or everywhere under a generic setback multiplier assumption applied to either the turbine tip-height or the base setback distance. These two methods can also be applied simultaneously - local setbacks are computed where given (via a the regulation file input) and a generic multiplier applied to the turbine tip-height or the base setback distance everywhere else.

Partial inclusions can be computed instead of boolean exclusions, both of which can be fed directly into reV.

Parameters:

excl_fpath (str) – Path to HDF5 file containing the county FIPS layer (should be called cnty_fips) used to match local regulations in regulations_fpath to counties on the grid. No data will be written to this file unless explicitly requested via the out_layers input.
node_feature_type (str) – Name of the feature type being run. Must be a key of the SETBACKS dictionary.
node_file_path (str) – Path to input feature file. This file MUST be a GeoPackage (and have the “.gpkg” extension).
node_multiplier (int | float | str | None, optional) – A setback multiplier to use if regulations are not supplied. This multiplier will be applied to the base_setback_dist to calculate the setback. If supplied along with regulations_fpath, this input will be used to apply a setback to all counties not listed in the regulations file.
out_dir (str) – Path to output directory where output file should be written.
tag (str) – Tag to add to each output file to make it unique (i.e. not clash with output files from other nodes).
hub_height (int | float, optional) – Turbine hub height (m), used along with rotor diameter to compute the blade tip-height which is used as the base setback distance for generic/local regulations. If this input is specified, rotor_diameter must also be given, and base_setback_dist must be set to None, otherwise an error in thrown. The base setback distance is scaled by generic/local multipliers (provided either via the regulations_fpath csv, or the generic_setback_multiplier input, or both) before setbacks are computed. By default, None.
rotor_diameter (int | float, optional) – Turbine rotor diameter (m), used along with hub height to compute the blade tip-height, which is used as the base setback distance for generic/local regulations. If this input is specified, hub_height must also be given, and base_setback_dist must be set to None, otherwise an error in thrown. The base setback distance is scaled by generic/local multipliers (provided either via the regulations_fpath csv, or the generic_setback_multiplier input, or both) before setbacks are computed. By default, None.
base_setback_dist (int | float, optional) – Base setback distance (m). This value is used as the base setback distance for generic/local regulations. If this input is specified, both hub_height``and ``rotor_diameter must be set to None, otherwise an error in thrown. The base setback distance is scaled by generic/local multipliers (provided either via the regulations_fpath csv, or the generic_setback_multiplier input, or both) before setbacks are computed. By default, None.
regulations_fpath (str, optional) – Path to regulations .csv or .gpkg file. At a minimum, this file must contain the following columns:
- Feature Type: Contains labels for the type of setback that each row represents. This should be a “feature_type” label that can be found in the SETBACK_SPECS dictionary (e.g. "structures", "roads", "water", etc.), unless you have created your own setback calculator using setbacks_calculator(), in which case this label can match the feature_type input you used for that function call.
- Feature Subtype: Contains labels for feature subtypes. The feature subtypes are only used for down-selecting the local regulations that should be applied for a particular feature, so often you can leave this blank or set it to None. If you do specify this value, it should be a “feature_subtypes_to_exclude” label that can be found in the SETBACK_SPECS dictionary, unless you have created your own setback calculator using setbacks_calculator(), in which case this label can match the feature_subtypes_to_exclude input you used for that function call.
- Value Type: Specifies wether the value is a multiplier or static height. See SetbackRegulations (if using only base_setback_dist input) or WindSetbackRegulations (if using hub_height + rotor_diameter input) for more info.
- Value: Numeric value of the setback or multiplier.
- FIPS: Specifies a unique 5-digit code for each county (this can be an integer - no leading zeros required). This is used along side the cnty_fips layer in the excl_fpath to match the county regulations to the county’s spatial extent.
This option overrides the generic_setback_multiplier input, but only for counties that are listed in the input CSV file. This means both regulations_fpath and generic_setback_multiplier can be specified simultaneously in order to compute setbacks driven by local ordinance where given + a generic multiplier applied everywhere else. By default, None, which does not compute any local setbacks.
weights_calculation_upscale_factor (int, optional) – Optional input to specify partial setback calculations. If this value is an int > 1, the output will be a layer with inclusion weight values (floats ranging from 0 to 1). Note that this is backwards w.r.t the typical output of exclusion integer values (1 for excluded, 0 otherwise). Values <= 1 will still return a standard exclusion mask. For example, a cell that was previously excluded with a boolean mask (value of 1) may instead be converted to an inclusion weight value of 0.75, meaning that 75% of the area corresponding to that point should be included (i.e. the exclusion feature only intersected a small portion - 25% - of the cell). This percentage inclusion value is calculated by upscaling the output array using this input value, rasterizing the exclusion features onto it, and counting the number of resulting sub-cells excluded by the feature. For example, setting the value to 3 would split each output cell into nine sub-cells - 3 divisions in each dimension. After the feature is rasterized on this high-resolution sub-grid, the area of the non-excluded sub-cells is totaled and divided by the area of the original cell to obtain the final inclusion percentage. Therefore, a larger upscale factor results in more accurate percentage values. If None (or a value <= 1), this process is skipped and the output is a boolean exclusion mask. By default None.
replace (bool, optional) – Flag to replace the output GeoTIFF if it already exists. By default, False.
hsds (bool, optional) – Boolean flag to use h5pyd to handle HDF5 “files” hosted on AWS behind HSDS. By default, False.
out_layers (dict, optional) – Dictionary mapping the input feature file names (with extension) to names of layers under which exclusions should be saved in the excl_fpath HDF5 file. If None or empty dictionary, no layers are saved to the HDF5 file. By default, None.
feature_specs (dict, optional) – Optional dictionary specifying new feature setback calculators or updates to existing ones. The keys of this dictionary should be names of the features for which a specification is being provided. If the name is already a key in SETBACK_SPECS, the corresponding specifications wil be updated for that feature. Otherwise, the name will represent a new feature type, which can be used as a key in the features input. The values of the feature-type keys should be dictionaries, where the keys are parameters of the setbacks_calculator() function. Required parameters in that function are required keys of these dictionaries. Values should be the updated value. For example, the input
```
feature_specs: {
    "water": {
        "num_features_per_worker": 500
    },
    "oil_and_gas_pipelines": {
        "feature_type": "oil and gas",
        "feature_filter_type": "clip"
    }
}
```
would update the existing "water" setbacks calculator to compute 500 features per worker at a time and create a new "oil_and_gas_pipelines" feature that looks for the string "oil and gas" in the regulations file and clips the feature to a county before calculating a setback. Note that even though "oil_and_gas_pipelines" is not a default feature supported by reVX, you can now use it in the features input. This can also be helpful if you need to compute the same type of setback for multiple different input datasets. For example, the input
```
feature_specs: {
    "water-nwi": {
        "feature_type": "water",
        "buffer_type": "default",
        "feature_filter_type": "clip",
        "num_features_per_worker": 700,
    },
    "water-nhd": {
        "feature_type": "water",
        "buffer_type": "default",
        "feature_filter_type": "clip",
        "num_features_per_worker": 10_000,
    }
}
```
would allow you to set up your features input like so:
```
features: {
    "water-nwi": "/path/to/nwi/*.gpkg",
    "water-nhd": "/path/to/nhd/*.gpkg",
}
```
By default, None, which does not add any new setback calculators (the default ones defined in SETBACK_SPECS are still available).
max_workers (int, optional) – Number of workers to use for setback exclusion computation. If this value is 1, the computation runs in serial. If this value is > 1, the computation runs in parallel with that many workers. If None, the computation runs in parallel on all available cores. By default, None.

Returns:

str – Path to output GeoTIFF file containing setback exclusion data.