Code Documentation

generator.py

The generator module of Copper deals with generating performance curves. It currently uses a genetic algorithm to find sets of curves that match user equipment definitions.

class copper.generator.Generator(equipment, method='best_match', pop_size=100, tol=0.005, max_gen=300, vars='', sFac=0.5, retain=0.2, random_select=0.1, mutate=0.95, bounds=(6, 10), base_curves=[], random_seed=None, num_nearest_neighbors=10, max_restart=None)[source]

Bases: object

calc_fit(pop)[source]

Calculate fitness of each individual in a population.

Parameters:: pop (list) – Population
Returns:: Fitness score of each individual
Return type:: list

check_gradients()[source]

Check if the objective of the gradient of the three curves are monotonic and have the sign we expect.

Returns:: Verification result
Return type:: bool

compute_grad(x, y, sign_val, threshold=1e-05)[source]

Check, for a single curve, if the gradient has the sign we expect. called by check_gradients.

Returns:: Verification result
Return type:: bool

determine_full_load_fitness(set_of_curves)[source]

Determine the full load fitness of a set of curves

Parameters:: set_of_curves (copper.curves.SetofCurves) – Set of curves
Returns:: Fitness score
Return type:: float

determine_normalization_fitness(set_of_curves)[source]

Determine the normalization fitness of a set of curves (e.g. are they normalized at rated/reference conditions?)

Parameters:: set_of_curves (copper.curves.SetofCurves) – Set of curves
Returns:: Fitness score
Return type:: float

determine_part_load_fitness(set_of_curves)[source]

Determine the part load fitness of a set of curves

Parameters:: set_of_curves (copper.curves.SetofCurves) – Set of curves
Returns:: Fitness score
Return type:: float

evolve_population(pop)[source]

Evolve population to create a new generation.

Parameters:: pop (list) – Population of individual, i.e. list of curves

fitness_scale_grading(pop, scaling=True)[source]

Calculate fitness, scale, and grade for a population.

Parameters:

pop (list) – Population of individual, i.e. list of curves
scaling (bool) – Linearly scale fitness scores

Returns:

List sets of curves graded by fitness scores

Return type:

list

generate_population(curves)[source]

Generate population of sets of curves.

Parameters:: curves (copper.curves.SetofCurves) – Initial set of curves to be modified by the algorithm
Returns:: Verification result
Return type:: bool

generate_set_of_curves(verbose=False, agg_only=False)[source]

Generate set of curves using genetic algorithm.

Parameters:: verbose (str) – Output results at each generation.
Returns:: Set of curves
Return type:: SetofCurves

get_random()[source]

Generate random number between two bounds.

Returns:: Randomly generated value
Return type:: float

grade_population(pop_scaled)[source]

Grade population.

Parameters:: pop_scaled (list) – List of tuples representing the fitness of a set of curves and the set of curves
Returns:: List of set of curves graded from the best to the worst
Return type:: list

identify_best_performer()[source]: Assign the best individual to the equipment.

individual(curves)[source]

Create new individual.

Parameters:: curves (copper.curves.SetofCurves) – Initial set of curves to be modified by the algorithm
Returns:: New set of curves randomly modified
Return type:: SetofCurves

is_target_met()[source]

Check if the objective of the optimization through the algorithm have been met.

Returns:: Verification result
Return type:: bool

perform_crossover(parents)[source]

Crossover best individuals.

Parameters:: parents (list) – List of best performing individuals of the generation

perform_mutation(individual)[source]

Mutate individual.

Parameters:: individual (copper.curves.SetofCurves) – Set of curves
Returns:: Modified indivudal
Return type:: SetofCurves

run_ga(curves, verbose=False)[source]

Run genetic algorithm.

Parameters:

curves (copper.curves.SetofCurves) – Initial set of curves to be modified by the algorithm
verbose (str) – Output results at each generation.

Returns:

Final population of sets of curves

Return type:

list

scale_fitnesses(fitnesses, pop, scaling=True)[source]

Scale the fitness scores to prevent best performers from dragging the whole population to a local extremum.

Parameters:

fitnesses (list) – List of fitness for each set of curves
pop (list) – List of sets of curves
scaling (bool) – Specifies whether of not to linearly scale the fitnesses

Returns:

List of tuples representing the fitness of a set of curves and the set of curves

Return type:

list

curves.py

The curves module of Copper handles all operations and manipulation related to curves, set of curves, and sets of curves.

class copper.curves.Curve(eqp, c_type)[source]

Bases: object

compute_grad(x, y, sign_val, threshold=1e-05)[source]

Check, for a single curve, if the gradient has the sign we expect. called by check_gradients.

Returns:: Verification result
Return type:: bool

convert_coefficients_to_ip()[source]: Convert curve coefficient to imperial units

evaluate(x, y)[source]

Return the output of a curve.

Parameters:

x (float) – First curve independent variable
y (float) – Second curve independent variable

Returns:

Curve output

Return type:

float

get_out_reference(eqp)[source]

Return the reference output of a curve.

Parameters:: eqp – Equipment
Returns:: Curve output at reference conditions
Return type:: float

nb_coeffs()[source]

Find number of curve coefficients.

Returns:: Number of curve coefficients
Return type:: int

normalized(data, x_norm, y_norm)[source]

Normalize curve around the reference data points.

Parameters:

data (pandas.DataFrame) – Dataframe object with the following columns: ‘X1’, ‘X1^2’, ‘X2’, ‘X2^2’, ‘X1*X2’, ‘Y’
x_norm (float) – First independent variable normalization points
y_norm (float) – Second independent variable normalization points

regression(data, curve_types)[source]

Find curve coefficient by running a multivariate linear regression.

Parameters:

data (pandas.DataFrame) – Dataframe object with the following columns: ‘X1’, ‘X1^2’, ‘X2’, ‘X2^2’, ‘X1*X2’, ‘Y’
curve_types (list) – List of Copper curve types

class copper.curves.SetofCurves[source]

Bases: object

export(path='./', fmt='idf', name='')[source]

Export curves to simulation engine input format.

Parameters:

path (str) – Path and file name, do not include the extension, it will be added based on the simulation engine of the SetofCurves object.
fmt (str) – Input format type. Currently supported: csv, json, idf.
name (str) – Name of the set of curves.

Returns:

Success

Return type:

bool

get_data_for_plotting(curve, norm)[source]

Retrieve equipment specific data for plotting set of curves.

Parameters:

curve (Curve) – Copper curve object
norm (bool) – Normalize data used for plotting the curves

Returns:

Data to be used for plotting the curves

Return type:

list

list_to_dict()[source]

Convert curves from the set from a list to a dictionary (the key being the output variable type).

Returns:: Dictionary of Copper curve objects
Return type:: dict

plot(out_var=[], axes=[], norm=False, color='Black', alpha=0.3)[source]

Plot a set of curves.

Parameters:

out_var (list) – List of the output variables to plot, e.g. eir-f-t, eir-f-plr, cap-f-t. Refer to JSON files structure for other output variables
axes (matplotlib.pyplot.axes) – Matplotlib pyplot axes
norm (bool) – Normalize plot to reference values
color (str) – Set of curves color
alpha (float) – Transparency of the curves (0-1).

Returns:

Plotting success

Return type:

bool

remove_curve(out_var)[source]

Remove curve for a particular output variable from the set.

Parameters:: out_var (str) – Name of the output variable to remove from the set

class copper.curves.SetsofCurves(eqp, sets)[source]

Bases: object

check_vars_in_dictionary(vars, target_attr)[source]

Function to check that the vars specified by the user exists in ‘target_attr’.

Parameters:

vars (list) – Variable to calculate weights with, as specified by the user
target_attr (list) – Target attributes

Returns:

List of variables not in ‘target_attr’

Return type:

list

get_aggregated_set_of_curves(method='weighted_average', N=None, ranges={}, misc_attr={})[source]

Determine sets of curves based on aggregation.

Parameters:

method (str) – Type of aggregation, currently supported: ‘average’, ‘median’, ‘weighted_average’, and ‘NN_weighted_average’ as in nearest neighbor weighted average.
N (int) – Number of neighbor used to the aggregation, only used when the method is ‘NN_weighted_average’.
ranges (dict) – Dictionary that defines the ranges of values for each independent variable used to calculate aggregated dependent variable values.
misc_attr (dict) – Dictionary that provides values for the aggregated set of curves.

Returns:

Aggregated set of curves

Return type:

SetofCurves

l2_norm(df, target_attr, weights, vars=['full_eff', 'ref_cap'])[source]

Perform L2 normalization.

Parameters:

df (pandas.DataFrame) – Dataframe containing the attributes of different equipments for a given equipment type
target_attr (dict) – Target equipment attribute
weights (list) – List of weights, must have the same dimensions as vars
vars (list) – List of string containing variable names to compute the L2 normalization

Returns:

L2 scores (same size as df)

Return type:

numpy.array

nearest_neighbor_sort(target_attr=None, vars=[], N=None)[source]

This function performs the weighted average and the nearest neighbor approach.

Parameters:

target_attr (dict) – Target attributes we want to match
vars (list) – The variables we want to use to compute our l2 score. note COP will be added
N (int) – Indicates the number of nearest neighbors to consider. N=None for weighted_average
df (pandas.DataFrame) – Pandas dataframe with selected chiller names and the associated weightings

Returns:

Index of set_of_curve that should be the closest fit

Return type:

int

normalize_vars(df, target_attr=None, vars=['ref_cap', 'full_eff'], epsilon=1e-05, weights=None, N=None)[source]

Normalize curve outputs.

Parameters:

df (pandas.DataFrame) – Input dataframe containing the variable inputs
target_attr (dict) – Reference targets with respect to which l2 score needs to computed
vars (list) – List of strings for variables we want to normalize
weights (list) – Weights associated with each variable in vars
N (int) – Number of nearest neighbors. It should be none unless method is ‘NN_weighted_average’

Returns:

Dataframe with added columns with normalized variables, dict with added normalized values of var in vars, index of the best curve

Return type:

list

softmax(x)[source]

Softmax function.

Parameters:: x (float) – Convert distances to scores/weights using the softmax function
Returns:: Result of the softmax function
Return type:: float

library.py

This is the library module of Copper. It contains functions used to parse the JSON library files.

class copper.library.Library(path='/home/runner/work/copper/copper/copper/data/chiller_curves.json', rating_std='', export=False)[source]

Bases: object

content()[source]

Content of a library in a dict format.

Returns:: Dictionary of the data contained in a library
Return type:: dict

find_base_curves(filters, eqp)[source]

Find an existing equipment curve that best matches the equipment.

Parameters:

filters (list) – List of filters, represented by tuples (field, val)
eqp – Instance of the equipment in Copper (e.g. copper.chiller.Chiller)

Returns:

Set of curves object

Return type:

SetofCurves

find_equipment(filters=[])[source]

Find equipment matching specified filter in the curve library.

Special filter characters:

~! means “all except…”
! means “do not include…”
~ means “include…”

Parameters:: filters (list) – List of filters, represented by tuples (field, val)
Returns:: Dictionary of field for each equipment matching specified filter
Return type:: dict

find_set_of_curves_from_lib(filters=[], part_eff_flag=False)[source]

Retrieve sets of curves from a library matching specific filters.

Parameters:: filters (list) – List of filters, represented by tuples (field, val)
Returns:: List of sets of curves object matching the filters
Return type:: list

get_best_match(eqp, matches)[source]

Find the set of curves matching the equipment characteristics the best.

Parameters:

eqp – Instance of the equipment in Copper (e.g. copper.chiller.Chiller)
matches (dict) – All potential matches

Returns:

Name of the set of curves that best matches the equipment characteristics

Return type:

str

get_curve(c, c_name, eqp)[source]

Retrieve individual attribute of a curve object.

Parameters:

c (Curve) – Curve object
c_name (str) – Name of the curve object
eqp_type (str) – Type of equipment associated with the curve

Returns:

Curve object

Return type:

Curve

get_set_of_curves_by_name(name)[source]

Retrieve set of curves from the library by name.

Parameters:: name (str) – Curve name
Returns:: Set of curves object
Return type:: SetofCurves

get_unique_eqp_fields()[source]

Get all unique values for each field of a particular equipment.

Returns:: Dictionary showing all unique values for each equipment field.
Return type:: dict

load_obj(data)[source]

Load data for an equipment from the libary.

Parameters:: data (dict) – Equipment data in a dict format
Returns:: Instance of the equipment in Copper (e.g. copper.chiller.Chiller)

units.py

The conversion module of Copper handles simple unit conversions to avoid creating additional dependencies.

class copper.units.Units(value, unit)[source]

Bases: object

conversion(new_unit)[source]

Convert efficiency rating.

Parameters:: new_unit (str) – Unit after conversion
Returns:: Converted value
Return type:: float

equipment.py

This is the equipment module of Copper. The module includes function that can be used by all types of equipment included in Copper.

class copper.equipment.Equipment[source]

Bases: object

convert_to_deg_c(unit='degF')[source]

Helper function to convert equipment data to degree F.

Parameters:: value (float) – Value to convert to degree C
Returns:: Vlue converted to degree C
Return type:: float

generate_set_of_curves(method='best_match', pop_size=100, tol=0.0025, max_gen=300, vars='', sFac=0.5, retain=0.2, random_select=0.1, mutate=0.95, bounds=(6, 10), base_curves=[], random_seed=None, verbose=False, export_path='', export_format='json', export_name='', num_nearest_neighbors=10, max_restart=None, agg_only=False)[source]

Generate a set of curves for a particular equipment.

Parameters:

method (str) – Method used to generate the set of curves: best_match, nearest_neighbor, or weighted_average
pop_size (int) – Population size used by the genetic algorithm
tol (float) – Tolerance used by the genetic algorithm to determine if the proposed solution is acceptable The lower, the more stringent
max_gen (int) – Maximum number of generation
vars (list()) – List of variable to run the alorithm on
sFac (float) – Linear fitness normalization factor, the higher the more aggressive the normalization will be
retain (float) – Probability of retaining an individual in the next generation
random_select (float) – Probability of randomly selecting an individual to be part of the next generation
mutate (float) – Probability of an individual to be mutated in the next generation
bounds (tuple()) – Random modification bounds
random_seed (int) – Integer that is used to inialize the random number generator, this should be used when identical results are needed from one run to another

Returns:

Set of curves object generated by the genetic algorithm that matches the definition

Return type:

SetofCurves

get_eir_ref(alt)[source]

Get the reference EIR (energy input ratio) of an equipment.

Parameters:: alt (bool) – Specify if the alternative equipment efficiency should be used to calculate the EIR
Returns:: Reference EIR
Return type:: float

get_ref_values(out_var)[source]

Get equipment reference/rated independent variables values (temperature and part load ratio) for an output variable (e.g., eir-f-t, eir-f-plr, cap-f-t).

Parameters:: out_var (str) – Output variable
Returns:: List of reference values
Return type:: list

chiller.py

This is the chiller module of Copper. The module handles all calculations and data manipulation related to chillers.

class copper.chiller.Chiller(ref_cap, ref_cap_unit, full_eff, full_eff_unit, compressor_type, condenser_type, compressor_speed, part_eff=0, part_eff_unit='', part_eff_ref_std='ahri_550/590', part_eff_alt=0, part_eff_unit_alt='', part_eff_ref_std_alt='ahri_550/590', full_eff_alt=0, full_eff_unit_alt='', set_of_curves=[], model='ect_lwt', sim_engine='energyplus', min_unloading=0.1, min_plr=None)[source]

Bases: Equipment

calc_eff_ect(cap_f_t, eir_f_t, eir_f_plr, eir_ref, ect, lwt, load)[source]

Calculate chiller efficiency using the ECT-based model for a specific ECT and load value (percentage load).

Parameters:

cap_f_t (Curve) – Capacity curve modifier as a function of temperature (LWT and ECT)
eir_f_t (Curve) – Energy Input Ratio curve modifier as a function of temperature (LWT and ECT)
eir_f_plr (Curve) – Energy Input Ratio curve modifier as a function of part load ratio
eir_ref (float) – Reference EIR
ect (float) – Entering condenser temperature in deg. C
lwt (float) – Leaving water temperature in deg. C
load (float) – Percentage load, as defined in AHRI 550/590

calc_rated_eff(eff_type, unit='kW/ton', output_report=False, alt=False)[source]

Calculate chiller efficiency.

Parameters:

eff_type (str) – Chiller efficiency type, currently supported full (full load rating) and part (part load rating)
unit (str) – Efficiency unit

Returns:

Chiller rated efficiency

Return type:

float

cond_inlet_temp_residual(lct, args)[source]

Calculate the enetering condenser temperature residual based on a leaving condenser temperature.

Parameters:: lct (float) – Leaving condenser temperature (deg. C)
Returns:: Entering condenser temperature residual
Return type:: float

convert_to_deg_c(unit='degF')

Helper function to convert equipment data to degree F.

Parameters:: value (float) – Value to convert to degree C
Returns:: Vlue converted to degree C
Return type:: float

generate_set_of_curves(method='best_match', pop_size=100, tol=0.0025, max_gen=300, vars='', sFac=0.5, retain=0.2, random_select=0.1, mutate=0.95, bounds=(6, 10), base_curves=[], random_seed=None, verbose=False, export_path='', export_format='json', export_name='', num_nearest_neighbors=10, max_restart=None, agg_only=False)

Generate a set of curves for a particular equipment.

Parameters:

method (str) – Method used to generate the set of curves: best_match, nearest_neighbor, or weighted_average
pop_size (int) – Population size used by the genetic algorithm
tol (float) – Tolerance used by the genetic algorithm to determine if the proposed solution is acceptable The lower, the more stringent
max_gen (int) – Maximum number of generation
vars (list()) – List of variable to run the alorithm on
sFac (float) – Linear fitness normalization factor, the higher the more aggressive the normalization will be
retain (float) – Probability of retaining an individual in the next generation
random_select (float) – Probability of randomly selecting an individual to be part of the next generation
mutate (float) – Probability of an individual to be mutated in the next generation
bounds (tuple()) – Random modification bounds
random_seed (int) – Integer that is used to inialize the random number generator, this should be used when identical results are needed from one run to another

Returns:

Set of curves object generated by the genetic algorithm that matches the definition

Return type:

SetofCurves

get_chiller_curves()[source]

Retrieve chiller curves from the chiller set_of_curves attribute.

Returns:: Dictionary of the curves associated with the chiller object
Return type:: dict

get_curves_from_lib(lib, filters)[source]

Function to get the sort from the library based on chiller filters.

Parameters:

lib (copper.library.Library) – Chiller library object
filters (list) – List of tuples containing the relevant filter keys and values

Returns:

List of set of curves object corresponding to seed curves

Return type:

list

get_eir_ref(alt)

Get the reference EIR (energy input ratio) of an equipment.

Parameters:: alt (bool) – Specify if the alternative equipment efficiency should be used to calculate the EIR
Returns:: Reference EIR
Return type:: float

get_lct(ect, args)[source]

Determine a chiller’s leaving condenser temperature based on a entering condenser temperature. The temperature should be determine by iteration, a secant root finding methods is used.

Parameters:: ect (float) – Entering condenser temperature (deg. C)
Returns:: Leaving condenser temperature (deg. C)
Return type:: float

get_lib_and_filters(lib_path='/home/runner/work/copper/copper/copper/data/chiller_curves.json')[source]

Get chiller library object and chiller specific filters.

:param str lib_path:Full path of json library :return: Chiller library object and filters :rtype: list

get_ranges()[source]

Get applicable range of values for independent variables of the chiller model.

Returns:: Range of values, and values used for normalization (reference/rated values)
Return type:: dict

get_rated_temperatures(alt=False)[source]

Get chiller rated temperatures.

Parameters:: alt (bool) – Indicate the chiller alternate standard rating should be used
Returns:: Rated entering condenser temperature and leaving chilled water temperature
Return type:: list

get_ref_cond_flow_rate()[source]

Function to compute the reference condenser flow rate given ref_cap, full_eff, ref_lct and ref_lwt

Returns:: Reference condenser flow rate
Return type:: float

get_ref_values(out_var)

Get equipment reference/rated independent variables values (temperature and part load ratio) for an output variable (e.g., eir-f-t, eir-f-plr, cap-f-t).

Parameters:: out_var (str) – Output variable
Returns:: List of reference values
Return type:: list

get_ref_vars_for_aggregation()[source]

get_seed_curves(lib=None, filters=None, csets=None)[source]

Function to generate seed curves specific to a chiller and sets relevant attributes (misc_attr, ranges).

Parameters:

lib (copper.library.Library) – Chiller library object
fitlers (list) – List of tuples containing the filter keys and values
csets (list) – List of set of curves object corresponding to selected chillers from library

Return type:

SetsofCurves

schema.py

Validation of the CLI input files.

class copper.schema.Schema(input)[source]

Bases: object

validate()[source]

Validate input file to be used in the CLI.

Returns:: Result of the validation
Return type:: bool