Attributes

Which problem is addressed by attributes?

To parametrize simulation models, different types of parameters are needed. A BIM model and specifically an IFC model offers multiple sources for the requested information. Let’s assume that we need the net_area of a wall. This information can either be obtained from:

  • the official IFC specified QuantitySet Qto_WallBaseQuantities/NetSideArea

  • the unofficial, but typical in ArchiCAD used BaseQuantities'/NetSideArea

  • any other PropertySet where the BIM modeller might have stored the information

  • the calculation of the Space Boundary area of the wall

  • nowhere, because the information simply does not exist in the model (might not be the case for this example)

To resolve this problem of multiple available sources and even parameters which will be not included in the BIM model at all the Attribute system provides a solution.

Concept / How does it work?

Simulation required informations that are potentially available in the BIM model are stored in an Attribute at the corresponding element.

E.g. the already mentioned net_area is implemented by the following lines in the the class OuterWall:


net_area = attribute.Attribute(
    default_ps=("Qto_WallBaseQuantities", "NetSideArea"),
    functions=[BPSProduct.get_net_bound_area],
    unit=ureg.meter ** 2
)

This way bim2sim knows where to look for in the IFC file and which function to use if no information exists in the IFC file. Also the unit in which the value should be stored is provided as m². See _get_value function of attribute documentation for more detailed description which other ways are implemented to obtain a value.

How are the attributes managed?

To manage the different attributes every bim2sim element instance owns an instance of the AttributeManager which is stored under element.attributes. This manager manages the values and current status of the Attributes.

If an information can’t be obtained by the implemented ways in _get_value function of attribute of attribute its status will be changed to NOT_AVAILABLE. As some information are mandatory to parametrize a simulation model, we implemented the concept of Decisions which is basically a structured way to obtain information from the user. To make sure that all relevant information exists, a parameter can be requested. This way a Decisions will be created if the status of the corresponding attribute is NOT_AVAILABLE.

// todo: flow chart with mermaid. To use mermaid: https://github.com/mgaitan/sphinxcontrib-mermaid#markdown-support

The AttributeManager uses the status of each attribute to store if an attribute was already requested. To trigger all decisions for the already requested attributes to finally obtain the corresponding values the final tasks before exporting to a simulation model should always trigger the get_pending_attribute_decisions function of element. This implementation was made to bundle the decisions at the end of the process if possible.

When to use attributes?

There are multiple ways to calculate and store information in a bim2sim element. Following you will find some guidelines when to use which way.

bim2sim attribute

The specialized bim2sim attribute system should be used when:

  • Values need to be obtained from different sources (IFC attributes, IFC PropertySets, enrichment data, etc.)

  • Physical units (via pint) need to be managed

  • Automatic validation and type checking is required

  • Values need to be traceable (status, data source)

  • Missing values should be supplemented via user interaction (Decisions)

Python properties

Python properties are created using the inbuilt decorator @property. Properties should be used when:

  • None of the features by the bim2sim attribute system is needed

  • Computed values should be determined on-demand

  • Getter/setter logic is needed

  • Attribute-like access to methods is desired

  • Validation or transformation is necessary when reading/writing

Example for the usage of property:

class Circle:
    def __init__(self, radius):
        self._radius = radius
    
    @property
    def area(self):
        return 3.14 * self._radius ** 2
    
    @property
    def radius(self):
        return self._radius
        
    @radius.setter
    def radius(self, value):
        if value < 0:
            raise ValueError("Radius must be positive")
        self._radius = value

Class attributes

  • When every instance of the class has the same value

  • When you want to share the value of this attribute through all instances of this class

An example would be the counter of created instances of this class:

class MyClass:
    instance_count = 0

    def __init__(self):
        MyClass.instance_count += 1

Instance attributes

  • If every instance of the class should have it’s own value

  • If the value is always needed and will stay the same for the lifetime of the object The most common way is to put information into instance attributes by add a value or the link to a method to calculate this value to the __init__ function:

class MyElement(element):
    def __init__(self, value):
        self.value = value  # constant instance attribute
        self.value_2 = self.calc_valuve_2()

    def calc_value_2(self):
        return 1+2