cerf package

Submodules

cerf.compete module

class cerf.compete.Competition(target_region_name, settings_dict, technology_dict, technology_order, expansion_dict, lmp_dict, generation_dict, operating_cost_dict, nov_dict, ic_dict, nlc_mask, zones_arr, xcoords, ycoords, indices_flat, randomize=True, seed_value=0, verbose=False)

Bases: object

Technology competition algorithm for CERF.

Grid cell level net locational cost (NLC) per technology and an electricity technology capacity expansion plan are used to compete technologies against each other to see which will win the grid cell. The technology that wins the grid cell is then sited until no further winning cells exist. Once sited, the location of the winning technology’s grid cell, along with its buffer, are no longer available for siting. The competition array is recalculated after all technologies have passed through an iteration. This process is repeated until there are either no cells left to site or there are no more power plants left to satisfy the expansion plan for any technology. For technologies that have the same NLC value in multiple grid cells that win the competition, random selection is available by default. If the user wishes to have the outcomes be repeatable, the randomizer can be set to False and a random seed set.

Parameters

• expansion_plan (dict) – Dictionary of {tech_id: number_of_sites, …}

• nlc_mask (ndarray) – 3D masked array of [tech_id, x, y] for Net Locational Costs. Each technology has been masked with its suitability data, so only grid cells that are suitable have an NLC per tech. The 0 index position is a default dimension which is chosen if no technologies are able to compete.

• technology_dict (dict) – A technology dictionary containing at a minimum {tech_id: buffer_in_km, …}

• randomize (bool) – Choose to make randomization of site selection where NLC is the same in multiple grid cells for a single technology random. If False, the seed_value will be used as a way to reproduce the exact siting. Default: True

• seed_value (int) – Value for the see if randomize is False.

• verbose (bool) – Log out siting information. Default False.

compete()

log_outcome()

Log a warning sites that were not able to be sited.

cerf.install_supplement module

class cerf.install_supplement.InstallSupplement(data_dir=None)

Bases: object

Download and unpack example data supplement from Zenodo that matches the current installed cerf distribution.

Parameters

data_dir (str) – Optional. Full path to the directory you wish to store the data in. Default is to install it in data directory of the package.

DATA_VERSION_URLS = {'2.0.0': 'https://zenodo.org/record/5218436/files/cerf_package_data.zip?download=1', '2.0.1': 'https://zenodo.org/record/5218436/files/cerf_package_data.zip?download=1', '2.0.2': 'https://zenodo.org/record/5218436/files/cerf_package_data.zip?download=1', '2.0.3': 'https://zenodo.org/record/5218436/files/cerf_package_data.zip?download=1', '2.0.4': 'https://zenodo.org/record/5247690/files/cerf_package_data.zip?download=1', '2.0.5': 'https://zenodo.org/record/5247690/files/cerf_package_data.zip?download=1', '2.0.6': 'https://zenodo.org/record/5247690/files/cerf_package_data.zip?download=1', '2.0.7': 'https://zenodo.org/record/5514010/files/cerf_package_data.zip?download=1', '2.0.8': 'https://zenodo.org/record/5514010/files/cerf_package_data.zip?download=1', '2.0.9': 'https://zenodo.org/record/5514010/files/cerf_package_data.zip?download=1', '2.1.0': 'https://zenodo.org/record/5514010/files/cerf_package_data.zip?download=1', '2.1.1': 'https://zenodo.org/record/5514010/files/cerf_package_data.zip?download=1', '2.2.0': 'https://zenodo.org/record/6998151/files/cerf_package_data.zip?download=1', '2.2.1': 'https://zenodo.org/record/6998151/files/cerf_package_data.zip?download=1', '2.3': 'https://zenodo.org/record/6998151/files/cerf_package_data.zip?download=1', '2.3.1': 'https://zenodo.org/record/6998151/files/cerf_package_data.zip?download=1', '2.3.2': 'https://zenodo.org/record/6998151/files/cerf_package_data.zip?download=1'}

fetch_zenodo()

Download and unpack the Zenodo example data supplement for the current cerf distribution.

cerf.install_supplement.install_package_data(data_dir=None)

Download and unpack example data supplement from Zenodo that matches the current installed cerf distribution.

Parameters

data_dir (str) – Optional. Full path to the directory you wish to store the data in. Default is to install it in data directory of the package.

cerf.interconnect module

class cerf.interconnect.Interconnection(template_array, technology_dict, technology_order, region_raster_file, region_abbrev_to_name_file, region_name_to_id_file, substation_file=None, transmission_costs_dict=None, transmission_costs_file=None, pipeline_costs_dict=None, pipeline_costs_file=None, pipeline_file=None, output_rasterized_file=False, output_dist_file=False, output_alloc_file=False, output_cost_file=False, interconnection_cost_file=None, output_dir=None)

Bases: object

Calculate interconnection costs per grid cell in $ / yr using:

Interconnection Cost ($ / yr) = Distance to nearest suitable transmission line (km) *

Electric grid interconnection captial cost (thous$ / km) * Annuity factor + (if gas-fired technology) Distance to nearest suitable gas pipeline (km) * Gas interconnection captial cost (thous$ / km) * Annuity factor

where, Annuity factor is (d(1 + d)**n) / ((1 + d)**n - 1) where, d = real annual discount rate (%), n = asset lifetime (years)

Parameters

• technology_dict (dict) – Dictionary containing technology specific information from the config file

• technology_order (list) – Order of technologies to process

• region_raster_file (str) – Full path with file name and extension to the region raster file that assigns a region ID to each raster grid cell

• region_abbrev_to_name_file (str) – Full path with file name and extension to the region abbreviation to name YAML reference file

• region_name_to_id_file (str) – Full path with file name and extension to the region name to ID YAML reference file

• substation_file (str) – Full path with file name and extension to the input substations shapefile. If None, CERF will use the default data stored in the package.

• transmission_costs_dict (dict) – A dictionary containing the cost of connection per km to a substation having a certain minimum voltage range. Default is to load from the CERF data file ‘costs_per_kv_substation.yml’ by specifying ‘None’

• transmission_costs_file (str) – A YAML file containing the cost of connection per km to a substation having a certain minimum voltage range. Default is to load from the CERF data file ‘costs_per_kv_substation.yml’ by specifying ‘None’

• pipeline_costs_dict (dict) – A dictionary containing the cost of connection per km to a gas pipeline. Default is to load from the CERF data file ‘costs_gas_pipeline.yml’ by specifying ‘None’

• pipeline_costs_file (str) – A YAML file containing the cost of connection per km to a gas pipeline. Default is to load from the CERF data file ‘costs_gas_pipeline.yml’ by specifying ‘None’

• pipeline_file (str) – Full path with file name and extension to the input pipelines shapefile. If None, CERF will use the default data stored in the package.

• output_rasterized_file (bool) – Write distance raster; if True, set ‘output_dir’ value

• output_dist_file (bool) – Write distance raster; if True, set ‘output_dir’ value

• output_alloc_file (bool) – Write allocation file; if True, set ‘output_dir’ value

• output_cost_file (bool) – Write cost file; if True, set ‘output_dir’ value

• interconnection_cost_file (str) – Full path with file name and extension to a preprocessed interconnection cost NPY file that has been previously written. If None, IC will be calculated.

• output_dir (str) – Full path to a directory to write outputs to if desired

static calc_annuity_factor(discount_rate, lifetime_yrs)

Calculate annuity factor.

generate_interconnection_costs_array()

Calculate the costs of interconnection for each technology.

get_pipeline_costs()

Get the costs of gas pipeline interconnection per kilometer.

process_pipelines()

Select natural gas pipelines data that have a length greater than 0.

Returns

A geodataframe containing the target pipelines

process_substations()

Process input substations from shapefile.

transmission_to_cost_raster(setting)

Create a cost per grid cell in $/km from the input GeoDataFrame of transmission infrastructure having a cost designation field as ‘_rval_’

Parameters

setting (str) – Either ‘substations’ or ‘pipelines’

Returns

Array of transmission interconnection cost per grid cell

cerf.interconnect.preprocess_eia_natural_gas_pipelines(pipeline_file, output_file)

Select natural gas pipelines from EIA data that have a status of operating and a length greater than 0.

Parameters

• pipeline_file (str) – Full path with filename and extension to the input EIA pipeline shapefile

• output_file (str) – Full path with filename and extension to the output shapefile

Returns

A geodataframe containing the target pipelines

cerf.interconnect.preprocess_hifld_substations(substation_file, output_file=None)

Select substations from HIFLD data that are within the CONUS and either in service or under construction and having a minimum voltage rating >= 0. A field used to rasterize (‘_rval_’) is also added containing the cost of connection in thous$/km for each substation.

This data is assumed to have the following fields: [‘TYPE’, ‘STATE’, ‘STATUS’].

Parameters

• substation_file (str) – Full path with filename and extension to the input HIFLD substation shapefile

• output_file (str) – Full path with filename and extension to the output shapefile

Returns

A geodataframe containing the target substations

cerf.lmp module

class cerf.lmp.LocationalMarginalPricing(lmp_zone_dict, technology_dict, technology_order, zones_arr)

Bases: object

Create a 3D array of locational marginal pricing per technology by capacity factor.

Locational Marginal Pricing (LMP) represents the cost of making and delivering electricity over an interconnected network of service nodes. LMPs are delivered on an hourly basis (8760 hours for the year) and help us to understand aspects of generation and congestion costs relative to the supply and demand of electricity when considering existing transmission infrastructure. LMPs are a also driven by factors such as the cost of fuel which cerf also takes into account when calculating a power plants Net Operating Value. When working with a scenario-driven grid operations model to evaluate the future evolution of the electricity system, cerf can ingest LMPs, return the sited generation per service area for the time step, and then continue this iteration through all future years to provide a harmonized view how the electricity system may respond to stressors in the future.

Parameters

• lmp_zone_dict (dict) – A dictionary containing lmp related settings from the config file

• technology_dict (dict) – A dictionary containing technology related settings from the config file

• technology_order – A list of technologies in the order by which they should be processed

• zones_arr – An array containing the lmp zones per grid cell

static get_cf_bin(capacity_factor_fraction)

Get the correct start and through index values to average over for calculating LMP.

get_lmp()

Create LMP array for the current technology.

Returns

3D numpy array of LMP where [tech_id, x, y]

cerf.lmp.generate_random_lmp_dataframe(n_zones=57, low_value=10, mid_value=300, high_value=500, n_samples=5000)

Generate a random dataframe of hourly 8760 LMP values per lmp zone. Let high value LMPs only be used for 15 percent of the data. :param n_zones: Number of zones to process :param low_value: Desired minimum value of MWh :param mid_value: Desired mid value of MWh to split the 85-15 split to :param high_value: Desired max value of MWh :param n_samples: Number of intervals to split the min, max choices by :return: Data frame of LMPs per zone

cerf.logger module

Logger for CERF model.

Copyright (c) 2018, Battelle Memorial Institute

Open source under license BSD 2-Clause - see LICENSE and DISCLAIMER

@author: Chris R. Vernon (chris.vernon@pnnl.gov)

class cerf.logger.Logger

Bases: object

Initialize project-wide logger. The logger outputs to both stdout and a file.

LOG_FORMAT_STRING = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'

static close_logger()

Shutdown logger.

console_handler(log_level)

Construct console handler.

file_handler(log_level)

Construct file handler.

initialize_logger()

Initialize logger to stdout and file.

property log_format

Generate log formatter.

property logger

Initialize logger as level info.

cerf.model module

Model interface for CERF

@author Chris R. vernon @email chris.vernon@pnnl.gov

License: BSD 2-Clause, see LICENSE and DISCLAIMER files

class cerf.model.Model(config_file=None, config_dict={}, initialize_site_data=None, log_level='info')

Bases: cerf.read_config.ReadConfig

Model wrapper for CERF.

Parameters

• config_file (str) – Full path with file name and extension to the input config.yml file

• config_dict (dict) – Optional instead of config_file. Configuration dictionary.

• initialize_site_data –

  None if no initialization is required, otherwise either a CSV file or Pandas DataFrame of siting data bearing the following required fields:

  xcoord: the X coordinate of the site in meters in USA_Contiguous_Albers_Equal_Area_Conic (EPSG: 102003)

  ycoord: the Y coordinate of the site in meters in USA_Contiguous_Albers_Equal_Area_Conic (EPSG: 102003)

  retirement_year: the year (int four digit, e.g., 2050) that the power plant is to be decommissioned

  buffer_in_km: the buffer around the site to apply in kilometers

• log_level (str) – Log level. Options are ‘info’ and ‘debug’. Default ‘info’

config_file: str

run_single_region(target_region_name, write_output=True)

run a single region.

stage()

run model.

cerf.nov module

class cerf.nov.NetOperationalValue(discount_rate, lifetime_yrs, unit_size_mw, capacity_factor_fraction, variable_om_esc_rate_fraction, fuel_price_esc_rate_fraction, carbon_tax_esc_rate_fraction, variable_om_usd_per_mwh, heat_rate_btu_per_kWh, fuel_price_usd_per_mmbtu, carbon_tax_usd_per_ton, carbon_capture_rate_fraction, fuel_co2_content_tons_per_btu, lmp_arr, target_year, consider_leap_year=False)

Bases: object

Calculate Net Operational Value (NOV) in ($ / yr) per grid cell for all technologies.

Parameters

• discount_rate (float) – The time value of money in real terms. Units: fraction

• lifetime_yrs (int) – Years of the expected technology plant lifetime_yrs. Units: years

• unit_size_mw (int) – The size of the expected power plant. Units: megawatt

• capacity_factor_fraction (float) – Capacity factor defined as average annual power generated divided by the potential output if the plant operated at its rated capacity for a year. Units: fraction

• variable_om_esc_rate_fraction (float) – Escalation rate of variable cost. Units: fraction

• fuel_price_esc_rate_fraction (float) – Escalation rate of fuel. Units: fraction

• carbon_tax_esc_rate_fraction (float) – Escalation rate of carbon. Units: fraction

• variable_om_usd_per_mwh (float) – Variable operation and maintenance costs of yearly capacity use. Units: $/MWh

• heat_rate_btu_per_kWh (float) – Amount of energy used by a power plant to generate one kilowatt-hour of electricity. Units: Btu/kWh

• fuel_price_usd_per_mmbtu (float) – Cost of fuel per unit. Units: $/MMBtu

• carbon_tax_usd_per_ton (float) – The fee imposed on the burning of carbon-based fuels. Units: $/ton

• carbon_capture_rate_fraction (float) – Rate of carbon capture. Units: fraction

• fuel_co2_content_tons_per_btu (float) – CO2 content of the fuel and the heat rate of the technology. Units: tons/Btu

• lmp_arr (ndarray) – Locational Marginal Price (LMP) per grid cell for each technology in a multi-dimensional array where the shape is [tech_id, xcoord, ycoord]. Units: $/MWh

• target_year (int) – Target year of the simulation as a four digit integer (e.g., 2010)

• consider_leap_year (bool) – Choose to account for leap year in the number of hours per year calculation

Returns

[0] generation_mwh_per_year [1] operating cost [2] NOV

HOURS_PER_YEAR_LEAP = 8784

HOURS_PER_YEAR_NONLEAP = 8760

classmethod assign_hours_per_year(target_year, consider_leap_year)

Assign the hours per year based on whether or not the target year is a leap year.

calc_annuity_factor()

Calculate annuity factor.

calc_generation()

Calculate electricity generation.

calc_levelization_factor_carbon()

Calculate the levelizing factor for carbon.

calc_levelization_factor_fuel()

Calculate the levelizing factor for fuel.

calc_levelization_factor_vom()

Calculate the levelizing factor for variable OM.

calc_nov()

Calculate NOV array for all technologies.

capacity_factor_fraction: float

carbon_capture_rate_fraction: float

carbon_tax_esc_rate_fraction: float

carbon_tax_usd_per_ton: float

consider_leap_year: bool

discount_rate: float

fuel_co2_content_tons_per_btu: float

fuel_price_esc_rate_fraction: float

fuel_price_usd_per_mmbtu: float

heat_rate_btu_per_kWh: float

lifetime_yrs: int

lmp_arr: numpy.ndarray

target_year: int

unit_size_mw: int

variable_om_esc_rate_fraction: float

variable_om_usd_per_mwh: float

cerf.outputs module

cerf.outputs.plot_siting(result_df, boundary_shp=None, regions_shp=None, column='tech_name', markersize=5, cmap='Paired', save_figure=False, output_file=None)

Plot the results of a cerf run on a map where each technology has its own color.

Parameters

• result_df (DataFrame) – Result data frame from running ‘cerf.run()’

• boundary_shp (str) – Full path to a boundary shapefile with file name and extension. If no file provided, the default boundary for the CONUS will be used.

• regions_shp (str) – Full path to a regions shapefile with file name and extension. If no file provided, the default regions for the CONUS will be used.

• column (str) – Column to plot

• markersize (int) – Size of power plant marker

• cmap – Custom matplotlib colormap object or name

• save_figure (bool) – If True, figure is saved to file and ‘output_file’ must be set

• output_file – If ‘save_figure’ is True, specify full path with file name and extension for the file to be saved to

cerf.package_data module

cerf.package_data.cerf_boundary_shapefile()

Return the cerf boundary shapefile as a Geopandas data frame. Used in output plot.

cerf.package_data.cerf_crs()

Return a coordinate reference system (CRS) object of class ‘pyproj.crs.crs.CRS’ for USA_Contiguous_Albers_Equal_Area_Conic.

cerf.package_data.cerf_regions_raster()

Return the cerf regions raster file.

cerf.package_data.cerf_regions_shapefile()

Return the cerf regions shapefile as a Geopandas data frame. Used in output plot.

cerf.package_data.config_file(yr)

Return the sample configuration file for 2010.

Parameters

yr (int) – Target four-digit year

Returns

Path to the target sample config file

cerf.package_data.costs_per_kv_substation()

Return a dictionary of the cost of interconnection to substations of certain KV classes.

cerf.package_data.get_costs_gas_pipeline()

Return the full path with file name and extension to the default costs per km to gas connect to pipelines.

cerf.package_data.get_costs_per_kv_substation_file()

Return the full path with file name and extension to the default costs per km of each kv substation file.

cerf.package_data.get_data_directory()

Return the directory of where the cerf package data resides.

cerf.package_data.get_default_gas_pipelines()

Return the full path with file name and extension to the default gas pipeline shapefile

cerf.package_data.get_region_abbrev_to_name()

Return a dictionary of region abbreviation to region name.

cerf.package_data.get_region_abbrev_to_name_file()

Return the file path for region abbreviation to region name.

cerf.package_data.get_region_name_to_id()

Return the region name to ID file path.

cerf.package_data.get_sample_lmp_data()

Return the sample 8760 hourly locational marginal price data as a Pandas DataFrame.

cerf.package_data.get_sample_lmp_file()

Return the sample 8760 hourly locational marginal price sample file.

cerf.package_data.get_substation_file()

Return the default substation file for the CONUS.

cerf.package_data.get_suitability_raster(default_raster)

Return the default suitability raster file associated with the technology being processed.

cerf.package_data.list_available_suitability_files()

Return a list of available suitability files.

cerf.package_data.load_sample_config(yr)

Read the config YAML file for illustrative purposes.

Parameters

yr (int) – Target configuration year in YYYY format.

Returns

dictionary for the configuration

cerf.package_data.sample_lmp_zones_raster_file()

Return path for the sample lmp zoness raster file.

cerf.process module

Processing module for CERF

@author Chris R. vernon @email chris.vernon@pnnl.gov

License: BSD 2-Clause, see LICENSE and DISCLAIMER files

cerf.process.cerf_parallel(model, data, write_output=True, n_jobs=- 1, method='sequential')

Run all regions in parallel.

Parameters

• model (class) – Instantiated CERF model class containing configuration options

• data – Data from cerf.stage.Stage containing NLC and suitability arrays

• config_file (str) – Full path with file name and extension to the input config.yml file

• write_output (bool) – Write output as a raster to the output directory specified in the config file

• n_jobs (int) – The number of processors to utilize. Default is -1 which is all but 1.

• method (str) – Backend parallelization method used in Joblib. Default is sequential to manage overhead for local runs. Options for advanced configurations are: loky, threading, and multiprocessing. See https://joblib.readthedocs.io/en/latest/parallel.html for details.

Returns

A 2D arrays containing sites as the technology ID per grid cell. All non-sited grid cells are given the value of NaN.

cerf.process.generate_model(config_file=None, config_dict={}, initialize_site_data=None, log_level='info')

Generate model instance for use in parallel applications.

Parameters

• config_file (str) – Full path with file name and extension to the input config.yml file

• config_dict (dict) – Optional instead of config_file. Configuration dictionary.

• initialize_site_data –

  None if no initialization is required, otherwise either a CSV file or Pandas DataFrame of siting data bearing the following required fields:

  xcoord: the X coordinate of the site in meters in USA_Contiguous_Albers_Equal_Area_Conic (EPSG: 102003)

  ycoord: the Y coordinate of the site in meters in USA_Contiguous_Albers_Equal_Area_Conic (EPSG: 102003)

  retirement_year: the year (int four digit, e.g., 2050) that the power plant is to be decommissioned

  buffer_in_km: the buffer around the site to apply in kilometers

• log_level (str) – Log level. Options are ‘info’ and ‘debug’. Default ‘info’

cerf.process.run(config_file=None, config_dict={}, write_output=True, n_jobs=- 1, method='sequential', initialize_site_data=None, log_level='info')

Run all CERF regions for the target year.

Parameters

• config_file (str) – Full path with file name and extension to the input config.yml file

• config_dict (dict) – Optional instead of config_file. Configuration dictionary.

• write_output (bool) – Write output as a raster to the output directory specified in the config file

• n_jobs (int) – The number of processors to utilize. Default is -1 which is all but 1.

• method (str) – Backend parallelization method used in Joblib. Default is sequential to manage overhead for local runs. Options for advanced configurations are: loky, threading, and multiprocessing. See https://joblib.readthedocs.io/en/latest/parallel.html for details.

• initialize_site_data –

  None if no initialization is required, otherwise either a CSV file or Pandas DataFrame of siting data bearing the following required fields:

  xcoord: the X coordinate of the site in meters in USA_Contiguous_Albers_Equal_Area_Conic (EPSG: 102003)

  ycoord: the Y coordinate of the site in meters in USA_Contiguous_Albers_Equal_Area_Conic (EPSG: 102003)

  retirement_year: the year (int four digit, e.g., 2050) that the power plant is to be decommissioned

  buffer_in_km: the buffer around the site to apply in kilometers

• log_level (str) – Log level. Options are ‘info’ and ‘debug’. Default ‘info’

Returns

A data frame containing each sited power plant and their attributes

cerf.process_region module

Process a region for the target year.

@author Chris R. vernon @email chris.vernon@pnnl.gov

License: BSD 2-Clause, see LICENSE and DISCLAIMER files

class cerf.process_region.ProcessRegion(settings_dict, technology_dict, technology_order, expansion_dict, regions_dict, suitability_arr, lmp_arr, generation_arr, operating_cost_arr, nov_arr, ic_arr, nlc_arr, zones_arr, xcoords, ycoords, indices_2d, target_region_name, randomize=True, seed_value=0, verbose=False, write_output=False)

Bases: object

competition()

Compete technologies.

extract_lmp_zones()

Extract the lmp zones elements for the target region and return as a flat array.

extract_region_metrics()

Extract the LMP, NOV, and IC arrays for the target region and return them as dictionaries where {tech_id: flat_array, …}.

extract_region_suitability()

Extract a single region from the suitability.

get_grid_coordinates()

Generate 1D arrays of grid coordinates (X, Y) to use for siting based on the bounds of the target region.

get_grid_indices()

Generate a 1D array of grid indices the target region to use as a way to map region level outcomes back to the full grid space.

get_region_id()

Load region name to region id YAML file to a dictionary.

Returns

Corresponding region ID for the user passed region name.

mask_nlc()

Extract NLC elements for the current region.

cerf.process_region.process_region(target_region_name, settings_dict, technology_dict, technology_order, expansion_dict, regions_dict, suitability_arr, lmp_arr, generation_arr, operating_cost_arr, nov_arr, ic_arr, nlc_arr, zones_arr, xcoords, ycoords, indices_2d, randomize=True, seed_value=0, verbose=False, write_output=True)

Convenience wrapper to log time and site an expansion plan for a target region for the target year.

Parameters

• target_region_name (str) – Name of the target region as it is represented in the region raster. Must be all lower case with spacing separated by an underscore.

• settings_dict (dict) – Project level setting dictionary from cerf.read_config.ReadConfig

• technology_dict (dict) – Technology level data dictionary from cerf.read_config.ReadConfig

• technology_order (list) – Technology processing order to index by from cerf.read_config.ReadConfig

• expansion_dict (dict) – Expansion plan data dictionary from cerf.read_config.ReadConfig

• regions_dict (dict) – Mapping from region name to region ID from cerf.read_config.ReadConfig

• suitability_arr (ndarray) – 3D array where {tech_id, x, y} for suitability data

• nlc_arr (ndarray) – 3D array where {tech_id, x, y} for NLC data

• data (class) – Object containing all data (NLC, etc.) to run the expansion. This data is generated from the cerf.stage.Stage class.

• randomize (bool) – Choice to randomize when a technology has more than one NLC cheapest value

• seed_value (int) – A random seed value that is used when the user wants to replicate a run exactly

• verbose (bool) – Log verbose siting information

• write_output (bool) – Choice to write output to a file

Returns

2D NumPy array of sited technologies in the CONUS grid space where grid cell values are in the technology number as provided by the expansion plan

cerf.read_config module

class cerf.read_config.ReadConfig(config_file=None, config_dict={})

Bases: cerf.logger.Logger

Read the configuration YAML file to a dictionary. Users can optionally pass in a configuration dictionary instead.

param config_file

Full path with file name and extension to the input config.yml file

type config_file

str

param config_dict

Configuration dictionary.

type config_dict

dict

config_file: str

get_regions_dict()

Get a dictionary of region name to region ID from the YAML file in package data.

get_yaml()

Read the YAML config file.

Returns

YAML config object

static read_yaml(yaml_file)

Read a YAML file.

validate_infrastructure_files()

Ensure that files necessary files exists for infrastructure.

validate_lmp_files()

Ensure that files necessary files exists for LMP zones.

validate_settings_files()

Ensure that files necessary files exists for settings.

validate_technology_files()

Ensure that files necessary files exists for technology.

cerf.stage module

Stage data for CERF run.

@author Chris R. vernon @email chris.vernon@pnnl.gov

License: BSD 2-Clause, see LICENSE and DISCLAIMER files

class cerf.stage.Stage(settings_dict, lmp_zone_dict, technology_dict, technology_order, infrastructure_dict, initialize_site_data)

Bases: object

build_suitability_array()

Build suitability array for all technologies.

calculate_ic()

Calculate interconnection costs.

calculate_lmp()

Calculate Locational Marginal Pricing.

calculate_nlc()

Calculate Net Locational Costs.

calculate_nov()

Calculate Net Operational Value.

get_sited_data()

If initial condition data is provided generate an array to use unsuitable where sites and their buffers exists. Also return a data frame of active sites (not reaching retirement age) to include in the current years output.

lmp_zone_dict: dict

load_lmp_zone_raster()

Load the lmp zoness raster for the CONUS into a 2D array.

settings_dict: dict

technology_dict: dict

technology_order: list

cerf.utils module

cerf.utils.array_to_raster(arr, template_raster_file, output_raster_file)

Write a raster file from a 2D array.

cerf.utils.buffer_flat_array(target_index, arr, nrows, ncols, ncells, set_value)

Assign a value to the neighboring elements of a 1D array as if they were in 2D space. The number of neighbors are based on the ncells argument which is used to define the window around the target cell to be altered as if they were in 2D space.

Parameters

• target_index (int) – Index of the target element in the 1D array

• arr (ndarray) – A 1D array that has been flattened from a corresponding 2D array

• nrows (int) – The number of rows in the parent 2D array

• ncols (int) – The number of columns in the parent 2D array

• ncells (int) – The number of cells for the buffer extending as a radius

• set_value (int; float) – The value to set for the selected buffer

Returns

[0] Modified 1D array [1] list of buffered indices

cerf.utils.default_suitabiity_files()

Return a dictionary of default suitability file names.

cerf.utils.empty_sited_dict()

Initialize a sited dictionary.

cerf.utils.ingest_sited_data(run_year, x_array, siting_data, template_raster_file: str)

Import sited data containing the locations and additional data to establish an initial suitability condition representing power plants and their siting buffer.

Required fields are the following and they can appear anywhere in the CSV or data frame:

xcoord: the X coordinate of the site in meters in USA_Contiguous_Albers_Equal_Area_Conic (EPSG: 102003) ycoord: the Y coordinate of the site in meters in USA_Contiguous_Albers_Equal_Area_Conic (EPSG: 102003) retirement_year: the year (int four digit, e.g., 2050) that the power plant is to be decommissioned buffer_in_km: the buffer around the site to apply in kilometers

Parameters

• run_year (int) – Four-digit year of the current run (e.g., 2050)

• x_array (ndarray) – 2D array of X coordinates for the entire grid space

• siting_data (str, DataFrame) – Full path with file name and extension for the input siting file or a Pandas DataFrame

• template_raster_file (str) – Full path with file name and extension to the input template raster file containing a grid index value per grid cell.

Returns

[0] 2D array of 0 (suitable) and 1 (unsuitable) values where 1 are the sites and their buffers of active power plants

[1] Pandas DataFrame of active sites (not retired)

cerf.utils.kilometers_to_miles(input_km_value)

Convert kilometers to miles.

Parameters

input_km_value (float, int) – Kilometer value to convert to miles

Returns

Miles

cerf.utils.raster_to_coord_arrays(template_raster)

Use the template raster to create two 2D arrays containing the X and Y coordinates of every grid cell.

Parameters

template_raster (str) – Full path with file name and extension to the input raster.

Returns

[0] 2D array of X coordinates [1] 2D array of Y coordinates

cerf.utils.results_to_geodataframe(result_df, target_crs)

Convert the results from ‘cerf.run()’ to a GeoDataFrame.

Parameters

• result_df (DataFrame) – Result data frame from running ‘cerf.run()’

• target_crs – Coordinate reference system to assign the output.

Returns

GeoPandas GeoDataFrame of results

cerf.utils.sited_dtypes()

Return data type dictionary for the sited data frame.

cerf.utils.suppress_callback(value)

Do not log callback output for whitebox functions.

Parameters

value – Value of callback

Module contents