Skip to content

Models and errors

All generated object models derive from IDFBaseModel. Their fields are documented per object type in the object reference.

IDFBaseModel

Bases: BaseModel

Base class for all IDF object models.

Provides common configuration and utility methods for IDF objects.

Attributes:

Name Type Description
_idf_object_type str

Class variable storing the original EnergyPlus object type name (e.g., "BuildingSurface:Detailed"). Override in subclasses.

idf_object_type classmethod 

idf_object_type() -> str

Get the EnergyPlus IDF object type name.

Returns:

Type Description
str

Original object type name (e.g., "Zone", "BuildingSurface:Detailed").

referencing 

referencing(
    consumer_type: str | None = None, *, strict: bool = True
) -> list[IDFBaseModel]

referencing(
    consumer_type: type[T], *, strict: bool = True
) -> list[T]

referencing(
    consumer_type: str | type[IDFBaseModel] | None = None,
    *,
    strict: bool = True,
) -> list[IDFBaseModel]

Find objects that reference this object.

Parameters:

Name Type Description Default
consumer_type str | type[IDFBaseModel] | None

EnergyPlus object type string (e.g., "BuildingSurface:Detailed"), Python class name, model class, or None. When None, returns all objects across every type.

 None
strict bool

When True (default) raise UnknownObjectTypeError on unresolvable consumer_type. Pass strict=False for the legacy behavior of returning [].

 True

Returns:

Type Description
list[IDFBaseModel]

List of objects whose ref fields point to this object.

Raises:

Type Description
RuntimeError

If not bound to an IDF container.
UnknownObjectTypeError

When strict=True and the consumer_type cannot be resolved.

referenced 

referenced(
    provider_type: str | None = None, *, strict: bool = True
) -> list[IDFBaseModel]

referenced(
    provider_type: type[T], *, strict: bool = True
) -> list[T]

referenced(
    provider_type: str | type[IDFBaseModel] | None = None,
    *,
    strict: bool = True,
) -> list[IDFBaseModel]

Find objects referenced by this object.

Parameters:

Name Type Description Default
provider_type str | type[IDFBaseModel] | None

EnergyPlus object type string, Python class name, model class, or None. When None, returns referenced objects across every type.

 None
strict bool

When True (default) raise UnknownObjectTypeError on unresolvable provider_type. Pass strict=False to return [] instead.

 True

Returns:

Type Description
list[IDFBaseModel]

Unique objects targeted by this object's ref fields.

Raises:

Type Description
RuntimeError

If not bound to an IDF container.
UnknownObjectTypeError

When strict=True and the provider_type cannot be resolved.

to_idf_dict 

to_idf_dict() -> dict[str, Any]

Convert model to IDF-compatible dictionary.

Exports all non-None fields with their original names.

Returns:

Type Description
dict[str, Any]

Dictionary suitable for IDF/epJSON serialization.

Errors

UnknownObjectTypeError 

UnknownObjectTypeError(key: type | str)

Bases: ValueError

Raised when an object type name or class cannot be resolved.

Attributes:

Name Type Description
key

The input key that failed resolution (type or str).

RefError dataclass 

RefError(
    object_type: str,
    object_name: str,
    field_name: str,
    ref_group: str,
    referenced_name: str,
    error_type: str,
    detail: str,
)

Single broken reference.

RefValidationError 

RefValidationError(errors: list[RefError])

Bases: Exception

Raised by IDF.validate_or_raise() when references are broken.