Entity Selection via Collections#

Most of the operations in HyperMesh performed by the user require an input entity selection provided via the interactive entity selector widget. The entity selection is internally translated into a so-called mark which is then subsequently passed to the HyperMesh function. In Tcl API, the marks can be created using the *createmark command (and its derived functions). User can create two marks per entity type simultaneously (a mark with ID 1 and ID 2). A mark is not persistent in the session, hence it needs to be defined just before calling the command that requires it as an input.

In Python API, the entity selection is provided through the Collection class. An entity selection is represented by a collection object which is persistent throughout the session and user can create an arbitrary number of collections per entity type. The requirement is that only one entity type can be present in a single collection and all entities must belong to the same model. Collections are iterable, meaning you can loop over them to perform operations on individual entity objects inside (see snippet below).

import hm
import hm.entities as ent

model = hm.Model()
elems = hm.Collection(model,ent.Element)

# Quering element IDs from a collection
for e in elems:
    print(e.id)

Collections do not behave like Python sequences. They are not ordered and you cannot directly extract items from them:

e1 = elems[0] # NOT SUPPORTED

Grabbing an individual item from a collection requires the collection to be converted into a Python list. This operation can be expensive on a large collection as it requires the generation of Python entity object for each entity in the collection:

e1 = list(elems)[0]

Basic Operations#

The Collection constructor offers multiple ways of defining the collection content. The two basic options are: defining a collection of all entities and defining an empty collection.

# Collection of all elements in the model
elems = hm.Collection(model,ent.Element)

# Empty collection of elements
empty_elem_col = hm.Collection(model,ent.Element,populate=False)

The empty collection is typically used as an input argument for functions that populate the collection with entities.

Advanced Methods#

HyperMesh Python API allows user to create collections using more advanced methods, either via specialized functions or via filters.

In the hm Module, you will find four specialized functions that return a collection object:

  • CollectionByAdjacent - creates a collection of entities adjacent to the entities in the source collection.

  • CollectionByAttached - creates a collection of entities attached to the entities in the source collection.

  • CollectionByDisplayed - creates a collection of displayed entities.

  • CollectionByFace - creates a collection of entities that represent the same face as the entities in the source collection.

Filter classes provide an additional mechanism to define more complex rules of creating an entity collection.

The three standard filters are:

  • FilterByAttribute - entity selection based on their properties/attributes. The search string follows the same syntax as the Browser search in the GUI (see Find and Search for Entities for more information).

  • FilterByCollection - entity selection by reference (e.g. elements by properties, nodes by elements etc.).

  • FilterByEnumeration - entity selection by providing a list UIDs, either entity IDs or names.

Once the filters are defined, they can be passed to the Collection constructor as an argument.

# FilterByAttribute
rule = hm.FilterByAttribute(ent.Property,"PSHELL_T<2.5 AND PSHELL_T>1.5")
props = hm.Collection(model,rule)

# FilterByCollection
rule = hm.FilterByCollection(ent.Element,ent.Property)
props = hm.Collection(model,ent.Property,'id=103,104')
elems = hm.Collection(model,rule,props)

# FilterByEnumeration
rule = hm.FilterByEnumeration(ent.Property,[103,104,201,202])
props = hm.Collection(model,rule)

The Collection constructor provides several ways of embedding the rules in the constructor, bypassing the creation of a filter object.

Below figures show how to use a FilterByAttribute search string directly inside the constructor.


A screenshot of a computer Description automatically generated A computer code with black text Description automatically generated

Figure 1. Collection of properties containing “Outer” in the name.


image1 A computer screen shot of a computer code Description automatically generated

Figure 2. Collection of properties with thickness greater than 1.5 and less than 2.5.


FilterByEnumeration can be substituted by directly passing a list of identifiers to the constructor:

hm.Collection(model, ent.Component, [1, 2])
hm.Collection(model, assem.Part, ['abc', 'xyz'])

FilterByCollection can be substituted by passing the source collection to the constructor:

elems = hm.Collection(model, ent.Element, hm.Collection(m, ent.Component, [1,2]))

Alternatively, a list of entity objects can be defined and passed as an argument:

elems = hm.Collection(model, ent.Element, [objcmp1, objcmp2, ... ])

The following filters allow selecting entities based on their position in space by prescribing a geometrical primitive:

  • FilterByBox - select entities inside a box.

  • FilterByCone - select entities inside a cone.

  • FilterByCylinder - select entities inside a cylinder.

  • FilterByInfiniteCylinder - select entities inside an infinite cylinder (i.e. within a distance from an axis).

  • FilterByPlane - select entities withing a distance from a plane.

  • FilterBySphere - select entities inside a sphere.

Interactive Selection#

A collection object can be also created by selecting entities interactively in the graphics area using CollectionByInteractiveSelection function. Upon calling this function, an entity selector widget will be posted in the graphics area and after finalizing the selection, the function will return a collection object.

elems = hm.CollectionByInteractiveSelection(model,ent.Element)

A wireframe of a metal object Description automatically generated

Figure 3. Interactive entity selection using the selector widget.

Arithmetic Operations#

Collections and entity objects also support arithmetic operators. Collections can be combined or subtracted from each other using the + or - operators. Alternatively, they can be modified by adding or subtracting specific entity objects or a list of entity objects. The collections and entity objects used in these operations must be of the same entity type.

collection_object3 = collection_object1 + collection_object2

new_collection_object = collection_object + entity_object

new_collection_object = collection_object - entity_object

new_collection_object = collection_object + [entity_object1, entity_object2]

new_collection_object = collection_object - [entity_object1, entity_object2]

Collection Set#

A CollectionSet is a collection of collections. It can contain only one collection per entity type. Collection sets are typically used in functions to supply multiple collections of different entity types as a single argument. Another common use case is user supplying an empty collection set to a function that populates it with multiple entity collections. Below is an example of creating a collection set of two different entity types: LoadForce and LoadMoment.

# Collection of all forces in the model
loadF_col = hm.Collection(model,ent.LoadForce)

# Collection of all moments in the model
loadM_col = hm.Collection(model,ent.LoadMoment)

# Creating the collection set
colset = hm.CollectionSet(model)

# Adding forces collection in collection set
colset.set(loadF_col)

# Adding moments collection in collection set
colset.set(loadM_col)