Ifcos Core Concepts

IFC Core Concepts

Quick Reference

Entity Hierarchy Overview

IfcRoot (abstract) — GlobalId, OwnerHistory, Name, Description
├── IfcObjectDefinition (abstract)
│   ├── IfcObject (abstract)
│   │   ├── IfcProduct (abstract) — ObjectPlacement, Representation
│   │   │   ├── IfcSpatialElement [IFC4+] / IfcSpatialStructureElement [IFC2X3]
│   │   │   ├── IfcElement (abstract)
│   │   │   │   ├── IfcBuiltElement [IFC4X3] / IfcBuildingElement [IFC2X3/IFC4]
│   │   │   │   ├── IfcDistributionElement
│   │   │   │   ├── IfcFurnishingElement
│   │   │   │   └── ... (see references/methods.md)
│   │   │   ├── IfcAnnotation
│   │   │   └── IfcPort
│   │   ├── IfcProcess — IfcTask
│   │   ├── IfcResource
│   │   ├── IfcControl
│   │   └── IfcGroup
│   ├── IfcContext [IFC4+] / IfcObject [IFC2X3]
│   │   ├── IfcProject
│   │   └── IfcProjectLibrary [IFC4+]
│   └── IfcTypeObject
│       └── IfcTypeProduct → IfcElementType
├── IfcPropertyDefinition
│   ├── IfcPropertySet
│   └── IfcElementQuantity
└── IfcRelationship (abstract)
    ├── IfcRelDecomposes — IfcRelAggregates, IfcRelVoidsElement
    ├── IfcRelAssigns — assignments to actors, groups, processes
    ├── IfcRelConnects — IfcRelContainedInSpatialStructure, IfcRelFillsElement
    ├── IfcRelAssociates — IfcRelAssociatesMaterial, IfcRelAssociatesClassification
    ├── IfcRelDeclares — project/library declarations [IFC4+]
    └── IfcRelDefines — IfcRelDefinesByType, IfcRelDefinesByProperties

Critical Version Differences

IfcRoot Attributes (Present on ALL Named Entities)

Every entity inheriting from IfcRoot has these four attributes:

Essential Patterns

1. Spatial Structure Hierarchy

The spatial structure defines the physical organization of a project. ALWAYS build it top-down using aggregate.assign_object.

IFC2X3 — Building-only hierarchy (RIGID):

IfcProject → IfcSite → IfcBuilding → IfcBuildingStorey → IfcSpace

IFC4 — Extended with zones:

IfcProject → IfcSite → IfcBuilding → IfcBuildingStorey → IfcSpace
                                    + IfcSpatialZone (non-hierarchical overlays)
                                    + IfcExternalSpatialElement (outdoor)

IFC4X3 — Infrastructure support (FLEXIBLE):

IfcProject → IfcSite → IfcBuilding → IfcBuildingStorey → IfcSpace
                      → IfcRoad → IfcRoadPart
                      → IfcBridge → IfcBridgePart
                      → IfcRailway → IfcRailwayPart
                      → IfcFacility → IfcFacilityPart

# IFC2X3/IFC4: Standard building hierarchy
# Schema: IFC2X3, IFC4
model = ifcopenshell.file(schema="IFC4")
project = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcProject", name="My Project")
site = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcSite", name="My Site")
building = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuilding", name="Building A")
storey = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcBuildingStorey", name="Ground Floor")

ifcopenshell.api.run("aggregate.assign_object", model, relating_object=project, products=[site])
ifcopenshell.api.run("aggregate.assign_object", model, relating_object=site, products=[building])
ifcopenshell.api.run("aggregate.assign_object", model, relating_object=building, products=[storey])

# IFC4X3: Infrastructure hierarchy
# Schema: IFC4X3
model = ifcopenshell.file(schema="IFC4X3")
project = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcProject", name="Infra Project")
site = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcSite", name="Project Site")
road = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcRoad", name="Highway A1")
road_part = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcRoadPart", name="Segment 1")

ifcopenshell.api.run("aggregate.assign_object", model, relating_object=project, products=[site])
ifcopenshell.api.run("aggregate.assign_object", model, relating_object=site, products=[road])
ifcopenshell.api.run("aggregate.assign_object", model, relating_object=road, products=[road_part])

2. Entity Inheritance and Type Checking

ALWAYS use is_a() for type checking. It traverses the full inheritance chain.

# Schema: IFC2X3, IFC4, IFC4X3
wall = model.by_type("IfcWall")[0]
wall.is_a()              # Returns "IfcWall"
wall.is_a("IfcWall")     # True
wall.is_a("IfcElement")  # True (parent class)
wall.is_a("IfcProduct")  # True (grandparent)
wall.is_a("IfcRoot")     # True (ancestor)
wall.is_a("IfcSlab")     # False (different subtype)

NEVER compare is_a() return values as strings for inheritance checks:

# WRONG: misses subtypes
if wall.is_a() == "IfcBuildingElement":  # Fails: wall.is_a() returns "IfcWall"

# CORRECT: checks full inheritance chain
if wall.is_a("IfcBuildingElement"):  # True for all building element subtypes

3. Relationship Model (Objectified Relationships)

IFC uses objectified relationships — relationships are first-class IfcRoot entities with their own GlobalId. NEVER set relationships by assigning attributes directly.

Key relationship types:

# Schema: IFC2X3, IFC4, IFC4X3
# CORRECT: Use API to create relationships
ifcopenshell.api.run("spatial.assign_container", model,
    relating_structure=storey, products=[wall])

# CORRECT: Query relationships via utility functions
container = ifcopenshell.util.element.get_container(wall)
element_type = ifcopenshell.util.element.get_type(wall)
material = ifcopenshell.util.element.get_material(wall)
psets = ifcopenshell.util.element.get_psets(wall)

4. Ownership Model

Every IfcRoot entity references an IfcOwnerHistory that records who created/modified it.

IFC2X3: OwnerHistory is MANDATORY on all IfcRoot entities. IFC4/IFC4X3: OwnerHistory is OPTIONAL.

# Schema: IFC2X3: OwnerHistory REQUIRED
owner_history = ifcopenshell.api.run("owner.create_owner_history", model)
wall = model.createIfcWall(
    ifcopenshell.guid.new(),
    owner_history,  # REQUIRED — cannot be None
    "MyWall"
)

# Schema: IFC4, IFC4X3: OwnerHistory OPTIONAL
wall = model.createIfcWall(
    ifcopenshell.guid.new(),
    None,  # ALLOWED in IFC4+
    "MyWall"
)

ALWAYS use ifcopenshell.api.run("root.create_entity", ...) instead of direct createIfc* calls. The API handles OwnerHistory automatically based on schema version.

5. Placement System

Every IfcProduct has an optional ObjectPlacement. Placements are relative to a parent placement, forming a placement tree.

# Schema: IFC2X3, IFC4, IFC4X3
import numpy

# Set placement using 4x4 transformation matrix (identity = origin)
ifcopenshell.api.run("geometry.edit_object_placement", model,
    product=wall, matrix=numpy.eye(4))

# Set placement relative to a container
ifcopenshell.api.run("geometry.edit_object_placement", model,
    product=wall, matrix=numpy.array([
        [1.0, 0.0, 0.0, 5.0],   # X offset = 5.0
        [0.0, 1.0, 0.0, 0.0],
        [0.0, 0.0, 1.0, 0.0],
        [0.0, 0.0, 0.0, 1.0]
    ]))

6. Representation System

Geometric representation is assigned through representation contexts. ALWAYS create a context before assigning geometry.

# Schema: IFC2X3, IFC4, IFC4X3
# Step 1: Create representation context
model3d = ifcopenshell.api.run("context.add_context", model, context_type="Model")
body_context = ifcopenshell.api.run("context.add_context", model,
    context_type="Model", context_identifier="Body",
    target_view="MODEL_VIEW", parent=model3d)

# Step 2: Create representation
representation = ifcopenshell.api.run("geometry.add_wall_representation", model,
    context=body_context, length=5.0, height=3.0, thickness=0.2)

# Step 3: Assign representation to product
ifcopenshell.api.run("geometry.assign_representation", model,
    product=wall, representation=representation)

7. Type Objects (Occurrence/Type Pattern)

IFC separates type definitions from occurrences. A type (e.g., IfcWallType) defines shared properties; occurrences (e.g., IfcWall) reference the type.

# Schema: IFC2X3, IFC4, IFC4X3
# Create a type
wall_type = ifcopenshell.api.run("root.create_entity", model,
    ifc_class="IfcWallType", name="Standard Wall 200mm")

# Assign type to occurrences
ifcopenshell.api.run("type.assign_type", model,
    related_objects=[wall1, wall2], relating_type=wall_type)

# Query type of an occurrence
element_type = ifcopenshell.util.element.get_type(wall1)

# Get all occurrences of a type
occurrences = ifcopenshell.util.element.get_types(wall_type)

Version-specific type entity names:

Common Operations

Query All Elements by Type

# Schema: IFC2X3, IFC4, IFC4X3
walls = model.by_type("IfcWall")           # All walls (tuple)
elements = model.by_type("IfcElement")     # ALL elements (includes subtypes)
products = model.by_type("IfcProduct")     # ALL products (elements + spatial + annotations)

Navigate Spatial Hierarchy

# Schema: IFC2X3, IFC4, IFC4X3
import ifcopenshell.util.element

# Get the spatial container of an element
container = ifcopenshell.util.element.get_container(wall)  # Returns IfcBuildingStorey etc.

# Get all elements contained in a spatial structure
for rel in storey.ContainsElements:
    for element in rel.RelatedElements:
        print(f"{element.is_a()}: {element.Name}")

# Walk the spatial decomposition tree
for rel in building.IsDecomposedBy:
    for part in rel.RelatedObjects:
        print(f"{part.is_a()}: {part.Name}")  # Storeys

Read Properties

# Schema: IFC2X3, IFC4, IFC4X3
import ifcopenshell.util.element

# Get all property sets as dict
psets = ifcopenshell.util.element.get_psets(wall)
# Returns: {'Pset_WallCommon': {'id': 42, 'IsExternal': True, 'FireRating': 'REI120'}}

# Get a specific property value
is_external = psets.get("Pset_WallCommon", {}).get("IsExternal")

Schema Version Detection

# Schema: IFC2X3, IFC4, IFC4X3
model = ifcopenshell.open("building.ifc")
schema = model.schema  # Returns "IFC2X3", "IFC4", or "IFC4X3"

# Version-aware entity class selection
if schema == "IFC4X3":
    elements = model.by_type("IfcBuiltElement")
else:
    elements = model.by_type("IfcBuildingElement")

Detect Schema and Handle IfcBuiltElement/IfcBuildingElement

# Schema: IFC2X3, IFC4, IFC4X3
def get_building_elements(model):
    """Get all building/built elements regardless of schema version."""
    schema = model.schema
    if schema == "IFC4X3":
        return model.by_type("IfcBuiltElement")
    return model.by_type("IfcBuildingElement")

Check Entity Existence in Schema

# Schema: IFC2X3, IFC4, IFC4X3
import ifcopenshell.ifcopenshell_wrapper

schema_obj = ifcopenshell.ifcopenshell_wrapper.schema_by_name(model.schema)
try:
    entity = schema_obj.declaration_by_name("IfcRoad")
    print("IfcRoad exists in this schema")
except RuntimeError:
    print("IfcRoad does NOT exist in this schema")

Reference Links

• references/methods.md — Complete entity class reference with attributes per schema version
• references/examples.md — Working code examples for entity traversal, spatial structure creation, property access, and relationship navigation
• references/anti-patterns.md — Common IFC conceptual mistakes with explanations

Official Documentation

• IFC4X3 Documentation: https://ifc43-docs.standards.buildingsmart.org/
• buildingSMART IFC Standards: https://technical.buildingsmart.org/standards/ifc/
• IFC Schema Specifications: https://technical.buildingsmart.org/standards/ifc/ifc-schema-specifications/