OpenSimula 0.8.6__tar.gz → 0.8.7__tar.gz

opensimula-0.8.7/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: opensimula
+Version: 0.8.7
+Summary: Component-based time simulation environment in Python
+Author-email: "Juan F. Coronel" <jfc@us.es>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anywidget>=0.11.0
+Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: matplotlib>=3.10.0
+Requires-Dist: nbformat>=5.10.4
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=2.3.2
+Requires-Dist: plotly>=6.3.0
+Requires-Dist: psychrolib>=2.5.0
+Requires-Dist: scipy>=1.16.2
+Requires-Dist: shapely>=2.1.1
+Requires-Dist: tqdm>=4.67.1
+Dynamic: license-file
+
+![Logo](https://jfcoronel.github.io/OpenSimula/img/logo_opensimula.png)
+
+# OpenSimula
+
+[![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/)
+[![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
+thermal and energy simulation of buildings and their HVAC installations — though it can be
+used to simulate any system whose state evolves over time. It implements the [ASHRAE
+140](https://www.ashrae.org/technical-resources/bookstore/method-of-test-for-the-evaluation-of-building-energy-analysis-computer-programs)
+standard test suite to validate its building load and HVAC calculations.
+
+[**Documentation**](https://jfcoronel.github.io/OpenSimula/) · [Getting started](https://jfcoronel.github.io/OpenSimula/getting_started/) · [User guide](https://jfcoronel.github.io/OpenSimula/user_guide/) · [Component list](https://jfcoronel.github.io/OpenSimula/component_list/)
+
+## What it does
+
+A project is built from **components** — spaces, walls, windows, constructions, schedules,
+HVAC equipment, weather files — wired together and simulated hour by hour (or at any other
+time step). OpenSimula takes care of:
+
+- **Building thermal simulation**: multi-space heat balance, constructions with thermal mass,
+  windows and solar gains, ground-coupled surfaces, internal gains and schedules.
+- **HVAC systems**: from an ideal loads system (`HVAC_perfect_system`) to direct-expansion and
+  water-based single- and multi-zone systems, coils, fans, pumps, chillers and heat pumps.
+- **Solar geometry and shadows**: direct and diffuse shadow calculations between the surfaces
+  of a project, with an interactive 3D [Plotly](https://plotly.com/python/) view — including
+  an animated view of shadows changing throughout the day.
+- **Everything else a simulation needs**: psychrometrics (via
+  [PsychroLib](https://github.com/psychrometrics/psychrolib)), day/week/year schedules,
+  arbitrary math expressions as inputs, and reading weather data (TMY3, MET) or generic data
+  files (CSV, Excel).
+- **Validation against ASHRAE 140**: the `ASHRAE_140/` folder in this repository reproduces
+  the standard's load, heating, cooling, air-side HVAC and weather test cases as runnable
+  notebooks, comparing OpenSimula's results against the reference values.
+
+Projects can be defined as plain Python dictionaries, JSON or Excel files, and results come
+back as component `Variable` time series or pandas `DataFrame`s, ready to plot or export.
+
+## Installation
+
+```bash
+pip install opensimula
+```
+
+Requires Python 3.12 or later.
+
+## Quick example
+
+```python
+import opensimula as osm
+
+project_dict = {
+    "name": "First example",
+    "time_step": 3600,
+    "n_time_steps": 24 * 7,
+    "initial_time": "01/01/2001 00:00:00",
+    "components": [
+        {
+            "type": "Day_schedule",
+            "name": "working_day",
+            "time_steps": [8 * 3600, 5 * 3600, 2 * 3600, 4 * 3600],
+            "values": [0, 100, 0, 80, 0],
+            "interpolation": "STEP",
+        },
+        {
+            "type": "Day_schedule",
+            "name": "holiday_day",
+            "time_steps": [],
+            "values": [0],
+            "interpolation": "STEP",
+        },
+        {
+            "type": "Week_schedule",
+            "name": "office_week",
+            "days_schedules": ["working_day"] * 5 + ["holiday_day"] * 2,
+        },
+    ],
+}
+
+sim = osm.Simulation()
+pro = sim.new_project("First example")
+pro.read_dict(project_dict)
+pro.simulate()
+
+sim.plot(pro.dates(), [pro.component("office_week").variable("values")])
+```
+
+This is deliberately minimal — the [Getting started](https://jfcoronel.github.io/OpenSimula/getting_started/)
+guide walks through a full building, and the `jupyter_test/` and `ASHRAE_140/` folders in
+this repository contain complete, runnable building and HVAC examples.
+
+## Working in Jupyter
+
+OpenSimula ships an interactive project editor as a [Jupyter
+widget](https://jfcoronel.github.io/OpenSimula/user_guide/#project-editor) (`pro.editor()`),
+built on [anywidget](https://anywidget.dev/) so it works the same in Jupyter, JupyterLab, VS
+Code notebooks and Marimo. It shows every component's parameters as a form generated from
+each component's own schema, together with an interactive 3D view of the building.
+
+![Project editor example](https://jfcoronel.github.io/OpenSimula/img/editor_3d.png)
+
+## Component types
+
+Components are grouped by what they define:
+
+- **Building**: `Building`, `Space_type`, `Space`, `Building_surface`, `Opening`, `Solar_surface`.
+- **Constructions**: `Material`, `Construction`, `Glazing`, `Frame`, `Opening_type`.
+- **HVAC (air side)**: `HVAC_perfect_system`, `DX_unit`, `HVAC_DX_system`, `Water_coil`, `Fan`, `HVAC_SZW_system`, `HVAC_MZW_system`.
+- **HVAC (water side)**: `Pump`, `Chiller_heat_pump`, `HVAC_water_system`.
+- **Schedules**: `Day_schedule`, `Week_schedule`, `Year_schedule`.
+- **Files**: `File_met`, `File_data`.
+- **Utilities**: `Calculator`.
+
+See the [Component list](https://jfcoronel.github.io/OpenSimula/component_list/) for every
+parameter and variable of each one.
+
+## Package dependencies
+
+- numpy
+- pandas
+- scipy
+- shapely
+- psychrolib
+- plotly
+- matplotlib
+- anywidget
+- jsonschema
+- nbformat
+- openpyxl
+- tqdm
+
+These are installed automatically with `pip install opensimula`.
+
+## Documentation and support
+
+Full documentation, including the getting started guide, user guide and component
+reference, is at [jfcoronel.github.io/OpenSimula](https://jfcoronel.github.io/OpenSimula/).
+Bugs and feature requests are tracked on
+[GitHub Issues](https://github.com/jfCoronel/OpenSimula/issues).
+
+## Main Developers
+
+* [Juan F. Coronel](http://jfc.us.es), Universidad de Sevilla
+
+## License
+
+OpenSimula is released under the [MIT License](LICENSE).

opensimula-0.8.7/README.md

@@ -0,0 +1,149 @@
+![Logo](https://jfcoronel.github.io/OpenSimula/img/logo_opensimula.png)
+
+# OpenSimula
+
+[![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/)
+[![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
+thermal and energy simulation of buildings and their HVAC installations — though it can be
+used to simulate any system whose state evolves over time. It implements the [ASHRAE
+140](https://www.ashrae.org/technical-resources/bookstore/method-of-test-for-the-evaluation-of-building-energy-analysis-computer-programs)
+standard test suite to validate its building load and HVAC calculations.
+
+[**Documentation**](https://jfcoronel.github.io/OpenSimula/) · [Getting started](https://jfcoronel.github.io/OpenSimula/getting_started/) · [User guide](https://jfcoronel.github.io/OpenSimula/user_guide/) · [Component list](https://jfcoronel.github.io/OpenSimula/component_list/)
+
+## What it does
+
+A project is built from **components** — spaces, walls, windows, constructions, schedules,
+HVAC equipment, weather files — wired together and simulated hour by hour (or at any other
+time step). OpenSimula takes care of:
+
+- **Building thermal simulation**: multi-space heat balance, constructions with thermal mass,
+  windows and solar gains, ground-coupled surfaces, internal gains and schedules.
+- **HVAC systems**: from an ideal loads system (`HVAC_perfect_system`) to direct-expansion and
+  water-based single- and multi-zone systems, coils, fans, pumps, chillers and heat pumps.
+- **Solar geometry and shadows**: direct and diffuse shadow calculations between the surfaces
+  of a project, with an interactive 3D [Plotly](https://plotly.com/python/) view — including
+  an animated view of shadows changing throughout the day.
+- **Everything else a simulation needs**: psychrometrics (via
+  [PsychroLib](https://github.com/psychrometrics/psychrolib)), day/week/year schedules,
+  arbitrary math expressions as inputs, and reading weather data (TMY3, MET) or generic data
+  files (CSV, Excel).
+- **Validation against ASHRAE 140**: the `ASHRAE_140/` folder in this repository reproduces
+  the standard's load, heating, cooling, air-side HVAC and weather test cases as runnable
+  notebooks, comparing OpenSimula's results against the reference values.
+
+Projects can be defined as plain Python dictionaries, JSON or Excel files, and results come
+back as component `Variable` time series or pandas `DataFrame`s, ready to plot or export.
+
+## Installation
+
+```bash
+pip install opensimula
+```
+
+Requires Python 3.12 or later.
+
+## Quick example
+
+```python
+import opensimula as osm
+
+project_dict = {
+    "name": "First example",
+    "time_step": 3600,
+    "n_time_steps": 24 * 7,
+    "initial_time": "01/01/2001 00:00:00",
+    "components": [
+        {
+            "type": "Day_schedule",
+            "name": "working_day",
+            "time_steps": [8 * 3600, 5 * 3600, 2 * 3600, 4 * 3600],
+            "values": [0, 100, 0, 80, 0],
+            "interpolation": "STEP",
+        },
+        {
+            "type": "Day_schedule",
+            "name": "holiday_day",
+            "time_steps": [],
+            "values": [0],
+            "interpolation": "STEP",
+        },
+        {
+            "type": "Week_schedule",
+            "name": "office_week",
+            "days_schedules": ["working_day"] * 5 + ["holiday_day"] * 2,
+        },
+    ],
+}
+
+sim = osm.Simulation()
+pro = sim.new_project("First example")
+pro.read_dict(project_dict)
+pro.simulate()
+
+sim.plot(pro.dates(), [pro.component("office_week").variable("values")])
+```
+
+This is deliberately minimal — the [Getting started](https://jfcoronel.github.io/OpenSimula/getting_started/)
+guide walks through a full building, and the `jupyter_test/` and `ASHRAE_140/` folders in
+this repository contain complete, runnable building and HVAC examples.
+
+## Working in Jupyter
+
+OpenSimula ships an interactive project editor as a [Jupyter
+widget](https://jfcoronel.github.io/OpenSimula/user_guide/#project-editor) (`pro.editor()`),
+built on [anywidget](https://anywidget.dev/) so it works the same in Jupyter, JupyterLab, VS
+Code notebooks and Marimo. It shows every component's parameters as a form generated from
+each component's own schema, together with an interactive 3D view of the building.
+
+![Project editor example](https://jfcoronel.github.io/OpenSimula/img/editor_3d.png)
+
+## Component types
+
+Components are grouped by what they define:
+
+- **Building**: `Building`, `Space_type`, `Space`, `Building_surface`, `Opening`, `Solar_surface`.
+- **Constructions**: `Material`, `Construction`, `Glazing`, `Frame`, `Opening_type`.
+- **HVAC (air side)**: `HVAC_perfect_system`, `DX_unit`, `HVAC_DX_system`, `Water_coil`, `Fan`, `HVAC_SZW_system`, `HVAC_MZW_system`.
+- **HVAC (water side)**: `Pump`, `Chiller_heat_pump`, `HVAC_water_system`.
+- **Schedules**: `Day_schedule`, `Week_schedule`, `Year_schedule`.
+- **Files**: `File_met`, `File_data`.
+- **Utilities**: `Calculator`.
+
+See the [Component list](https://jfcoronel.github.io/OpenSimula/component_list/) for every
+parameter and variable of each one.
+
+## Package dependencies
+
+- numpy
+- pandas
+- scipy
+- shapely
+- psychrolib
+- plotly
+- matplotlib
+- anywidget
+- jsonschema
+- nbformat
+- openpyxl
+- tqdm
+
+These are installed automatically with `pip install opensimula`.
+
+## Documentation and support
+
+Full documentation, including the getting started guide, user guide and component
+reference, is at [jfcoronel.github.io/OpenSimula](https://jfcoronel.github.io/OpenSimula/).
+Bugs and feature requests are tracked on
+[GitHub Issues](https://github.com/jfCoronel/OpenSimula/issues).
+
+## Main Developers
+
+* [Juan F. Coronel](http://jfc.us.es), Universidad de Sevilla
+
+## License
+
+OpenSimula is released under the [MIT License](LICENSE).

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

@@ -1,6 +1,6 @@
 [project]
 name = "opensimula"
-version = "0.8.6"
+version = "0.8.7"
 requires-python = ">=3.12"
 authors = [
   { name="Juan F. Coronel", email="jfc@us.es" },
@@ -10,6 +10,7 @@ readme = "README.md"
 dependencies = [
     "anywidget>=0.11.0",
     "jsonschema>=4.26.0",
+    "matplotlib>=3.10.0",
     "nbformat>=5.10.4",
     "numpy>=2.3.3",
     "openpyxl>=3.1.5",
@@ -19,7 +20,6 @@ dependencies = [
     "scipy>=1.16.2",
     "shapely>=2.1.1",
     "tqdm>=4.67.1",
-    "vedo>=2025.5.4",
 ]
 
 [dependency-groups]

{opensimula-0.8.6 → opensimula-0.8.7}/src/opensimula/Project.py

@@ -677,23 +677,30 @@ class Project(Parameter_container):
         self.create_3D_environment(env_3D)
         return env_3D.geometry_dict()
 
-    def show_3D(self, jupyter=False):
+    def show_3D(self):
         env_3D = Environment_3D()
         self.create_3D_environment(env_3D)
-        return env_3D.show(polygons_type="initial", jupyter=jupyter)
+        env_3D.show(polygons_type="initial")
 
-    def show_3D_shadows(self, date, jupyter=False):
+    def plotly_figure_3D(self):
+        """The Plotly figure of show_3D(), returned instead of shown, so it
+        can be composed, saved, or otherwise reused."""
+        env_3D = Environment_3D()
+        self.create_3D_environment(env_3D)
+        return env_3D.plotly_figure(polygons_type="initial")
+
+    def show_3D_shadows(self, date):
         env_3D = Environment_3D()
         self.create_3D_environment(env_3D)
         file_met = self.parameter("simulation_file_met").component
         cos = file_met.sun_cosines(date)
         if len(cos) == 3:
             env_3D.calculate_shadows(cos)
-            env_3D.show(polygons_type="Building_shadows", jupyter=jupyter)
+            env_3D.show(polygons_type="Building_shadows")
         else:
             self._sim_.message(Message(date.strftime("%H:%M,  %d/%m/%Y") + " is night", "WARNING"))
 
-    def show_3D_shadows_animation(self, date, jupyter=False):
+    def show_3D_shadows_animation(self, date):
         env_3D = Environment_3D()
         self.create_3D_environment(env_3D)
         file_met = self.parameter("simulation_file_met").component
@@ -705,6 +712,6 @@ class Project(Parameter_container):
             if len(cos) == 3:  # Day time
                 texts.append(new_date.strftime("%H:%M,  %d/%m/%Y"))
                 cosines.append(cos)
-        env_3D.show_animation(texts, cosines, polygons_type="Building_shadows", jupyter=jupyter)
+        env_3D.show_animation(texts, cosines, polygons_type="Building_shadows")