Sensor: Event

Model ElementThis model element defines an event sensor in the model.

Description

A Sensor_Event is used to define and monitor events of significance during a simulation. Once an event of interest occurs, you can take action to respond to the event.

For instance, the lateral acceleration of a car body may be monitored to determine whether the car is going out of control during a vehicle simulation. If this quantity becomes larger than a threshold value, you may like to stop the simulation.

As another example, the contact force between two bodies may be monitored to trigger a zero crossing action. This action may help capture the first time that contact occurs in your model more accurately thereby improving your results.

Many different event responses can be automated using Sensor_Event. Some common responses to events are to modify the print interval, restart the integrator, stop the simulation, or change the integrator step size.

Format

<Sensor_Event
     label                 = "string"     
     id                    = "integer"     
     value                 = "real"  
  {  type                  = "EXPRESSION"
     expr                  = "motionsolve_expression"   
   | type                  = "USERSUB"
     usrsub_dll_name       = "valid_path_name"
     usrsub_param_string   = "USER([[par_1[,...][,par_n]])"
     usrsub_fnc_name       = "custom_fnc_name" >   
   | type                  = "USERSUB"
     script_name           = valid_path_name
     interpreter           = "PYTHON" | "MATLAB"
     usrsub_param_string   = "USER( [[par_1 [, ...][,par_n]] )"
     usrsub_fnc_name       = "custom_fnc_name" 
  } 
   [ compare               = { "GE" | "LT" | "EQ" }  ]   
   [ evaluate_id           = "integer" ]   
   [ error_tol             = "real" ]   
   [ dt                    = "real" ]   
   [ stepsize              = "real" ]   
   [ zero_crossing         = "real" ]  
   [ hmax                  = "real" ]      
   [ halt                  = { "TRUE" | "FALSE" } ]   
   [ print                 = { "TRUE" | "FALSE" } ]  
   [ restart               = { "TRUE" | "FALSE" } ] 
   [ verbose               = { "TRUE" | "FALSE" } ]      
   [ return                = { "TRUE" | "FALSE" } ] 
/>

Attributes

label
Any alphanumeric string associated with the Sensor_Event.
id
Element identification number (integer>0). This number is unique among all Sensor_Event elements.
value
The sensor event threshold. An event is said to occur when the expression or user subroutine meets the comparison criterion with respect to value.
type
Select from EXPRESSION and USERSUB. Specifies how the event expression is defined.
The EXPRESSION option specifies that the event value is a MotionSolve expression that can be evaluated at run-time.
The USERSUB option indicates that the value of the event is specified in a user-written subroutine. The parameters "usrsub_param_string" and "usrsub_dll_name" are used to provide more information about the user defined subroutine SENSUB.
expr
Specifies an expression that defines the sensor event. Use this parameter only when type = EXPRESSION. Any valid run-time MotionSolve expression can be used.
compare
Defines the comparison measure.
Select from GE, LT, or EQ. The comparison measures are used to detect when an event has occurred and are implemented as follows:
  • GE: expr >= value
  • LT: expr < value
  • EQ: expr = value
evaluate_id
Specifies the ID of a Sensor_Evaluate element that is evaluated when the sensor becomes active. The value of the Sensor_Evaluate does not change until the Sensor detects another event.
error_tol
Defines the error tolerance for detecting an event. The sensed value is required to be within this tolerance of the threshold value, before an event is generated by the solver.
usrsub_param_string
The list of parameters that are passed from the data file to the user defined SENSUB. Use this keyword only when type = USERSUB is selected.
usrsub_dll_name
Specifies the path and name of the DLL or shared library containing the user subroutine. MotionSolve uses this information to load the user subroutine SENSUB in the DLL at run time.
dt
Specifies the new print interval to be applied when the event occurs.
stepsize
Specifies the maximum stepsize for the next trial step. This expires after one step.
zero_crossing
Specifies the tolerance for the zero crossing search. The tolerance is defined as the value of zero_crossing multiplied by the current hmax. The search stops when the time reaches the exact time the event happens within this tolerance. See Comment 3 for details.
hmax
Specifies the value of the maximum step size the solver is allowed to take as soon as the sensor is triggered. This value persists till the end of the simulation unless changed by another sensor. See Comment 3 for details.
halt
Stops the simulation when the event occurs.
usrsub_fnc_name
Specifies an alternative name for the user-written subroutine SENSUB.
script_name
Specifies the path and name of the user written script that contains the routine specified by usrsub_fnc_name. Use this keyword only when type = USERSUB is selected.
interpreter
Specifies the interpreted language that the user script is written in. Valid choices are MATLAB or PYTHON.
print
Prints an output.
restart
Forces MotionSolve to restart the integrator. All integrator history of the system is deleted and the integrator starts over.
verbose
Use this attribute to control how often an action message is written to the screen and log file when a sensor is triggered.
TRUE: MotionSolve writes out information about the action triggered by the sensor at each reported time step as long as the sensor is active. Note: setting verbose to TRUE may cause these messages to comprise a majority of the content for the log file.
FALSE: MotionSolve writes out the information about the action triggered by the sensor only once, at the very first time the sensor is triggered.
Default is FALSE.
return
Returns control of the program to the command processor so the next command can be processed. If there are no more commands, simulation is halted.

Example

The sensor shown below monitors the absolute value of the x-component of the acceleration of Marker 21 with respect to Marker 11 in the coordinate system of Marker 21. All time derivatives are taken in the reference frame associated with Marker 11. When the monitored value goes above 5 (m/s2), the expression in Sensor_Evaluate/100 is to be evaluated and the simulation is to be halted. An error tolerance of 1e-4 is to be used to monitor the event.

A sensor such as this can be used to stop a vehicle simulation when it is obvious that the vehicle is out of control.

< Sensor_Event
   id                  = "100"
   type                = "EXPRESSION"
   expr                = "ABS( ACCX(21,11,21,11) )"
   compare             = "GE"
   value               = "5"
   evaluate_id         = "100"
   error_tol           = "0.0001"
   halt                = "TRUE" 
/>

The sensor shown below monitors the value returned by SENSUB. When the monitored value goes above 5, the expression in Sensor_Evaluate/200 is to be evaluated and the simulation print interval is to be changed to 1e-2. An error tolerance of 1e-4 is to be used to monitor the event.

A sensor like this can be used to change the frequency of output when an event of interest occurs.

<Sensor_Event
  id                  = "200"
  type                = "USERSUB"
  usrsub_param_string = "USER(22,11)"
  usrsub_dll_name     = "NULL"
  compare             = "GE"
  value               = "0."
  evaluate_id         = "200"
  error_tol           = "0.0001"
  dt                  = "1e-2"
/>

Comments

  1. Many systems are characterized by discrete events wherein the underlying equations can change. A hydraulic system in which a valve is open or shut is one common example. Different sets of equations define the system at each of these configurations. A Sensor_Event element can be used to detect the event (opening/closing of the valve) and force the system to reformulate the system equations when the transition occurs. The Sensor_Evaluate can be used to store the state of the system (valve open or closed).

    Each Sensor_Event can have one or more sensor actions defined within it, in other words, these actions will be executed each time the sensor is triggered.

  2. A common use of Sensor_Event is to stop the simulation when certain end conditions are met. Since the end conditions may be a function of state, they cannot be specified explicitly in the Param_Transient statement.
  3. Another typical usage of the Sensor_Event is to accurately capture the time of first contact for a model containing contact elements via the zero crossing action. This is useful in getting realistic contact forces without having to run the entire simulation at a small step size. To do this, the sensor monitors the contact force for a contact pair in the model. As soon as contact is first detected, the zero_crossing action is triggered.
    When zero_crossing is present in a Sensor_Event, MotionSolve saves the complete states at each converged step in memory. When the event occur, MotionSolve:
    • Resets the sensor
    • Goes back to the previous converged time
    • Restores all system states at the previous converged time
    • Reduces the hmax to the zero_crossing times the current hmax; reduces the hmin to the zero_crossing times the current hmin and marches forward with this reduced hmax/hmin combination.

      Typical zero_crossing value is 0.01 (1%) to 0.001 (0.1%). Thus, when the next time the event is triggered, the solution time will be closer to (within the reduced hmax) the exact time the event criteria is satisfied. The solver then resets the sensor and restores the previous hmax/hmin before the step size was reduced.

      Other actions, such as hmax may be optionally used in this scenario to reduce the solver step size permanently after contact is detected. This change remains permanent till the end of the simulation or until it is changed by another sensor action or control subroutine (CONSUB).

  4. A less common use of Sensor_Event is to force an output when an event of interest occurs. For instance, if you are modeling a force using an IMPACT() MotionSolve expression, you might be interested in forcing an output whenever impact occurs. This allows the system to accurately the impact force.