API Reference

Warning

This API documentation is under development and may change

This section provides detailed documentation for the BC Combined Modelling API.

Core Components

The BC Combined Modelling framework consists of several main modules:

Main Workflow Controller

Command Line Interface

Data Linking Utilities

class bc_combined_modelling.clews_to_pypsa.FutureTechInvestments(year, scenario_name: str, storage_algorithm: str = 'Kotzur', timeslices: int = 8, solver_name: str = 'gurobi')

Bases: object

create_mapping(future_techs_resource_options: dict, resource_options: DataFrame, output_path: str | Path)

create_mapping_nuclear(future_techs_resource_options: dict, resource_options: DataFrame, output_path: str | Path)

get_data_paths()

get_existing_techs(techs)

get_future_techs(techs: list, no_of_existing_techs: int)

get_investments()

get_scenario_investment(timeslices)

Utility Functions

bc_combined_modelling.utils.add_generic_columns(assets, gen_generic, gen_type)

This functions adds generic columns of costs and efficiencies. This is needed before creating the .csv for OSeMOSYS via Otoole. # MODIFIED 2024-10-01 for CODERS update

bc_combined_modelling.utils.add_generic_columns_tpp(assets, gen_generic)

This functions adds generic columns of costs and efficiencies. This is needed before creating the .csv for OSeMOSYS via Otoole.

bc_combined_modelling.utils.convert_cid_2_aid(cid, old_aid)

This creates an asset id (aid) based on the component id (cid). Common Example:

cid -> BC_ZBL03_GEN old_aid -> BC_ZBL_GSS new_aid -> BC_ZBL_GSS

Example: cid -> BC_BR0101_GEN old_aid -> BC_BR1_DFS new_aid -> BC_BR1_DFS Example: cid -> BC_BR0102_GEN old_aid -> BC_BR2_GSS new_aid -> BC_BR2_GSS

bc_combined_modelling.utils.create_era5_cutout(bounds, cfg)

This function creates a cutout based on data for era5.

bc_combined_modelling.utils.create_folder(folder)

This functions creates a folder if not already created. If the folder is already created it takes no action folder: Path + folder name.

bc_combined_modelling.utils.create_standard_gen_bus_map(buses)

This function accepts a list a buses and returns a mapping from the buses to the lowest voltage bus for each unique node code. The underlying assumption used in selecting a bus to connect a generator to is that generators are connected the lowest voltage bus at their given node location. Example: Buses = ["230_ABN_GSS", "138_ABN_GSS","500_MCA_GSS", "63_MCA_GSS"] -> bus_dict = {ABN_GSS:138, MCA_GSS:63}

bc_combined_modelling.utils.find_project_root(marker='bc_combined_modelling', start_dir: str = None) → Path

Traverse upwards to find the root directory containing a specific folder or file.

Parameters:

• marker (str) -- The folder or file name to identify the project root.

• start_dir (str) -- The starting directory for the search. Defaults to current directory.

Returns:

The path to the project root.

Return type:

Path

Raises:

FileNotFoundError -- If the marker is not found.

bc_combined_modelling.utils.fix_coders_update(data, col_to_correct, codes)

Modified 2024-10-01: CODERS updates to buses creating mismatches in string match incorrectly. data: col_to_correct: column name containing the values in which we plan to map to corrections for CODERS. codes: cords to map from an old string to a new one, example of codes... codes = {'BC_BR0101_GEN':'BC_BR101_GEN','BC_BR0102_GEN':'BC_BR102_GEN','BC_BR0103_GEN':'BC_BR103_GEN','BC_BR0104_GEN':'BC_BR104_GEN',

'BC_BR0201_GEN':'BC_BR201_GEN','BC_BR0202_GEN':'BC_BR202_GEN','BC_BR0203_GEN':'BC_BR203_GEN','BC_BR0204_GEN':'BC_BR204_GEN'}

bc_combined_modelling.utils.fix_df_ts_index(df: DataFrame, start_date: str = '2021-01-01 00:00:00', end_date: str = '2021-12-31 23:00:00')

This function hardcodes and fixes the timeseries to be an 8760 timeseries beginning in 2021-01-01.

bc_combined_modelling.utils.get_bounds(polygon_list)

This function takes in a list of polygons and returns the maximum bounds for them.

bc_combined_modelling.utils.get_cutout_path(cfg)

This function return the unique name based on the region and start/end year for a cutout. return: file path + name for the cutout described by selections in the cutout configuration.

bc_combined_modelling.utils.get_gen_bus(node_code, bus_dict)

This function returns the correct standardized electric bus for a generator. Example: node_code = "BC_ABS_GSS" bus_dict = {"ABS_GSS":230, "MCA_GSS":63} return -> "230_ABS_GSS"

bc_combined_modelling.utils.get_multi_gen_override()

bc_combined_modelling.utils.get_multi_link_override()

Gets the multi-link override. Needed for cascaded hydroelectric.

bc_combined_modelling.utils.get_region_polygon(geometry)

This function finds a bounding box of the region and creates a polygon for it. Returns a polygon of the regions max/min bounds in terms of lats and lons.

bc_combined_modelling.utils.load_config(config_file)

This function loads the configuration file for PyPSA_BC config_file: Path + filename of the configuration file. (i.e. ../config/config.yaml)

bc_combined_modelling.utils.parse_data_value(value)

Attempts to convert strings that represent lists (e.g. '[100, 200, 300]') into actual lists. If not possible, returns the value as-is.

bc_combined_modelling.utils.print_update(level: int = None, message: str = '--', alert: bool | None = False)

bc_combined_modelling.utils.read_pickle(filepath)

Read a json file based on a dictionary.

bc_combined_modelling.utils.set_root(current_dir=PosixPath('/local-scratch/localhome/mei3/eliasinul/work/BC_Combined_Modelling'))

bc_combined_modelling.utils.setup_environment(marker='bc_combined_modelling', start_dir: str = None)

Configure the environment for running scripts or notebooks from any directory.

Parameters:

• marker (str) -- The folder or file name to identify the project root.

• start_dir (str) -- The starting directory for the search. Defaults to current directory.

bc_combined_modelling.utils.write_pickle(data_dict, filepath)

Write a pickle file based on a dictionary.

Attributes Parser

class bc_combined_modelling.attributes_parser.AttributesParser(combined_model_config_path: str | Path = 'config/config.yaml')

Bases: object

This is the parent class that will extract the core attributes from the User Config file.

## Remarks:

• Handles the clews_builder.yaml file creation and updates under-the hood.

• The clews_builder.yaml file if not exists will mirror the skeleton file sourced from 'models/BC_Nexus/config/clews_builder_skeleton.yaml'

property bcnexus_scenarios: dict

combined_model_config_path: str | Path = 'config/config.yaml'

get_bcnexus_scenario_results_path(scenario: str, storage_algorithm: str)

get_case_input_csvs_path(storage_algorithm: str)

get_data_paths()

property linking_tool_results_path

static load_config(config_file_path)

Loads the yaml file as dictionary and extracts the attributes to pass on child classes.

property pypsa_results_path

Note

If the above documentation doesn't render properly, this indicates import issues with dependencies. The modules provide the following main functionality:

• bc_combined_modelling: Main workflow orchestration and combined analysis

• cli: Command-line interface for running analyses and data conversion

• clews_to_pypsa: Data conversion between BC_Nexus/CLEWs and PyPSA formats

• utils: General utility functions for data processing and file handling

• attributes_parser: Configuration file parsing and validation

Quick Reference

Main Classes

Class	Description
CombinedWorkflow	Main orchestrator for integrated analysis
CLEWSPyPSALinker	Data conversion between modeling frameworks
ConfigManager	Configuration file management
ResultsAnalyzer	Post-processing and analysis of results

Key Functions

Function	Description
run_combined_analysis()	Execute full integrated workflow
convert_clews_to_pypsa()	Convert BC_Nexus outputs to PyPSA inputs
validate_configuration()	Validate configuration files
process_results()	Process and visualize results

Configuration Structure

The framework uses YAML configuration files with the following main sections:

project:
  name: str
  region: str
  base_year: int

bc_nexus:
  model_path: str
  scenarios: list
  
pypsa_bc:
  network_file: str
  solver: str
  
linking:
  temporal_resolution: str
  spatial_aggregation: str

---

For detailed examples, see the Getting Started Guide and example notebooks.