# Device Kit
`device_kit` is a Python package containing a collection of scalar vector flow device models for convex optimal flow simulations. The package defines a common abstract interface for a device, a base set of concrete devices, and a way of constructing new aggregate devices from collection of related sub-devices. Under the hood it's a big 2d numpy array, with discrete time slot along one dimension, and leaf device along the other. `device_kit` makes it easier to express and manage the constraints and cost functions, and solve the system.
The `device_kit` was originally written for the purpose modeling controllable microgrid or household electrical devices, and then optimizing flows over a day-ahead time horizon.
<table>
<tr>
<td width="50%" style="vertical-align: top;">
<figure>
<a name='f1'><img width='400px' name='f1' src='docs/img/uml-cd.png'/></a><br/>
<small>The core classes of `device_kit`. Most the model complexity is in sub classes of `Device`. A handful of sub-types are provided in this package such as `IDevice`. `DeviceSet` connects a network of devices. </small>
</figure>
</td>
<td width="50%" style="vertical-align: top;">
<figure>
<a name='f2'><img width='400px' name='f2' src='docs/img/tree-of-smart-homes-op-e-phys.jpg'/></a><br/>
<small>Example radial microgrid model-able with `device_kit`.</small>
</figure>
</td>
</tr>
<tr>
<td width="50%" style="vertical-align: top;">
<figure>
<a name='f3'><img width='400px' name='f1' src='docs/img/lcl-scenario-home5-9b94d3e.gif'/></a><br/>
<small>Example microgrid connection home simulation from unoptimized to optimized.</small>
</figure>
</td>
<td width="50%" style="vertical-align: top;">
<figure>
<a name='f4'><img width='400px' name='f2' src='docs/img/aircon-scenario.gif'/></a><br/>
<small>Example aircon utility based simulation from unoptimized to optimized. Temperature goes up as cost goes down. Utility curve varies between aircon scenarios.</small>
</figure>
</td>
</tr>
</table>
# Installation
```
pip install "git+https://github.com/sgpinkus/microgrid_device_kit"`
```
# Synopsis
A simple example of using `device_kit` to model a collection of devices and then solve for some constraint over the joint flows - most commonly balanced flows:
```python
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import device_kit
from device_kit import *
def random_uncontrolled():
return np.maximum(0, 0.5+np.cumsum(np.random.uniform(-1,1, 24)))
def generator_cost_curve():
return np.stack((np.sin(np.linspace(0, np.pi, 24))*0.5+0.1, np.ones(24)*0.001, np.zeros(24)), axis=1)
def make_model():
''' Small power network model. '''
np.random.seed(19)
model = DeviceSet('site1', [
Device('uncontrolled', 24, (random_uncontrolled(),)),
IDevice2('scalable', 24, (0.5, 2), (0, 24), d0=0.3),
CDevice('shiftable', 24, (0, 2), (12, 24)),
GDevice('generator', 24, (-10,0), cbounds=None, cost_coeffs=generator_cost_curve()),
DeviceSet('sub-site1', [
Device('uncontrolled', 24, (random_uncontrolled(),)),
SDevice('buffer', 24, (-7, 7), c1=1.0, capacity=70, sustainment=1, efficiency=1)
],
sbounds=(0,10) # max capacity constraint.
),
],
sbounds=(0,0) # balanced flow constraint.
)
return model
def main():
model = make_model()
(x, solve_meta) = device_kit.solve(model, p=0) # Convenience convex solver.
print(solve_meta.message)
df = pd.DataFrame.from_dict(dict(model.map(x)), orient='index')
df.loc['total'] = df.sum()
pd.set_option('display.float_format', lambda v: '%+0.3f' % (v,),)
print(df.sort_index())
print('Utility: ', model.cost(x, p=0))
df.transpose().plot(drawstyle='steps', grid=True)
plt.ylabel('Power (kWh)')
plt.xlabel('Time (H)')
plt.savefig('synopsis.png');
if __name__ == '__main__':
main()
```
Gives:
```
Optimization terminated successfully
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
site1.generator -3.850 -2.744 -1.964 -1.630 -1.303 -1.455 -0.991 -1.040 -1.084 -1.140 -0.927 -0.770 -0.770 -0.783 -0.808 -0.848 -0.907 -0.991 -1.110 -1.282 -1.542 -1.964 -2.698 -3.249
site1.scalable +0.991 +0.664 +0.663 +0.551 +0.632 +0.500 +0.664 +0.500 +0.500 +0.500 +0.500 +0.663 +0.663 +0.663 +0.663 +0.663 +0.664 +0.664 +0.664 +0.664 +0.664 +0.663 +0.698 +1.249
site1.shiftable +2.000 +0.793 +0.696 +0.000 +0.000 +0.000 +0.100 +0.000 +0.000 +0.000 +0.000 +0.108 +0.108 +0.120 +0.145 +0.119 +0.244 +0.327 +0.446 +0.618 +0.878 +1.301 +2.000 +2.000
site1.sub-site1.buffer +0.128 +0.052 +0.052 +0.026 +0.044 -0.091 +0.052 -0.015 -0.076 -0.138 -0.033 -0.000 -0.000 -0.000 -0.000 -0.000 -0.000 -0.000 -0.000 -0.000 -0.000 -0.000 +0.000 -0.000
site1.sub-site1.uncontrolled +0.730 +1.016 +0.553 +1.054 +0.627 +1.046 +0.176 +0.555 +0.660 +0.767 +0.460 +0.000 +0.000 +0.000 +0.000 +0.066 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000
site1.uncontrolled +0.000 +0.218 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.011 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000
total +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000
Utility: -13.021871014972055
```
<table>
<tr>
<td width="50%" style="vertical-align: top;">
<figure>
<a name='f3'><img width='400px' name='f1' src='scripts/synopsis.png'/></a><br/>
<small>Output plot.</small>
</figure>
</td>
</tr>
</table>
# Overview
In the scope of this package, a device is something that consumes and/or produces some kind of scalar valued commodity (ex. electricity, gas, fluid) over a fixed, discrete, and finite future planning/scheduling horizon (ex. every hour of the next day, or every minute of the next hour, etc). For each device what is modeled is simply:
1. The non-negotiable hard constraints on the commodity *flow* to/from the device.
2. Costs (or soft constraints) for different feasible states of flow to/from the device.
All the concrete device models provided are currently all weakly convex and tune-able. The concrete set of device implementations can be used to model quite a wide range of scenarios within the bounds of convexity.
Low level devices exist in a network which acts as a conduit for commodity flow between devices (ex. an electrical bus). This package is limited (by design) to modeling radially structured (in other words, *rooted tree* structured) networks to an arbitrary nesting level (the simple flow networks we're interested in modeling have a radial structure or can be treated as such at the level of abstraction we're interested in). "Networks" are implemented as composite devices containing other atomic or composite devices, down to some eventual leaf node device level (<a href="#f2">see figure</a>).
# Implemented Devices
|SHORT NAME|LONG NAME|COST FUNCTION AND CONSTRAINTS|
|-|-|-|
|CDevice|Cummulative Device|Linear with cummulative consumption over time bounds|
|GDevice|Generator Device|Quadractive cost function|
|IDevice|Instantaneous Device|Parametized quadratic section see [here](./docs/instantaneous-device-utility-curve-analysis.md)|
|IDevice2|Alternative Instantaneous Device|Parametized quadratic section see [here](./docs/instantaneous-device-utility-curve-analysis.md)|
|MFDevice|Multiflow Device|Constraints s.t. can take flow from one of two source (ex. heat and electricity) in perfect subs|
|PVDevice|Photo-voltaic Device|Simple model of PV with some surface area and efficiency factor|
|SDevice|Storage Device|Generic battery or thermal storage device with a few parameters|
|TDevice|Thermal Device|Does a thing|
|ADevice|Any Device|Takes an arbitrary cost function and constraints|
|...|Other Device|Experimental|
# Class Structure
There is two important classes: `Device` and `DeviceSet`. The UML class diagram in the <a href="#f1">figure</a> shows how they are related. All devices sub-class `BaseDevice` which is the key abstract representation of a device. A device's consumption/production/both, herein called *flow*, is a 2D `R` by `C` numpy array. For "atomic" devices of class `Device`, `R` is always 1, and `C` is the fixed length (`__len__`) of the Device. A collection of devices is also implemented as a sub-type of `BaseDevice` and this is how `R` can be greater than 1. The `DeviceSet` class is used to represent collections of devices, such as a network or sub-network. `DeviceSet` allows devices to be organized into an arbitrarily deep rooted tree of devices. An example is shown in the figure. Atomic device always occur at the leaves. All internal nodes, and the root of the tree are `DeviceSet` instances.
All devices are intended to be stateless: they are not actively consuming producing anything. Rather they are modeling the preferences and constraints for the flow of a commodity (the `map(flow)` method shown in the UML diagram allows you to map an actual flow matrix onto a collection of devices). Devices are also intended to be immutable (but technically they are not currently strictly immutable).
# Flexibility Modeling Details
Device's encapsulate a flexibility model. Flexibility has two components *preferences* or soft constraints and (hard) *constraints*.
For convenience, the `Device` base class provides for two very common rudimentary baked-in constraints:
- `Device.bounds` for *interval* (also called instantaneous) bounds for each given interval of the time-horizon and,
- `Device.cbounds` for *cumulative* bounds across the entire time-horizon.
Preferences are expressed via the `Device.cost(flow)` function which expresses how much the device "likes" the given state of flow (note utility = -cost). The `Device` base class has no preferences: `Device.cost()` just returns 0. It is the main job of a `Device` sub-type to define preferences and/or additional more complex constraints that describe more nuanced device models. sub-types do this by overriding `Device.cost()` (preferences) and `Device.constraints` (constraints).
Raw data
{
"_id": null,
"home_page": null,
"name": "device-kit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9.2",
"maintainer_email": "Sam Pinkus <sgpinkus@gmail.com>",
"keywords": "microgrid, day-ahead, simulation, modeling",
"author": null,
"author_email": "Sam Pinkus <sgpinkus@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a1/bb/df1b17ac373465d6c35ec5c6d63f3bf61390eb0c86249fdd98c32ca8f40d/device_kit-1.0.6.tar.gz",
"platform": null,
"description": "# Device Kit\n`device_kit` is a Python package containing a collection of scalar vector flow device models for convex optimal flow simulations. The package defines a common abstract interface for a device, a base set of concrete devices, and a way of constructing new aggregate devices from collection of related sub-devices. Under the hood it's a big 2d numpy array, with discrete time slot along one dimension, and leaf device along the other. `device_kit` makes it easier to express and manage the constraints and cost functions, and solve the system.\n\nThe `device_kit` was originally written for the purpose modeling controllable microgrid or household electrical devices, and then optimizing flows over a day-ahead time horizon.\n\n<table>\n <tr>\n <td width=\"50%\" style=\"vertical-align: top;\">\n <figure>\n <a name='f1'><img width='400px' name='f1' src='docs/img/uml-cd.png'/></a><br/>\n <small>The core classes of `device_kit`. Most the model complexity is in sub classes of `Device`. A handful of sub-types are provided in this package such as `IDevice`. `DeviceSet` connects a network of devices. </small>\n </figure>\n </td>\n <td width=\"50%\" style=\"vertical-align: top;\">\n <figure>\n <a name='f2'><img width='400px' name='f2' src='docs/img/tree-of-smart-homes-op-e-phys.jpg'/></a><br/>\n <small>Example radial microgrid model-able with `device_kit`.</small>\n </figure>\n </td>\n </tr>\n <tr>\n <td width=\"50%\" style=\"vertical-align: top;\">\n <figure>\n <a name='f3'><img width='400px' name='f1' src='docs/img/lcl-scenario-home5-9b94d3e.gif'/></a><br/>\n <small>Example microgrid connection home simulation from unoptimized to optimized.</small>\n </figure>\n </td>\n <td width=\"50%\" style=\"vertical-align: top;\">\n <figure>\n <a name='f4'><img width='400px' name='f2' src='docs/img/aircon-scenario.gif'/></a><br/>\n <small>Example aircon utility based simulation from unoptimized to optimized. Temperature goes up as cost goes down. Utility curve varies between aircon scenarios.</small>\n </figure>\n </td>\n </tr>\n</table>\n\n# Installation\n\n```\npip install \"git+https://github.com/sgpinkus/microgrid_device_kit\"`\n```\n\n# Synopsis\nA simple example of using `device_kit` to model a collection of devices and then solve for some constraint over the joint flows - most commonly balanced flows:\n\n```python\nimport numpy as np\nimport pandas as pd\nimport matplotlib.pyplot as plt\nimport device_kit\nfrom device_kit import *\n\ndef random_uncontrolled():\n return np.maximum(0, 0.5+np.cumsum(np.random.uniform(-1,1, 24)))\n\ndef generator_cost_curve():\n return np.stack((np.sin(np.linspace(0, np.pi, 24))*0.5+0.1, np.ones(24)*0.001, np.zeros(24)), axis=1)\n\ndef make_model():\n ''' Small power network model. '''\n np.random.seed(19)\n model = DeviceSet('site1', [\n Device('uncontrolled', 24, (random_uncontrolled(),)),\n IDevice2('scalable', 24, (0.5, 2), (0, 24), d0=0.3),\n CDevice('shiftable', 24, (0, 2), (12, 24)),\n GDevice('generator', 24, (-10,0), cbounds=None, cost_coeffs=generator_cost_curve()),\n DeviceSet('sub-site1', [\n Device('uncontrolled', 24, (random_uncontrolled(),)),\n SDevice('buffer', 24, (-7, 7), c1=1.0, capacity=70, sustainment=1, efficiency=1)\n ],\n sbounds=(0,10) # max capacity constraint.\n ),\n ],\n sbounds=(0,0) # balanced flow constraint.\n )\n return model\n\ndef main():\n model = make_model()\n (x, solve_meta) = device_kit.solve(model, p=0) # Convenience convex solver.\n print(solve_meta.message)\n df = pd.DataFrame.from_dict(dict(model.map(x)), orient='index')\n df.loc['total'] = df.sum()\n pd.set_option('display.float_format', lambda v: '%+0.3f' % (v,),)\n print(df.sort_index())\n print('Utility: ', model.cost(x, p=0))\n df.transpose().plot(drawstyle='steps', grid=True)\n plt.ylabel('Power (kWh)')\n plt.xlabel('Time (H)')\n plt.savefig('synopsis.png');\n\nif __name__ == '__main__':\n main()\n```\n\nGives:\n\n```\nOptimization terminated successfully\n 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23\nsite1.generator -3.850 -2.744 -1.964 -1.630 -1.303 -1.455 -0.991 -1.040 -1.084 -1.140 -0.927 -0.770 -0.770 -0.783 -0.808 -0.848 -0.907 -0.991 -1.110 -1.282 -1.542 -1.964 -2.698 -3.249\nsite1.scalable +0.991 +0.664 +0.663 +0.551 +0.632 +0.500 +0.664 +0.500 +0.500 +0.500 +0.500 +0.663 +0.663 +0.663 +0.663 +0.663 +0.664 +0.664 +0.664 +0.664 +0.664 +0.663 +0.698 +1.249\nsite1.shiftable +2.000 +0.793 +0.696 +0.000 +0.000 +0.000 +0.100 +0.000 +0.000 +0.000 +0.000 +0.108 +0.108 +0.120 +0.145 +0.119 +0.244 +0.327 +0.446 +0.618 +0.878 +1.301 +2.000 +2.000\nsite1.sub-site1.buffer +0.128 +0.052 +0.052 +0.026 +0.044 -0.091 +0.052 -0.015 -0.076 -0.138 -0.033 -0.000 -0.000 -0.000 -0.000 -0.000 -0.000 -0.000 -0.000 -0.000 -0.000 -0.000 +0.000 -0.000\nsite1.sub-site1.uncontrolled +0.730 +1.016 +0.553 +1.054 +0.627 +1.046 +0.176 +0.555 +0.660 +0.767 +0.460 +0.000 +0.000 +0.000 +0.000 +0.066 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000\nsite1.uncontrolled +0.000 +0.218 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.011 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000\ntotal +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000 +0.000\nUtility: -13.021871014972055\n```\n\n<table>\n <tr>\n <td width=\"50%\" style=\"vertical-align: top;\">\n <figure>\n <a name='f3'><img width='400px' name='f1' src='scripts/synopsis.png'/></a><br/>\n <small>Output plot.</small>\n </figure>\n </td>\n </tr>\n</table>\n\n# Overview\nIn the scope of this package, a device is something that consumes and/or produces some kind of scalar valued commodity (ex. electricity, gas, fluid) over a fixed, discrete, and finite future planning/scheduling horizon (ex. every hour of the next day, or every minute of the next hour, etc). For each device what is modeled is simply:\n\n 1. The non-negotiable hard constraints on the commodity *flow* to/from the device.\n 2. Costs (or soft constraints) for different feasible states of flow to/from the device.\n\nAll the concrete device models provided are currently all weakly convex and tune-able. The concrete set of device implementations can be used to model quite a wide range of scenarios within the bounds of convexity.\n\nLow level devices exist in a network which acts as a conduit for commodity flow between devices (ex. an electrical bus). This package is limited (by design) to modeling radially structured (in other words, *rooted tree* structured) networks to an arbitrary nesting level (the simple flow networks we're interested in modeling have a radial structure or can be treated as such at the level of abstraction we're interested in). \"Networks\" are implemented as composite devices containing other atomic or composite devices, down to some eventual leaf node device level (<a href=\"#f2\">see figure</a>).\n\n# Implemented Devices\n\n|SHORT NAME|LONG NAME|COST FUNCTION AND CONSTRAINTS|\n|-|-|-|\n|CDevice|Cummulative Device|Linear with cummulative consumption over time bounds|\n|GDevice|Generator Device|Quadractive cost function|\n|IDevice|Instantaneous Device|Parametized quadratic section see [here](./docs/instantaneous-device-utility-curve-analysis.md)|\n|IDevice2|Alternative Instantaneous Device|Parametized quadratic section see [here](./docs/instantaneous-device-utility-curve-analysis.md)|\n|MFDevice|Multiflow Device|Constraints s.t. can take flow from one of two source (ex. heat and electricity) in perfect subs|\n|PVDevice|Photo-voltaic Device|Simple model of PV with some surface area and efficiency factor|\n|SDevice|Storage Device|Generic battery or thermal storage device with a few parameters|\n|TDevice|Thermal Device|Does a thing|\n|ADevice|Any Device|Takes an arbitrary cost function and constraints|\n|...|Other Device|Experimental|\n\n# Class Structure\nThere is two important classes: `Device` and `DeviceSet`. The UML class diagram in the <a href=\"#f1\">figure</a> shows how they are related. All devices sub-class `BaseDevice` which is the key abstract representation of a device. A device's consumption/production/both, herein called *flow*, is a 2D `R` by `C` numpy array. For \"atomic\" devices of class `Device`, `R` is always 1, and `C` is the fixed length (`__len__`) of the Device. A collection of devices is also implemented as a sub-type of `BaseDevice` and this is how `R` can be greater than 1. The `DeviceSet` class is used to represent collections of devices, such as a network or sub-network. `DeviceSet` allows devices to be organized into an arbitrarily deep rooted tree of devices. An example is shown in the figure. Atomic device always occur at the leaves. All internal nodes, and the root of the tree are `DeviceSet` instances.\n\nAll devices are intended to be stateless: they are not actively consuming producing anything. Rather they are modeling the preferences and constraints for the flow of a commodity (the `map(flow)` method shown in the UML diagram allows you to map an actual flow matrix onto a collection of devices). Devices are also intended to be immutable (but technically they are not currently strictly immutable).\n\n# Flexibility Modeling Details\nDevice's encapsulate a flexibility model. Flexibility has two components *preferences* or soft constraints and (hard) *constraints*.\n\nFor convenience, the `Device` base class provides for two very common rudimentary baked-in constraints:\n\n - `Device.bounds` for *interval* (also called instantaneous) bounds for each given interval of the time-horizon and,\n - `Device.cbounds` for *cumulative* bounds across the entire time-horizon.\n\nPreferences are expressed via the `Device.cost(flow)` function which expresses how much the device \"likes\" the given state of flow (note utility = -cost). The `Device` base class has no preferences: `Device.cost()` just returns 0. It is the main job of a `Device` sub-type to define preferences and/or additional more complex constraints that describe more nuanced device models. sub-types do this by overriding `Device.cost()` (preferences) and `Device.constraints` (constraints).\n",
"bugtrack_url": null,
"license": null,
"summary": "Flow device economical optimization modeling kit",
"version": "1.0.6",
"project_urls": {
"Homepage": "https://github.com/sgpinkus/device_kit",
"Issues": "https://github.com/sgpinkus/device_kit/issues"
},
"split_keywords": [
"microgrid",
" day-ahead",
" simulation",
" modeling"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9dda94b40790f1b422a83ec10a770ffe1c2fcdd151e611eb3f09c90145f16345",
"md5": "fbc872b5e16ddf9980b0aa50a6d0eda4",
"sha256": "fedc6d748bc3a7c484217f502b968ef7b69c2b1d79d5deea278228a69aa1ffd2"
},
"downloads": -1,
"filename": "device_kit-1.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fbc872b5e16ddf9980b0aa50a6d0eda4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.2",
"size": 47300,
"upload_time": "2024-11-04T08:11:14",
"upload_time_iso_8601": "2024-11-04T08:11:14.105741Z",
"url": "https://files.pythonhosted.org/packages/9d/da/94b40790f1b422a83ec10a770ffe1c2fcdd151e611eb3f09c90145f16345/device_kit-1.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a1bbdf1b17ac373465d6c35ec5c6d63f3bf61390eb0c86249fdd98c32ca8f40d",
"md5": "58b3f104b960dcf1f6244b6a3229dfb4",
"sha256": "468d80439cde4002f00f1813dc3f9a11a123f5f450404f1ead1da9ed6ef2a38f"
},
"downloads": -1,
"filename": "device_kit-1.0.6.tar.gz",
"has_sig": false,
"md5_digest": "58b3f104b960dcf1f6244b6a3229dfb4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.2",
"size": 49156,
"upload_time": "2024-11-04T08:11:15",
"upload_time_iso_8601": "2024-11-04T08:11:15.926578Z",
"url": "https://files.pythonhosted.org/packages/a1/bb/df1b17ac373465d6c35ec5c6d63f3bf61390eb0c86249fdd98c32ca8f40d/device_kit-1.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-04 08:11:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sgpinkus",
"github_project": "device_kit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "device-kit"
}
JSON
