API Guide for Authors

The API Guide for Authors explains the usage of the plug-in from an Author's perspective. The Authors of API plug-ins can create a dialog box (window) within EDEM’s GUI that allows editing of parameters without the use of preference files or recompiling. This guide assumes that you are familiar with EDEM’s API and have a complete plug-in that can be compiled and seamlessly used within EDEM. For more information about the basics of EDEM’s API, see the Altair Community page before continuing with authoring plug-ins.

To use the API guide for Authors:
  1. To update the API version, starting from the source code of a functioning plug-in, ensure that the plug-in is updated to be using at least version 3.5 of the relevant (either contact model or particle body force) API.
    This is done by editing the values within the GETEFINTERVACEVERSION() or GETCMINTERVACEVERSION() macros as follows:


    Note: This is a mandatory step to access pluginParameterManagerand various functions that allow you to create a custom dialog box for your plug-in.
  2. To create an accessible dialog box for the plug-in, perform the following steps:
    1. Use the primary function setApiParametersTemplate(NApiCore::IapiManager_X_X& apiManager) which is a member function of both the IpluginContactModelVX_X_0 and IpluginParticleBodyForceVX_X_0 (X_X >= 3_5) interface classes provided by EDEM.

      After implementing this function, it returns 'true' and the enables the icon for additional settings for Physics models within EDEM’s GUI.

    2. To define the plug-in parameters, use pluginParameterManager available through IApiPluginParameterManager_X_X.h.

      You must include this header within your plug-in to access all the useful functionality that populates the plug-in dialog box.

    3. After opening this header, the following group names are available:

      These group names are protected and EDEM will populate the dialog box differently depending on how these group names are used. The group names are used to group the parameters that you wish to expose to the user according to how they are accessed in EDEM’s GUI and where they should be applied.

      In order to populate the dialog box, you must interact with the interface IApiPluginParameterManager_X_X.

    4. Create a pointer to an instance of this class within setApiParametersTemplate(), and populate the dialog box with the parameters that you want to expose to the user.
    5. Access the IApiPluginParameterManager_X_X from the starting() function to retrieve the values stored in the dialog box.

  3. To use the key member functions of IApiPluginParameterManager_X_X, you must browse the header directly. 
    • Add parameters (typically used in setApiParametersTemplate()):
      • addDoubleValue()

        Adds a Double value to the dialog box and allows you to specify the name, default value, units, and min/max limits.

      • addIntegerValue()

        Adds an Integer value to the dialog box and allows you to specify the name,default value, and min/max limits.

      • addBoolValue()

        Adds a Boolean value to the dialog box and allows you to specify the name and default value.

      • addStringValue()

        Adds a String value to the dialog box and allows you to specify the name and default value.

      • addComboBoxValue()

        Adds a combo Box to the dialog box and allows you to specify the name and default value.

      • addComboBoxOption()

        Adds an additional option to a specified combo box and allows you to specify the name of the combo box option and the combo box to which it should be added.

    • Get stored parameter values (typically used in the starting() function):
      • getDoubleValue()

        Retrieves the current double value set by the user.

      • getIntegerValue()

        Retrieves the current integer value set by the user.

      • getBoolValue()

        Retrieves the current Boolean value set by the user.

      • getStringValue()

        Retrieves the current String value set by the user.

      • getComboBoxValue()

        Retrieves the currently selected combo box value set by the user.

    • Interact with Groups:
      • startGroup()

        Starts a group, to store parameters in. Allows you to either use a protected group name or specify your own. This will typically be used inside setApiParametersTemplate() when first creating the groups and parameters.

      • endGroup()

        Ends or closes a group. This will be used in both setApiParametersTemplate() and starting(), when you are done defining a group or closing it once you have retrieved the necessary data.

      • openGroup()

        Opens an already existing group. This is used when accessing values set by the user. This will typically be used inside the starting() function.

      • getGroupCount()

        Returns the number of sub-groups defined within the current group. This is to be used when looping over all defined interactions. This will typically be used inside the starting() function.

      • openInteractionGroup()

        Opens an interaction group. You must specify the group index. The material names are passed in empty <> but the corresponding material names are populated, based on the provided group index. This will typically be used inside the starting() function.

    • Tables offer similar functionality to groups. Parameters are defined via column headers instead of individual values using similar syntax. It is also possible to define default rows, in which case those rows may still be modified by the user, but not deleted.
      • startTable()

        Starts a table to store parameters and will be used inside setApiParametersTemplate().

      • endTable()

        Ends or closes a table and will be used in both setApiParametersTemplate() and starting(), when you have defined a table or closed after retrieving the necessary data.

      • openTable()

        Opens an already existing table. This is used when accessing values set by the user. This will typically be used inside the starting() function.

      • getTableRowCount()

        Returns the number of table rows within the current table and is used when looping over all table rows to read values. This will be used inside the starting() function.

      • addTableDoubleColumnHeader()

        Adds a column of type Double to the table and allows you to specify the name, default value, and units.

      • addTableIntegerColumnHeader()

        Adds a column of type Integer to the table and allows you to specify the name and default value.

      • addTableBoolColumnHeader()

        Adds a column of type Boolean to the table and allows you to specify the name and default value.

      • addTableStringColumnHeader()

        Adds a column of type String to the table and allows you to specify the name and default value.

      • startTableRow()

        Starts a default table row definition. Parameters defined inside this row must match existing table column names, and will be used as the default values. You can still edit this default row’s content, but will not be able to delete the row. This will be used inside the starting()function.

      • endTableRow()

        Ends or closes a table row. This will be used in both setApiParametersTemplate() and the starting() function, when you have defined a default table row, or closed it after retrieving the necessary data.

      • openTableRow()

        Opens an already existing table row and is used when accessing values set by the user. When a table row is open, values in that row are accessed the same as normal parameters, using the column names as identifiers. This will be used inside the starting() function.

Use Functions

Use the files and functions described in the recommended order.

To use functions:
  1. Update your plug-in to be compliant with version 3.5 of the relevant API.
  2. Add the IApiPluginParameterManager_X_X.h header to your plug-in.
  3. Add the setApiParametersTemplate() function to your class.
  4. Obtain a pointer to an instance of the IApiPluginParameterManager_X_X to interact with within setApiParametersTemplate().
  5. Define your groups, tables, and parameters as required
  6. Obtain a pointer to an instance of the IApiPluginParameterManager_X_X to interact with, within the starting() function.
  7. Retrieve data as required for use within the rest of the plug-in.

Use Groups

You must define all parameters within one of the three Physics chain groups.

To use Groups:
  1. To define parameters in setApiParametersTemplate() for the Particle-Particle, Particle-Geometry, and Particle Body Force groups, start the group before defining your parameters and close it as follows:


  2. Define a Double called ‘Test double 1’ and a Boolean called ‘Test bool 1’ with the default values '1234.0 ' and 'true' respectively.
  3. To retrieve these values in the starting() function, use openGroup(), getDoubleValue(), and getBoolValue().


    You are assigning the retrieved Double and Boolean values here to member variables that you can use in your plug-in as required.
  4. To define parameters for material interactions, follow the same steps but first add an additional group to define a template that all the other interactions are based on.
  5. To implement setApiParametersTemplate(), perform the following steps:


  6. To retrieve the data, perform an additional step as the material interactions need to be looped over for all the defined interactions that are unknown at the time of compiling the plug-in:


    Note: Indenting within the code snippets in all of these steps is done for code legibility and is not mandatory.