OpenSimula 0.8.7__tar.gz → 0.8.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensimula
-Version: 0.8.7
+Version: 0.8.8
 Summary: Component-based time simulation environment in Python
 Author-email: "Juan F. Coronel" <jfc@us.es>
 Requires-Python: >=3.12
@@ -24,8 +24,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,6 +164,21 @@ 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).
 
+## Contributing
+
+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).
+
 ## Main Developers
 
 * [Juan F. Coronel](http://jfc.us.es), Universidad de Sevilla

{opensimula-0.8.7 → opensimula-0.8.8}/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,6 +142,21 @@ 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).
 
+## Contributing
+
+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).
+
 ## Main Developers
 
 * [Juan F. Coronel](http://jfc.us.es), Universidad de Sevilla

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

@@ -1,6 +1,6 @@
 [project]
 name = "opensimula"
-version = "0.8.7"
+version = "0.8.8"
 requires-python = ">=3.12"
 authors = [
   { name="Juan F. Coronel", email="jfc@us.es" },

opensimula-0.8.8/src/opensimula/Iterative_process.py

@@ -0,0 +1,50 @@
+import math
+
+class Iterative_process:
+    def __init__(self, x_0, tol = 1e-5, lambda_min=0.1, lambda_max=1.0, n_ini_relax=2,rel_vel = 0.9):
+        """
+        Iterative process using the fixed-point method with adaptive relaxation coefficient
+    
+        Parameters:
+        x_0: Initial value
+        tol: convergence tolerance
+        lambda_min, lambda_max: relaxation coefficient range
+        n_ini_relax: Number of iterations in which adaptive relaxation is initiated, must be greater than 1
+        """
+        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):
+        # 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):
+        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):
+        self.x.append(next_x)
+

{opensimula-0.8.7 → opensimula-0.8.8}/src/opensimula/components/Building.py

@@ -85,7 +85,7 @@ class Building(Component):
         SWR_matrix = (SWR_matrix - np.matmul(self.ff_matrix, rho_matrix)
             - np.matmul(self.ff_matrix, np.matmul(tau_matrix, self.B_matrix)))
 
-        SWR_matrix = np.linalg.inv(SWR_matrix)
+        SWR_matrix = _radiosity_inverse_(SWR_matrix)
         aux_matrix = np.matmul(area_matrix, np.matmul(alpha_matrix, SWR_matrix))
         self.SWDIF_matrix = np.matmul(aux_matrix, np.matmul(self.ff_matrix, tau_matrix))  # SW Solar Diffuse
 
@@ -119,7 +119,7 @@ class Building(Component):
         LWR_matrix = (LWR_matrix - np.matmul(self.ff_matrix, rho_matrix)
             - np.matmul(self.ff_matrix, np.matmul(tau_matrix, self.B_matrix)))
 
-        LWR_matrix = np.linalg.inv(LWR_matrix)
+        LWR_matrix = _radiosity_inverse_(LWR_matrix)
         aux_matrix = np.matmul(area_matrix, np.matmul(alpha_matrix,LWR_matrix))
 
         ig_dist_matrix = np.zeros((self._n_surfaces, self._n_spaces))
@@ -508,4 +508,18 @@ class Building(Component):
     
     # _______________ post_iteration _______________
     def post_iteration(self, time_index, date, daylight_saving, converged):
-        super().post_iteration(time_index, date, daylight_saving, converged)
+        super().post_iteration(time_index, date, daylight_saving, converged)
+
+
+def _radiosity_inverse_(matrix):
+    """Inverse of a radiosity matrix (I - F·rho - F·tau·B).
+
+    In a closed enclosure whose surfaces neither absorb nor transmit (rho = 1, e.g. surfaces
+    with solar absorptance or emissivity 0, as in the ASHRAE 140 ground-coupling cases) the
+    matrix is singular, since the rows of F sum to 1. Nothing is absorbed then, so any
+    generalised inverse gives the same (zero) absorbed radiation: use the pseudo-inverse.
+    """
+    try:
+        return np.linalg.inv(matrix)
+    except np.linalg.LinAlgError:
+        return np.linalg.pinv(matrix)

{opensimula-0.8.7 → opensimula-0.8.8}/src/opensimula/components/Construction.py

@@ -281,7 +281,10 @@ class Construction(Component):
         ox = []
         oy = []
         oz = []
-        for i in range(1, n_coef):
+        # n_coef terms of the response series give n_coef valid a, b, c coefficients, as many
+        # as d has: with one fewer, the steady state (sum(a)/sum(d) = U) failed for light
+        # constructions with few roots, e.g. 6.59 instead of 5.05 W/m²K for a thin panel
+        for i in range(1, n_coef + 1):
             sum_exp_x = 0
             sum_exp_y = 0
             sum_exp_z = 0
@@ -304,10 +307,11 @@ class Construction(Component):
             if math.fabs(d[i]) < min_coef:
                 d = d[0: i+1]
                 break
-        # Cut number of coeficients, se producen coeficientes extraños para muros ligeros a partir del n. de roots
-        a = np.resize(a, n_coef-1)
-        b = np.resize(b, n_coef-1)
-        c = np.resize(c, n_coef-1)
+        # Only the first n_coef terms of the convolutions are valid (the response series
+        # above are truncated after n_coef terms)
+        a = np.resize(a, n_coef)
+        b = np.resize(b, n_coef)
+        c = np.resize(c, n_coef)
         # Cut a, b, c coefficients
         for i in range(len(a)):
             if (

{opensimula-0.8.7 → opensimula-0.8.8}/src/opensimula/components/File_met.py

@@ -68,6 +68,7 @@ class File_met(Component):
         self.pressure = np.zeros(8760)
         self.total_cloud_cover = np.zeros(8760)
         self.opaque_cloud_cover = np.zeros(8760)
+        self._delta_t = 3600  # time step, set by pre_simulation
 
     def check(self):
         errors = super().check()
@@ -219,6 +220,7 @@ class File_met(Component):
 
     def pre_simulation(self, n_time_steps, delta_t):
         super().pre_simulation(n_time_steps, delta_t)
+        self._delta_t = delta_t
 
     def pre_iteration(self, time_index, date, daylight_saving):
         super().pre_iteration(time_index, date, daylight_saving)
@@ -262,6 +264,8 @@ class File_met(Component):
                           time_index, i, j, f)
         self._interpolate("opaque_cloud_cover", self.opaque_cloud_cover,
                           time_index, i, j, f)
+        if self._sub_hourly_integrated_radiation_():
+            self._set_sub_hourly_radiation_(time_index, date, alt)
         # Corregir la directa si el sol no ha salido, y con alturas solares pequeñas
         if (alt < 3 and self.variable("sol_direct").values[time_index] > 0):
             self.variable(
@@ -282,6 +286,37 @@ class File_met(Component):
         self.variable("wet_bulb_temp").values[time_index] = sicro.GetTWetBulbFromRelHum(
             T, HR, p)
 
+    def _sub_hourly_integrated_radiation_(self):
+        """TMY3, TMY2 and WYEC2 radiation values are totals over the hour before each record."""
+        return (
+            self.parameter("file_type").value in ("TMY3", "TMY2", "WYEC2")
+            and self._delta_t < 3600
+            and 3600 % self._delta_t == 0
+        )
+
+    def _set_sub_hourly_radiation_(self, time_index, date, alt):
+        """Radiation of a sub-hourly time step that keeps the hour total of the file.
+
+        Interpolating linearly between hour centres would spread a quarter of each hour's
+        radiation over the neighbouring hours. Instead, the diffuse radiation is held through
+        the hour and the horizontal direct radiation follows the sine of the solar altitude,
+        scaled so that its mean over the time steps of the hour is the file value.
+        """
+        hour_start = date.replace(minute=0, second=0, microsecond=0)
+        k = int((hour_start - dt.datetime(date.year, 1, 1)).total_seconds() // 3600) % 8760
+        n = round(3600 / self._delta_t)
+        sin_alt = [
+            max(math.sin(math.radians(self.sunpos(hour_start + dt.timedelta(seconds=(m + 0.5) * self._delta_t))[1])), 0)
+            for m in range(n)
+        ]
+        mean_sin_alt = sum(sin_alt) / n
+        if mean_sin_alt > 0:
+            direct = self.sol_direct[k] * max(math.sin(math.radians(alt)), 0) / mean_sin_alt
+        else:
+            direct = 0
+        self.variable("sol_direct").values[time_index] = direct
+        self.variable("sol_diffuse").values[time_index] = self.sol_diffuse[k]
+
     def _interpolate(self, variable, array, time_i, i, j, f):
         self.variable(
             variable).values[time_i] = array[i] * (1 - f) + array[j] * f
@@ -377,66 +412,53 @@ class File_met(Component):
             return 0
         model = self.parameter("tilted_diffuse_model").value
         beta = math.radians(surf_altitude)
-        if (model == "ISOTROPIC"):
-            # Isotropic diffuse radiation (Liu-Jordan model)
-            E_dif = sol_diffuse * (1 + math.sin(beta))/2
-        elif (model == "HAY-DAVIES"):
-            theta = self.solar_surface_angle(
-                time_index, surf_azimuth, surf_altitude)
-            if theta is not None:
-                sol_direct = self.variable("sol_direct").values[time_index]
-                sol_altitude = math.radians(self.variable(
-                    "sol_altitude").values[time_index])
-                A = sol_direct/math.sin(sol_altitude)/1353
-                R_b = math.cos(theta) / math.sin(sol_altitude)
-                E_dif = sol_diffuse * A * R_b + sol_diffuse * \
-                    (1-A) * (1 + math.sin(beta))/2
-            else:
-                E_dif = sol_diffuse * (1 + math.sin(beta))/2
-        elif (model == "REINDL"):
-            theta = self.solar_surface_angle(
-                time_index, surf_azimuth, surf_altitude)
-            sol_altitude = math.radians(self.variable(
-                "sol_altitude").values[time_index])
-            sol_direct = self.variable("sol_direct").values[time_index]
-            zenit = math.pi/2 - beta
-            f_horizon = 1 + \
-                math.sqrt(sol_direct/(sol_direct+sol_diffuse)) * \
-                (math.sin(zenit/2))**3
-            if theta is not None:
-                A = sol_direct/math.sin(sol_altitude)/1353
-                R_b = math.cos(theta) / math.sin(sol_altitude)
-                E_dif = sol_diffuse * A * R_b + sol_diffuse * \
-                    (1-A) * (1 + math.sin(beta))/2 * f_horizon
-            else:
-                E_dif = sol_diffuse * (1 + math.sin(beta))/2 * f_horizon
-        elif (model == "PEREZ"):
-            theta = self.solar_surface_angle(
-                time_index, surf_azimuth, surf_altitude)
-            if theta is None:  # No direct sun
-                E_dif = sol_diffuse * (1 + math.sin(beta))/2
-            else:
-                sol_altitude = math.radians(self.variable(
-                    "sol_altitude").values[time_index])
-                sol_direct = self.variable("sol_direct").values[time_index]
-                zenit = math.pi/2 - beta
-                sol_zenit = math.pi/2 - sol_altitude
-                epsilon = ((sol_direct/math.sin(sol_altitude)+sol_diffuse) /
-                           sol_diffuse + 1.041 * sol_zenit**3)/(1 + 1.041*sol_zenit**3)
-                m = 1 / math.cos(sol_zenit)
-                Delta = m*sol_diffuse/1353
-                f = self._perez_coef(epsilon)
-                F_2 = f[3]+f[4]*Delta+f[5]*sol_zenit
-                a = math.cos(theta)
-                b = max(0.087156, math.cos(sol_zenit))
-                F_1 = max(0, f[0]+f[1]*Delta+f[2]*sol_zenit)
-                E_dif = sol_diffuse * \
-                    ((1-F_1)*(1+math.cos(zenit))/2 +
-                     F_1 * a/b + F_2 * math.sin(zenit))
-        return E_dif
+        isotropic = sol_diffuse * (1 + math.sin(beta)) / 2
+        if model == "ISOTROPIC":  # Liu-Jordan model
+            return isotropic
+        # Anisotropic models need the sun above the horizon (sol_altitude is NaN below 3°)
+        alt_sol = self.variable("sol_altitude").values[time_index]
+        if math.isnan(alt_sol):
+            return isotropic
+        sol_altitude = math.radians(alt_sol)
+        sol_direct = self.variable("sol_direct").values[time_index]
+        # Circumsolar term only on surfaces that see the sun (cos_theta clipped at 0), but the
+        # sky part keeps its anisotropy weighting also on surfaces facing away from the sun:
+        # using the isotropic model for them overestimated their diffuse radiation
+        cos_theta = max(0.0, self._cos_incidence(time_index, surf_azimuth, surf_altitude))
+        if model in ("HAY-DAVIES", "REINDL"):
+            A = sol_direct / math.sin(sol_altitude) / 1353  # anisotropy index
+            R_b = cos_theta / math.sin(sol_altitude)
+            f_horizon = 1
+            if model == "REINDL":
+                zenit = math.pi / 2 - beta
+                f_horizon = 1 + math.sqrt(sol_direct / (sol_direct + sol_diffuse)) * (math.sin(zenit / 2)) ** 3
+            return sol_diffuse * A * R_b + sol_diffuse * (1 - A) * (1 + math.sin(beta)) / 2 * f_horizon
+        # PEREZ
+        zenit = math.pi / 2 - beta
+        sol_zenit = math.pi / 2 - sol_altitude
+        epsilon = ((sol_direct / math.sin(sol_altitude) + sol_diffuse) / sol_diffuse
+                   + 1.041 * sol_zenit**3) / (1 + 1.041 * sol_zenit**3)
+        m = 1 / math.cos(sol_zenit)
+        Delta = m * sol_diffuse / 1353
+        f = self._perez_coef(epsilon)
+        F_1 = max(0, f[0] + f[1] * Delta + f[2] * sol_zenit)
+        F_2 = f[3] + f[4] * Delta + f[5] * sol_zenit
+        b = max(0.087156, math.cos(sol_zenit))
+        return sol_diffuse * ((1 - F_1) * (1 + math.cos(zenit)) / 2 + F_1 * cos_theta / b + F_2 * math.sin(zenit))
+
+    def _cos_incidence(self, time_index, surf_azimuth, surf_altitude):
+        """Cosine of the angle between the sun and the surface exterior normal (negative when
+        the sun is behind the surface)."""
+        azi_sur = math.radians(surf_azimuth)
+        alt_sur = math.radians(surf_altitude)
+        azi_sol = math.radians(self.variable("sol_azimuth").values[time_index])
+        alt_sol = math.radians(self.variable("sol_altitude").values[time_index])
+        return (math.cos(azi_sol) * math.cos(alt_sol) * math.cos(azi_sur) * math.cos(alt_sur)
+                + math.sin(azi_sol) * math.cos(alt_sol) * math.sin(azi_sur) * math.cos(alt_sur)
+                + math.sin(alt_sol) * math.sin(alt_sur))
 
     def _perez_coef(self, epsilon):
-        if epsilon > 1 and epsilon <= 1.065:
+        if epsilon <= 1.065:  # overcast bin, also epsilon = 1 (no beam radiation)
             return [-0.0083117, 0.5877285, -0.0620636, -0.0596012, 0.0721249, -0.0220216]
         elif epsilon > 1.065 and epsilon <= 1.23:
             return [0.1299457, 0.6825954, -0.1513752, -0.0189325, 0.0659650, -0.0288748]

{opensimula-0.8.7 → opensimula-0.8.8}/src/opensimula/components/HVAC_SZW_system.py

@@ -383,14 +383,14 @@ class HVAC_SZW_system(Component):  # HVAC Single Zone Water system
                 self.M_w = 0
                 self.w_CA = self.w_MA
                 return
-            else:
-                capacity, self.epsilon = self.h_coil.get_heating_capacity(
-                    self.T_MA,
-                    self.T_MAwb,
-                    heating_Tw,
-                    self.air_flow,
-                    self.heating_water_flow,
-                )
+        # Coil capacity with the water temperature of either source
+        capacity, self.epsilon = self.h_coil.get_heating_capacity(
+            self.T_MA,
+            self.T_MAwb,
+            heating_Tw,
+            self.air_flow,
+            self.heating_water_flow,
+        )
         self.M_w = 0  # No latent load in heating
         self.w_CA = self.w_MA
         # Q_required is only the coil capacity
@@ -435,20 +435,20 @@ class HVAC_SZW_system(Component):  # HVAC Single Zone Water system
                 self.M_w = 0
                 self.w_CA = self.w_MA
                 return
-            else:
-                (
-                    capacity_sen,
-                    capacity_lat,
-                    self.T_ADP,
-                    self.epsilon,
-                    self.epsilon_adp,
-                ) = self.c_coil.get_cooling_capacity(
-                    self.T_MA,
-                    self.T_MAwb,
-                    cooling_Tw,
-                    self.air_flow,
-                    self.cooling_water_flow,
-                )
+        # Coil capacity with the water temperature of either source
+        (
+            capacity_sen,
+            capacity_lat,
+            self.T_ADP,
+            self.epsilon,
+            self.epsilon_adp,
+        ) = self.c_coil.get_cooling_capacity(
+            self.T_MA,
+            self.T_MAwb,
+            cooling_Tw,
+            self.air_flow,
+            self.cooling_water_flow,
+        )
 
         Q_required = -self.Q_required
         # Q_required is only the coil capacity

{opensimula-0.8.7 → opensimula-0.8.8}/src/opensimula/components/Space.py

@@ -30,7 +30,7 @@ class Space(Component):
         self.add_parameter(Parameter_float("volume", 1, "m³", min=0.0))
         self.add_parameter(Parameter_float("furniture_weight", 10, "kg/m²", min=0.0))
         self.add_parameter(Parameter_float("convergence_DT", 0.01, "°C", min=0.0))
-        self.add_parameter(Parameter_float("convergence_Dw", 0.1, "g/kg", min=0.0))
+        self.add_parameter(Parameter_float("convergence_Dw", 0.01, "g/kg", min=0.0))
 
         # Variables
         self.add_variable(Variable("temperature", unit="°C"))
@@ -504,6 +504,9 @@ class Space(Component):
         self._calculate_heat_fluxes(time_index)
 
     def _calculate_heat_fluxes(self, time_i):
+        # The uncontrolled systems may have changed since the last thermal solution (e.g. a VAV
+        # system replaces its maximum air flow by a controlled flow): report the current ones
+        self._acumulate_u_systems()
         V_inf = self.variable("infiltration_flow").values[time_i]
         T_ext = self._file_met.variable("temperature").values[time_i]
         w_ext = self._file_met.variable("abs_humidity").values[time_i]

{opensimula-0.8.7 → opensimula-0.8.8}/src/opensimula/visual_3D/Environment_3D.py

@@ -2,6 +2,7 @@ import time
 import numpy as np
 import math
 from scipy.interpolate import RegularGridInterpolator
+from scipy.ndimage import distance_transform_edt
 import matplotlib.pyplot as plt
 from opensimula.visual_3D.Polygon_3D import Polygon_3D
 
@@ -424,15 +425,31 @@ class Environment_3D:
                 k = k + 1
             j = j + 1
         
+        # Interpolation tables. Where the sun is behind a polygon its sunny fraction drops to 0,
+        # but there the direct radiation is already 0, so those cells take the value of the
+        # nearest cell with the sun in front: otherwise the interpolation between both sides
+        # of that step gives wrong fractions near grazing sun (e.g. 0.84-1.11 for an unshaded
+        # roof with cubic splines). Linear interpolation keeps the values within [0, 1], and
+        # the azimuth grid is closed at 360° so that 350°-360° is interpolated, not extrapolated.
+        azimuth_grid = np.append(self.shadow_azimuth_grid, 360)
         self.sunny_interpolation_functions = []
-        for i in range(0, len(sunny_polygons)):
+        for i, polygon in enumerate(sunny_polygons):
+            table = self.sunny_fraction_tables[i].copy()
+            behind = np.array(
+                [[polygon.get_angle_with_normal(azi, alt) >= math.pi / 2
+                  for alt in self.shadow_altitude_grid] for azi in self.shadow_azimuth_grid]
+            )
+            if behind.any() and not behind.all():
+                nearest = distance_transform_edt(behind, return_distances=False, return_indices=True)
+                table = table[nearest[0], nearest[1]]
+            table = np.vstack([table, table[0]])
             self.sunny_interpolation_functions.append(
                 RegularGridInterpolator(
-                    (self.shadow_azimuth_grid, self.shadow_altitude_grid),
-                    self.sunny_fraction_tables[i],
+                    (azimuth_grid, self.shadow_altitude_grid),
+                    table,
                     bounds_error=False,
                     fill_value=None,
-                    method="cubic",
+                    method="linear",
                 )
             )
     
@@ -471,7 +488,8 @@ class Environment_3D:
         if self.solar_tables_calculated == True:
             if azi < 0:
                 azi = azi + 360
-            return self.sunny_interpolation_functions[sunny_i]((azi, alt))
+            # clip: linear extrapolation beyond the ±85° altitude grid could leave [0, 1]
+            return float(np.clip(self.sunny_interpolation_functions[sunny_i]((azi, alt)), 0, 1))
         else:
             return 1      
     

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensimula
-Version: 0.8.7
+Version: 0.8.8
 Summary: Component-based time simulation environment in Python
 Author-email: "Juan F. Coronel" <jfc@us.es>
 Requires-Python: >=3.12
@@ -24,8 +24,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,6 +164,21 @@ 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).
 
+## Contributing
+
+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).
+
 ## Main Developers
 
 * [Juan F. Coronel](http://jfc.us.es), Universidad de Sevilla

{opensimula-0.8.7 → opensimula-0.8.8}/test/test_Case_600FF.py

@@ -319,6 +319,6 @@ def test_ff_temperature():
 
     T = pro.component("spaces_1").variable("temperature").values
 
-    assert T.mean() == pytest.approx(25.175713235125627)
-    assert T.max() == pytest.approx(65.7183978047975)
-    assert T.min() == pytest.approx(-13.37619837019802)
+    assert T.mean() == pytest.approx(25.07681213119194)
+    assert T.max() == pytest.approx(65.66725801535114)
+    assert T.min() == pytest.approx(-13.387879316775047)

{opensimula-0.8.7 → opensimula-0.8.8}/test/test_Case_610.py

@@ -349,7 +349,23 @@ def test_HVAC_perfect_system():
     peak_heating = load.max()/1000
     peak_cooling = -load.min()/1000
 
-    assert annual_heating == pytest.approx(4.6204817991668445)
-    assert annual_cooling == pytest.approx(4.177237252213477)
-    assert peak_heating == pytest.approx(3.257835742527949)
-    assert peak_cooling == pytest.approx(5.447455230231858)
+    assert annual_heating == pytest.approx(4.635639661707876)
+    assert annual_cooling == pytest.approx(4.135999834242331)
+    assert peak_heating == pytest.approx(3.2579149609779443)
+    assert peak_cooling == pytest.approx(5.451313222438749)
+
+
+def test_interpolated_sunny_fraction():
+    # Unshaded surfaces must get a sunny fraction of exactly 1 with INTERPOLATION, also with
+    # low sun, and every fraction must stay within [0, 1] (cubic interpolation overshot both)
+    sim = osim.Simulation()
+    pro = sim.new_project("pro")
+    pro.read_dict({**case610_dict, "shadow_calculation": "INTERPOLATION", "n_time_steps": 24})
+    pro.simulate()
+    env = pro.env_3D
+    roof = env.get_sunny_index("roof_wall")
+    window = env.get_sunny_index("south_window_1")
+    for azi in range(-180, 181, 7):
+        for alt in [1, 3, 5, 8, 12, 20, 40, 70, 88]:
+            assert env.get_direct_interpolated_sunny_fraction(roof, azi, alt) == pytest.approx(1)
+            assert 0 <= env.get_direct_interpolated_sunny_fraction(window, azi, alt) <= 1

{opensimula-0.8.7 → opensimula-0.8.8}/test/test_Construction.py

@@ -74,6 +74,29 @@ project_dic = {
             ],
             "thicknesses": [0.016, 0.076, 0.203, 0.076, 0.025],
         },
+        {
+            "type": "Material",
+            "name": "Opaque panel",
+            "conductivity": 1,
+            "density": 2470,
+            "specific_heat": 750,
+        },
+        {
+            "type": "Material",
+            "name": "Air gap",
+            "conductivity": 0.0625,
+            "density": 1.2925,
+            "specific_heat": 1006,
+        },
+        {
+            # Thin and light, with a single root: its CTF used to fail the steady state
+            # (ASHRAE 140 high-conductance wall)
+            "type": "Construction",
+            "name": "Thin panel",
+            "solar_alpha": [0.8, 0.8],
+            "materials": ["Opaque panel", "Air gap", "Opaque panel"],
+            "thicknesses": [0.003048, 0.012, 0.003048],
+        },
     ],
 }
 
@@ -102,6 +125,12 @@ def test_walls_1h():
     U = sum(wall._coef_T_a)/sum(wall._coef_Q)
     assert 1/wall.thermal_resistance() == pytest.approx(U, 0.00001)
 
+    wall = pro.component("Thin panel")
+    assert sum(wall._coef_T_a) == pytest.approx(sum(wall._coef_T_b), 0.00001)
+    assert sum(wall._coef_T_a) == pytest.approx(sum(wall._coef_T_c), 0.00001)
+    U = sum(wall._coef_T_a)/sum(wall._coef_Q)
+    assert 1/wall.thermal_resistance() == pytest.approx(U, 0.00001)
+
 
 def test_walls_15min():
     sim = osim.Simulation()
@@ -127,3 +156,9 @@ def test_walls_15min():
     assert sum(wall._coef_T_a) == pytest.approx(sum(wall._coef_T_c), 0.00001)
     U = sum(wall._coef_T_a)/sum(wall._coef_Q)
     assert 1/wall.thermal_resistance() == pytest.approx(U, 0.00001)
+
+    wall = pro.component("Thin panel")
+    assert sum(wall._coef_T_a) == pytest.approx(sum(wall._coef_T_b), 0.00001)
+    assert sum(wall._coef_T_a) == pytest.approx(sum(wall._coef_T_c), 0.00001)
+    U = sum(wall._coef_T_a)/sum(wall._coef_Q)
+    assert 1/wall.thermal_resistance() == pytest.approx(U, 0.00001)

{opensimula-0.8.7 → opensimula-0.8.8}/test/test_File_met.py

@@ -131,3 +131,22 @@ def test_ground_temperature_kasuda():
     T_mean = met.T_average
     # At 10m, temperature should be very close to annual mean
     assert abs(var_z10.values[0] - T_mean) < 2.0  # Within 2°C of mean
+
+
+def test_perez_surface_facing_away_from_sun():
+    # A surface that does not see the sun gets no circumsolar diffuse, but the rest of the
+    # sky radiation keeps the Perez (1 - F1) weighting, so it is below the isotropic value
+    # (the fallback to the isotropic model overestimated north walls by ~20 %)
+    sim = osim.Simulation()
+    pro = sim.new_project("pro")
+    pro.read_dict({**project, "simulation_file_met": "denver"})
+    pro.simulate()
+    met = pro.component("denver")
+    perez, isotropic = 0, 0
+    for i in range(8760):
+        cos_theta = met._cos_incidence(i, 180, 0)  # north vertical wall
+        if met.variable("sol_direct").values[i] > 0 and cos_theta < 0:
+            perez += met.solar_diffuse_rad(i, 180, 0)
+            isotropic += met.variable("sol_diffuse").values[i] / 2
+    assert isotropic > 0
+    assert perez < 0.95 * isotropic

{opensimula-0.8.7 → opensimula-0.8.8}/test/test_HVAC_DX_system.py

@@ -373,12 +373,12 @@ def test_HVAC_DX_system_without_vent():
     power = pro.component("system").variable("power").values.sum()/1e6
     annual_latent = pro.component("system").variable("Q_latent").values.sum()/1e6
 
-    assert annual_heating == pytest.approx(3.650510994153891)
-    assert annual_cooling == pytest.approx(5.000080590503151)
-    assert peak_heating == pytest.approx(2.753531135235261)
-    assert peak_cooling == pytest.approx(5.6938218907562925)
-    assert power == pytest.approx(14.614108682923018)
-    assert annual_latent == pytest.approx(0.05590912058065888)
+    assert annual_heating == pytest.approx(3.662558442285695)
+    assert annual_cooling == pytest.approx(4.953843972941708)
+    assert peak_heating == pytest.approx(2.753548603988852)
+    assert peak_cooling == pytest.approx(5.697679866477179)
+    assert power == pytest.approx(14.602619928128332)
+    assert annual_latent == pytest.approx(0.05448078004799185)
     
 
 def test_HVAC_DX_system_with_vent():
@@ -400,10 +400,10 @@ def test_HVAC_DX_system_with_vent():
     annual_latent = pro.component("system").variable("Q_latent").values.sum()/1e6
     print(annual_heating,annual_cooling,peak_heating,peak_cooling,power,annual_latent)
 
-    assert annual_heating == pytest.approx(6.56738727816441)
-    assert annual_cooling == pytest.approx(4.086059953886718)
-    assert peak_heating == pytest.approx(4.013664255449629)
-    assert peak_cooling == pytest.approx(5.374631379884803)
-    assert power == pytest.approx(16.747003071596513)
-    assert annual_latent == pytest.approx(0.07848460851539883)
+    assert annual_heating == pytest.approx(6.584015158948548)
+    assert annual_cooling == pytest.approx(4.047643778543491)
+    assert peak_heating == pytest.approx(4.013662511248714)
+    assert peak_cooling == pytest.approx(5.378485230257034)
+    assert power == pytest.approx(16.73810229504327)
+    assert annual_latent == pytest.approx(0.07588097994857204)
 

{opensimula-0.8.7 → opensimula-0.8.8}/test/test_HVAC_FAN_COIL_water_system.py

@@ -376,12 +376,12 @@ def test_HVAC_FAN_COIL_water_system():
     peak_heating = Q_sens.max() / 1000
     peak_cooling = -Q_sens.min() / 1000
 
-    assert annual_heating == pytest.approx(0.0723509834896354, rel=1e-5)
-    assert annual_cooling == pytest.approx(4.8761768134697965, rel=1e-5)
-    assert annual_humidification == pytest.approx(0.5830451955419828, rel=1e-5)
+    assert annual_heating == pytest.approx(0.07271765233509604, rel=1e-5)
+    assert annual_cooling == pytest.approx(4.838342243586122, rel=1e-5)
+    assert annual_humidification == pytest.approx(0.5796872363278687, rel=1e-5)
     assert annual_dehumidification == pytest.approx(0.0)
-    assert peak_heating == pytest.approx(2.6769614390992165, rel=1e-5)
-    assert peak_cooling == pytest.approx(5.530450229446886, rel=1e-5)
+    assert peak_heating == pytest.approx(2.679327322280834, rel=1e-5)
+    assert peak_cooling == pytest.approx(5.531297059385839, rel=1e-5)
 
     yearly_df = water.variable_dataframe(
         frequency="yearly", value="sum", pos_neg_columns=["Q_gen"]
@@ -389,13 +389,13 @@ def test_HVAC_FAN_COIL_water_system():
     heating_generation = yearly_df["Q_gen_pos"].values[0] / 1e6
     cooling_generation = yearly_df["Q_gen_neg"].values[0] / 1e6
 
-    assert heating_generation == pytest.approx(0.07351703946829136, rel=1e-5)
-    assert cooling_generation == pytest.approx(-4.969237804755222, rel=1e-5)
+    assert heating_generation == pytest.approx(0.07388369713417615, rel=1e-5)
+    assert cooling_generation == pytest.approx(-4.93133992091134, rel=1e-5)
 
     T_WGO = water.variable("T_WGO").values
     T_WGI = water.variable("T_WGI").values
 
-    assert T_WGO.max() == pytest.approx(51.407879045644584, rel=1e-5)
+    assert T_WGO.max() == pytest.approx(50.6756558449134, rel=1e-5)
     assert T_WGO.min() == pytest.approx(7.0)
-    assert T_WGI.max() == pytest.approx(51.42244343580782, rel=1e-5)
-    assert T_WGI.min() == pytest.approx(7.042183201358537, rel=1e-5)
+    assert T_WGI.max() == pytest.approx(50.688432226123474, rel=1e-5)
+    assert T_WGI.min() == pytest.approx(7.041926599097343, rel=1e-5)

opensimula-0.8.8/test/test_Iterative_process.py

@@ -0,0 +1,30 @@
+import opensimula as osim
+import math
+import pytest
+
+def test_Iterative_process():
+    def y(x):
+        return math.cos(x)
+    x_i = 0.5
+    itera = osim.Iterative_process(x_i)    
+    while not itera.converged():
+        x_i = itera.estimate_next_x(y(x_i))
+
+    assert x_i == pytest.approx(0.73908,abs=1e-4)
+
+
+def test_Iterative_process_residual():
+    # Slowly contracting fixed point (x = 0.95 x + 0.05, solution 1): at convergence the
+    # fixed-point residual must be below the tolerance. Testing the relaxed step instead
+    # stopped with residuals up to tol / lambda_min.
+    def y(x):
+        return 0.95 * x + 0.05
+    tol = 1e-4
+    x_i = 0.0
+    itera = osim.Iterative_process(x_i, tol=tol, n_ini_relax=3, rel_vel=0.8)
+    n = 0
+    while not itera.converged() and n < 10000:
+        x_i = itera.estimate_next_x(y(x_i))
+        n += 1
+    assert abs(y(x_i) - x_i) < tol
+    assert x_i == pytest.approx(1, abs=tol / (1 - 0.95))

{opensimula-0.8.7 → opensimula-0.8.8}/test/test_editor_schema.py

@@ -124,15 +124,21 @@ def test_real_projects_validate(schema, relative_path):
     jsonschema.validate(document, schema)
 
 
-def _project_dicts_in_notebooks(directory):
-    """Yield (notebook, project dict) for every project literal in the notebooks.
-
-    The ASHRAE 140 cases define their projects as dict literals inside code
-    cells, which makes them the largest corpus of real project definitions in
-    the repository. They are read with ast.literal_eval, so cells that build a
-    dict from variables are skipped rather than executed.
+def _ashrae_140_projects(directory):
+    """Yield (name, project dict) for every ASHRAE 140 case.
+
+    The cases are the largest corpus of real project definitions in the
+    repository: project JSON files in <TEST>/cases/ for the automated folders,
+    plus dict literals still defined inside notebooks (folders not automated
+    yet; read with ast.literal_eval, so cells that build a dict from variables
+    are skipped rather than executed). Archived notebooks are skipped: their
+    cases are the JSON files.
     """
+    for json_path in sorted(directory.glob("*/cases/*.json")):
+        yield json_path.name, json.loads(json_path.read_text())
     for notebook_path in sorted(directory.rglob("*.ipynb")):
+        if "old_notebooks" in notebook_path.parts:
+            continue
         notebook = nbformat.read(notebook_path, as_version=4)
         for cell in notebook.cells:
             if cell.cell_type != "code":
@@ -160,7 +166,7 @@ def test_ashrae_140_projects_validate(schema):
     validator = jsonschema.Draft202012Validator(schema)
     failures = []
     n_documents = 0
-    for notebook, document in _project_dicts_in_notebooks(directory):
+    for notebook, document in _ashrae_140_projects(directory):
         n_documents += 1
         for component in document["components"]:
             type_name = component.get("type")
@@ -176,7 +182,7 @@ def test_ashrae_140_projects_validate(schema):
                 failures.append(f"{notebook}: {type_name}.{path}: {error.message}")
         validator.validate(document)
 
-    assert n_documents > 0, "no project dicts found in the notebooks"
+    assert n_documents > 0, "no ASHRAE 140 project definitions found"
     assert failures == [], "\n".join(failures[:20])
 
 

opensimula-0.8.7/src/opensimula/Iterative_process.py

@@ -1,47 +0,0 @@
-import math
-
-class Iterative_process:
-    def __init__(self, x_0, tol = 1e-5, lambda_min=0.1, lambda_max=1.0, n_ini_relax=2,rel_vel = 0.9):
-        """
-        Iterative process using the fixed-point method with adaptive relaxation coefficient
-    
-        Parameters:
-        x_0: Initial value
-        tol: convergence tolerance
-        lambda_min, lambda_max: relaxation coefficient range
-        n_ini_relax: Number of iterations in which adaptive relaxation is initiated, must be greater than 1
-        """
-        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
-
-        
-    def converged(self):
-        if len(self.x) == 1:
-            return False
-        else:
-            if abs(self.x[-1]-self.x[-2]) < self.tol:
-                return True
-            else:
-                return False
-
-    def estimate_next_x(self, proposed_x):
-        x_next = (1 - self.lambda_i) * self.x[-1] + self.lambda_i * proposed_x
-        
-        # Ajuste dinámico de lambda (reduce si hay oscilaciones)
-        if len(self.x)>self.n_ini_relax:
-            #if abs(x_next - self.x[-1]) > abs(self.x[-1]- self.x[-2]):
-                self.lambda_i = max(self.lambda_min, self.lambda_i * self.rel_vel)  # Reducimos lambda
-            #else:
-                #self.lambda_i = min(self.lambda_max, self.lambda_i * 1/self.rel_vel)  # Aumentamos lambda
-
-        self.x.append(x_next)
-        return x_next
-    
-    def set_next_x(self, next_x):
-        self.x.append(next_x)
-

opensimula-0.8.7/test/test_Iterative_process.py

@@ -1,13 +0,0 @@
-import opensimula as osim
-import math
-import pytest
-
-def test_Iterative_process():
-    def y(x):
-        return math.cos(x)
-    x_i = 0.5
-    itera = osim.Iterative_process(x_i)    
-    while not itera.converged():
-        x_i = itera.estimate_next_x(y(x_i))
-
-    assert x_i == pytest.approx(0.73908,abs=1e-4)