Skip to content

compas_model.models ¤

Classes¤

ElementNode ¤

ElementNode(element: Element, **kwargs)

Class representing nodes containing elements in an element tree.

Parameters:

  • element (Element) –

    The element contained in the node.

Attributes:

  • element (Element) –

    The element contained in the node.

Notes

This object will raise an Exception, when it is (de)serialised independently, outside the context of a Model.

ElementTree ¤

ElementTree(name: str | None = None)

Class representing the hierarchy of elements in a model through a tree.

Parameters:

  • model (:class:`compas_model.model.Model`) –

    The parent model of the element tree.

  • name (str, default: None ) –

    The name of the tree.

Attributes:

  • model (:class:`compas_model.model.Model`) –

    The parent model of the tree.

  • groups (list[:class:`GroupNode`], read-only) –

    The groups contained in the tree.

  • elements ((list[Element], read - only)) –

    The elements contained in the tree

InteractionGraph ¤

InteractionGraph(**kwargs)

Class representing the interactions between elements in a model.

Parameters:

  • default_node_attributes (dict) –

    The default attributes for nodes.

  • default_edge_attributes (dict) –

    The default attributes for edges.

Notes

The main purpose of this class customisation is to modify the data serialisation behaviour of the graph in the context of element interaction modelling in a model.

Functions¤

clear_edges ¤
clear_edges()

Clear all the edges and connectivity information of the graph.

node_element ¤
node_element(node: int) -> Element

Get the element associated with the node.

Parameters:

  • node (int) –

    The identifier of the node.

Returns:

  • Element –

Model ¤

Model(name=None, **kwargs)

Class representing a general model of hierarchically organised elements, with interactions.

Attributes:

  • tree ((ElementTree, read - only)) –

    A tree representing the spatial hierarchy of the elements in the model.

  • graph ((InteractionGraph, read - only)) –

    A graph containing the interactions between the elements of the model on its edges.

  • bvh ((ElementBVH, read - only)) –

    To recompute the BVH, use compute_bvh. The BVH is used to speed up collision detection: for example, during calculation of element contacts.

  • kdtree ((KDTree, read - only)) –

    To recompute the tree, use compute_kdtree. The KD tree is used for nearest neighbour searches: for example, during calculation of element contacts.

  • transformation (Transformation) –

    The transformation from local to world coordinates.

Notes

A model has an element tree to store the hierarchical relationships between elements, and an interaction graph to store the interactions between pairs of elements. Model elements are contained in the tree hierarchy in tree nodes, and in the interaction graph in graph nodes.

Every model element can appear only once in the tree, and only once in the graph. This means that every element can have only one hierarchical parent. At the same time, independently of the hierarchy, every element can have many interactions with other elements.

Functions¤

add_element ¤
add_element(
    element: Element | ElementType,
    parent: Element | None = None,
    material: Material | None = None,
) -> Element | ElementType

Add an element to the model.

Parameters:

  • element (Element) –

    The element to add.

  • parent (Element, default: None ) –

    The parent element of the element. If None, the element will be added directly under the root element.

  • material (Material, default: None ) –

    A material to assign to the element. Note that the material should have already been added to the model before it can be assigned.

Returns:

  • Element –

    The element added to the model.

Raises:

  • ValueError –

    If the parent node is not a GroupNode.

  • ValueError –

    If a material is provided that is not part of the model.

add_elements ¤
add_elements(
    elements: list[Element | ElementType],
    parent: Element | None = None,
    material: Material | None = None,
) -> list[Element | ElementType]

Add a list of elements to the model.

Parameters:

  • elements (list[Element]) –

    The elements to add.

  • parent (Element, default: None ) –

    The parent element of the elements. If None, the elements will be added directly under the root element.

  • material (Material, default: None ) –

    A material to assign to the elements. Note that the material should have already been added to the model before it can be assigned.

Returns:

  • list[Element] –

    The list of elements added to the model.

Raises:

  • ValueError –

    If the parent node is not a GroupNode.

  • ValueError –

    If a material is provided that is not part of the model.

add_group ¤
add_group(name: str | None = None) -> Group

Add a group to the model.

Parameters:

  • name (str, default: None ) –

    The name of the group.

Returns:

  • class:`Group` –

    The group added to the model.

add_interaction ¤
add_interaction(
    a: Element, b: Element, modifier: Modifier | None = None
) -> tuple[int, int]

Add an interaction between two elements of the model.

Parameters:

  • a (Element) –

    The first element.

  • b (Element) –

    The second element.

Returns:

  • tuple[int, int] –

    The edge of the interaction graph representing the interaction between the two elements.

Raises:

  • Exception –

    If one or both of the elements are not in the graph.

Notes

In future implementations, adding an interaction should implicitly take care of adding modifiers onto the interaction edges, based on the registered modifiers of the source nodes.

In the current implementation, modifiers have to be added explicitly using :meth:add_modifiers. This method will add an interaction edge from the source of the modifier to its target if needed and store the modifier object on it.

add_material ¤
add_material(material: Material) -> None

Add a material to the model.

Parameters:

Returns:

  • None –
add_modifier ¤
add_modifier(source: Element, target: Element, modifier: Modifier) -> list[Modifier]

Add a modifier between two elements, with one the source of the modifier and the other the target.

Parameters:

  • source (Element) –

    The source element.

  • target (Element) –

    The target element.

  • modifiertype (Type[Modifier]) –

    The type of modifier.

Returns:

  • list[Modifier] –

    All modifiers stored on the interaction edge between source and target.

Notes

This element should implement the protocol specified by the modifier. The methods of the source element defined by the protocol are used to compute the tools involved in the modification. The tools are used by the modifier to apply the modification to the model geometry of the target element.

The modifier defines the protocol for the modification. The protocol should be implemented by the source element. The protocol methods of the source element are used to compute the modification tool. The modifier applies the modification to the target using this tool.

add_or_get_material ¤
add_or_get_material(material: Material) -> Material

Add a material to the model or retrieve an existing instance of the same type.

Parameters:

Returns:

assign_material ¤
assign_material(
    material: Material,
    element: Element | None = None,
    elements: list[Element] | None = None,
) -> None

Assign a material to an element or a list of elements.

Parameters:

  • material (Material) –

    The material.

  • element (Element, default: None ) –

    The element to assign the material to.

  • elements (list[Element, optional], default: None ) –

    The list of elements to assign the material to.

Returns:

  • None –

Raises:

  • ValueError –

    If neither element or elements is provided.

  • ValueError –

    If both element and elements are provided.

  • ValueError –

    If the material is not part of the model.

  • ValueError –

    If the provided element or one of the elements in the provided element list is not part of the model.

compute_bvh ¤
compute_bvh(
    nodetype=ElementAABBNode, max_depth: int | None = None, leafsize: int = 1
) -> ElementBVH

Compute the Bounding Volume Hierarchy (BVH) of the elements for fast collision checks.

Parameters:

  • nodetype (ElementOBBNode, default: ElementAABBNode ) –

    The type of bounding volume node used in the tree.

  • max_depth (int, default: None ) –

    The maximum depth used for constructing the BVH.

  • leafsize (int, default: 1 ) –

    The number of elements contained in a BVH leaf node.

Returns:

  • ElementBVH –
compute_contacts ¤
compute_contacts(
    tolerance=1e-06, minimum_area=0.01, contacttype: Type[Contact] = Contact
) -> None

Compute the contacts between the block elements of this model.

Computing contacts is done independently of the edges of the interaction graph. If contacts are found between two elements with an existing edge, the contacts attribute of the edge will be replaced. If there is no pre-existing edge, one will be added. No element pairs are excluded in the search based on the existence of an edge between their nodes in the interaction graph.

The search is conducted entirely based on the BVH of the elements contained in the model. It is a spatial search that creates topological connections between elements based on their geometrical interaction.

Parameters:

  • tolerance (float, default: 1e-06 ) –

    The distance tolerance.

  • minimum_area (float, default: 0.01 ) –

    The minimum contact size.

Returns:

  • None –
compute_kdtree ¤
compute_kdtree() -> KDTree

Compute the KD tree of the elements for fast nearest neighbour queries.

The KD tree is built using the reference points of the elements of the model.

Returns:

  • class:`KDTree` –
element_nnbrs ¤
element_nnbrs(element: Element, k=1) -> list[tuple[Element, float]]

Find the nearest neighbours to a root element.

Parameters:

  • element (Element) –

    The root element.

  • k (int, default: 1 ) –

    The number of nearest neighbours that should be returned.

Returns:

  • list[tuple[Element, float]] –

    A list of nearest neighbours, with each neighbour defined as an element and the distance of that element to the root element.

elements ¤
elements() -> Iterator[Element]

Iterate over the elements contained in the model.

Returns:

find_all_elements_of_type ¤
find_all_elements_of_type(elementtype: Type[Element]) -> list[Element]

Find all model elements of a given type.

Parameters:

  • elementtype (Type[Element]) –

    The type of element.

Returns:

find_element_with_name ¤
find_element_with_name(name: str) -> Element | None

Returns True if the model contains an element with the given name.

Parameters:

  • name (str) –

    The name to check.

Returns:

  • Element or None –
has_element ¤
has_element(element: Element) -> bool

Returns True if the model contains the given element.

Parameters:

  • element (Element) –

    The element to check.

Returns:

has_element_with_name ¤
has_element_with_name(name: str) -> bool

Returns True if the model contains an element with the given name.

Parameters:

  • name (str) –

    The name to check.

Returns:

has_interaction ¤
has_interaction(a: Element, b: Element) -> bool

Returns True if two elements have an interaction set between them.

Parameters:

  • a (Element) –

    The first element.

  • b (Element) –

    The second element.

Returns:

has_material ¤
has_material(material: Material) -> bool

Verify that the model contains a specific material.

Parameters:

  • material (Material) –

    A model material.

Returns:

materials ¤
materials() -> Iterator[Material]

Iterate over the materials stored in the model.

Returns:

point_nnbrs ¤
point_nnbrs(point, k=1) -> list[tuple[Element, float]]

Find the nearest neighbours to a point.

Parameters:

  • point (Point) –

    The root point.

  • k (int, default: 1 ) –

    The number of nearest neighbours that should be returned.

Returns:

  • list[tuple[Element, float]] –

    A list of nearest neighbours, with each neighbour defined as an element and the distance of that element to the root element.

remove_element ¤
remove_element(element: Element) -> None

Remove an element from the model.

Parameters:

  • element (Element) –

    The element to remove.

Returns:

  • None –
remove_elements_of_type ¤
remove_elements_of_type(elementtype: Type[Element]) -> list[Element]

Remove all model elements of a given type.

Parameters:

  • elementtype (Type[Element]) –

    The type of element.

Returns:

  • list[Element] –

    The removed elements.

remove_interaction ¤
remove_interaction(a: Element, b: Element) -> None

Remove the interaction between two elements.

Parameters:

  • a (Element) –
  • b (Element) –

Returns:

  • None –
transform ¤
transform(transformation: Transformation) -> None

Transform the model and all that it contains.

Parameters:

  • Transformation –

    The transformation to apply.

Returns:

  • None –

    The model is modified in-place.