IDF¶

The container for a whole EnergyPlus model. See Files and dictionaries for a guided tour.

IDF ¶

IDF()

EnergyPlus IDF file unified interface.

Integrates object container and IDF file read/write functionality. Reference validation is handled automatically by RefValidator in Pydantic models.

Attributes:

Name	Type	Description
`_objects`	`dict[str, dict[str, IDFBaseModel]]`	Internal storage mapping object_type -> {name -> object}

Initialize empty IDF container.

version `property` ¶

version: str

Get EnergyPlus schema version from Version model default.

Returns:

Type	Description
`str`	Schema version string (e.g., '25.1').

types ¶

types() -> KeysView[str]

Return the object type names present in this IDF.

add ¶

add(obj: IDFBaseModel) -> None

Add an IDF object to the container.

For named objects, raises ValueError on duplicate name. For nameless objects (no 'name' field or empty name), auto-generates a unique internal key with incrementing index.

Parameters:

Name	Type	Description	Default
`obj`	`IDFBaseModel`	IDF object instance to add.	required

Raises:

Type	Description
`ValueError`	If a named object with same type and name already exists.

get ¶

get(
    object_type: type[_T],
    name: str,
    *,
    strict: bool = True,
) -> _T | None

get(
    object_type: str, name: str, *, strict: bool = True
) -> IDFBaseModel | None

get(
    object_type: type[_T] | str,
    name: str,
    *,
    strict: bool = True,
) -> _T | IDFBaseModel | None

Get an object by type and name.

Parameters:

Name	Type	Description	Default
`object_type`	`type[_T] \| str`	EnergyPlus object type string (e.g., 'Zone'), Python class name string (e.g., 'BuildingSurfaceDetailed'), or model class (e.g., Zone).	required
`name`	`str`	Object name.	required
`strict`	`bool`	When True (default) raise UnknownObjectTypeError on unresolvable `object_type`. Pass `strict=False` for the legacy silent-return behavior.	`True`

Returns:

Type	Description
`_T \| IDFBaseModel \| None`	IDF object or None if not found.

Raises:

Type	Description
`UnknownObjectTypeError`	When `strict=True` and the `object_type` cannot be resolved.

has ¶

has(
    object_type: type[IDFBaseModel],
    name: str,
    *,
    strict: bool = True,
) -> bool

has(
    object_type: str, name: str, *, strict: bool = True
) -> bool

has(
    object_type: type[IDFBaseModel] | str,
    name: str,
    *,
    strict: bool = True,
) -> bool

Check if an object exists.

Parameters:

Name	Type	Description	Default
`object_type`	`type[IDFBaseModel] \| str`	EnergyPlus object type, Python class name, or model class.	required
`name`	`str`	Object name.	required
`strict`	`bool`	When True (default) raise UnknownObjectTypeError on unresolvable `object_type`.	`True`

Returns:

Type	Description
`bool`	True if object exists, False otherwise.

Raises:

Type	Description
`UnknownObjectTypeError`	When `strict=True` and the `object_type` cannot be resolved.

all_of_type ¶

all_of_type(
    object_type: type[_T], *, strict: bool = True
) -> dict[str, _T]

all_of_type(
    object_type: str, *, strict: bool = True
) -> dict[str, IDFBaseModel]

all_of_type(
    object_type: type[_T] | str, *, strict: bool = True
) -> dict[str, _T] | dict[str, IDFBaseModel]

Get all objects of a specific type.

Parameters:

Name	Type	Description	Default
`object_type`	`type[_T] \| str`	EnergyPlus object type, Python class name, or model class.	required
`strict`	`bool`	When True (default) raise UnknownObjectTypeError on unresolvable `object_type`.	`True`

Returns:

Type	Description
`dict[str, _T] \| dict[str, IDFBaseModel]`	Dictionary mapping name to object, empty dict if type is
`dict[str, _T] \| dict[str, IDFBaseModel]`	resolvable but no objects exist.

Raises:

Type	Description
`UnknownObjectTypeError`	When `strict=True` and the `object_type` cannot be resolved.

remove ¶

remove(
    object_type: type[_T],
    name: str,
    *,
    strict: bool = True,
) -> _T | None

remove(
    object_type: str, name: str, *, strict: bool = True
) -> IDFBaseModel | None

remove(
    object_type: type[_T] | str,
    name: str,
    *,
    strict: bool = True,
) -> _T | IDFBaseModel | None

Remove an object and unregister its references.

Parameters:

Name	Type	Description	Default
`object_type`	`type[_T] \| str`	EnergyPlus object type, Python class name, or model class.	required
`name`	`str`	Object name.	required
`strict`	`bool`	When True (default) raise UnknownObjectTypeError on unresolvable `object_type`.	`True`

Returns:

Type	Description
`_T \| IDFBaseModel \| None`	Removed object, or None if not found.

Raises:

Type	Description
`UnknownObjectTypeError`	When `strict=True` and the `object_type` cannot be resolved.

validate ¶

validate() -> list[RefError]

Validate all cross-object references.

Checks: 1. Existence: referenced name exists in at least one ref group 2. Type compatibility: provider type is valid for the matched group

Multiple object_list groups per field have OR semantics.

validate_or_raise ¶

validate_or_raise() -> None

Validate references, raise RefValidationError if broken.

to_dict ¶

to_dict() -> dict[str, dict[str, dict[str, Any]]]

Convert IDF container to epJSON-style nested dictionary.

Returns:

Type	Description
`dict[str, dict[str, dict[str, Any]]]`	Nested dict: object_type → object_name → fields (without name).

from_dict `classmethod` ¶

from_dict(
    data: dict[str, dict[str, dict[str, Any]]],
    *,
    strict: bool = True,
) -> IDF

Construct IDF from epJSON-style nested dictionary.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, dict[str, dict[str, Any]]]`	Nested dict: object_type → object_name → fields.	required
`strict`	`bool`	When True (default), raise on unknown object types and validation errors. When False, log warnings and skip.	`True`

Returns:

Type	Description
`IDF`	IDF instance with parsed objects.

Raises:

Type	Description
`ValueError`	If data is not a dict, any object-type value is not a dict, or any fields entry is not a mapping.
`UnknownObjectTypeError`	When `strict=True` and an object type is not recognized.

merge_dict ¶

merge_dict(
    data: dict[str, dict[str, dict[str, Any]]],
    *,
    on_conflict: ConflictPolicy = 'raise',
    strict: bool = True,
) -> None

Merge epJSON-style dictionary into this IDF instance.

The merge is atomic: all input is validated and all model objects are constructed before any mutation. If any step raises, the IDF is left unchanged.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, dict[str, dict[str, Any]]]`	Nested dict: object_type → object_name → fields.	required
`on_conflict`	`ConflictPolicy`	Strategy when a conflict is detected (named duplicate or singleton already present): `"raise"` (default) raises ValueError, `"replace"` removes the old object first, `"skip"` keeps the existing object.	`'raise'`
`strict`	`bool`	When True (default), raise on unknown object types and validation errors. When False, log warnings and skip.	`True`

Raises:

Type	Description
`ValueError`	If data structure is invalid, or `on_conflict="raise"` and a conflict is detected.
`UnknownObjectTypeError`	When `strict=True` and an unknown type is encountered.

load `classmethod` ¶

load(path: Path, *, strict: bool = True) -> IDF

Load IDF/epJSON file and parse into object container.

File format is auto-detected by extension: - .epjson / .json → epJSON format - others → IDF text format

Parameters:

Name	Type	Description	Default
`path`	`Path`	Path to IDF or epJSON file.	required
`strict`	`bool`	When True (default), raise on the first object that has an unknown type, fails validation, duplicates an existing name, or carries values beyond its schema fields. IDF text errors carry a note with the file path and the line where the object starts. When False, skip invalid objects (and truncate surplus values) with a warning log.	`True`

Returns:

Type	Description
`IDF`	IDF instance with the parsed objects.

Raises:

Type	Description
`FileNotFoundError`	If file does not exist.
`UnknownObjectTypeError`	When `strict=True` and an object type is not recognized.
`ValueError`	When `strict=True` and an object is invalid; pydantic `ValidationError` is a subclass.

save ¶

save(
    path: Path,
    output_type: Literal['idf', 'epjson'] = 'idf',
) -> None

Save IDF container to file.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Output file path.	required
`output_type`	`Literal['idf', 'epjson']`	Output format, 'idf' or 'epjson'.	`'idf'`

IDF¶

IDF ¶

version property ¶

types ¶

add ¶

get ¶

has ¶

all_of_type ¶

remove ¶

validate ¶

validate_or_raise ¶

to_dict ¶

from_dict classmethod ¶

merge_dict ¶

load classmethod ¶

save ¶

version `property` ¶

from_dict `classmethod` ¶

load `classmethod` ¶