diff --git a/src/ifcopenshell-python/ifcopenshell/api/constraint/add_metric.py b/src/ifcopenshell-python/ifcopenshell/api/constraint/add_metric.py index ba0913fc88..b0eee618fe 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/constraint/add_metric.py +++ b/src/ifcopenshell-python/ifcopenshell/api/constraint/add_metric.py @@ -20,13 +20,29 @@ import ifcopenshell class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, objective=None): + """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. + + :param objective: The IfcObjective that this metric is a benchmark of. + :type objective: ifcopenshell.entity_instance.entity_instance + :return: The newly created IfcMetric entity + :rtype: ifcopenshell.entity_instance.entity_instance + + Example:: + + objective = ifcopenshell.api.run("constraint.add_objective", model) + metric = ifcopenshell.api.run("constraint.add_metric", model, + objective=objective) + """ self.file = file self.settings = { - "objective": None, + "objective": objective, } - for key, value in settings.items(): - self.settings[key] = value def execute(self): metric = self.file.create_entity( diff --git a/src/ifcopenshell-python/ifcopenshell/api/constraint/add_objective.py b/src/ifcopenshell-python/ifcopenshell/api/constraint/add_objective.py index ffbecb2cbc..0ba45a7f92 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/constraint/add_objective.py +++ b/src/ifcopenshell-python/ifcopenshell/api/constraint/add_objective.py @@ -20,11 +20,29 @@ import ifcopenshell class Usecase: - def __init__(self, file, **settings): + def __init__(self, file): + """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. + + :return: The newly created IfcObjective entity + :rtype: ifcopenshell.entity_instance.entity_instance + + Example:: + + # Create a new objective for code compliance requirements + objective = ifcopenshell.api.run("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. + """ self.file = file self.settings = {} - for key, value in settings.items(): - self.settings[key] = value def execute(self): return self.file.create_entity( diff --git a/src/ifcopenshell-python/ifcopenshell/api/constraint/assign_constraint.py b/src/ifcopenshell-python/ifcopenshell/api/constraint/assign_constraint.py index 8db7adf822..1d77a7bb74 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/constraint/assign_constraint.py +++ b/src/ifcopenshell-python/ifcopenshell/api/constraint/assign_constraint.py @@ -20,14 +20,30 @@ import ifcopenshell class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, product=None, constraint=None): + """Assigns a constraint to a product + + 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. + + :param product: The product the constraint applies to. This is anything + which can have properties or quantities. + :type product: ifcopenshell.entity_instance.entity_instance + :param constraint: The IfcObjective constraint + :type constraint: ifcopenshell.entity_instance.entity_instance + :return: The new or updated IfcRelAssociatesConstraint relationship + :rtype: ifcopenshell.entity_instance.entity_instance + """ self.file = file self.settings = { - "product": None, - "constraint": None, + "product": product, + "constraint": constraint, } - for key, value in settings.items(): - self.settings[key] = value def execute(self): rel = self.get_constraint_rel() diff --git a/src/ifcopenshell-python/ifcopenshell/api/constraint/edit_metric.py b/src/ifcopenshell-python/ifcopenshell/api/constraint/edit_metric.py index 394e9fc936..3a25175a87 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/constraint/edit_metric.py +++ b/src/ifcopenshell-python/ifcopenshell/api/constraint/edit_metric.py @@ -18,11 +18,29 @@ class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, metric=None, attributes=None): + """Edit the attributes of a metric + + For more information about the attributes and data types of an + IfcMetric, consult the IFC documentation. + + :param metric: The IfcMetric you want to edit. + :type metric: ifcopenshell.entity_instance.entity_instance + :param attributes: a dictionary of attribute names and values. + :type attributes: dict, optional + :return: None + :rtype: None + + Example:: + + objective = ifcopenshell.api.run("constraint.add_objective", model) + metric = ifcopenshell.api.run("constraint.add_metric", model, + objective=objective) + ifcopenshell.api.run("constraint.edit_metric", model, + metric=metric, attributes={"ConstraintGrade": "HARD"}) + """ self.file = file - self.settings = {"metric": None, "attributes": {}} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"metric": metric, "attributes": attributes or {}} def execute(self): for name, value in self.settings["attributes"].items(): diff --git a/src/ifcopenshell-python/ifcopenshell/api/constraint/edit_objective.py b/src/ifcopenshell-python/ifcopenshell/api/constraint/edit_objective.py index 4c35d913a9..14b4986db2 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/constraint/edit_objective.py +++ b/src/ifcopenshell-python/ifcopenshell/api/constraint/edit_objective.py @@ -18,11 +18,27 @@ class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, objective=None, attributes=None): + """Edit the attributes of a objective + + For more information about the attributes and data types of an + IfcObjective, consult the IFC documentation. + + :param objective: The IfcObjective you want to edit. + :type objective: ifcopenshell.entity_instance.entity_instance + :param attributes: a dictionary of attribute names and values. + :type attributes: dict, optional + :return: None + :rtype: None + + Example:: + + objective = ifcopenshell.api.run("constraint.add_objective", model) + ifcopenshell.api.run("constraint.edit_objective", model, + objective=objective, attributes={"ConstraintGrade": "HARD"}) + """ self.file = file - self.settings = {"objective": None, "attributes": {}} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"objective": objective, "attributes": attributes or {}} def execute(self): for name, value in self.settings["attributes"].items(): diff --git a/src/ifcopenshell-python/ifcopenshell/api/constraint/remove_constraint.py b/src/ifcopenshell-python/ifcopenshell/api/constraint/remove_constraint.py index 54e4a84f2d..4142eb38e9 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/constraint/remove_constraint.py +++ b/src/ifcopenshell-python/ifcopenshell/api/constraint/remove_constraint.py @@ -18,11 +18,27 @@ class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, constraint=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. + + :param constraint: The IfcObjective you want to remove. + :type constraint: ifcopenshell.entity_instance.entity_instance + :return: None + :rtype: None + + Example:: + + objective = ifcopenshell.api.run("constraint.add_objective", model) + ifcopenshell.api.run("constraint.remove_constraint", model, + constraint=objective) + """ self.file = file - self.settings = {"constraint": None} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"constraint": constraint} def execute(self): self.file.remove(self.settings["constraint"]) diff --git a/src/ifcopenshell-python/ifcopenshell/api/constraint/remove_metric.py b/src/ifcopenshell-python/ifcopenshell/api/constraint/remove_metric.py index 0ccdae2961..b8a7c4b668 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/constraint/remove_metric.py +++ b/src/ifcopenshell-python/ifcopenshell/api/constraint/remove_metric.py @@ -18,11 +18,27 @@ class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, metric=None): + """Remove a metric benchmark + + Removes a metric benchmark and all of its associations to any products + and objectives. + + :param metric: The IfcMetric you want to remove. + :type metric: ifcopenshell.entity_instance.entity_instance + :return: None + :rtype: None + + Example:: + + objective = ifcopenshell.api.run("constraint.add_objective", model) + metric = ifcopenshell.api.run("constraint.add_metric", model, + objective=objective) + ifcopenshell.api.run("constraint.remove_metric", model, + metric=metric) + """ self.file = file - self.settings = {"metric": None} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"metric": metric} def execute(self): self.file.remove(self.settings["metric"]) diff --git a/src/ifcopenshell-python/ifcopenshell/api/constraint/unassign_constraint.py b/src/ifcopenshell-python/ifcopenshell/api/constraint/unassign_constraint.py index c594aff586..2972268fb5 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/constraint/unassign_constraint.py +++ b/src/ifcopenshell-python/ifcopenshell/api/constraint/unassign_constraint.py @@ -18,14 +18,24 @@ class Usecase: - def __init__(self, file, **settings): + def __init__(self, file, product=None, constraint=None): + """Unassigns a constraint to a product + + The constraint will not be deleted and is available to be assigned to + other products. + + :param product: The product the constraint applies to. + :type product: ifcopenshell.entity_instance.entity_instance + :param constraint: The IfcObjective constraint + :type constraint: ifcopenshell.entity_instance.entity_instance + :return: None + :rtype: None + """ self.file = file self.settings = { - "product": None, - "constraint": None, + "product": product, + "constraint": constraint, } - for key, value in settings.items(): - self.settings[key] = value def execute(self): for rel in self.settings["product"].HasAssociations: