idfkit 0.6.4__tar.gz → 0.7.0__tar.gz

{idfkit-0.6.4 → idfkit-0.7.0}/.vscode/settings.json

@@ -22,5 +22,12 @@
     "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
     "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format",
     "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
+  ],
+  "python-envs.pythonProjects": [
+    {
+      "path": ".",
+      "envManager": "ms-python.python:venv",
+      "packageManager": "ms-python.python:pip"
+    }
   ]
 }

{idfkit-0.6.4 → idfkit-0.7.0}/AGENTS.md

@@ -177,7 +177,7 @@ idfkit searches for EnergyPlus in this order (see `src/idfkit/simulation/config.
 4. Platform default directories (newest version first):
    - Linux: `~/.local/EnergyPlus-*`, `~/EnergyPlus-*`, `/usr/local/EnergyPlus-*`, `/opt/EnergyPlus-*`
    - macOS: `~/Applications/EnergyPlus-*`, `/Applications/EnergyPlus-*`
-   - Windows: `%ProgramFiles%/EnergyPlus-*`
+   - Windows: `%ProgramFiles%/EnergyPlus-*`, `%SystemDrive%\EnergyPlusV*` (e.g. `C:\EnergyPlusV25-2-0`)
 
 ### Verifying the Installation
 

{idfkit-0.6.4 → idfkit-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idfkit
-Version: 0.6.4
+Version: 0.7.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

idfkit-0.7.0/docs/api/migration.md

@@ -0,0 +1,119 @@
+# Migration API
+
+Forward-migrate IDF models across EnergyPlus versions by orchestrating the
+`Transition-VX-to-VY` binaries shipped in `PreProcess/IDFVersionUpdater`.
+
+## migrate
+
+::: idfkit.migration.runner.migrate
+    options:
+      show_root_heading: true
+      show_source: true
+
+## async_migrate
+
+::: idfkit.migration.async_runner.async_migrate
+    options:
+      show_root_heading: true
+      show_source: true
+
+## MigrationReport
+
+::: idfkit.migration.report.MigrationReport
+    options:
+      show_root_heading: true
+      show_source: true
+      members:
+        - migrated_model
+        - source_version
+        - target_version
+        - requested_target
+        - steps
+        - diff
+        - success
+        - completed_steps
+        - failed_step
+        - summary
+
+## MigrationStep
+
+::: idfkit.migration.report.MigrationStep
+    options:
+      show_root_heading: true
+      show_source: true
+
+## MigrationDiff
+
+::: idfkit.migration.report.MigrationDiff
+    options:
+      show_root_heading: true
+      show_source: true
+      members:
+        - added_object_types
+        - removed_object_types
+        - object_count_delta
+        - field_changes
+        - is_empty
+
+## FieldDelta
+
+::: idfkit.migration.report.FieldDelta
+    options:
+      show_root_heading: true
+      show_source: true
+
+## MigrationProgress
+
+::: idfkit.migration.progress.MigrationProgress
+    options:
+      show_root_heading: true
+      show_source: true
+
+## Migrator
+
+::: idfkit.migration.protocol.Migrator
+    options:
+      show_root_heading: true
+      show_source: true
+
+## AsyncMigrator
+
+::: idfkit.migration.protocol.AsyncMigrator
+    options:
+      show_root_heading: true
+      show_source: true
+
+## MigrationStepResult
+
+::: idfkit.migration.protocol.MigrationStepResult
+    options:
+      show_root_heading: true
+      show_source: true
+
+## SubprocessMigrator
+
+::: idfkit.migration.subprocess_backend.SubprocessMigrator
+    options:
+      show_root_heading: true
+      show_source: true
+
+## AsyncSubprocessMigrator
+
+::: idfkit.migration.async_subprocess_backend.AsyncSubprocessMigrator
+    options:
+      show_root_heading: true
+      show_source: true
+
+## plan_migration_chain
+
+::: idfkit.migration.chain.plan_migration_chain
+    options:
+      show_root_heading: true
+      show_source: true
+
+## document_diff
+
+::: idfkit.migration.diff.document_diff
+    options:
+      show_root_heading: true
+      show_source: true

{idfkit-0.6.4 → idfkit-0.7.0}/docs/api/simulation/results.md

@@ -30,6 +30,7 @@ Simulation result container and output file access.
         - html_path
         - rdd_path
         - mdd_path
+        - migration_report
         - from_directory
 
 ## ErrorReport

{idfkit-0.6.4 → idfkit-0.7.0}/docs/concepts/version-compatibility.md

@@ -9,6 +9,15 @@ The linter parses Python source files using the AST (no code execution) and
 compares extracted string literals against the bundled epJSON schemas for
 different EnergyPlus versions.
 
+!!! tip "Static linting vs. runtime migration"
+    The compatibility linter described here flags cross-version breakage
+    *statically* — it tells you which lines of your code reference object
+    types or choice values that won't exist in another EnergyPlus version.
+    To actually upgrade an existing IDF model, see
+    [Migrating Versions](../simulation/migrating-versions.md), which uses
+    `idfkit.migrate()` to forward-migrate models through the
+    `IDFVersionUpdater` transition binaries.
+
 ## What it detects
 
 | Code | Description |

{idfkit-0.6.4 → idfkit-0.7.0}/docs/getting-started/quick-start.md

@@ -105,5 +105,6 @@ unmodified objects:
 
 - [Core Tutorial](core-tutorial.ipynb) - Complete interactive walkthrough
 - [Simulation Guide](../simulation/index.md) - Deep dive into simulation features
+- [Migrating Versions](../simulation/migrating-versions.md) - Move models forward across EnergyPlus releases
 - [Weather Guide](../weather/index.md) - Weather station search and design days
 - [API Reference](../api/document.md) - Full API documentation

{idfkit-0.6.4 → idfkit-0.7.0}/docs/index.md

@@ -49,6 +49,7 @@ pip install idfkit
 <span class="chip">:material-play-circle-outline: Simulation</span>
 <span class="chip">:material-weather-cloudy: Weather data</span>
 <span class="chip">:material-history: v8.9 -- v25.2</span>
+<span class="chip">:material-update: Version migration</span>
 
 </div>
 
@@ -134,5 +135,6 @@ pip install idfkit
 |------|-------------|
 | [Core Tutorial](getting-started/core-tutorial.ipynb) | Interactive notebook covering basic, advanced, and expert usage |
 | [Migrating from eppy](migration.md) | Side-by-side comparison of eppy and idfkit APIs |
+| [Migrating Versions](simulation/migrating-versions.md) | Forward-migrate IDF models across EnergyPlus releases |
 | [Benchmarks](benchmarks.md) | Performance comparison against eppy and other tools |
 | [Troubleshooting](troubleshooting/errors.md) | Common errors and solutions |

{idfkit-0.6.4 → idfkit-0.7.0}/docs/simulation/async.md

@@ -27,6 +27,10 @@ returns the same `SimulationResult`.  The only difference is that EnergyPlus
 runs as an `asyncio` subprocess, so the event loop is free to do other work
 while waiting.
 
+The `auto_migrate` flag and `result.migration_report` work identically to
+the sync API. For pure async migration without simulating, see
+[`async_migrate()`][idfkit.migration.async_runner.async_migrate].
+
 ## Async Batch Processing
 
 `async_simulate_batch()` mirrors `simulate_batch()` but uses an
@@ -194,10 +198,14 @@ don't block the event loop.  This is transparent — no user action required.
 Error handling is identical to the sync API:
 
 ```python
-from idfkit.exceptions import SimulationError
+from idfkit.exceptions import SimulationError, VersionMismatchError
 
 try:
     result = await async_simulate(model, weather, timeout=60)
+except VersionMismatchError as e:
+    # Retry with auto_migrate, or migrate explicitly first.
+    print(f"Model is {e.current}, need {e.target}")
+    result = await async_simulate(model, weather, timeout=60, auto_migrate=True)
 except SimulationError as e:
     if e.exit_code is None:
         print("Simulation timed out")
@@ -212,4 +220,5 @@ never raises due to a single job failing.
 
 - [Running Simulations](running.md) — Sync simulation guide
 - [Batch Processing](batch.md) — Sync batch guide
+- [Migrating Versions](migrating-versions.md) — Forward-migrate models with `auto_migrate` or `async_migrate`
 - [Simulation Architecture](../concepts/simulation-architecture.md) — Design decisions

{idfkit-0.6.4 → idfkit-0.7.0}/docs/simulation/errors.md

@@ -67,6 +67,28 @@ The `simulate()` function raises `SimulationError` for certain failures:
 | EnergyPlus not found | `EnergyPlusNotFoundError` |
 | Timeout exceeded | `SimulationError` (exit_code=None) |
 | OS error starting process | `SimulationError` |
+| Model version differs from installed EnergyPlus | `VersionMismatchError` |
+
+### Version Mismatch
+
+By default `simulate()` refuses to run when `model.version` doesn't match
+the installed EnergyPlus version, raising
+[`VersionMismatchError`][idfkit.exceptions.VersionMismatchError] with a
+suggested migration chain. Two ways to resolve it:
+
+```python
+# Option A: let simulate() forward-migrate transparently
+result = simulate(model, weather, auto_migrate=True)
+print(result.migration_report.summary())
+
+# Option B: migrate explicitly first, inspect the report, then simulate
+from idfkit import migrate
+report = migrate(model, target_version=(25, 2, 0))
+result = simulate(report.migrated_model, weather)
+```
+
+Backward migration (installed EnergyPlus older than the model) is never
+attempted and always raises. See [Migrating Versions](migrating-versions.md).
 
 ### Timeout Handling
 
@@ -179,4 +201,5 @@ Or from string:
 
 - [Running Simulations](running.md) — Basic simulation guide
 - [Parsing Results](results.md) — Working with SimulationResult
+- [Migrating Versions](migrating-versions.md) — Resolving `VersionMismatchError`
 - [Troubleshooting](../troubleshooting/errors.md) — Common error solutions

idfkit-0.7.0/docs/simulation/migrating-versions.md

@@ -0,0 +1,86 @@
+# Migrating Versions
+
+EnergyPlus ships a new release roughly twice a year, and each release can
+rename objects, drop fields, or alter defaults. idfkit's
+[`migrate()`][idfkit.migration.runner.migrate] orchestrates the
+`Transition-VX-to-VY` binaries shipped in `PreProcess/IDFVersionUpdater` to
+forward-migrate an IDF model across one or more version steps in a single
+call.
+
+There are two ways to migrate a model:
+
+| Approach | When to use |
+|----------|-------------|
+| Explicit `migrate(model, target_version=...)` | You want to inspect the migrated model, the structural diff, or per-step diagnostics before doing anything else. |
+| `simulate(model, ..., auto_migrate=True)` | You want to run a simulation against the installed EnergyPlus and don't care about the intermediate steps. |
+
+!!! note "Forward only"
+    EnergyPlus does not ship reverse transition binaries. Asking to migrate
+    *backwards* (target older than source) always raises
+    [`VersionMismatchError`][idfkit.exceptions.VersionMismatchError] with
+    `direction == "backward"`.
+
+## Explicit Migration
+
+Call [`migrate()`][idfkit.migration.runner.migrate] directly when you need
+the migrated [`IDFDocument`][idfkit.document.IDFDocument] in hand:
+
+```python
+--8<-- "docs/snippets/migration_versions/quick_start.py:example"
+```
+
+The returned [`MigrationReport`][idfkit.migration.report.MigrationReport]
+exposes:
+
+| Attribute | Description |
+|-----------|-------------|
+| `migrated_model` | The migrated `IDFDocument` (`None` on a no-op migration where source equals target). |
+| `source_version` / `target_version` | The version range actually traversed. |
+| `requested_target` | The version originally requested — differs from `target_version` only on partial failures. |
+| `steps` | Ordered tuple of [`MigrationStep`][idfkit.migration.report.MigrationStep] records with stdout/stderr/audit per binary invocation. |
+| `diff` | Structural [`MigrationDiff`][idfkit.migration.report.MigrationDiff] — added/removed object types, count deltas, and per-type field changes. |
+| `success` | `True` only when every step succeeded. |
+| `summary()` | Short human-readable summary suitable for logs or CLI. |
+
+## Transparent Migration During `simulate()`
+
+When you only want a simulation result, pass `auto_migrate=True` and
+`simulate()` will forward-migrate the model on your behalf if the
+installed EnergyPlus version differs:
+
+```python
+--8<-- "docs/snippets/migration_versions/auto_migrate_simulate.py:example"
+```
+
+The resulting [`SimulationResult.migration_report`][idfkit.simulation.result.SimulationResult.migration_report]
+is populated whenever a migration ran, and `None` otherwise. Without
+`auto_migrate=True`, a version mismatch raises
+[`VersionMismatchError`][idfkit.exceptions.VersionMismatchError] before the
+simulation starts.
+
+## Async Migration
+
+Both APIs have async counterparts with identical semantics:
+
+- [`async_migrate()`][idfkit.migration.async_runner.async_migrate] — non-blocking
+  equivalent of `migrate()`, useful inside FastAPI handlers or other async
+  contexts where you want only the migration.
+- [`async_simulate(..., auto_migrate=True)`][idfkit.simulation.async_runner.async_simulate]
+  — accepts the same `auto_migrate` flag and populates `migration_report`
+  on the returned `SimulationResult`.
+
+## Partial Failures
+
+If a transition step fails midway,
+[`MigrationError`][idfkit.exceptions.MigrationError] is raised. The
+exception carries `from_version`, `to_version`, the binary's `exit_code`
+and `stderr`, and `completed_steps` — the prefix of `(from, to)` pairs that
+ran successfully — so you can recover partial progress or report exactly
+which transition broke.
+
+## See Also
+
+- [Migration API](../api/migration.md) — full reference for `migrate`, `MigrationReport`, and the `Migrator` protocol.
+- [Version Compatibility](../concepts/version-compatibility.md) — the *static* `idfkit check` linter for catching cross-version breakage in your code before you migrate.
+- [Running Simulations](running.md) — full `simulate()` parameter reference.
+- [Error Handling](errors.md) — handling `VersionMismatchError` from `simulate()`.

{idfkit-0.6.4 → idfkit-0.7.0}/docs/simulation/running.md

@@ -105,6 +105,7 @@ def simulate(
     cache: SimulationCache | None = None,
     fs: FileSystem | None = None,
     on_progress: Callable[[SimulationProgress], Any] | Literal["tqdm"] | None = None,
+    auto_migrate: bool = False,
 ) -> SimulationResult:
 ```
 
@@ -134,6 +135,7 @@ def simulate(
 | `cache` | `None` | Simulation cache for result reuse |
 | `fs` | `None` | File system backend for cloud storage |
 | `on_progress` | `None` | Callback or `"tqdm"` for real-time progress updates |
+| `auto_migrate` | `False` | Forward-migrate the model when its version differs from the installed EnergyPlus (see [Migrating Versions](migrating-versions.md)) |
 
 ## EnergyPlus Discovery
 
@@ -240,8 +242,19 @@ Enable content-addressed caching to avoid redundant simulations:
 
 See [Caching](caching.md) for details.
 
+## Version Migration
+
+When `model.version` differs from the installed EnergyPlus,
+`simulate()` raises [`VersionMismatchError`][idfkit.exceptions.VersionMismatchError]
+by default. Pass `auto_migrate=True` to forward-migrate the model
+transparently before the run; the resulting
+[`MigrationReport`][idfkit.migration.report.MigrationReport] is attached to
+[`SimulationResult.migration_report`][idfkit.simulation.result.SimulationResult.migration_report].
+See [Migrating Versions](migrating-versions.md) for the full workflow.
+
 ## See Also
 
+- [Migrating Versions](migrating-versions.md) — Forward-migrate IDF models across EnergyPlus releases
 - [Progress Tracking](progress.md) — Real-time progress with `on_progress`
 - [Parsing Results](results.md) — Working with `SimulationResult`
 - [Batch Processing](batch.md) — Running multiple simulations

idfkit-0.7.0/docs/snippets/migration_versions/auto_migrate_simulate.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from idfkit import IDFDocument
+from idfkit.simulation import SimulationResult
+
+model: IDFDocument = ...  # type: ignore[assignment]
+result: SimulationResult = ...  # type: ignore[assignment]
+# --8<-- [start:example]
+from idfkit import load_idf
+from idfkit.simulation import simulate
+
+# Forward-migrate the model transparently before running.
+model = load_idf("old_building.idf")
+result = simulate(model, "weather.epw", design_day=True, auto_migrate=True)
+
+if result.migration_report is not None:
+    print(result.migration_report.summary())
+
+print(f"Simulation success: {result.success}")
+# --8<-- [end:example]

idfkit-0.7.0/docs/snippets/migration_versions/quick_start.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from idfkit import IDFDocument, MigrationReport
+
+model: IDFDocument = ...  # type: ignore[assignment]
+report: MigrationReport = ...  # type: ignore[assignment]
+# --8<-- [start:example]
+from idfkit import load_idf, migrate
+from idfkit.simulation import find_energyplus
+
+# Load an older IDF (e.g. v22.1.0) and migrate to the installed EnergyPlus.
+model = load_idf("old_building.idf")
+config = find_energyplus()
+
+report = migrate(model, target_version=config.version, energyplus=config)
+
+print(report.summary())
+
+migrated = report.migrated_model
+if migrated is not None:
+    print(f"Migrated model version: {migrated.version}")
+# --8<-- [end:example]

{idfkit-0.6.4 → idfkit-0.7.0}/docs/troubleshooting/errors.md

@@ -216,7 +216,7 @@ types, invalid bytes, or extra fields on non-extensible objects).
        doc = load_idf("file.idf", strict_parsing=False)
    ```
 
-### Version Mismatch
+### Unsupported Schema Version
 
 ```
 ValueError: Schema for version (99, 0, 0) not found
@@ -237,6 +237,39 @@ ValueError: Schema for version (99, 0, 0) not found
    doc = load_idf("file.idf", version=(24, 1, 0))
    ```
 
+### Simulation Version Mismatch
+
+```
+VersionMismatchError: Model version 22.1.0 does not match target EnergyPlus version 25.2.0.
+Migration chain: 22.1.0->22.2.0 -> 22.2.0->23.1.0 -> ... -> 25.1.0->25.2.0
+Call idfkit.migrate(model, target_version=...) to migrate explicitly.
+```
+
+**Cause:** `simulate()` was called with a model whose `version` differs
+from the installed EnergyPlus, and `auto_migrate` is `False` (the default).
+
+**Solutions:**
+
+1. Forward-migrate transparently inside `simulate()`:
+   ```python
+   result = simulate(model, weather, auto_migrate=True)
+   print(result.migration_report.summary())
+   ```
+
+2. Migrate explicitly first so you can inspect the diff:
+   ```python
+   from idfkit import migrate
+   report = migrate(model, target_version=(25, 2, 0))
+   result = simulate(report.migrated_model, weather)
+   ```
+
+!!! warning "Backward migration is not supported"
+    EnergyPlus ships no reverse transition binaries, so a model *newer*
+    than the installed EnergyPlus cannot be downgraded. Install a newer
+    EnergyPlus or load the model explicitly at an older version.
+
+See [Migrating Versions](../simulation/migrating-versions.md) for the full workflow.
+
 ## Performance Issues
 
 ### Slow Station Index Loading

{idfkit-0.6.4 → idfkit-0.7.0}/mkdocs.yml

@@ -38,6 +38,7 @@ nav:
     - Plotting: simulation/plotting.md
     - Output Discovery: simulation/output-discovery.md
     - Error Handling: simulation/errors.md
+    - Migrating Versions: simulation/migrating-versions.md
 
   - Schedules:
     - Overview: schedules/index.md
@@ -82,6 +83,7 @@ nav:
       - Cache: api/simulation/cache.md
       - Plotting: api/simulation/plotting.md
       - File Systems: api/simulation/fs.md
+    - Migration: api/migration.md
     - Schedules:
       - Overview: api/schedules/index.md
     - Weather:

{idfkit-0.6.4 → idfkit-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "idfkit"
-version = "v0.6.4"
+version = "0.7.0"
 description = "A fast, modern EnergyPlus IDF/epJSON parser with O(1) lookups and reference tracking"
 authors = [{ name = "Samuel Letellier-Duchesne", email = "developers@idfkit.com" }]
 readme = "README.md"
@@ -80,6 +80,7 @@ dev = [
     "types-aiobotocore-s3>=2.5",
     "boto3>=1.26",
     "aiobotocore>=2.5",
+    "plotly>=5.0",
 ]
 benchmark = [
     "eppy>=0.5.63",
@@ -130,6 +131,7 @@ reportUnknownParameterType = false
 reportOptionalMemberAccess = false
 reportMissingParameterType = false
 reportMissingImports = false
+reportMissingTypeStubs = false
 reportUntypedFunctionDecorator = false
 reportUntypedBaseClass = false
 reportMissingTypeArgument = false

{idfkit-0.6.4 → idfkit-0.7.0}/src/idfkit/__init__.py

@@ -46,6 +46,7 @@ from .exceptions import (
     IdfKitError,
     IDFParseError,
     InvalidFieldError,
+    MigrationError,
     NoDesignDaysError,
     ParseError,
     RangeError,
@@ -54,6 +55,7 @@ from .exceptions import (
     UnknownObjectTypeError,
     UnsupportedVersionError,
     ValidationFailedError,
+    VersionMismatchError,
     VersionNotFoundError,
 )
 
@@ -95,6 +97,9 @@ from .idf_parser import IDFParser, get_idf_version, parse_idf
 
 # Introspection
 from .introspection import FieldDescription, ObjectDescription
+
+# Migration
+from .migration import MigrationReport, async_migrate, migrate
 from .objects import IDFCollection, IDFObject
 
 # Reference graph
@@ -398,6 +403,8 @@ __all__ = [
     "IDFParser",
     "IdfKitError",
     "InvalidFieldError",
+    "MigrationError",
+    "MigrationReport",
     "NoDesignDaysError",
     "ObjectDescription",
     "ParseError",
@@ -413,12 +420,14 @@ __all__ = [
     "ValidationFailedError",
     "ValidationResult",
     "Vector3D",
+    "VersionMismatchError",
     "VersionNotFoundError",
     "ZoneFootprint",
     "ZonedBlock",
     "ZoningScheme",
     "__version__",
     "add_shading_block",
+    "async_migrate",
     "bounding_box",
     "calculate_surface_area",
     "calculate_surface_azimuth",
@@ -451,6 +460,7 @@ __all__ = [
     "link_horizontal_surfaces",
     "load_epjson",
     "load_idf",
+    "migrate",
     "new_document",
     "parse_epjson",
     "parse_idf",