ifcopenshell.api.constraint

Constraints are an advanced feature allowing you to specify parametric limits on properties

Warning: usage of constraints are mostly untested in real life applications.

Submodules

Package Contents

ifcopenshell.api.constraint.add_metric(file: ifcopenshell.file, objective: ifcopenshell.entity_instance) → ifcopenshell.entity_instance

Add a new metric benchmark

Qualitative constraints may have a series of quantitative benchmarks linked to it known as metrics. Metrics may be parametrically linked to computed model properties or quantities. Metrics need to be satisfied to meet the objective of the constraint.

Parameters:

objective (ifcopenshell.entity_instance) – The IfcObjective that this metric is a benchmark of.

Returns:

The newly created IfcMetric entity

Return type:

ifcopenshell.entity_instance

Example:

objective = ifcopenshell.api.constraint.add_objective(model)
metric = ifcopenshell.api.constraint.add_metric(model,
    objective=objective)
ifcopenshell.api.constraint.add_metric_reference(file: ifcopenshell.file, metric: ifcopenshell.entity_instance, reference_path: str) → list[ifcopenshell.entity_instance]

Adds a chain of references to a metric. The reference path is a string of the form “attribute.attribute.attribute” Used to reference a value of an attribute of an instance through a metric objective entity.

ifcopenshell.api.constraint.add_objective(file: ifcopenshell.file) → ifcopenshell.entity_instance

Add a new objective constraint

Parametric constraints may be defined by the user. The constraint is defined by first creating an objective describing the purpose of the constraint and whether it is a hard or soft constraint. Later on, metrics may be added to check whether the constraint has been met by connecting it to properties and quantities. See ifcopenshell.api.constraint.add_metric for more information.

Returns:

The newly created IfcObjective entity

Return type:

ifcopenshell.entity_instance

Example:

# Create a new objective for code compliance requirements
objective = ifcopenshell.api.constraint.add_objective(model)
objective.ConstraintGrade = "ADVISORY"
objective.ObjectiveQualifier = "CODECOMPLIANCE"
# Note: the objective right now is purely qualitative and for
# information purposes. You may wish to add quantiative metrics.
ifcopenshell.api.constraint.assign_constraint(file: ifcopenshell.file, products: list[ifcopenshell.entity_instance], constraint: ifcopenshell.entity_instance) → ifcopenshell.entity_instance | None

Assigns a constraint to a list of products

This assigns a relationship between a product and a constraint, so that when a product’s properties and quantities do not match the requirements of the constraint’s metrics, results can be flagged.

It is assumed (but not explicit in the IFC documentation) that constraints are inherited from the type. This way, it is not necessary to create lots of constraint assignments.

Parameters:

  • products (list[ifcopenshell.entity_instance]) – The list of products the constraint applies to. This is anything which can have properties or quantities.

  • constraint (ifcopenshell.entity_instance) – The IfcObjective constraint

Returns:

The new or updated IfcRelAssociatesConstraint relationship or None if products was an empty list.

Return type:

ifcopenshell.entity_instance

ifcopenshell.api.constraint.edit_metric(file: ifcopenshell.file, metric: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None

Edit the attributes of a metric

For more information about the attributes and data types of an IfcMetric, consult the IFC documentation.

Parameters:

  • metric (ifcopenshell.entity_instance) – The IfcMetric you want to edit.

  • attributes (dict) – a dictionary of attribute names and values.

Returns:

None

Return type:

None

Example:

objective = ifcopenshell.api.constraint.add_objective(model)
metric = ifcopenshell.api.constraint.add_metric(model,
    objective=objective)
ifcopenshell.api.constraint.edit_metric(model,
    metric=metric, attributes={"ConstraintGrade": "HARD"})
ifcopenshell.api.constraint.edit_objective(file: ifcopenshell.file, objective: ifcopenshell.entity_instance, attributes: dict[str, Any]) → None

Edit the attributes of a objective

For more information about the attributes and data types of an IfcObjective, consult the IFC documentation.

Parameters:

  • objective (ifcopenshell.entity_instance) – The IfcObjective you want to edit.

  • attributes (dict) – a dictionary of attribute names and values.

Returns:

None

Return type:

None

Example:

objective = ifcopenshell.api.constraint.add_objective(model)
ifcopenshell.api.constraint.edit_objective(model,
    objective=objective, attributes={"ConstraintGrade": "HARD"})
ifcopenshell.api.constraint.remove_constraint(file: ifcopenshell.file, constraint: ifcopenshell.entity_instance) → None

Remove a constraint (typically an objective)

Removes a constraint definition and all of its associations to any products. Typically this would be an IfcObjective, although technically you can associate IfcMetrics ith products too, though the meaning may be unclear.

Parameters:

constraint (ifcopenshell.entity_instance) – The IfcObjective you want to remove.

Returns:

None

Return type:

None

Example:

objective = ifcopenshell.api.constraint.add_objective(model)
ifcopenshell.api.constraint.remove_constraint(model,
    constraint=objective)
ifcopenshell.api.constraint.remove_metric(file: ifcopenshell.file, metric: ifcopenshell.entity_instance) → None

Remove a metric benchmark

Removes a metric benchmark and all of its associations to any products and objectives.

Parameters:

metric (ifcopenshell.entity_instance) – The IfcMetric you want to remove.

Returns:

None

Return type:

None

Example:

objective = ifcopenshell.api.constraint.add_objective(model)
metric = ifcopenshell.api.constraint.add_metric(model,
    objective=objective)
ifcopenshell.api.constraint.remove_metric(model,
    metric=metric)
ifcopenshell.api.constraint.unassign_constraint(file: ifcopenshell.file, products: list[ifcopenshell.entity_instance], constraint: ifcopenshell.entity_instance) → None

Unassigns a constraint from a list of products

The constraint will not be deleted and is available to be assigned to other products.

Parameters:

  • products (list[ifcopenshell.entity_instance]) – The list of products the constraint applies to.

  • constraint (ifcopenshell.entity_instance) – The IfcObjective constraint

Returns:

None

Return type:

None