epinterface 1.2.0__tar.gz → 1.3.0__tar.gz

{epinterface-1.2.0 → epinterface-1.3.0}/.cursor/Dockerfile.agent

@@ -1,5 +1,6 @@
 ARG EP_VERSION=24.2.0
 ARG PYTHON_VERSION=3.12
+ARG UV_VERSION=0.9.30
 FROM nrel/energyplus:${EP_VERSION} AS energyplus
 
 # Remove unnecessary datasets to reduce image size
@@ -13,8 +14,9 @@ RUN mkdir -p /energyplus-local && \
     # ep is installed by the nrel image
     cp -r * /energyplus-local/
 
+FROM ghcr.io/astral-sh/uv:${UV_VERSION} AS uv
 FROM python:${PYTHON_VERSION}-slim-bookworm AS main
-COPY --from=ghcr.io/astral-sh/uv:0.9.30 /uv /uvx /bin/
+COPY --from=uv /uv /uvx /bin/
 
 
 # Install dependencies for running energy models

epinterface-1.3.0/.cursor/rules/uv-dependencies.mdc

@@ -0,0 +1,44 @@
+---
+description: How to add packages with uv and when to use optional-dependencies vs dependency-groups
+globs: pyproject.toml
+alwaysApply: false
+---
+
+# Adding Dependencies with uv
+
+Use `uv add` to add packages. Where they go depends on who needs them.
+
+## `uv add` usage
+
+- **Core runtime dependency** (always required by the library):
+  ```bash
+  uv add <package>
+  ```
+  Adds to `[project] dependencies` in `pyproject.toml`.
+
+- **Optional extra** (for downstream installers):
+  ```bash
+  uv add --optional <extra-name> <package>
+  ```
+  Adds to `[project.optional-dependencies]` under the given extra (e.g. `uv add --optional plot pandas-plot`).
+
+- **Local-only group** (dev/docs/tooling, not published as installable extras):
+  ```bash
+  uv add --group <group-name> <package>
+  ```
+  Adds to `[dependency-groups]` (e.g. `uv add --group dev pytest`).
+
+## When to use which
+
+| Place | Who gets it | Use for |
+|-------|-------------|--------|
+| **`project.dependencies`** | Everyone who installs `epinterface` | Required runtime deps only. |
+| **`project.optional-dependencies`** | Only people who install e.g. `uv add epinterface[extra-name]` or `pip install epinterface[extra-name]` | Optional features other projects may want when using epinterface as a library. |
+| **`dependency-groups`** | Only this repo (local dev, CI, docs) | Testing, linting, docs, pre-commit, etc. Not exposed as pip/uv extras. |
+
+**Rule of thumb:** If another repo would ever do `pip install epinterface[something]` to get optional functionality, put that in **optional-dependencies**. If it’s only for developing or building this repo, put it in **dependency-groups**.
+
+## Examples (this project)
+
+- **optional-dependencies:** e.g. a `viz` extra for plotting only used by some downstream users → `[project.optional-dependencies] viz = ["matplotlib", ...]`.
+- **dependency-groups:** `dev` (pytest, pyright, pre-commit), `docs` (mkdocs, mkdocstrings) — local tooling only, not installable as `epinterface[dev]`.

{epinterface-1.2.0 → epinterface-1.3.0}/.github/workflows/main.yml

@@ -34,8 +34,8 @@ jobs:
     #   EPINTERFACE_ENERGYPLUS_VERSION: ${{ matrix.energyplus-version }}
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
-        energyplus-version: [22.2.0, 23.2.0, 24.2.0, 25.2.0] # later, add 9.4.0
+        python-version: ["3.12"]
+        energyplus-version: [22.2.0, 24.2.0, 25.2.0] # later, add 9.4.0
         energyplus-platform: [Linux-Ubuntu22.04]
         include:
           - runs-on: ubuntu-latest

{epinterface-1.2.0 → epinterface-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: epinterface
-Version: 1.2.0
+Version: 1.3.0
 Summary: This is a repository for dynamically generating energy models within Python, relying on Archetypal and Eppy for most of its functionality.
 Project-URL: Homepage, https://github.com/szvsw/epinterface
 Project-URL: Documentation, https://szvsw.github.io/epinterface

{epinterface-1.2.0 → epinterface-1.3.0}/epinterface/geometry.py

@@ -7,6 +7,7 @@ import numpy as np
 from archetypal.idfclass import IDF
 from geomeppy.geom.polygons import Polygon3D
 from geomeppy.geom.vectors import Vector2D
+from numpy.typing import ArrayLike
 from pydantic import BaseModel, Field
 from shapely import LineString, Polygon, from_wkt
 from shapely.affinity import translate
@@ -192,6 +193,125 @@ def compute_shading_mask(
     return shading_mask
 
 
+def shading_fence_closed_ring(
+    elevations: ArrayLike,
+    d: float,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, float]:
+    """Construct N vertical 'shading fence' rectangles whose bases are tangent segments forming a closed regular polygon around a circle of radius d.
+
+    Inputs:
+      elevations: (N,) elevation angles theta_k [radians]
+      d: radius to tangency points (base midpoints)
+
+    Outputs:
+      azimuths: (N,) inferred azimuths alpha_k = 2πk/N
+      p0:       (N, 2) base endpoint A (x,y)
+      p1:       (N, 2) base endpoint B (x,y)
+      h:        (N,) heights h_k = d * tan(theta_k)
+      w:        scalar side length / segment width = 2 d tan(π/N)
+
+    Notes:
+      - With this construction, the segments intersect/meet: p1[k] == p0[k+1] (cyclic),
+        up to floating point tolerance.
+      - N must be >= 3 for a closed polygon.
+    """
+    theta = np.asarray(elevations, dtype=np.float64)
+    if theta.ndim != 1:
+        msg = f"elevations must be 1D, got shape {theta.shape}"
+        raise ValueError(msg)
+
+    N = theta.shape[0]
+    if N < 3:
+        msg = "Need at least 3 elevations (N >= 3) to form a closed ring."
+        raise ValueError(msg)
+
+    # Inferred equally spaced azimuths
+    k = np.arange(N, dtype=np.float64)
+    azimuths = 2.0 * np.pi * k / N
+
+    ca, sa = np.cos(azimuths), np.sin(azimuths)
+
+    # Tangency points (base midpoints) on circle radius d
+    px = d * ca
+    py = d * sa
+
+    # Unit tangent direction (perpendicular to radius)
+    tx = -sa
+    ty = ca
+
+    # Choose width so adjacent tangent segments meet (circumscribed regular N-gon)
+    half_w = d * np.tan(np.pi / N)
+    w = 2.0 * half_w
+
+    # Endpoints in xy: p ± half_w * t
+    p0 = np.stack([px - half_w * tx, py - half_w * ty], axis=-1)
+    p1 = np.stack([px + half_w * tx, py + half_w * ty], axis=-1)
+
+    # Heights from elevation angles
+    h = d * np.tan(theta)
+
+    return azimuths, p0, p1, h, w
+
+
+def prepare_neighbor_shading_for_idf(
+    building: Polygon | str,
+    neighbors: Sequence[Polygon | str | None],
+    neighbor_heights: Sequence[float | int | None],
+    *,
+    azimuthal_angle: float = 2 * np.pi / 48,
+    fence_radius: float = 100,
+    outward_offset: float = 2,
+    f2f_height: float,
+) -> tuple[list[Polygon], list[int]]:
+    """Prepare neighbor polygons and floor counts for match_idf_to_building_and_neighbors.
+
+    Computes a shading mask from the building and neighbors, converts it to shading fence
+    quadrilaterals, and returns polygons plus floor counts suitable for IDF shading blocks.
+
+    Args:
+        building: The building polygon (or WKT string).
+        neighbors: Neighbor polygons (or WKT strings).
+        neighbor_heights: Heights of each neighbor [m].
+        azimuthal_angle: Angular spacing for shading rays (default 2π/48).
+        fence_radius: Radius for shading fence tangency points.
+        outward_offset: Distance to extend fence quadrilaterals outward.
+        f2f_height: Floor-to-floor height for converting heights to floor counts.
+
+    Returns:
+        mask_polys: List of Shapely Polygons (quadrilaterals) for each shading fence.
+        neighbor_floors: List of floor counts (int) for each fence.
+    """
+    shading_mask = compute_shading_mask(
+        building, neighbors, neighbor_heights, azimuthal_angle
+    )
+    az, p0, p1, h, _w = shading_fence_closed_ring(
+        elevations=shading_mask, d=fence_radius
+    )
+
+    building_geom = building if isinstance(building, Polygon) else from_wkt(building)
+    centroid = building_geom.centroid
+    cx, cy = centroid.x, centroid.y
+
+    angles = 2 * np.pi * np.arange(len(az)) / len(az)
+    outward = np.stack([np.cos(angles), np.sin(angles)], axis=-1)
+    p2 = p1 + outward_offset * outward
+    p3 = p0 + outward_offset * outward
+
+    mask_polys = [
+        Polygon([
+            (p0[i, 0] + cx, p0[i, 1] + cy),
+            (p1[i, 0] + cx, p1[i, 1] + cy),
+            (p2[i, 0] + cx, p2[i, 1] + cy),
+            (p3[i, 0] + cx, p3[i, 1] + cy),
+            (p0[i, 0] + cx, p0[i, 1] + cy),
+        ])
+        for i in range(len(az))
+    ]
+    neighbor_floors = [int(h[i] // f2f_height) for i in range(len(h))]
+
+    return mask_polys, neighbor_floors
+
+
 ZoningType = Literal["core/perim", "by_storey"]
 
 

{epinterface-1.2.0 → epinterface-1.3.0}/epinterface/sbem/builder.py

@@ -1,17 +1,22 @@
 """A module for building the energy model using the SBEM template library approach."""
 
 import gc
+import io
 import logging
+import os
 import shutil
+import sys
 import tempfile
 from collections.abc import Callable
 from dataclasses import dataclass
+from datetime import datetime
 from pathlib import Path
 from typing import Literal, cast, get_args
 from uuid import uuid4
 
 import numpy as np
 import pandas as pd
+import yaml
 from archetypal.idfclass import IDF
 from archetypal.idfclass.sql import Sql
 from ladybug.epw import EPW
@@ -38,6 +43,10 @@ from epinterface.interface import (
     add_default_schedules,
     add_default_sim_controls,
 )
+from epinterface.sbem.components.composer import (
+    construct_composer_model,
+    construct_graph,
+)
 from epinterface.sbem.components.envelope import (
     ConstructionAssemblyComponent,
     EnvelopeAssemblyComponent,
@@ -46,6 +55,7 @@ from epinterface.sbem.components.envelope import (
 from epinterface.sbem.components.systems import DHWFuelType, FuelType
 from epinterface.sbem.components.zones import ZoneComponent
 from epinterface.sbem.exceptions import NotImplementedParameter
+from epinterface.sbem.prisma.client import PrismaSettings
 from epinterface.settings import energyplus_settings
 from epinterface.weather import BaseWeather
 
@@ -1206,6 +1216,78 @@ class Model(BaseWeather, validate_assignment=True):
         return zone_weights, zone_names
 
 
+def construct_zone_def(
+    component_map_path: Path,
+    db_path: Path,
+    semantic_field_context: dict[str, float | str | int],
+) -> ZoneComponent:
+    """Construct the zone definition from a component map and database.
+
+    Args:
+        component_map_path: Path to the component map YAML file.
+        db_path: Path to the component database file.
+        semantic_field_context: The semantic field values used to compile the zone definition.
+
+    Returns:
+        zone_def: The zone definition for the simulation.
+    """
+    g = construct_graph(ZoneComponent)
+    SelectorModel = construct_composer_model(
+        g,
+        ZoneComponent,
+        use_children=False,
+    )
+
+    with open(component_map_path) as f:
+        component_map_yaml = yaml.safe_load(f)
+    selector = SelectorModel.model_validate(component_map_yaml)
+
+    if db_path.exists():
+        mtime = os.path.getmtime(db_path)
+        mtime_str = datetime.fromtimestamp(mtime).strftime("%Y-%m-%d %H:%M:%S")
+        logger.info(
+            f"Loading database: {db_path} "
+            f"(modified: {mtime_str}, size: {db_path.stat().st_size} bytes)"
+        )
+    else:
+        logger.error(f"Database file not found: {db_path}")
+
+    settings = PrismaSettings.New(
+        database_path=db_path, if_exists="ignore", auto_register=False
+    )
+    db = settings.db
+
+    def _stdout_has_fileno() -> bool:
+        """True if sys.stdout has a real OS file descriptor (required by Prisma on Windows in Jupyter)."""
+        try:
+            sys.stdout.fileno()
+        except (AttributeError, io.UnsupportedOperation, OSError, ValueError):
+            return False
+        else:
+            return True
+
+    if not _stdout_has_fileno():
+        with open(os.devnull, "w") as _devnull:
+            _old_stdout, _old_stderr = sys.stdout, sys.stderr
+            sys.stdout = sys.stderr = _devnull
+            try:
+                with db:
+                    zone = cast(
+                        ZoneComponent,
+                        selector.get_component(context=semantic_field_context, db=db),
+                    )
+            finally:
+                sys.stdout, sys.stderr = _old_stdout, _old_stderr
+                _devnull.close()
+    else:
+        with db:
+            zone = cast(
+                ZoneComponent,
+                selector.get_component(context=semantic_field_context, db=db),
+            )
+    return zone
+
+
 @dataclass
 class ModelRunResults:
     """The results of a model run."""
@@ -1219,14 +1301,6 @@ class ModelRunResults:
 
 
 if __name__ == "__main__":
-    import yaml
-
-    from epinterface.sbem.components.composer import (
-        construct_composer_model,
-        construct_graph,
-    )
-    from epinterface.sbem.prisma.client import PrismaSettings
-
     with tempfile.TemporaryDirectory() as temp_dir:
         # database_path = Path("/Users/daryaguettler/globi/data/Brazil/components-lib.db")
         # component_map_path = Path(

{epinterface-1.2.0 → epinterface-1.3.0}/epinterface/sbem/components/composer.py

@@ -1,5 +1,6 @@
 """A module for automatically fetching and composing SBEM objects."""
 
+import logging
 import uuid
 from typing import Any, ClassVar, Literal, TypeVar, get_origin
 
@@ -9,6 +10,8 @@ from pydantic import BaseModel, Field, create_model
 
 from epinterface.sbem.common import NamedObject
 
+logger = logging.getLogger(__name__)
+
 """Tree construction:
 
 Every node in the tree may or may not have a selector action specified.

{epinterface-1.2.0 → epinterface-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "epinterface"
-version = "v1.2.0"
+version = "v1.3.0"
 description = "This is a repository for dynamically generating energy models within Python, relying on Archetypal and Eppy for most of its functionality."
 readme = "README.md"
 authors = [

epinterface-1.3.0/tests/test_construct_zone_def.py

@@ -0,0 +1,68 @@
+"""Tests for construct_zone_def."""
+
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from epinterface.sbem.builder import construct_zone_def
+from epinterface.sbem.components.zones import ZoneComponent
+from epinterface.sbem.prisma.client import PrismaSettings
+from epinterface.sbem.prisma.seed_fns import (
+    create_dhw_systems,
+    create_envelope,
+    create_hvac_systems,
+    create_operations,
+    create_schedules,
+    create_space_use_children,
+    create_zone,
+)
+
+
+@pytest.fixture(scope="module")
+def preseeded_db_path_and_component_map():
+    """Create a preseeded database and minimal component map for construct_zone_def tests."""
+    with tempfile.TemporaryDirectory() as temp_dir:
+        db_path = Path(temp_dir) / "test.db"
+        component_map_path = Path(temp_dir) / "component-map.yaml"
+
+        settings = PrismaSettings.New(
+            database_path=db_path, if_exists="raise", auto_register=False
+        )
+        with settings.db:
+            create_schedules(settings.db)
+            last_space_use_name = create_space_use_children(settings.db)
+            last_hvac_name = create_hvac_systems(settings.db)
+            last_dhw_name = create_dhw_systems(settings.db)
+            _last_ops_name = create_operations(
+                settings.db, last_space_use_name, last_hvac_name, last_dhw_name
+            )
+            create_envelope(settings.db)
+            create_zone(settings.db)
+
+        component_map_path.write_text(
+            "selector:\n  source_fields: [basic]\n",
+            encoding="utf-8",
+        )
+
+        yield db_path, component_map_path
+
+
+def test_construct_zone_def_returns_zone_component(
+    preseeded_db_path_and_component_map: tuple[Path, Path],
+):
+    """Test that construct_zone_def returns a valid ZoneComponent from the preseeded db."""
+    db_path, component_map_path = preseeded_db_path_and_component_map
+
+    zone = construct_zone_def(
+        component_map_path=component_map_path,
+        db_path=db_path,
+        semantic_field_context={"basic": "default_zone"},
+    )
+
+    assert isinstance(zone, ZoneComponent)
+    assert zone.Name == "default_zone"
+    assert zone.Envelope is not None
+    assert zone.Operations is not None
+    assert zone.Envelope.Name == "default_env"
+    assert zone.Operations.Name == "default_ops"

epinterface-1.3.0/tests/test_neighbor_shading_geometry.py

@@ -0,0 +1,151 @@
+"""Tests for neighbor shading geometry (shading_fence_closed_ring, prepare_neighbor_shading_for_idf)."""
+
+import numpy as np
+import pytest
+from shapely import Polygon
+
+from epinterface.geometry import (
+    compute_shading_mask,
+    prepare_neighbor_shading_for_idf,
+    shading_fence_closed_ring,
+)
+
+
+def test_shading_fence_closed_ring():
+    """Test shading_fence_closed_ring output shapes and cyclic closure."""
+    elevations = np.array([0.1, 0.2, 0.3])
+    d = 100.0
+
+    az, p0, p1, h, w = shading_fence_closed_ring(elevations=elevations, d=d)
+
+    assert az.shape == (3,)
+    assert p0.shape == (3, 2)
+    assert p1.shape == (3, 2)
+    assert h.shape == (3,)
+    assert isinstance(w, float)
+
+    # Cyclic closure: p1[k] == p0[(k+1) % N] (within floating point tolerance)
+    for k in range(3):
+        np.testing.assert_allclose(p1[k], p0[(k + 1) % 3], atol=1e-12)
+
+    # Heights: h[k] == d * tan(elevations[k])
+    expected_h = d * np.tan(elevations)
+    np.testing.assert_allclose(h, expected_h, rtol=1e-10)
+
+
+def test_shading_fence_closed_ring_raises_for_n_less_than_3():
+    """Test that shading_fence_closed_ring raises ValueError for N < 3."""
+    elevations = np.array([0.1, 0.2])
+
+    with pytest.raises(ValueError, match="at least 3 elevations"):
+        shading_fence_closed_ring(elevations=elevations, d=100)
+
+
+def test_prepare_neighbor_shading_for_idf_no_neighbors():
+    """Test prepare_neighbor_shading_for_idf with no neighbors (default 48 azimuths)."""
+    building = Polygon([(0, 0), (10, 0), (10, 10), (0, 10)])
+
+    mask_polys, neighbor_floors = prepare_neighbor_shading_for_idf(
+        building=building,
+        neighbors=[],
+        neighbor_heights=[],
+        f2f_height=3.0,
+    )
+
+    assert len(mask_polys) == 48
+    assert len(neighbor_floors) == 48
+
+    for poly in mask_polys:
+        assert poly.is_valid
+        assert not poly.is_empty
+        assert len(poly.exterior.coords) >= 4  # closed ring has repeated first point
+
+
+def test_prepare_neighbor_shading_for_idf_with_neighbors():
+    """Test prepare_neighbor_shading_for_idf with one neighbor."""
+    building = Polygon([(0, 0), (10, 0), (10, 10), (0, 10)])
+    neighbor = Polygon([(20, 5), (25, 5), (25, 15), (20, 15)])
+    neighbor_height = 10.0
+
+    mask_polys, neighbor_floors = prepare_neighbor_shading_for_idf(
+        building=building,
+        neighbors=[neighbor],
+        neighbor_heights=[neighbor_height],
+        f2f_height=3.0,
+    )
+
+    assert len(mask_polys) == 48
+    assert len(neighbor_floors) == 48
+
+    for poly in mask_polys:
+        assert poly.is_valid
+        assert not poly.is_empty
+
+
+def test_shading_mask_from_real_geometry_matches_shading_mask_from_fake_ring():
+    """Shading mask from real neighbor geometry equals shading mask from the fake ring.
+
+    Manually construct a main building with neighbors scattered around it. Compute the
+    shading mask from these real polygons. Then build the fake ring (mask_polys) from
+    that shading mask and compute the shading mask again from the fake ring. The two
+    masks should match, since the fake ring is designed to reproduce the same elevation
+    angles when rays are cast from the building centroid.
+    """
+    azimuthal_angle = 2 * np.pi / 48
+    fence_radius = 100.0
+
+    # Main building: 10x10 square centered at (5, 5) - centroid at (5, 5)
+    building = Polygon([(0, 0), (10, 0), (10, 10), (0, 10)])
+
+    # Neighbors: rectangles to the east, north, and northwest with different heights.
+    # Building centroid is (5, 5). Rays will intersect these at various distances.
+    neighbor_east = Polygon([(15, 2), (25, 2), (25, 8), (15, 8)])  # east, height 12m
+    neighbor_north = Polygon([(2, 15), (8, 15), (8, 22), (2, 22)])  # north, height 9m
+    neighbor_nw = Polygon([
+        (-5, 8),
+        (-2, 8),
+        (-2, 12),
+        (-5, 12),
+    ])  # northwest, height 6m
+
+    neighbors = [neighbor_east, neighbor_north, neighbor_nw]
+    neighbor_heights = [12.0, 9.0, 6.0]
+
+    # Shading mask from real geometry
+    mask_from_real = compute_shading_mask(
+        building=building,
+        neighbors=neighbors,
+        neighbor_heights=neighbor_heights,
+        azimuthal_angle=azimuthal_angle,
+    )
+
+    # Build the fake ring from this mask
+    mask_polys, _neighbor_floors = prepare_neighbor_shading_for_idf(
+        building=building,
+        neighbors=neighbors,
+        neighbor_heights=neighbor_heights,
+        azimuthal_angle=azimuthal_angle,
+        fence_radius=fence_radius,
+        f2f_height=3.0,
+    )
+
+    # Heights of the fake ring fences: h = d * tan(elevation) for each azimuth.
+    # We need these exact heights (not the floor-discretized ones) for an exact match.
+    _, _, _, fence_heights, _ = shading_fence_closed_ring(
+        elevations=mask_from_real, d=fence_radius
+    )
+
+    # Shading mask from the fake ring (using exact fence heights)
+    mask_from_fake_ring = compute_shading_mask(
+        building=building,
+        neighbors=mask_polys,
+        neighbor_heights=fence_heights.tolist(),
+        azimuthal_angle=azimuthal_angle,
+    )
+
+    np.testing.assert_allclose(
+        mask_from_real,
+        mask_from_fake_ring,
+        atol=1e-10,
+        err_msg="Shading mask from real geometry should match shading mask from fake ring",
+    )

{epinterface-1.2.0 → epinterface-1.3.0}/uv.lock

@@ -573,7 +573,7 @@ wheels = [
 
 [[package]]
 name = "epinterface"
-version = "1.2.0"
+version = "1.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "archetypal" },