HyperMesh Functions#

HyperMesh services can be accessed as instance methods of the Model class. When calling a model method, it is always executed on the HyperMesh model associated with the model object.

Python API gives user the access to the same functionalities as exposed via Tcl API. The Tcl documentation recognizes three command categories - GUI commands, Modify commands, and Query commands.

Only a subset of GUI commands is exposed in Python API. Historically, most of the commands have been linked to the old Tk-based interface and are gradually being replaced with Python API native to the new UI architecture.

In general, both set of APIs expose the same core functions, hence they operate with the same input arguments. However, the signatures of the Python functions have been adopted to fit the Python concepts such as the usage of collections instead of marks, entity objects instead of IDs, etc. The argument names have also been adopted to be technically accurate, but the names of the functions have been kept the same so users can easily find references in the documentation.

Tcl vs Python Signatures#

Let us have a quick look at few differences and commonalities between the same function exposed in Tcl and Python.

Translating elements via *translatemark command in Tcl requires providing four inputs - the entity type and mark ID (i.e. the input entity selection), the direction vector (provided via *createvector command) and the distance (e.g. 500.0).

*translatemark entity_type mark_id vector_id distance

image2

Figure 1. List of inputs for Tcl command *translatemark.


A close-up of text Description automatically generated

Figure 2. Code snippet from the Tcl console showing the usage of *translatemark command.


In Python, entity_type and mark_id are replaced with a single collection argument (note: a collection object is aware of which entity type it collects). The directional vector is no longer defined via a dedicated command, it is represented by a data type - hwTriple. The distance (float) argument is exposed the same way in both languages.

elems = hm.Collection(model,ent.Element)
model.translatemark(collection=elems,vector_id=hm.hwTriple(0.0,0.0,1.0),distance=500.0)

Argument Comparison Table#

As explained in the previous section, the signatures of the Python functions differ from the Tcl command signatures in places where the argument refers to a specific HyperMesh data type. Strings, integers, floats, etc. are exposed the same way in both interfaces. The table below highlights the main differences between Tcl and Python function signatures based on the argument types.

Tcl Argument Type

Python Argument Type

entity_type + mark_id

Collection

mark_id (when only one entity type is supported)

Collection

mark_id (multiple entity types are supported)

CollectionSet

entity_type + entity_id

Entity object

entity_type + list_id

EntityList

list_id (when only one entity type is supported)

EntityList

entity_id (when only one entity type is supported)

Entity object

entity_type

Entity class

Certain Tcl arguments use auxiliary commands to define the required input. For example, the above mentioned *translatemark uses *createvector to define the vector argument. In Python, these types of arguments are represented by a dedicated data type available in the HyperMesh module. No extra function is required to be executed prior to the main command. Instead of using *createvector, user needs to define a hwTriple object.

The table below lists the most common Tcl commands that are redundant in the Python API and are substituted by a HyperMesh data type.

Tcl Command

Python Argument Type

*createvector

hwTriple

*createplane

2x hwTriple

*createarray

hwIntList

*createintarray2d

hwIntList2

*createdoublearray

hwDoubleList

*createdoublearray2d

hwDoubleList2

*createstringarray

hwStringList

Implicit Conversion#

The HyperMesh data types ensure that the correct information is passed to the core function. For example, hwTriple can only represent a list of three doubles. If a function requires a list of three doubles, the argument is defined via hwTriple. As a result, the function knows it will receive the correct data without having to do extra checks (passing two or four values would fail at the point of constructing the hwTriple object).

The conversion mechanism allows user to supply a native Python data type as the argument value and it will internally convert it to the respective HyperMesh data type. See the table below for the list of HyperMesh data types supported by the implicit conversion.

HyperMesh Data Type

Python Data Type

EntityList

List of entity objects

EntityList2

2D list of entity objects

hwDoubleList

List of doubles

hwDoubleList2

2D list of doubles

hwBoolList

List of Bool values

hwIntList

List of integers

hwIntList2

2D list of integers

hwMatrix44

List of 16 doubles

hwString

String

hwStringList

List of string values

hwTriple

List of 3 doubles

_EntityFullTypeList_vector

List of entity classes

_EntityFullTypeList_vector is a special data type that does not have a Python class representation. It is constructed internally from a list of Python entity classes.

Example - Find the elements and nodes in a radius of 20.0 around element ID 1229#
import hm
import hm.entities as ent

model = hm.Model()

output_col_set = hm.CollectionSet(model)

# List of entity classes representing _EntityFullTypeList_vector
ent_class_list = [ent.Node, ent.Element]

status = model.hm_getnearbyentities(
   input_entity_collection=hm.Collection(model, ent.Element, [1229]),
   output_entity_collection=output_col_set,
   radius=20.0,
   outputentitytypes=ent_class_list,
)

# Print the type of each collection inside the populated collection set
for collection in outccset:
   print(f"Collection Entity Type {collection}")

Status Object#

All HyperMesh functions return a status object. Most of the query functions also return a result object which is covered in the next section. The status objects let you review the message returned by the function and the status returned by the core function.

Status value 0 indicates successful execution. If the function fails, a Python error is triggered.

A screen shot of a computer Description automatically generated

Figure 3. Python Window showing the usage of status object.

errorPythonImage

Figure 4. Python Window showing the error triggered by incorrect argument definition.

Query Functions#

The name of query functions always starts with “hm_”. Their characteristic is that most of them, beside returning a status object, return also a result object that carries the queried information. There are two types of result objects/classes - HmQueryResult and HmQueryResultList.

HmQueryResult is a HyperMesh data type that by default has the attribute keys which returns a list of all attributes that carry the information returned by the function. Below is an example of hm_getmass() function that returns the total mass, total volume, and total area.

A screenshot of a computer code Description automatically generated

Figure 5. Python Window showing the usage of query result object.

HmQueryResultList represents a list of HmQueryResult objects. A HmQueryResultList object can be returned directly by a function, or in case of more complex query functions it can be returned by one of the HmQueryResult attributes. Below example shows a HmQueryResultList object returned by hm_metadata_all() function. User can check the length of the object using Python’s len(), grab individual HmQueryResult objects and query their content.

image3

Figure 6. Python Window showing the usage of status object.

Split Functions#

Some of the HyperMesh core functions have been split into multiple Python functions with different signatures. For example, in Tcl user will find a single command to query metadata called hm_metadata. In Python, the command is split into four functions - hm_metadata_all, hm_metadata_bycollection, hm_metadata_byentitytype, hm_metadata_byname. Table below lists the most notable split functions and their Tcl counterpart.

Python Function

Tcl Command

CE_ConnectorLineCombine_bycollection

*CE_ConnectorLineCombine

CE_ConnectorLineCombine_byentitylist

CE_ConnectorLineCombineWithCC_bycollection

*CE_ConnectorLineCombineWithCC

CE_ConnectorLineCombineWithCC_byentitylist

CE_FE_UnregisterRealizedEntities_byallentitytypes

*CE_FE_UnregisterRealizedEntities

CE_FE_UnregisterRealizedEntities_bycollection

CE_FE_UnregisterRealizedEntities_byentitytype

compositeanalysis_bycollection

*compositeanalysis

compositeanalysis_byentity

compositeanalysis_byname

convertunit_bycollection

*convertunit

convertunit_bytype

createelements1d_bycollection

*createelements1d

createelements1d_byentitylist

hideentity_byname

*hideentity

hm_attributeentitytype_byentityname

hm_attributeentitytype

hm_attributeidentifier_byentityname

hm_attributeidentifier

hm_attributeindexentitytype_byentityname

hm_attributeindexentitytype

hm_attributeindexentitytypename_byentityname

hm_attributeindexentitytypename

hm_attributeindexidentifier_byentityname

hm_attributeindexidentifier

hm_attributeindexsolver_byentityname

hm_attributeindexsolver

hm_attributeindexstatus_byentityname

hm_attributeindexstatus

hm_attributeindextype_byentityname

hm_attributeindextype

hm_attributeindextypename_byentityname

hm_attributeindextypename

hm_attributelist_byentityname

hm_attributelist

hm_attributesolverarrayvalues_byentityid

hm_attributesolverarrayvalues

hm_attributesolverarrayvalues_byentityname

hm_attributetype_byentityname

hm_attributetype

hm_attributetypename_byentityname

hm_attributetypename

hm_ce_linkprojectionorderget_bycollection

hm_ce_linkprojectionorderget

hm_ce_linkprojectionorderget_byentity

hm_clearmarker

hm_clearmarker

hm_clearmarker_bycollection

hm_clearmarker_byentity

hm_clearshape

hm_clearshape

hm_clearshape_bycollection

hm_clearshape_byentity

hm_defaultstatus_byentity

hm_defaultstatus

hm_defaultstatus_byname

hm_entityincollector_byentity

hm_entityincollector

hm_entityincollector_byname

hm_entityrecorder_switch

hm_entityrecorder

hm_getconfigtypecountincol_byentity

hm_getconfigtypecountincol

hm_getconfigtypecountincol_byname

hm_getconfigtypeincol_byentity

hm_getconfigtypeincol

hm_getconfigtypeincol_byname

hm_getcrossreferencedentities_byname

hm_getcrossreferencedentities

hm_getfilletfaces_fromcollection

hm_getfilletfaces

hm_getincludesentities_byids

hm_getincludesentities

hm_getincludesentities_bynames

hm_getinternalid_bypoolid

hm_getinternalid

hm_getinternalid_bypoolname

hm_getinternalidlist_bypoolid

hm_getinternalidlist

hm_getinternalidlist_bypoolname

hm_getinternalname_bypoolid

hm_getinternalname

hm_getinternalname_bypoolname

hm_getreferencedentities_byname

hm_getreferencedentities

hm_getsolverids_byentity

hm_getsolverids

hm_getsolverids_byname

hm_getsurfacethicknessvalues_bycollection

hm_getsurfacethicknessvalues

hm_getsurfacethicknessvalues_byentity

hm_gettablecolumndata_byentity

hm_gettablecolumndata

hm_gettablecolumndata_byname

hm_getunusedoremptyentities_bycollection

hm_getunusedoremptyentities

hm_getunusedoremptyentities_byentity

hm_getunusedoremptyentities_byname

hm_getuvvectors_bynode

hm_getuvvectors

hm_getuvvectors_bypoint

hm_getuvvectors_byxyz

hm_isentitydatanameparameterized_byentity

hm_isentitydatanameparameterized

hm_metadata_all

hm_metadata

hm_metadata_bycollection

hm_metadata_byentitytype

hm_metadata_byname

hm_morph_getdomainarcangle_bybaseandaxis

hm_morph_getdomainarcangle

hm_morph_getdomainarcangle_byentity

hm_morph_getdomainradius_bybaseandaxis

hm_morph_getdomainradius

hm_morph_getdomainradius_byentity

hm_plotloads_bycollection

hm_plotloads

hm_plotloads_byentity

hm_plotmarker_bycollection

hm_plotmarker

hm_plotmarker_byentity

hm_plotshape_bycollection

hm_plotshape

hm_plotshape_byentity

hm_visualizeloads

hm_visualizeloads

hm_visualizeloads_clearall

hm_wadlinessetentities_bycollection

hm_wadlinessetentities

hm_wadlinessetentities_bymode

isolateonlyentity_byname

*isolateonlyentity

modelcheck_applyautocorrection_byallentitytypes

*modelcheck_applyautocorrection

modelcheck_applyautocorrection_bycollection

modelcheck_applyautocorrection_byentitytype

modelcheck_runchecks_byallentitytypes

*modelcheck_runchecks

modelcheck_runchecks_bycollection

modelcheck_runchecks_byentitytype

positionentity_bycollection

*positionentity

realizeentity_fields_byentity

*realizeentity_fields

realizeentity_fields_byname

reviewentity_byname

*reviewentity

setmeshparams_byedgecollection

*setmeshparams

setmeshparams_byentity

setmeshparams_byfacecollection

setmeshparams_bynodepair

showentity_byname

*showentity