new util method ifcopenshell.util.element.get_groups

src/ifcopenshell-python/ifcopenshell/util/element.py

@@ -975,6 +975,28 @@ def get_grouped_by(element: ifcopenshell.entity_instance) -> list[ifcopenshell.e
     return results
 
 
+def get_groups(element: ifcopenshell.entity_instance) -> list[ifcopenshell.entity_instance]:
+    """
+    Retrieves the groups of an element.
+
+    :param element: The IFC element
+    :return: List of IfcGroups element is assigned to.
+    :rtype: list[ifcopenshell.entity_instance.entity_instance]
+
+    Example:
+
+    .. code:: python
+
+        wall = file.by_type("IfcWall")[0]
+        group = ifcopenshell.util.element.get_groups(element)[0]
+    """
+    groups = []
+    for rel in element.HasAssignments:
+        if rel.is_a("IfcRelAssignsToGroup"):
+            groups.append(rel.RelatingGroup)
+    return groups
+
+
 def get_aggregate(element: ifcopenshell.entity_instance) -> ifcopenshell.entity_instance:
     """
     Retrieves the aggregate parent of an element.

src/ifcopenshell-python/test/util/test_element.py

@@ -732,6 +732,23 @@ class TestGetDecompositionIFC4(test.bootstrap.IFC4):
         assert subsubelement in results
 
 
+class TestGetGroupsIFC4(test.bootstrap.IFC4):
+    def test_run(self):
+        element = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcWall")
+        group1 = ifcopenshell.api.run("group.add_group", self.file)
+        group2 = ifcopenshell.api.run("group.add_group", self.file)
+
+        # assign group for multiple elements
+        ifcopenshell.api.run("group.assign_group", self.file, products=[element], group=group1)
+        ifcopenshell.api.run("group.assign_group", self.file, products=[element], group=group2)
+
+        assert set(subject.get_groups(element)) == set([group1, group2])
+
+
+class TestGetGroupsIFC2X3(test.bootstrap.IFC2X3, TestGetGroupsIFC4):
+    pass
+
+
 class TestGetAggregateIFC4(test.bootstrap.IFC4):
     def test_getting_the_containing_aggregate_of_a_subelement(self):
         element = ifcopenshell.api.run("root.create_entity", self.file, ifc_class="IfcWall")