SENSOR
The SENSOR statement is used to modify the simulation when a user-defined event occurs during run-time. The event is defined by a logical expression which compares an expression to a target value. If the logical expression becomes true during the simulation, the sensor modifies the simulation by the means described below.
Format
Arguments
CODGEN | Generates a new pivot sequence for matrix factorization when the event Adams Solver (FORTRAN) is monitoring becomes true. This may help the integrator to produce more accurate data or to proceed more smoothly at troublesome points in time. A pivot sequence for matrix factorization is generated before the start of a simulation. A new pivot sequence is not generated unless the CODGEN argument is used or Adams Solver (FORTRAN) determines it is necessary to reach convergence. Default: Off |
DT=r | Redefines the time between consecutive output steps when the event Adams Solver (FORTRAN) is monitoring becomes true. Default: Time between output steps determined by SIMULATE command |
EQ | Used to define the event logical expression. The event is true (active) if the function expression (or user-written subroutine) minus VALUE is equal or less than ERROR. Default: EQ |
ERROR=r | Used to define the event logical expression. ERROR specifies the absolute value of allowable error to be realized in VALUE. Default: 0.001 |
 | Specifies an expression or defines and passes constants to a user-written subroutine that is evaluated when the event Adams Solver (FORTRAN) is monitoring becomes true. The scalar value of the expression or the return value of the user-written subroutine can then be obtained using the SENVAL function expression. If you want to define the evaluated function with an expression, EVALUATE must be followed with an equal sign and the expression. If you want to define the evaluated function with a user-subroutine, FUNCTION must be followed with an equal sign, the character string USER, and the selected values (r1[,...,r30]) that Adams Solver (FORTRAN) passes to the user-written subroutine SEVSUB. If the EVALUATE argument is used, it must either be the last argument in the SENSOR statement or be followed by a backslash (\). |
EVALUATE_ROUTINE=libname::subname | Specifies an alternative library and name for the user subroutine SEVSUB. Learn more about the ROUTINE Argument. |
 | Specifies an expression or defines and passes constants to a user-written subroutine to define the event logical expression. To define an expression, follow FUNCTION with an equal sign and the expression (e). To define a user-written subroutine, follow FUNCTION with an equal sign, the character string USER, and the values (r1[,...,r30]) that you want Adams Solver (FORTRAN) to pass to the user-written subroutine SENSUB. If the FUNCTION argument is used, it must either be the last argument in the SENSOR statement, or be followed by a backslash (\). Default: None Range: An expression or user-parameter list of 1 to 30 real values |
GE | Used to define the event logical expression. The event is true (active) if the function or user-written subroutine is equal to or greater than (VALUE-ERROR). Default: EQ |
HALT | Terminates execution when the event Adams Solver (FORTRAN) is monitoring becomes true (active). Default: Off |
LE | Used to define the event logical expression. The event is true (active) if the function or user-written subroutine is equal to or less than (VALUE + ERROR). Default: EQ |
PRINT | Writes data to the request, graphics, and output files when the event Adams Solver (FORTRAN) is monitoring becomes true. Default: Off |
RESTART | Restarts the integration when the event Adams Solver (FORTRAN) is monitoring becomes true. Adams Solver (FORTRAN) reduces the integration order to one. If the SENSOR includes STEPSIZE, the integration step size is reinitialized to the specified value. If you do not specify STEPSIZE, Adams Solver (FORTRAN) reinitializes the integration step size to HINIT. Default: Off |
RETURN | Stops the simulation and returns to the command level when the event Adams Solver (FORTRAN) is monitoring becomes true. Default: Off |
ROUTINE=libname::subname | Specifies an alternative library and name for the user subroutine SENSUB. Learn more about the ROUTINE Argument. |
STEPSIZE=r | Redefines the trial integration step size when the event Adams Solver (FORTRAN) is monitoring becomes true. This change is temporary and lasts only for the next step. Default: An integrator determined value except when the SENSOR statement includes the RESTART argument. In this case, STEPSIZE defaults to HINIT. Range: STEPSIZE > 0 |
VALUE=r | Specifies the value to be compared to the function expression (or evaluation of the user-written subroutine). When using GE with VALUE, the event logical expression is true only if the function expression is equal or greater than (VALUE - ERROR). When using EQ with VALUE, the event logical expression is true only if the absolute value of the function expression minus VALUE is equal or less than ERROR. When using LE with VALUE, the event logical expression is true only if the function expression is less than (VALUE + ERROR). Default: None Range: Any real number |
YYDUMP | Dumps the state variable vector when the event Adams Solver (FORTRAN) is monitoring becomes true. Default: Off |
Extended Definition
The SENSOR statement defines a user-defined event that affects a set of simulation controls when the event occurs. The event is defined by a logical expression that compares a function expression (or evaluation of a user-written subroutine) to a target value using a relational operator. If the logical expression becomes true during the simulation, the sensor modifies a set of simulation controls, which include output and integration step sizes, simulation end time, and the Jacobian pivot sequence. A sensor can also output diagnostic information and store the value of a function expression for later recall.
The Adams Solver (FORTRAN) evaluates the logical expression after every successful integration step when doing dynamic analysis and after every successful output step when doing other types of analyses. To define the function, use a function expression or a user-written subroutine. More information on valid function expressions. User-written subroutines and utility subroutines discuss the subroutines they can access.
Caution: | ■The SENSOR function must be continuous because Adams Solver (FORTRAN) tries to adjust the step size to find the exact time when the sensor becomes active. This process is inaccurate and time consuming when the function is discontinuous. For that reason, functions of time or displacements work best for sensors; functions of velocities, accelerations, and forces are less desirable. |
■Adams Solver (FORTRAN) tests the sensor after every successful time step during dynamic analyses and after every output step during other analyses. If the sensor becomes active, Adams Solver (FORTRAN) modifies the simulation control accordingly and does not test the sensor again until it has completed three time steps. Then, Adams Solver (FORTRAN) again tests the sensor after every time step. | |
■If you want Adams Solver (FORTRAN) to take an action, make sure to include one of the action arguments (CODGEN, DT, HALT, PRINT, RESTART, RETURN, STEPSIZE, EVALUATE, and YYDUMP) in the SENSOR statement. The sensor can become active even if one of the action arguments is not included. However, Adams Solver (FORTRAN) does not, of course, take action unless one is specified. | |
■If a MOTION statement generates nonzero initial part accelerations, the Adams Solver (FORTRAN) integrator may not produce reliable accelerations and velocities for the first two or three internal integration steps. Adams Solver (FORTRAN) automatically corrects for this, so that the values returned at the first output step are accurate. A SENSOR, however, that depends on the accelerations or reaction forces due to this motion may trip unexpectedly prior to the first output step, even though the solution appears correct when the SENSOR is removed. If this occurs, you should modify the displacement function in the MOTION statement so that the initial accelerations are zero. | |
■In some cases, Adams Solver (FORTRAN) may not be able to use the specified STEPSIZE. ■If this step size gives poor convergence or generates too much error, Adams Solver(FORTRAN) tries other step sizes. ■For those INTEGRATOR statements where you set INTERPOLATE=OFF, if the specified step size steps past the next output step, Adams Solver (FORTRAN) reduces the step size to reach the output step exactly. ■If the specified step size is larger than HMAX, Adams Solver (FORTRAN) uses HMAX. ■If the specified step size is smaller than HMIN, and you specify RESTART, the value of HMIN overrides the value of STEPSIZE. | |
■Adams Solver (FORTRAN) may occasionally have difficulty enforcing an equality (EQ) SENSOR, especially if the specified error is very small. In these cases, Adams Solver (FORTRAN) may appear to pass through the sensed value without invoking the sensor action. If this occurs, you should try increasing the error tolerance, if possible. An alternative is to change to an inequality (GE or LE) sensor, then DEACTIVATE the sensor after it has triggered. |
Examples
SENSOR/231, FUNCTION=DX(0201,0307)/
,VALUE=3.24, RETURN
,VALUE=3.24, RETURN
This SENSOR statement senses the x-component for the displacement of Marker 0201 with respect to Marker 0307 and resolves the displacement in the ground coordinate system (GCS). When the relative x displacement equals 3.24 (+/_ 0.001), the statement stops the simulation and returns to the command level.
See other Analysis parameters available.