OpenSimula 0.8.7__tar.gz → 0.8.9__tar.gz

{opensimula-0.8.7/src/opensimula.egg-info → opensimula-0.8.9}/PKG-INFO

@@ -1,8 +1,10 @@
 Metadata-Version: 2.4
 Name: opensimula
-Version: 0.8.7
+Version: 0.8.9
 Summary: Component-based time simulation environment in Python
+Author: Luis Pérez-Lombard, Ismael R. Maestre
 Author-email: "Juan F. Coronel" <jfc@us.es>
+Maintainer-email: "Juan F. Coronel" <jfc@us.es>
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -24,8 +26,10 @@ Dynamic: license-file
 
 # OpenSimula
 
+[![Tests](https://github.com/jfCoronel/OpenSimula/actions/workflows/tests.yml/badge.svg)](https://github.com/jfCoronel/OpenSimula/actions/workflows/tests.yml)
 [![PyPI version](https://img.shields.io/pypi/v/opensimula)](https://pypi.org/project/opensimula/)
 [![Python versions](https://img.shields.io/pypi/pyversions/opensimula)](https://pypi.org/project/opensimula/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23210985.svg)](https://doi.org/10.5281/zenodo.23210985)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 **OpenSimula** is a component-based time simulation environment in Python, focused on the
@@ -162,9 +166,28 @@ reference, is at [jfcoronel.github.io/OpenSimula](https://jfcoronel.github.io/Op
 Bugs and feature requests are tracked on
 [GitHub Issues](https://github.com/jfCoronel/OpenSimula/issues).
 
-## Main Developers
+## Contributing
 
-* [Juan F. Coronel](http://jfc.us.es), Universidad de Sevilla
+Contributions are welcome: bug reports, fixes, new components, validation cases and examples.
+See [CONTRIBUTING.md](https://github.com/jfCoronel/OpenSimula/blob/main/CONTRIBUTING.md) for how to set up a development environment, run the
+tests and submit a pull request.
+
+## Citing OpenSimula
+
+If you use OpenSimula in your research, please cite it with its DOI,
+[10.5281/zenodo.23210985](https://doi.org/10.5281/zenodo.23210985), which always resolves to
+the latest version (each version also has its own DOI, listed on
+[Zenodo](https://doi.org/10.5281/zenodo.23210985)). The full metadata is in
+[CITATION.cff](https://github.com/jfCoronel/OpenSimula/blob/main/CITATION.cff) (GitHub's "Cite this repository" button generates APA and BibTeX
+entries from it).
+
+## Authors
+
+* [Juan F. Coronel](http://jfc.us.es), Universidad de Sevilla — creator, lead developer and maintainer
+* Luis Pérez-Lombard, Universidad de Sevilla — reviewer and advisor on the HVAC models, tester
+  and co-author of the validation test cases
+* Ismael R. Maestre, Universidad de Cádiz — reviewer and advisor on the building envelope
+  models, tester and co-author of the validation test cases
 
 ## License
 

{opensimula-0.8.7 → opensimula-0.8.9}/README.md

@@ -2,8 +2,10 @@
 
 # OpenSimula
 
+[![Tests](https://github.com/jfCoronel/OpenSimula/actions/workflows/tests.yml/badge.svg)](https://github.com/jfCoronel/OpenSimula/actions/workflows/tests.yml)
 [![PyPI version](https://img.shields.io/pypi/v/opensimula)](https://pypi.org/project/opensimula/)
 [![Python versions](https://img.shields.io/pypi/pyversions/opensimula)](https://pypi.org/project/opensimula/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23210985.svg)](https://doi.org/10.5281/zenodo.23210985)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 **OpenSimula** is a component-based time simulation environment in Python, focused on the
@@ -140,9 +142,28 @@ reference, is at [jfcoronel.github.io/OpenSimula](https://jfcoronel.github.io/Op
 Bugs and feature requests are tracked on
 [GitHub Issues](https://github.com/jfCoronel/OpenSimula/issues).
 
-## Main Developers
+## Contributing
 
-* [Juan F. Coronel](http://jfc.us.es), Universidad de Sevilla
+Contributions are welcome: bug reports, fixes, new components, validation cases and examples.
+See [CONTRIBUTING.md](https://github.com/jfCoronel/OpenSimula/blob/main/CONTRIBUTING.md) for how to set up a development environment, run the
+tests and submit a pull request.
+
+## Citing OpenSimula
+
+If you use OpenSimula in your research, please cite it with its DOI,
+[10.5281/zenodo.23210985](https://doi.org/10.5281/zenodo.23210985), which always resolves to
+the latest version (each version also has its own DOI, listed on
+[Zenodo](https://doi.org/10.5281/zenodo.23210985)). The full metadata is in
+[CITATION.cff](https://github.com/jfCoronel/OpenSimula/blob/main/CITATION.cff) (GitHub's "Cite this repository" button generates APA and BibTeX
+entries from it).
+
+## Authors
+
+* [Juan F. Coronel](http://jfc.us.es), Universidad de Sevilla — creator, lead developer and maintainer
+* Luis Pérez-Lombard, Universidad de Sevilla — reviewer and advisor on the HVAC models, tester
+  and co-author of the validation test cases
+* Ismael R. Maestre, Universidad de Cádiz — reviewer and advisor on the building envelope
+  models, tester and co-author of the validation test cases
 
 ## License
 

{opensimula-0.8.7 → opensimula-0.8.9}/pyproject.toml

@@ -1,9 +1,14 @@
 [project]
 name = "opensimula"
-version = "0.8.7"
+version = "0.8.9"
 requires-python = ">=3.12"
 authors = [
   { name="Juan F. Coronel", email="jfc@us.es" },
+  { name="Luis Pérez-Lombard" },
+  { name="Ismael R. Maestre" },
+]
+maintainers = [
+  { name="Juan F. Coronel", email="jfc@us.es" },
 ]
 description = "Component-based time simulation environment in Python"
 readme = "README.md"
@@ -28,6 +33,7 @@ dev = [
     "mkdocs>=1.6.1",
     "pytest>=8.4.2",
     "marimo>=0.19.0",
+    "mkdocstrings[python]>=1.0.8",
 ]
 
 [tool.setuptools]

{opensimula-0.8.7 → opensimula-0.8.9}/src/opensimula/Component.py

@@ -5,9 +5,26 @@ from opensimula.Variable import Variable
 
 
 class Component(Parameter_container):
-    """Base Class for all the components"""
+    """Base Class for all the components
+
+    A component has parameters (inherited from Parameter_container, with `name`,
+    `description` and `type`) and variables (time series filled during the simulation).
+    Components are created by the project (`Project.new_component()`, `read_dict()`,
+    `read_json()`), not directly.
+
+    New component types inherit from this class: they add their parameters and variables
+    in `__init__()`, validate them in `check()` and override the simulation methods
+    (`pre_simulation()`, `pre_iteration()`, `iteration()`, `post_iteration()`,
+    `post_simulation()`) that the project calls in this order. See the developer guide.
+    """
 
     def __init__(self, name, proj):
+        """Create new component
+
+        Args:
+            name (str): name of the component
+            proj (Project): project the component belongs to
+        """
         Parameter_container.__init__(self, proj._sim_)
         self._variables_ = {}
         self.add_parameter(Parameter_string("type", "Component"))
@@ -16,35 +33,62 @@ class Component(Parameter_container):
         self._project_ = proj
 
     def project(self):
+        """Project the component belongs to
+
+        Returns:
+            Project: parent project
+        """
         return self._project_
 
     def add_variable(self, variable):
-        """add new Variable"""
+        """Add a new variable to the component
+
+        Args:
+            variable (Variable): variable to add, replaces any variable with the same key
+        """
         variable.parent = self
         variable._sim_ = self._sim_
         self._variables_[variable.key] = variable
 
     def del_variable(self, variable):
+        """Remove a variable from the component
+
+        Args:
+            variable (Variable): variable to remove
+        """
         self._variables_.pop(variable.key,None)
 
     def variable(self, key):
+        """Find and return a variable using its key
+
+        Args:
+            key (str): key of the variable, e.g. "temperature"
+
+        Returns:
+            Variable: the variable (KeyError if it does not exist)
+        """
         return self._variables_[key]
 
     def variable_dict(self):
+        """Variables of the component
+
+        Returns:
+            dict: {key: Variable}
+        """
         return self._variables_
 
     def variable_dataframe(self, units=False, frequency=None, value="mean", interval=None, pos_neg_columns=[]):
-        """_summary_
+        """Variables of the component as a table
 
         Args:
-            units (bool, optional): Includes unit in the name of the variable. Defaults to True.
+            units (bool, optional): Includes unit in the name of the variable. Defaults to False.
             frequency (None or str, optional): frequency of the values: None, "hourly", "daily", "monthly", "yearly". Defaults to None.
             value (str, optional): "mean", "sum", "sum_pos", "sum_neg", "max" or "min". Defaults to "mean".
             interval (None or list of two dates): List with the start and end dates of the period to be included in the dataframe, if the value is None all values are included.
             pos_neg_columns (list of str, optional): List of variables that will be included in separate columns positive and negative values. Defaults to [].
 
         Returns:
-            pandas DataFrame: Returns all the variables 
+            pandas.DataFrame: column "date" and one column per variable
         """
         series = {}
         series["date"] = self.project().dates()
@@ -92,7 +136,7 @@ class Component(Parameter_container):
                 been the walk follows it until the stack runs out.
 
         Returns:
-            component_list (component[])
+            list of Component: referenced components and, last, the component itself
         """
         if _seen is None:
             _seen = set()
@@ -125,8 +169,12 @@ class Component(Parameter_container):
     def check(self):
         """Check if all is correct
 
+        Checks every parameter and creates the variables of the `Parameter_variable` and
+        `Parameter_variable_list` parameters. Components that override it call this one
+        first and add their own checks.
+
         Returns:
-            errors (string list): List of errors
+            list of Message: errors found
         """
         errors = []
         # Parameter errors
@@ -152,6 +200,16 @@ class Component(Parameter_container):
         return errors
 
     def get_parameter_variable_dictionary(self,time_index):
+        """Values of the variables taken from `Parameter_variable` parameters at a time step
+
+        Used to evaluate `Parameter_math_exp` expressions.
+
+        Args:
+            time_index (int): index of the time step
+
+        Returns:
+            dict: {symbol: value}
+        """
         # variables dictonary
         var_dic = {}
         for i in range(len(self._var_from_parameter_symbol)):
@@ -159,6 +217,15 @@ class Component(Parameter_container):
         return var_dic
 
     def pre_simulation(self, n_time_steps, delta_t):
+        """Prepare the component before the time loop of the simulation
+
+        The base method sets up the variables of the `Parameter_variable` parameters and
+        initialises every variable to zeros. Overriding methods call it first.
+
+        Args:
+            n_time_steps (int): number of time steps of the simulation
+            delta_t (int): time step (s)
+        """
         # Create variables from paramater "Parameter_variable" and "Parameter_variable_list"
         self._var_from_parameter_symbol = []
         self._var_from_parameter_variable = []
@@ -176,9 +243,20 @@ class Component(Parameter_container):
             var.initialise(n_time_steps)
 
     def post_simulation(self):
+        """Finish the component after the time loop of the simulation"""
         pass
 
     def pre_iteration(self, time_index, date, daylight_saving):
+        """Prepare the time step, before its iterations
+
+        The base method copies the values of the `Parameter_variable` parameters at the
+        time step. Overriding methods call it first.
+
+        Args:
+            time_index (int): index of the time step
+            date (datetime): date of the time step (center of the interval)
+            daylight_saving (bool): daylight saving time is in effect
+        """
         # Initilise all variables to 0
         for key, value in self.parameter_dict().items():
             # Copy variables in paramater_variable
@@ -193,9 +271,31 @@ class Component(Parameter_container):
                             value.symbol[i]).values[time_index] = value.variable[i].values[time_index]
 
     def iteration(self, time_index, date, daylight_saving, n_iter):
+        """Calculate one iteration of the time step
+
+        The project repeats the iterations of every component until all of them return
+        True or the maximum number of iterations is reached.
+
+        Args:
+            time_index (int): index of the time step
+            date (datetime): date of the time step (center of the interval)
+            daylight_saving (bool): daylight saving time is in effect
+            n_iter (int): number of the iteration in the time step, from 0
+
+        Returns:
+            bool: the component has converged
+        """
         return True
 
     def post_iteration(self, time_index, date, daylight_saving, converged):
+        """Finish the time step, after its iterations
+
+        Args:
+            time_index (int): index of the time step
+            date (datetime): date of the time step (center of the interval)
+            daylight_saving (bool): daylight saving time is in effect
+            converged (bool): every component converged in the time step
+        """
         pass
 
     def _repr_html_(self):
@@ -208,6 +308,11 @@ class Component(Parameter_container):
         return html
 
     def variable_html(self):
+        """Key, description and unit of the variables as an HTML table
+
+        Returns:
+            str: HTML table
+        """
         keys = []
         descriptions = []
         units = []
@@ -222,5 +327,10 @@ class Component(Parameter_container):
         return data.to_html()
 
     def function_html(self):
+        """Short HTML help of the component's table methods
+
+        Returns:
+            str: HTML text
+        """
         html = "<p><strong>parameter_dataframe():</strong> Return pandas DataFrame with the component parametes.</p>"
         html += "<p><strong>variable_dataframe():</strong> Return pandas DataFrame with the component variables.</p>"

opensimula-0.8.9/src/opensimula/Iterative_process.py

@@ -0,0 +1,85 @@
+import math
+
+class Iterative_process:
+    """Iterative process using the fixed-point method with adaptive relaxation coefficient
+
+    Used by the components to converge a value coupled with other components (e.g. the
+    temperature or humidity of a space) within the iterations of a time step:
+
+    ```python
+    it = Iterative_process(x_0, tol=0.01)
+    # in each iteration, with the value proposed by the component's equations
+    x = it.estimate_next_x(proposed_x)
+    converged = it.converged()
+    ```
+    """
+
+    def __init__(self, x_0, tol = 1e-5, lambda_min=0.1, lambda_max=1.0, n_ini_relax=2,rel_vel = 0.9):
+        """Create new iterative process
+
+        Args:
+            x_0 (float): Initial value
+            tol (float, optional): convergence tolerance of the residual. Defaults to 1e-5.
+            lambda_min (float, optional): minimum relaxation coefficient. Defaults to 0.1.
+            lambda_max (float, optional): maximum (and initial) relaxation coefficient.
+                Defaults to 1.0.
+            n_ini_relax (int, optional): Number of iterations in which adaptive relaxation
+                is initiated, must be greater than 1. Defaults to 2.
+            rel_vel (float, optional): factor that reduces (or, divided, recovers) the
+                relaxation coefficient. Defaults to 0.9.
+        """
+        self.x = [x_0]
+        self.tol = tol
+        self.lambda_min = lambda_min
+        self.lambda_max = lambda_max
+        self.lambda_i = lambda_max
+        self.n_ini_relax = n_ini_relax
+        self.rel_vel = rel_vel
+        self.residual = None  # |proposed_x - x| of the last iteration
+
+    def converged(self):
+        """The residual of the last iteration is below the tolerance
+
+        Returns:
+            bool: converged
+        """
+        # Fixed-point residual, not the relaxed step: with relaxation lambda the step is only
+        # lambda * residual, so testing the step stopped with residuals up to tol / lambda_min
+        # (10 x tol), e.g. zones far from their moisture balance in steady state
+        return self.residual is not None and self.residual < self.tol
+
+    def estimate_next_x(self, proposed_x):
+        """Relaxed next value from the value proposed by the fixed-point equation
+
+        Args:
+            proposed_x (float): value given by the equations from the last value
+
+        Returns:
+            float: next value, `(1 - lambda) * x + lambda * proposed_x`
+        """
+        residual = proposed_x - self.x[-1]
+        x_next = (1 - self.lambda_i) * self.x[-1] + self.lambda_i * proposed_x
+
+        # Adaptive relaxation: reduce lambda when the iteration oscillates (the residual
+        # changes sign) or does not contract (the residual grows), and recover it while it
+        # contracts; reducing it unconditionally made well-behaved iterations crawl
+        # (lambda_min after ~10 iterations)
+        if len(self.x) > self.n_ini_relax and self.residual is not None:
+            if residual * self._last_residual < 0 or abs(residual) > self.residual:
+                self.lambda_i = max(self.lambda_min, self.lambda_i * self.rel_vel)
+            else:
+                self.lambda_i = min(self.lambda_max, self.lambda_i / self.rel_vel)
+        self._last_residual = residual
+        self.residual = abs(residual)
+
+        self.x.append(x_next)
+        return x_next
+    
+    def set_next_x(self, next_x):
+        """Set the next value directly, without relaxation
+
+        Args:
+            next_x (float): next value
+        """
+        self.x.append(next_x)
+

opensimula-0.8.9/src/opensimula/Message.py

@@ -0,0 +1,35 @@
+class Message:
+    """Message of the simulation environment (error, warning or information)
+
+    Messages are added with `Simulation.message()` and listed with
+    `Simulation.message_list()`.
+    """
+
+    def __init__(self, text, level="ERROR"):
+        """Create new message
+
+        Args:
+            text (str): text of the message
+            level (str, optional): "ERROR", "WARNING", "INFO" or "CONSOLE". Defaults to
+                "ERROR".
+        """
+        self._text_ = text
+        self._level_ = level   # ERROR, WARNING, INFO, CONSOLE
+
+    @property
+    def text(self):
+        """str: text of the message"""
+        return self._text_
+
+    @property
+    def level(self):
+        """str: "ERROR", "WARNING", "INFO" or "CONSOLE" """
+        return self._level_
+    
+    def print(self):
+        """Print the message, preceded by its level unless it is "CONSOLE" """
+        if self.level == "CONSOLE":
+            print(self.text)
+        else:
+            print(self.level + ": " + self.text)
+        

{opensimula-0.8.7 → opensimula-0.8.9}/src/opensimula/Parameter_container.py

@@ -3,40 +3,71 @@ from opensimula.Parameters import Parameter_string
 from opensimula.Message import Message
 
 class Parameter_container:
-    """Class to manage a list of Paramaters
+    """Class to manage a list of Parameters
 
     Superclass for Projects and Components
 
     Default parameters included:
+
     - name (string)
     - description (string)
-
     """
 
     def __init__(self, sim):
+        """Create the container with the parameters name and description
+
+        Args:
+            sim (Simulation): simulation environment, used to report messages
+        """
         self._sim_ = sim
         self._parameters_ = {}
         self.add_parameter(Parameter_string("name", "Name"))
         self.add_parameter(Parameter_string("description", "Description"))
 
     def add_parameter(self, param):
-        """add Parameter"""
+        """Add a parameter
+
+        Args:
+            param (Parameter): parameter to add, replaces any parameter with the same key
+        """
         param.parent = self
         param._sim_ = self._sim_
         self._parameters_[param.key] = param
 
     def del_parameter(self, param):
-        """Deletet parameter"""
-        self._parameters_.remove(param)
+        """Delete a parameter
+
+        Args:
+            param (Parameter): parameter to delete
+        """
+        self._parameters_.pop(param.key, None)
 
     def parameter(self, key):
+        """Find and return a parameter using its key
+
+        Args:
+            key (str): key of the parameter, e.g. "name"
+
+        Returns:
+            Parameter: the parameter (KeyError if it does not exist); read or change its
+                value with `.value`
+        """
         return self._parameters_[key]
 
     def parameter_dict(self):
+        """Parameters of the container
+
+        Returns:
+            dict: {key: Parameter}
+        """
         return self._parameters_
 
     def set_parameters(self, dictonary):
-        """Read parameters from dictonary"""
+        """Set parameter values from a dictionary
+
+        Args:
+            dictonary (dict): {key: value}; unknown keys are reported as errors
+        """
         for key, value in dictonary.items():
             if key in self._parameters_:
                 self.parameter(key).value = value
@@ -44,6 +75,14 @@ class Parameter_container:
                 self._sim_.message(Message("Component parameter " + key + " does not exist","ERROR"))
 
     def parameter_dataframe(self, string_format=False):
+        """Parameters as a table
+
+        Args:
+            string_format (bool, optional): Convert every value to string. Defaults to False.
+
+        Returns:
+            pandas.DataFrame: key, type, value and unit of each parameter
+        """
         keys = []
         values = []
         types = []
@@ -69,7 +108,7 @@ class Parameter_container:
         """Check if all is correct
 
         Returns:
-            errors (string list): List of errors
+            list of Message: errors found
         """
         errors = []
         for key, value in self._parameters_.items():