modnn 1.0.0__tar.gz

modnn-1.0.0/LICENSE

@@ -0,0 +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.

modnn-1.0.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: modnn
+Version: 1.0.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: 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 very easy:
+
+pip install modnn
+
+
+
+## 🧠 Example
+Please find the online Jupyter notebook for a step-by-step instruction
+
+
+## 🧪 Requirements
+
+    Python 3.7+
+
+    PyTorch
+
+    NumPy
+
+    Pandas
+
+    Matplotlib
+
+    Seaborn
+
+    scikit-learn
+
+    tqdm
+
+---
+📬 License
+
+MIT License
+
+🙋‍♂️ Author
+
+Zixin Jiang: 
+zjiang19@syr.edu

modnn-1.0.0/README.md

@@ -0,0 +1,47 @@
+# 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 very easy:
+
+pip install modnn
+
+
+
+## 🧠 Example
+Please find the online Jupyter notebook for a step-by-step instruction
+
+
+## 🧪 Requirements
+
+    Python 3.7+
+
+    PyTorch
+
+    NumPy
+
+    Pandas
+
+    Matplotlib
+
+    Seaborn
+
+    scikit-learn
+
+    tqdm
+
+---
+📬 License
+
+MIT License
+
+🙋‍♂️ Author
+
+Zixin Jiang: 
+zjiang19@syr.edu

modnn-1.0.0/modnn/Config.py

@@ -0,0 +1,109 @@
+def _paras(**kwargs):
+    """
+    Return hyperparameters for training.
+    Accepts keyword arguments to override default values.
+    """
+    para = {
+        # Internal gain module
+        "Int_in": 3, "Int_h": 18, "Int_out": 1,
+
+        # External disturbance module
+        "Ext_in": 5, "Ext_h": 22, "Ext_out": 1,
+
+        # Zone module
+        "Zone_in": 1, "Zone_out": 1,
+
+        # HVAC module
+        "HVAC_in": 1, "HVAC_out": 1,
+
+        # Look back window
+        "window" : 1,
+
+        # Training hyperparameters
+        "lr": 0.01,
+        "epochs": 500,
+        "patience": 10, #Early stop
+    }
+
+    # Allow override from kwargs
+    para.update(kwargs)
+
+    return para
+
+
+def _args(**kwargs):
+    """
+    Returns model configurations.
+    Allows keyword-based overrides.
+    """
+    para_overrides = kwargs.pop("para", {})
+    args = {
+        "para": _paras(**para_overrides),
+
+        # Paths and device
+        "datapath": "../Dataset/EPlus.csv",
+        "device": "cuda:1",
+
+        # Data settings
+        "resolution": 15, # 15 minutes data
+        "enLen": 48, # "Kind of warm-up"
+        "deLen": 96, # Prediction horizon, 96 is for 24 hours
+        "startday": 60, # Training data selection
+        "trainday": 90, # Training data selection
+        "testday": 1, # Testing data selection
+        "training_batch": 1024,
+        "plott": 'all', # all: If want to see how model response to max heating/cooling; else: only Tzone prediction
+        "modeltype": 'PI-modnn', # We also have "LSTM", "PI-modnn", "PI-modnn|C", "PI-modnn|L", "PI-modnn|LC" for fun
+                                 # LSTM is the baseline, |C means no constraints, |L means no loss adjustment
+        "scale": 1, # scaling factor for HVAC power
+    }
+
+    args.update(kwargs)
+
+    return args
+
+
+def get_config(overrides=None):
+    """
+    Adjust parameters as needed.
+
+    Args:
+        overrides (dict): override config like:
+            {
+                "datapath": "your_path.csv",
+                "para": {"epochs": 200, "lr": 0.01},
+                "device": "cuda:1",
+                ...
+            }
+    Returns:
+        dict: Final configuration dictionary
+    """
+    return _args(**(overrides or {}))
+
+def print_help():
+    print("\n🔧 Adjustable Parameters:\n")
+    print("General Args:")
+    print("  datapath        (str)  : Path to the dataset CSV")
+    print("  device          (str)  : Device to run the model on (e.g., 'cuda:0', 'cuda:1', 'cpu')")
+    print("  resolution      (int)  : Data resolution in minutes")
+    print("  enLen           (int)  : Encoder sequence length (timesteps), 1 step is 15 minutes")
+    print("  deLen           (int)  : Decoder sequence length, it is also prediction horizon (timesteps), 1 step is 15 minutes")
+    print("  startday        (int)  : Start day of the dataset for training")
+    print("  trainday        (int)  : Number of training days")
+    print("  testday         (int)  : Number of test days")
+    print("  training_batch  (int)  : Batch size for training")
+    print("  plott           (str)  : 'all' to plot prediction results and checking results, 'others' to plot prediction results only")
+    print("  modeltype       (str)  : LSTM, PI-modnn, PI-modnn|C, PI-modnn|L, PI-modnn|LC where LSTM is the baseline, |C means no constraints, |L means no loss adjustment")
+    print("  scale           (float): Scaling factor for HVAC power")
+    print("\nHyperparameters (args['para']):")
+    print("  Int_in, Int_h, Int_out      : Internal module input/hidden/output size")
+    print("  Ext_in, Ext_h, Ext_out      : External module input/hidden/output size")
+    print("  Zone_in, Zone_out           : Zone module input/output size")
+    print("  HVAC_in, HVAC_out           : HVAC module input/output size")
+    print("  window                      : Look up window size")
+    print("  lr                          : Learning rate")
+    print("  epochs                      : Max training epochs")
+    print("  patience                    : Early stopping patience")
+    print("\n📝 Use `get_config(overrides)` to modify these settings.\n")
+
+

modnn-1.0.0/modnn/Dataset.py

@@ -0,0 +1,175 @@
+from sklearn.preprocessing import MinMaxScaler
+from torch.utils.data import DataLoader, Dataset, random_split
+import pandas as pd
+import numpy as np
+import os
+import torch
+import pickle
+
+
+def _get_ModNN_input(start_time, timestep_minutes, occupancy=None, hvac=None,
+                         temp_amb=None, solar=None, temp_room=None, path_to_save=None):
+    """
+    Generate dataframe that can be used for modnn.
+
+    Args:
+        start_time (str): Start timestamp (e.g., '2023-07-01 00:00')
+        timestep_minutes (int): Time resolution (e.g., 15 for 15-minute steps)
+        occupancy (list or np.array): Occupancy schedule
+        hvac (list or np.array): HVAC power values (in W)
+        temp_amb (list or np.array): Ambient temperature [°F]
+        solar (list or np.array): Solar radiation [W/m²]
+        temp_room (list or np.array): Room temp [°F]
+
+    Returns:
+        pd.DataFrame: Formatted and time-indexed input DataFrame
+    """
+
+    n = len(hvac)
+    index = pd.date_range(start=start_time, periods=n, freq=f"{timestep_minutes}min")
+
+    def fill_or_default(arr, default):
+        return arr if arr is not None else np.full(n, default)
+
+    df = pd.DataFrame({
+        "temp_room": fill_or_default(temp_room, 72),
+        "temp_amb": fill_or_default(temp_amb, 85),
+        "solar": fill_or_default(solar, 0),
+        "occ": fill_or_default(occupancy, 0),
+        "phvac": hvac
+    }, index=index)
+    df=df.resample('15T').mean()
+    df.to_csv(path_to_save)
+
+    return df
+
+
+class MyData(Dataset):
+    """
+    Generate sequence-to-sequence pairs for learning.
+    """
+    def __init__(self, X_seq, y_seq):
+        self.X = np.array(X_seq)
+        self.y = np.array(y_seq)[:, :, [0]]  # Index 0 is Tzone
+
+    def __len__(self):
+        return len(self.X)
+
+    def __getitem__(self, index):
+        return torch.tensor(self.X[index], dtype=torch.float32), \
+               torch.tensor(self.y[index], dtype=torch.float32)
+
+
+class DataCook:
+    """
+    Full data pipeline for modnn:
+    - Load CSV
+    - Add time-based features
+    - Normalize inputs
+    - Slice into training/testing sequences
+    - Create PyTorch DataLoaders
+    """
+    def __init__(self, args):
+        self.args = args
+        self.df = None
+        self.processed_data = None
+
+    def load_data(self):
+        """Load raw CSV data and preprocess it."""
+        self.df = pd.read_csv(self.args["datapath"], index_col=[0])
+        self._parse_time_index()
+        self._generate_time_features()
+        self._scale_features()
+
+    def _parse_time_index(self):
+        """Convert index to datetime format (auto-detect)."""
+        try:
+            self.df.index = pd.to_datetime(self.df.index, format="%m/%d/%Y %H:%M")
+        except:
+            try:
+                self.df.index = pd.to_datetime(self.df.index, format="%Y-%m-%d %H:%M:%S")
+            except:
+                raise ValueError("Unsupported datetime format in index.")
+
+    def _generate_time_features(self):
+        """Add time-of-day features (sin and cos)."""
+        if "day_sin" not in self.df.columns:
+            time_hours = self.df.index.hour + self.df.index.minute / 60
+            self.df["day_sin"] = np.sin(2 * np.pi * time_hours / 24)
+            self.df["day_cos"] = np.cos(2 * np.pi * time_hours / 24)
+
+    def _scale_features(self):
+        """Apply MinMax scaling to each feature and save scalers."""
+        features = ["temp_room", "temp_amb", "solar", "occ", "phvac"]
+        scalers = {f: MinMaxScaler(feature_range=(-1, 1)) for f in features}
+        scalers["phvac"] = MinMaxScaler(feature_range=(-1*self.args["scale"], 1*self.args["scale"]))
+        scaled_data = [scalers[f].fit_transform(self.df[[f]]) for f in features]
+
+        # Save scalers for inference
+        os.makedirs("../Scaler", exist_ok=True)
+        with open("ModNN_scaler.pkl", "wb") as f:
+            pickle.dump(scalers, f)
+
+        self.scalers = scalers
+        self.processed_data = np.hstack([
+            scaled_data[0],  # temp_room
+            scaled_data[1],  # temp_amb
+            scaled_data[2],  # solar
+            self.df[["day_sin", "day_cos"]].values,  # keep as-is (since it is already within -1 to 1)
+            scaled_data[3],  # occ
+            scaled_data[4],  # phvac
+        ])
+
+    def prepare_data_splits(self):
+        """Split into training and testing datasets."""
+        res = int(1440 / self.args["resolution"])
+        start, train, test = self.args["startday"], self.args["trainday"], self.args["testday"]
+        en_len, de_len = self.args["enLen"], self.args["deLen"]
+
+        self.trainingdf = self.processed_data[res * start : res * (start + train)]
+        # offset a little bit, since the prediction needs to start from 12:00
+        self.testingdf = self.processed_data[res * (start + train) - en_len :
+                                             res * (start + train + test) + de_len]
+
+        self.test_raw_df = self.df.iloc[res * (start + train): res * (start + train + test + 1)]
+        self.test_start = self.test_raw_df.index[0].strftime("%m-%d")
+        self.test_end = self.test_raw_df.index[-1].strftime("%m-%d")
+
+    def create_dataloaders(self):
+        """Generate PyTorch dataloaders."""
+        self.TrainLoader, self.ValidLoader = self._create_dataloader(self.trainingdf,
+                                                                     self.args["training_batch"],
+                                                                     shuffle=True, split=0.3)
+        self.TestLoader = self._create_dataloader(self.testingdf, batch_size=len(self.testingdf), shuffle=False)
+
+    def _create_dataloader(self, data, batch_size, shuffle, split=None):
+        """Internal function to create dataset + optional split."""
+        X, y = self._generate_sequences(data)
+        dataset = MyData(X, y)
+
+        if split:
+            train_size = int((1 - split) * len(dataset))
+            valid_size = len(dataset) - train_size
+            train_ds, valid_ds = random_split(dataset, [train_size, valid_size])
+            return DataLoader(train_ds, batch_size=batch_size, shuffle=shuffle), \
+                   DataLoader(valid_ds, batch_size=batch_size, shuffle=shuffle)
+
+        return DataLoader(dataset, batch_size=batch_size, shuffle=shuffle)
+
+    def _generate_sequences(self, data):
+        """Slice data into overlapping sequences of encoder+decoder length."""
+        en_len, de_len = self.args["enLen"], self.args["deLen"]
+        X, y = [], []
+        for i in range(len(data) - (en_len + de_len)):
+            seq = data[i: i + en_len + de_len]
+            # Don't be surprise why X and Y are suing same index
+            # The offset was considered in model itself
+            X.append(seq)
+            y.append(seq)
+        return X, y
+
+    def cook(self):
+        """Run the full pipeline."""
+        self.load_data()
+        self.prepare_data_splits()
+        self.create_dataloaders()