12.0 API Programmer's Guide

ID Management

A new ID Manager has been added in HyperMesh 12.0 and will be officially released in HyperMesh 12.0.110. The ID range for each entity type in each sub-model (like an include file) can be defined to position the entity IDs. For example, there are two includes in HyperMesh. The ID range for include1 is 1001-2000 (min-max) while include2 has 3001-4000. If include1 is set as current, when a new entity is created or imported, the ID for this new entity will be between 1001 to 2000, not the ID with [max id +1] in current HyperMesh. Similarly, if include2 is set as current, a new created entity ID will be between 3001-4000.

Because of this, some usage of the command hm_entitymaxid will not make sense and needs to be updated to use new commands. The command hm_entitymaxid still returns the maximum database ID in use. However, there are other "unsupported" uses of this command that will no longer work, so it is mandatory to update scripts to use the new APIs for those usages.

Currently there are two main usages of hm_entitymaxid:
  1. To get latest created entity ID. For example:
    proc CreateGRNOD { args } {
    set d_nodesList [lindex $args 0];
    if { [llength $d_nodesList] } {
        set str_setName [::hwat::utils::GetUniqueName sets [lindex $args 1]];
        eval *createmark nodes 1 $d_nodesList;
        *entitysetcreate "$str_setName" nodes 1;
        *createmark sets 1 -1;
        *dictionaryload sets 1 $::str_templatePath "GRNOD";
        return [hm_entitymaxid sets];
    } else {
        return 0;
    }
}
  2. To get a unique ID number to assign to a name for an entity. For example:
    proc HandleNewInDefineMaterialProperties { args } {
    # First find out the maximum material ID used.
    set max_mat_col_id [hm_entitymaxid mats];
    
    # The new material ID will be one more than the existing maximum mat ID.
    set ::material_id [ expr { $max_mat_col_id + 1 }];
    
    # Set the default mu value.
    set ::material_mu 0.2;
    
    # Set the Material collector default name by adding name and ID.
    # This is to make sure that it is a unique name.
    set ::material_name "";
    append ::material_name "TARGET_CONTACT" "_MAT_" $::material_id;
}
To cover these two use cases, new commands have been created to replace hm_entitymaxid.
  1. Use new command hm_latestentityid. It is mandatory to update scripts to replace hm_entitymaxid for these use cases. For example:
    proc CreateGRNOD { args } {
    set d_nodesList [lindex $args 0];
    if { [llength $d_nodesList] } {
        set str_setName [::hwat::utils::GetUniqueName sets [lindex $args 1]];
        eval *createmark nodes 1 $d_nodesList;
        *entitysetcreate "$str_setName" nodes 1;
        *createmark sets 1 -1;
        *dictionaryload sets 1 $::str_templatePath "GRNOD";
        return [hm_latestentityid sets];
    } else {
        return 0;
    }
}
  2. Use hm_entityinfo maxid. This is not mandatory, as hm_entitymaxid behaves the same as in previous versions for this case. For example:
    proc HandleNewInDefineMaterialProperties { args } {
    # First find out the maximum material ID used.
    set max_mat_col_id [hm_entityinfo maxid mats];
    
    # The new material ID will be one more than the existing maximum mat ID.
    set ::material_id [ expr { $max_mat_col_id + 1 }];
    
    # Set the default mu value.
    set ::material_mu 0.2;
    
    # Set the Material collector default name by adding name and ID.
    # This is to make sure that it is a unique name.
    set ::material_name "";
    append ::material_name "TARGET_CONTACT" "_MAT_" $::material_id;
}

    However, for the use case of generating a unique name, the command hm_getincrementalname can be used and is a better choice:

    proc HandleNewInDefineMaterialProperties { args } {
    set ::material_name [hm_getincrementalname materials TARGET_CONTACT_MAT_]
}

A new API, hm_entityrecorder, has also been added to "record" the IDs of the entities created while the recorder is enabled.

In addition, the behavior of selecting recently created entities using negative values using *createmark/hm_createmark has been improved. Previously, the values returned by this functionality were always the highest entity IDs, which is how entities were previously numbered during creation. With the new ID Management functionality, this now more accurately returns the recently created entity IDs and matches the return values of hm_latestentityid. In essence, this now selects entities in the reverse order they are stored in the database (the order they are created, regardless of ID). However, any operations that affect the order of entities in the database (organize, reorder, etc...) will change the returned/selected entities. As in previous releases, it is recommended to use this option only immediately after entity creation and before any other operations that may modify the database.

Solve Templates

There have been a few changes and bug fixes in the HyperMesh template system while updating to a new infrastructure. With these updates, the following behaviors and corrections must now be noted:
  • *beforecollector(), *aftercollector()

    The published specification did not permit the use of these for anything other than elements, loads, equations, vectors, systems, and beamsections. However, the template interpreter never enforced that restriction, so many templates were written that used these commands improperly. Now, this restriction will be enforced. If you try to output a model through a template, and see an error message that looks like "*beforecollector() command not valid for nodes. Please move the code inside *beforecollector() to *before() and remove *beforecollector()" then you will need to modify the custom template to conform.

    For nodes, components, control cards, properties, materials and multibodies, you will get the same behavior as before by moving any code from a *beforecollector() block to the *before() block, and any code from a *aftercollector() block to the *after() block. For all other entity types, to get the same behavior as before, such code should be consolidated into the *format() block.

  • There are a few places where the template parser has become more strict in usage. This also affects Tcl scripts.
    • The set entity types "component", "property", "material", "assembly", "node", and "element", now must be spelled correctly. Before, a haphazard variety of abbreviations and misspellings were permitted. An error message "Parameter in function defining entity type <entity_type> contains an error" will now be posted upon encountering such an error.
    • @getentityvalue() now requires that its entity type name be spelled correctly. Before, a haphazard variety of abbreviations and misspellings were permitted. An error message "Parameter in function defining entity type <entity_type> contains an error" will now be posted upon encountering such an error.
    • The dataname "collector" was incorrectly permitted in unexpected places, but ignored except when legal. Now, this misuse will be an error "Unknown <entity type> data type 'collector' found in file". For example, some templates used it like this:
      *loadsteps()
    *format()
    *string("A loadstep: ")
    *field(int, collector.id, 10)
    *string(",")
    *field(string, collector.name, 0)
    *end()
*output()
      However, there is no collector data name for loadsteps. What is really intended is:
      *loadsteps()
    *format()
    *string("A loadstep: ")
    *field(int, id, 10)
    *string(",")
    *field(string, name, 0)
    *end()
*output()
    • It is now an error to use the obsolete load data names "location" and "nodelocation" for anything other than for loads applied to nodes or elements. It used to silently fail, without any kind of error message. The error is "Unknown load data type 'location' found in file" or "Unknown load data type 'nodelocation' found in file".

FE Input and Results Readers

Eventually, the HyperMesh database will support full part-instancing, and module-restricted ID-spaces for entities (that is, 2 different elements with Id=1, in separate include files). To allow for this upgraded power, now include files should not be sent to HyperMesh before their parent files have been sent for custom FE Input readers. It used to be that the order received was irrelevant.

Compilers

HyperWorks 12.0 has been upgraded to use new compilers. This means that users compiling custom FE Input and Result Readers, or ExtAPI programs, need to be aware of the following compiler support:
  • Windows: Visual Studio 2010 SP1
  • Linux: gcc version 4.4.4 20100726 (Red Hat 4.4.4-13) (GCC)
  • Mac: clang version 3.1 (tags/Apple/clang-318.0.58) (based on LLVM 3.1svn)

New Commands

Modified Commands

  • Collision
  • General/Core
    • hm_entityinfo – Added new option maxid. hm_entitymaxid– Use hm_entityinfo maxid, hm_entityrecorder or hm_latestentityid instead, depending on the use case. See the ID Management topic above for more details.
    • hm_info – Added new options lodthreshold and retainloads.
    • *createmark/*appendmark/hm_createmark/hm_appendmark – Support has been added to the "by box", "by cylinder" and "by sphere" methods for selecting entities that span across the shape boundary by specifying "acrossboundary" as the location.
    • *createmark/*appendmark/hm_createmark/hm_appendmark – The behavior of selecting recently created entities using negative values has been improved. Previously, the values returned by this functionality were always the highest entity IDs, which is how entities were previously numbered during creation. With the new ID Management functionality, this now more accurately returns the recently created entity IDs and matches the return values of hm_latestentityid. In essence, this now selects entities in the reverse order they are stored in the database (the order they are created, regardless of ID). However, any operations that affect the order of entities in the database (organize, reorder, etc...) will change the returned/selected entities. As in previous releases, it is still recommended to use this option only immediately after entity creation and before any other operations that may modify the database.
    • *createmark/*appendmark/hm_createmark/hm_appendmark – The "by block" selection method has been updated to use the smaller of the global node tolerance, or 1/200 of the smallest block dimension, for the selection tolerance.
  • GUI
    • hm_framework – Added new option getmenustatus. Added new option setnativeheight. Added new optional argument height to drawpanel, which changes the previous default behavior for sizing of the panel area.