Runner API¶

Core simulation execution functions.

simulate¶

`idfkit.simulation.runner.simulate(model, weather, *, output_dir=None, energyplus=None, expand_objects=True, annual=False, design_day=False, output_prefix='eplus', output_suffix='C', readvars=False, timeout=3600.0, preprocessor_timeout=None, extra_args=None, cache=None, fs=None, on_progress=None, auto_migrate=False)` ¶

Run an EnergyPlus simulation.

Creates an isolated run directory, writes the model, and executes EnergyPlus as a subprocess. The caller's model is not mutated.

When expand_objects is True (the default) and the model contains GroundHeatTransfer:Slab:* or GroundHeatTransfer:Basement:* objects, the Slab and/or Basement ground heat-transfer preprocessors are run automatically before simulation. This is equivalent to calling run_slab_preprocessor or run_basement_preprocessor individually, but happens transparently.

Parameters:

Name	Type	Description	Default
`model`	`IDFDocument`	The EnergyPlus model to simulate.	required
`weather`	`str \| Path`	Path to the weather file (.epw).	required
`output_dir`	`str \| Path \| None`	Directory for output files (default: auto temp dir).	`None`
`energyplus`	`EnergyPlusConfig \| None`	Pre-configured EnergyPlus installation. If None, uses find_energyplus for auto-discovery.	`None`
`expand_objects`	`bool`	Run ExpandObjects before simulation. When `True`, also runs the Slab and Basement ground heat-transfer preprocessors if the model contains the corresponding objects.	`True`
`annual`	`bool`	Run annual simulation (`-a` flag).	`False`
`design_day`	`bool`	Run design-day-only simulation (`-D` flag).	`False`
`output_prefix`	`str`	Prefix for output files (default "eplus").	`'eplus'`
`output_suffix`	`Literal['C', 'L', 'D']`	Output file naming suffix: `"C"` for combined table files (default), `"L"` for legacy separate table files, or `"D"` for timestamped separate files.	`'C'`
`readvars`	`bool`	Run ReadVarsESO after simulation (`-r` flag).	`False`
`timeout`	`float`	Maximum runtime in seconds (default 3600). Applied only to the main EnergyPlus subprocess; preprocessor stages (ExpandObjects, Slab, Basement) have an independent budget — see preprocessor_timeout.	`3600.0`
`preprocessor_timeout`	`float \| None`	Per-subprocess timeout (seconds) applied individually to ExpandObjects, Slab, and Basement when they run automatically. `None` (the default) consults the `IDFKIT_PREPROCESSOR_TIMEOUT` environment variable, falling back to 120 s. Independent of timeout — there is no shared wall-clock cap across the pipeline.	`None`
`extra_args`	`list[str] \| None`	Additional command-line arguments.	`None`
`cache`	`SimulationCache \| None`	Optional simulation cache for content-hash lookups.	`None`
`fs`	`FileSystem \| None`	Optional file system backend for storing results on remote storage (e.g., S3). When provided, `output_dir` is required and specifies the remote destination path. EnergyPlus runs locally in a temp directory; results are then uploaded to `output_dir` via fs after execution. Note The `fs` parameter handles output storage only. The `weather` file must be a local path — remote weather files are not automatically downloaded. For cloud workflows, download weather files first using WeatherDownloader or pre-stage them locally before calling `simulate()`.	`None`
`on_progress`	`Callable[[SimulationProgress], Any] \| Literal['tqdm'] \| None`	Optional callback invoked with a SimulationProgress event each time EnergyPlus emits a progress line (warmup iterations, simulation day changes, post-processing steps, etc.). Pass `"tqdm"` to use a built-in tqdm progress bar (requires `pip install idfkit[progress]`).	`None`
`auto_migrate`	`bool`	When `True` and `model.version` differs from the installed EnergyPlus version, forward-migrate the model before running the simulation. The resulting MigrationReport is attached to the returned SimulationResult.migration_report. Backward migration (installed EP older than the model) is never attempted and always raises VersionMismatchError.	`False`

Returns:

Type	Description
`SimulationResult`	SimulationResult with paths to output files.

Raises:

Type	Description
`SimulationError`	On timeout, OS error, or missing weather file.
`ExpandObjectsError`	If a preprocessing step (ExpandObjects, Slab, or Basement) fails during automatic preprocessing.
`EnergyPlusNotFoundError`	If EnergyPlus cannot be found.
`VersionMismatchError`	If `model.version` differs from the installed EnergyPlus version and auto_migrate is `False` — or if the model is newer than the installed EnergyPlus (backward migration is not supported).

Source code in idfkit/simulation/runner.py

def simulate(
    model: IDFDocument,
    weather: str | Path,
    *,
    output_dir: str | Path | None = None,
    energyplus: EnergyPlusConfig | None = None,
    expand_objects: bool = True,
    annual: bool = False,
    design_day: bool = False,
    output_prefix: str = "eplus",
    output_suffix: Literal["C", "L", "D"] = "C",
    readvars: bool = False,
    timeout: float = 3600.0,
    preprocessor_timeout: float | None = None,
    extra_args: list[str] | None = None,
    cache: SimulationCache | None = None,
    fs: FileSystem | None = None,
    on_progress: Callable[[SimulationProgress], Any] | Literal["tqdm"] | None = None,
    auto_migrate: bool = False,
) -> SimulationResult:
    """Run an EnergyPlus simulation.

    Creates an isolated run directory, writes the model, and executes
    EnergyPlus as a subprocess. The caller's model is not mutated.

    When *expand_objects* is ``True`` (the default) and the model contains
    ``GroundHeatTransfer:Slab:*`` or ``GroundHeatTransfer:Basement:*``
    objects, the Slab and/or Basement ground heat-transfer preprocessors
    are run automatically before simulation.  This is equivalent to
    calling [run_slab_preprocessor][idfkit.simulation.expand.run_slab_preprocessor] or
    [run_basement_preprocessor][idfkit.simulation.expand.run_basement_preprocessor]
    individually, but happens transparently.

    Args:
        model: The EnergyPlus model to simulate.
        weather: Path to the weather file (.epw).
        output_dir: Directory for output files (default: auto temp dir).
        energyplus: Pre-configured EnergyPlus installation. If None,
            uses [find_energyplus][idfkit.simulation.config.find_energyplus] for auto-discovery.
        expand_objects: Run ExpandObjects before simulation.  When
            ``True``, also runs the Slab and Basement ground heat-transfer
            preprocessors if the model contains the corresponding objects.
        annual: Run annual simulation (``-a`` flag).
        design_day: Run design-day-only simulation (``-D`` flag).
        output_prefix: Prefix for output files (default "eplus").
        output_suffix: Output file naming suffix: ``"C"`` for combined table
            files (default), ``"L"`` for legacy separate table files, or
            ``"D"`` for timestamped separate files.
        readvars: Run ReadVarsESO after simulation (``-r`` flag).
        timeout: Maximum runtime in seconds (default 3600).  Applied only
            to the main EnergyPlus subprocess; preprocessor stages
            (ExpandObjects, Slab, Basement) have an independent budget — see
            *preprocessor_timeout*.
        preprocessor_timeout: Per-subprocess timeout (seconds) applied
            individually to ExpandObjects, Slab, and Basement when they
            run automatically.  ``None`` (the default) consults the
            ``IDFKIT_PREPROCESSOR_TIMEOUT`` environment variable, falling
            back to 120 s.  Independent of *timeout* — there is no shared
            wall-clock cap across the pipeline.
        extra_args: Additional command-line arguments.
        cache: Optional simulation cache for content-hash lookups.
        fs: Optional file system backend for storing results on remote
            storage (e.g., S3). When provided, ``output_dir`` is required
            and specifies the remote destination path. EnergyPlus runs
            locally in a temp directory; results are then uploaded to
            ``output_dir`` via *fs* after execution.

            !!! note
                The ``fs`` parameter handles **output storage only**.
                The ``weather`` file must be a local path — remote weather
                files are not automatically downloaded. For cloud workflows,
                download weather files first using [WeatherDownloader][idfkit.weather.WeatherDownloader]
                or pre-stage them locally before calling ``simulate()``.
        on_progress: Optional callback invoked with a
            [SimulationProgress][idfkit.simulation.progress.SimulationProgress] event
            each time EnergyPlus emits a progress line (warmup iterations,
            simulation day changes, post-processing steps, etc.).  Pass
            ``"tqdm"`` to use a built-in tqdm progress bar (requires
            ``pip install idfkit[progress]``).
        auto_migrate: When ``True`` and ``model.version`` differs from the
            installed EnergyPlus version, forward-migrate the model before
            running the simulation. The resulting [MigrationReport][idfkit.migration.report.MigrationReport]
            is attached to the returned [SimulationResult.migration_report][idfkit.simulation.result.SimulationResult.migration_report].
            Backward migration (installed EP older than the model) is never
            attempted and always raises [VersionMismatchError][idfkit.exceptions.VersionMismatchError].

    Returns:
        SimulationResult with paths to output files.

    Raises:
        SimulationError: On timeout, OS error, or missing weather file.
        ExpandObjectsError: If a preprocessing step (ExpandObjects, Slab,
            or Basement) fails during automatic preprocessing.
        EnergyPlusNotFoundError: If EnergyPlus cannot be found.
        VersionMismatchError: If ``model.version`` differs from the installed
            EnergyPlus version and *auto_migrate* is ``False`` — or if the
            model is newer than the installed EnergyPlus (backward migration
            is not supported).
    """
    if fs is not None and output_dir is None:
        msg = "output_dir is required when using a file system backend"
        raise ValueError(msg)

    progress_cb, progress_cleanup = resolve_on_progress(on_progress)

    try:
        config = resolve_config(energyplus)
        logger.debug("EnergyPlus: %s (version %d.%d.%d)", config.executable, *config.version)
        weather_path = Path(weather).resolve()

        if not weather_path.is_file():
            msg = f"Weather file not found: {weather_path}"
            raise SimulationError(msg)

        sim_input_model, migration_report = resolve_version_mismatch(
            model=model,
            config=config,
            auto_migrate=auto_migrate,
        )

        logger.info("Starting simulation with weather %s", weather_path.name)

        cache_key: CacheKey | None = None
        if cache is not None:
            cache_key = cache.compute_key(
                sim_input_model,
                weather_path,
                expand_objects=expand_objects,
                annual=annual,
                design_day=design_day,
                output_suffix=output_suffix,
                readvars=readvars,
                extra_args=extra_args,
            )
            cached = cache.get(cache_key)
            if cached is not None:
                logger.debug("Cache hit for key %s", cache_key.hex_digest[:12])
                cached.migration_report = migration_report
                return cached
            logger.debug("Cache miss for key %s", cache_key.hex_digest[:12])

        # Copy model to avoid mutation
        sim_model = sim_input_model.copy()
        ensure_sql_output(sim_model)

        # Auto-preprocess ground heat-transfer objects when needed.
        sim_model, ep_expand = maybe_preprocess(
            sim_input_model,
            sim_model,
            config,
            weather_path,
            expand_objects,
            preprocessor_timeout=preprocessor_timeout,
        )

        # When using a remote fs, always run locally in a temp dir
        local_output_dir = None if fs is not None else output_dir
        run_dir = prepare_run_directory(local_output_dir, weather_path)
        idf_path = run_dir / "model.idf"

        from ..writers import write_idf

        write_idf(sim_model, idf_path)

        cmd = build_command(
            config=config,
            idf_path=idf_path,
            weather_path=run_dir / weather_path.name,
            output_dir=run_dir,
            output_prefix=output_prefix,
            output_suffix=output_suffix,
            expand_objects=ep_expand,
            annual=annual,
            design_day=design_day,
            readvars=readvars,
            extra_args=extra_args,
        )
        logger.debug("Command: %s", " ".join(cmd))

        start = time.monotonic()

        if progress_cb is not None:
            stdout, stderr, returncode = _run_with_progress(cmd, run_dir, timeout, start, progress_cb)
        else:
            stdout, stderr, returncode = _run_simple(cmd, run_dir, timeout, start)
    finally:
        if progress_cleanup is not None:
            progress_cleanup()

    elapsed = time.monotonic() - start

    if returncode != 0:
        logger.warning("Simulation exited with code %d in %.1fs", returncode, elapsed)
    else:
        logger.info("Simulation completed successfully in %.1fs", elapsed)

    if fs is not None:
        remote_dir = Path(str(output_dir))
        upload_results(run_dir, remote_dir, fs)
        result = SimulationResult(
            run_dir=remote_dir,
            success=returncode == 0,
            exit_code=returncode,
            stdout=stdout,
            stderr=stderr,
            runtime_seconds=elapsed,
            output_prefix=output_prefix,
            fs=fs,
            migration_report=migration_report,
        )
    else:
        result = SimulationResult(
            run_dir=run_dir,
            success=returncode == 0,
            exit_code=returncode,
            stdout=stdout,
            stderr=stderr,
            runtime_seconds=elapsed,
            output_prefix=output_prefix,
            migration_report=migration_report,
        )
    if cache is not None and cache_key is not None and result.success:
        cache.put(cache_key, result)
    return result

find_energyplus¶

`idfkit.simulation.config.find_energyplus(*, version=None, path=None)` ¶

Find an EnergyPlus installation.

Discovery order

Explicit path argument.
ENERGYPLUS_DIR environment variable.
energyplus on PATH (via shutil.which).
Platform-specific default directories (newest version first).

Parameters:

Name	Type	Description	Default
`version`	`tuple[int, int, int] \| str \| None`	Optional version filter. Accepts `(major, minor, patch)` tuple or a string like `"24.1.0"` or `"24.1"`.	`None`
`path`	`str \| Path \| None`	Explicit path to EnergyPlus install directory or executable.	`None`

Returns:

Type	Description
`EnergyPlusConfig`	Validated EnergyPlusConfig.

Raises:

Type	Description
`EnergyPlusNotFoundError`	If no matching installation is found.

Source code in idfkit/simulation/config.py

def find_energyplus(
    *,
    version: tuple[int, int, int] | str | None = None,
    path: str | Path | None = None,
) -> EnergyPlusConfig:
    """Find an EnergyPlus installation.

    Discovery order:
        1. Explicit *path* argument.
        2. ``ENERGYPLUS_DIR`` environment variable.
        3. ``energyplus`` on ``PATH`` (via [shutil.which][]).
        4. Platform-specific default directories (newest version first).

    Args:
        version: Optional version filter. Accepts ``(major, minor, patch)``
            tuple or a string like ``"24.1.0"`` or ``"24.1"``.
        path: Explicit path to EnergyPlus install directory or executable.

    Returns:
        Validated EnergyPlusConfig.

    Raises:
        EnergyPlusNotFoundError: If no matching installation is found.
    """
    target_version = normalize_version(version) if version is not None else None
    searched: list[str] = []

    # 1. Explicit path
    if path is not None:
        p = Path(path).resolve()
        searched.append(str(p))
        config = EnergyPlusConfig.from_path(p)
        if target_version is not None and config.version != target_version:
            raise EnergyPlusNotFoundError(searched)
        return config

    # 2-4. Try candidates from env var, PATH, and platform dirs
    for candidate in _discovery_candidates():
        searched.append(str(candidate))
        logger.debug("Trying candidate %s", candidate)
        result = _try_candidate(candidate, target_version)
        if result is not None:
            logger.info("Found EnergyPlus %d.%d.%d at %s", *result.version, result.install_dir)
            return result

    raise EnergyPlusNotFoundError(searched)

EnergyPlusConfig¶

`idfkit.simulation.config.EnergyPlusConfig` `dataclass` ¶

Validated EnergyPlus installation configuration.

Attributes:

Name	Type	Description
`executable`	`Path`	Path to the energyplus executable.
`version`	`tuple[int, int, int]`	Parsed version as (major, minor, patch).
`install_dir`	`Path`	Root installation directory.
`idd_path`	`Path`	Path to the Energy+.idd file.

Source code in idfkit/simulation/config.py

@dataclass(frozen=True, slots=True)
class EnergyPlusConfig:
    """Validated EnergyPlus installation configuration.

    Attributes:
        executable: Path to the energyplus executable.
        version: Parsed version as (major, minor, patch).
        install_dir: Root installation directory.
        idd_path: Path to the Energy+.idd file.
    """

    executable: Path
    version: tuple[int, int, int]
    install_dir: Path
    idd_path: Path

    @property
    def weather_dir(self) -> Path | None:
        """Path to the bundled WeatherData directory, if present."""
        d = self.install_dir / "WeatherData"
        return d if d.is_dir() else None

    @property
    def schema_path(self) -> Path | None:
        """Path to Energy+.schema.epJSON, if present."""
        p = self.install_dir / "Energy+.schema.epJSON"
        return p if p.is_file() else None

    @property
    def expand_objects_exe(self) -> Path | None:
        """Path to ExpandObjects executable, if present."""
        name = "ExpandObjects.exe" if platform.system() == "Windows" else "ExpandObjects"
        p = self.install_dir / name
        return p if p.is_file() else None

    @property
    def _preprocess_dir(self) -> Path:
        """Path to the PreProcess/GrndTempCalc directory."""
        return self.install_dir / "PreProcess" / "GrndTempCalc"

    @property
    def slab_exe(self) -> Path | None:
        """Path to the Slab ground heat-transfer preprocessor, if present."""
        name = "Slab.exe" if platform.system() == "Windows" else "Slab"
        p = self._preprocess_dir / name
        return p if p.is_file() else None

    @property
    def slab_idd(self) -> Path | None:
        """Path to SlabGHT.idd, if present."""
        p = self._preprocess_dir / "SlabGHT.idd"
        return p if p.is_file() else None

    @property
    def basement_exe(self) -> Path | None:
        """Path to the Basement ground heat-transfer preprocessor, if present."""
        name = "Basement.exe" if platform.system() == "Windows" else "Basement"
        p = self._preprocess_dir / name
        return p if p.is_file() else None

    @property
    def basement_idd(self) -> Path | None:
        """Path to BasementGHT.idd, if present."""
        p = self._preprocess_dir / "BasementGHT.idd"
        return p if p.is_file() else None

    @property
    def version_updater_dir(self) -> Path | None:
        """Path to the ``PreProcess/IDFVersionUpdater`` directory, if present.

        This directory houses the per-step ``Transition-VX-to-VY`` binaries
        and the ``VX-Y-Z-Energy+.idd`` files used to migrate IDF models
        between EnergyPlus versions.
        """
        d = self.install_dir / "PreProcess" / "IDFVersionUpdater"
        return d if d.is_dir() else None

    def transition_exe(
        self,
        from_version: tuple[int, int, int],
        to_version: tuple[int, int, int],
    ) -> Path | None:
        """Return the transition binary for a single version step, if present.

        Probes the registry-exact name first, then ``patch=0`` fallbacks so
        callers using version tuples such as ``(9, 0, 1)`` still resolve the
        ``Transition-V8-9-0-to-V9-0-0`` binary that EnergyPlus actually ships.

        Returns:
            Path to the transition binary, or ``None`` if the IDFVersionUpdater
            directory is missing or no matching binary exists.
        """
        from ..migration.subprocess_backend import binary_candidates

        updater_dir = self.version_updater_dir
        if updater_dir is None:
            return None
        for name in binary_candidates(from_version, to_version):
            p = updater_dir / name
            if p.is_file():
                return p
        return None

    def transition_idd(self, version: tuple[int, int, int]) -> Path | None:
        """Return the bundled IDD for *version* inside IDFVersionUpdater, if present.

        The transition binaries load ``V{maj}-{min}-{patch}-Energy+.idd`` from
        the IDFVersionUpdater directory at runtime.
        """
        updater_dir = self.version_updater_dir
        if updater_dir is None:
            return None
        name = f"V{version[0]}-{version[1]}-{version[2]}-Energy+.idd"
        p = updater_dir / name
        return p if p.is_file() else None

    @classmethod
    def from_path(cls, path: str | Path) -> EnergyPlusConfig:
        """Create config from an explicit installation path.

        The path can point to either the installation directory or the
        energyplus executable directly.

        Args:
            path: Path to EnergyPlus install directory or executable.

        Returns:
            Validated EnergyPlusConfig.

        Raises:
            EnergyPlusNotFoundError: If the path is not a valid installation.
        """
        path = Path(path).resolve()

        # If path is an executable, derive install dir
        if path.is_file():
            install_dir = path.parent
            exe = path
        else:
            install_dir = path
            exe_name = "energyplus.exe" if platform.system() == "Windows" else "energyplus"
            exe = install_dir / exe_name

        if not exe.is_file():
            raise EnergyPlusNotFoundError([str(install_dir)])

        idd = install_dir / "Energy+.idd"
        if not idd.is_file():
            raise EnergyPlusNotFoundError([str(install_dir)])

        version = _extract_version(install_dir)
        if version is None:
            version = _extract_version_from_idd(idd)
        if version is None:
            raise EnergyPlusNotFoundError([str(install_dir)])

        return cls(
            executable=exe,
            version=version,
            install_dir=install_dir,
            idd_path=idd,
        )

`basement_exe` `property` ¶

Path to the Basement ground heat-transfer preprocessor, if present.

`basement_idd` `property` ¶

Path to BasementGHT.idd, if present.

`executable` `instance-attribute` ¶

`expand_objects_exe` `property` ¶

Path to ExpandObjects executable, if present.

`idd_path` `instance-attribute` ¶

`install_dir` `instance-attribute` ¶

`schema_path` `property` ¶

Path to Energy+.schema.epJSON, if present.

`slab_exe` `property` ¶

Path to the Slab ground heat-transfer preprocessor, if present.

`slab_idd` `property` ¶

Path to SlabGHT.idd, if present.

`version` `instance-attribute` ¶

`version_updater_dir` `property` ¶

Path to the PreProcess/IDFVersionUpdater directory, if present.

This directory houses the per-step Transition-VX-to-VY binaries and the VX-Y-Z-Energy+.idd files used to migrate IDF models between EnergyPlus versions.

`weather_dir` `property` ¶

Path to the bundled WeatherData directory, if present.

`from_path(path)` `classmethod` ¶

Create config from an explicit installation path.

The path can point to either the installation directory or the energyplus executable directly.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to EnergyPlus install directory or executable.	required

Returns:

Type	Description
`EnergyPlusConfig`	Validated EnergyPlusConfig.

Raises:

Type	Description
`EnergyPlusNotFoundError`	If the path is not a valid installation.

Source code in idfkit/simulation/config.py

@classmethod
def from_path(cls, path: str | Path) -> EnergyPlusConfig:
    """Create config from an explicit installation path.

    The path can point to either the installation directory or the
    energyplus executable directly.

    Args:
        path: Path to EnergyPlus install directory or executable.

    Returns:
        Validated EnergyPlusConfig.

    Raises:
        EnergyPlusNotFoundError: If the path is not a valid installation.
    """
    path = Path(path).resolve()

    # If path is an executable, derive install dir
    if path.is_file():
        install_dir = path.parent
        exe = path
    else:
        install_dir = path
        exe_name = "energyplus.exe" if platform.system() == "Windows" else "energyplus"
        exe = install_dir / exe_name

    if not exe.is_file():
        raise EnergyPlusNotFoundError([str(install_dir)])

    idd = install_dir / "Energy+.idd"
    if not idd.is_file():
        raise EnergyPlusNotFoundError([str(install_dir)])

    version = _extract_version(install_dir)
    if version is None:
        version = _extract_version_from_idd(idd)
    if version is None:
        raise EnergyPlusNotFoundError([str(install_dir)])

    return cls(
        executable=exe,
        version=version,
        install_dir=install_dir,
        idd_path=idd,
    )

`transition_exe(from_version, to_version)` ¶

Return the transition binary for a single version step, if present.

Probes the registry-exact name first, then patch=0 fallbacks so callers using version tuples such as (9, 0, 1) still resolve the Transition-V8-9-0-to-V9-0-0 binary that EnergyPlus actually ships.

Returns:

Type	Description
`Path \| None`	Path to the transition binary, or `None` if the IDFVersionUpdater
`Path \| None`	directory is missing or no matching binary exists.

Source code in idfkit/simulation/config.py

def transition_exe(
    self,
    from_version: tuple[int, int, int],
    to_version: tuple[int, int, int],
) -> Path | None:
    """Return the transition binary for a single version step, if present.

    Probes the registry-exact name first, then ``patch=0`` fallbacks so
    callers using version tuples such as ``(9, 0, 1)`` still resolve the
    ``Transition-V8-9-0-to-V9-0-0`` binary that EnergyPlus actually ships.

    Returns:
        Path to the transition binary, or ``None`` if the IDFVersionUpdater
        directory is missing or no matching binary exists.
    """
    from ..migration.subprocess_backend import binary_candidates

    updater_dir = self.version_updater_dir
    if updater_dir is None:
        return None
    for name in binary_candidates(from_version, to_version):
        p = updater_dir / name
        if p.is_file():
            return p
    return None

`transition_idd(version)` ¶

Return the bundled IDD for version inside IDFVersionUpdater, if present.

The transition binaries load V{maj}-{min}-{patch}-Energy+.idd from the IDFVersionUpdater directory at runtime.

Source code in idfkit/simulation/config.py

def transition_idd(self, version: tuple[int, int, int]) -> Path | None:
    """Return the bundled IDD for *version* inside IDFVersionUpdater, if present.

    The transition binaries load ``V{maj}-{min}-{patch}-Energy+.idd`` from
    the IDFVersionUpdater directory at runtime.
    """
    updater_dir = self.version_updater_dir
    if updater_dir is None:
        return None
    name = f"V{version[0]}-{version[1]}-{version[2]}-Energy+.idd"
    p = updater_dir / name
    return p if p.is_file() else None

Runner API¶

simulate¶

find_energyplus¶

idfkit.simulation.config.find_energyplus(*, version=None, path=None) ¶

EnergyPlusConfig¶

idfkit.simulation.config.EnergyPlusConfig dataclass ¶

basement_exe property ¶

basement_idd property ¶

executable instance-attribute ¶

expand_objects_exe property ¶

idd_path instance-attribute ¶

install_dir instance-attribute ¶

schema_path property ¶

slab_exe property ¶

slab_idd property ¶

version instance-attribute ¶

version_updater_dir property ¶

weather_dir property ¶

from_path(path) classmethod ¶

transition_exe(from_version, to_version) ¶

transition_idd(version) ¶

`idfkit.simulation.config.find_energyplus(*, version=None, path=None)` ¶

`idfkit.simulation.config.EnergyPlusConfig` `dataclass` ¶

`basement_exe` `property` ¶

`basement_idd` `property` ¶

`executable` `instance-attribute` ¶

`expand_objects_exe` `property` ¶

`idd_path` `instance-attribute` ¶

`install_dir` `instance-attribute` ¶

`schema_path` `property` ¶

`slab_exe` `property` ¶

`slab_idd` `property` ¶

`version` `instance-attribute` ¶

`version_updater_dir` `property` ¶

`weather_dir` `property` ¶

`from_path(path)` `classmethod` ¶

`transition_exe(from_version, to_version)` ¶

`transition_idd(version)` ¶