Event Builder
Setup → Vehicle Environment → Event Builder
You use the Event Builder to create or modify an XML event file (previously referred to as a driver control file, see XML File Format). Using the Event Builder, you create a series of mini-maneuvers that define a file-driven (see Adams SmartDriver Analysis), full-vehicle analysis (see Full-Vehicle Analysis: SmartDriver).
You can start Event Builder in new file mode or in modify mode. The first time you start Event Builder from the Adams Car Standard Interface, it appears in new file mode. If you want to generate a new event file, from the File menu select New. If you want to edit an existing event file, from the File menu, select Open.
Opening Event Builder again automatically loads the XML file that you were last using.
Adams Car automatically generates event files when you submit any of the standard events, such as step steer. You can use the Event Builder to modify these files or view them to understand their content. However, you can't view existing TiemOrbit form driver control files (.dcf) without first converting them to XML event files. The shared car database includes sample event files.
If you want to convert existing .dcf files to .xml, from the Tools menu, point to Database Management, point to Version Upgrade, and then select TO XML.
For the option: | Do the following: |
|---|---|
Event File | Enter a name for the event file. Adams Car automatically generates a file with extension .xml in the working directory and updates the Event File text box with the file name you entered. |
Speed | Enter the initial vehicle speed for the maneuver. |
Gear | Enter the initial gear position for the maneuver. |
Current Field Unit | Some quantities have associated units: the current unit text box located at the bottom of the dialog box identifies the units when you place the cursor in the appropriate text box. The default units are SI. You can review and modify these units by selecting Units from the Settings menu, at the top of the Event Builder. |
Static Set-up tab - Select the desired static setup method to be performed before the dynamic maneuver. This method is used to set up the vehicle in the desired initial conditions of lateral and longitudinal accelerations. | |
You can specify static task and initial values for steer, brake, throttle, and clutch signals: ■Task (learn more with Structure of Event Files) ■Initial Steer/Brake/Throttle/Clutch When Halt On Failure is set to no, the simulation will perform the dynamic phase even in the case quasi static setup phase was not successful. When Linear is set to yes, a linear analysis is performed after each static equilibrium analysis during the pre-phase. Note that values computed during Skidpad or Straight static setup overwrite initial steer/throttle signals, in case you selected skidpad or straight. | |
Gear Shifting Parameters tab - Defines the gear-shifting properties and the shape of the upshift and downshift curves for throttle and clutch signals. (see Structure of Event Files) | |
Gear Shift | Duration of the gear shifting event (> 0.0). |
Throttle Raise | Delta time of the step function for the ascending curve of the throttle signal (> 0.0). |
Clutch Raise | Delta time of the step function for the ascending curve of the clutch signal (> 0.0). |
Throttle Fall | Delta time of the step function for the descending curve of the throttle signal (> 0.0). |
Clutch Fall | Delta time of the step function for the descending curve of the clutch signal (> 0.0). |
Clutch Off Throttle On Delay | Delay between clutch off and throttle on (>0.0). |
Clutch On Throttle Off Delay | Delay between clutch on and throttle off (>0.0). |
RPM Control | Enable a feedback PID controller to eliminate jerk and synchronize engine rotational speed. |
Controller Parameters tab – Specify Machine Control’s control actions (see Machine Control Basics) | |
Rax Saturation | When set to true and the vehicle velocity is far from the target, the corresponding acceleration reference profile is altered to let the vehicle reach the target faster [true, false]. |
Yaw Correction | Enables the internal yaw rate controller that operates on the steering, to compensate unpredicted yaw rate events (that is, oversteering) [true, false]. |
Tire Fz Control | When set to true, the Machine Control checks if the driving tires are lifted, and in such a case, cuts throttle [true/false]. |
Power-based-shifting | Gear shifting method that chooses the gear that would give the maximum vehicle acceleration [true/false]. |
Feed Forward | When set to true, an instantaneous estimation of the longitudinal control action value is calculated, improving the responsiveness of the control system [true/false]. |
Throttle Control | When set to on, it will control the open loop throttle signal to zero during gear shifting [true/false]. |
Rolling Resistance Correction | When set to true, the feedforward calculations for the longitudinal controller will include an estimate for rolling resistance [true/false]. It should be noted that any larger variations of the tire rolling resistance torque may result in unrealistic throttle/brake signals. |
Tire Radius for Brake Control | The average tire radius of the front and rear tires are used in the brake controller for calculation of the maximum brake torque at the engine level. The following methods are available for obtaining the average tire radius of front and rear tires: ■Constant from static solution (default) - constant average loaded tire radius obtained from the static solution. ■Custom entered value (average) - tire radius specified by parameter tireRadBrkCtrlCustom in the .xml event file. ■Transient during dynamics solution - average loaded tire radius obtained from the tire model during simulation runtime. ■Approximated by unloaded tire radius - average unloaded tire radius obtained from the tire property file. ■Effective tire radius from static solution - constant average effective tire radius obtained from the static solution. |
Create Driver Target Path Data | When set to true, a driver road data file (_pth.drd) is created used for displaying the driver target path in Adams Pre- and Postprocessor and results sets are created for original, b-spline, transformed and actual driver path. |
Drive Authority | Controls driving aggressiveness (% of acceleration capability used) by longitudinal controller and SmartDriver static speed profile calculator. |
Brake Authority | Controls braking aggressiveness (% of deceleration capability used) by longitudinal controller and SmartDriver static speed profile calculator. |
Trajectory Planning Parameters tab – Trajectory planning calculates the connecting contour between the current vehicle position (wherever it may be) and some point on the target path, along which the vehicle will be steered to later bring it back on the target path. | |
Path Distance Compensation | When set to true and if the vehicle is not exactly over the reference path, the path distance compensation controller (Lateral Displacement Feedback) acts to correct the vehicle so that it is over the path [true/false]. |
Path Comp. Tolerance | Value of the path distance under which the path distance compensation controller is activated (L0crit) (>0.0). The default of -1.0 indicates the internal default. |
Min Preview Distance | Minimum value of the preview distance; even if the vehicle is very slow, the preview distance does not become smaller than this value. It must be set at least as long as the vehicle wheel base (>0.0). The default of -1.0 indicates the internal default, typically of 5 meter. |
Connecting Contour | The connecting contour is built between the current vehicle position and some point on the target path (determined by the preview distance), along which the vehicle will be steered to later bring it back to the target path. The following methods are available for the Connecting Contour: ■Cubic maintaining vehicle tangents (default) (‘cubic’) – cubic with tangents matching the vehicle heading at both the “near” and “far” ends. ■Cubic matching vehicle and path tangents (‘cubic_yaw’) - cubic matching the vehicle heading at the "near" end and the path tangent at the "far" end. ■Circular arc matching vehicle tangent (‘circular’) - circular arc matching the vehicle heading at the "near" end and touching the target path at the far end. ■Auto (‘auto’) – For reverse driving (gear is set to a negative number): the circular connecting contour is used, which may show better steering behavior for e.g. low speed parking events. Also, the minimum preview distance is reduced by the vehicle’s wheelbase (assuming the gyro is mounted on the rear axle with a minimum preview distance set to 1.5 meters) and the proportional part of the feedback controller is turned off (LatPathP) to reduce oscillatory steering behavior. For forward driving: the default settings are used, i.e. the cubic connecting contour Is used. |
PID’s Speed & Path Parameters tab - Defines the Machine Control PID (Proportional, Integral and Derivative) Controller gains for: ■following a longitudinal velocity or longitudinal acceleration profile. ■steering when following a path. ■following a lateral acceleration profile. Note: Increasing gains generally produces a quicker controller response, but it also increases controller sensitivity to input disturbance with the risk of becoming unstable. | |
LonVx P | Proportional gain of Vx compensator used when following a velocity profile (Longitudinal Velocity Feedback). |
LonVx I | Integral gain of Vx compensator used when following a velocity profile (Longitudinal Velocity Feedback). |
LonVx D | Derivative gain of Vx compensator used when following a velocity profile (Longitudinal Velocity Feedback). |
LonAx P | Proportional gain of Ax compensator used when following a longitudinal acceleration profile. |
LonAx I | Integral gain of Ax compensator used when following a longitudinal acceleration profile. |
LonAx D | Derivative gain of Ax compensator used when following a longitudinal acceleration profile. |
LatPth P | Proportional gain of yaw rate compensator used when following a path or target curvature (Yaw Rate Feedback). |
LatPth I | Integral gain of yaw rate compensator used when following a path or target curvature (Yaw Rate Feedback). |
LatPth D | Derivative gain of yaw rate compensator used when following a path or target curvature (Yaw Rate Feedback). |
LatAy P | Proportional gain of curvature compensator used when following a lateral acceleration profile. |
LatAy I | Integral gain of curvature compensator used when following a lateral acceleration profile. |
LatAy D | Derivative gain of curvature compensator used when following a lateral acceleration profile. |
LatAyC P | Proportional gain of Ay compensator used when following a lateral acceleration profile. |
LatAyC I | Integral gain of Ay compensator used when following a lateral acceleration profile. |
PID’s Steering Output Parameters tab - Defines the Machine Control PID (Proportional, Integral and Derivative) Controller gains for steering output for actuator type being set to Force or Torque. Once the required steering wheel angle to follow a specified path is calculated by Machine Control (by the feedforward controller and feedback PID controller using the PID gains as shown above), the PID Steering output controller calculates the Force or Torque required to obtain such a steering wheel angle. | |
SteFrc P | Proportional gain for calculation of steering force output. |
SteFrc I | Integral gain for calculation of steering force output. |
SteFrc D | Derivative gain for calculation of steering force output. |
SteTrq P | Proportional gain for calculation of steering torque output. |
SteTrq I | Integral gain for calculation of steering torque output. |
SteTrq D | Derivative gain for calculation of steering torque output. |
Filters tab - Defines settings for in- and output filters for Machine Control. | |
SigmaCutFreq | Cut-off frequency (Hz) for low-pass filter on feed-forward control steering input signal (default = negative value means no filtering) |
YawVelCutFreq | Cut-off frequency (Hz) for low-pass filter on yaw velocity input signal (default = negative value means no filtering) |
EngSpeedCutFreq | Cut-off frequency (Hz) for low-pass filters on engine speed and transmission input omega signals (default = negative value means no filtering) |
PathPitchCutFreq | Cut-off frequency (Hz) for low-pass filter on the slope (pitch) of the road input (driver path) signal (default = negative value means no filtering) |
SteCutFreq | Cut-off frequency (Hz) for low-pass filter on steering output signal (default = negative value means no filtering) |
ThrCutFreq | Cut-off frequency (Hz) for low-pass filter on throttle output signal (default = negative value means no filtering) |
BrkCutFreq | Cut-off frequency (Hz) for low-pass filter on brake output signal (default = negative value means no filtering) |
You can use two modes for defining various mini-maneuvers: ■Table Editor - To display, select the Arrow tool .  ■Property Editor - To display, you can do either of the following: ■Double-click the mini-maneuver name ■Right-click the mini-maneuver name and select Modify with Property Editor When editing a mini-maneuver in Property Editor mode, you define the five control signals (steering, brake, throttle, clutch, and gear) and the conditions that end or abort the mini-maneuver. (see Creating Event Files) | |
| Select to display the Table Editor. Note that at the bottom of the Table Editor, you can add a new mini-maneuver by entering a string in the Name text box and then selecting Add. |
Active | Set a mini-maneuver to active (yes) or inactive (no). Adams Car only performs active mini-maneuvers. |
Abort Time | Specify the relative time from the beginning of the mini-maneuver when the Driving Machine stops the mini-maneuver. It executes the next mini-maneuver if defined. Value must be > 0.0. |
Step Size | Specify the Adams Solver Output step size. |
Sample Period | Specify Driving Machine discrete GSE sample time. |
Maximum Adams Solver step size determined by stepSize, samplePeriod and hmax. The maximum Adams Solver time step in an Adams Car simulation is determined by the smallest value of output stepSize, samplePeriod and hmax. Both stepSize (.xml event file:section dcf:DcfMini) and samplePeriod (.xml event file dcf:DcfMachine and dcf:DcfSmartDriver) can be set in the Event Builder as part of each mini-maneuver, or by editing the .xml event file directly. Hmax can be set from the Adams Car toolbar under Settings → Solver → Dynamics. For more information about hmax, see Solver Settings - Dynamics. Using the Event Builder, the value entered for samplePeriod will set the discrete GSE samplePeriod parameter for both Driving Machine (.xml event file dcf:DcfMachine) and SmartDriver events (.xml event file dcf:DcfSmartDriver). If you are modifying the .xml event file by hand, please note that when performing a Driving Machine analysis, only the samplePeriod as specified under dcf:DcfMachine in the .xml event file will be used. For a SmartDriver analysis, only the samplePeriod as specified under dcf:DcfSmartDriver will be used. For more information about integrator step size selection when discrete GSE elements are included in the model, see Integrator step size selection. Note: The sampling period for standard Adams Car events may differ (e.g. for the full vehicle analysis ‘Double Lane Change’ this value is set to hmax by executing mini.machine().samplePeriod(self.hmax) in <Adams installation>/python/win64/Lib/site-packages/mdi/afc/chassis/full_vehicle/handling/double_lane_change.py). | |
Steering tab - Define the parameters that control the steering signal during the mini-maneuver that you are creating. | |
Actuator Type | Learn about Specifying an Actuator Type. Note that the actuator types do not necessarily correspond to the actuators defined in your vehicle model. The Event Builder cannot browse your model and populate the Actuator Type option with the actuators actually defined in your model. |
Control Method | When defining a mini-maneuver, you must specify a control method for each control signal. Different options appear depending on the Control Method you selected. The control methods are: ■open - Uses open-loop control where the control signal is a function of time. (see Open Control Method). For open loop (time based output control signals) you will have to define parameters for the appropriate control type. Depending on your selection in the open-loop control type area (adjacent to the parameters mentioned above), you have to specify information to define the shape of the steering control signal. ■machine - Uses closed-loop lateral and longitudinal controllers to follow a path and target velocity or longitudinal acceleration profiles. For machine control, you have to select the type of closed-loop target for the appropriate application area. (see Machine Control Method). ■SmartDriver - Uses a series of race-optimized lateral and longitudinal controllers. (Requires Adams SmartDriver.) For SmartDriver control, you have to define course parameters, such as type of task and course file.(see SmartDriver Control Method). |
If you set Control Method to open, Adams Car displays the following option: | |
Control Type | Learn about Specifying a Control Type. |
If you set Control Type to constant, data_driven, data_map, impulse or step, Adams Car displays the following option: | |
Control Mode | Learn about Specifying a Control Mode. |
Throttle/Braking/Gear/Clutch tabs - Contain the same information as the Steering tab, except that the information applies to the particular signal. Note: It is possible to combine machine controlled throttle with open-loop controlled braking and vice versa. Selecting the throttle respectively braking control method will no longer automatically set the braking respectively throttle control method. | |
Conditions tab | |
Specify a number of conditions for each mini-maneuver. Conditions has two modes: Table Editor and Property Editor, as described next. ■Table Editor - Add new end conditions to the mini-maneuver you are creating. To display, select the Arrow tool . The Table Editor mode gives you access to the complete set of parameters. Learn more about Specifying Conditions. Note that the conditions do not necessarily correspond to the condition defined in your vehicle model. This is an extensive list but the Event Builder cannot browse your model and populate the Type option menu with the condition actually defined in your model. ■Property Editor - Define parameters for the condition. To display, you can do either of the following: ■Double-click the mini-maneuver name ■Right-click the mini-maneuver name and select Modify with Property Editor | |
Actuators tab | |
Specify a number of user-defined actuators for each mini-maneuver. Actuator only supports Table Editor mode, as described next. ■Table Editor - Add new actuators to the mini-maneuver you are creating. The Table Editor mode gives you access to the complete set of parameters. Learn more about Specifying Actuators. Note that the actuators are populated when you launch the Event Builder and will correspond to those user-defined actuators present in the currently active model. | |
Linear tab | |
Specify a number of linear analyses for each mini-maneuver. Linear has two modes: Table Editor and Property Editor, as described next. ■Table Editor - Add new linear analyses to the mini-maneuver you are creating. To display, select the Arrow tool. The Table Editor mode gives you access to a subset of parameters. Learn more about Specifying Linear Analyses. Note that the conditions do not necessarily correspond to the condition defined in your vehicle model. This is an extensive list but the Event Builder cannot browse your model and populate the Type option menu with the condition actually defined in your model. ■Property Editor - Define parameters for the linear analysis. To display, you can do either of the following: ■Double-click the mini-maneuver name ■Right-click the mini-maneuver name and select Modify with Property Editor | |
SmartDriver Setting Template
The SmartDriver Setting Template file (basically an xml event file without events) is used to set default values for Event files. The default values are used when:
■converting .dcf format Event files to .xml format Event files.
■creating new Event files using the Event Builder.
You can use environment variable MSC_SD_DEFAULT_XML to set the path to a custom SmartDriver Setting Template file (.smartdriver.xml). If MSC_SD_DEFAULT_XML is not set, the SmartDriver Setting Template file path search order is as follows:
1. Home directory ($HOME\.smartdriver.xml)
2. \<Adams Installation>\<platform>\ ($topdir\$MDI_CPU\.smartdriver.xml)
Note: | The SmartDriver Setting Template replaces the Environment Variables used to set default values for longitudinal, lateral and steering output PID controller gains (MSC_SD_GAIN_*). |
The following parameters are not yet supported in the Event Builder, but you can modify them directly in the .xml file:
This parameter: | Does the following: | Takes the value: |
|---|---|---|
smoothingTime | Allows you to filter the output of the Machine Control at the concatenation of mini-maneuvers, therefore, helping you avoid discontinuities in the output from the Machine Control. | Real value > 0.0 |
samplePeriod [DcfMachine] | Time interval between two consecutive evaluations of the controller during a closed-loop event. | Real value > 0.0 |
samplePeriod [DcfSmartDriver] | Time interval between two consecutive evaluations of the controller during an Adams SmartDriver event. | Real value > 0.0 |
useBrake | For Chassis models only, specifies if brakes can be used to achieve the specified (negative) target acceleration for staticSetup = Straight or Skidpad. | [yes,no] |
haltOnFailure | Select yes if you want to stop the simulation in case the quasi-static setup phase is not successful. | [yes,no] |
pathPositioning | Defines whether the path must be positioned automatically or whether its location is absolute and must remain unchanged. | [automatic, absolute, default] |
speed_map_filter_flag | activates/deactivates the target speed map low pass filter | true/false |
speed_map_filter_freq | sets the cut-off frequency for the target speed map low pass filter | Real value > 0.0 |
speed_map_spline_flag | activates/deactivates target speed map bspline interpolation | true/false |
speed_map_spline_order | sets the order of the target speed map bspline interpolation | Integer value 2-10 inclusive |