idfpy 25.2.2__tar.gz → 25.2.4__tar.gz

idfpy-25.2.4/.github/workflows/docs.yml

@@ -0,0 +1,88 @@
+name: Docs
+
+# Builds one documentation copy per release/ep-* branch and deploys the whole
+# site to GitHub Pages. Guides and configuration always come from master.
+# Both release workflows push with GITHUB_TOKEN, which does not trigger other
+# workflows, so new releases are picked up through workflow_run. The weekly
+# Sync EnergyPlus run also rebuilds when it finds nothing new; that costs a
+# minute or two and keeps the trigger free of extra permissions.
+on:
+  push:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "scripts/docs/**"
+      - "zensical.toml"
+      - ".github/workflows/docs.yml"
+  workflow_run:
+    workflows: ["Release EnergyPlus Version", "Sync EnergyPlus"]
+    types: [completed]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    if: github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: master
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v10.2.0
+
+      - name: List EnergyPlus versions
+        id: versions
+        run: |
+          list=$(git for-each-ref --format='%(refname:short)' 'refs/remotes/origin/release/ep-*' \
+            | sed 's#^origin/release/ep-##' | sort -V | tr '\n' ' ')
+          echo "list=${list% }" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/cache@v6
+        with:
+          path: schemas
+          key: ep-schemas-${{ steps.versions.outputs.list }}
+          restore-keys: ep-schemas-
+
+      # Only Energy+.schema.epJSON is extracted from each EnergyPlus release
+      # archive; the cache avoids repeating the ~200 MB downloads.
+      - name: Download EnergyPlus schemas
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          for version in ${{ steps.versions.outputs.list }}; do
+            dest="schemas/$version"
+            [ -f "$dest/Energy+.schema.epJSON" ] && continue
+            url=$(gh api "repos/NREL/EnergyPlus/releases/tags/v$version" --jq \
+              '[.assets[] | select(.name | test("Linux.*x86_64\\.tar\\.gz$"))][0].browser_download_url')
+            mkdir -p "$dest"
+            curl -fsSL "$url" | tar -xz --wildcards --strip-components=1 -C "$dest" '*/Energy+.schema.epJSON'
+          done
+
+      - run: uv sync --group docs
+
+      - name: Build site
+        run: uv run python scripts/docs/build_site.py --schema-pattern 'schemas/{version}/Energy+.schema.epJSON'
+
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

{idfpy-25.2.2 → idfpy-25.2.4}/.github/workflows/sync-energyplus.yml

@@ -46,37 +46,40 @@ jobs:
           } >> "$GITHUB_OUTPUT"
           echo "EnergyPlus $VERSION -> $ASSET_URL"
 
-      - name: Skip if version already released
+      - name: Skip if EnergyPlus line already released
         id: check
         run: |
-          VERSION="${{ steps.ep.outputs.version }}"
-          TAG="v${VERSION}"
-
-          TAG_EXISTS=false
-          if git ls-remote --exit-code --tags origin "refs/tags/$TAG" > /dev/null 2>&1; then
-            TAG_EXISTS=true
-          fi
+          EP_VERSION="${{ steps.ep.outputs.version }}"
+          MAJOR_MINOR="${EP_VERSION%.*}"
 
-          PYPI_EXISTS=false
-          HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
-            "https://pypi.org/pypi/idfpy/${VERSION}/json")
-          if [ "$HTTP_CODE" = "200" ]; then
-            PYPI_EXISTS=true
-          fi
+          # idfpy versions are <EP major>.<EP minor>.<idfpy patch>; any release
+          # on this line means the EnergyPlus version is already covered.
+          LINE_TAGS=$(git tag -l "v${MAJOR_MINOR}.*")
+          LINE_PYPI=$(curl -fsS "https://pypi.org/pypi/idfpy/json" \
+            | jq -r --arg p "${MAJOR_MINOR}." '.releases | keys[] | select(startswith($p))')
 
           SKIP=false
-          if [ "$TAG_EXISTS" = "true" ] && [ "$PYPI_EXISTS" = "true" ]; then
-            echo "Tag $TAG and PyPI ${VERSION} both already exist; skipping"
+          if [ -n "$LINE_TAGS" ] && [ -n "$LINE_PYPI" ]; then
+            echo "idfpy ${MAJOR_MINOR}.* already released for EnergyPlus ${EP_VERSION}; skipping"
             SKIP=true
-          elif [ "$TAG_EXISTS" = "true" ]; then
-            echo "::error::Tag $TAG already exists but PyPI ${VERSION} is missing; refusing to proceed"
+          elif [ -n "$LINE_TAGS" ]; then
+            echo "::error::Tags v${MAJOR_MINOR}.* exist but PyPI has no ${MAJOR_MINOR}.* release; refusing to proceed"
             exit 1
-          elif [ "$PYPI_EXISTS" = "true" ]; then
-            echo "::error::PyPI ${VERSION} already exists but tag $TAG is missing; refusing to proceed"
+          elif [ -n "$LINE_PYPI" ]; then
+            echo "::error::PyPI has ${MAJOR_MINOR}.* releases but tags v${MAJOR_MINOR}.* are missing; refusing to proceed"
             exit 1
           fi
 
-          echo "skip=$SKIP" >> "$GITHUB_OUTPUT"
+          # A new line starts at the current idfpy patch shared by all lines.
+          PATCH=$(git tag -l 'v*' \
+            | sed -nE 's/^v[0-9]+\.[0-9]+\.([0-9]+)$/\1/p' | sort -n | tail -1)
+          RELEASE_VERSION="${MAJOR_MINOR}.${PATCH:-0}"
+
+          {
+            echo "skip=$SKIP"
+            echo "release_version=$RELEASE_VERSION"
+          } >> "$GITHUB_OUTPUT"
+          echo "EnergyPlus ${EP_VERSION} -> idfpy ${RELEASE_VERSION} (skip=${SKIP})"
 
       - name: Download schema
         if: steps.check.outputs.skip == 'false'
@@ -107,6 +110,7 @@ jobs:
         if: steps.check.outputs.skip == 'false'
         run: |
           EP_VERSION="${{ steps.ep.outputs.version }}"
+          RELEASE_VERSION="${{ steps.check.outputs.release_version }}"
           MAJOR_MINOR="${EP_VERSION%.*}"
 
           OBJ_COUNT=$(grep -rh '_idf_object_type: ClassVar' idfpy/models/*.py \
@@ -115,7 +119,7 @@ jobs:
           PROP_COUNT=$(grep -rh '^    @property$' idfpy/models/*.py \
             | grep -cv '_base.py')
 
-          sed -i "s/^version = .*/version = \"${EP_VERSION}\"/" pyproject.toml
+          sed -i "s/^version = .*/version = \"${RELEASE_VERSION}\"/" pyproject.toml
 
           # README badge: URL slug + alt text
           sed -Ei "s|EnergyPlus-[0-9.]+-orange|EnergyPlus-${MAJOR_MINOR}-orange|" README.md
@@ -133,11 +137,15 @@ jobs:
           sed -Ei "s|✅ [0-9]+ ref groups|✅ ${REF_COUNT} ref groups|" README.md
           sed -Ei "s|✅ [0-9]+ properties|✅ ${PROP_COUNT} properties|" README.md
 
-      - name: Publish to latest branch and tag
+      # Same branch layout as release-version.yml: one release/ep-X.Y.Z branch
+      # per EnergyPlus version, which the Docs workflow builds into the site.
+      - name: Publish to release branch and tag
         id: push
         if: steps.check.outputs.skip == 'false'
         run: |
           EP_VERSION="${{ steps.ep.outputs.version }}"
+          TAG="v${{ steps.check.outputs.release_version }}"
+          BRANCH="release/ep-${EP_VERSION}"
 
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
@@ -145,13 +153,11 @@ jobs:
           # Capture codegen + metadata changes before switching branch
           git stash push --include-untracked -m "sync-${EP_VERSION}"
 
-          # Rebase latest on top of the triggering branch, then re-apply the stash
-          if git ls-remote --exit-code --heads origin latest > /dev/null; then
-            git fetch origin latest
-            git switch -C latest origin/${{ github.ref_name }}
-          else
-            git switch -C latest
+          # Rebuild the EP support branch on top of the triggering branch
+          if git ls-remote --exit-code --heads origin "$BRANCH" > /dev/null; then
+            git fetch origin "$BRANCH"
           fi
+          git switch -C "$BRANCH" origin/${{ github.ref_name }}
 
           git stash pop
 
@@ -162,11 +168,11 @@ jobs:
             exit 0
           fi
 
-          git commit -m "feat(models): sync to EnergyPlus ${EP_VERSION}"
-          git tag -a "v${EP_VERSION}" -m "EnergyPlus ${EP_VERSION} models"
+          git commit -m "feat(models): sync ${TAG} to EnergyPlus ${EP_VERSION}"
+          git tag -a "$TAG" -m "idfpy ${TAG} (EnergyPlus ${EP_VERSION})"
 
-          git push origin latest --force-with-lease
-          git push origin "v${EP_VERSION}"
+          git push origin "$BRANCH" --force-with-lease
+          git push origin "$TAG"
 
           echo "updated=true" >> "$GITHUB_OUTPUT"
 
@@ -187,7 +193,7 @@ jobs:
           BRANCH="chore/sync-readme"
           TITLE="docs: sync README for EnergyPlus ${EP_VERSION}"
 
-          # README on latest (HEAD) already has the sed-updated content
+          # README on the release branch (HEAD) already has the sed-updated content
           cp README.md /tmp/README.new
 
           git fetch origin master
@@ -207,7 +213,7 @@ jobs:
           Auto-generated by the \`Sync EnergyPlus\` workflow.
 
           Updates README badges, version line, and counts to match EnergyPlus ${EP_VERSION}.
-          Only \`README.md\` is touched — models and codegen products stay on the \`latest\` branch.
+          Only \`README.md\` is touched — models and codegen products stay on the \`release/ep-${EP_VERSION}\` branch.
           EOF
           )
 

idfpy-25.2.4/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.lock
+
+.claude/
+
+_dev/
+
+# Documentation build
+_site/
+site/
+docs/reference/
+.zensical-build.yml
+.cache/

{idfpy-25.2.2 → idfpy-25.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: idfpy
-Version: 25.2.2
+Version: 25.2.4
 Summary: Type-safe Pydantic models for all EnergyPlus IDF objects
 Project-URL: Repository, https://github.com/ITOTI-Y/idfpy
 Project-URL: Issues, https://github.com/ITOTI-Y/idfpy/issues
@@ -26,18 +26,19 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/idfpy)](https://pypi.org/project/idfpy/)
 [![Python 3.12+](https://img.shields.io/pypi/pyversions/idfpy)](https://pypi.org/project/idfpy/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![EnergyPlus 26.1](https://img.shields.io/badge/EnergyPlus-26.1-orange)](https://energyplus.net/)
+[![EnergyPlus 26.2](https://img.shields.io/badge/EnergyPlus-26.2-orange)](https://energyplus.net/)
 [![Autoupdate](https://github.com/ITOTI-Y/idfpy/actions/workflows/sync-energyplus.yml/badge.svg)](https://github.com/ITOTI-Y/idfpy/actions/workflows/sync-energyplus.yml)
+[![Docs](https://github.com/ITOTI-Y/idfpy/actions/workflows/docs.yml/badge.svg)](https://itoti-y.github.io/idfpy/)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/itoti-y/idfpy)
 
 Type-safe [Pydantic](https://docs.pydantic.dev/) models for **all** [EnergyPlus](https://energyplus.net/) IDF object types, plus IDF file read/write and simulation execution, optimized for LLM tool calling and IDE auto-completion.
 
-Auto-generated from `Energy+.schema.epJSON` version **26.1.0**.
+Auto-generated from `Energy+.schema.epJSON` version **26.2.0**.
 
 ## Features
 
-- **859 object types** as Pydantic v2 models with full validation
-- **275 reference types** with cross-object validation
+- **881 object types** as Pydantic v2 models with full validation
+- **287 reference types** with cross-object validation
 - **Forward navigation** — `surface.zone` resolves one reference field; `surface.referenced()` returns every referenced object
 - **Reverse navigation** — `zone.referencing("Lights")` finds all objects that reference a given object
 - **Reference validation** — `idf.validate()` batch-checks all cross-object references for existence and type compatibility
@@ -57,8 +58,8 @@ Auto-generated from `Energy+.schema.epJSON` version **26.1.0**.
 | No EnergyPlus IDD required at runtime | ✅ | ❌ |
 | Type-safe field validation | ✅ Pydantic v2 | ❌ |
 | epJSON read/write | ✅ | ❌ |
-| Cross-reference validation | ✅ 275 ref groups | ❌ |
-| Forward/reverse navigation | ✅ 2849 properties | ❌ |
+| Cross-reference validation | ✅ 287 ref groups | ❌ |
+| Forward/reverse navigation | ✅ 2921 properties | ❌ |
 | Surface geometry (area/normal) | ✅ ext plugin | ❌ |
 | `to_dict()` / `from_dict()` for LLM | ✅ | ❌ |
 | Dependencies | 4 (pydantic, jinja2, loguru, typer) | 12+ (lxml, pyparsing...) |

{idfpy-25.2.2 → idfpy-25.2.4}/README.md

@@ -3,18 +3,19 @@
 [![PyPI](https://img.shields.io/pypi/v/idfpy)](https://pypi.org/project/idfpy/)
 [![Python 3.12+](https://img.shields.io/pypi/pyversions/idfpy)](https://pypi.org/project/idfpy/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![EnergyPlus 26.1](https://img.shields.io/badge/EnergyPlus-26.1-orange)](https://energyplus.net/)
+[![EnergyPlus 26.2](https://img.shields.io/badge/EnergyPlus-26.2-orange)](https://energyplus.net/)
 [![Autoupdate](https://github.com/ITOTI-Y/idfpy/actions/workflows/sync-energyplus.yml/badge.svg)](https://github.com/ITOTI-Y/idfpy/actions/workflows/sync-energyplus.yml)
+[![Docs](https://github.com/ITOTI-Y/idfpy/actions/workflows/docs.yml/badge.svg)](https://itoti-y.github.io/idfpy/)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/itoti-y/idfpy)
 
 Type-safe [Pydantic](https://docs.pydantic.dev/) models for **all** [EnergyPlus](https://energyplus.net/) IDF object types, plus IDF file read/write and simulation execution, optimized for LLM tool calling and IDE auto-completion.
 
-Auto-generated from `Energy+.schema.epJSON` version **26.1.0**.
+Auto-generated from `Energy+.schema.epJSON` version **26.2.0**.
 
 ## Features
 
-- **859 object types** as Pydantic v2 models with full validation
-- **275 reference types** with cross-object validation
+- **881 object types** as Pydantic v2 models with full validation
+- **287 reference types** with cross-object validation
 - **Forward navigation** — `surface.zone` resolves one reference field; `surface.referenced()` returns every referenced object
 - **Reverse navigation** — `zone.referencing("Lights")` finds all objects that reference a given object
 - **Reference validation** — `idf.validate()` batch-checks all cross-object references for existence and type compatibility
@@ -34,8 +35,8 @@ Auto-generated from `Energy+.schema.epJSON` version **26.1.0**.
 | No EnergyPlus IDD required at runtime | ✅ | ❌ |
 | Type-safe field validation | ✅ Pydantic v2 | ❌ |
 | epJSON read/write | ✅ | ❌ |
-| Cross-reference validation | ✅ 275 ref groups | ❌ |
-| Forward/reverse navigation | ✅ 2849 properties | ❌ |
+| Cross-reference validation | ✅ 287 ref groups | ❌ |
+| Forward/reverse navigation | ✅ 2921 properties | ❌ |
 | Surface geometry (area/normal) | ✅ ext plugin | ❌ |
 | `to_dict()` / `from_dict()` for LLM | ✅ | ❌ |
 | Dependencies | 4 (pydantic, jinja2, loguru, typer) | 12+ (lxml, pyparsing...) |

idfpy-25.2.4/docs/api/ext.md

@@ -0,0 +1,28 @@
+# Extensions
+
+Mixins injected into generated models. See [Extensions](../guides/extensions.md).
+
+## Geometry
+
+::: idfpy.ext.geometry.mixins._BaseGeometryMixin
+    options:
+      heading: Surface geometry
+      heading_level: 3
+      show_bases: false
+
+::: idfpy.ext.geometry.functions
+    options:
+      heading: Geometry functions
+      heading_level: 3
+
+## Construction
+
+::: idfpy.ext.construction.mixins.ConstructionLayersMixin
+    options:
+      heading: ConstructionLayersMixin
+      heading_level: 3
+
+::: idfpy.ext.construction.functions
+    options:
+      heading: Construction functions
+      heading_level: 3

idfpy-25.2.4/docs/api/idf.md

@@ -0,0 +1,6 @@
+# IDF
+
+The container for a whole EnergyPlus model. See
+[Files and dictionaries](../guides/files.md) for a guided tour.
+
+::: idfpy.idf.IDF

idfpy-25.2.4/docs/api/models.md

@@ -0,0 +1,26 @@
+# Models and errors
+
+All generated object models derive from `IDFBaseModel`. Their fields are
+documented per object type in the [object reference](../reference/index.md).
+
+::: idfpy.models._base.IDFBaseModel
+    options:
+      show_root_full_path: false
+      heading: IDFBaseModel
+
+## Errors
+
+::: idfpy.models._errors.UnknownObjectTypeError
+    options:
+      heading: UnknownObjectTypeError
+      heading_level: 3
+
+::: idfpy.models._errors.RefError
+    options:
+      heading: RefError
+      heading_level: 3
+
+::: idfpy.models._errors.RefValidationError
+    options:
+      heading: RefValidationError
+      heading_level: 3

idfpy-25.2.4/docs/api/sim.md

@@ -0,0 +1,15 @@
+# Simulation
+
+See [Running simulations](../guides/simulation.md) for examples.
+
+::: idfpy.sim
+    options:
+      show_root_heading: false
+      members:
+        - simulate
+        - simulate_batch
+        - async_simulate
+        - async_simulate_batch
+        - SimJob
+        - SimResult
+        - ErrSummary

idfpy-25.2.4/docs/getting-started.md

@@ -0,0 +1,69 @@
+# Getting started
+
+## Installation
+
+idfpy needs Python 3.12 or newer. EnergyPlus itself is only required for
+running simulations; reading, editing and validating models works without it.
+
+=== "pip"
+
+    ```bash
+    pip install "idfpy==26.2.*"
+    ```
+
+=== "uv"
+
+    ```bash
+    uv add "idfpy==26.2.*"
+    ```
+
+Pick the idfpy series that matches the EnergyPlus version of your models.
+The installed version reports the EnergyPlus schema it was generated from:
+
+```python
+from idfpy import IDF
+
+IDF().version  # '26.2'
+```
+
+## Load, edit, save
+
+```python
+from pathlib import Path
+
+from idfpy import IDF
+from idfpy.models import Zone
+
+idf = IDF.load(Path('existing.idf'))  # format detected from the extension
+
+zone = idf.get(Zone, 'Zone1')  # typed as Zone | None
+zone.multiplier = 2  # validated on assignment
+
+idf.save(Path('modified.idf'))
+```
+
+Query methods accept the model class, its Python class name
+(`'BuildingSurfaceDetailed'`) or the EnergyPlus type name
+(`'BuildingSurface:Detailed'`). Passing the class keeps precise types in your
+editor.
+
+## Run a simulation
+
+```python
+from pathlib import Path
+
+from idfpy.sim import simulate
+
+result = simulate(
+    Path('modified.idf'),
+    weather=Path('USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw'),
+    output_dir=Path('results'),
+)
+print(result.success, result.err.severe_count if result.err else None)
+```
+
+## Where next
+
+- [Files and dictionaries](guides/files.md) covers every way in and out of an `IDF`.
+- [Navigating references](guides/navigation.md) shows how objects point at each other.
+- The [object reference](reference/index.md) lists every field of every object type.

idfpy-25.2.4/docs/guides/cli.md

@@ -0,0 +1,33 @@
+# Command line
+
+Installing idfpy provides the `idfpy` command.
+
+## `idfpy run`
+
+Runs one EnergyPlus simulation and exits with the EnergyPlus return code.
+
+```bash
+idfpy run --idf model.idf --weather weather.epw --output results --readvars
+```
+
+| Option | Short | Description |
+|---|---|---|
+| `--idf` | `-i` | IDF file to simulate |
+| `--weather` | `-w` | EPW weather file |
+| `--output` | `-o` | Output directory, defaults to the IDF file's directory |
+| `--readvars` | `-r` | Convert ESO output to CSV with ReadVarsESO |
+| `--output-prefix` | `-p` | Prefix of the output file names |
+
+## `idfpy codegen`
+
+Regenerates the models from an EnergyPlus schema. You only need this when
+developing idfpy or adding an [extension](extensions.md#writing-a-plugin).
+
+```bash
+idfpy codegen --schema /path/to/Energy+.schema.epJSON --output idfpy/models
+```
+
+| Option | Short | Description |
+|---|---|---|
+| `--schema` | `-s` | Path to `Energy+.schema.epJSON` |
+| `--output` | `-o` | Output directory, defaults to `idfpy/models` |

idfpy-25.2.4/docs/guides/extensions.md

@@ -0,0 +1,63 @@
+# Extensions
+
+Extensions add computed properties to generated models. They are mixed into
+the model classes at code generation time, so editors auto-complete them like
+ordinary fields.
+
+## Geometry
+
+Surface objects gain geometry computed from their vertices with Newell's
+method:
+
+```python
+surface = idf.get('BuildingSurface:Detailed', 'Wall1')
+
+surface.area  # 30.0, in m²
+surface.normal  # (0.0, -1.0, 0.0), outward unit normal
+surface.centroid  # (5.0, 0.0, 1.5)
+surface.tilt  # 90.0, degrees from horizontal
+surface.azimuth  # 180.0, degrees clockwise from north
+surface.perimeter
+surface.bounding_box
+surface.is_convex
+surface.vertices_as_tuples  # [(0, 0, 3), (0, 0, 0), (10, 0, 0), (10, 0, 3)]
+```
+
+Supported types: `BuildingSurface:Detailed`, `FenestrationSurface:Detailed`,
+`Floor:Detailed`, `RoofCeiling:Detailed`, `Wall:Detailed`,
+`Shading:Building:Detailed`, `Shading:Site:Detailed` and
+`Shading:Zone:Detailed`.
+
+## Constructions
+
+`Construction` gains `layers`, `is_window_construction` and
+`is_opaque_construction`; see [Navigating references](navigation.md#constructions-and-layers).
+
+## Writing a plugin
+
+An extension is a sub-package of `idfpy.ext` that exposes `MIXIN_MAP`,
+mapping generated class names to mixin classes:
+
+```python
+# idfpy/ext/thermal/__init__.py
+from .mixins import ThermalPropertyMixin
+
+MIXIN_MAP: dict[str, type] = {
+    'BuildingSurfaceDetailed': ThermalPropertyMixin,
+}
+```
+
+```python
+# idfpy/ext/thermal/mixins.py
+class ThermalPropertyMixin:
+    @property
+    def u_value(self) -> float:
+        """U-value of the surface construction, in W/(m²·K)."""
+        ...
+```
+
+Regenerate the models so the code generator injects the mixin:
+
+```bash
+idfpy codegen --schema Energy+.schema.epJSON --output idfpy/models
+```

idfpy-25.2.4/docs/guides/files.md

@@ -0,0 +1,85 @@
+# Files and dictionaries
+
+An `IDF` is a container of model objects keyed by object type and name. It
+reads and writes both the classic IDF text format and epJSON.
+
+## Loading and saving
+
+```python
+from pathlib import Path
+
+from idfpy import IDF
+
+idf = IDF.load(Path('model.idf'))  # IDF text
+idf = IDF.load(Path('model.epjson'))  # epJSON, chosen by extension
+
+idf.save(Path('out.idf'))  # default: IDF text
+idf.save(Path('out.epjson'), output_type='epjson')
+```
+
+## Adding, querying and removing objects
+
+```python
+from idfpy.models import Lights, Zone
+
+idf.add(Zone(name='Office'))  # ValueError if 'Office' already exists
+
+idf.get(Zone, 'Office')  # Zone | None
+idf.has('Zone', 'Office')  # True
+idf.all_of_type(Lights)  # dict[str, Lights], keyed by name
+list(idf.types())  # object types present in the model
+
+idf.remove(Zone, 'Office')  # also unregisters its references
+```
+
+Objects without a name field, such as `Version` or `Timestep`, receive an
+internal key automatically when added.
+
+Type names are checked: a misspelt type raises `UnknownObjectTypeError`
+instead of silently returning nothing. Pass `strict=False` to get `None` or an
+empty result instead.
+
+```python
+idf.get('BuildingSurface:detailed', 'Wall1')
+# UnknownObjectTypeError: Unknown object type: 'BuildingSurface:detailed'. ...
+```
+
+## Dictionaries for LLM tool calls
+
+`to_dict()` returns the epJSON structure, object type → object name →
+fields, which maps directly onto JSON tool arguments. Only fields that were
+set explicitly are included, which keeps the payload small.
+
+```python
+data = idf.to_dict()
+# {'Building': {'MyBuilding': {'north_axis': 0.0, 'terrain': 'Suburbs'}},
+#  'Zone': {'Zone1': {'multiplier': 2}}, ...}
+
+idf = IDF.from_dict(data)
+```
+
+`merge_dict()` applies a partial dictionary to an existing model. The merge is
+atomic: every object is validated before anything changes, so a rejected tool
+call leaves the model untouched.
+
+```python
+idf.merge_dict(
+    {'Zone': {'Zone2': {'multiplier': 3}}},
+    on_conflict='replace',  # 'raise' (default), 'replace' or 'skip'
+)
+```
+
+Field names may use either the Python `snake_case` names or the original
+schema keys.
+
+## Logging
+
+idfpy logs through Loguru. Messages at `INFO` and above are visible by
+default; per-object progress uses the `TRACE` level and needs an explicit
+sink:
+
+```python
+from loguru import logger
+
+logger.add('idfpy.log', level='TRACE')
+```