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_stack_current(power, p1, p2, p3, p4, p5)[source]#

Convert power produced, in kW to current, in amperes (I) using the efficiency curve from the H2Integrage PEM electrolysis model.

\[i_{stack} = p1 * power^{3} + p2 * power^{2} + p3 * power + p4 * power^{1/2} + p5\]
Parameters:

  • power (np.ndarray | pd.Series) -- Power produced, in kW.

  • p1 (int | float) -- First coefficient.

  • p2 (int | float) -- Second coefficient.

  • p3 (int | float) -- Third coefficient

  • p4 (int | float) -- Fourth coefficient.

  • p5 (int | float) -- Intercept.

Return type:

ndarray | Series

Returns:

np.ndarray | pd.Series -- Converted current from the farm's power production.

wombat.utilities.utilities.calculate_hydrogen_production(rated_capacity, FE=0.9999999, n_cells=135, turndown_ratio=0.1, *, efficiency_rate=None, p1=None, p2=None, p3=None, p4=None, p5=None)[source]#

Create the hydrogen production curve for an electrolyzer. One of efficiency_rate or a complete set of polynomial values (p1, p2, p3, p4, and p5) for the power to current conversion must be provided.

kWh are converted to current using the following efficiency formulation when the polynomial inputs are all provided, and the efficiency_rate is nonzero. .. math:

i_{stack} = p1 * power^{3} + p2 * power^{2} + p3 * power + p4 * power^{1/2} + p5
Parameters:

  • rated_capacity (float) -- Rated maximum input power of the electrolyzer, in kW.

  • FE (float, optional) -- Faradic efficiency, by default 0.9999999.

  • n_cells (int, optional) -- Number of cells per 1 MW stack, by default 135.

  • turndown_ratio (float, optional) -- Minimum input power as a ratio of the rated capacity, by default 0.1.

  • efficiency_rate (float, optional) -- Energy efficiency in kWh per kg H2. Required if p1 through ``p5 are not provided.

  • p1 (int | float | None) -- First coefficient of the efficiency polynomial curve. Required if efficiency_rate is not provided, by default None.

  • p2 (int | float | None) -- Second coefficient of the efficiency polynomial curve. Required if efficiency_rate is not provided, by default None.

  • p3 (int | float | None) -- Third coefficient of the efficiency polynomial curve. Required if efficiency_rate is not provided, by default None.

  • p4 (int | float | None) -- Fourth coefficient of the efficiency polynomial curve. Required if efficiency_rate is not provided, by default None.

  • p5 (int | float | None) -- Intercept of the efficiency polynomial curve. Required if efficiency_rate is not provided, by default None.

Return type:

Callable

Returns:

Callable -- Function to calculate H₂ production (kg/hr) from power input (kW).

Raises:

  • ValueError -- Raised when turndown_ratio is outside the range [0, 1].

  • ValueError -- Raised when efficiency_rate is provided and less than or equal to 0.

  • ValueError -- Raised when neither the efficiency_rate nor polynomial values ( p1 through p5) are provided.

  • ValueError -- Raised both the efficiency_rate and polynomial values ( p1 through p5) are provided.

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