Author Custom Methods

Register new methods and save/import existing libraries. The following chapter, Method Manager, shows these steps in more detail.

Method Entity Structure

To understand the required steps, you should be familiar with the structure of methods and libraries.

A library is a collection of method definitions as well as user attribute definitions which can be re-used. Libraries are saved/imported as *.xml files that must be in the below form:


Figure 1. User method file schema

It requires a main block <root> which contains a list of <method> tags.

You can optionally add attribute name=”user library name” at the <root> level. The user name displays in the Method Manager.

It requires a main block <root> which contains a list of <method> tags.

A method is:

  • A reference to a function, such as retval=myfunc(x,y,z), defined in an external file (Compose, Python, Tcl, DLL)
  • the ordered list of input arguments mapping
  • the ordered list of output argument names
  • optionally, a post evaluation sorting (aggregation)
See Figure 1.

Method Attributes

The method tag, in xml, requires some mandatory attributes. (Figure 1)

displayname=" "
The name displayed in the Method Manager dialog. It serves as an identifier key.
When a designpointmethod entity is created in the HyperMesh database, it comes with an ID, a name (HyperMesh entity name) and an attribute Method which will be set to the value of displayname from the .xml file.


Figure 2. Method Entity Editor
On run, the method definition is found from the available registered libraries by displayname key.
Note: The name must be unique across all registered methods.
type="DLL | PYTHON | COMPOSE | TCL"
The engine used to run the method. It is saved as dataname “Engine” in a HyperMesh designpointmethod entity (Figure 2).
path=" "
The file path of the Python/Compose/Tcl file where functions are defined. It can be either an absolute path or a relative path from the library file path.
name=" "
The true function name as defined in the Compose/Python/Tcl file.
category="Rivet | Spring | Panel_metallic | Panel_composite | Generic"
Used to filter the list of available methods in the UI. Category value is on par with designpointset config.
The following arguments are optional arguments that add options in method UI for result extraction that you can change at run time.
corner= ”true |false” (def false)
resavg=”none |simple |min |max |ext | sum” (def: none)
hideoption=”true |false”
Allows the author to set the default for corner and resavg, but disables you from changing them.

Then, two tags are mandatory to specify the input parameters and method outputs:

InputArgList
Defines mapping between method inputs and model/result/user keys to query from the engines. The list of parameters must be ordered in the same way as the method arguments.
A list of attributes is pre-defined in the installation. These attributes are <name-value> pairs which are resolved based on the current solver at run-time. It aims to register reusable methods by defining a mapping not tied to a solver keyword (as much as possible).
Should this default set of attributes lack the desired key to be queried, you can add your own attribute in the library to be consumed by methods (see User Attribute Registration).
Parameters mapped to attributes are automatically queried and passed to the method for evaluation. Some of these attributes are not editable (result values come from result files) while some can be edited in the HyperMesh database (for instance, material allowable or method/structural property data names). In some scenarios, the method requires some other input that has no existing placeholder in HyperMesh:
  • Material extra allowable is not available in the solver decks (like out-of-plane shear limit)
  • Method specific buckling factor is not available as a regular entity data name
In such cases, it is possible to extend the database by dynamically adding a placeholder to destination bind. The parameter will be declared as userinput=”1”. Then, entitytype= "a valid HyperMesh entity type" where the data will be attached to. The choice of a bind depends on granularity expected; typical use cases are:
designpointmethod
method level parameter
  • method specific parameter
  • same for all structural elements being evaluated
structuralproperty
structural property level parameter
  • argument can vary per structural element
property (props)
attribute assigned to FE property
material(mats)
material allowable
  • intrinsic to the material itself
If entitytype is either property or material, the engine looks for metadata available on that entity with the same name as attribute name=”” in the xml. The type of the metadata is defined by the attributes:
  • name=””: metadata name used to query value
  • datatype=””: double |integer | string
  • value=””: default value used when metadata is auto created
If entitytype is either designpointmethod or structuralproperty other options are available:
  • displayname =””: name of the attribute displayed in the UI (can be different from name).
  • allowables =”” space separated list of allowable values. Rendered as combo box in the UI.
  • differentiator=””:
    • fileopen |filesave: Render strings as file open/save widget.
    • checkbox: Renders the integer as boolean checkbox.
Dynamic data names are added to designpointmethod (resp structuralproperty) along with regular data names that come with the selected config. These are not metadata anymore. In the following example, a string condition was added (called condition) to a designpointmethod. It accepts two values:
  • Condition1
  • Condition2


    Figure 3.
When created from this template, the method is shown as:


Figure 4.
Metadata values
When the engine runs a method with definition that uses user input parameters, it expects that the data exists at run-time. The engine always uses values defined at the entity level in the database no matter the value set in xml.
Dynamic data names on designpointmethod are added when method is created. For other entities the following logic applies when method is assigned (to designpointset) or selected to run:
Scan entities where method is run and create relevant dynamic data names or metadata only if they do not exist. Property and material assigned to structuralproperty takes precedence over element property if metadata needs to be assigned.
If property (material) already has metadata with the same name, keep it unchanged. Otherwise, if the metadata cannot be found, it is added with the default value from xml, if specified.
OutputArgList
Methods can output multiple (pre-defined) results.
Variable number of outputs is not supported. You can give a display name (in ordered way) for each method output. This name will become the header of the method table column (Figure 5).
One (and only one) of the <Parameter> tags used in the OuptuArgList can have an attribute marginofsafety="1".
Whenever multiple methods are assigned to the same location, an extra consolidated table is created considering all methods having one attribute with marginofsafety="1". Then, methods are compared against each other using as a metric the parameter tagged as marginofsafety.
Figure 5. Method table: Input & Output

Sorting

Inside method registration, it is possible to add a Sort block. As a result, the method will still be evaluated for each entity inside a designpoint (element | layer) as well as each loadcase.

However, after method run, an aggregation is performed on a Domain using a metric and envelope type. The result of this aggregation is that table output by method will retain only aggregated values. The envelope type can be spatial and/or on loadcases depending on the domain (Figure 6).

Type (of envelope)
Valid types are:
  • Min
  • Max
  • AbsMin
  • AbsMax
Value
The value can be any float parameter either from InputArgList or OutputArgList. It is used as comparison metric.
Domain
Domain can be a combination of multiple keys in the following list:
  • DDP
  • entityid
  • elementid
  • nodeids
  • layerindex
  • loadcase
As soon as one of these keys is missing, an aggregation occurs along this dimension. For example, a domain made of successive calls.
  • DDP |entityid |elementid|layerindex |nodeids: Performs a loadcase envelop. If corners or nodal data was considered, they are kept after sorting.
  • DDP |entityid |elementid|layerindex: Performs a loadcase envelop. If corners or nodal data was considered, they are aggregated.
  • DDP |entityid |elementid|nodeids|loadcase: Performs aggregation across the element’s layers. Keep result per loadcase.
  • DDP |entityid |elementid: Performs loadcase envelope. Spatial aggregation to retain critical value per element.
  • DDP | entityid: Performs loadcase envelope. Spatial aggregation to retain critical entity (panel or freebody).
  • DDP |nodeids |loadcase: Aggregate value on nodes of a given DDP (keep DDP boundaries). Per loadcase.


Figure 6. Post evaluation sorting
Restriction: As soon as a sorting is done, the output table keeps the whole row with all of the values (input/output) corresponding to the critical metric value. By doing a sorting across a dimension, you lose a dimension, which might prevent full contouring on sorted dimension.
  • Whenever there are critical values across loadcases, contour is available only for envelope loadcases and no more load case per load case.
  • Whenever results across layers are aggregated, contour is available only at the element level.
  • Whenever an aggregation is done across elements (on a designpoint) the table will have the following: DDP | elementid | loadcase | ..inputs | ..outputs | metric, where metric uses critical values. As a result, only one element ID is kept per designpoint in the table. However, the contour method feature has the ability to select DDP as an entity, which contours a constant value on all elements inside the structural element.

Input Aggregation

In addition to post evaluation sorting, attributes can be sorted before sending them to method for evaluation. This enables some flexibility in method evaluation. For example, you can declare the method input parameter as:
<Parameter name = "Composite Stress XX"
                perlayer="0"
                sort=”min|max|minmax|sum|avg|absmin|absmax” (optional)
/>

This way, all layers are queried for Sxx before calling a method, and only the min or max will be retained and sent to method. In the case of minmax, both the min and max values are sent as a vector to method. The sort key is optional. If sort is not requested, all layer values of Sxx will be sent at one time (as a vector) to the method.

The attribute aggregation types are (exclusive choice):
  • perlayer="0|1"
    • 0 means list of all layers (method is called per element only)
    • 1 (def) means current layer only (method is called per layer)
  • perelement="0|1"
    • 0 means list of all elements (method is called per designpoint only)
    • 1 (def) means current element only (method is called per element)
  • perloadcase="0|1"
    • 0 means list of all loadcases (method is called once for all loadcases)
    • 1 (def) method is called per loadcase

User Attribute Registration

Registered attributes are either Model info queried from the HyperMesh database or Result info queried from result files. Result datatypes must match names in the result file. Most of the time, the result reader provides aggregated vector or tensor datatypes.

For instance:
  • 1DForces & 1DMoments
  • 2DForces & 2DMoments
  • Stress
  • Composite Stress
For a better portability of method registration, it is advisable whenever possible to use such aggregated datatypes instead of direct raw scalars. Raw scalars are subject to change depending on element formulation (such as cbar vs cbush force) or file format used, even for the same solver (*.xdb and *.op2 have different spelling scalars). There is a list of pre-defined attributes you can use (see Figure 3). Only user-specific attributes must be defined.
Restriction: This operation is currently available only by editing the library .xml file. No GUI.
All result attributes are defined in a fully qualified path from designpoint (key “value=”) starting with HMDb results (Figure 7).
Note: HMDb is the current designpoint which will be queried.
Whenever the designpoint is made of several elements, the framework loops through the designpoint content. As an example, “Composite Stress XX” used on a panel_composite designpoint queries Sxx on each element and each layer. An attribute can be defined in a flexible way with a fully qualified path. By default, property or material-based attributes are queried from the structuralproperty’s property entity. If none are available, the query is performed at the element’s property level.
If you want to enforce a path to query elements no matter what the structural property, you can fully qualify the path to include element:
  1. HMDb.property.PCOMP_MID.MAT8_Xt queries the ply’s material Xt (Nastran solver attribute) based on the order of precedence mentioned above.
  2. HMDb.element.property.PCOMP_MID.MAT8_Xt will always go with the local element’s property no matter which property is assigned (or not) to the structural property.
In some situations, the framework cannot resolve any precedence, such as for “Thickness” for panel_metallic:
  1. HMDb.element.thickness will retrieve elemental thickness in a Panel (metallic & Composite).
  2. HMDb.structuralproperty.thickness enforce to use attribute thickness for Panel_metallic structural property.

If an attribute can take multiple values on an element (like material allowable per ply), the engine will manage during the query loop layer per layer.

The key name=" " must be unique across all attributes within a Library (same .xml file):
  • Re-defining an attribute with the same name as in the installation takes precedence in methods in the same library.
  • Attributes with the same names across libraries are resolved locally.


Figure 7. User attribute definition example