Module Contents

ifcopenshell.api.project.assign_declaration.assign_declaration(file: ifcopenshell.entity_instance, definitions: list[ifcopenshell.entity_instance], relating_context: ifcopenshell.entity_instance) ifcopenshell.entity_instance | None

Declares the list of elements to the project

All data in a model must be directly or indirectly related to the project. Most data is indirectly related, existing instead within the spatial decomposition tree. Other data, such as types, may be declared at the top level.

Most of the time, the API handles declaration automatically for you. There is one scenario where you might want to explicitly declare objects to the project, and that’s when you want to organise objects into project libraries for future use (such as an assets library). Assigning a declaration lets you say that an object belongs to a library.


The new IfcRelDeclares relationship or None if all definitions were already declared / do not support declaration.

Return type:

Union[ifcopenshell.entity_instance, None]


# Programmatically generate a library. You could do this visually too.
library = ifcopenshell.api.run("project.create_file")
root = ifcopenshell.api.run("root.create_entity", library, ifc_class="IfcProject", name="Demo Library")
context = ifcopenshell.api.run("root.create_entity", library,
    ifc_class="IfcProjectLibrary", name="Demo Library")

# It's necessary to say our library is part of our project.
ifcopenshell.api.run("project.assign_declaration", library, definitions=[context], relating_context=root)

# Assign units for our example library
unit = ifcopenshell.api.run("unit.add_si_unit", library,
    unit_type="LENGTHUNIT", name="METRE", prefix="MILLI")
ifcopenshell.api.run("unit.assign_unit", library, units=[unit])

# Let's create a single asset of a 200mm thick concrete wall
wall_type = ifcopenshell.api.run("root.create_entity", library, ifc_class="IfcWallType", name="WAL01")
concrete = ifcopenshell.api.run("material.add_material", file, name="CON", category="concrete")
rel = ifcopenshell.api.run("material.assign_material", library,
    products=[wall_type], type="IfcMaterialLayerSet")
layer = ifcopenshell.api.run("material.add_layer", library,
    layer_set=rel.RelatingMaterial, material=concrete)
layer.Name = "Structure"
layer.LayerThickness = 200

# Mark our wall type as a reusable asset in our library.
ifcopenshell.api.run("project.assign_declaration", library,
    definitions=[wall_type], relating_context=context)

# All done, just for fun let's save our asset library to disk for later use.