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

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

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.

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

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.

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.

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