modnn 3.0.9__tar.gz → 3.2.0__tar.gz

{modnn-3.0.9 → modnn-3.2.0}/LICENSE

@@ -1,7 +1,7 @@
-Copyright 2024-2025 Zixin
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright 2024-2025 Zixin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

{modnn-3.0.9 → modnn-3.2.0}/PKG-INFO

@@ -1,115 +1,156 @@
-Metadata-Version: 2.4
-Name: modnn
-Version: 3.0.9
-Summary: Physics-Informed Modularized Neural Network for Building Energy Modeling
-Author-email: Zixin Jiang <zjiang19@syr.edu>
-License-Expression: MIT
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy
-Requires-Dist: torch
-Requires-Dist: pandas
-Requires-Dist: matplotlib
-Requires-Dist: seaborn
-Requires-Dist: scikit-learn
-Requires-Dist: tqdm
-Dynamic: license-file
-
-# ModNN
-
-**ModNN** is a Modularized Physics-Informed Neural Network for building energy modeling.
-
-It incorporates with physics-informed model structure, loss function, and model constraints.
-
----
-
-## 🚀 Installation
-
-You can install the package using pip:
-
-pip install modnn
-
-
-
-## 🧠 Example
-Please find the online Jupyter notebook for a step-by-step instruction:
-https://colab.research.google.com/drive/1A2jt1q53RtxGuaoym6N1PmlKELDPpYFX?usp=sharing
-
-
-## 🧠 Update log
-# 🧠 [2.0.0] 2025 May 9
-To further improve physical consistency, 
-
-I replaced heat transfer module by set of energy balance equations, 
-
-Start from version 2.0.0
-
-# 🧠 [2.0.1] 2025 May 10
-Add another parameter: "envelop_mdl", 
-
-Allow user to use the new physics based module or previous data driven module. 
-
-# 🧠 [2.0.2] 2025 May 10
-Fix bug due to parameter: "envelop_mdl",
-
-Vectorize calculation,speed improved by ~6 times.
-
-# 🧠 [3.0.0] 2025 June 11
-Update datadriven modnn
-RC based envelop_mdl really hard to tune on new dataset
-
-# 🧠 [3.0.1] 2025 June 11
-Add a step function for one step ahead prediction
-
-# 🧠 [3.0.2] 2025 June 11
-Fix bug for step function
-
-# 🧠 [3.0.3] 2025 June 11
-Fix bug for step function
-
-# 🧠 [3.0.4] 2025 Sept 10
-Didn't work on it for 3 months, just update the latest version
-Will use it for BESTOpt building dynamic model
-
-# 🧠 [3.0.5] 2025 Sept 15
-3.0.4 CAN-NOT work at all, I mistakenly comment one line and add a new line of code
-
-# 🧠 [3.0.6] 2025 Sept 15
-Fix temperature unit conversion issue
-
-# 🧠 [3.0.7] 2025 Sept 15
-Fix step model zone module dimension issue
-
-# 🧠 [3.0.8] 2025 Oct 20
-Change path in saving results function, so Windows user can use it without bugs
-
-# 🧠 [3.0.9] 2025 Oct 20
-Fix bugs
-## 🧪 Requirements
-
-    Python 3.7+
-
-    PyTorch
-
-    NumPy
-
-    Pandas
-
-    Matplotlib
-
-    Seaborn
-
-    scikit-learn
-
-    tqdm
-
----
-📬 License
-
-MIT License
-
-🙋‍♂️ Author
-
-Zixin Jiang: 
-zjiang19@syr.edu
+Metadata-Version: 2.4
+Name: modnn
+Version: 3.2.0
+Summary: Physics-Informed Modularized Neural Network for Building Energy Modeling
+Author-email: Zixin Jiang <zjiang19@syr.edu>
+License-Expression: MIT
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: torch
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: seaborn
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: tqdm
+Dynamic: license-file
+
+# ModNN
+
+**ModNN** is a Modularized Physics-Informed Neural Network for building energy modeling.
+
+It incorporates with physics-informed model structure, loss function, and model constraints.
+
+---
+
+## 🚀 Installation
+
+You can install the package using pip:
+
+pip install modnn
+
+
+
+## 🧠 Example
+Please find the online Jupyter notebook for a step-by-step instruction:
+https://colab.research.google.com/drive/1A2jt1q53RtxGuaoym6N1PmlKELDPpYFX?usp=sharing
+
+
+## ⚡ Quick start
+Your CSV needs a datetime index and the columns `temp_room`, `temp_amb`, `solar`, `occ` and `phvac`.
+
+```python
+from modnn import get_config, Mod
+
+args = get_config({"datapath": "your_data.csv"})
+model = Mod(args)
+model.data_ready()       # or model.data_ready(df) with a pandas DataFrame
+model.train()
+model.load()
+model.test()
+```
+
+or from the command line: `python -m modnn.run your_data.csv`
+
+Scalers, checkpoints, trained models, results and figures are written to `./modnn_output`
+(change with `"output_dir"`). The GPU is used when available, otherwise the CPU.
+
+## 🧩 Model options
+| option | values | meaning |
+| --- | --- | --- |
+| `architecture` | `"v3"` (default), `"v1"` | `"v1"` is the first-generation model (LSTM envelope, as in 1.0.1) |
+| `ext_input` | `"state"` (default), `"delta"` | envelope module input: [T_zone, T_ambient] or T_ambient - T_zone (as in 3.0.0) |
+| `constraints` | any of `"hvac"`, `"internal"`, `"ambient"`, `"solar"` | inputs whose effect on zone temperature must follow physics (default `["hvac", "internal"]`) |
+
+`"ambient"` and `"solar"` constrain the envelope module and need `architecture="v3"` with `ext_mdl="RNN"`.
+For example, a model whose responses to HVAC, occupancy, weather and sun all follow physics:
+
+```python
+args = get_config({"datapath": "your_data.csv", "ext_input": "delta",
+                   "constraints": ["hvac", "internal", "ambient", "solar"]})
+```
+
+## 🧠 Update log
+# 🧠 [2.0.0] 2025 May 9
+To further improve physical consistency, 
+
+I replaced heat transfer module by set of energy balance equations, 
+
+Start from version 2.0.0
+
+# 🧠 [2.0.1] 2025 May 10
+Add another parameter: "envelop_mdl", 
+
+Allow user to use the new physics based module or previous data driven module. 
+
+# 🧠 [2.0.2] 2025 May 10
+Fix bug due to parameter: "envelop_mdl",
+
+Vectorize calculation,speed improved by ~6 times.
+
+# 🧠 [3.0.0] 2025 June 11
+Update datadriven modnn
+RC based envelop_mdl really hard to tune on new dataset
+
+# 🧠 [3.0.1] 2025 June 11
+Add a step function for one step ahead prediction
+
+# 🧠 [3.0.2] 2025 June 11
+Fix bug for step function
+
+# 🧠 [3.0.3] 2025 June 11
+Fix bug for step function
+
+# 🧠 [3.0.4] 2025 Sept 10
+Didn't work on it for 3 months, just update the latest version
+Will use it for BESTOpt building dynamic model
+
+# 🧠 [3.0.5] 2025 Sept 15
+3.0.4 CAN-NOT work at all, I mistakenly comment one line and add a new line of code
+
+# 🧠 [3.0.6] 2025 Sept 15
+Fix temperature unit conversion issue
+
+# 🧠 [3.0.7] 2025 Sept 15
+Fix step model zone module dimension issue
+
+# 🧠 [3.1.0] 2026 Sept 25
+New options: "architecture" (v1/v3) and "ext_input" (state/delta); physical constraints applied through `model.apply_constraints()`
+
+Easier to use: `from modnn import get_config, Mod`, `python -m modnn.run your_data.csv`, outputs in `./modnn_output`
+(previously `../`), device defaults to "cuda" with CPU fallback, clear errors for a missing data file or column, scipy added to requirements
+
+# 🧠 [3.2.0] 2026 Sept 25
+Choose which responses are physically constrained with `"constraints"`: any of "hvac", "internal", "ambient", "solar"
+
+Presets removed
+
+## 🧪 Requirements
+
+    Python 3.7+
+
+    PyTorch
+
+    NumPy
+
+    Pandas
+
+    Matplotlib
+
+    Seaborn
+
+    scikit-learn
+
+    tqdm
+
+---
+📬 License
+
+MIT License
+
+🙋‍♂️ Author
+
+Zixin Jiang: 
+zjiang19@syr.edu

modnn-3.2.0/README.md

@@ -0,0 +1,137 @@
+# ModNN
+
+**ModNN** is a Modularized Physics-Informed Neural Network for building energy modeling.
+
+It incorporates with physics-informed model structure, loss function, and model constraints.
+
+---
+
+## 🚀 Installation
+
+You can install the package using pip:
+
+pip install modnn
+
+
+
+## 🧠 Example
+Please find the online Jupyter notebook for a step-by-step instruction:
+https://colab.research.google.com/drive/1A2jt1q53RtxGuaoym6N1PmlKELDPpYFX?usp=sharing
+
+
+## ⚡ Quick start
+Your CSV needs a datetime index and the columns `temp_room`, `temp_amb`, `solar`, `occ` and `phvac`.
+
+```python
+from modnn import get_config, Mod
+
+args = get_config({"datapath": "your_data.csv"})
+model = Mod(args)
+model.data_ready()       # or model.data_ready(df) with a pandas DataFrame
+model.train()
+model.load()
+model.test()
+```
+
+or from the command line: `python -m modnn.run your_data.csv`
+
+Scalers, checkpoints, trained models, results and figures are written to `./modnn_output`
+(change with `"output_dir"`). The GPU is used when available, otherwise the CPU.
+
+## 🧩 Model options
+| option | values | meaning |
+| --- | --- | --- |
+| `architecture` | `"v3"` (default), `"v1"` | `"v1"` is the first-generation model (LSTM envelope, as in 1.0.1) |
+| `ext_input` | `"state"` (default), `"delta"` | envelope module input: [T_zone, T_ambient] or T_ambient - T_zone (as in 3.0.0) |
+| `constraints` | any of `"hvac"`, `"internal"`, `"ambient"`, `"solar"` | inputs whose effect on zone temperature must follow physics (default `["hvac", "internal"]`) |
+
+`"ambient"` and `"solar"` constrain the envelope module and need `architecture="v3"` with `ext_mdl="RNN"`.
+For example, a model whose responses to HVAC, occupancy, weather and sun all follow physics:
+
+```python
+args = get_config({"datapath": "your_data.csv", "ext_input": "delta",
+                   "constraints": ["hvac", "internal", "ambient", "solar"]})
+```
+
+## 🧠 Update log
+# 🧠 [2.0.0] 2025 May 9
+To further improve physical consistency, 
+
+I replaced heat transfer module by set of energy balance equations, 
+
+Start from version 2.0.0
+
+# 🧠 [2.0.1] 2025 May 10
+Add another parameter: "envelop_mdl", 
+
+Allow user to use the new physics based module or previous data driven module. 
+
+# 🧠 [2.0.2] 2025 May 10
+Fix bug due to parameter: "envelop_mdl",
+
+Vectorize calculation,speed improved by ~6 times.
+
+# 🧠 [3.0.0] 2025 June 11
+Update datadriven modnn
+RC based envelop_mdl really hard to tune on new dataset
+
+# 🧠 [3.0.1] 2025 June 11
+Add a step function for one step ahead prediction
+
+# 🧠 [3.0.2] 2025 June 11
+Fix bug for step function
+
+# 🧠 [3.0.3] 2025 June 11
+Fix bug for step function
+
+# 🧠 [3.0.4] 2025 Sept 10
+Didn't work on it for 3 months, just update the latest version
+Will use it for BESTOpt building dynamic model
+
+# 🧠 [3.0.5] 2025 Sept 15
+3.0.4 CAN-NOT work at all, I mistakenly comment one line and add a new line of code
+
+# 🧠 [3.0.6] 2025 Sept 15
+Fix temperature unit conversion issue
+
+# 🧠 [3.0.7] 2025 Sept 15
+Fix step model zone module dimension issue
+
+# 🧠 [3.1.0] 2026 Sept 25
+New options: "architecture" (v1/v3) and "ext_input" (state/delta); physical constraints applied through `model.apply_constraints()`
+
+Easier to use: `from modnn import get_config, Mod`, `python -m modnn.run your_data.csv`, outputs in `./modnn_output`
+(previously `../`), device defaults to "cuda" with CPU fallback, clear errors for a missing data file or column, scipy added to requirements
+
+# 🧠 [3.2.0] 2026 Sept 25
+Choose which responses are physically constrained with `"constraints"`: any of "hvac", "internal", "ambient", "solar"
+
+Presets removed
+
+## 🧪 Requirements
+
+    Python 3.7+
+
+    PyTorch
+
+    NumPy
+
+    Pandas
+
+    Matplotlib
+
+    Seaborn
+
+    scikit-learn
+
+    tqdm
+
+---
+📬 License
+
+MIT License
+
+🙋‍♂️ Author
+
+Zixin Jiang: 
+zjiang19@syr.edu