2019.1 API Programmer's Guide

Properties and Control Cards to Damping

The LS-DYNA keywords *DAMPING_PART_MASS, *DAMPING_PART_STIFFNESS and *DAMPING_RELATIVE and the Radioss keywords/DAMP and /DAMP_INTER have been mapped from the property entity to the new damping entity. The LS-DYNA keywords *DAMPING_FREQUENCY_RANGE and *DAMPING_GLOBAL have been mapped from the control card entity to the new damping entity. See the dampings data names documentation for more details.

Scripts that created or queried the property or control card entities for these keywords must be updated to use the damping entity. Note that solver ID pools are no longer required with this new entity type as well. Below are a few examples.

To create a *DAMPING_PART_MASS keyword, create a damping entity with config 101:

*createentity damping config=101

To create a /DAMP keyword, create a damping entity with config 201:

*createentity damping config=201

To update the values of different data names like Alpha:

*setvalue dampings id=$id Alpha=$set_id

System Collectors to Position

The LS-DYNA keywords *DEFINE_TRANSFORMATION and *NODE_TRANSFORM and the PAM-CRASH keyword TRSFM have been mapped from the system collector to the position and transformation entities. See the positions and transformations data names documentation for more details.

Scripts that created or queried the system collector entity for these keywords must be updated to use the position and transformation entities. Below are a few examples.

To create a *DEFINE_TRANSFORMATION keyword, create a position entity with config 101:

*createentity position config=101

To create a *NODE_TRANSFORM keyword, create a position entity with config 101:

*createentity position config=101
*setvalue position id=$id STATUS=2 entities={sets 0}

To create transformation cards with option TRANSL, ROTATE, SCALE, etc...:

*createentity transformations config=2            // TRANSL
*createentity transformations config=3            // ROTATE
*createentity transformations config=4            // SCALE
*createentity transformations config=5            // MIRROR
*createentity transformations config=101          // POINT
*createentity transformations config=102          // POS6P
*createentity transformations config=103          // POS6N

To create a TRSFM keyword, create a position entity with config 407:

*createentity position config=407

To update the values of different data names like position_scale:

*setvalue transformation id=$id position_scale=$scale

System Collectors to Solversubmodel

The LS-DYNA keyword *INCLUDE_TRANSFORM has been mapped from the system collector to an include file and solversubmodel enitty. See the solversubmodels data names documentation for more details.

Scripts that created or queried the system collector entity for this keyword must be updated to use the solversubmodel entity. Below are a few examples.

To create a *INCLUDE_TRANSFORM keyword, create a solversubmodel entity with config 101:

*createentity solversubmodel config=101 includefile=seat_01.k alloptionoffset=10000 nodeoffset=10000 elementoffset=10000

To update the values of different data names like massfactor or materialoffset:

*setvalue solversubmodel id=$id massfactor=$factor
*setvalue solversubmodel id=$id materialoffset=$offset

Syntax Parser Improvements for hm_getvalue/createentity/createentitysameas/*setvalue

The syntax parser for these commands has been improved to improve error reporting and enforce a proper syntax.

Common changes include:

Keywords provided in the input should fully and strictly match with the documented keyword names like name, id, mark, etc...
Example of incorrect syntax:
```
hm_getvalue comps identity=1 dataname=nametoffset=10000
```
Example of corrected syntax:
```
hm_getvalue comps id=1 dataname=nametoffset=10000
```

Enhanced error messages to give an indication of the reason for a failure:

*setvalue comps id=2 materialid=1 property name=test
error: *setvalue :  Invalid input at "property name=test"

hm_getvalue comps id=1 dataname
error: hm_getvalue:  Invalid input at "dataname"

Enclosing both the key and value pair in quotes with a leading or trailing space for the value "<keyname>= <value> " is invalid. If there is a need to specify the value in {} or "" , enclose only the value part of the pair.
Example of incorrect syntax:
```
hm_getvalue comps "id= 1" "dataname =  name "
```
Examples of correct syntax:
```
hm_getvalue comps id=1 dataname=materialid
```
```
*setvalue comps id=1 name= "test comp"
```
```
*setvalue comps id=1 name = {test comp}
```

Changes specific to hm_getvalue include:

The suffix operator "." is supported only on data names/attributes that can hold a single entity. Usage of this operator on entity array data names/attribute now results in an error.
Example of incorrect usage:
```
hm_getvalue sets id=1 dataname=ids.id
```

Changes specific to *createentity include:

Any data names provided in the input that require an empty string must be specified as "".
Example of incorrect syntax:
```
*createentity comps cardimage=
```
Example of corrected syntax:
```
*createentity comps cardimage=""
```

New Commands

Modified Commands

The following commands have modified behavior that potentially require script updates:

General/Core
- hm_getvalue/*createentity/*createentitysameas/*setvalue - See the section above for syntax parser improvements that may require updates to incorrectly formatted command input.
Meshing
- hm_geomfindsymmetry - Now returns six lists instead of four. The fifth is the maximum deviation between the source and target, and the sixth is a list of two coordinate lists where the maximum deviation occurs with the first on the source and the second on the target.

The following commands have new options or enhanced capabilities. Existing scripts are not affected and only need to be updated if usage of the new functionality is desired:

Data Names
- crosssections - Added new data names CID_Options and GID_Options.
- designvars
  - free shape - Added new data names boundary, boundary_btype, boundary_option, boundary_setid, boundary_skip, bounds, bounds_lb, bounds_option, bounds_ub, draft, draftangle, filter, filter_radius, filter_type, freeshape_method, freeshapeelem and freeshapeproperty.
- elements - Added new data names elementalxaxis, elementalyaxis, and elementalzaxis.
  - joint - Added new type values 42-60.
  - master3 - Added new data name baseelementinternalid.
  - master4 - Added new data name baseelementinternalid.
  - slave3 - Added new data name baseelementinternalid.
  - slave4 - Added new data name baseelementinternalid.
- failures - Added new data names FAILURES_CR_AIR, FAILURES_CR_EDGE, FAILURES_CR_FOIL, FAILURES_EMA, FAILURES_EXP_N, FAILURES_GRSH3N, FAILURES_GRSH4N, FAILURES_I_FRWAVE, FAILURES_IMOD, FAILURES_KIC, FAILURES_KTH, FAILURES_RLEN, FAILURES_SOFT, FAILURES_T_CUT, FAILURES_V0 and FAILURES_VC.
- hourglass - Added new data names hgscalefactor and hgtype.
- interfacecomponents - Added new data names cid, fileformat, filename, nid and optionalcard.
- interfacelinkings - Added new data name filename.
- materials - Added new data names isinlibrary, librarycomment, libraryentityid, libraryname and libraryrevision.
- modelcheckchecks - Added new data names failedvalues and userstatus.
- parameters - Added new config value 6 and usage value 5. Added new data names dvlink, isactive and varname.
- positions - Added new config values 101 and 407. Added new data names picexp_export_control, picexp_export_control_qualifier, picexp_export_control_switch and Title.
- sets - Added new data name elementids.
- rigidbodies - Added new data names alpha, dofstring, dof1, dof2, dof3, dof4, dof5, dof6, GMj, gmjcount, GNi, gnicount, gs, radius, type, uniqueid_rbe2gs, xs, ys and zs.
- shapes - Added new data name parameterid.
- solversubmodels - Added new config value 101. Added new data names curveoffset, defineoffset, include_fullname, incout1flag, lengthfactor, massfactor, prefix, setoffset, suffix, temperaturefactor, timefactor and ransformationid.
- systems - Added new data names constructionaxis, constructionaxisx, constructionaxisy, constructionaxisz, constructionplane, constructionplanex, constructionplaney and constructionplanez.
- transformations - Added new config values 101, 102, 103 and 406. Added new data names base_node, localid, pos_coord1, point1, point2, point3, point4, point5, point6, pos_coord1, pos_coord2, pos_coord3, pos_coord4, pos_coord5, pos_coord6, position_node1, reflect_coordinatesystem, rotation_direction_x, rotation_direction_y, rotation_direction_z, rotation_x, rotation_y and rotation_z.
General/Core
- *setoption - Added new options beam_lod_threshold, cadupdate_parameter_immediate, element_window_selection_mode, graphics_optimize_view_control, legend_allow_background_transparency, numeric_legend_force_ranged, method_xml_file, numeric_legend_threshold, snap_circle_center, snap_circle_center, snap_global_xyz, snap_line_end, snap_line_line_intersect, snap_line_middle, snap_on, snap_on_empty_space, snap_on_tangent_extension, snap_perp_from_line, snap_perp_from_surf, snap_perp_to_line, snap_perp_to_surf, snap_surf_center, snap_surf_line_intersect, snap_system_center, snap_tangent_from_line and snap_tangent_to_line.
Meshing
- hm_checkproximity - Added new optional arguments min_angle_limit and max_angle_limit.
- hm_proximityinit - Added new optional arguments min_angle_limit and max_angle_limit.
- hm_proximityinitwithtarget - Added new optional arguments min_angle_limit and max_angle_limit.
- *check_symmetric_mesh - Added new string_array values tolerance and transformation.
- *check_symmetric_surfaces - Added new string_array values tolerance and transformation.
- *map_symmetric_mesh - Added new string_array values tolerance and transformation.
- *midmesh_repair - CreateMidEdge now linearly interpolates between the selected nodes. The CreateMidEdgeWithLines Lines1Mark and Lines2Mark selections are now optional. The behaivor now depends on which, if any, lines marks are populated.
- *readqualitycriteria - Updated to also read 3D criteria.
- *writecurrentqualitycriteria - Updated to also write 3D criteria.

Deprecated Commands

Geometry
- *midsurface_accept_edge_target - Use *midsurface_accept_edge_target_by_number instead.
- *midsurface_remove_edge_target - Use *midsurface_remove_edge_target_by_number instead.

While still continuing to work as before, the following are all deprecated by *createentity and may be removed in a future release:

*latparmcreate
*opticonstraintcreate
*opticontrolcreate
*opticontrolcreate80
*opticontrolcreate80sr1
*optictrlcreate
*optidobjrefcreate
*optidscreencreate
*optidscreencreateextended
*optiminmaxcreate
*optiobjectivecreate
*optiresponsecreate
*shapevarcreate
*shapevarcreate_twonode
*shpdesvarcreate
*shpdesvarcreatewithddvalfield
*sizedesvarcreate
*sizedesvarcreatewithddvalfield
*topologydesvarcreate

While still continuing to work as before, the following are all deprecated by *setvalue and may be removed in a future release:

*interfaceall
*interfacebox
*interfacecomponent
*interfacecontactsurf
*interfacedefinition
*interfacesets
*jointelement_update
*latparmupdate
*latparmupdatebucksfparameter
*latparmupdatemaxradparameter
*loadstepsupdate
*loadstepsupdateattributesfromidlist
*masselementupdate
*materialupdate
*mbjointupdate
*multibody_cogupdate
*multibody_sysupdate
*opticonstraintupdate
*opticontrolupdate
*opticontrolupdate80
*opticontrolupdate80sr1
*opticontrolupdateapproxparameters
*opticontrolupdatebarconparameters
*opticontrolupdatecontolparameters
*opticontrolupdateeslparameters
*opticontrolupdatemanthrparameters
*opticontrolupdateoptimizationparameters
*opticontrolupdateremeshparameters
*opticontrolupdatetopdiscparameters
*opticontrolupdatetopdvparameters
*opticontrolupdatetoprstparameters
*optictrlupdate
*optidobjrefupdate
*optidscreenupdate
*optidscreenupdateextended
*optiminmaxupdate
*optiobjectiveupdate
*optiresponseexcludeelements
*optiresponsesetequationdata1
*optiresponsesetequationdata2
*optiresponsesetequationdata3
*optiresponsesetequationdata4
*optiresponseupdate
*optiresponseupdatenodeid
*optiresponseupdatenormalacceleration
*optiresponseupdatenormaldisplacement
*optiresponseupdatenormalvelocity
*optiresponseupdaterandpsid
*optiresponseupdatesubcasetrackingvalue
*outputblocksupdate
*propertyupdate
*propertyupdateentity
*rbe3update
*rbe3updatealldofs
*rbe3updateallwts
*rbe3updatedofs
*rbe3updatewts
*rigidlinkupdate
*rigidsupdate
*rigidsupdate_setattach
*rigidsupdateconnectivity
*rigidwall_motion_update
*rodupdate
*shapeboundsupdate
*shapeboundsupdatewithddvalfield
*shapevarupdate
*shapevarupdate_twonode
*shpdesvarupdate
*shpdesvarupdatewithddvalfield
*sizedesvarupdate
*sizedesvarupdatewithddvalfield
*systemsetanalysis
*systemsetreference
*topographypatternupdate
*topographyrepetitionupdate
*topographypatternvaluesupdate
*topologydesvarupdate
*topologydrawupdate
*topologydrawupdatewithnoholeandstamp
*topologyextrusionupdate
*topologylatticeupdate
*topologyparametersupdate
*topologyparametersupdate80
*topologyparametersupdatewithfatigue
*topologyparametersupdatewithmingap
*topologyparamsupdate
*topologypatternupdate
*topologyrepetitionupdate
*topologysymmetryupdate