Sensor: Event

Model Element

Description

This model element defines an event sensor in the model.

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.

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.

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.

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.

Comments

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.

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.

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"

Model Element
Description
This model element defines an event sensor in the model. A SENSOR 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.
Declaration
def SENSOR(id, LABEL="", FUNCTION="", VALUE=0.0, ERROR=0.0, OPERATOR="", VERBOSE="" ZERO_CROSSING=0.0, DT=0.0, HMAX=0.0, HALT=False, PRINT=False, RESTART=False, RETURN=False, STEPSIZE=0.0, EVALUATE="", ROUTINE="",SCRIPT=""):
Attributes
id	Element identification number (integer>0). This number is unique among all the SENSOR elements.
LABEL	The name of the SENSOR element. Any alphanumeric string associated with the SENSOR.
FUNCTION	Specifies an expression that defines the sensor event. Any valid run-time MotionSolve expression can be used. Or The list of parameters that are passed from the data file to the user defined SENSUB.
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.
ERROR	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.
OPERATOR	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: FUNCTION >= VALUE LT: FUNCTION < VALUE EQ: FUNCTION = VALUE
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.
DT	Specifies the new print interval to be applied when the event occurs.
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 until the end of the simulation unless changed by another sensor.
HALT	Stops the simulation when the event occurs.
PRINT	Prints an output.
RESTART	Forces MotionSolve to restart the integrator. All integrator history of the system is deleted and the integrator starts over.
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.
STEPSIZE	Specifies the maximum step size for the next trial step. This expires after one step.
EVALUATE	Specifies the function that is evaluated when the sensor becomes active. The value of the SENSOR does not change until the SENSOR detects another event.
ROUTINE	Specifies an alternative name for the user subroutine SENSUB.
SCRIPT	Specifies the path and name of the user written script that contains the routine.
Comments See Sensor_Event
Example The first example demonstrates how to use a SENSOR using expression. SENSOR(100, FUNCTION="ABS(ACCX(21,11,21,11))", VALUE=5, ERROR=0.0001, OPERATOR="GE", HALT=True) The second example demonstrates how to use a SENSOR using USERSUB. SENSOR(200, FUNCTION="USER(21,11)", VALUE=0, ERROR=0.0001, OPERATOR="GE", DT=0.01, ROUTINE="NULL")

Sensor: Event

Sensor: Event

Sensor: Event

Model Element

Description

Format

Attributes

Comments

Example

Model Element

Description

Declaration

Attributes

Comments

Example