utils

This module consists of helpful utility functions

eeco.utils.convert_utc_to_timezone(utc_hour, timezone_str)

Convert UTC hour (0-23) to the corresponding hour in a specified timezone.

Parameters: utc_hour (int): Hour in UTC (0-23). timezone_str (str): Timezone string, e.g., ‘America/New_York’.

Returns: int: Corresponding hour in the specified timezone.

eeco.utils.decompose_consumption(expression, model=None, varstr=None, decomposition_type='absolute_value')

Decomposes consumption data into positive and negative components And adds constraint such that total consumption equals positive values minus negative values (where negative values are stored as positive magnitudes).

Parameters:

• expression ([) – numpy.Array, cvxpy.Expression, pyomo.core.expr.numeric_expr.NumericExpression, pyomo.core.expr.numeric_expr.NumericNDArray, pyomo.environ.Param, pyomo.environ.Var

• ] – Expression representing consumption data

• model (pyomo.environ.Model) – The model object associated with the problem. Only used in the case of Pyomo, so None by default.

• varstr (str) – Name prefix for the variables to be created if using a Pyomo model

• decomposition_type (str) – Type of decomposition to use. - “binary_variable”: To be implemented - “absolute_value”: Creates nonlinear problem

Returns:

(positive_values, negative_values, model) where positive_values and negative_values are both positive with the constraint that total = positive - negative

Return type:

tuple

eeco.utils.get_decomposed_var_names(utility)

Get consistent variable names for decomposed consumption variables.

eeco.utils.get_freq_binsize_minutes(freq)

Gets size of a given time frequency expressed in units of minutes

Parameters:

freq (str) – a string of the form [type][freq_binsize], where type corresponds to a numpy.timedelta64 encoding and freq binsize is an integer giving the number of increments of type of one binned increment of our time variable (for example ‘6h’ means the data are grouped into increments of 6 hours)

Raises:

ValueError – when resolution is not minute, hourly, or daily

Returns:

integer giving the number of minutes in the given time frequency unit

Return type:

int

eeco.utils.idxparam_value(idx_param)

Returns the parameter value at the given index.

Parameters:

idx_param (pyomo.environ.Param or pyomo.environ.Var) – The Pyomo parameter or variable to be converted

Returns:

Indexed variable or parameter as a numpy array

Return type:

numpy.ndarray

eeco.utils.max(expression, model=None, varstr=None)

Elementwise maximum of an expression or array

Parameters:

• expression ([) – numpy.Array, cvxpy.Expression, pyomo.core.expr.numeric_expr.NumericExpression, pyomo.core.expr.numeric_expr.NumericNDArray, pyomo.environ.Param, pyomo.environ.Var

• ] – The expression to find the maximum of

• model (pyomo.environ.Model) – The model object associated with the problem. Only used in the case of Pyomo, so None by default.

• varstr (str) – Name of the variable to be created if using a Pyomo model

Raises:

TypeError – When expression is not of type numpy.Array, cvxpy.Expression, pyomo.core.expr.numeric_expr.NumericExpression, pyomo.core.expr.numeric_expr.NumericNDArray, pyomo.environ.Param, or pyomo.environ.Var

Returns:

Expression representing max of expression

Return type:

([numpy.Array, cvxpy.Expression, pyomo.environ.Var], pyomo.environ.Model)

eeco.utils.max_pos(expression, model=None, varstr=None)

Returns the element-wise maximum positive value of an expression. Returns scalar for scalar input, indexed for indexed input.

Parameters:

• expression ([) – numpy.Array, cvxpy.Expression, pyomo.core.expr.numeric_expr.NumericExpression, pyomo.core.expr.numeric_expr.NumericNDArray, pyomo.environ.Param, pyomo.environ.Var

• ] – Expression representing a matrix, vector, or scalar

• model (pyomo.environ.Model) – The model object associated with the problem. Only used in the case of Pyomo, so None by default.

• varstr (str) – Name of the variable to be created if using a Pyomo model

Raises:

TypeError – When expression is not of type numpy.Array, cvxpy.Expression, pyomo.core.expr.numeric_expr.NumericNDArray, pyomo.core.expr.numeric_expr.NumericExpression, pyomo.environ.Param, or pyomo.environ.Var

Returns:

• ( – [numpy.float, numpy.int, numpy.Array, cvxpy.Expression, or pyomo.environ.Var], pyomo.environ.Model

• ) – Expression representing element-wise maximum positive value of expression. Scalar input returns scalar output, indexed input returns indexed output.

eeco.utils.multiply(expression1, expression2, model=None, varstr=None)

Implements elementwise multiplication operation on two optimization expressions

Parameters:

• expression1 ([) – numpy.Array, cvxpy.Expression, pyomo.core.expr.numeric_expr.NumericExpression, pyomo.core.expr.numeric_expr.NumericNDArray, pyomo.environ.Param, pyomo.environ.Var

• ] – LHS of multiply operation

• expression2 ([) – numpy.Array, cvxpy.Expression, pyomo.core.expr.numeric_expr.NumericExpression, pyomo.core.expr.numeric_expr.NumericNDArray, pyomo.environ.Param, pyomo.environ.Var

• ] – RHS of multiply operation

• model (pyomo.environ.Model) – The model object associated with the problem. Only used in the case of Pyomo, so None by default.

• varstr (str) – Name of the variable to be created if using a Pyomo model

Raises:

TypeError – When expression is not of type numpy.Array, cvxpy.Expression, pyomo.core.expr.numeric_expr.NumericNDArray, pyomo.core.expr.numeric_expr.NumericExpression, pyomo.environ.Param, or pyomo.environ.Var

Returns:

• [ – numpy.Array, cvxpy.Expression, pyomo.core.expr.numeric_expr.NumericNDArray, pyomo.environ.Expression

• ] – result from elementwise multiplication of expression1 and expression2

eeco.utils.parse_freq(freq)

Parses a time frequency code string, returning its type and its freq_binsize

Parameters:

freq (str) – a string of the form [type][freq_binsize], where type corresponds to a numpy.timedelta64 encoding and freq binsize is an integer giving the number of increments of type of one binned increment of our time variable (for example ‘6h’ means the data are grouped into increments of 6 hours)

Returns:

tuple of the form (int,`str`) giving the binsize and units (freq_type)

Return type:

tuple

eeco.utils.sanitize_varstr(varstr)

Sanitizes a variable string by removing non-alphanumeric characters and replacing spaces with underscores.

Parameters:

varstr (str) – The variable string to sanitize.

Returns:

The sanitized variable string.

Return type:

str

eeco.utils.sum(expression, axis=0, model=None, varstr=None)

Elementwise sum of values in an expression or array

Parameters:

• expression ([) – numpy.Array, cvxpy.Expression, pyomo.core.expr.numeric_expr.NumericExpression, pyomo.core.expr.numeric_expr.NumericNDArray, pyomo.environ.Param, pyomo.environ.Var

• ] – Expression representing a matrix to sum

• axis (int) – Optional axis along which to compute sum. Default is 0

• model (pyomo.environ.Model) – The model object associated with the problem. Only used in the case of Pyomo, so None by default.

• varstr (str) – Name of the variable to be created if using a Pyomo model

Raises:

TypeError – When expression is not of type numpy.Array, cvxpy.Expression, pyomo.core.expr.numeric_expr.NumericExpression, pyomo.core.expr.numeric_expr.NumericNDArray pyomo.environ.Param, or pyomo.environ.Var

Returns:

Expression representing sum of expression along axis

Return type:

[numpy.Array, cvxpy.Expression, pyomo.environ.Expression]