Helpers and Plotting

Helpers and Plotting#

Importing and Converting From Old Versions#

wombat.core.library.load_yaml(path, fname)[source]#

Loads and returns the contents of the YAML file.

Parameters:

  • path (str | Path) -- Path to the file to be loaded.

  • fname (str | Path) -- Name of the file (ending in .yaml or .yml) to be loaded.

Return type:

Any

Returns:

Any -- Whatever content is in the YAML file.

wombat.core.library.create_library_structure(library_path, create_init=False)[source]#

Creates the following library structure at library_path. If library_path does not exist, then the method will fail.

<library_path>/
└── project
    └── config     <- Project-level configuration files
    └── port       <- Port configuration files
    └── plant      <- Wind farm layout files
└── cables       <- Export and Array cable configuration files
└── substations  <- Substation configuration files
└── turbines     <- Turbine configuration and power curve files
└── vessels      <- Land-based and offshore servicing equipment configuration files
└── weather      <- Weather profiles
└── results      <- The analysis log files and any saved output data
Parameters:

  • library_path (str | Path) -- The folder under which the subfolder structure should be created.

  • create_init (bool) -- If True, create "__init__.py" in each of the folders so that python installation processes will register the files, and if False, only create the folders, by default False.

Raises:

FileNotFoundError -- Raised if library_path is not a directory

Return type:

None

wombat.core.library.convert_failure_data(configuration, which, save_name=None, return_dict=False)[source]#

Converts the pre-v0.10 failure configuration data for cable, turbine, substation data in both individual files or consolidated configurations to be in the v0.10+ style.

Parameters:

  • configuration (str | Path | dict) -- The configuration file or dictionary containing failure data.

  • which (str) -- The type of configuration. Muat be one of "cable", "substation", "turbine", or "configuration" where "configuration" is a consolidated simulation configuration file containing any or all of the different types.

  • save_name (str | Path | None, optional) -- The file path and name of where to save the converted configuration, by default None.

  • return_dict (bool, optional) -- Use True to return the converted dictionary, by default False.

Return type:

None | dict

Returns:

None | dict -- If return_dict is True, then dict, otherwise None.

Raises:

  • FileNotFoundError -- Raised if the configuration can't be found.

  • ValueError -- Raised if configuration can't be converted to a dictionary because a dictionary was not passed nor was a valid file path to load.

  • ValueError -- Raised if which received an invalid input.

Plotting#

Provides expoerimental plotting routines to help with simulation diagnostics.

wombat.utilities.plot.plot_farm_layout(windfarm, figure_kwargs=None, plot_kwargs=None, return_fig=False)[source]#

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

Args:
figure_kwargsdict, optional

Customized keyword arguments for matplotlib figure instantiation that will passed as plt.figure(**figure_kwargs). Defaults to {}.

plot_kwargsdict, optional

Customized parameters for networkx.draw() that can will passed as nx.draw(**figure_kwargs). Defaults to with_labels=True, horizontalalignment=right, verticalalignment=bottom, font_weight=bold, font_size=10, and node_color=#E37225.

return_figbool, optional

Whether or not to return the figure and axes objects for further editing and/or saving. Defaults to False.

Return type:

None | tuple[figure, axes]

Returns:

None | tuple[plt.figure, plt.axes]: _description_

Parameters:

  • windfarm (Windfarm)

  • figure_kwargs (dict | None)

  • plot_kwargs (dict | None)

  • return_fig (bool)

wombat.utilities.plot.plot_farm_availability(sim, which='energy', individual_turbines=False, farm_95_CI=False, figure_kwargs=None, plot_kwargs=None, legend_kwargs=None, tick_fontsize=12, label_fontsize=16, return_fig=False)[source]#

Plots a line chart of the monthly availability at the wind farm level.

Parameters:

  • sim (Simulation) -- A Simulation object that has been run.

  • which (str) -- One of "time" or "energy", to indicate the basis for the availability calculation, by default "energy".

  • individual_turbines (bool, optional) -- Indicates if faint gray lines should be added in the background for the availability of each turbine, by default False.

  • farm_95_CI (bool, optional) -- Indicates if the 95% CI area fill should be added in the background.

  • figure_kwargs (dict, optional) -- Custom parameters for plt.figure(), by default figsize=(15, 7) and dpi=300.

  • plot_kwargs (dict, optional) -- Custom parameters to be passed to ax.plot(), by default a label consisting of the simulation name and project-level availability.

  • legend_kwargs (dict, optional) -- Custom parameters to be passed to ax.legend(), by default fontsize=14.

  • tick_fontsize (int, optional) -- The x- and y-axis tick label fontsize, by default 12.

  • label_fontsize (int, optional) -- The x- and y-axis label fontsize, by default 16.

  • return_fig (bool, optional) -- If True, return the figure and Axes object, otherwise don't, by default False.

Return type:

tuple[Figure | Axes] | None

Returns:

tuple[plt.Figure, plt.Axes] | None -- See return_fig for details. _description_

wombat.utilities.plot.plot_operational_levels(sim, figure_kwargs=None, cbar_label_fontsize=14, return_fig=False)[source]#

Plots an hourly view of the operational levels of the wind farm and individual turbines as a heatmap.

Parameters:

  • sim (Simulation) -- A Simulation object that has been run.

  • figure_kwargs (dict, optional) -- Custom settings for plt.figure(), by default figsize=(15, 10) and dpi=300.

  • cbar_label_fontsize (int, optional) -- The default fontsize used in the color bar legend for the axis label, by default 14.

  • return_fig (bool, optional) -- If True, return the figure and Axes object, otherwise don't, by default False.

Returns:

tuple[plt.Figure, plt.Axes] | None -- See return_fig for details.

Logging functions#

General logging methods.

wombat.utilities.logging.setup_logger(logger_name, log_file, level=20, capacity=500)[source]#

Creates the logging infrastructure for a given logging category.

TODO: Figure out how to type check logging.INFO; Callable?

Parameters:

  • logger_name (str) -- Name to assign to the logger.

  • log_file (Path) -- File name and path for where the log data should be saved.

  • level (Any, optional) -- Logging level, by default logging.INFO.

  • capacity (int)

Return type:

None

wombat.utilities.logging.format_events_log_message(simulation_time, env_time, system_id, system_name, part_id, part_name, system_ol, part_ol, agent, action, reason, additional, duration, request_id, location='na', materials_cost=0, hourly_labor_cost=0, salary_labor_cost=0, equipment_cost=0)[source]#

Formats the logging messages into the expected format for logging.

Parameters:

  • simulation_time (datetime64) -- Timestamp within the simulation time.

  • env_time (float) -- Environment simulation time (Environment.now).

  • system_id (str) -- Turbine ID, System.id.

  • system_name (str) -- Turbine name, System.name.

  • part_id (str) -- Subassembly, component, or cable ID, _.id.

  • part_name (str) -- Subassembly, component, or cable name, _.name.

  • system_ol (int | float) -- System operating level, System.operating_level. Use an empty string for n/a.

  • part_ol (int | float) -- Subassembly, component, or cable operating level, _.operating_level. Use an empty string for n/a.

  • agent (str) -- Agent performin the action.

  • action (str) -- Action that was taken.

  • reason (str) -- Reason an action was taken.

  • additional (str) -- Any additional information that needs to be logged.

  • duration (float) -- Length of time the action lasted.

  • request_id (str) -- The RepairRequest.request_id or "na".

  • location (str) -- The location of where the event ocurred: should be one of site, port, enroute, or system, by default "na".

  • materials_cost (int | float, optional) -- Total cost of materials for action, in USD, by default 0.

  • hourly_labor_cost (int | float, optional) -- Total cost of hourly labor for action, in USD, by default 0.

  • salary_labor_cost (int | float, optional) -- Total cost of salaried labor for action, in USD, by default 0.

  • equipment_cost (int | float, optional) -- Total cost of equipment for action, in USD, by default 0.

Return type:

str

Returns:

str -- Formatted message for consistent logging.[summary]

Time Calculations#

General methods for time-based calculations.

wombat.utilities.time.parse_date(value)[source]#

Thin wrapper for dateutil.parser.parse that converts string dates and returns back None or the original value if it's None or a datetime.datetime object, respectively.

Parameters:

value (str | None | datetime.datetime) -- A month/date or month-date formatted string to be converted to a datetime.datetime object, or datetime.datetime object, or None.

Return type:

datetime | None

Returns:

datetime.datetime | None -- A converted datetime.datetime object or None.

wombat.utilities.time.convert_dt_to_hours(diff)[source]#

Convert a datetime.timedelta object to number of hours at the seconds resolution.

Parameters:

diff (datetime.timedelta) -- The difference between two datetime.datetime objects.

Return type:

float

Returns:

float -- Number of hours between to datetime.datetime objects.

wombat.utilities.time.hours_until_future_hour(dt, hour)[source]#

Number of hours until a future hour in the same day for hour <= 24, otherwise, it is the number of hours until a time in the proceeding days.

Parameters:

  • dt (datetime.datetime) -- Focal datetime.

  • hour (int) -- Hour that is later in the day, in 24 hour time.

Return type:

float

Returns:

float -- Number of hours between the two times.

wombat.utilities.time.check_working_hours(env_start, env_end, workday_start, workday_end)[source]#

Checks the working hours of a port or servicing equipment, and overrides a default (-1) to the environment's settings, otherwise returns back the input hours.

Parameters:

  • env_start (int) -- The starting hour for the environment's shift

  • env_end (int) -- The ending hour for the environment's shift

  • workday_start (int) -- The starting hour to be checked.

  • workday_end (int) -- The ending hour to be checked.

Return type:

tuple[int, int]

Returns:

tuple[int, int] -- The starting and ending hour to be applied back to the port or servicing equipment.

wombat.utilities.time.calculate_cost(duration, rate, n_rate=1, daily_rate=False)[source]#

Calculates the equipment cost, or labor cost for either salaried or hourly employees.

Parameters:

  • duration (int | float) -- Length of time, in hours.

  • rate (float) -- The labor or equipment rate, in $USD/hour.

  • n_rate (int) -- Total number of of the rate to be applied, more than one if``rate`` is broken down by number of individual laborers (if rate is a labor rate), by default 1.

  • daily_rate (bool, optional) -- Indicator for if the rate is a daily rate (True), or hourly rate (False), by default False.

Return type:

float

Returns:

float -- The total cost of the labor performed.

Miscellaneous#

Provides various utility functions that don't fit within a common theme.

wombat.utilities.utilities._mean(*args)[source]#

Multiplies two numbers. Used for a reduce operation.

Parameters:

args (int | float) -- The values to compute the mean over

Return type:

float

Returns:

float -- The average of the values provided

wombat.utilities.utilities.create_variable_from_string(string)[source]#

Creates a valid Python variable style string from a passed string.

Parameters:

string (str) -- The string to convert into a Python-friendly variable name.

Return type:

str

Returns:

str -- A Python-valid variable name.

Examples

>>> example_string = "*Electrical!*_ _System$*_"
>>> print(create_variable_from_string(example_string))
'electrical_system'
wombat.utilities.utilities.IEC_power_curve(windspeed_column, power_column, bin_width=0.5, windspeed_start=0.0, windspeed_end=30.0)[source]#

Direct copyfrom OpenOA: NREL/OpenOA Use IEC 61400-12-1-2 method for creating wind-speed binned power curve.

Parameters:

  • windspeed_column (np.ndarray | pandas.Series) -- The power curve's windspeed values, in m/s.

  • power_column (np.ndarray | pandas.Series) -- The power curve's output power values, in kW.

  • bin_width (float) -- Width of windspeed bin, default is 0.5 m/s according to standard, by default 0.5.

  • windspeed_start (float) -- Left edge of first windspeed bin, where all proceeding values will be 0.0, by default 0.0.

  • windspeed_end (float) -- Right edge of last windspeed bin, where all following values will be 0.0, by default 30.0.

Return type:

Callable

Returns:

Callable

Python function of the power curve, of type (Array[float] -> Array[float]), that maps input windspeed value(s) to ouptut power value(s).

wombat.utilities.utilities.calculate_windfarm_operational_level(operations, turbine_id, turbine_weights, substation_turbine_map)[source]#

Calculates the overall wind farm operational level, accounting for substation downtime by multiplying the sum of all downstream turbine operational levels by the substation's operational level.

Parameters:

  • operations (pd.DataFrame) -- The turbine and substation operational level DataFrame.

  • turbine_id (np.ndarray | list[str]) -- The turbine ids that match Windfarm.turbine_id.

  • turbine_weights (pd.DataFrame) -- The turbine weights, coming from Windfarm.turbine_weights.

  • substation_turbine_map (dict[str, dict[str, np.ndarray]]) -- The Windfarm.substation_turbine_map.

Return type:

DataFrame

Notes

This is a crude cap on the operations, and so a smarter way of capping the availability should be added in the future.

Return type:

DataFrame

Returns:

pd.DataFrame -- The aggregate wind farm operational level.

Parameters:

  • operations (DataFrame)

  • turbine_id (ndarray | list[str])

  • turbine_weights (DataFrame)

  • substation_turbine_map (dict[str, dict[str, ndarray]])

Contents