Integrating Custom Events into the Event Browser

Since users usually have many custom events, with corresponding macros and dialog boxes, it is often necessary to be able to integrate those existing customizations into the event browser framework to take advantage of the full capability of Adams Car. Integrating existing custom event macros into the event browser involves the following steps:

Each of these steps will be outlined in detail below.

Examples of custom events are placed in:

<Adams installation directory>/acar/examples/custom_events/

If a new custom event is needed it is often faster to start from one of the already existing events in the Adams car suite of events. Much of the base functionality will then already be in place. Best is to start with a go-though of the events under the Simulate menu to find something similar to the thought custom event. When the appropriate event has been found the name of the underlying macro is needed.

The event macros for Adams Car are placed under ACAR.macros and typically called something like mac_ana_ful_XYZ_sub (full vehicle events) or mac_ana_sus_XYZ_sub (suspension events) where XYZ is the typically the analysis file suffix, but some exemptions exist for this rule. For example, the suspension event opposite wheel travel which have a longer suffix (opposite_travel).

Add additional functionality to the exported macro. If the event is such that not all functionality happens in the macro but there are also steps happening in python it is also good to find the python class for the event and investigate it. For example, this is true for events that have pre-events. There are examples of such event classes in the folder:

<Adams installation directory>\python\win64\Lib\site-packages\mdi\afc\chassis\

on Windows and on Linux in the folder:

<Adams installation directory>/python/linux64/lib/pythonX.X/site-packages/mdi/afc/chassis/

where pythonX.X may vary with the version of Python Adams is currently using.

If a macro already has been written earlier and used outside of the event framework, it can still be adapted to the event framework to enable that the resulting event is handled in the same way as native events are. But integration into the event framework will be easier if parameter names of the macro follows the Adams Car standard. Hence it is advised that the parameter names of the macros are changed to fit with the standard events. This is easiest done by inspecting the standard analysis macros.

In order to integrate with the event browser framework in Adams Car, each event must have a "class" definition. This backbone is built using the Python programming language to allow for greater extensibility and to take advantage of the object-oriented features of the language. In order to make conversion easier, a macro ("acar toolkit event convert") is provided to facilitate the conversion into the python event class. The python class can also be created manually if the new event is a variant of an already existing event. Here python inheritance enables to, in large, add only the differences to the python file. See, Custom Event Example 1: Custom Swept Steer Integrated In Standard Dialog Box.

The following table details the parameters to this macro.

 

Note that this step should be performed once (or whenever the macro changes) to generate the python class and does not need to be performed each time Adams Car starts.

If the event is a full vehicle event it is recommended that the full vehicle analysis common dialog box is used to modify the event. In Adams Car all full vehicle events use the dialog box .ACAR.dboxes.dbox_ana_ful_sub which display containers depending on the event class.

Example for a full vehicle event:

If the output_suffix is defined in the macro and the name of the container equates cont_ + the output_suffix, the dialog box and correct container will be shown at event modify.

If a standalone dialog box (separate dbox per event) is to be used the call should be something along the lines with:

Each event definition must be registered into the current Adams Car session. This enables the event framework to apply the mapping between the custom macro and the class definition. This registration happens via the following macro:

 

The best way of registering event definitions is by making it run automatically by adding the command in the acarAS.cmd/acarBS.cmd, plugin "load" macro in case the event is to be a part of a plugin or in the macro .ACAR.macros.acar_init_site if the event is to be part of a site.

The final step is to create an event instance that uses the custom event. This enables the event browser to display the instance for modification and/or rerun. This registration happens via the following macro call:

All the event values must be entered as strings as shown in the example below.

All parameter values should be entered as strings and if the value to an attribute is for example a vector of values, then the values should be enclosed in hard brackets like so: "[1, 2 ,5 ,6]" . At the completion of this command the event is created in the default event set.

If no dialog box is defined for the event upon display of the event browser, a custom table will display all the attributes of the event directly in the event browser. For example:

 

There are several ways to make a custom event having a dialog box connected to it in the event framework. Using a custom container in the standard dialog or using a separate dialog box. If an advanced dialog box has already been built it may be the right choice to let the event have a separate dialog box and integrate it into the event workflow. However, for most cases the best practise is to use the standard dialog boxes and switch containers depending on event. Another option is to make a copy of the standard dialog box with a new name, remove the standard containers and insert the custom ones. The third option is to use a complete standalone dialog box for each new analysis. It may seem tempting to use a standalone dialog box for each event but, but if the number of custom events become more than a few then the first or second option will result in an easier code to maintain over time. The first option will also make it easier to make use of additions made to Adams Car the future.

For full vehicle events, to integrate the event seamlessly it is best to use the dialog box .ACAR.dboxes.dbox_ana_ful_sub as this dialog box already handles many of the standard input to a macro such as Variant, Output Prefix, Analysis Mode, End time, solver Settings file. It is important to know that the custom macro may need changes to accommodate these inputs if they are not present today.

To use this dialog box, a container for the event should be prepared. By naming convention, the three last letters of the output suffix are used together with the prefix cont_ as the name of the container. So if the output suffix of the event is "abc" then the name of the container should be cont_abc. In the session it should be created under the dialog box .ACAR.dboxes.dbox_ana_ful_sub. It is also important for this case to set the variable $_topgui.className to the custom macro name in case the macro name is not matching .ACAR.macros.mac_ana_ful_abc_sub.

To understand how this works it is recommended to study a few containers in the dialog box editor and/or export it to disk for study there. To export a container for example, the Swept Steer event do the following:

Placing it under the dialog box could easiest be done if a site is used as the modifications to the dialog box during site build then would be preserved in the site binary. If the event is to be placed in a plugin then the dialog box should be extended with the container during for example the load macro of the plugin. Modifications can also be done in acarAS.cmd/acarBS.cmd

For suspension analysis the process is analogue to the process of the full vehicle event but the container should be placed under the dialog box .ACAR.dboxes.dbox_ana_sus_sub.

It is of course also possible to create a custom separate dialog box which switches container just like the standard dialog boxes depending on event.

A complete example on how to integrate an analysis as an event into the standard dialog box is available in:

<Adams installation directory>/acar/examples/custom_events/multi_stepped_steer/
event_framework_common_dbox/

A complete example on how to integrate an analysis as an event into a separate dialog box is available in:

<Adams installation directory>/acar/examples/custom_events/multi_stepped_steer/

event_framework_separate_dbox/

Both the above examples can be compared (using a file comparison tool) to the unaltered classic custom analysis which is not adapted to the event framework. It is placed here:

<Adams installation directory>/acar/examples/custom_events/multi_stepped_steer/classic/

In general, there are two sets of commands that need to be modified to work with the event instance:

The start commands are used to populate the dialog box upon selecting Modify from the Event Browser. The dialog box will be called with the following parameters:

The general procedure for populating interface objects is to for each attribute extract the value from the event instance using a function depending on the type of value it contains:

where e is the event instance and <member_name> is the name of the attribute from the python class (usually the same as corresponding macro parameter).

There are three functions. One for integers one for strings, and one for reals, They all take a string argument as input which should evaluate as a python expression. The value is returned as the type the function name indicates. If the values could not be evaluated an empty string is returned or the value -1234567890 in case of integers and reals.

For example, the o_no_of_turns option menu, the r_turn_direction radio box and the f_wait_time and f_steer_angles fields of a container or a separate dialog box can be set like this:

 

The same commands can be used for a container or a separate dialog box, but for a separate dialog box the event instance python variable, e must be created in beforehand by using the python command:

or (in Adams command language):

For a container in the standard dialog box the variable e is already set during start of the dialog box.

For the execution commands, the process is to replace the macro call (that is, "acar analysis full_vehicle …) with:

In a standalone dialog box, the following commands should be added in the execution commands to create the event (and to modify it)

For a container in the standard dialog box a variable called $_topgui.eventUDE is already created present and can be used for modification of the event.

In the container execution commands or after the above commands in the standalone dialog boxcommands like the following should be added to set the attributes of the event (typically the macro parameters):

There may be multiple calls to this macro changing all the attributes of the event. Only the "event", "attributes" and "values" parameters are required in the call to this macro.

Finally, the following commands should be added to the execution commands of the separate dialog box only to show the event browser or run the simulation in addition to removal of the temporary variables:

To support modification and creation only, without running the event the event_only simulation mode the analysis_mode should be added to the simulation model option menu in case of a separate dialog box.

In case of container, execution of the event and clean-up is performed but the standard dialog box.

The last step after objects have been modified is to make the changes persistent over sessions and most often also available for other users within the organization. Adam Car offers several ways of accomplishing this.

The simplest way is just to include commands in acarAS.cmd file in the home or working directory. Other options are inclusion in a plugin or a personal or company site.

All the provided examples contain a file called readin.cmd which contains all the needed commands which have to be placed in the site /plugin/acarAS.cmd.

By adding the commands to read macro and dialog box / container together with registering an event to the file acarAS.cmd the event will become available for usage by the local user. This is a great way to go when the event is being developed as changes take effect immediately after restart. Once the event is working and mature it is recommended that the event is included in a site or a plugin instead as this will facilitate sharing and lead to faster start up times of Adams Car.

In site building scripts load the macro into the session as how it would be done with any macro, eg

where <site build source path>/macros is the location to where the macro is placed.

Read also the commands to update the full vehicle analysis dialog box with the new container:

where <site build source path>/dboxes is the location to where the container update file is placed.

Add the following lines to the macro .ACAR.macros.acar_init_site (this shall be created when building the site) to connect the macro with the python file.

The macro .ACAR.macros.acar_init_site is executed when Adams starts and the site has been loaded, that is, the commands will be executed when Adams opens for usage and not during building of the site.

In plugin building scripts load the macro into the session as how it would be done with any macro, for example,

where <plugin build source path>/macros is the location to where the macro is placed.

Read also the commands to update the full vehicle analysis dialog box with the new container:

where <plugin build source path>/dboxes is the location to where the container update file is placed.

Add the following lines to the macro .my_plugin.load to connect the macro with the python file.

The macro.ACAR.macros.load is executed when Adams starts and the plugin is loaded, that is, the commands will be executed when Adams opens for usage and not during building of the plugin.

To make the dialog box F1 help work, place the single file html file: dbox_ana_ful_swp_cus_sub.mht in a folder called /help/dialog_boxes/ (see documentation_text in cont_swp_cus.cmd) under the folder of one of the paths listed in MDI_USER_PLUGIN_DIR or change the path in documentation_text in the container to a hardcoded path.

An example where a custom event is created in which the steering function attribute of a swept steer event is updated using an added field in a custom container. See, Custom Event Example 1: Custom Swept Steer Integrated In Standard Dialog Box.

Three sets of files showing how a classic analysis is transformed to an event using standalone dialog box and common dialog box methods. See, Custom Event Example 2: Transforming An Existing Analysis Into An Event.

Two simulations brought together forming a single event where the second simulation is taking results from the first simulation as input. Results are shown in a custom report and in a custom plot for the event. See, Custom Event Example 3: Pre-event, report, and plot config files.

To create a new event set using Adams command language:

 

The same thing in python language can be done like this:

To activate an event set using Adams command language