Rebase/decompose (#49)

* Initializing branch for decomposing positive/negative charges (branched off of feature/parametrize_charges)

In utils:
- Updating sum() util function to use pyo.summation
- Adding decompose_consumption function to split a np array, pyo variable, or cvxpy variable into positive and negative components
- Adding initialize_decomposed_pyo_vars to help with initializing the decomposed elements in a pyomo model

Modifying existing tests in test_costs.py to include decompositino

Adding test_decompose_consumption_np, test_decompose_consumption_cvxpy, test_decompose_consumption_pyo to test_utils.py

Adding documentation notes in how_to_advanced

Adding test coverage for negative values input to energy / demand calculation

Removing ValueError raised in calculate_cost for non-np.array/pyo/cvx object. Since this code is never actually reached because the valueerror will be raised from ut.multiply() first

Consolidating consumption_data_dict and consumption_object_dict arguments

Adding magnitude constraint so that positive_var[t] + negative_var[t] == abs(expression[t]) to prevent both variables becoming large when export rate is higher than energy rate

Reformatted with black

Updated test_calculate_cost_pyo to use ipopt rather than gurobi when running decompose_exports, since abs() function is nonlinear / nonconvex

* Renaming scale_ratios to percent_change_dict in parametrize_charge_dict and parametrize_rate_data

Adding test_calculate_itemized_costs for np, cvx, and pyo with one non-decomposed and one decomposed example

Adding a warning test to calculate_export_revenue

Adding helper functions for pyo and cvx problems to be used by their versions of both test_calculate_cost and test_calculate_itemized_cost

Adding warning that decompose_exports isn't supported with cvxpy due to non-DCP exports-imports issues

Reformatted with black

* Simplifying test_decompose_consumption_pyo with approx

* Changing decompose_exports argument to decomposition_type, which can take None, "absolute_value", "binary", or other types in the future

Using max_pos for creating positive and negative pyomo variables
(WIP: Index issue failing test in test_utils)

* Adding missing arguments in test_costs.py

* COSTS
Adding calculate_conversion_factors

Modifying calculate_energy_cost to only apply convex approximation when there are charge tiers

TESTS
Adding consumption_estimate to test_calculate_cost_cvx to avoid default 0 issues

Adding additional test case for cvx problem without charge limit to test_calculate_cost_cvx

Updating test expectations in test_max_pos_pyo so that scalar inputs have scalar expectations, vector inputs have vector expectations

* Fixing bug with duplicated conversion_factor in calculate_cost

Reformatting with black

* Since conversion_factor is applied earlier during import/export decomposition, removing it from divisor in costs.py and renaming divisor to n_per_hour

Moving application of conversion factor to helper function get_converted_consumption_data

* Consolidating get_unique_row_name and default_varstr_alias_func

default_varstr_alias_func takes row index parameter, where index is used if "name" is blank

Removing dashes from names in test_costs.py since sanitize_varstr removes dashes and replaces with underscores

Cleaning up error expectation in test_calculate_cost_np

* Cleaning up calculate_energy_cost

* Reverting changes to default_varstr_alias_func

Adding back get_unique_row_name (renamed to get_charge_name)

Removing initialize_decomposed_pyo_vars. The variables self-initialize during solve.

Updating test_decompose_consumption_pyo to just check for the presence of objects, not values. (WIP to add value check in test_calculate_cost_pyo for pre-decomposed inputs)

Renaming _get_decomposed_var_names to get_decomposed_var_names

Adding test cases for extended consumption data format in test_calculate_cost_np and test_calculate_cost_pyo

* Adding test calling max_pos on pyo scalar

Updating minimum pyomo version to 6.8

* Reformatted with black

* Add comprehensive test coverage for utils and costs

- Add scalar LinearExpression tests for max_pos_pyo
- Add TypeError tests for invalid types in max_pos and decompose_consumption
- Add warning tests for unimplemented decomposition types
- Add ValueError test for invalid type in calculate_export_revenue
- Add negative values warning test in calculate_demand_costs
- Add test for consumption_estimate=None and dict consumption_estimate
- Add conversion factor test with MW units in test_calculate_itemized_cost_pyo
- Fix idempotency in get_converted_consumption_data to prevent duplicate components
- Add warnings for unimplemented decomposition_type in utils.decompose_consumption

* Removing uneeded else statements in calculate_cost if conversion / decomposition has already been run on the model

* Correcting UserWarning syntax in costs.py

* Creating new test to address bug with double unit conversions in itemized costs

* Fixed errors in rebase so that only two tests fail now

* Fixing flake8 errors

* Trying to address double unit conversion

* Fixed unit conversion errors and all tests now passing

* Autoreformatted with black

* Creating codecov.yml file to try to address patch coverage

* Fixed flake8 errors

* Fixing documentation formatting

* Fixing whitespace error

---------

Co-authored-by: dalyw <sdwettermark@gmail.com>

Author: fletchapin

codecov.yml

@@ -0,0 +1,10 @@
+coverage:
+  status:
+    project:
+      default:
+        target: auto
+    patch:
+      default:
+        enabled: yes
+        target: 100%
+        threshold: 5%

docs/how_to_advanced.rst

@@ -135,32 +135,91 @@ the previous consumption during this billing period in conjunction with `consump
 How to Use `demand_scale_factor`
 ================================
 
-By default `demand_scale_factor=1`, meaning that there will be no modifications applied to the demand or energy charges.
-The purpose of the scale factor is to modify the demand charges proportional to energy charges when performing moving horizon optimization.
+The `demand_scale_factor` parameter allows you to scale demand charges to reflect shorter optimization horizons or to prioritize demand differently across sequential optimization horizons.
 
-There are various heuristics that could be used to calculate the scale factor (see :ref:`why-scale-demand`), 
-but for now let's assume that we just want to scale the demand charge down by the length of the horizon window proportional to billing period.
+By default, `demand_scale_factor=1.0`. Use values less than 1.0 when solving for a subset of the billing period, or to adjust demand charge weighting in sequential optimization.
+
+When `demand_scale_factor < 1.0`, demand charges are proportionally reduced to reflect the shorter optimization horizon. This is useful for:
+- Moving horizon optimization where you solve for sub-periods of the billing cycle
+- Sequential optimization where you want to reduce demand charge weighting as time goes on in the month
 
 .. code-block:: python
 
-    from eeco import costs
+    from electric_emission_cost import costs
     
-    # load necessary data 
-    start_dt = np.datetime64("2024-07-10")
-    end_dt = np.datetime64("2024-07-11")
-    charge_dict = costs.get_charge_dict(start_dt, end_dt, tariff_df)
-    num_timesteps_horizon = 96
-    num_timesteps_billing = 96 * 31
+    # E.g. solving for 3 days out of a 30-day billing period
+    demand_scale_factor = 3 / 30
+    
+    result, model = costs.calculate_cost(
+        charge_dict,
+        consumption_data,
+        demand_scale_factor=demand_scale_factor
+        # ...
+    )
 
-    # this is just a CVXPY variable, but a user would provide constraints to the optimization problem
-    consumption_data_dict = {"electric": cp.Variable(num_timesteps), "gas": cp.Variable(num_timesteps)}
+For more details on applying the sequential optimization strategy, see:
 
-    total_monthly_bill, _ = costs.calculate_costs(
+    Bolorinos, J., Mauter, M.S. & Rajagopal, R. Integrated Energy Flexibility Management at Wastewater Treatment Facilities. *Environ. Sci. Technol.* **57**, 46, 18362–18371 (2023). DOI: [10.1021/acs.est.3c00365](https://doi.org/10.1021/acs.est.3c00365)
+
+In `bibtex` format:
+
+.. code-block:: bibtex
+
+   @Article{Bolorinos2023,
+   author={Bolorinos, Jose
+   and Mauter, Meagan S.
+   and Rajagopal, Ram},
+   title={Integrated Energy Flexibility Management at Wastewater Treatment Facilities},
+   journal={Environmental Science & Technology},
+   year={2023},
+   month={Jun},
+   day={16},
+   volume={57},
+   number={46},
+   pages={18362--18371},
+   doi={10.1021/acs.est.3c00365},
+   url={https://doi.org/10.1021/acs.est.3c00365}
+   }
+
+
+.. _decompose-exports:
+
+How to Use `decomposition_type`
+===============================
+
+The `decomposition_type` parameter allows you to decompose consumption data into positive (imports) and negative (exports) components. This is useful when you have export charges or credits in your rate structure.
+Options include:
+
+- Default `None`
+- `"binary_variable"`: To be implemented
+- `"absolute_value"`
+
+.. code-block:: python
+
+    from electric_emission_cost import costs
+    
+    # Example with export charges
+    charge_dict = {
+        "electric_export_0_2024-07-10_2024-07-10_0": np.ones(96) * 0.025,
+    }
+    
+    consumption_data = {
+        "electric": np.concatenate([np.ones(48) * 10, -np.ones(48) * 5]),
+        "gas": np.ones(96),
+    }
+    
+    # Decompose consumption into imports and exports
+    result, model = costs.calculate_cost(
         charge_dict,
-        consumption_data_dict,
-        demand_scale_factor=num_timesteps_horizon/num_timesteps_billing
+        consumption_data,
+        decomposition_type="absolute_value"
     )
 
+When decomposition_type is not None the function creates separate variables for positive consumption (imports) and negative consumption (exports)
+and applies export charges only to the export component.
+For Pyomo models, decomposition_type adds a constraint total_consumption = imports - exports
+
+
 .. _varstr-alias:
 
 How to Use `varstr_alias_func`

docs/how_to_cost.rst

@@ -73,6 +73,7 @@ NumPy
     # one month of 15-min intervals
     num_timesteps = 24 * 4 * 31
     # this is synthetic consumption data, but a user could provide real historical meter data
+    # Positive values represent imports, negative values represent exports in consumption data
     consumption_data_dict = {"electric": np.ones(num_timesteps) * 100, "gas": np.ones(num_timesteps))}
     total_monthly_bill, _ = costs.calculate_cost(charge_dict, consumption_data_dict)