energiapy 2.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- energiapy-2.0.0/LICENSE +21 -0
- energiapy-2.0.0/PKG-INFO +244 -0
- energiapy-2.0.0/README.md +179 -0
- energiapy-2.0.0/pyproject.toml +48 -0
- energiapy-2.0.0/setup.cfg +4 -0
- energiapy-2.0.0/src/__init__.py +0 -0
- energiapy-2.0.0/src/energia/__init__.py +38 -0
- energiapy-2.0.0/src/energia/components/__init__.py +0 -0
- energiapy-2.0.0/src/energia/components/commodity/__init__.py +2 -0
- energiapy-2.0.0/src/energia/components/commodity/_commodity.py +98 -0
- energiapy-2.0.0/src/energia/components/commodity/currency.py +35 -0
- energiapy-2.0.0/src/energia/components/commodity/emission.py +14 -0
- energiapy-2.0.0/src/energia/components/commodity/land.py +13 -0
- energiapy-2.0.0/src/energia/components/commodity/material.py +12 -0
- energiapy-2.0.0/src/energia/components/commodity/misc.py +49 -0
- energiapy-2.0.0/src/energia/components/commodity/resource.py +74 -0
- energiapy-2.0.0/src/energia/components/commodity/stored.py +12 -0
- energiapy-2.0.0/src/energia/components/game/__init__.py +0 -0
- energiapy-2.0.0/src/energia/components/game/couple.py +10 -0
- energiapy-2.0.0/src/energia/components/game/player.py +30 -0
- energiapy-2.0.0/src/energia/components/graph/__init__.py +0 -0
- energiapy-2.0.0/src/energia/components/graph/edge.py +29 -0
- energiapy-2.0.0/src/energia/components/graph/node.py +29 -0
- energiapy-2.0.0/src/energia/components/impact/__init__.py +0 -0
- energiapy-2.0.0/src/energia/components/impact/categories.py +21 -0
- energiapy-2.0.0/src/energia/components/impact/indicator.py +24 -0
- energiapy-2.0.0/src/energia/components/measure/__init__.py +0 -0
- energiapy-2.0.0/src/energia/components/measure/unit.py +108 -0
- energiapy-2.0.0/src/energia/components/operation/__init__.py +0 -0
- energiapy-2.0.0/src/energia/components/operation/_operation.py +173 -0
- energiapy-2.0.0/src/energia/components/operation/free.py +0 -0
- energiapy-2.0.0/src/energia/components/operation/process.py +305 -0
- energiapy-2.0.0/src/energia/components/operation/storage.py +186 -0
- energiapy-2.0.0/src/energia/components/operation/trade.py +1 -0
- energiapy-2.0.0/src/energia/components/operation/transport.py +307 -0
- energiapy-2.0.0/src/energia/components/spatial/__init__.py +0 -0
- energiapy-2.0.0/src/energia/components/spatial/linkage.py +119 -0
- energiapy-2.0.0/src/energia/components/spatial/location.py +228 -0
- energiapy-2.0.0/src/energia/components/temporal/__init__.py +0 -0
- energiapy-2.0.0/src/energia/components/temporal/_calendar.py +61 -0
- energiapy-2.0.0/src/energia/components/temporal/lag.py +61 -0
- energiapy-2.0.0/src/energia/components/temporal/modes.py +109 -0
- energiapy-2.0.0/src/energia/components/temporal/periods.py +204 -0
- energiapy-2.0.0/src/energia/components/temporal/scales.py +14 -0
- energiapy-2.0.0/src/energia/core/__init__.py +0 -0
- energiapy-2.0.0/src/energia/core/component.py +92 -0
- energiapy-2.0.0/src/energia/core/dimension.py +47 -0
- energiapy-2.0.0/src/energia/core/name.py +46 -0
- energiapy-2.0.0/src/energia/core/x.py +104 -0
- energiapy-2.0.0/src/energia/dimensions/__init__.py +0 -0
- energiapy-2.0.0/src/energia/dimensions/consequence.py +43 -0
- energiapy-2.0.0/src/energia/dimensions/problem.py +109 -0
- energiapy-2.0.0/src/energia/dimensions/space.py +119 -0
- energiapy-2.0.0/src/energia/dimensions/system.py +60 -0
- energiapy-2.0.0/src/energia/dimensions/time.py +120 -0
- energiapy-2.0.0/src/energia/examples/__init__.py +0 -0
- energiapy-2.0.0/src/energia/examples/energy.py +426 -0
- energiapy-2.0.0/src/energia/library/__init__.py +0 -0
- energiapy-2.0.0/src/energia/library/components.py +116 -0
- energiapy-2.0.0/src/energia/library/decisions.py +276 -0
- energiapy-2.0.0/src/energia/library/processes.py +167 -0
- energiapy-2.0.0/src/energia/modeling/__init__.py +0 -0
- energiapy-2.0.0/src/energia/modeling/constraints/__init__.py +0 -0
- energiapy-2.0.0/src/energia/modeling/constraints/_generator.py +98 -0
- energiapy-2.0.0/src/energia/modeling/constraints/balance.py +283 -0
- energiapy-2.0.0/src/energia/modeling/constraints/bind.py +800 -0
- energiapy-2.0.0/src/energia/modeling/constraints/calculate.py +193 -0
- energiapy-2.0.0/src/energia/modeling/constraints/vmap.py +384 -0
- energiapy-2.0.0/src/energia/modeling/indices/__init__.py +0 -0
- energiapy-2.0.0/src/energia/modeling/indices/domain.py +485 -0
- energiapy-2.0.0/src/energia/modeling/parameters/__init__.py +0 -0
- energiapy-2.0.0/src/energia/modeling/parameters/conversion.py +245 -0
- energiapy-2.0.0/src/energia/modeling/parameters/value.py +33 -0
- energiapy-2.0.0/src/energia/modeling/variables/__init__.py +0 -0
- energiapy-2.0.0/src/energia/modeling/variables/aspect.py +411 -0
- energiapy-2.0.0/src/energia/modeling/variables/control.py +42 -0
- energiapy-2.0.0/src/energia/modeling/variables/default.py +254 -0
- energiapy-2.0.0/src/energia/modeling/variables/impact.py +23 -0
- energiapy-2.0.0/src/energia/modeling/variables/loss.py +24 -0
- energiapy-2.0.0/src/energia/modeling/variables/state.py +51 -0
- energiapy-2.0.0/src/energia/modeling/variables/stream.py +31 -0
- energiapy-2.0.0/src/energia/represent/__init__.py +2 -0
- energiapy-2.0.0/src/energia/represent/blocks.py +571 -0
- energiapy-2.0.0/src/energia/represent/graph.py +60 -0
- energiapy-2.0.0/src/energia/represent/model.py +360 -0
- energiapy-2.0.0/src/energia/represent/program.py +69 -0
- energiapy-2.0.0/src/energia/represent/scenario.py +1 -0
- energiapy-2.0.0/src/energia/utils/__init__.py +0 -0
- energiapy-2.0.0/src/energia/utils/data.py +463 -0
- energiapy-2.0.0/src/energia/utils/decorators.py +13 -0
- energiapy-2.0.0/src/energia/utils/dictionary.py +85 -0
- energiapy-2.0.0/src/energia/utils/math.py +142 -0
- energiapy-2.0.0/src/energia/utils/nsrdb.py +139 -0
- energiapy-2.0.0/src/energia/utils/plot.py +62 -0
- energiapy-2.0.0/src/energia/utils/scaling.py +35 -0
- energiapy-2.0.0/src/energiapy.egg-info/PKG-INFO +244 -0
- energiapy-2.0.0/src/energiapy.egg-info/SOURCES.txt +98 -0
- energiapy-2.0.0/src/energiapy.egg-info/dependency_links.txt +1 -0
- energiapy-2.0.0/src/energiapy.egg-info/requires.txt +29 -0
- energiapy-2.0.0/src/energiapy.egg-info/top_level.txt +2 -0
energiapy-2.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Rahul Kakodkar, Efstratios N. Pistikopoulos
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
energiapy-2.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: energiapy
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: For multiscale modeling and optimization of energy systems
|
|
5
|
+
Author-email: Rahul Kakodkar <cacodcar@gmail.com>, "Efstratios N. Pistikopoulos" <stratos@tamu.edu>
|
|
6
|
+
Maintainer-email: Rahul Kakodkar <cacodcar@gmail.com>
|
|
7
|
+
License: MIT License
|
|
8
|
+
|
|
9
|
+
Copyright (c) 2025 Rahul Kakodkar, Efstratios N. Pistikopoulos
|
|
10
|
+
|
|
11
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
12
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
13
|
+
in the Software without restriction, including without limitation the rights
|
|
14
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
15
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
16
|
+
furnished to do so, subject to the following conditions:
|
|
17
|
+
|
|
18
|
+
The above copyright notice and this permission notice shall be included in all
|
|
19
|
+
copies or substantial portions of the Software.
|
|
20
|
+
|
|
21
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
22
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
23
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
24
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
25
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
26
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
27
|
+
SOFTWARE.
|
|
28
|
+
|
|
29
|
+
Project-URL: Homepage, https://github.com/TAMUparametric/energiapy
|
|
30
|
+
Project-URL: Issues, https://github.com/TAMUparametric/energiapy/issues
|
|
31
|
+
Keywords: modeling,optimization,energy systems,ems,multiscale
|
|
32
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
33
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
34
|
+
Classifier: Operating System :: OS Independent
|
|
35
|
+
Requires-Python: >=3.13
|
|
36
|
+
Description-Content-Type: text/markdown
|
|
37
|
+
License-File: LICENSE
|
|
38
|
+
Requires-Dist: gana
|
|
39
|
+
Requires-Dist: ppopt
|
|
40
|
+
Requires-Dist: matplotlib
|
|
41
|
+
Requires-Dist: scipy
|
|
42
|
+
Requires-Dist: pandas
|
|
43
|
+
Requires-Dist: numpy
|
|
44
|
+
Requires-Dist: gurobipy
|
|
45
|
+
Provides-Extra: all
|
|
46
|
+
Requires-Dist: pvlib; extra == "all"
|
|
47
|
+
Requires-Dist: windpowerlib; extra == "all"
|
|
48
|
+
Requires-Dist: h5pyd; extra == "all"
|
|
49
|
+
Provides-Extra: test
|
|
50
|
+
Requires-Dist: coverage; extra == "test"
|
|
51
|
+
Requires-Dist: pytest; extra == "test"
|
|
52
|
+
Requires-Dist: hypothesis; extra == "test"
|
|
53
|
+
Provides-Extra: docs
|
|
54
|
+
Requires-Dist: sphinx; extra == "docs"
|
|
55
|
+
Requires-Dist: sphinx-book-theme; extra == "docs"
|
|
56
|
+
Requires-Dist: nbsphinx; extra == "docs"
|
|
57
|
+
Requires-Dist: sphinx_mdinclude; extra == "docs"
|
|
58
|
+
Requires-Dist: myst-nb; extra == "docs"
|
|
59
|
+
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
|
|
60
|
+
Requires-Dist: sphinx-copybutton; extra == "docs"
|
|
61
|
+
Requires-Dist: sphinx-togglebutton; extra == "docs"
|
|
62
|
+
Requires-Dist: numpydoc; extra == "docs"
|
|
63
|
+
Requires-Dist: linkify; extra == "docs"
|
|
64
|
+
Dynamic: license-file
|
|
65
|
+
|
|
66
|
+
<p align="center">
|
|
67
|
+
<img src="https://github.com/TAMUparametric/energiapy/raw/main/docs/_static/logo2.jpg" width="75%">
|
|
68
|
+
</p>
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
[](https://energiapy.readthedocs.io/en/latest/)
|
|
72
|
+
[](https://pypi.org/project/energiapy)
|
|
73
|
+
[](https://pepy.tech/project/energiapy)
|
|
74
|
+
[](https://github.com/TAMUparametric/energiapy/actions/workflows/python-package.yml)
|
|
75
|
+
<!-- [](https://app.codacy.com/gh/TAMUparametric/energiapy/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) -->
|
|
76
|
+
|
|
77
|
+
Energia is a tool for the data-driven multiscale modeling and optimization of energy systems under uncertainty. Users are directed to {cite}`kakodkar2022review` for an overview of the state-of-the-art in the field.
|
|
78
|
+
The component-driven methodology is inspired by the resource task network (RTN) methodology {cite}`barbosa_povoa_pantelides_1997` and constituent functionalities developed through the research conducted in
|
|
79
|
+
the [Multiparameteric Optimization and Control (Pistikopoulos) Group](https://parametric.tamu.edu/).
|
|
80
|
+
|
|
81
|
+
:::{seealso}
|
|
82
|
+
[Gana](https://gana.readthedocs.io/en/latest/), an Algebraic Modeling Language (AML) for Multiscale Modeling and Optimization which serves as the backend
|
|
83
|
+
:::
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
# Installation
|
|
87
|
+
|
|
88
|
+
Energia can be installed using the standard pip installation. It is recommended to install the package in a separate
|
|
89
|
+
conda or pip environment.
|
|
90
|
+
|
|
91
|
+
Create and activate a pip environment
|
|
92
|
+
|
|
93
|
+
python3.13 -m venv energiaenv
|
|
94
|
+
.\energiaenv\Scripts\activate
|
|
95
|
+
|
|
96
|
+
Or,
|
|
97
|
+
|
|
98
|
+
Create and activate a conda environment
|
|
99
|
+
|
|
100
|
+
conda create --name energiaenv python=3.13
|
|
101
|
+
conda activate energiaenv
|
|
102
|
+
|
|
103
|
+
Install energiapy
|
|
104
|
+
|
|
105
|
+
pip install energiapy
|
|
106
|
+
|
|
107
|
+
For the most updated (albeit occassionally unstable) version use
|
|
108
|
+
|
|
109
|
+
pip install git+https://github.com/TAMUparametric/energiapy
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
# Components
|
|
113
|
+
|
|
114
|
+
```Model``` is the primary central object which aggregate components based on a broader
|
|
115
|
+
perspective of what they describe, namely Scope (```Time```, ```Space```), ```System``` , ```Consequence```, ```Problem```.
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
**Scope** which defines the extent of the system under consideration, and the fidelity of data.
|
|
119
|
+
|
|
120
|
+
1. ```Time```, with ```Periods``` and ```TemporalScales``` defining the discretization
|
|
121
|
+
2. ```Space```, with ```Location``` and ```Linkage``` serving as nodes and edges
|
|
122
|
+
|
|
123
|
+
The most sparsely discretized ```Periods``` serves as the temporal ```horizon```, and the most encompassing ```Location``` (which are nested) is the ```network```
|
|
124
|
+
|
|
125
|
+
**Streams** which scale the domains of the system via operations.
|
|
126
|
+
|
|
127
|
+
3. ```Commodity``` which includes ```Resource```, and subsets ```Currency```, ```Land```, ```Emission```, ```Material```, etc.
|
|
128
|
+
4. ```Indicator``` categories such as ```Environ```, ```Social```, and ```Economic```
|
|
129
|
+
|
|
130
|
+
```Commodity``` streams belong to ```System```, whereas ```Indicators``` inform the ```Consequence```.
|
|
131
|
+
|
|
132
|
+
**Operational** components, decisions pertaining to which generate and direct ```Commodity``` streams.
|
|
133
|
+
|
|
134
|
+
5. ```Process``` for commodity conversion
|
|
135
|
+
6. ```Transport``` to import and export certain commodities
|
|
136
|
+
7. ```Storage``` to charge and discharge inventory
|
|
137
|
+
|
|
138
|
+
```Storage``` is actually a combination of two ```Process``` objects (for charging and discharging) and ```Inventory``` space.
|
|
139
|
+
|
|
140
|
+
**Game** components suggest ownership and strategic interactions between independent actors.
|
|
141
|
+
|
|
142
|
+
8. ```Player``` is an independent actor
|
|
143
|
+
9. ```Couple``` represents a link between two ```Player```s
|
|
144
|
+
|
|
145
|
+
**Aspect**s are the facets being modeled.
|
|
146
|
+
|
|
147
|
+
These generate variables:
|
|
148
|
+
|
|
149
|
+
10. ```State``` (in Energia) are restricted to operational conditions
|
|
150
|
+
11. ```Control``` or decision variables
|
|
151
|
+
12. ```Stream```, also a ```State``` that quantify ```Commodity``` streams
|
|
152
|
+
13. ```Impact``` which quantify ```Indicator``` streams
|
|
153
|
+
14. ```Loss```, a general variable to describe loss and (or) degradation
|
|
154
|
+
|
|
155
|
+
Note that users can choose to model sans ```Control``` variables and model ```State``` directly.
|
|
156
|
+
|
|
157
|
+
**Constraints**
|
|
158
|
+
|
|
159
|
+
Data provided either:
|
|
160
|
+
|
|
161
|
+
15. ```Bind``` or restrict any given ```Aspect```
|
|
162
|
+
or
|
|
163
|
+
16. ```Calculate``` a dependent ```Aspect``` such as ```Stream```, ```Impact```, or ```Loss```
|
|
164
|
+
|
|
165
|
+
Consistency is maintained by generating implicit constraints:
|
|
166
|
+
|
|
167
|
+
17. ```Balance``` for general resource balance
|
|
168
|
+
and
|
|
169
|
+
18. ```Map``` to scale and sum streams across spatiotemporal domains
|
|
170
|
+
|
|
171
|
+
**Parameters**
|
|
172
|
+
|
|
173
|
+
No special parameter types exist of bind and calculations. However,:
|
|
174
|
+
|
|
175
|
+
19. ```Conversion``` serves as general parameter that dictates conversion efficiency and material use for setup
|
|
176
|
+
|
|
177
|
+
**Disposition** describes both the fidelity and specificity of a modeling element.
|
|
178
|
+
|
|
179
|
+
20. ```Domain``` is an ordered index set
|
|
180
|
+
|
|
181
|
+
**Objectives**
|
|
182
|
+
|
|
183
|
+
Multiple objectives can be provided. Infact the lower and upperbounds of any ```Aspect``` with regards to a specific component within some spatiotemporal context
|
|
184
|
+
can be determined.
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
<!--  -->
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
# Application
|
|
192
|
+
|
|
193
|
+
Models can also simultaneously perform the following analyses under an integrated paradigm:
|
|
194
|
+
|
|
195
|
+
- Multiperiod Multiscale Design and Scheduling {cite}`kakodkar2023hydrogen,kakodkar2024multiperiod`
|
|
196
|
+
- Modeling the Material-Energy-Mobility Nexus {cite}`montano2025modeling,flores2025integrating`
|
|
197
|
+
- Carbon Accounting and Life Cycle Assessment Under Uncertainty {cite}`sousa2025integrating,de2025integrated`
|
|
198
|
+
- Robust Scheduling Using Multiparametric Programming {cite}`kakodkar2024robust`
|
|
199
|
+
- Resilience Analysis of Distributed Energy and Manufacturing Systems {cite}`vedant2024information`
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
# Select Features
|
|
203
|
+
|
|
204
|
+
Available constraints are able to model:
|
|
205
|
+
|
|
206
|
+
1. network design (with discrete choice)
|
|
207
|
+
2. resource flows
|
|
208
|
+
3. inventory balance
|
|
209
|
+
4. emission and costing calculations
|
|
210
|
+
5. environmental, social, and economic impact
|
|
211
|
+
6. material and land use for infrastructure development
|
|
212
|
+
7. nonlinear behavior modeling using piece-wise linear curves
|
|
213
|
+
8. transportation
|
|
214
|
+
9. failure and loss
|
|
215
|
+
|
|
216
|
+
Examples of objectives towards which the model can be optimized include:
|
|
217
|
+
|
|
218
|
+
1. minimizing cost
|
|
219
|
+
2. minimizing impact
|
|
220
|
+
3. maximizing resource discharge
|
|
221
|
+
|
|
222
|
+
Large scenarios can be aggregated using the following available techniques:
|
|
223
|
+
|
|
224
|
+
1. agglomerative hierarchial clustering (AHC)
|
|
225
|
+
2. dynamic time warping (DTW)
|
|
226
|
+
|
|
227
|
+
Both the input data and solution output can be illustrated, examples include:
|
|
228
|
+
|
|
229
|
+
1. input data: capacity, demand, cost factors
|
|
230
|
+
2. solution output: inventory, production, consumption, discharge/sales schedule; contribution towards costs (capital,
|
|
231
|
+
variable and fixed operational), meeting demand.
|
|
232
|
+
|
|
233
|
+
Other (and optional) features include:
|
|
234
|
+
|
|
235
|
+
1. math utilities for calculating euclidean distances, generation connectivity matrices, etc.
|
|
236
|
+
2. generating dataframes with missing data fixed (weekends, public holidays) for time-series data such as resource price
|
|
237
|
+
3. function to fetch weather data at an appropriate resolution from [NREL NSRDB](https://nsrdb.nrel.gov/) for any county
|
|
238
|
+
in the US
|
|
239
|
+
4. latex constraints writer for model documentation
|
|
240
|
+
|
|
241
|
+
Direct any communication to Rahul Kakodkar (cacodcar@gmail.com)
|
|
242
|
+
|
|
243
|
+
# References
|
|
244
|
+
```{bibliography}
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://github.com/TAMUparametric/energiapy/raw/main/docs/_static/logo2.jpg" width="75%">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
[](https://energiapy.readthedocs.io/en/latest/)
|
|
7
|
+
[](https://pypi.org/project/energiapy)
|
|
8
|
+
[](https://pepy.tech/project/energiapy)
|
|
9
|
+
[](https://github.com/TAMUparametric/energiapy/actions/workflows/python-package.yml)
|
|
10
|
+
<!-- [](https://app.codacy.com/gh/TAMUparametric/energiapy/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) -->
|
|
11
|
+
|
|
12
|
+
Energia is a tool for the data-driven multiscale modeling and optimization of energy systems under uncertainty. Users are directed to {cite}`kakodkar2022review` for an overview of the state-of-the-art in the field.
|
|
13
|
+
The component-driven methodology is inspired by the resource task network (RTN) methodology {cite}`barbosa_povoa_pantelides_1997` and constituent functionalities developed through the research conducted in
|
|
14
|
+
the [Multiparameteric Optimization and Control (Pistikopoulos) Group](https://parametric.tamu.edu/).
|
|
15
|
+
|
|
16
|
+
:::{seealso}
|
|
17
|
+
[Gana](https://gana.readthedocs.io/en/latest/), an Algebraic Modeling Language (AML) for Multiscale Modeling and Optimization which serves as the backend
|
|
18
|
+
:::
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
# Installation
|
|
22
|
+
|
|
23
|
+
Energia can be installed using the standard pip installation. It is recommended to install the package in a separate
|
|
24
|
+
conda or pip environment.
|
|
25
|
+
|
|
26
|
+
Create and activate a pip environment
|
|
27
|
+
|
|
28
|
+
python3.13 -m venv energiaenv
|
|
29
|
+
.\energiaenv\Scripts\activate
|
|
30
|
+
|
|
31
|
+
Or,
|
|
32
|
+
|
|
33
|
+
Create and activate a conda environment
|
|
34
|
+
|
|
35
|
+
conda create --name energiaenv python=3.13
|
|
36
|
+
conda activate energiaenv
|
|
37
|
+
|
|
38
|
+
Install energiapy
|
|
39
|
+
|
|
40
|
+
pip install energiapy
|
|
41
|
+
|
|
42
|
+
For the most updated (albeit occassionally unstable) version use
|
|
43
|
+
|
|
44
|
+
pip install git+https://github.com/TAMUparametric/energiapy
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
# Components
|
|
48
|
+
|
|
49
|
+
```Model``` is the primary central object which aggregate components based on a broader
|
|
50
|
+
perspective of what they describe, namely Scope (```Time```, ```Space```), ```System``` , ```Consequence```, ```Problem```.
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
**Scope** which defines the extent of the system under consideration, and the fidelity of data.
|
|
54
|
+
|
|
55
|
+
1. ```Time```, with ```Periods``` and ```TemporalScales``` defining the discretization
|
|
56
|
+
2. ```Space```, with ```Location``` and ```Linkage``` serving as nodes and edges
|
|
57
|
+
|
|
58
|
+
The most sparsely discretized ```Periods``` serves as the temporal ```horizon```, and the most encompassing ```Location``` (which are nested) is the ```network```
|
|
59
|
+
|
|
60
|
+
**Streams** which scale the domains of the system via operations.
|
|
61
|
+
|
|
62
|
+
3. ```Commodity``` which includes ```Resource```, and subsets ```Currency```, ```Land```, ```Emission```, ```Material```, etc.
|
|
63
|
+
4. ```Indicator``` categories such as ```Environ```, ```Social```, and ```Economic```
|
|
64
|
+
|
|
65
|
+
```Commodity``` streams belong to ```System```, whereas ```Indicators``` inform the ```Consequence```.
|
|
66
|
+
|
|
67
|
+
**Operational** components, decisions pertaining to which generate and direct ```Commodity``` streams.
|
|
68
|
+
|
|
69
|
+
5. ```Process``` for commodity conversion
|
|
70
|
+
6. ```Transport``` to import and export certain commodities
|
|
71
|
+
7. ```Storage``` to charge and discharge inventory
|
|
72
|
+
|
|
73
|
+
```Storage``` is actually a combination of two ```Process``` objects (for charging and discharging) and ```Inventory``` space.
|
|
74
|
+
|
|
75
|
+
**Game** components suggest ownership and strategic interactions between independent actors.
|
|
76
|
+
|
|
77
|
+
8. ```Player``` is an independent actor
|
|
78
|
+
9. ```Couple``` represents a link between two ```Player```s
|
|
79
|
+
|
|
80
|
+
**Aspect**s are the facets being modeled.
|
|
81
|
+
|
|
82
|
+
These generate variables:
|
|
83
|
+
|
|
84
|
+
10. ```State``` (in Energia) are restricted to operational conditions
|
|
85
|
+
11. ```Control``` or decision variables
|
|
86
|
+
12. ```Stream```, also a ```State``` that quantify ```Commodity``` streams
|
|
87
|
+
13. ```Impact``` which quantify ```Indicator``` streams
|
|
88
|
+
14. ```Loss```, a general variable to describe loss and (or) degradation
|
|
89
|
+
|
|
90
|
+
Note that users can choose to model sans ```Control``` variables and model ```State``` directly.
|
|
91
|
+
|
|
92
|
+
**Constraints**
|
|
93
|
+
|
|
94
|
+
Data provided either:
|
|
95
|
+
|
|
96
|
+
15. ```Bind``` or restrict any given ```Aspect```
|
|
97
|
+
or
|
|
98
|
+
16. ```Calculate``` a dependent ```Aspect``` such as ```Stream```, ```Impact```, or ```Loss```
|
|
99
|
+
|
|
100
|
+
Consistency is maintained by generating implicit constraints:
|
|
101
|
+
|
|
102
|
+
17. ```Balance``` for general resource balance
|
|
103
|
+
and
|
|
104
|
+
18. ```Map``` to scale and sum streams across spatiotemporal domains
|
|
105
|
+
|
|
106
|
+
**Parameters**
|
|
107
|
+
|
|
108
|
+
No special parameter types exist of bind and calculations. However,:
|
|
109
|
+
|
|
110
|
+
19. ```Conversion``` serves as general parameter that dictates conversion efficiency and material use for setup
|
|
111
|
+
|
|
112
|
+
**Disposition** describes both the fidelity and specificity of a modeling element.
|
|
113
|
+
|
|
114
|
+
20. ```Domain``` is an ordered index set
|
|
115
|
+
|
|
116
|
+
**Objectives**
|
|
117
|
+
|
|
118
|
+
Multiple objectives can be provided. Infact the lower and upperbounds of any ```Aspect``` with regards to a specific component within some spatiotemporal context
|
|
119
|
+
can be determined.
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
<!--  -->
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
# Application
|
|
127
|
+
|
|
128
|
+
Models can also simultaneously perform the following analyses under an integrated paradigm:
|
|
129
|
+
|
|
130
|
+
- Multiperiod Multiscale Design and Scheduling {cite}`kakodkar2023hydrogen,kakodkar2024multiperiod`
|
|
131
|
+
- Modeling the Material-Energy-Mobility Nexus {cite}`montano2025modeling,flores2025integrating`
|
|
132
|
+
- Carbon Accounting and Life Cycle Assessment Under Uncertainty {cite}`sousa2025integrating,de2025integrated`
|
|
133
|
+
- Robust Scheduling Using Multiparametric Programming {cite}`kakodkar2024robust`
|
|
134
|
+
- Resilience Analysis of Distributed Energy and Manufacturing Systems {cite}`vedant2024information`
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
# Select Features
|
|
138
|
+
|
|
139
|
+
Available constraints are able to model:
|
|
140
|
+
|
|
141
|
+
1. network design (with discrete choice)
|
|
142
|
+
2. resource flows
|
|
143
|
+
3. inventory balance
|
|
144
|
+
4. emission and costing calculations
|
|
145
|
+
5. environmental, social, and economic impact
|
|
146
|
+
6. material and land use for infrastructure development
|
|
147
|
+
7. nonlinear behavior modeling using piece-wise linear curves
|
|
148
|
+
8. transportation
|
|
149
|
+
9. failure and loss
|
|
150
|
+
|
|
151
|
+
Examples of objectives towards which the model can be optimized include:
|
|
152
|
+
|
|
153
|
+
1. minimizing cost
|
|
154
|
+
2. minimizing impact
|
|
155
|
+
3. maximizing resource discharge
|
|
156
|
+
|
|
157
|
+
Large scenarios can be aggregated using the following available techniques:
|
|
158
|
+
|
|
159
|
+
1. agglomerative hierarchial clustering (AHC)
|
|
160
|
+
2. dynamic time warping (DTW)
|
|
161
|
+
|
|
162
|
+
Both the input data and solution output can be illustrated, examples include:
|
|
163
|
+
|
|
164
|
+
1. input data: capacity, demand, cost factors
|
|
165
|
+
2. solution output: inventory, production, consumption, discharge/sales schedule; contribution towards costs (capital,
|
|
166
|
+
variable and fixed operational), meeting demand.
|
|
167
|
+
|
|
168
|
+
Other (and optional) features include:
|
|
169
|
+
|
|
170
|
+
1. math utilities for calculating euclidean distances, generation connectivity matrices, etc.
|
|
171
|
+
2. generating dataframes with missing data fixed (weekends, public holidays) for time-series data such as resource price
|
|
172
|
+
3. function to fetch weather data at an appropriate resolution from [NREL NSRDB](https://nsrdb.nrel.gov/) for any county
|
|
173
|
+
in the US
|
|
174
|
+
4. latex constraints writer for model documentation
|
|
175
|
+
|
|
176
|
+
Direct any communication to Rahul Kakodkar (cacodcar@gmail.com)
|
|
177
|
+
|
|
178
|
+
# References
|
|
179
|
+
```{bibliography}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>61"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "energiapy"
|
|
7
|
+
version = "2.0.0"
|
|
8
|
+
authors = [
|
|
9
|
+
{ name="Rahul Kakodkar", email="cacodcar@gmail.com" },
|
|
10
|
+
{name = "Efstratios N. Pistikopoulos", email = "stratos@tamu.edu"}
|
|
11
|
+
]
|
|
12
|
+
maintainers = [
|
|
13
|
+
{ name="Rahul Kakodkar", email="cacodcar@gmail.com" },
|
|
14
|
+
]
|
|
15
|
+
description = "For multiscale modeling and optimization of energy systems"
|
|
16
|
+
requires-python = ">=3.13"
|
|
17
|
+
readme = "README.md"
|
|
18
|
+
license = { file = "LICENSE" }
|
|
19
|
+
keywords = ["modeling", "optimization", "energy systems", "ems", "multiscale"]
|
|
20
|
+
classifiers = [
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"License :: OSI Approved :: MIT License",
|
|
23
|
+
"Operating System :: OS Independent",
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
dependencies = ["gana", "ppopt", "matplotlib", "scipy", "pandas", "numpy", "gurobipy"]
|
|
27
|
+
|
|
28
|
+
[project.optional-dependencies]
|
|
29
|
+
all = ["pvlib", "windpowerlib", "h5pyd"]
|
|
30
|
+
test = ["coverage", "pytest", "hypothesis"]
|
|
31
|
+
docs = [
|
|
32
|
+
"sphinx",
|
|
33
|
+
"sphinx-book-theme",
|
|
34
|
+
"nbsphinx",
|
|
35
|
+
"sphinx_mdinclude",
|
|
36
|
+
"myst-nb",
|
|
37
|
+
"sphinxcontrib-bibtex",
|
|
38
|
+
"sphinx-copybutton",
|
|
39
|
+
"sphinx-togglebutton",
|
|
40
|
+
"numpydoc",
|
|
41
|
+
"linkify"
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
[project.urls]
|
|
47
|
+
Homepage = "https://github.com/TAMUparametric/energiapy"
|
|
48
|
+
Issues = "https://github.com/TAMUparametric/energiapy/issues"
|
|
File without changes
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
"""Energia Imports"""
|
|
2
|
+
|
|
3
|
+
from .components.commodity.currency import Currency
|
|
4
|
+
from .components.commodity.land import Land
|
|
5
|
+
from .components.commodity.material import Material
|
|
6
|
+
from .components.commodity.resource import Resource
|
|
7
|
+
from .components.game.player import Player
|
|
8
|
+
from .components.impact.categories import Economic, Environ, Social
|
|
9
|
+
from .components.measure.unit import Unit
|
|
10
|
+
from .components.operation.process import Process
|
|
11
|
+
from .components.operation.storage import Storage
|
|
12
|
+
from .components.operation.transport import Transport
|
|
13
|
+
from .components.spatial.linkage import Linkage
|
|
14
|
+
from .components.spatial.location import Location
|
|
15
|
+
from .components.temporal.periods import Periods
|
|
16
|
+
from .components.temporal.scales import TemporalScales
|
|
17
|
+
from .represent.model import Model
|
|
18
|
+
|
|
19
|
+
__all__ = [
|
|
20
|
+
"Currency",
|
|
21
|
+
"Economic",
|
|
22
|
+
"Environ",
|
|
23
|
+
"Land",
|
|
24
|
+
"Linkage",
|
|
25
|
+
"Location",
|
|
26
|
+
"Material",
|
|
27
|
+
"Model",
|
|
28
|
+
"Periods",
|
|
29
|
+
"Player",
|
|
30
|
+
"Process",
|
|
31
|
+
"Resource",
|
|
32
|
+
"Social",
|
|
33
|
+
"Storage",
|
|
34
|
+
"TemporalScales",
|
|
35
|
+
"Transport",
|
|
36
|
+
"Unit",
|
|
37
|
+
]
|
|
38
|
+
__version__ = "2.0.0"
|
|
File without changes
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
"""Commodity Base Class"""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
from typing import Self
|
|
5
|
+
|
|
6
|
+
from ...core.component import Component
|
|
7
|
+
from ...modeling.parameters.conversion import Conversion
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
@dataclass
|
|
11
|
+
class _Commodity(Component):
|
|
12
|
+
"""A commodity, can be a material, chemical, energy, etc.
|
|
13
|
+
|
|
14
|
+
Args:
|
|
15
|
+
label (str): Label of the commodity, used for plotting. Defaults to None.
|
|
16
|
+
name (str): Name of the commodity, used for indexing. Defaults to None.
|
|
17
|
+
basis (Unit): Unit basis of the commodity. Defaults to None.
|
|
18
|
+
|
|
19
|
+
Attributes:
|
|
20
|
+
conversions (list[Conv]): List of conversions associated with the commodity. Defaults to [].
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
def __post_init__(self):
|
|
24
|
+
Component.__post_init__(self)
|
|
25
|
+
|
|
26
|
+
# list of conversions associated with the commodity
|
|
27
|
+
self.conversions: list[Conversion] = []
|
|
28
|
+
|
|
29
|
+
# flag indicates whether the commodity is produced and expended insitu only
|
|
30
|
+
self.insitu = False
|
|
31
|
+
|
|
32
|
+
@property
|
|
33
|
+
def conversion(self) -> dict[Conversion, int | float]:
|
|
34
|
+
"""Conversion"""
|
|
35
|
+
# if no conversion is set, return 1.0
|
|
36
|
+
if not self.conversions:
|
|
37
|
+
return {self: 1.0}
|
|
38
|
+
# if there is a conversion, return its parameter in all tasks its
|
|
39
|
+
# associated with
|
|
40
|
+
return {task: task.conversion[self] for task in self.conversions}
|
|
41
|
+
|
|
42
|
+
def __setattr__(self, name, value):
|
|
43
|
+
|
|
44
|
+
if isinstance(value, Conversion):
|
|
45
|
+
# update conversions
|
|
46
|
+
self.conversions.append(value)
|
|
47
|
+
|
|
48
|
+
super().__setattr__(name, value)
|
|
49
|
+
|
|
50
|
+
def __mul__(self, other: int | float) -> Conversion:
|
|
51
|
+
# multiplying a number with a resources gives conversion
|
|
52
|
+
# math operations with conversions form the balance in tasks
|
|
53
|
+
conv = Conversion()
|
|
54
|
+
conv.conversion = {self: other}
|
|
55
|
+
return conv
|
|
56
|
+
|
|
57
|
+
def __rmul__(self, other: int | float) -> Conversion:
|
|
58
|
+
# reverse multiplication
|
|
59
|
+
return self * other
|
|
60
|
+
|
|
61
|
+
def __add__(self, other: Conversion) -> Conversion:
|
|
62
|
+
conv = Conversion()
|
|
63
|
+
if isinstance(other, _Commodity):
|
|
64
|
+
# if another resource is added, give it the parameter 1
|
|
65
|
+
conv.conversion = {self: 1, other: 1}
|
|
66
|
+
return conv
|
|
67
|
+
|
|
68
|
+
# if added with another conversion, updated the balance
|
|
69
|
+
conv.conversion = {self: 1, **other.conversion}
|
|
70
|
+
return conv
|
|
71
|
+
|
|
72
|
+
def __neg__(self) -> Conversion:
|
|
73
|
+
# just multiply by -1
|
|
74
|
+
return self * -1
|
|
75
|
+
|
|
76
|
+
def __sub__(self, other: Conversion | Self):
|
|
77
|
+
if isinstance(other, _Commodity):
|
|
78
|
+
# if another resource is subtracted
|
|
79
|
+
# give it the parameter -1
|
|
80
|
+
return self + -1 * other
|
|
81
|
+
if isinstance(other, Conversion):
|
|
82
|
+
# if another conversion is subtracted, update the balance
|
|
83
|
+
conv = Conversion()
|
|
84
|
+
|
|
85
|
+
conv.conversion = {
|
|
86
|
+
self: 1,
|
|
87
|
+
**{
|
|
88
|
+
res: (
|
|
89
|
+
-1 * par if isinstance(par, (int, float)) else [-i for i in par]
|
|
90
|
+
)
|
|
91
|
+
for res, par in other.conversion.items()
|
|
92
|
+
},
|
|
93
|
+
}
|
|
94
|
+
return conv
|
|
95
|
+
|
|
96
|
+
def __truediv__(self, other: int | float):
|
|
97
|
+
# treat division as multiplication by the inverse
|
|
98
|
+
return self * (1 / other)
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
"""Currency"""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
|
|
5
|
+
from operator import is_
|
|
6
|
+
from typing import Self
|
|
7
|
+
|
|
8
|
+
# from ..operation.task import Task
|
|
9
|
+
from ...modeling.variables.default import Transact
|
|
10
|
+
|
|
11
|
+
# from ..impact.categories import Eco
|
|
12
|
+
from ._commodity import _Commodity
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass
|
|
16
|
+
class Currency(_Commodity, Transact):
|
|
17
|
+
"""Same as Economic Impact (Eco)"""
|
|
18
|
+
|
|
19
|
+
def __post_init__(self):
|
|
20
|
+
_Commodity.__post_init__(self)
|
|
21
|
+
|
|
22
|
+
def howmany(self, cash: Self):
|
|
23
|
+
"""Exchange rate basically"""
|
|
24
|
+
|
|
25
|
+
if is_(cash, self):
|
|
26
|
+
return 1
|
|
27
|
+
if cash in self.conversion:
|
|
28
|
+
return self.conversion[cash]
|
|
29
|
+
# find a common currency
|
|
30
|
+
if list(self.conversion)[0] == list(cash.conversion)[0]:
|
|
31
|
+
return (
|
|
32
|
+
self.conversion[list(self.conversion)[0]]
|
|
33
|
+
/ cash.conversion[list(cash.conversion)[0]]
|
|
34
|
+
)
|
|
35
|
+
raise ValueError(f'{cash} does not have an exchange rate set {self.name}')
|