2021.1 API Programmer's Guide

Classic Loads to Engineering Loads

Specific keywords (see table below) previously mapped to classic loads have been migrated to engineering loads for the LS-DYNA solver interface. See loads data names documentation for more details.

Mapping these keywords to the engineering loads brings several benefits: more representative visualization, ID pool support, more efficient load management, and easier switch between load types. Classic load support is still available for the affected keywords as a convenience, but it is not recommended to use them. Scripts that rely on the creation of classic loads will still work. For more information on how to create engineering loads or convert classic loads to engineering loads, refer to the Engineering Loads section of the 2020 API Programmer’s Guide.

Mapping for LS-DYNA keywords:
LS-DYNA Keywords Engineering Loads Entity
*LOAD_GRAVITY_PART Acceleration
*LOAD_GRAVITY_PART_SET
*BOUNDARY_PRESCRIBED_MOTION_NODE
*BOUNDARY_PRESCRIBED_MOTION_SET
*BOUNDARY_PRESCRIBED_MOTION_RIGID
*BOUNDARY_SPC_NODE Constraints
*BOUNDARY_SPC_SET
*BOUNDARY_PRESCRIBED_MOTION_NODE
*BOUNDARY_PRESCRIBED_MOTION_SET
*BOUNDARY_PRESCRIBED_MOTION_RIGID
*BOUNDARY_CONVECTION_SET Fluxes
*BOUNDARY_RADIATION_SET
*LOAD_NODE_POINT Forces
*LOAD_NODE_SET
*LOAD_RIGID_BODY
*LOAD_NODE_POINT Moments
*LOAD_NODE_SET
*LOAD_RIGID_BODY
*LOAD_SHELL_ELEMENT Pressures
*LOAD_SHELL_SET
*LOAD_SEGMENT
*LOAD_SEGMENT_SET
*LOAD_BEAM_ELEMENT
*LOAD_BEAM_SET
*INITIAL_TEMPERATURE_NODE Temperatures
*INITIAL_TEMPERATURE_SET
*BOUNDARY_TEMPERATURE_NODE
*BOUNDARY_TEMPERATURE_SET
*LOAD_THERMAL_CONSTANT_NODE
*LOAD_THERMAL_CONSTANT
*LOAD_THERMAL_VARIABLE_NODE
*LOAD_THERMAL_VARIABLE
*INITIAL_VELOCITY_NODE Velocities
*INITIAL_VELOCITY
*INITIAL_VELOCITY_RIGID_BODY
*INITIAL_VELOCITY_GENERATION
*BOUNDARY_PRESCRIBED_MOTION_NODE
*BOUNDARY_PRESCRIBED_MOTION_SET
*BOUNDARY_PRESCRIBED_MOTION_RIGID

Loadcollectors to Analysisparameters

Specific keywords previously mapped to the loadcols entity have been migrated to the new analysisparameters entity for the following profiles: Nastran and OptiStruct.

Refer to analysisparameters data names documentation for more details. Scripts that created or queried the load collector entity for the keywords listed in the table below must be updated to use the new analysis parameters entity.

The following are examples of how to create and modify an EIGRL card:
  • Before – Created as a load collector
    *createentity loadcols name="loadcol1" cardimage="EIGRL"
  • After – Created as an analysis parameter
    *createentity analysisparameters name="analysisparam1" real_eigen_type="EIGRL"
  • Set the V2 value on the EIGRL card to 500.0
    *setvalue analysisparameters id=$id STATUS=1 v2=500
The following table shows mappings for OptiStruct keywords.
Table 1.
Keyword Analysisparameters Entity
EIGRL Config: 301

Type: EIGRL

EIGRA Config: 301

Type: EIGRA

EIGRD Config: 301

Type: EIGRD

EIGC Config: 302

Type: EIGC

NLPARM Config: 303

Type: NLPARM

NLADAPT Config: 304

Type: NLADAPT

NLMON Config: 305

Type: NLMON

NLOUT Config: 306

Type: NLOUT

Support for the following OptiStruct keywords has been added.
Table 2.
Keyword Analysisparameters Entity
NLPRINT Config: 307

Type: NLPRINT

NLENRG Config: 308

Type: NLENRG

BASELIN Config: 309

Type: BASELIN

The following table shows mappings for Nastran keywords.
Table 3.
Keyword Analysisparameters Entity
EIGRL Config: 301

Type: EIGRL

EIGC Config: 302

Type: EIGC

NLPARM Config: 303

Type: NLPARM

NLOUT Config: 305

Type: NLOUT

Reference Geometries

Keywords defining reference geometries in LS-DYNA, Radioss and PAM-CRASH solver interfaces are mapped to the new referencegeometries entity. Creating and modifying the new entity is done using the *createentity and *setvalue commands.

The commands *createreferencegeometry, *reviewreferencegeometry, *updatereferencegeometry should not be used for creating, reviewing, or updating reference geometry. Any scripts that rely on using control volumes, controlcards, or table entities to create reference geometry-related keywords in crash profiles should be updated to the referencegeometries entity.

The following LS-DYNA keywords are mapped from the controlvolumes entity to the referencegeometries entity:
  • *INITIAL_FOAM_REFERENCE_GEOMETRY
  • *INITIAL_FOAM_REFERENCE_GEOMETRY_RAMP
  • *AIRBAG_REFERENCE_GEOMETRY
  • *AIRBAG_REFERENCE_GEOMETRY_BIRTH
  • *AIRBAG_REFERENCE_GEOMETRY_RDT
  • *AIRBAG_REFERENCE_GEOMETRY_ID
  • *AIRBAG_REFERENCE_GEOMETRY_BIRTH_RDT
  • *AIRBAG_REFERENCE_GEOMETRY_BIRTH_ID
  • *AIRBAG_REFERENCE_GEOMETRY_RDT_ID
  • *AIRBAG_REFERENCE_GEOMETRY_BIRTH_RDT_ID
  • *INITIAL_AIRBAG_PARTICLE_POSITION
The following LS-DYNA keywords are mapped from the tables entity to the referencegeometries entity:
  • *AIRBAG_SHELL_REFERENCE_GEOMETRY
  • *AIRBAG_SHELL_REFERENCE_GEOMETRY_RDT
  • *AIRBAG_SHELL_REFERENCE_GEOMETRY_ID
  • *AIRBAG_SHELL_REFERENCE_GEOMETRY_RDT_ID
To create an *INITIAL_FOAM_REFERENCE_GEOMETRY keyword, create referencegeometry with config 101:
*createentity referencegeometries config=101
To create an *AIRBAG_REFERENCE_GEOMETRY keyword, create referencegeometry with config 102:
*createentity referencegeometries config=102
To create an *AIRBAG_SHELL_REFERENCE_GEOMETRY keyword, create referencegeometry with config 103:
*createentity referencegeometries config=103
To create an *INITIAL_AIRBAG_PARTICLE_POSITION keyword, create referencegeometry with config 104:
*createentity referencegeometries config=104

The following Radioss keyword is mapped from the controlvolumes entity to the referencegeometries entity: /XREF.

The following Radioss keywords are mapped from the tables entity to the referencegeometries entity:
  • /EREF/SH3N
  • /EREF/SHELL
  • /EREF/TETRA4
  • /EREF/BRICK

The following Radioss keyword is mapped from the controlcards entity to the referencegeometries entity: /REFSTA.

To create an /XREF keyword, create a referencegeometry entity with config 201:
*createentity referencegeometries config=201
To create an /EREF/SH3N keyword, create a referencegeometry entity with config 202:
*createentity referencegeometries config=202
To create an /EREF/SHELL keyword, create a referencegeometry entity with config 203:
*createentity referencegeometries config=203
To create an /EREF/TETRA4 keyword, create a referencegeometry entity with config 204:
*createentity referencegeometries config=204
To create an /EREF/BRICK keyword, create a referencegeometry entity with config 205:
*createentity referencegeometries config=205
To create a /REFSTA keyword, create a referencegeometry entity with config 206:
*createentity referencegeometries config=206
The following PAM-CRASH keywords are mapped from the controlcards entity to the referencegeometries entity:
  • METRIC/ NODES/
  • METRIC/ BAR/
  • METRIC/ MEMBR/
  • METRIC/ TETRA4/
  • METRIC/ SOLID/
  • METRIC/ PENTA6/
  • METRIC/ TETRA10/
To create METRIC/ NODES/, create a referencegeometries entity with config 401:
*createentity referencegeometries config=401
To create METRIC/ BAR/, create a referencegeometries entity with config 402:
*createentity referencegeometries config=402
To create METRIC/ MEMBR/, create a referencegeometries entity with config 403:
*createentity referencegeometries config=403
To create METRIC/ TETRA4/, create a referencegeometries entity with config 404:
*createentity referencegeometries config=404
To create METRIC/ SOLID/, create a referencegeometries entity with config 405:
*createentity referencegeometries config=405
To create METRIC/ PENTA6/, create a referencegeometries entity with config 406:
*createentity referencegeometries config=406
To create METRIC/ TETRA10/, create a referencegeometries entity with config 407:
*createentity referencegeometries config=407
The data defined on a referencegeometry entity is updated using the *setvalue command. To update the definition of a node-based reference geometry:
*setvalue referencegeometries id=$id nodes_table_node={1 2 3 4}
*setvalue referencegeometries id=$id nodes_table_x={0.1 0.2 0.3 0.4}
To update the definition of an element-based reference geometry:
*setvalue referencegeometries id=$id elems_table_elem={1 2 3 4}
*setvalue referencegeometries id=$id elems_table_n1={10 11 12 13}
To update optional parameters, the parameter must be activated first using the corresponding flag:
*setvalue referencegeometries id=$id birthtoggle=1
*setvalue referencegeometries id=$id birth=10.5

New Commands

Modified Commands

The following commands have modified behavior that potentially require script updates:
  • Data Names
    • responses - Updated the list of responserequesttype values.
  • General/Core
    • hm_getvalue - Resolved an issue with incorrect value being returned for certain colors when querying color entity data name.
  • Meshing
    • hm_getbatchparams - Updated the surface_holes_table options.
    • *batchparams_update - Updated the surface_holes_table options.
    • *compute_midmesh_thickness - Added new options RegroupThicknessVariationFactor, RenameRetainedComponents, and ThicknessAssignMethod to enhance thickness grouping. Removed the ThicknessOutputOption value PropertyOnComponents.
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
    • attachments – Added new data name aegroup.
    • attachmentcontrols - Added new data names createelements, duplicateelems, feature, and maxlayers.
    • connectorgroups – Added new data name attachments.
    • designvars
      • topology - Added new data names holeinst, holerad, levelset, nholesx, nholesy and nholesz.
    • explorations - Added new explorationtype value 3.
    • failures – Added new data name epsp_min, new PAM-CRASH support.
    • features - Added new options associativity,config_color, dim_sides_selection, elem_ids, feature_height, feature_length, feature_minwidth, feature_maxwidth, feature_type, feature_shape, fillet_maxangle, fillet_maxradius, fillet_minangle, fillet_minradius, fillet_ratio, hole_axis, hole_center, hole_ratio, hole_size1, hole_size2, ids, invalid, line_ids, logo_concavityfactor, logo_size, logo_string, node_ids, region_2delems, region_2dedges, region_3delems, region_lines, region_surfs, solidhole_axis, solidhole_blind, solidhole_bottomradmax, solidhole_bottomradmin, solidhole_bottomrims, solidhole_center, solidhole_topradmax, solidhole_topradmin, solidhole_toprims, and surf_ids.
    • loads
      • accelerations – Added new data names for LS-DYNA engineering loads: activation_time, add_part_construct_stage, crash_dir_flag, crash_dofstring and load_body_opt, curveid, deactivation_time, displayname, dyn_relax_evolve_fn, entity_select_option, keyword_name, load_dof, magnitude, motion_rigid_local_option, motion_type, motion_vec_dir, nodal_rigid_body, plane_axis_coord1, plane_axis_coord2, rem_part_construct_stage, rigid_part, rigidbody_option, and vector.
      • constraints – Added new data names for LS-DYNA engineering loads: activation_time, ang_vel_center, curveid, deactivation_time, displayname, dof1, dof2, dof3, dof4, dof5, dof6, inputsystem, keyword_name, load_boundary_nodes, load_dof, magnitude, motion_rigid_local_option, motion_type, motion_vec_dir, nodal_rigid_body, plane_axis_coord1, plane_axis_coord2, plane_node2, plane_node3, rel_disp_ref_body, rigid_part, rigidbody_option, sort_nodes, symmetry_repetition_dir, and time_activate_option.
      • fluxes – Added new data names for LS-DYNA engineering loads: curveid, env_temp_const, env_temp_evolve_fn, magnitude, radiation_type, and thk_shell_surf_temp.
      • forces – Added new data names for LS-DYNA engineering loads: crash_dir_flag, curveid, follower_load, force_ev_fn, inputsystem, load_dof, magnitude, plane_node1, plane_node2, plane_node3, rigid_part and vector.
      • moments – Added new data names for LS-DYNA engineering loads: crash_dir_flag, curveid, follower_load, force_ev_fn, inputsystem, load_dof, magnitude, plane_node1, plane_node2, plane_node3, rigid_part and vector.
      • pressures – Added new data names for LS-DYNA engineering loads: activation_time, beam_axial_dir, box_region_def, curveid, displayname, element_inclusion_option, keyword_name, magnitude, masking_fn_projection_vec, motion_vec_dir, pressure_lower_limit, pressure_mask_fn, rgd_bdy_vel_opt_overwrite, shell_part, and timestep_offset.
      • temperatures – Added new data names for LS-DYNA engineering loads: box_region_def, curveid, dyn_relax_evolve_fn, exempt_node_dyn_rel_temp_sf_evolve_fn, exempt_node_scaled_temp, exempt_node_temp, exempt_node_temp_sf_evolve_fn, exempt_nodes, magnitude, scaled_temp, and thk_shell_surf_temp.
    • modelcheckchecks – Added new data names report and concernedids.
    • modules - Added new data name rep_comment.
    • positions – Added new config value 408 and new data name positions.
    • rbe3 – Added new inputs independentnodesets, independentnodesetcoeffs, independentnodesetidofs, nset, rx, ry, rz, tx, ty, tz, and wt.
    • responses - Added new response value 12.
    • sets – Added new style value 3.
    • topology - Added new data names levelset, holeinst, holerad, nholesx, nholesy, and nholesz.
    • weldlines - Added new data name active_weld_type.
  • General/Core
  • Library
  • Meshing
    • *rbody_mesh - Added new shared_edge_flag values 6, 10, 11, 12, 13, 14, 15, and 16.
    • *update1delements - Added new options connectiontol, contacttol, cutlocation, planebase, planeheight, planenormal, planewidth, refentid, refentname, refentsearchtol, refenttype, taperangle, targetenttype, and targetmark.
  • Subsystems

Removed Commands