waves.project

waves.project#

Provides the Project class that ties to together ORBIT (CapEx), WOMBAT (OpEx), and FLORIS (AEP) simulation libraries for a simplified modeling workflow.

Functions

`convert_to_multi_index`(date_tuples, name)	Converts year and month tuple(s) into a pandas MultiIndex.
`load_weather`(value)	Loads in the weather file using PyArrow, but returing a `pandas.DataFrame` object.

Classes

Project(library_path, turbine_type, ...[, ...])

The unified interface for creating, running, and assessing analyses that combine ORBIT, WOMBAT, and FLORIS.

waves.project.convert_to_multi_index(date_tuples, name)[source]#

Converts year and month tuple(s) into a pandas MultiIndex.

Return type:

MultiIndex

Parameters:

date_tuples (tuple[int, int] | list[tuple[int, int]] | pd.MultiIndex | None) -- A single (tuple), or many combinations (list of tuple``s) of ``int year and int month. If a MultiIndex or None is passed, it will be returned as-is.
name (str) -- The name of the variable to ensure that a helpful error is raised in case of invalid inputs.

Returns:

pd.MultiIndex -- A pandas MultIndex with index columns: "year" and "month", or None, if None is passed.

Raises:

ValueError -- Raised if the year, month combinations are not length 2 and are not tuples

waves.project.load_weather(value)[source]#

Loads in the weather file using PyArrow, but returing a pandas.DataFrame object. Must have the column "datetime", which can be converted to a pandas.DatetimeIndex.

Return type:

DataFrame

Parameters:

value (str | Path | DataFrame) -- str | Path | pd.DataFrame The input file name and path, or a pandas.DataFrame (gets passed back without modification).

Returns:

pd.DataFrame: The full weather profile with the column "datetime" as a pandas.DatetimeIndex.

class waves.project.Project(library_path, turbine_type, weather_profile, orbit_config=None, wombat_config=None, floris_config=None, landbosse_config=None, orbit_start_date=None, orbit_weather_cols=['windspeed', 'wave_height'], floris_windspeed='windspeed', floris_wind_direction='wind_direction', floris_turbulence_intensity=None, floris_x_col='floris_x', floris_y_col='floris_y', connect_floris_to_layout=True, connect_orbit_array_design=True, offtake_price=None, fixed_charge_rate=0.0582, environmental_loss_ratio=0.0159, discount_rate=None, finance_rate=None, reinvestment_rate=None, soft_capex_date=None, project_capex_date=None, system_capex_date=None, turbine_capex_date=None, report_config=None)[source]#

The unified interface for creating, running, and assessing analyses that combine ORBIT, WOMBAT, and FLORIS.

Parameters:

library_path (str | pathlib.Path) -- The file path where the configuration data for ORBIT, WOMBAT, and FLORIS can be found.
turbine_type (str) -- The type of wind turbine used. Must be one of "land", "fixed", or "floating".
weather_profile (str | pathlib.Path) --
The file path where the weather profile data is located, with the following column requirements:
- datetime: The timestamp column
- orbit_weather_cols: see orbit_weather_cols
- floris_windspeed: see floris_windspeed
- floris_wind_direction: see floris_wind_direction
orbit_weather_cols (list[str]) -- The windspeed and wave height column names in weather to use for running ORBIT. Defaults to ["windspeed", "wave_height"].
floris_windspeed (str) -- The windspeed column in weather that will be used for the FLORIS wake analysis. Defaults to "windspeed_100m".
floris_wind_direction (str) -- The wind direction column in weather that will be used for the FLORIS wake analysis. Defaults to "wind_direction_100m".
floris_turbulence_intensity (str | None) -- The turbulence intensity column in weather that will be used for the FLORIS wake analysis. If None, then the input from floris_config will be used. Defaults to "None".
floris_x_col (str) -- The column of x-coordinates in the WOMBAT layout file that corresponds to the Floris.farm.layout_x Defaults to "floris_x".
floris_y_col (str) -- The column of x-coordinates in the WOMBAT layout file that corresponds to the Floris.farm.layout_y Defaults to "floris_y".
orbit_config (str | pathlib.Path | dict | None) -- The ORBIT configuration file name or dictionary. If None, will not set up the ORBIT simulation component.
landbosse_config (str | pathlib.Path | dict | None) -- The LandBOSSE configuration file name or dictionary. If None, will not set up the LandBOSSE simulation component.
wombat_config (str | pathlib.Path | dict | None) -- The WOMBAT configuration file name or dictionary. If None, will not set up the WOMBAT simulation component.
floris_config (str | pathlib.Path | dict | None) --
The FLORIS configuration file name or dictionary. If None, will not set up the FLORIS simulation component.

Note

The farm:trubine_library_path is automatically set to use the library_path / turbines folder to maintain consistency.
connect_floris_to_layout (bool, optional) --
If True, automatically connect the FLORIS and WOMBAT layout files, so that the simulation results can be linked. If False, don't connec the two models. Defaults to True.

Note

This should only be set to False if the FLORIS and WOMBAT layouts need to be connected in an additional step
connect_orbit_array_design (bool, optional) -- If True, the ORBIT array cable lengths will be calculated on initialization and added into the primary layout file.
offtake_price (float, optional) -- The price paid per MWh of energy produced. Defaults to None.
fixed_charge_rate (float, optional) -- Revenue per amount of investment required to cover the investment cost, with the default provided through the NREL 2021 Cost of Energy report [1]. Defaults to 0.0582.
discount_rate (float, optional) -- The minimum acceptable rate of return, or the assumed return on an alternative investment of comparable risk. Defaults to None.
finance_rate (float, optional) -- Interest rate paid on the cash flows. Defaults to None.
reinvestment_rate (float, optional) -- Interest rate paid on the cash flows upon reinvestment. Defaults to None.
environmental_loss_ratio (float, optional) -- Percentage of environmental losses to deduct from the total energy production. Should be represented as a decimal in the range of [0, 1]. Defaults to 0.0159.
orbit_start_date (str | None) -- The date to use for installation phase start timings that are set to "0" in the install_phases configuration. If None the raw configuration data will be used. Defaults to None.
soft_capex_date (tuple[int, int] | list[tuple[int, int]] | None, optional) -- The date(s) where the ORBIT soft CapEx costs should be applied as a tuple of year and month, for instance: (2020, 1) for January 2020. Alternatively multiple dates can be set, which evenly divides the cost over all the dates, by providing a list of year and month combinations, for instance, a semi-annual 2 year cost starting in 2020 would look like: [(2020, 1), (2020, 7), (2021, 1), (2021, 7)]. If None is provided, then the CapEx date will be the same as the start of the installation. Defaults to None
project_capex_date (tuple[int, int] | list[tuple[int, int]] | None, optional) -- The date(s) where the ORBIT project CapEx costs should be applied as a tuple of year and month, for instance: (2020, 1) for January 2020. Alternatively multiple dates can be set, which evenly divides the cost over all the dates, by providing a list of year and month combinations, for instance, a semi-annual 2 year cost starting in 2020 would look like: [(2020, 1), (2020, 7), (2021, 1), (2021, 7)]. If None is provided, then the CapEx date will be the same as the start of the installation. Defaults to None
system_capex_date (tuple[int, int] | list[tuple[int, int]] | None, optional) -- The date(s) where the ORBIT system CapEx costs should be applied as a tuple of year and month, for instance: (2020, 1) for January 2020. Alternatively multiple dates can be set, which evenly divides the cost over all the dates, by providing a list of year and month combinations, for instance, a semi-annual 2 year cost starting in 2020 would look like: [(2020, 1), (2020, 7), (2021, 1), (2021, 7)]. If None is provided, then the CapEx date will be the same as the start of the installation. Defaults to None.
turbine_capex_date (tuple[int, int] | list[tuple[int, int]] | None, optional) -- The date(s) where the ORBIT turbine CapEx costs should be applied as a tuple of year and month, for instance: (2020, 1) for January 2020. Alternatively multiple dates can be set, which evenly divides the cost over all the dates, by providing a list of year and month combinations, for instance, a semi-annual 2 year cost starting in 2020 would look like: [(2020, 1), (2020, 7), (2021, 1), (2021, 7)]. If None is provided, then the CapEx date will be the same as the start of the installation. Defaults to None.
report_config (dict[str, dict], optional) -- A dictionary that can be passed to generate_report(), and be used as the metrics_configuration dictionary. An additional field of name is required as input, which will be passed to simulation_name. Defaults to None.

References

library_path: Path#

turbine_type: str#

weather_profile: str#

orbit_config: str | Path | dict | None#

wombat_config: str | Path | dict | None#

floris_config: str | Path | dict | None#

landbosse_config: str | Path | dict | None#

orbit_start_date: str | None#

orbit_weather_cols: list[str]#

floris_windspeed: str#

floris_wind_direction: str#

floris_turbulence_intensity: str | None#

floris_x_col: str#

floris_y_col: str#

connect_floris_to_layout: bool#

connect_orbit_array_design: bool#

offtake_price: float | int#

fixed_charge_rate: float#

environmental_loss_ratio: float#

discount_rate: float#

finance_rate: float#

reinvestment_rate: float#

soft_capex_date: tuple[int, int] | list[tuple[int, int]] | None#

project_capex_date: tuple[int, int] | list[tuple[int, int]] | None#

system_capex_date: tuple[int, int] | list[tuple[int, int]] | None#

turbine_capex_date: tuple[int, int] | list[tuple[int, int]] | None#

report_config: dict[str, dict] | None#

weather: DataFrame#

orbit_config_dict: dict#

landbosse_config_dict: dict#

wombat_config_dict: dict#

floris_config_dict: dict#

wombat: Simulation#

orbit: ProjectManager#

landbosse: LandBOSSERunner#

floris: FlorisModel#

project_wind_rose: WindRose#

monthly_wind_rose: WindRose#

floris_turbine_order: list[str]#

turbine_potential_energy: DataFrame#

turbine_production_energy: DataFrame#

project_potential_energy: DataFrame#

project_production_energy: DataFrame#

_fi_dict: dict[tuple[int, int], FlorisModel]#

operations_start: Timestamp#

operations_end: Timestamp#

operations_years: int#

library_exists(attribute, value)[source]#

Validates that the user input to library_path is a valid directory.

Return type:

None

Parameters:

attribute (attrs.Attribute) -- The attrs Attribute information/metadata/configuration.
value (Path) -- The user input.

Raises:

FileNotFoundError -- Raised if value does not exist.
ValueError -- Raised if the value exists, but is not a directory.

validate_turbine_type(attribute, value)[source]#

Validates that :py:attr`turbine_type` is one of "land", "fixed", or "floating".

Return type:

None

Parameters:

attribute (attrs.Attribute) -- The attrs Attribute information/metadata/configuration.
value (str) -- The user input.

Raises:

ValueError -- Raised if not one of "land", "fixed", or "floating".

validate_report_config(attribute, value)[source]#

Validates the user input for report_config.

Return type:

None

Parameters:

attribute (attrs.Attribute) -- The attrs Attribute information/metadata/configuration.
value (dict | None) -- _description_

Raises:

ValueError -- Raised if report_config is not a dictionary.
KeyError -- Raised if report_config does not contain a key, value pair for "name".

classmethod from_file(library_path, config_file)[source]#

Creates a Project object from either a JSON or YAML file. See Project for configuration requirements.

Return type:

Project

Parameters:

library_path (str | Path) -- The library path to be used in the simulation.
config_file (str | Path) -- The configuration file to create a Project object from, which should be located at: library_path / project / config / config_file.

Raises:

FileExistsError -- Raised if library_path is not a valid directory.
ValueError -- Raised if config_file is not a JSON or YAML file.

Returns:

Project -- An initialized Project object.

property config_dict: dict#

Generates a configuration dictionary that can be saved to a new file for later re/use.

Returns:: dict -- YAML-safe dictionary of a Project-loadable configuration.

check_consistent_config()[source]#

Check the configurations of the models after they have been set up but before running the model to ensure the basicinputs to each model are consistent.

Return type:: None

save_config(config_file)[source]#

Saves a copy of the Project configuration settings to recreate the results of the current settings.

Return type:: None
Parameters:: config_file (str | Path) -- The name to use for saving to a YAML configuration file.

setup_orbit()[source]#

Creates the ORBIT Project Manager object and readies it for running an analysis.

Return type:: None

setup_landbosse()[source]#

Creates the LandBOSSE runner object and readies it for running an analysis.

Return type:: None

setup_wombat()[source]#

Creates the WOMBAT Simulation object and readies it for running an analysis.

Return type:: None

setup_floris()[source]#

Creates the FLORIS FlorisInterface object and readies it for running an analysis.

Return type:: None

connect_floris_to_turbines(x_col='floris_x', y_col='floris_y')[source]#

Generates floris_turbine_order from the WOMBAT Windfarm.layout_df.

Parameters:

x_col (str, optional) -- The column name in the layout corresponding to the FLORIS x poszitions, by default "floris_x".
y_col (str, optional) -- The column name in the layout corresponding to the FLORIS y positions, by default "floris_y".

connect_orbit_cable_lengths(save_results=True)[source]#

Runs the ORBIT design phases, so that the array system has computed the necessary cable length and distance measures, then attaches the cable length calculations back to the layout file, saves the results to the layout files, and reloads both ORBIT and WOMBAT with this data.

Return type:: None
Parameters:: save_results (bool, optional) -- Save the resulting, updated layout table to both library_path/project/plant/wombat_config_dict["layout"] and library_path/cables/wombat_config_dict["layout"] for WOMBAT and ORBIT compatibility, respectively.

generate_floris_positions_from_layout(x_col='easting', y_col='northing', update_config=True, config_fname=None)[source]#

Updates the FLORIS layout_x and layout_y based on the relative coordinates from the WOMBAT layout file.

Return type:

None

Parameters:

x_col (str, optional) -- The relative, distance-based x-coordinate column name. Defaults to "easting".
y_col (str, optional) -- The relative, distance-based y-coordinate column name. Defaults to "northing".
update_config (bool, optional) -- Run FlorisInterface.reinitialize with the updated layout_x and layout_y values. Defaults to True.
config_fname (str | None, optional) -- Provide a file name if update_config and this new configuration should be saved. Defaults to None.

run_wind_rose_aep(full_wind_rose=False, set_kwargs=None)[source]#

Runs the custom FLORIS WindRose AEP methodology that allows for gathering of intermediary results.

Parameters:

full_wind_rose (bool, optional) -- If True, the full wind profile will be used, otherwise, if False, the wind profile will be limited to just the simulation period. Defaults to False.
set_kwargs (dict | None, optional) --
Arguments that are provided to FlorisInterface.get_farm_AEP_wind_rose_class(). Defaults to None.

From FLORIS:
- yaw_angles (NDArrayFloat | list[float] | None, optional):
  The relative turbine yaw angles in degrees. If None is specified, will assume that the turbine yaw angles are all zero degrees for all conditions. Defaults to None.
- turbine_weights (NDArrayFloat | list[float] | None, optional):
  weighing terms that allow the user to emphasize power at particular turbines and/or completely ignore the power from other turbines. This is useful when, for example, you are modeling multiple wind farms in a single floris object. If you only want to calculate the power production for one of those farms and include the wake effects of the neighboring farms, you can set the turbine_weights for the neighboring farms' turbines to 0.0. The array of turbine powers from floris is multiplied with this array in the calculation of the objective function. If None, this is an array with all values 1.0 and with shape equal to (n_wind_directions, n_wind_speeds, n_turbines). Defaults to None.

run_floris(set_kwargs=None, full_wind_rose=False)[source]#

Runs either a FLORIS wind rose analysis for a simulation-level AEP value (which="wind_rose") or a turbine-level time series for the WOMBAT simulation period (which="time_series").

Return type:

None

Parameters:

set_kwargs (dict | None, optional) -- Any keyword arguments to be assed to FlorisInterface.reinitialize(). Defaults to None.
full_wind_rose (bool, optional) -- Indicates, for "wind_rose" analyses ONLY, if the full weather profile from weather (True) or the limited, WOMBAT simulation period (False) should be used for analyis. Defaults to False.

Raises:

ValueError -- Raised if which is not one of "wind_rose" or "time_series".:

run(floris_kwargs=None, full_wind_rose=False, skip=None)[source]#

Run all three models in serial, or a subset if skip is used.

Return type:

None

Parameters:

floris_kwargs (dict | None) -- Any additional FlorisModel.set keyword arguments. Defaults to None.
full_wind_rose (bool, optional) -- Indicates, for "wind_rose" analyses ONLY, if the full weather profile from weather (True) or the limited, WOMBAT simulation period (False) should be used for analyis. Defaults to False.
skip (list[str] | None, optional) -- A list of models to be skipped. This is intended to be used after a model is reinitialized with a new or modified configuration. Defaults to None.

reinitialize(orbit_config=None, landbosse_config=None, wombat_config=None, floris_config=None)[source]#

Enables a user to reinitialize one or multiple of the CapEx, OpEx, and AEP models.

Return type:

None

Parameters:

orbit_config (str | Path | dict | None, optional) -- ORBIT configuration file or dictionary. Defaults to None.
landbosse_config ((str | Path | dict | None, optional) -- LandBOSSE configuration file or dictionary. Defaults to None.
wombat_config (str | Path | dict | None, optional) -- WOMBAT configuation file or dictionary. Defaults to None.
floris_config ((str | Path | dict | None, optional) -- FLORIS configuration file or dictionary. Defaults to None.

Raises:

RuntimeError -- Raised if neither ORBIT nor LandBOSSE are configured to run.

plot_farm(figure_kwargs=None, draw_kwargs=None, return_fig=False)[source]#

Plot the graph representation of the windfarm as represented through WOMBAT.

Return type:

None | tuple[figure, axes]

Parameters:

figure_kwargs (dict | None, optional) -- Customized keyword arguments for matplotlib figure instantiation that will passed as plt.figure(**figure_kwargs). Defaults to None.
draw_kwargs (dict | None, optional) -- Customized keyword arguments for networkx.draw() that can will passed as nx.draw(**figure_kwargs). Defaults to None.
return_fig (bool, optional) -- Whether or not to return the figure and axes objects for further editing and/or saving. Defaults to False.

Returns:

None | tuple[plt.figure, plt.axes] -- If return_fig is False, then None is returned, otherwise (True) the Figure and Axes objects are returned.

n_turbines()[source]#

Returns the number of turbines from either ORBIT, WOMBAT, or FLORIS depending on which model is available internally.

Return type:: int
Returns:: int -- The number of turbines in the project.
Raises:: RuntimeError -- Raised if no model configurations were provided on initialization.

turbine_rating()[source]#

Calculates the average turbine rating, in MW, of all the turbines in the project.

Return type:: float
Returns:: float -- The average rating of the turbines, in MW.
Raises:: RuntimeError -- Raised if no model configurations were provided on initialization.

n_substations()[source]#

Calculates the number of substations in the project.

Return type:: int
Returns:: int -- The number of substations in the project.

capacity(units='mw')[source]#

Calculates the project's capacity in the desired units of kW, MW, or GW.

Return type:: float
Parameters:: units (str, optional) -- One of "kw", "mw", or "gw". Defaults to "mw".
Returns:: float -- The project capacity, returned in the desired units
Raises:: RuntimeError -- Raised if no model configurations were provided on initialization.

capex(breakdown=False, per_capacity=None)[source]#

Calculate capital expenditure (CapEx) using ORBIT or LandBOSSE outputs.

Return type:

DataFrame | float

Parameters:

breakdown (bool, optional) -- Provide a detailed view of the CapEx breakdown, and a total, which is the sum of the BOS, turbine, project, and soft CapEx categories. Defaults to False.
per_capacity (str, optional) -- Provide the CapEx normalized by the project's capacity, in the desired units. If None, then the unnormalized CapEx is returned, otherwise it must be one of "kw", "mw", or "gw". Defaults to None.

Raises:

RuntimeError -- Raised if neither ORBIT nor LandBOSSE have been run.

Returns:

pd.DataFrame | float -- Project CapEx, normalized by per_capacity, if using, as either a pandas DataFrame if breakdown is True, otherwise, a float total.

capex_orbit(*, breakdown=False)[source]#

Provides a thin wrapper to ORBIT's ProjectManager CapEx calculations that can provide a breakdown of total or normalize it by the project's capacity, in MW.

Return type:: DataFrame
Parameters:: breakdown (bool, optional) -- Provide a detailed view of the CapEx breakdown, and a total, which is the sum of the BOS, turbine, project, and soft CapEx categories. Defaults to False.
Returns:: pd.DataFrame -- Project CapEx, normalized by per_capacity, if using, as either a pandas DataFrame if breakdown is True, otherwise, a float total.

capex_landbosse(*, breakdown=False)[source]#

Calculates project CapEx from LandBOSSE result, in MW.

Return type:: DataFrame | float
Parameters:: breakdown (bool, optional) -- Provide a detailed view of the CapEx breakdown, and a total, which is the sum of the BOS, turbine, project, and soft CapEx categories. Defaults to False.
Returns:: pd.DataFrame | float -- Project CapEx, normalized by per_capacity, if using, as either a pandas DataFrame if breakdown is True, otherwise, a float total.

array_system_total_cable_length()[source]#

Calculates the total length of the cables in the array system, in km.

Returns:

float -- Total length, in km, of the array system cables.

Raises:

ValueError -- Raised if neither ArraySystemDesign nor CustomArraySystem design were created in ORBIT.
RuntimeError -- Raised if neither ORBIT nor LandBOSSE have been run.

export_system_total_cable_length()[source]#

Calculates the total length of the cables in the export system, in km.

Returns:

float -- Total length, in km, of the export system cables.

Raises:

ValueError -- Raised if ExportSystemDesign was not created in ORBIT.
RuntimeError -- Raised if neither ORBIT nor LandBOSSE have been run.

_get_floris_energy(which, frequency='project', by='windfarm', units='gw')[source]#

Return type:

DataFrame | float

Parameters:

which (str)
frequency (str)
by (str)
units (str)

energy_potential(frequency='project', by='windfarm', units='gw', per_capacity=None, aep=False)[source]#

Computes the potential energy production, or annual potential energy production, in GWh, for the simulation by extrapolating the monthly contributions to AEP if FLORIS (without wakes) results were computed by a wind rose, or using the time series results.

Return type:

DataFrame | float

Parameters:

frequency (str, optional) -- One of "project" (project total), "annual" (annual total), or "month-year" (monthly totals for each year).
by (str, optional) -- One of "windfarm" (project level) or "turbine" (turbine level) to indicate what level to calculate the energy production.
units (str, optional) -- One of "gw", "mw", or "kw" to determine the units for energy production.
per_capacity (str, optional) -- Provide the energy production normalized by the project's capacity, in the desired units. If None, then the unnormalized energy production is returned, otherwise it must be one of "kw", "mw", or "gw". Defaults to None.
aep (bool, optional) -- Flag to return the energy production normalized by the number of years the plan is in operation. Note that frequency must be "project" for this to be computed.

Raises:

ValueError -- Raised if frequency is not one of: "project", "annual", "month-year".

Returns:

pd.DataFrame | float -- The wind farm-level energy prodcution, in GWh, for the desired frequency.

energy_production(frequency='project', by='windfarm', units='gw', per_capacity=None, environmental_loss_ratio=None, aep=False)[source]#

Computes the energy production, or annual energy production.

To compute the losses, the total loss ratio from :py:method:`loss_ratio` is applied to each time step (e.g., month for month-year) rather than using each time step's losses. :rtype: DataFrame | float

This lower resolution apporach to turbine and time step energy stems from the nature of the loss method itself, which is intended for farm-level results.

Parameters:

frequency (str, optional) -- One of "project" (project total), "annual" (annual total), or "month-year" (monthly totals for each year).
by (str, optional) -- One of "windfarm" (project level) or "turbine" (turbine level) to indicate what level to calculate the energy production.
units (str, optional) -- One of "gw", "mw", or "kw" to determine the units for energy production.
per_capacity (str, optional) -- Provide the energy production normalized by the project's capacity, in the desired units. If None, then the unnormalized energy production is returned, otherwise it must be one of "kw", "mw", or "gw". Defaults to None.
environmental_loss_ratio (float, optional) -- The decimal environmental loss ratio to apply to the energy production. If None, then it will attempt to use the environmental_loss_ratio provided in the Project configuration. Defaults to 0.0159.
aep (bool, optional) -- Flag to return the energy production normalized by the number of years the plan is in operation. Note that frequency must be "project" for this to be computed.

Raises:

ValueError -- Raised if frequency is not one of: "project", "annual", "month-year".

Returns:

pd.DataFrame | float -- The wind farm-level energy prodcution, in GWh, for the desired frequency.

Return type:

DataFrame | float

energy_losses(frequency='project', by='windfarm', units='gw', per_capacity=None, environmental_loss_ratio=None, aep=False)[source]#

Computes the energy losses for the simulation by subtracting the energy production from the potential energy production.

To compute the losses, the total loss ratio from :py:method:`loss_ratio` is applied to each time step (e.g., month for month-year) rather than using each time step's losses. :rtype: DataFrame

This lower resolution apporach to turbine and time step energy stems from the nature of the loss method itself, which is intended for farm-level results.

Parameters:

frequency (str, optional) -- One of "project" (project total), "annual" (annual total), or "month-year" (monthly totals for each year).
by (str, optional) -- One of "windfarm" (project level) or "turbine" (turbine level) to indicate what level to calculate the energy production.
units (str, optional) -- One of "gw", "mw", or "kw" to determine the units for energy production.
per_capacity (str, optional) -- Provide the energy production normalized by the project's capacity, in the desired units. If None, then the unnormalized energy production is returned, otherwise it must be one of "kw", "mw", or "gw". Defaults to None.
environmental_loss_ratio (float, optional) -- The decimal environmental loss ratio to apply to the energy production. If None, then it will attempt to use the environmental_loss_ratio provided in the Project configuration. Defaults to 0.0159.
aep (bool, optional) -- AEP for the annualized losses. Only used for frequency = "project".

Raises:

ValueError -- Raised if frequency is not one of: "project", "annual", "month-year".

Returns:

pd.DataFrame | float -- The wind farm-level energy prodcution, in GWh, for the desired frequency.

Return type:

DataFrame

wake_losses(frequency='project', by='windfarm', units='kw', per_capacity=None, aep=False, ratio=False)[source]#

Computes the wake losses, in GWh, for the simulation by extrapolating the monthly wake loss contributions to AEP if FLORIS (with wakes) results were computed by a wind rose, or using the time series results.

Return type:

DataFrame | float

Parameters:

frequency (str, optional) -- One of "project" (project total), "annual" (annual total), or "month-year" (monthly totals for each year).
by (str, optional) -- One of "windfarm" (project level) or "turbine" (turbine level) to indicate what level to calculate the wake losses.
per_capacity (str, optional) -- Provide the wake losses normalized by the project's capacity, in the desired units. If None, then the unnormalized energy production is returned, otherwise it must be one of "kw", "mw", or "gw". Defaults to None.
aep (bool, optional) -- Flag to return the wake losses normalized by the number of years the plan is in operation. Note that frequency must be "project" for this to be computed.
ratio (bool, optional) -- Flag to return the wake loss ratio or the ratio of wake losses to the potential energy generation.
units (str)

Raises:

ValueError -- Raised if frequency is not one of: "project", "annual", "month-year".

Returns:

pd.DataFrame | float -- The wind farm-level losses, in GWh, for the desired frequency.

technical_loss_ratio()[source]#

Calculate technical losses based on the project type.

This method is adopted from ORCA where a 1% hysterisis loss is applied for fixed-bottom turbines. For floating turbines, this is 1% hysterisis, 0.1% for onboard equipment, and 0.1% for rotor misalignment (0.01197901 total).

Return type:: float
Returns:: float -- The technical loss ratio.

electrical_loss_ratio()[source]#

Calculate electrical losses based on ORBIT parameters.

Return type:: float
Returns:: float -- The electrical loss ratio.

loss_ratio(environmental_loss_ratio=None, breakdown=False)[source]#

Calculate total losses based on environmental, availability, wake, technical, and electrical losses. :rtype: DataFrame | float

Note

This method treats different types of losses as efficiencies and is applied

as in Equation 1 from Beiter et al. 2020 (https://www.nrel.gov/docs/fy21osti/77384.pdf).

Parameters:

environmental_loss_ratio (float, optional) -- The decimal environmental loss ratio to apply to the energy production. If None, then it will attempt to use the environmental_loss_ratio provided in the Project configuration. Defaults to 0.0159.
breakdown (bool, optional) -- Flag to return the losses breakdown including environmental, availability, wake, technical, electrical losses, and total losses.

Returns:

float | pd.DataFrame -- The total loss ratio, or the DataFrame of all loss ratios.

Return type:

DataFrame | float

availability(which, frequency='project', by='windfarm')[source]#

Calculates the availability based on either a time or energy basis. This is a thin wrapper around self.wombat.metrics.time_based_availability() or self.wombat.metrics.production_based_availability().

Return type:

DataFrame | float

Parameters:

which (str) -- One of "energy" or "time" to indicate which basis to use for the availability calculation. For "energy", this indicates the operating capacity of the project, and for "time", this is the ratio of any level operational to all time.
frequency (str, optional) -- One of "project" (project total), "annual" (annual total), or "month-year" (monthly totals for each year).
by (str, optional) -- One of "windfarm" (project level) or "turbine" (turbine level) to indicate what level to calculate the availability.

Returns:

pd.DataFrame | float -- The appropriate availability metric, as a DataFrame unless it's calculated at the project/windfarm level.

Raises:

ValueError -- Raised if which is not one of "energy" or "time".

capacity_factor(which, frequency='project', by='windfarm', environmental_loss_ratio=None)[source]#

Calculates the capacity factor over a project's lifetime as a single value, annual average, or monthly average for the whole windfarm or by turbine.

Return type:

DataFrame | float

Parameters:

which (str) -- One of "net" (realized energy / capacity) or "gross" (potential energy production / capacity).
frequency (str) -- One of "project", "annual", "monthly", or "month-year". Defaults to "project".
by (str) --
One of "windfarm" or "turbine". Defaults to "windfarm".

Note

This will only be checked for which = "net".
environmental_loss_ratio (float, optional) -- The decimal environmental loss ratio to apply to the energy production. If None, then it will attempt to use the environmental_loss_ratio provided in the Project configuration. Defaults to 0.0159.

Returns:

pd.DataFrame | float -- The capacity factor at the desired aggregation level.

opex(frequency='project', per_capacity=None)[source]#

Calculates the operational expenditures of the project.

Return type:

DataFrame | float

Parameters:

(str (frequency) -- Defaults to "project".
optional) (One of "project", "annual", "monthly", "month-year".) -- Defaults to "project".
per_capacity (str, optional) -- Provide the OpEx normalized by the project's capacity, in the desired units. If None, then the unnormalized OpEx is returned, otherwise it must be one of "kw", "mw", or "gw". Defaults to None.
frequency (str)

Returns:

pd.DataFrame | float -- The resulting OpEx DataFrame at the desired frequency, if more granular than the project frequency, otherwise a float. This will be normalized by the capacity, if per_capacity is not None.

revenue(frequency='project', offtake_price=None, per_capacity=None)[source]#

Calculates the revenue stream using the WOMBAT availabibility, FLORIS energy production, and WAVES energy pricing.

Return type:

DataFrame | float

Parameters:

frequency (str, optional) -- One of "project", "annual", "monthly", or "month-year". Defaults to "project".
offtake_price (float, optional) -- Price paid per MWh of energy produced. Defaults to None.
per_capacity (str, optional) -- Provide the revenue normalized by the project's capacity, in the desired units. If None, then the unnormalized revenue is returned, otherwise it must be one of "kw", "mw", or "gw". Defaults to None.

Returns:

pd.DataFrame | float -- The revenue stream of the wind farm at the provided frequency.

capex_breakdown(frequency='month-year', installation_start_date=None, soft_capex_date=None, project_capex_date=None, system_capex_date=None, turbine_capex_date=None, breakdown=False)[source]#

Calculates the monthly CapEx breakdwon into a DataFrame, that is returned at the desired frequency, allowing for custom starting dates for the varying CapEx costs.

Return type:

DataFrame

Parameters:

frequency (str, optional) -- The desired frequency of the outputs, where "month-year" is the monthly total over the course of a project's life. Must be one of: "project", "annual", "month-year". Defaults to "month-year"
installation_start_date (str | None, optional) -- If not provided in the Project configuration as orbit_start_date, an installation starting date that is parseable from a string by Pandas may be provided here. Defaults to None
soft_capex_date (tuple[int, int] | list[tuple[int, int]] | None, optional) -- The date(s) where the ORBIT soft CapEx costs should be applied as a tuple of year and month, for instance: (2020, 1) for January 2020. Alternatively multiple dates can be set, which evenly divides the cost over all the dates, by providing a list of year and month combinations, for instance, a semi-annual 2 year cost starting in 2020 would look like: [(2020, 1), (2020, 7), (2021, 1), (2021, 7)]. If None is provided, then the CapEx date will be the same as the start of the installation. Defaults to None
project_capex_date (tuple[int, int] | list[tuple[int, int]] | None, optional) -- The date(s) where the ORBIT project CapEx costs should be applied as a tuple of year and month, for instance: (2020, 1) for January 2020. Alternatively multiple dates can be set, which evenly divides the cost over all the dates, by providing a list of year and month combinations, for instance, a semi-annual 2 year cost starting in 2020 would look like: [(2020, 1), (2020, 7), (2021, 1), (2021, 7)]. If None is provided, then the CapEx date will be the same as the start of the installation. Defaults to None
system_capex_date (tuple[int, int] | list[tuple[int, int]] | None, optional) -- The date(s) where the ORBIT system CapEx costs should be applied as a tuple of year and month, for instance: (2020, 1) for January 2020. Alternatively multiple dates can be set, which evenly divides the cost over all the dates, by providing a list of year and month combinations, for instance, a semi-annual 2 year cost starting in 2020 would look like: [(2020, 1), (2020, 7), (2021, 1), (2021, 7)]. If None is provided, then the CapEx date will be the same as the start of the installation. Defaults to None.
turbine_capex_date (tuple[int, int] | list[tuple[int, int]] | None, optional) -- The date(s) where the ORBIT turbine CapEx costs should be applied as a tuple of year and month, for instance: (2020, 1) for January 2020. Alternatively multiple dates can be set, which evenly divides the cost over all the dates, by providing a list of year and month combinations, for instance, a semi-annual 2 year cost starting in 2020 would look like: [(2020, 1), (2020, 7), (2021, 1), (2021, 7)]. If None is provided, then the CapEx date will be the same as the start of the installation. Defaults to None.
offtake_price (int | float | None, optional) -- The price paid for the energy produced, by default None.
breakdown (bool, optional) -- If True, all the CapEx categories will be provided as a column, in addition to the OpEx and Revenue columns, and the total cost in "cash_flow", othwerwise, only the "cash_flow" column will be provided. Defaults to False.

Returns:

pd.DataFrame -- Returns the pandas DataFrame of the cashflow with a fixed monthly or annual interval, or a project total for the desired categories.

Raises:

ValueError -- Raised if frequency is not one of: "project", "annual", "month-year".
TypeError -- Raised if a valid starting date can't be found for the installation.

cash_flow(frequency='month-year', installation_start_date=None, soft_capex_date=None, project_capex_date=None, system_capex_date=None, turbine_capex_date=None, offtake_price=None, breakdown=False)[source]#

Calculates the monthly cashflows into a DataFrame, that is returned at the desired frequency, and with or without a high level breakdown, allowing for custom starting dates for the varying CapEx costs.

Return type:

DataFrame

Parameters:

frequency (str, optional) -- The desired frequency of the outputs, where "month-year" is the monthly total over the course of a project's life. Must be one of: "project", "annual", "month-year". Defaults to "month-year"
installation_start_date (str | None, optional) -- If not provided in the Project configuration as orbit_start_date, an installation starting date that is parseable from a string by Pandas may be provided here. Defaults to None
soft_capex_date (tuple[int, int] | list[tuple[int, int]] | None, optional) -- The date(s) where the ORBIT soft CapEx costs should be applied as a tuple of year and month, for instance: (2020, 1) for January 2020. Alternatively multiple dates can be set, which evenly divides the cost over all the dates, by providing a list of year and month combinations, for instance, a semi-annual 2 year cost starting in 2020 would look like: [(2020, 1), (2020, 7), (2021, 1), (2021, 7)]. If None is provided, then the CapEx date will be the same as the start of the installation. Defaults to None
project_capex_date (tuple[int, int] | list[tuple[int, int]] | None, optional) -- The date(s) where the ORBIT project CapEx costs should be applied as a tuple of year and month, for instance: (2020, 1) for January 2020. Alternatively multiple dates can be set, which evenly divides the cost over all the dates, by providing a list of year and month combinations, for instance, a semi-annual 2 year cost starting in 2020 would look like: [(2020, 1), (2020, 7), (2021, 1), (2021, 7)]. If None is provided, then the CapEx date will be the same as the start of the installation. Defaults to None
system_capex_date (tuple[int, int] | list[tuple[int, int]] | None, optional) -- The date(s) where the ORBIT system CapEx costs should be applied as a tuple of year and month, for instance: (2020, 1) for January 2020. Alternatively multiple dates can be set, which evenly divides the cost over all the dates, by providing a list of year and month combinations, for instance, a semi-annual 2 year cost starting in 2020 would look like: [(2020, 1), (2020, 7), (2021, 1), (2021, 7)]. If None is provided, then the CapEx date will be the same as the start of the installation. Defaults to None.
turbine_capex_date (tuple[int, int] | list[tuple[int, int]] | None, optional) -- The date(s) where the ORBIT turbine CapEx costs should be applied as a tuple of year and month, for instance: (2020, 1) for January 2020. Alternatively multiple dates can be set, which evenly divides the cost over all the dates, by providing a list of year and month combinations, for instance, a semi-annual 2 year cost starting in 2020 would look like: [(2020, 1), (2020, 7), (2021, 1), (2021, 7)]. If None is provided, then the CapEx date will be the same as the start of the installation. Defaults to None.
offtake_price (int | float | None, optional) -- The price paid for the energy produced, by default None.
breakdown (bool, optional) -- If True, all the CapEx categories will be provided as a column, in addition to the OpEx and Revenue columns, and the total cost in "cash_flow", othwerwise, only the "cash_flow" column will be provided. Defaults to False.

Returns:

pd.DataFrame -- Returns the pandas DataFrame of the cashflow with a fixed monthly or annual interval, or a project total for the desired categories.

Raises:

ValueError -- Raised if frequency is not one of: "project", "annual", "month-year".
TypeError -- Raised if a valid starting date can't be found for the installation.

npv(frequency='project', discount_rate=None, offtake_price=None, cash_flow=None, **kwargs)[source]#

Calculates the net present value of the windfarm at a project, annual, or monthly resolution given a base discount rate and offtake price. :rtype: DataFrame

Note

NPV is implemented via https://numpy.org/numpy-financial/latest/npv.html#numpy_financial.npv.

Parameters:

frequency (str) -- One of "project", "annual", "monthly", or "month-year".
discount_rate (float, optional) -- The rate of return that could be earned on alternative investments. Defaults to None.
offtake_price (float, optional) -- Price of energy, per MWh. Defaults to None.
cash_flow (pd.DataFrame, optional) -- A modified cash flow DataFrame for custom workflows. Must have the "cash_flow" column with consistent time steps (monthly, annually, etc.). Defaults to None.
kwargs (dict, optional) -- See cash_flow() for details on starting date options.

Returns:

pd.DataFrame -- The project net prsent value at the desired time resolution.

Return type:

DataFrame

irr(offtake_price=None, finance_rate=None, reinvestment_rate=None, cash_flow=None, **kwargs)[source]#

Calculates the Internal Rate of Return using the ORBIT CapEx as the initial investment in conjunction with the WAVES monthly cash flows. :rtype: float

Note

This method allows for the caluclation of the modified internal rate of return through https://numpy.org/numpy-financial/latest/mirr.html#numpy_financial.mirr if both the finance_rate and the reinvestment_rate are provided.

Parameters:

offtake_price (float, optional) -- Price of energy, per MWh. Defaults to None.
finance_rate (float, optional) -- Interest rate paid on the cash flows. Only used if reinvestment_rate is also provided. Defaults to None.
reinvestment_rate (float, optional) -- Interest rate received on the cash flows upon reinvestment. Only used if finance_rate is also provided.
cash_flow (pd.DataFrame, optional) -- A modified cash flow DataFrame for custom workflows. Must have the "cash_flow" column with consistent time steps (monthly, annually, etc.). Defaults to None.
kwargs (dict, optional) -- See cash_flow() for details on starting date options.

Returns:

float -- The IRR.

Return type:

float

lcoe(fixed_charge_rate=None, capex=None, opex=None, aep=None)[source]#

Calculates the levelized cost of energy (LCOE) as the following: LCOE = (CapEx * FCR + OpEx) / AEP, in $/MWh.

Return type:

float

Parameters:

fixed_charge_rate (float, optional) -- Revenue per amount of investment required to cover the investment cost. Required if no value was provided in the Project configuration. Defaults to None
capex (float, optional) -- Custom CapEx value, in $/kW. Defaults to None.
opex (float, optional) -- Custom OpEx value, in $/kW/year. Defaults to None.
aep (float, optional) -- Custom AEP value, in MWh/MW/year. Defaults to None.

Returns:

float -- The levelized cost of energy.

Raises:

ValueError -- Raised if the input to units is not one of "kw", "mw", or "gw".

generate_report(metrics_configuration=None, simulation_name=None)[source]#

Generates a single row dataframe of all the desired resulting metrics from the project. :rtype: DataFrame

Note

This assumes all results will be a single number, and not a Pandas DataFrame

Parameters:

metrics_dict (dict[str, dict], optional) --
The dictionary of dictionaries containing the following key, value pair pattern:
```
{
    "Descriptive Name (units)": {
        "metric": "metric_method_name",
        "kwargs": {"kwarg1": "kwarg_value_1"}  # Exclude if not needed
    }
}
```
For metrics that have no keyword arguments, or where the default parameter values are desired, either an empty dictionary or no dictionary input for "kwargs" is allowed. If no input is provided, then report_config will be used to populate
simulation_name (str) -- The name that should be given to the resulting index.
metrics_configuration (dict[str, dict] | None)

Returns:

pd.DataFrame -- A pandas.DataFrame containing all of the provided outputs defined in metrics_dict.

Raises:

ValueError -- Raised if any of the keys of metrics_dict aren't implemented methods.

Return type:

DataFrame

generate_report_lcoe_breakdown()[source]#

Generates a dataframe containing the detailed breakdown of LCOE (Levelized Cost of Energy) metrics for the project, which is used to produce LCOE waterfall charts and CapEx donut charts in the Cost of Wind Energy Review. The breakdown includes the contributions of each CapEx and OpEx component (from ORBIT and WOMBAT) to the LCOE in $/MWh.

This function calculates the LCOE by considering both CapEx (from ORBIT) and OpEx (from WOMBAT),and incorporates the fixed charge rate (FCR) and net annual energy production (net AEP) into the computation for each component.

Return type:

DataFrame

Returns:

pd.DataFrame --

A DataFrame containing the detailed LCOE breakdown with the following columns:

"Component": The name of the project component (e.g., "Turbine", "Balance of System CapEx", "OpEx").
"Category": The category of the component (e.g., "Turbine", "Balance of System CapEx", "Financial CapEx", "OpEx").
"Value ($/kW)": The value of the component in $/kW.
"Fixed charge rate (FCR) (real)": The real fixed charge rate (FCR) applied to the component.
"Value ($/kW-yr)": The value of the component in $/kW-yr, after applying the FCR.
"Net AEP (MWh/kW/yr)": The net annual energy production (AEP) in MWh/kW/yr.
"Value ($/MWh)": The value of the component in $/MWh, calculated by dividing the $/kW-yr value by the net AEP.

Notes

CapEx components are categorized into "Turbine", "Balance of System CapEx", and "Financial
CapEx".
OpEx components are derived from WOMBAT's OpEx metrics, categorized as "OpEx".
The LCOE is calculated by considering both CapEx and OpEx components, and adjusting for net AEP and FCR.
Rows with a value of 0 in the "Value ($/MWh)" column are removed to avoid clutter in annual reporting charts.

generate_report_project_details()[source]#

Generates a DataFrame containing detailed project information, following the format from the table at slide 64 in the Cost of Wind Energy Review: 2024 Edition (https://www.nrel.gov/docs/fy25osti/91775.pdf).

This function collects various project parameters such as turbine specifications, wind speed data,energy capture, and efficiency metrics, and formats them into a comprehensive report.

Return type:

DataFrame

Returns:

pd.DataFrame -- A DataFrame containing the project details, where each row corresponds to a specific assumption and its associated unit and value. The columns include:

"Assumption": Describes the specific project assumption (e.g., "Wind plant capacity","Turbine rating").

"Units": The unit of measurement for each assumption (e.g., "MW", "Number", "m/s").

"Value": The actual value for each assumption, computed based on the project's
configurations and available data.

determine_substructure_type()[source]#

Determine the substructure type based on the ORBIT configuration file.

This function scans the "design_phases" section of the ORBIT configuration file to identify the substructure type used in the project. The substructure types considered are "Monopile", "SemiSubmersible", "Jacket", and "Spar". The function returns the substructure type as a string if found in the design phases, or "Unknown" if no substructure type is identified.

Returns:: str -- The substructure type as one of the following: "Monopile", "SemiSubmersible", "Jacket", "Spar", or "Unknown" if no match is found.

Notes

The search is case-insensitive and looks for the substructure types as substrings within the design phase names.
If no substructure type is found after checking all phases, the function will return "Unknown".

cut_in_windspeed()[source]#

Determine the cut-in wind speed for the turbine based on the power-thrust table.

This function extracts the power and wind speed data from the turbine definitions in the FLORIS model and identifies the cut-in wind speed. The cut-in wind speed is the wind speed at which the turbine begins to produce power after zero power is achieved. The function returns the cut-in wind speed or None if no valid value can be determined.

Returns:: float | None -- The wind speed (in m/s) at which the turbine starts producing power, or None if no valid cut-in wind speed can be found.

Notes

The cut-in wind speed is identified as the wind speed immediately following the last wind speed with zero power that is lower than the wind speed at which the turbine produces maximum power.
If no valid zero power wind speeds are found below the maximum power wind speed, None is returned.

cut_out_windspeed()[source]#

Determine the cut-out wind speed for the turbine based on the power-thrust table.

This function extracts the power and wind speed data from the turbine definitions in the FLORIS model and identifies the cut-out wind speed. The cut-out wind speed is the wind speed at which the turbine stops producing power, which occurs when the power drops to zero. The function returns the cut-out wind speed or None if no valid value can be determined.

Returns:: float | None -- The wind speed (in m/s) at which the turbine stops producing power, or None if no valid cut-out wind speed can be found.

Notes

The cut-out wind speed is identified as the wind speed immediately preceding the first wind speed where the turbine generates zero power and the wind speed is greater than the wind speed at which maximum power is produced.
If no valid zero power wind speeds are found above the maximum power wind speed, None is returned.

calculate_wind_speed(height)[source]#

Calculates a new array, series, or value of wind speed at a given height.

Return type:: Series
Parameters:: height (int | float) -- The new height to calculate the wind speed.
Returns:: pd.Series -- The wind speed data at :py:arg:`height`.

average_wind_speed(height)[source]#

Calculates the average wind speed at a specified height.

This method computes the mean wind speed from the weather data at the given height. If the wind speed data for the specified height is not found, and there are not at least two columns of wind speed data, an error is raised.

Parameters:: height (int) -- The height (in meters) at which the average wind speed is to be calculated. The method expects the column in the weather data to be named in the format 'windspeed_{height}m'.
Returns:: float | str -- If the wind speed data for the specified height exists, the method returns the mean wind speed as a float (in meters per second). If the data is not found, it returns a string indicating that the wind speed data is missing.
Raises:: KeyError -- If the column corresponding to the specified height is not present in the weather data.

identify_windspeed_columns_and_heights(df)[source]#

Identifies columns containing wind speed measurements and their respective sensor heights.

Scans the DataFrame to find columns that match the pattern "windspeed_{number}m", where `{number}`corresponds to the sensor height in meters. The function returns a dictionary with the first two matches, where the keys are the column names and the values are the heights in meters.

Parameters:: df (pandas.DataFrame) -- A DataFrame containing wind speed columns. The columns should follow the naming convention"windspeed_{number}m", where {number} represents the sensor height in meters.
Returns:: dict[str, int] -- A dictionary containing the first two columns that match the "windspeed_{number}m" pattern. The keys are the column names (e.g., "windspeed_10m"), and the values are the corresponding sensor heights (e.g., 10).

compute_weibull(height, random_seed=1)[source]#

Fits a Weibull distribution to wind speed data at a specified height.

This function fits a Weibull distribution to the wind speed data at the specified height from the weather data. It assumes that wind speeds are non-negative, so it fixes the location parameter of the Weibull distribution to 0. If the required column for the given height is not present in the weather data, an error message is printed and the function returns a string indicating the missing data.

Parameters:

height (int) -- The height (in meters) at which the wind speed data is collected. The function looks for a column named "windspeed_{height}m" in the weather data.
random_seed (int, optional) -- A random seed for reproducibility. Defaults to 1. This seed is used to initialize the random number generator for the Weibull fitting procedure.

Returns:

float | str -- If the wind speed data is available for the specified height, the function returns the shape parameter of the fitted Weibull distribution. If the necessary column is missing from the weather data, it returns a string indicating the error (e.g., "wind speed at {height}m not provided").

waves.project

Contents

waves.project#