idfkit 1.1.1__tar.gz → 1.2.0__tar.gz

{idfkit-1.1.1 → idfkit-1.2.0}/CHANGELOG.md

@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-10-28
+
+This release moves to `conformance-2026.21`. Through `conformance-2026.19`, the level the TypeScript library also declares, the corpus adds five cases for the multi-field `update` shared with the TypeScript library, an `update` operation and a `post-operation-epjson` assertion (`conformance-2026.17`), and removes the divergence entries for those cases in both languages: the ten Python entries that `IDFObject.update` closes (`conformance-2026.18`) and the six TypeScript ones (`conformance-2026.19`). `conformance-2026.20` then removes the two Python round-trip entries that #183 closes. An idfkit release without `IDFObject.update` fails the five update cases at this level, and one that still stores a blank fixed field as `""` fails those two. `conformance-2026.21` removes the three Python entries that #187 closes, so a release that still drops an unterminated final object fails `malformed-truncated-object` and `preserve-unterminated-final`.
+
+### Added
+
+- **Every object type in a document's schema became reachable as a typed attribute
+  on `IDFDocument`, not only the hand-written shorthands.** Each type has one
+  `snake_case` plural, declared in `document.pyi`: `doc.air_loop_hvacs` is
+  `IDFCollection[AirLoopHVAC]`, and `doc.coil_cooling_dx_single_speeds` and
+  `doc.zone_hvac_equipment_connections` resolve likewise. Names are derived from
+  the schema by rule, with a short override table for the types the rule splits
+  badly (`Output:SQLite` is `doc.output_sqlite`), and a test fails when a new
+  release adds an acronym that has not been reviewed. Existing shorthands kept
+  their meaning, and the spellings that resolved before, such as
+  `doc.Site_Location` and `doc.ZONE`, still resolve. A failed lookup names the
+  closest matches and their object types; the message is built only when read, so
+  `hasattr()` and `getattr(doc, name, default)` stay fast
+  ([#202](https://github.com/idfkit/idfkit/pull/202)).
+- `idfkit.geometry.polygon_difference_parts_2d(outer, *inners)` subtracts one or more polygons and returns hole-free, non-overlapping, counter-clockwise pieces, largest first, that together cover the difference. A result with a hole is cut by a vertical line through each hole. Every piece is a valid EnergyPlus surface outline or `create_block` footprint. ([#164](https://github.com/idfkit/idfkit/issues/164), [#244](https://github.com/idfkit/idfkit/pull/244))
+- `idfkit.geometry.triangulate_2d(poly)` ear-clips a convex or concave 2D polygon into triangles, returned as index triples into the input in its own winding. It tolerates collinear and duplicate vertices, keyhole outlines with doubled bridge vertices and polygons pinched at a vertex, and it still uses every vertex of a self-intersecting polygon. The 3D viewers and `intersect_and_match` now share it. ([#246](https://github.com/idfkit/idfkit/pull/246))
+- `idfkit.geometry_builders.split_horizontal_surface_by_regions(doc, surface, regions)` splits a horizontal surface under several regions in one step and returns `(region_surfaces, remaining_surfaces)`. `link_blocks` now uses it for each roof, so adjacent floors resting on one roof are subtracted together. ([#164](https://github.com/idfkit/idfkit/issues/164), [#244](https://github.com/idfkit/idfkit/pull/244))
+- `idfkit.zoning.create_courtyard_block(doc, name, outer, courtyards, floor_to_floor, num_stories)` builds a block whose footprint has one or more courtyards cut out. The footprint is split into hole-free pieces with `polygon_difference_parts_2d`, each piece becomes one zone per story named `"<name> Part <k>"` (`"<name> Story <n> Part <k>"` for several stories), and the walls along the cuts between pieces are paired interior walls rather than exterior walls. ([#245](https://github.com/idfkit/idfkit/pull/245))
+- `idfkit.zoning.footprint_courtyard_parts(outer_width, outer_depth, inner_width, inner_depth)` returns a centred rectangular courtyard footprint as two hole-free U-shaped halves. ([#245](https://github.com/idfkit/idfkit/pull/245))
+- `IDFObject.update` sets several fields in one call, given as a mapping, keyword arguments, or both; where both name the same field, the keyword wins, as with `dict.update`. The call is all or nothing: every entry is examined before any is applied, and if one is refused, no field changes. An entry is refused when its name is not a field of the type, when it is `name` (use `IDFDocument.rename`), when it is a legacy flat extensible name such as `vertex_3_x_coordinate`, or when it gives the extensible wrapper key a value single assignment rejects: something other than a list, or a list holding an item that is not a dict or group, or a group with an unknown field. Unknown names are refused whenever the object has a schema field order, including in a document opened with `strict=False`, where single assignment stores them; an object constructed detached without one accepts any name, as single assignment does. Accepted entries are applied by ordinary attribute assignment, so reference and change tracking are those of consecutive assignments. The method returns `None`; the TypeScript `IdfObject.update` returns the object, a difference recorded in the naming register. The generated stubs type `update` per object type, so a type checker reports a misspelled field name or a wrongly typed value given as a keyword; the positional mapping is typed `Mapping[str, Any] | None`, as at run time, so that a mapping built at run time is accepted. ([#235](https://github.com/idfkit/idfkit/issues/235), [#236](https://github.com/idfkit/idfkit/pull/236))
+- `InvalidFieldError` accepts an optional keyword-only `refused`, the entries of a refused `update` group, and then lists every one in its message and in its `refused` attribute, a tuple of `idfkit.exceptions.RefusedEntry`. Without it, every message is unchanged. ([#236](https://github.com/idfkit/idfkit/pull/236))
+- **`GeocodingError` gained `kind` and `status`.** `kind` is `"not-found"`,
+  `"unreachable"`, `"http"` or `"invalid-response"`, and `status` holds the HTTP
+  code when `kind` is `"http"`, so a caller can tell a place name that matches
+  nothing from a service that could not be reached without matching message
+  text. `geocode` and `detect_location` set both on every error they raise. An
+  HTTP error from Nominatim or ipapi.co, previously reported only as "Failed to
+  geocode", now names its status. An ipapi.co payload that reports a rate limit
+  is `"http"` with `status` `429`, and a truncated response body is
+  `"unreachable"` rather than escaping as `http.client.IncompleteRead`.
+  Coordinates that are blank, boolean or not finite are `"invalid-response"`.
+  `@idfkit/weather` carries the same fields
+  ([idfkit/idfkit-js#88](https://github.com/idfkit/idfkit-js/issues/88), [#249](https://github.com/idfkit/idfkit/pull/249)).
+
+### Changed
+
+- **Breaking:** `polygon_difference_2d` raises `ValueError` when the difference has a hole (the subtracted polygon lies strictly inside) or falls into several pieces, and names `polygon_difference_parts_2d` as the replacement. It used to return a single "bridge/slit" ring for these cases, which had the wrong area or coincident vertices. The subtracted polygon no longer has to lie inside the outer one, and either winding is accepted. ([#164](https://github.com/idfkit/idfkit/issues/164), [#244](https://github.com/idfkit/idfkit/pull/244))
+- **Breaking:** A blank fixed field (any field outside a repeating group, in every object type) was stored in the model as `""`, numeric fields included, although `write_idf` and `write_epjson` both omitted it, so re-parsing idfkit's own IDF output did not equal the document it was written from: a `Zone` written with eight blank trailing commas parsed to 12 fields and came back with 4. Such a field is now left out of the model, as ConvertInputFormat and idfkit-js leave it out, and assigning `None` or `""` to a field now clears it, as it already cleared an extensible slot. A blank field now reads as `None`, as a field cut off by an earlier semicolon always has, in attribute, item and positional access and in the eppy-compatible `fieldvalues`; code that compared such a field with `""` should test for `None`. An explicit `0` is still a value, and `write_idf` still writes an interior blank in its position. ([#183](https://github.com/idfkit/idfkit/issues/183), [#242](https://github.com/idfkit/idfkit/pull/242))
+- `idfkit tmy --near ADDRESS` now exits `1` (no matches) instead of `3`
+  (network failure) when the address resolves to no place. Exit `3` remains for
+  a geocoder that could not be reached, answered with an HTTP error, or returned
+  an unreadable body
+  ([idfkit/idfkit-js#88](https://github.com/idfkit/idfkit-js/issues/88), [#249](https://github.com/idfkit/idfkit/pull/249)).
+
+### Deprecated
+
+- `footprint_courtyard` emits a `DeprecationWarning`. It returns a "slit" ring that repeats a vertex and runs out and back along a zero-width cut to the courtyard, which `create_block` turns into overlapping, opposite-facing exterior walls and a self-touching floor and roof that EnergyPlus rejects (the defect behind [#164](https://github.com/idfkit/idfkit/issues/164)). Its output is unchanged; use `create_courtyard_block` or `footprint_courtyard_parts` instead. ([#245](https://github.com/idfkit/idfkit/pull/245))
+
+### Fixed
+
+- `StationIndex.search` missed queries in the form "City, state" and accented queries, and now finds them. Tokens are split on commas and semicolons as well as whitespace, so `"Golden, CO"` no longer keeps the comma in `"golden,"`, and on dots and hyphens as station names are, so `"St. Louis, MO"` and `"Winston-Salem, NC"` find their stations; a token equal to a station's state or country code qualifies the match rather than having to appear in its name, and counts as matched in a partial match, so `"Boulder, CO"` ranks Boulder, Colorado first; a token shorter than three characters must equal a whole word of the name, so `"co"` no longer prefix-matches Mbanza Congo and Cotonou; and query and station names are compared with diacritics folded, so `"Montréal"` finds Montreal and `"Tromsø"` finds Tromso. ([#248](https://github.com/idfkit/idfkit/issues/248), [#250](https://github.com/idfkit/idfkit/pull/250))
+- `create_block`, `create_courtyard_block` and `ZonedBlock.build` with `air_boundary=True` now raise a `ValueError` naming the version requirement on a document older than EnergyPlus 9.2, before adding anything. `Construction:AirBoundary` first appeared in 9.2, and they previously added every zone and surface of the block and then failed with `UnknownObjectTypeError`, leaving the document holding a block with blank constructions on its interior walls. ([#247](https://github.com/idfkit/idfkit/pull/247))
+- A batch job refused before EnergyPlus runs, such as one without `weather` that is not design-day-only, no longer leaves an empty temporary directory behind when it names no `output_dir`. `simulate_batch` and `async_simulate_batch` created one with `tempfile.mkdtemp()` for every such job and never removed it. The failed result's `run_dir` is now `idfkit.simulation.REFUSED_RUN_DIR`, a placeholder path under the null device that cannot be created, and its output accessors such as `errors` return empty results for it without reading the filesystem. ([#228](https://github.com/idfkit/idfkit/issues/228), [#239](https://github.com/idfkit/idfkit/pull/239))
+- `SimulationCache` no longer returns a previous run's results after a file the model reads has changed. The key covered the model, the weather file and the run flags, so editing a `Schedule:File` CSV staged into `output_dir`, or one referenced by absolute path, returned the earlier run silently. The key now also hashes the contents of every file the model names for EnergyPlus to read: `Schedule:File`, `Schedule:File:Shading`, the `Table:Lookup`, `Table:IndependentVariable`, `Table:MultiVariableLookup` and `Table:TwoIndependentVariables` external files, `Construction:WindowDataFile` (including its default `Window5DataFile.dat`), the ASHRAE 205 representation files of `Chiller:Electric:ASHRAE205` and `Coil:DX:ASHRAE205:Performance`, and FMUs imported through `ExternalInterface:FunctionalMockupUnitImport`. The list is derived from the model's own schema, as the string fields marked `retaincase` whose names refer to a file or path, so file fields added by later EnergyPlus releases are covered too. A relative path is resolved as EnergyPlus resolves it, against `output_dir` and then the EnergyPlus executable's directory. Restoring a file's earlier content hits the earlier entry. A model with a `PythonPlugin:Instance`, or an `ExternalInterface` in `PtolemyServer` or `FunctionalMockupUnitExport` mode, can read inputs no key can cover, so `simulate`, `async_simulate` and the batch helpers now neither look it up nor store it, and log a warning. `SimulationCache.compute_key` takes a new `search_dirs` argument for resolving relative paths. A model that names no external file keeps the key it had, so existing cache entries stay valid. ([#241](https://github.com/idfkit/idfkit/pull/241))
+- A simulation run into an `output_dir` that already held a weather file of the same name, left by an earlier run with a different weather file, now replaces that stale copy. EnergyPlus previously ran with the earlier weather file while `SimulationCache.compute_key` hashed the new one, so the cache stored results under the wrong key. A copy with identical content, or a weather file that already lives in `output_dir`, is left untouched. ([#227](https://github.com/idfkit/idfkit/issues/227), [#237](https://github.com/idfkit/idfkit/pull/237))
+- `load_idf()` and `get_idf_version()` raised `VersionNotFoundError` on an IDF whose `Version` object carries more than three components, such as the `Version, 23.1.0.002;` that DesignBuilder writes. Components past the patch are now ignored, so that file resolves to 23.1.0, as it does in idfkit-js. The epJSON parser already read such strings this way. ([#238](https://github.com/idfkit/idfkit/pull/238))
+- `polygon_difference_2d` returns a clean simple polygon. For an edge or corner cut-out the ring used to contain coincident consecutive vertices, a zero-width slit, so `create_block` built degenerate surfaces and EnergyPlus failed. Subtracting a polygon fully inside the outer one returned the wrong area: 4212.5 m² instead of 5300 m² for a 40 × 25 m island in a 105 × 60 m footprint. The difference is now computed from a planar overlay of both outlines with only the standard library. ([#164](https://github.com/idfkit/idfkit/issues/164), [#244](https://github.com/idfkit/idfkit/pull/244))
+- The bundled `developing-with-idfkit` agent reference no longer suggests `footprint_courtyard`, or building each `polygon_difference_parts_2d` piece with its own `create_block` call, which left the walls along the cuts as exterior walls. It now points to `create_courtyard_block`. ([#245](https://github.com/idfkit/idfkit/pull/245))
+- `polygon_difference_parts_2d` no longer leaves sliver pieces when two holes' middles nearly line up. Each hole got its own vertical cut, so courtyards whose middles were 1 cm apart came back as five pieces, three of them 1 cm wide, and `create_courtyard_block` made each one a zone. The largest hole is now cut through its middle and a hole an earlier cut already crosses gets no cut of its own, giving two pieces. ([#245](https://github.com/idfkit/idfkit/pull/245))
+- `split_horizontal_surface` and `link_blocks` no longer leave a wrong-area, slit-shaped exposed roof when an upper block sits strictly inside the lower block's roof. The exposed frame is split into hole-free surfaces, and each extra piece is named `"<roof name> Remainder"` and copies the roof's construction, zone and boundary conditions. ([#164](https://github.com/idfkit/idfkit/issues/164), [#244](https://github.com/idfkit/idfkit/pull/244))
+- `view_model()` and the other 3D viewers in `idfkit.visualization` drew concave surfaces, such as L- and U-shaped floors and roofs, with spurious triangles spanning their notches. Surfaces were fan-triangulated from their first vertex, which is only correct for convex polygons; concave ones are now ear-clipped on their own plane, keeping the surface's winding, and convex ones keep the fan. Collinear and duplicate vertices are skipped, keyhole polygons with doubled bridge vertices are clipped correctly, and a self-intersecting polygon is still drawn instead of raising. ([#240](https://github.com/idfkit/idfkit/pull/240), [#246](https://github.com/idfkit/idfkit/pull/246))
+- `intersect_and_match` and `intersect_match` no longer give a concave surface drawn as a keyhole (a courtyard roof or ceiling with doubled bridge vertices), or one pinched at a vertex, the wrong area when they split it. Its triangulation clipped triangles that lay outside the surface. A 96 m² keyhole ceiling with one 4 m² floor above it was split into fragments totalling 168 m²; they now total 96 m². ([#246](https://github.com/idfkit/idfkit/pull/246))
+- An IDF file whose last object has no closing `;`, such as `Version, 24.1;\nZone, Z1, 0`, no longer loads with that object silently dropped. A strict parse (the default) raises `IDFParseError` with an `Unterminated object near "..." (missing ";")` finding of code `ParseError`, positioned at the line the object starts on and naming its type. With `strict_parsing=False` or `load_idf_with_diagnostics` the rest of the file still loads, and the finding is logged as a warning and returned. Trailing whitespace and comments are not affected. The same change removes exponential backtracking in the object pattern and in the `preserve_formatting=True` syntax-tree pattern, which made an unterminated tail of thirty characters take more than one hundred seconds to read, and `iter_idf_objects` now skips such a tail with a warning instead of scanning it. ([#187](https://github.com/idfkit/idfkit/issues/187), [#243](https://github.com/idfkit/idfkit/pull/243))
+
 ## [1.1.1] - 2026-10-19
 
 ### Fixed
@@ -908,7 +977,9 @@ Initial public release.
 - Performance benchmarks comparing idfkit against eppy and opyplus. ([#5](https://github.com/idfkit/idfkit/pull/5))
 - MkDocs Material documentation site with a full API reference, an eppy migration guide, and a getting-started Jupyter notebook. ([#2](https://github.com/idfkit/idfkit/pull/2))
 
-[Unreleased]: https://github.com/idfkit/idfkit/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/idfkit/idfkit/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/idfkit/idfkit/compare/v1.1.1...v1.2.0
+[1.1.1]: https://github.com/idfkit/idfkit/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/idfkit/idfkit/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/idfkit/idfkit/compare/v1.0.0-rc.6...v1.0.0
 [1.0.0-rc.6]: https://github.com/idfkit/idfkit/compare/v1.0.0-rc.5...v1.0.0-rc.6

{idfkit-1.1.1 → idfkit-1.2.0}/Makefile

@@ -89,7 +89,7 @@ check: check-stubs check-conformance-level check-epw-sentinels check-doc-locatio
 	@echo "🚀 Linting code: Running pre-commit"
 	@uv run pre-commit run -a
 	@echo "🚀 Static type checking: Running pyright"
-	@uv run pyright src/ agent_references/snippets
+	@uv run pyright src/ agent_references/snippets tests/type_checks
 	@echo "🚀 Checking for obsolete dependencies: Running deptry"
 	@uv run deptry src
 

{idfkit-1.1.1 → idfkit-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: idfkit
-Version: 1.1.1
+Version: 1.2.0
 Summary: A fast, modern EnergyPlus IDF/epJSON parser with O(1) lookups and reference tracking
 Project-URL: Homepage, https://py.idfkit.com/
 Project-URL: Repository, https://github.com/idfkit/idfkit
@@ -57,27 +57,26 @@ Description-Content-Type: text/markdown
 
 **A fast, modern EnergyPlus IDF/epJSON toolkit for Python.**
 
-> [!IMPORTANT]
-> **The next release renames how you write a model to disk.** `write_idf(doc, path)`
-> becomes `save_idf(doc, path)`, and `write_epjson(doc, path)` becomes
-> `save_epjson(doc, path)`. `write_*` now only returns a string.
+> [!NOTE]
+> **Upgrading from 0.x.** Since 1.0.0, writing a model to disk uses
+> `save_idf(doc, path)` and `save_epjson(doc, path)`. `write_idf` and
+> `write_epjson` only return a string.
 >
-> Worth knowing before you upgrade, because neither failure names the cause:
+> Code that still calls `write_*` with a path fails without naming the cause:
 > `write_epjson(doc, path)` raises `TypeError: can't multiply sequence by
-> non-int of type 'PosixPath'`, and `write_idf(doc, path)` fails silently,
-> writing nothing and leaving an empty file that surfaces later as
+> non-int of type 'PosixPath'`, and `write_idf(doc, path)` writes nothing,
+> leaving an empty file that surfaces later as
 > `Could not detect EnergyPlus version in file`.
 >
 > Search for `write_idf(` and `write_epjson(` called with two positional
-> arguments, or run a type checker, which rejects both. Full notes in the
+> arguments, or run a type checker, which rejects both. Full notes are in the
 > [changelog](CHANGELOG.md#migration).
 
 > [!NOTE]
-> idfkit is in **beta**. The API may change between minor versions. We're looking
-> for early adopters and testers — especially users of eppy who want
-> better performance and a modern API. If you try it out, please
-> [open an issue](https://github.com/idfkit/idfkit/issues) with feedback,
-> bug reports, or feature requests.
+> idfkit follows [semantic versioning](https://semver.org/): breaking API
+> changes occur only in major releases and are recorded in the
+> [changelog](CHANGELOG.md). Feedback, bug reports, and feature requests are
+> welcome as [GitHub issues](https://github.com/idfkit/idfkit/issues).
 
 idfkit lets you load, create, query, and modify EnergyPlus models with an
 intuitive Python API. It is designed as a drop-in replacement for

{idfkit-1.1.1 → idfkit-1.2.0}/README.md

@@ -7,27 +7,26 @@
 
 **A fast, modern EnergyPlus IDF/epJSON toolkit for Python.**
 
-> [!IMPORTANT]
-> **The next release renames how you write a model to disk.** `write_idf(doc, path)`
-> becomes `save_idf(doc, path)`, and `write_epjson(doc, path)` becomes
-> `save_epjson(doc, path)`. `write_*` now only returns a string.
+> [!NOTE]
+> **Upgrading from 0.x.** Since 1.0.0, writing a model to disk uses
+> `save_idf(doc, path)` and `save_epjson(doc, path)`. `write_idf` and
+> `write_epjson` only return a string.
 >
-> Worth knowing before you upgrade, because neither failure names the cause:
+> Code that still calls `write_*` with a path fails without naming the cause:
 > `write_epjson(doc, path)` raises `TypeError: can't multiply sequence by
-> non-int of type 'PosixPath'`, and `write_idf(doc, path)` fails silently,
-> writing nothing and leaving an empty file that surfaces later as
+> non-int of type 'PosixPath'`, and `write_idf(doc, path)` writes nothing,
+> leaving an empty file that surfaces later as
 > `Could not detect EnergyPlus version in file`.
 >
 > Search for `write_idf(` and `write_epjson(` called with two positional
-> arguments, or run a type checker, which rejects both. Full notes in the
+> arguments, or run a type checker, which rejects both. Full notes are in the
 > [changelog](CHANGELOG.md#migration).
 
 > [!NOTE]
-> idfkit is in **beta**. The API may change between minor versions. We're looking
-> for early adopters and testers — especially users of eppy who want
-> better performance and a modern API. If you try it out, please
-> [open an issue](https://github.com/idfkit/idfkit/issues) with feedback,
-> bug reports, or feature requests.
+> idfkit follows [semantic versioning](https://semver.org/): breaking API
+> changes occur only in major releases and are recorded in the
+> [changelog](CHANGELOG.md). Feedback, bug reports, and feature requests are
+> welcome as [GitHub issues](https://github.com/idfkit/idfkit/issues).
 
 idfkit lets you load, create, query, and modify EnergyPlus models with an
 intuitive Python API. It is designed as a drop-in replacement for

{idfkit-1.1.1 → idfkit-1.2.0}/agent_references/snippets/document-and-objects.py

@@ -63,6 +63,23 @@ for material in doc.materials:
 # --8<-- [end:lookup]
 
 
+# --8<-- [start:accessors]
+# Any type in the schema is reachable as a typed attribute, not only common ones.
+loops = doc.air_loop_hvacs  # IDFCollection[AirLoopHVAC]
+coils = doc.coil_cooling_dx_single_speeds  # Coil:Cooling:DX:SingleSpeed
+also_loops = doc["AirLoopHVAC"]  # equivalent
+shades = doc.shading_building_detaileds  # Shading:Building:Detailed
+
+# A typo names the closest matches and their object types:
+#   >>> doc.shading_bulding
+#   AttributeError: 'IDFDocument' object has no attribute 'shading_bulding'.
+#   Did you mean:
+#     shading_building   (Shading:Building:Detailed)
+#     shading_buildings  (Shading:Building)
+#     shading_fins       (Shading:Fin)
+# --8<-- [end:accessors]
+
+
 # --8<-- [start:modify]
 zone = doc["Zone"]["Office"]
 zone.ceiling_height = 3.5  # plain field

{idfkit-1.1.1 → idfkit-1.2.0}/agent_references/snippets/geometry-and-surfaces.py

@@ -148,10 +148,43 @@ inner = [(1, 1), (4, 1), (4, 4), (1, 4)]
 polygon_area_2d(a)  # 50.0
 polygon_contains_2d(a, inner)  # True (every vertex of inner is inside a)
 polygon_intersection_2d(a, b)  # overlapping rectangle
-polygon_difference_2d(a, b)  # a minus b
+polygon_difference_2d(a, b)  # a minus b: [(0, 0), (5, 0), (5, 5), (0, 5)]
 # --8<-- [end:polygon-2d]
 
 
+# --8<-- [start:polygon-difference-parts]
+from idfkit import footprint_rectangle
+from idfkit.geometry import polygon_difference_parts_2d
+from idfkit.zoning import create_courtyard_block
+
+site = footprint_rectangle(105, 60)
+courtyard = footprint_rectangle(40, 25, origin=(35, 20))  # strictly inside: leaves a hole
+office = footprint_rectangle(33.3, 9.0)  # corner cut-out
+
+# polygon_difference_2d(site, courtyard) raises ValueError: the result has a hole.
+pieces = polygon_difference_parts_2d(site, courtyard, office)
+
+# To build them, keep the pieces in one block so the cut walls become interior walls:
+create_courtyard_block(doc, "Wing", site, [courtyard, office], floor_to_floor=3.5)
+# --8<-- [end:polygon-difference-parts]
+
+
+# --8<-- [start:triangulate-2d]
+from idfkit.geometry import triangulate_2d
+
+l_shape = [(10, 5), (5, 5), (5, 10), (0, 10), (0, 0), (10, 0)]
+triangles = triangulate_2d(l_shape)  # [(5, 0, 1), (1, 2, 3), (1, 3, 4), (1, 4, 5)]
+total = sum(polygon_area_2d([l_shape[i] for i in tri]) for tri in triangles)  # 75.0
+# --8<-- [end:triangulate-2d]
+
+
+# --8<-- [start:mistake-hole-good]
+from idfkit.zoning import create_courtyard_block
+
+create_courtyard_block(doc, "Block", site, [courtyard], floor_to_floor=3.5)
+# --8<-- [end:mistake-hole-good]
+
+
 # --8<-- [start:mistake-area-good]
 calculate_surface_area(surface)
 # --8<-- [end:mistake-area-good]

{idfkit-1.1.1 → idfkit-1.2.0}/agent_references/snippets/geometry-builders-and-zoning.py

@@ -27,16 +27,34 @@ from idfkit import (
     footprint_rectangle,
     footprint_l_shape,
     footprint_u_shape,
-    footprint_courtyard,
 )
 
 rect = footprint_rectangle(width=50, depth=30)
 ell = footprint_l_shape(width=40, depth=20, wing_width=20, wing_depth=15)
 u = footprint_u_shape(width=40, depth=30, courtyard_width=15, courtyard_depth=10)
-courtyard = footprint_courtyard(outer_width=40, outer_depth=30, inner_width=15, inner_depth=10)
 # --8<-- [end:footprints]
 
 
+# --8<-- [start:courtyard]
+from idfkit.zoning import create_courtyard_block, footprint_courtyard_parts
+
+# One call: the footprint minus the courtyard(s), split into hole-free pieces,
+# one zone per piece per story, cut walls between pieces paired as interior walls.
+create_courtyard_block(
+    doc,
+    "Office",
+    footprint_rectangle(50, 40),
+    [footprint_rectangle(20, 10, origin=(15, 15))],
+    floor_to_floor=3.5,
+    num_stories=3,
+)
+# Zones: "Office Story 1 Part 1", "Office Story 1 Part 2", ...
+
+# Just the pieces (two U-shaped halves), e.g. to inspect or zone them yourself
+halves = footprint_courtyard_parts(outer_width=50, outer_depth=40, inner_width=20, inner_depth=10)
+# --8<-- [end:courtyard]
+
+
 # --8<-- [start:zoning-schemes]
 from idfkit import ZoningScheme, ZoneFootprint
 
@@ -133,6 +151,22 @@ new_a, new_b = split_horizontal_surface(
 # --8<-- [end:split-surface]
 
 
+# --8<-- [start:split-surface-regions]
+from idfkit.geometry_builders import split_horizontal_surface_by_regions
+
+region_surfaces, remaining_surfaces = split_horizontal_surface_by_regions(
+    doc,
+    surface,
+    regions=[
+        [(10, 5), (15, 5), (15, 15), (10, 15)],
+        [(15, 5), (20, 5), (20, 15), (15, 15)],
+    ],
+)
+# region_surfaces: one new surface per region, in order
+# remaining_surfaces: the original surface first, then any extra remainder pieces
+# --8<-- [end:split-surface-regions]
+
+
 # --8<-- [start:mistake-ccw-good]
 ccw_rect = footprint_rectangle(50, 30)  # CCW by construction
 # --8<-- [end:mistake-ccw-good]
@@ -145,6 +179,13 @@ for zone in doc["Zone"]:
 # --8<-- [end:mistake-hvac-good]
 
 
+# --8<-- [start:mistake-courtyard-good]
+create_courtyard_block(
+    doc, "Office", footprint_rectangle(50, 40), [footprint_rectangle(20, 10, origin=(15, 15))], floor_to_floor=3.5
+)
+# --8<-- [end:mistake-courtyard-good]
+
+
 # --8<-- [start:mistake-link-good]
 link_blocks(doc)
 # --8<-- [end:mistake-link-good]

{idfkit-1.1.1 → idfkit-1.2.0}/agent_references/snippets/parsing-idf-epjson.py

@@ -43,6 +43,16 @@ except IDFParseError as e:
 # --8<-- [end:strict-parsing]
 
 
+# --8<-- [start:blank-fields]
+# Zone, Office, 0, 0, 0, 0, , , ;  -- type, multiplier and ceiling height left blank
+zone = doc["Zone"]["Office"]
+zone.ceiling_height  # None, exactly as if the semicolon had come earlier
+"ceiling_height" in zone.data  # False: a blank field is not stored
+if zone.ceiling_height is None:
+    zone.ceiling_height = "Autocalculate"
+# --8<-- [end:blank-fields]
+
+
 # --8<-- [start:version]
 from idfkit import get_idf_version
 
@@ -106,6 +116,12 @@ if report.success and report.migrated_model is not None:
 # --8<-- [end:mistake-version-good]
 
 
+# --8<-- [start:mistake-blank-good]
+if zone.multiplier is None:  # blank or never written: both read as None
+    ...
+# --8<-- [end:mistake-blank-good]
+
+
 # --8<-- [start:mistake-preserve-good]
 doc = load_idf("building.idf", preserve_formatting=True)
 save_idf(doc, "out.idf")  # byte-identical

{idfkit-1.1.1 → idfkit-1.2.0}/agent_references/snippets/simulation-execution.py

@@ -94,7 +94,7 @@ asyncio.run(main())
 
 
 # --8<-- [start:batch]
-from idfkit.simulation import simulate_batch, SimulationJob
+from idfkit.simulation import REFUSED_RUN_DIR, simulate_batch, SimulationJob
 
 jobs = []
 for wwr in (0.2, 0.3, 0.4, 0.5):
@@ -106,7 +106,10 @@ for wwr in (0.2, 0.3, 0.4, 0.5):
 
 batch = simulate_batch(jobs, max_workers=4)
 for job, result in zip(jobs, batch):
-    print(job.label, result.errors.summary())
+    if result.run_dir == REFUSED_RUN_DIR:
+        print(job.label, "refused:", result.stderr)  # EnergyPlus never ran
+    else:
+        print(job.label, result.errors.summary())
 # --8<-- [end:batch]
 
 

{idfkit-1.1.1 → idfkit-1.2.0}/agent_references/snippets/weather-data.py

@@ -60,6 +60,23 @@ results = index.nearest(*geocode("350 Fifth Avenue, New York, NY"))
 # --8<-- [end:search-address]
 
 
+# --8<-- [start:geocode-errors]
+from idfkit.weather import GeocodingError, geocode
+
+
+def locate(query: str) -> tuple[float, float] | str:
+    try:
+        return geocode(query)
+    except GeocodingError as exc:
+        if exc.kind == "not-found":  # Nominatim answered: no such place
+            return f"No place called {query!r} was found."
+        # "unreachable", "http" (exc.status holds the code), or "invalid-response"
+        return "The place-name service could not be reached; try again shortly."
+
+
+# --8<-- [end:geocode-errors]
+
+
 # --8<-- [start:search-coords]
 hits = index.nearest(41.978, -87.904, limit=10)
 # --8<-- [end:search-coords]

{idfkit-1.1.1 → idfkit-1.2.0}/agent_references/templates/SKILL.md

@@ -17,6 +17,7 @@ Read `references/<topic>.md` for focused, task-oriented guidance. Each reference
 | Find or update cross-references between objects | [reference-tracking.md](references/reference-tracking.md) |
 | Compute surface area, zone volume, azimuth, WWR | [geometry-and-surfaces.md](references/geometry-and-surfaces.md) |
 | Build a building footprint and zone it | [geometry-builders-and-zoning.md](references/geometry-builders-and-zoning.md) |
+| Build a footprint with a courtyard or hole (no slit polygons) | [geometry-builders-and-zoning.md](references/geometry-builders-and-zoning.md) |
 | Stand up an HVAC system quickly with `HVACTemplate:*` | [hvac-templates.md](references/hvac-templates.md) |
 | Hand-author `AirLoopHVAC` / `PlantLoop` / `CondenserLoop` | [hvac-loops.md](references/hvac-loops.md) |
 | Run EnergyPlus simulations (sync, async, batch) | [simulation-execution.md](references/simulation-execution.md) |

{idfkit-1.1.1 → idfkit-1.2.0}/agent_references/templates/document-and-objects.md

@@ -24,7 +24,7 @@ The `IDFDocument` is the in-memory representation of an EnergyPlus model. Every
 | `doc.schema` | `EpJSONSchema` for the document's version. |
 | `doc[obj_type]` | The `IDFCollection` for the type. Type names are case-insensitive, as they are in EnergyPlus, so `doc["zone"]` and `doc["Zone"]` are the same collection. Never raises: an absent or misspelled type gives an empty collection that is detached from the document, so reading a type never inserts it. |
 | `doc.get_collection(obj_type)` | The same operation, typed for dynamic `str` keys. It delegates to `doc[obj_type]`; there is no behavioural difference. |
-| `doc.<attr>` | Python-name accessors for common types: `doc.zones`, `doc.buildings`, `doc.materials`, `doc.constructions`, `doc.hvac_templates`, etc. |
+| `doc.<attr>` | Typed attribute accessor for any schema type: the `snake_case` plural (`doc.air_loop_hvacs` is `IDFCollection[AirLoopHVAC]`). Hand-written shorthands also resolve and keep their meaning (`doc.building_surfaces` → `BuildingSurface:Detailed`, `doc.ideal_loads` → `ZoneHVAC:IdealLoadsAirSystem`). A typo raises `AttributeError` naming the closest matches. |
 | `doc.add(obj_type, name=None, **fields)` | Create and insert an object. Returns the new `IDFObject`. |
 | `doc.rename(obj_type, old, new)` | Rename + cascade updates through every reference. |
 | `doc.removeidfobject(obj)` | Delete an object. |
@@ -52,6 +52,16 @@ Singletons (objects EnergyPlus requires exactly one of, like `Building` or `Simu
 
 Collections support `.first()` (when you know there's a singleton), `.values()`, name-keyed `[name]` access, and `in` membership tests.
 
+Any object type in the schema is also reachable as an attribute: its `snake_case` plural, typed like the subscript form. Use the attribute in application code, and `doc["Type:Name"]` when the type name comes from EnergyPlus documentation, an epJSON file or a variable. A misspelling raises `AttributeError` naming the closest matches:
+
+```python
+--8<-- "agent_references/snippets/document-and-objects.py:accessors"
+```
+
+Names are derived from the schema by rule, so object types added in a new EnergyPlus release are reachable with no change to idfkit. Three types the rule cannot split are named explicitly (`Output:SQLite` is `doc.output_sqlite`), and singular nouns ending in `s` get a real plural (`doc.window_material_gases`). The plural of every type, plus the shorthands, is declared in the type stub, so editors complete it and type checkers see `IDFCollection` of the generated class. The same names appear in `dir(doc)` for IPython and Jupyter.
+
+Resolution is strict about separators: `doc.z_o_n_e`, `doc.zone_`, `doc.airloophvacs` and the singular `doc.air_loop_hvac` all raise rather than guess. The raw type name with `_` in place of `:` resolves in any case (`doc.Site_Location`, `doc.ZONE`), as it did before derived names existed, but is untyped. A name owned by a real member wins over any accessor: `doc.version` is the version tuple, and the `Version` objects are `doc.versions`.
+
 ## Modifying objects
 
 Field access is via attribute. Setting a value re-validates against the schema and updates the reference graph automatically:

{idfkit-1.1.1 → idfkit-1.2.0}/agent_references/templates/geometry-and-surfaces.md

@@ -83,7 +83,7 @@ For higher-level ceiling↔floor helpers, see [geometry-builders-and-zoning.md](
 
 ## 2D polygon utilities
 
-For computing footprint overlaps or differences (e.g. courtyard cut-outs):
+For computing footprint overlaps or differences (e.g. corner cut-outs):
 
 ```python
 --8<-- "agent_references/snippets/geometry-and-surfaces.py:polygon-2d"
@@ -91,8 +91,35 @@ For computing footprint overlaps or differences (e.g. courtyard cut-outs):
 
 These take 2D `(x, y)` tuples (not `Vector3D`) because the typical use is on building footprints in plan view.
 
+`polygon_difference_2d` returns one clean, counter-clockwise, simple polygon with no duplicate or coincident vertices, ready for `create_block`. The subtracted polygon may cross the outer boundary, sit flush with a corner, or extend outside it. A single ring cannot describe a result with a hole (the subtracted polygon strictly inside) or a result in several pieces, so `polygon_difference_2d` raises `ValueError` for those. Use `polygon_difference_parts_2d` from `idfkit.geometry` there. It subtracts any number of polygons and returns hole-free pieces, largest first, each one a valid EnergyPlus surface outline or `create_block` footprint. Building each piece with its own `create_block` call leaves the walls along the cuts as exterior walls; `create_courtyard_block` (in `idfkit.zoning`) builds the pieces as zones of one block so those walls are paired interior walls:
+
+```python
+--8<-- "agent_references/snippets/geometry-and-surfaces.py:polygon-difference-parts"
+```
+
+To cut a concave outline into triangles (for a mesh, or for area-weighted sampling), use `triangulate_2d` from `idfkit.geometry`. It returns index triples into the input, in the input's winding, and it handles keyhole outlines whose bridge vertices are doubled:
+
+```python
+--8<-- "agent_references/snippets/geometry-and-surfaces.py:triangulate-2d"
+```
+
 ## Common mistakes
 
+!!! failure "stitching a hole into one polygon with a slit"
+
+    ```python
+    # Joining the outer ring and the hole ring with a zero-width "bridge" edge
+    # gives coincident vertices, so create_block makes degenerate surfaces and EnergyPlus fatals.
+    slit = [*outer, outer[0], hole[0], *reversed(hole), hole[0]]
+    create_block(doc, "Block", slit, floor_to_floor=3.5)
+    ```
+
+!!! success "split it into hole-free pieces in one block"
+
+    ```python
+    --8<-- "agent_references/snippets/geometry-and-surfaces.py:mistake-hole-good"
+    ```
+
 !!! failure "manually summing vertex coordinates"
 
     ```python

{idfkit-1.1.1 → idfkit-1.2.0}/agent_references/templates/geometry-builders-and-zoning.md

@@ -27,6 +27,16 @@ idfkit provides parametric footprint generators that return `list[tuple[float, f
 
 Or pass any CCW `list[tuple[float, float]]` you generate yourself.
 
+## Courtyards (footprints with holes)
+
+EnergyPlus surfaces cannot have holes, so a footprint with a courtyard has to become several simple pieces. Use `create_courtyard_block` from `idfkit.zoning`: it subtracts the courtyard polygons from the outer footprint with `polygon_difference_parts_2d`, makes one zone per piece per story (`"<name> Part <k>"`, largest first), and builds the pieces as `CUSTOM` zones of one block, so the walls along the cuts are interior `Surface` walls paired between the pieces' zones, not exterior walls. Courtyards may also touch or cross the outer edge (a notch). `footprint_courtyard_parts` returns the two hole-free halves of a centred rectangular courtyard if you want the polygons themselves:
+
+```python
+--8<-- "agent_references/snippets/geometry-builders-and-zoning.py:courtyard"
+```
+
+Each piece is concave, so there is no `zoning=` argument: every piece is one zone per story. For a finer split, compute the pieces yourself and pass them (or your own subdivision of them) as `custom_zones` to `create_block` with `ZoningScheme.CUSTOM`; walls whose edges match in reverse become interior walls.
+
 ## Zoning schemes
 
 `ZoningScheme` controls how each story is partitioned:
@@ -41,7 +51,7 @@ Or pass any CCW `list[tuple[float, float]]` you generate yourself.
 
 `create_block` also accepts:
 
-- `air_boundary=True` — apply `Construction:AirBoundary` to all inter-zone walls. Use for open-plan spaces that share air but are still thermally distinct.
+- `air_boundary=True` — apply `Construction:AirBoundary` to all inter-zone walls. Use for open-plan spaces that share air but are still thermally distinct. Needs EnergyPlus 9.2+; on an older document it raises `ValueError` before adding anything.
 - `base_elevation` — ground floor Z (default 0). When > 0, the ground-floor boundary becomes `Outdoors` instead of `Ground`.
 
 ## Multi-block buildings (setbacks)
@@ -88,6 +98,12 @@ When a footprint changes and you want to keep one surface but redraw it:
 --8<-- "agent_references/snippets/geometry-builders-and-zoning.py:split-surface"
 ```
 
+The remainder is always EnergyPlus-safe: no holes and no zero-width slits. When the region sits strictly inside the surface, the remainder would be a frame with a hole, so it is cut into hole-free pieces. The original surface keeps the largest piece, and each other piece becomes a new `"<name> Remainder"` surface that copies its construction, zone and boundary conditions. To get those surfaces back, or to split under several adjacent regions at once (as `link_blocks` does for every floor resting on one roof), use `split_horizontal_surface_by_regions`:
+
+```python
+--8<-- "agent_references/snippets/geometry-builders-and-zoning.py:split-surface-regions"
+```
+
 ## Common mistakes
 
 !!! failure "passing a clockwise footprint"
@@ -120,6 +136,21 @@ When a footprint changes and you want to keep one surface but redraw it:
 
 See [hvac-templates.md](hvac-templates.md).
 
+!!! failure "the deprecated `footprint_courtyard` slit polygon"
+
+    ```python
+    fp = footprint_courtyard(50, 40, 20, 10)  # DeprecationWarning
+    create_block(doc, "Office", fp, floor_to_floor=3.5)
+    # The ring repeats a vertex and runs out and back along a zero-width slit:
+    # two overlapping exterior walls and a self-touching floor. EnergyPlus fails.
+    ```
+
+!!! success "`create_courtyard_block`"
+
+    ```python
+    --8<-- "agent_references/snippets/geometry-builders-and-zoning.py:mistake-courtyard-good"
+    ```
+
 !!! failure "forgetting `link_blocks` between setbacks"
 
     ```python

{idfkit-1.1.1 → idfkit-1.2.0}/agent_references/templates/parsing-idf-epjson.md

@@ -48,6 +48,14 @@ Drop to `strict=False` only as a tolerant fallback for legacy or noisy files:
 --8<-- "agent_references/snippets/parsing-idf-epjson.py:strict-parsing"
 ```
 
+## Blank fields are unset
+
+A blank IDF field (`, ,`) is an unset field. It is not stored in `obj.data`, it is not written to epJSON, and it reads as `None`, the same as a field cut off by an early semicolon. An explicit `0` is a value and is kept. Assigning `None` or `""` to a field clears it the same way. Writing the document back to IDF and reading it again gives an equal model.
+
+```python
+--8<-- "agent_references/snippets/parsing-idf-epjson.py:blank-fields"
+```
+
 ## Version handling
 
 Every document is tied to a specific EnergyPlus version. The parser reads the `Version` object and picks the matching bundled schema (8.9 through 26.2 — see `idfkit.ENERGYPLUS_VERSIONS`).
@@ -124,6 +132,19 @@ For batch workflows, preload the schema once and pass it to every `IDFParser` so
     --8<-- "agent_references/snippets/parsing-idf-epjson.py:mistake-version-good"
     ```
 
+!!! failure "testing a blank field against the empty string"
+
+    ```python
+    if zone.multiplier == "":                  # never true: a blank field reads as None
+        zone.multiplier = 1
+    ```
+
+!!! success "test for None"
+
+    ```python
+    --8<-- "agent_references/snippets/parsing-idf-epjson.py:mistake-blank-good"
+    ```
+
 !!! failure "forgetting `preserve_formatting` for the writer side"
 
     ```python

{idfkit-1.1.1 → idfkit-1.2.0}/agent_references/templates/simulation-execution.md

@@ -82,6 +82,8 @@ For UI loops or asyncio-based batch tooling:
 
 `async_simulate_batch` and `async_simulate_batch_stream` give you async/streaming variants. `simulate_batch` runs jobs concurrently on a thread pool (use `max_workers` to cap parallelism); each job is an EnergyPlus subprocess, so threads are all the parallelism it needs and documents never cross a process boundary.
 
+A job that fails never raises out of the batch: its result has `success=False` and the reason in `result.stderr`. A job refused before EnergyPlus ran (for example `weather=None` on a job that is not design-day-only) and that named no `output_dir` gets `run_dir == REFUSED_RUN_DIR`, a placeholder that is never created; its `errors` report is empty, so read `stderr` for the reason.
+
 ## Caching
 
 If you re-simulate the same model + weather + flags often (e.g. iterating on output processing), wrap in a `SimulationCache`:
@@ -90,7 +92,9 @@ If you re-simulate the same model + weather + flags often (e.g. iterating on out
 --8<-- "agent_references/snippets/simulation-execution.py:caching"
 ```
 
-The cache key is the SHA-256 of the (model bytes + weather bytes + flags) tuple. Any change invalidates the entry.
+The cache key is the SHA-256 of the model, the weather file, the run flags, and the contents of every other file the model names: `Schedule:File` and `Schedule:File:Shading` CSVs, `Table:Lookup` / `Table:IndependentVariable` data files, `Construction:WindowDataFile`, ASHRAE 205 representation files and imported FMUs (the list is derived from the model's schema, so it follows the EnergyPlus version). Any change to any of them is a miss, and restoring a file's earlier content is a hit on the earlier entry. So staging a `Schedule:File` CSV into `output_dir` and varying it across runs caches correctly. A relative file path is resolved the way EnergyPlus resolves it: against `output_dir`, then the EnergyPlus executable's directory.
+
+A model with a `PythonPlugin:Instance`, or with an `ExternalInterface` in `PtolemyServer` or `FunctionalMockupUnitExport` mode, has inputs no key can cover. `simulate` never caches it and logs a warning saying why.
 
 ## Progress events