esclab 0.0.1__tar.gz

esclab-0.0.1/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: esclab
+Version: 0.0.1
+Summary: Energy Systems Simulation and Control Lab
+Author-email: Mike Wagner <mjwagner2@wisc.edu>
+License-Expression: LicenseRef-UW-Madison-proprietary-instructional
+Project-URL: Homepage, https://github.com/esclab/esclab
+Project-URL: Issues, https://github.com/esclab/esclab/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Education
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: eeslib>=0.0.5
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: CoolProp>=6.4.0
+Requires-Dist: sympy>=1.13.0
+Requires-Dist: gurobipy>=12.0.1
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: matplotlib>=3.10.0
+Requires-Dist: pyqtgraph>=0.14.0
+Requires-Dist: PyQt5>=5.15.11
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: build>=0.10; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: sphinx>=8.2.3; extra == "dev"
+Requires-Dist: sphinx_rtd_theme>=3.0.2; extra == "dev"
+Requires-Dist: sphinx_autodoc_typehints>=3.5.2; extra == "dev"
+Provides-Extra: admin
+
+# ESCLAB
+**Engineering Simulation and Control Lab**
+
+This software provides an environment for time-series simulation and control of complex multi-component systems. The approach used here relies on iterative (successive substitution) solving to converge on values for a given step, allowing compartmentalization of calculations between individual system components. 
+
+The simulation is configured and managed in Python scripts. 
+
+A graphical plotting interface provides real-time simulation results and a network topology rendering tool.
+
+The software is structured to support both research and teaching activities and is used in the upper-graduate course "ME 964: Simulation and Optimal Control of Energy Systems" at the University of Wisconsin-Madison.
+
+## Installation
+
+1. Download and install a Python package manager. This program was developed using [miniconda](https://www.anaconda.com/download/success?reg=skipped), and it's recommended for environment creation and maintenance. 
+
+2. Download and install [VS Code](https://code.visualstudio.com/download) (or your favorite Python IDE, though VS Code is currently recommended)
+
+3. Open a command console and create a new conda environment. You can call this what you'd like, but I assume the name 'esclab_dev' in the documentation:
+
+```bash
+# Create and activate a new conda environment
+conda create -n esclab_dev python=3.13
+conda activate esclab_dev
+```
+
+### Installing from source code
+
+Use this option when you plan on extending the component or model libraries with code that will closely integrate. This allows direct modification of the ESCLab source code and incorporation of the latest updates that are pushed to the GitHub repository. 
+
+4. Change to a convenient location for the repository. A path with no spaces is recommended.
+```bash
+cd C:\repositories
+```
+
+5. Collect the ESCLab package source code. If you're using git, clone the repository. Otherwise, you can download and unzip the repository. 
+```bash
+# Clone
+git clone https://github.com/uw-esolab/esclab.git
+```
+
+6. Install the ESCLab project to the python package you just created. 
+
+```bash
+# The -e flag makes the installation editable.
+pip install -e .
+# ESCLab currently requires the most recent version of EESLib (published by uw-esolab). 
+# Clone and install the editable version to this conda environment. 
+# Make sure C:\repositories is replace with the path to your repository directory.
+pip install -e C:\repositories\eeslib
+# Ensure the editable version is correctly installed in esclab_dev.
+python -c "import eeslib; print(eeslib.__file__)"
+```
+
+### Installing from the package manager (PyPi)
+
+Do this **instead** of the source code option if you're happy with a relatively stable release of the ESCLab core source code and will only be developing models and components for your own use without intending to share them as part of the ESCLab distribution. 
+
+Following step #3 above: 
+
+4. Install the package using `pip`:
+```bash
+pip install esclab
+```
+
+## Getting started
+
+* Source code for constructing and simulating models is found in the /src/esclab directory
+* Components are defined in the */src/esclab/components* folder
+* Models are defined in the */src/esclab/models* folder
+
+To create a new model, prepare one or more component files that contain instance(s) of Component classes that are units in the system you want to model. Connect components together in a *model* file.
+
+Templates and examples for *Components* and *Models* are provided in their respective folders. 
+
+* `template_model.py` provides a template for building new system models
+* `template_component.py` provides a template for a component library
+* `sample_circuit_secsub.py` gives and example of a simple solve loop using successive substitution (no coupled equations)
+* `sample_circuit.py` gives an equivalent example using the coupled equation approach. `sample_circuit_tee.py`, and `sample_circuit_hilopass.py` also give examples of solving coupled equations for increasingly complex topologies.
+
+The main calculation and plotting scripts are:
+
+* `simulate.py` | core simulation engine
+* `network_topology.py` | tools for detecting, organizing, and rendering coupled network systems
+* `online_plotter.py` | Qt-based window for real-time plotting
+
+Definitions:
+| Term               | Definition                                                                                                                       |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| Component          | Building block for a system model. Components take input and compute output values, and they connect with other components       |
+| Model              | Collection of one or more components together into a simulated system                                                            |
+| Simulation         | Time-dependent evaluation of a model                                                                                             |
+| Step               | Calculations done at a specific value in time. A simulation contains many steps |
+| Coupled equations  | Equations that are designated to be solved together using matrix inversion, outside of the normal successive-substitution method |
+| Absolute tolerance | Absolute difference between connection values on succesive iterations                                                            |
+| Relative tolerance | Difference relative to the magnitude of the last connection value                                                                                                                                 |
+| Learning rate      | Fraction of the difference between the new and old computed values to apply when iterating                                                                                                                                 |
+
+## Uploading a new version to PyPi (developers only!)
+
+To upload a new version of ESCLab to Pypi, follow the steps outlined in the [Python packaging tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/). 
+
+The preferred packaging tool is `setuptools`. 
+
+The most relevant steps are as follows:
+1. Don't forget to update the code version number in `pyproject.toml` and in the `src/__init__.py` file.
+1. Open a command window and navigate to the `esclab` directory, such as
+    ```bash
+    cd C:\repositories\esclab
+    ```
+2. Ensure the build and packaging tools are installed in the Conda environment that you're using. 
+    The preferred method will install a developer tools, including build, pytest, and twine, specified in the pyproject.toml file in the esclab directory:
+    ```bash
+    pip install .[dev]
+    ```
+    Alternatively, you can manually install packages:
+    ```bash
+    python -m pip install --upgrade build 
+    python -m pip install --upgrade twine
+    ```
+3. Build the Python distributable
+    ```bash
+    python -m build
+    ```
+    This should create a folder `dist/` that contains a wheel (.whl) and tar.gz file. 
+4. Upload the file to Pypi. You will need to have first created a username and API token, following the packing tutorial instructions. If uploading to the production server, use the command:
+    ```bash
+    twine upload dist/*
+    ```
+
+    If using the test server, use the command:
+    ```bash
+    python -m twine upload --repository testpypi dist/*
+    ```
+
+5. To install the package, activate the Conda environment (e.g., `conda activate esclab_dev`), and install. 
+    If running from the production environment use:
+    ```bash
+    pip install esclab
+    ```
+
+    If you have previous versions of `esclab` already installed, force use of the most recent version using: 
+    ```bash
+    pip install --force-reinstall --upgrade esclab
+    ```
+
+
+## Authors
+
+Lead author:
+Mike Wagner | Associate Professor, University of Wisconsin-Madison | [GitHub: uw-esolab](https://github.com/uw-esolab/) | [Profile](https://engineering.wisc.edu/directory/profile/mike-wagner/)
+
+Contributors:

esclab-0.0.1/README.md

@@ -0,0 +1,152 @@
+# ESCLAB
+**Engineering Simulation and Control Lab**
+
+This software provides an environment for time-series simulation and control of complex multi-component systems. The approach used here relies on iterative (successive substitution) solving to converge on values for a given step, allowing compartmentalization of calculations between individual system components. 
+
+The simulation is configured and managed in Python scripts. 
+
+A graphical plotting interface provides real-time simulation results and a network topology rendering tool.
+
+The software is structured to support both research and teaching activities and is used in the upper-graduate course "ME 964: Simulation and Optimal Control of Energy Systems" at the University of Wisconsin-Madison.
+
+## Installation
+
+1. Download and install a Python package manager. This program was developed using [miniconda](https://www.anaconda.com/download/success?reg=skipped), and it's recommended for environment creation and maintenance. 
+
+2. Download and install [VS Code](https://code.visualstudio.com/download) (or your favorite Python IDE, though VS Code is currently recommended)
+
+3. Open a command console and create a new conda environment. You can call this what you'd like, but I assume the name 'esclab_dev' in the documentation:
+
+```bash
+# Create and activate a new conda environment
+conda create -n esclab_dev python=3.13
+conda activate esclab_dev
+```
+
+### Installing from source code
+
+Use this option when you plan on extending the component or model libraries with code that will closely integrate. This allows direct modification of the ESCLab source code and incorporation of the latest updates that are pushed to the GitHub repository. 
+
+4. Change to a convenient location for the repository. A path with no spaces is recommended.
+```bash
+cd C:\repositories
+```
+
+5. Collect the ESCLab package source code. If you're using git, clone the repository. Otherwise, you can download and unzip the repository. 
+```bash
+# Clone
+git clone https://github.com/uw-esolab/esclab.git
+```
+
+6. Install the ESCLab project to the python package you just created. 
+
+```bash
+# The -e flag makes the installation editable.
+pip install -e .
+# ESCLab currently requires the most recent version of EESLib (published by uw-esolab). 
+# Clone and install the editable version to this conda environment. 
+# Make sure C:\repositories is replace with the path to your repository directory.
+pip install -e C:\repositories\eeslib
+# Ensure the editable version is correctly installed in esclab_dev.
+python -c "import eeslib; print(eeslib.__file__)"
+```
+
+### Installing from the package manager (PyPi)
+
+Do this **instead** of the source code option if you're happy with a relatively stable release of the ESCLab core source code and will only be developing models and components for your own use without intending to share them as part of the ESCLab distribution. 
+
+Following step #3 above: 
+
+4. Install the package using `pip`:
+```bash
+pip install esclab
+```
+
+## Getting started
+
+* Source code for constructing and simulating models is found in the /src/esclab directory
+* Components are defined in the */src/esclab/components* folder
+* Models are defined in the */src/esclab/models* folder
+
+To create a new model, prepare one or more component files that contain instance(s) of Component classes that are units in the system you want to model. Connect components together in a *model* file.
+
+Templates and examples for *Components* and *Models* are provided in their respective folders. 
+
+* `template_model.py` provides a template for building new system models
+* `template_component.py` provides a template for a component library
+* `sample_circuit_secsub.py` gives and example of a simple solve loop using successive substitution (no coupled equations)
+* `sample_circuit.py` gives an equivalent example using the coupled equation approach. `sample_circuit_tee.py`, and `sample_circuit_hilopass.py` also give examples of solving coupled equations for increasingly complex topologies.
+
+The main calculation and plotting scripts are:
+
+* `simulate.py` | core simulation engine
+* `network_topology.py` | tools for detecting, organizing, and rendering coupled network systems
+* `online_plotter.py` | Qt-based window for real-time plotting
+
+Definitions:
+| Term               | Definition                                                                                                                       |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| Component          | Building block for a system model. Components take input and compute output values, and they connect with other components       |
+| Model              | Collection of one or more components together into a simulated system                                                            |
+| Simulation         | Time-dependent evaluation of a model                                                                                             |
+| Step               | Calculations done at a specific value in time. A simulation contains many steps |
+| Coupled equations  | Equations that are designated to be solved together using matrix inversion, outside of the normal successive-substitution method |
+| Absolute tolerance | Absolute difference between connection values on succesive iterations                                                            |
+| Relative tolerance | Difference relative to the magnitude of the last connection value                                                                                                                                 |
+| Learning rate      | Fraction of the difference between the new and old computed values to apply when iterating                                                                                                                                 |
+
+## Uploading a new version to PyPi (developers only!)
+
+To upload a new version of ESCLab to Pypi, follow the steps outlined in the [Python packaging tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/). 
+
+The preferred packaging tool is `setuptools`. 
+
+The most relevant steps are as follows:
+1. Don't forget to update the code version number in `pyproject.toml` and in the `src/__init__.py` file.
+1. Open a command window and navigate to the `esclab` directory, such as
+    ```bash
+    cd C:\repositories\esclab
+    ```
+2. Ensure the build and packaging tools are installed in the Conda environment that you're using. 
+    The preferred method will install a developer tools, including build, pytest, and twine, specified in the pyproject.toml file in the esclab directory:
+    ```bash
+    pip install .[dev]
+    ```
+    Alternatively, you can manually install packages:
+    ```bash
+    python -m pip install --upgrade build 
+    python -m pip install --upgrade twine
+    ```
+3. Build the Python distributable
+    ```bash
+    python -m build
+    ```
+    This should create a folder `dist/` that contains a wheel (.whl) and tar.gz file. 
+4. Upload the file to Pypi. You will need to have first created a username and API token, following the packing tutorial instructions. If uploading to the production server, use the command:
+    ```bash
+    twine upload dist/*
+    ```
+
+    If using the test server, use the command:
+    ```bash
+    python -m twine upload --repository testpypi dist/*
+    ```
+
+5. To install the package, activate the Conda environment (e.g., `conda activate esclab_dev`), and install. 
+    If running from the production environment use:
+    ```bash
+    pip install esclab
+    ```
+
+    If you have previous versions of `esclab` already installed, force use of the most recent version using: 
+    ```bash
+    pip install --force-reinstall --upgrade esclab
+    ```
+
+
+## Authors
+
+Lead author:
+Mike Wagner | Associate Professor, University of Wisconsin-Madison | [GitHub: uw-esolab](https://github.com/uw-esolab/) | [Profile](https://engineering.wisc.edu/directory/profile/mike-wagner/)
+
+Contributors:

esclab-0.0.1/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "esclab"
+version = "0.0.1"
+authors = [
+  { name="Mike Wagner", email="mjwagner2@wisc.edu" },
+]
+description = "Energy Systems Simulation and Control Lab"
+readme = "README.md"
+requires-python = ">=3.13"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Education",
+]
+license = "LicenseRef-UW-Madison-proprietary-instructional"
+license-files = ["LICENSE"]
+
+dependencies = [
+    "eeslib>=0.0.5",
+    "numpy>=1.21.0",
+    "scipy>=1.7.0",
+    "CoolProp>=6.4.0",
+    "sympy>=1.13.0",
+    "gurobipy>=12.0.1",
+    "pandas>=1.3.0",
+    "matplotlib>=3.10.0",
+    "pyqtgraph>=0.14.0",
+    "PyQt5>=5.15.11",
+]
+
+[project.urls]
+Homepage = "https://github.com/esclab/esclab"
+Issues = "https://github.com/esclab/esclab/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "build>=0.10",
+    'twine>=4.0.0',
+    "sphinx>=8.2.3",
+    "sphinx_rtd_theme>=3.0.2",
+    "sphinx_autodoc_typehints>=3.5.2", 
+]
+admin = [
+]

esclab-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

esclab-0.0.1/src/esclab/__init__.py

@@ -0,0 +1,8 @@
+# This file marks the src directory as a Python package.
+"""
+ESCLab: Engineering Simulation and Control Lab
+"""
+
+__version__ = "0.0.1"
+__author__ = "Mike Wagner"
+__email__ = "mjwagner2@wisc.edu"

esclab-0.0.1/src/esclab/components/__init__.py

@@ -0,0 +1,35 @@
+"""
+This file ensures that the component libraries are available for import from the top-level components module. 
+
+Add new modules to this file using:
+	from . import my_component_library
+    
+And add the module name to __all__ to make it available using the flat import syntax:
+	from esclab.components import my_component_library
+    or
+    from esclab.components import *
+
+It's best practice to import the component library as a named item, and then 
+reference the components through that namespace to avoid name collisions across libraries. For example:
+	import esclab.circuit_elements as ce
+	ce.Resistor(...)
+
+Import the submodule you need and reference components through it to avoid
+name collisions across libraries:
+
+    from esclab.components import circuit_elements
+    circuit_elements.TeeOut(...)
+
+"""
+
+from . import brayton_simple
+from . import circuit_elements
+from . import esol_properties
+from . import template_component
+
+__all__ = [
+    "brayton_simple",
+    "circuit_elements",
+    "esol_properties",
+    "template_component"
+]

esclab-0.0.1/src/esclab/components/brayton_simple.py

@@ -0,0 +1,123 @@
+from esclab.simulate import *
+from eeslib import fluid_properties
+import numpy as np
+
+# -------------------------------------------
+class Turbine(Component):
+
+    eta_s =    Component.Parameter(0.9)
+    mdot_in =  Component.Input()
+    T_in    =  Component.Input()
+    P_in    =  Component.Input()
+    h_out =    Component.Output()
+    T_out =    Component.Output()
+    P_out =    Component.Output()
+    mdot_out = Component.Output()
+    W =        Component.Output()
+    fluid = 'Air'
+
+    def calculate(self):
+        self.mdot_out = self.mdot_in
+        h_in = fluid_properties.enthalpy(self.fluid, T=self.T_in, P=self.P_in)
+        s_in = fluid_properties.entropy(self.fluid, T=self.T_in, P=self.P_in)
+        self.P_out = self.P_in / self.model.design.PR
+        h_out_s = fluid_properties.enthalpy(self.fluid,P=self.P_out, s=s_in)
+        self.h_out = h_in - (h_in-h_out_s)*self.eta_s
+        self.T_out = fluid_properties.temperature(self.fluid, P=self.P_out, h=self.h_out)
+        self.W = (h_in - self.h_out)*self.mdot_in        
+        return 
+    
+# -------------------------------------------
+class Compressor(Component):
+    eta_s = Component.Parameter(0.85)
+    PR = Component.Parameter(3.)
+
+    mdot_in = Component.Input()
+    T_in    = Component.Input()
+    P_in    = Component.Input()
+
+    h_out = Component.Output()
+    T_out = Component.Output()
+    P_out = Component.Output()
+    mdot_out = Component.Output()
+    W = Component.Output()
+
+    fluid = 'Air'
+        
+    def calculate(self):
+        self.mdot_out = self.mdot_in
+        h_in = fluid_properties.enthalpy(self.fluid, T=self.T_in, P=self.P_in)
+        s_in = fluid_properties.entropy(self.fluid, T=self.T_in, P=self.P_in)
+        self.P_out = self.P_in * self.PR
+        h_out_s = fluid_properties.enthalpy(self.fluid,P=self.P_out, s=s_in)
+        self.h_out = h_in + (h_out_s - h_in)/self.eta_s
+        self.T_out = fluid_properties.temperature(self.fluid, P=self.P_out, h=self.h_out)
+        self.W = (h_in - self.h_out)*self.mdot_in  
+        return 
+    
+# -------------------------------------------
+class Combustor(Component):
+    mdot_in = Component.Input()
+    T_in    = Component.Input()
+    P_in    = Component.Input()
+
+    h_out = Component.Output()
+    T_out = Component.Output()
+    P_out = Component.Output()
+    mdot_out = Component.Output()
+    qdot = Component.Output()
+
+    def presim_setup(self, **kwargs):
+        return super().presim_setup(**kwargs)
+
+    def calculate(self):
+        super().calculate()
+        self.mdot_out = self.mdot_in 
+        self.P_out = self.P_in 
+        self.T_out = self.model.design.T_turb_in
+        h_in = fluid_properties.enthalpy(self.model.design.fluid, T=self.T_in, P=self.P_in)
+        self.h_out = fluid_properties.enthalpy(self.model.design.fluid, T=self.T_out, P=self.P_out)
+        self.qdot = (self.h_out - h_in)*self.mdot_in
+        return 
+    
+# -------------------------------------------
+class Cooler(Component):
+    dT_approach = Component.Parameter(20)
+
+    mdot_in    = Component.Input()
+    T_in       = Component.Input()
+    P_in       = Component.Input()
+    T_amb      = Component.Input()
+
+    h_out = Component.Output()
+    T_out = Component.Output()
+    P_out = Component.Output()
+    mdot_out = Component.Output()
+    qdot = Component.Output()
+    
+    def calculate(self):
+        self.mdot_out = self.mdot_in
+        self.P_out = self.P_in
+        h_in = fluid_properties.enthalpy(self.model.design.fluid, T=self.T_in, P=self.P_in)
+        self.T_out = self.T_amb + self.dT_approach
+        self.h_out = fluid_properties.enthalpy(self.model.design.fluid, P=self.model.design.P_low, T=self.T_out)
+        self.qdot = (self.h_out - h_in)*self.mdot_in
+        return 
+
+class Summary(Component):
+    W_turbine = Component.Input()
+    W_compressor = Component.Input()
+    Q_combustor = Component.Input()
+    eta_cycle = Component.Output()
+    
+    def calculate(self):
+        self.eta_cycle = (self.W_turbine + self.W_compressor)/self.Q_combustor
+
+class Weather(Component):
+    def presim_setup(self):
+        self.T_amb = Component.Output()
+        return 
+
+    def calculate(self):
+        super().calculate()
+        self.T_amb = self.model.design.T_amb + 15*np.sin(self.model.time/1e5/np.pi) + 15*np.sin(self.model.time/1e5/np.pi*2+.5)