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.

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.

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 (Figure 3) 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
You can hence define a default value with value="" (see Figure 3). Currently, only float values are supported.
Whenever a method is attached to a designpointset where designpoints have structural properties assigned, the tool parses the database to search if such metadata already exists. If not, metadata will be created with the default value. When you save your model, metadata that was created will be retrieved when the file is opened next time.
If the selected bind for user input is a property or material (FE entities) then new data is added as metadata. Metadata can be created by external script (see HyperMesh help: *metadata…commands); As soon as the metadata name matches the userinput parameter set in the method registration, it will be used
Then, the order of precedence is to search:
  1. first, if such a property or material is referenced in a designpoint’s structuralproperty.
  2. otherwise, at each designpoint’s elemental property
Whenever an allowable is attached to a material in a Panel_composite category, then the tool will drill down the property (from structuralproperty then element) to gather all plies materials and create them if needed. If selected bind for user input is designpointmethod or structuralproperty, then it will be appended to regular data names (so called dynamic data names).


Figure 3. Method registration & example Compose method
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 4).
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 4. 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 5).

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 above following list:
  • DDP (designpoint)
  • elementid
  • layerindex
  • loadcase
As soon as one of these keys is missing, then an aggregation occurs along this dimension. For example, a domain made of successive calls of:
  • DDP | elementid | layerindex : Retains on each layer the critical metric across loadcases
  • DDP | elementid: Retains 1 value per element which is critical metric across layers and loadcases
  • DDP | elementid | loadcase: Retains 1 value per element per loadcase
  • DDP | loadcase: Performs spatial aggregation across elements (layers if any) per loadcase
  • DDP: Reatins the critical metric across loadcase:
    • If method was element/layer based, there will be spatial aggregation too.
    • If method was a DDP level method (1 value per DDP), it is just an envelope.


Figure 5. 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 will be 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 will provide 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 predefine 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 results attributes are defined in a fully qualified path from designpoint (key “value=”) starting with HMDb results (Figure 6) .
Note: HMDb is the current designpoint which will be queried.
Whenever the designpoint is made of several elements, then the framework loops through the designpoint content. As an example, “Composite Stress XX” used on a panel_composite designpoint will query 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 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 will query ply’s material Xt (Nastran solver attribute) based on order of precedence mentioned above.
  2. HMDb.element.property.PCOMP_MID.MAT8_Xt will always go with local element’s property no matter which property is assigned (or not) to the structural property.
In some situations, the framework can’t resolve any precedence, like 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):
  • Redefining an attribute with the same name as in the installation will take precedence in methods in same library
  • Attributes with the same names across libraries are resolved locally.


Figure 6. User attribute definition example