buildyn 1.0.0__tar.gz

buildyn-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felix Koch, Thomas Krug, Benjamin Tischler
+
+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.

buildyn-1.0.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: buildyn
+Version: 1.0.0
+Author-email: Felix Koch <felix.koch@th-rosenheim.de>, Thomas Krug <thomas.krug@th-rosenheim.de>
+Requires-Python: ==3.13.*
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: more-itertools==10.6.0
+Requires-Dist: json-five==1.1.2
+Requires-Dist: fmpy==0.3.22
+Requires-Dist: matplotlib==3.10.1
+Requires-Dist: numpy==2.2.4
+Requires-Dist: pandas==2.2.3
+Requires-Dist: plotly==6.0.0
+Requires-Dist: regex==2024.11.6
+Requires-Dist: scipy==1.15.2
+Requires-Dist: ruff==0.1.10
+Requires-Dist: tqdm==4.67.1
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+Dynamic: requires-python
+
+[![Python](https://img.shields.io/badge/Python-3776AB?style=flat&logo=python&logoColor=white)](https://www.python.org/downloads/release/python-3100/)
+[![GitHub License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/felixmkoch/buildyn/blob/main/LICENSE)
+![PyPI](https://img.shields.io/badge/PyPI-available-white)
+![Version](https://img.shields.io/badge/Version-1.0.0-green)
+
+BuilDyn is an open-source free-to-use PyPI package to help simulating Functional Mockup Units (FMU) for buildings. Its primarily use is probing buildings thermal dynamics, randomizing building parameters, and demand-driven building simulation. As this is an open-source project, we encourage users and researchers to contribute with new ideas and directions to follow for future releases! 
+
+## Setup
+
+The only hard requirement for this package is python == 3.13.  
+ Aside from that, there are two ways to build this package in your environment:
+
+### Installation via Pip
+
+We distribute the newest version of this package over PyPI. 
+
+```bash
+pip install buildyn
+```
+
+### Installation from source code
+
+Aside from the pip installation, you can also build the newest version of this package from scratch. First, clone this repository.
+
+```
+git clone https://github.com/felixmkoch/buildyn.git
+```
+
+After that, you can pip install this package into your python environemnt using  
+```
+pip install .
+``` 
+
+## Strcture
+
+The package has two main classes to consider: FMU and BuilDyn. FMU is a modified and extended wrapper around the FmuSlave from FmPy. BuilDyn enables users full control over variations, walker distributions, and demand-dirven simulation. Multiple functionalities are inspired by [BuilDa](https://github.com/fabianraisch/BuilDa). For further information about the structure we refer to our paper.
+
+## Usage
+
+One general use-case would be the following:  
+```python
+from buildyn import FMU
+from buildyn.buildyn import BuilDyn
+from buildyn.walker.random.random_walker import RandomWalker
+from buildyn.walker.interval_walker import IntervalWalker
+
+
+fmu_path = "model1.fmu"
+
+start_variables = {
+    "weaDat.filNam": "resources/Munich.mos",
+    "internalGain.fileName": "resources/NoActivity.txt"
+}
+
+fmu = FMU(fmu_path, init_values=start_variables)
+
+observables = ["thermalZone.TAir", "heatingPower"]
+
+rw = RandomWalker(min=10, max=500, is_discrete=True)
+iw = IntervalWalker(rw, 900) # 900 is the step size of the walker.
+
+buildyn = BuilDyn(fmu, observables=observables)
+
+buildyn.add_walker_distribution("heatingPower", iw)
+
+print(buildyn.sample_one())
+```
+
+To explore all features of BuilDyn, we refer to our notebooks; each of them thematizes one key part.
+
+## Citation
+If you are using BuilDyn, consider citing the corresponding paper.
+```
+@inproceedings{
+  koch26buildyn,
+  title={BuilDyn: Excitation-Driven Data Generation for Building Thermal Dynamics Modeling and Control},
+  author={Koch, Felix and Krug, Thomas and Raisch, Fabian and Schäfer, Benjamin and Tischler, Benjamin},
+  booktitle={Proceedings of the 17th ACM International Conference on Future and Sustainable Energy Systems}
+  year={2026}
+}
+```
+

buildyn-1.0.0/README.md

@@ -0,0 +1,82 @@
+[![Python](https://img.shields.io/badge/Python-3776AB?style=flat&logo=python&logoColor=white)](https://www.python.org/downloads/release/python-3100/)
+[![GitHub License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/felixmkoch/buildyn/blob/main/LICENSE)
+![PyPI](https://img.shields.io/badge/PyPI-available-white)
+![Version](https://img.shields.io/badge/Version-1.0.0-green)
+
+BuilDyn is an open-source free-to-use PyPI package to help simulating Functional Mockup Units (FMU) for buildings. Its primarily use is probing buildings thermal dynamics, randomizing building parameters, and demand-driven building simulation. As this is an open-source project, we encourage users and researchers to contribute with new ideas and directions to follow for future releases! 
+
+## Setup
+
+The only hard requirement for this package is python == 3.13.  
+ Aside from that, there are two ways to build this package in your environment:
+
+### Installation via Pip
+
+We distribute the newest version of this package over PyPI. 
+
+```bash
+pip install buildyn
+```
+
+### Installation from source code
+
+Aside from the pip installation, you can also build the newest version of this package from scratch. First, clone this repository.
+
+```
+git clone https://github.com/felixmkoch/buildyn.git
+```
+
+After that, you can pip install this package into your python environemnt using  
+```
+pip install .
+``` 
+
+## Strcture
+
+The package has two main classes to consider: FMU and BuilDyn. FMU is a modified and extended wrapper around the FmuSlave from FmPy. BuilDyn enables users full control over variations, walker distributions, and demand-dirven simulation. Multiple functionalities are inspired by [BuilDa](https://github.com/fabianraisch/BuilDa). For further information about the structure we refer to our paper.
+
+## Usage
+
+One general use-case would be the following:  
+```python
+from buildyn import FMU
+from buildyn.buildyn import BuilDyn
+from buildyn.walker.random.random_walker import RandomWalker
+from buildyn.walker.interval_walker import IntervalWalker
+
+
+fmu_path = "model1.fmu"
+
+start_variables = {
+    "weaDat.filNam": "resources/Munich.mos",
+    "internalGain.fileName": "resources/NoActivity.txt"
+}
+
+fmu = FMU(fmu_path, init_values=start_variables)
+
+observables = ["thermalZone.TAir", "heatingPower"]
+
+rw = RandomWalker(min=10, max=500, is_discrete=True)
+iw = IntervalWalker(rw, 900) # 900 is the step size of the walker.
+
+buildyn = BuilDyn(fmu, observables=observables)
+
+buildyn.add_walker_distribution("heatingPower", iw)
+
+print(buildyn.sample_one())
+```
+
+To explore all features of BuilDyn, we refer to our notebooks; each of them thematizes one key part.
+
+## Citation
+If you are using BuilDyn, consider citing the corresponding paper.
+```
+@inproceedings{
+  koch26buildyn,
+  title={BuilDyn: Excitation-Driven Data Generation for Building Thermal Dynamics Modeling and Control},
+  author={Koch, Felix and Krug, Thomas and Raisch, Fabian and Schäfer, Benjamin and Tischler, Benjamin},
+  booktitle={Proceedings of the 17th ACM International Conference on Future and Sustainable Energy Systems}
+  year={2026}
+}
+```
+

buildyn-1.0.0/buildyn/__init__.py

@@ -0,0 +1,2 @@
+from .fmu import FMU
+from .buildyn import BuilDyn

buildyn-1.0.0/buildyn/buildyn.py

@@ -0,0 +1,129 @@
+from buildyn.fmu import FMU
+from typing import Dict
+from buildyn.walker.walker import Walker
+from buildyn.walker.interval_walker import IntervalWalker
+from buildyn.distributions.distribution import Distribution
+from buildyn.distributions.discrete.discrete_distribution import DiscreteDistribution
+
+from copy import copy
+import itertools
+
+class BuilDyn:
+
+    def __init__(self, 
+                 fmu: FMU,
+                 observables: list = []
+                 ):
+
+        self.variation_distributions: Dict[str, Distribution] = dict()
+
+        self.walker_distributions: Dict[str, IntervalWalker | DiscreteDistribution] = dict()
+
+        self.fmu: FMU = fmu
+
+        self.observables = observables
+
+
+    def add_variation_distribution(self, variable: str, distribution: Distribution):
+
+        self.variation_distributions[variable] = distribution
+
+
+    def add_walker_distribution(self, variable: str, distribution: IntervalWalker | DiscreteDistribution):
+
+        self.walker_distributions[variable] = distribution
+
+
+    def sample_one(self,
+                   start_time: int = 0,
+                   stop_time: int = 86_400,
+                   step_size: int = 900):
+        
+
+        # Sample one fmu with random variation
+        fmu = self.sample_one_fmu()
+
+        # Sample the walker from the correpnding walker distributions
+        walker: Dict[str, Walker] = dict()
+
+        for param, walker_dist in self.walker_distributions.items():
+            
+            if isinstance(walker_dist, IntervalWalker):
+
+                walker[param] = walker_dist
+                continue
+
+            walker[param] = walker_dist.sample_one()
+
+        res = fmu.simulate(
+                    start_time=start_time,
+                    stop_time=stop_time,
+                    step_size=step_size,
+                    observables=self.observables,
+                    walker=walker
+                )
+
+        return res
+    
+
+    def sample_one_fmu(self):
+
+        fmu = self.fmu.__copy__()
+
+        fmu_initial_variables = dict()
+
+        # Sample the variations from the corresponding distributions
+        for param, distirbution in self.variation_distributions.items():
+
+            variable_value = distirbution.sample_one()
+
+            fmu_initial_variables[param] = variable_value
+
+            fmu.set_initial_variables(variables=fmu_initial_variables)
+
+        return fmu
+    
+
+    def sample_all_fmus(self):
+
+        all_fmus = []
+        all_samples = {}
+
+        # Check if all distributions in this class are Discrete, else it would not be possible to really sample all.
+
+        for variable, distribution in self.variation_distributions.items():
+
+            if not isinstance(distribution, DiscreteDistribution):
+
+                return TypeError(f"Sampling all FMUs in not possible because {distribution.__class__.__name__} is not a discrete distribution.")
+            
+            all_samples[variable] = distribution.sample_all()
+
+        keys = list(all_samples.keys())
+        values = list(all_samples.values())
+
+        # Making the cartesian product of the sample_all
+        for combination in itertools.product(*values):
+
+            variation_dict = dict(zip(keys, combination))
+
+            fmu = copy(self.fmu)
+            fmu.set_initial_variables(variation_dict)
+
+            all_fmus.append(fmu)
+
+        return all_fmus
+
+
+
+        
+
+
+
+            
+
+            
+
+        
+
+

buildyn-1.0.0/buildyn/converter/__init__.py

@@ -0,0 +1,2 @@
+from .converter_function import ConverterFunction
+from .converter import Converter

buildyn-1.0.0/buildyn/converter/converter.py

@@ -0,0 +1,35 @@
+from buildyn.converter.converter_function import ConverterFunction
+
+class Converter:
+
+    def __init__(self):
+
+        self.converter_functions: set[ConverterFunction] = []
+
+        # For variables that should be used in the variation step of an fmu.
+        self.converter_variables: dict[str, str | bool | float | int] = {}
+
+
+    def add_converter_function(self, converter_function: ConverterFunction = None):
+
+        if not converter_function:
+            return
+        
+        self.converter_functions.append(converter_function)
+
+
+    def get_converter_functions(self) -> list[ConverterFunction]:
+
+        return self.converter_functions
+    
+
+    def update_converter_variables(self, d: dict[str, str | bool | float | int]):
+
+        self.converter_variables.update(d)
+
+
+    def get_converter_variables(self) -> dict[str, str | bool | float | int]:
+
+        return self.converter_variables
+
+        

buildyn-1.0.0/buildyn/converter/converter_function.py

@@ -0,0 +1,12 @@
+from abc import ABC
+
+class ConverterFunction(ABC):
+
+    def __init__(self):
+
+        pass
+
+
+    def convert(self, var_dict: dict):
+
+        return NotImplementedError("Function convert not implemented in this ConverterFunction. Please override this method first.")

buildyn-1.0.0/buildyn/distributions/__init__.py

@@ -0,0 +1 @@
+from .distribution import Distribution

buildyn-1.0.0/buildyn/distributions/continuous/__init__.py

@@ -0,0 +1,2 @@
+from .continuous_distribution import ContinuousDistribution
+from .gauss_distribution import GaussDistribution

buildyn-1.0.0/buildyn/distributions/continuous/continuous_distribution.py

@@ -0,0 +1,5 @@
+from buildyn.distributions.distribution import Distribution
+
+class ContinuousDistribution(Distribution):
+
+    pass

buildyn-1.0.0/buildyn/distributions/continuous/gauss_distribution.py

@@ -0,0 +1,35 @@
+from buildyn.distributions.continuous.continuous_distribution import ContinuousDistribution
+import random
+
+class GaussDistribution(ContinuousDistribution):
+
+    def __init__(self, mu, sigma, min: float = None, max: float = None):
+
+        super().__init__()
+
+        self.mu = mu
+        self.sigma = sigma
+        self.min = min
+        self.max = max
+
+
+    def sample_one(self):
+
+        # No bounds → return normally
+        if self.min is None and self.max is None:
+            return random.gauss(self.mu, self.sigma)
+
+        # Otherwise, keep sampling until value is within bounds
+        for _ in range(999):
+            value = random.gauss(self.mu, self.sigma)
+
+            if self.min is not None and value < self.min:
+                continue
+            if self.max is not None and value > self.max:
+                continue
+
+            return value
+        
+        # We assume that the min-max is near-impossible to hit.
+        raise Exception(f"Gauss distribution: Not realistic with min {self.min} and max {self.max}")
+    

buildyn-1.0.0/buildyn/distributions/discrete/__init__.py

@@ -0,0 +1,2 @@
+from .discrete_distribution import DiscreteDistribution
+from .random_choice import RandomChoiceDistribution

buildyn-1.0.0/buildyn/distributions/discrete/discrete_distribution.py

@@ -0,0 +1,10 @@
+from abc import abstractmethod
+
+from buildyn.distributions.distribution import Distribution
+
+class DiscreteDistribution(Distribution):
+
+    @abstractmethod
+    def sample_all(self):
+
+        pass

buildyn-1.0.0/buildyn/distributions/discrete/random_choice.py

@@ -0,0 +1,21 @@
+from buildyn.distributions.discrete.discrete_distribution import DiscreteDistribution
+import random
+
+class RandomChoiceDistribution(DiscreteDistribution):
+
+    def __init__(self, choices: list | set):
+
+        super().__init__()
+
+        self.choices = choices
+
+
+    def sample_one(self):
+        
+        return random.choice(self.choices)
+    
+
+    def sample_all(self):
+        
+        return self.choices
+    

buildyn-1.0.0/buildyn/distributions/distribution.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+
+class Distribution(ABC):
+
+    @abstractmethod
+    def sample_one(self):
+
+        pass
+    
+
+    def sample_multiple(self, n: int):
+
+        return [self.sample_one() for _ in range(n)]

buildyn-1.0.0/buildyn/examples/builda/builda_fmu.py

@@ -0,0 +1,104 @@
+from buildyn.converter import Converter
+from buildyn.examples.builda.converter_functions.Component_configurator import Component_configurator
+from buildyn.examples.builda.converter_functions.Link_resolver import Link_resolver
+from buildyn.examples.builda.converter_functions.Miscellaneous_handler import Miscellaneous_handler
+from buildyn.examples.builda.converter_functions.Model_compatibility_layer import Model_compatibility_layer
+from buildyn.examples.builda.converter_functions.Nominal_cooling_power_calculator import Nominal_cooling_power_calculator
+from buildyn.examples.builda.converter_functions.Nominal_heating_power_calculator import Nominal_heating_power_calculator
+from buildyn.examples.builda.converter_functions.RC_Distribution_Configurator import RC_Distribution_Configurator
+from buildyn.examples.builda.converter_functions.Zone_dimensions_calculator import Zone_dimensions_calculator
+from buildyn.examples.builda.converter_functions.Component_properties_calculator import Component_properties_calculator
+
+
+# Helper function to retrieve the pre-configured BuilDa FMU with all converter functions and default values set.
+def get_configured_builda_fmu(internal_controller: bool = False):
+
+    converter = Converter()
+
+    # All the converter functiosn from BuilDa 2.0
+    converter_functions = [Link_resolver, Miscellaneous_handler, Model_compatibility_layer, Zone_dimensions_calculator, Component_configurator, RC_Distribution_Configurator, Component_properties_calculator, Nominal_heating_power_calculator, Nominal_cooling_power_calculator]
+
+    for cf in converter_functions:
+        converter.add_converter_function(cf())
+
+    converter_variables = {
+        "zone_length": 9.4125,
+        "zone_width": 8,
+        "floor_height": 3.04,
+        "n_floors": 2,
+        "fAWin_south": 0.14056,
+        "fAWin_west": 0.14056,
+        "fAWin_north": 0.14056,
+        "fAWin_east": 0.14056,
+        "fATransToAWindow": 0.9,
+        "fARoofToAFloor": 1.63612217795485,
+        "fAInt": 1.238235294117647,
+        "heatCapacity_furniture_per_m2": 2230,
+        "UExt": 0.665,
+        "heatCapacity_wall": 192000,
+        "UFloor": 0.514,
+        "heatCapacity_floor": 483840,
+        "UInt": 1,
+        "heatCapacity_internalWall": 145154,
+        "URoof": 0.402,
+        "heatCapacity_roof": 81240,
+        "UWin": 3.2,
+        "thermalZone.gWin": 0.7,
+        "heatRecoveryRate": 0,
+        "airChangeRate": 0.3,
+        "heatingCurve_steepness": 1,
+        "relative_heatPump_efficiency": 0.8,
+        "internalGainsConvectiveFraction": 0.4,
+        "heatingConvectiveFraction": 1,
+        "weaDat.fileName": "resources/Munich.mos",
+        "internalGain.fileName": "resources/NoActivity.txt",
+        "hygienicalWindowOpening.fileName": "resources/no_opening.txt",
+        "roomTempLowerSetpoint": 18,
+        "roomTempUpperSetpoint": 22,
+        #"UseInternalController": 0,
+        "extWall_C_distribution": "monolythic",
+        "floor_C_distribution": [478800, 5040, 0.001],
+        "roof_C_distribution": [22440, 58800, 0.001],
+        "extWall_R_distribution": "monolythic",
+        "floor_R_distribution": [0.0525, 0.0525, 0.1579, 0.0001],
+        "roof_R_distribution": [1.1085, 1.1085, 0.1, 0.0001],
+        "intWall_R_distribution": "monolythic",
+        "intWall_C_distribution": "monolythic",
+        "Rsi_extWall": 0.13333333333333333,
+        "Rsi_intWall": 0.13333333333333333,
+        "Rsi_floor": 0.17543859649122806,
+        "Rsi_roof": 0.1,
+        "Rse_extWall": 0.04,
+        "Rse_roof": 0.04,
+        "Rsi_window": 0.13333333333333333,
+        "Rse_window": 0.05,
+        "ta_min": None,
+        "ti_set": None
+    }
+
+    # Set the converter variables in the converter. This also updates previously set variables.
+    converter.update_converter_variables(converter_variables)
+
+    from buildyn import FMU
+    import json
+
+    # Example FMU from BuilDa 2.0
+    fmu_path = "resources/building.fmu"
+
+    # Initial variables from the BuilDa 2.0 FMU -> Needs extra variables here because the BuilDa FMU is weird. For other use-cases you don't have to do this.
+    with open("resources/fmu_state_dict.json", "r") as f:
+        start_variables = json.load(f)
+
+    start_variables.update({
+        "weaDat.filNam": "resources/Munich.mos",
+        "internalGain.fileName": "resources/NoActivity.txt",
+        "hygienicalWindowOpening.fileName": "resources/no_opening.txt",
+        "UseInternalController.k": 1 if internal_controller else 0
+    })
+
+    # FMU object from the buil_dyn package
+    fmu = FMU(fmu_file=fmu_path, init_values=start_variables)
+
+    fmu.set_converter(converter=converter)
+
+    return fmu