The math models in VehicleSim products can be extended several ways:

- The VS Math Model can be connected to a model in another simulation environment, such as Simulink.
- Equations and and variables can be added using VS Commands.
- Variables can be exchanged with custom programs as is done with Simulink.
- Variables in the math model can be accessed directly by custom programs that support C/C++ pointers.

This page describes the main uses of VS Commands.

# VS Commands

A VS Solver is a program in a VehicleSim product that reads input files, writes output files, and calculates variables from an internal math model. Besides scanning input files for keywords associated with parameters and tables, the VS Solvers look for VS Commands that can apply advanced analyses (e.g., Linearization), set up advanced procedures with VS Events, add variables, add equations, and perform other actions.

VS solvers support a symbolic calculator that allows inputs to be expressed either numerically or in terms of formulas involving other model parameters and variables.

The solver programs also include a preprocessor with advanced commands that allow users to customize and extend the models by adding equations at run time. Import variables can be assigned to formulas involving other model variables. For example, road friction variables for each tire can be redefined with equations defined at runtime that are based on other variables in the model.

## Define New Parameter and Variables

New variables may be defined at run-time for a variety of purposes: import, export and output, constant parameters, and auxiliary variables used in other equations. VS Commands can also be used to add degrees of freedom in the form of new state variables that will be calculated by numerical integration of corresponding user-defined differential equations.

### Units

VS Solvers maintain two sets of units. Internal SI units are used in all equations, such the no scale factors are ever used. Angles are radians, lengths are meters, time is seconds, etc. User units are assigned to every variable that is not an integer. By default, these are commonly used units for the associated parameters or variables: angles are degrees, dimensions are mm, vehicle speed is km/h, acceleration is g, etc.

All user units of all parameters and variables can be changed using VS Commands. Further, new units can be defined and assigned to any parameters or variables. For example, forward vehicle speed, normally presented in km/h, is sometimes set for mi/h, m/s, or other units.

### Add Equations to the Model

New variables added with VS Commands can be calculated with equations that are also defined with VS Commands. The equations can be algebraic, involving all existing and new variables and parameters in the model. Differential equations can also be added; algebraic equations are defined at run time for the derivatives of the new variables.

Equations can be inserted at various times in the simulation: during initialization, at the start of a time step, and the end of a time step, etc.

Equations can also be added for existing import variables that are available for working with external software. Rather than obtaining forces, moments, controls, etc. from external software such as Simulink, they can be defined using equations specified with VS Commands. For example, specify forces and moments to constrain the vehicle sprung mass for simulated K&C tests, such as the CarSim example shown at the top of this page, or the Tilt Table TruckSim example.

## VS Events

One of the most powerful capabilities is the **VS Event**. Pending
events are set up, in which a variable is monitored and compared to a formula
(a number, another variable, or a symbolic expression involving other variables
and built-in functions). When the comparison (<, >, =, etc.) is true,
then a new data file is loaded that can change almost anything in the model.
Go from open-loop to closed-loop control; replace a tire; change roads; reset
some vehicle condition; enable and disable writing to file.

Events are commonly used to script complicated test procedures and extend the math model by adding new sensitivities. For example, see the sine with dwell CarSim example.

## Linearize

The vehicle math models in VehicleSim products include nonlinear ordinary differential equations (ODEs). These are used to calculated the response of the model to driver controls, interactions with the ground, etc. as functions of time. In normal operation, simulated test results are viewed and analyzed using the same methods as used for physical testing.

Prior to the availability of high-speed digital computers, researchers and engineers typically studied dynamic systems by analytic frequency-domain methods such as Eigenvalues and Bode plotting. These methods have been used in automotive dynamic analyses since the 1950s, and in motorcycle dynamic analyses since the 1970s. The classical frequency-domain methods are all based on system models with linear equations of motion.

Although the full VS model equations are nonlinear, the behavior of the full
system can be approximated as a linear system at any time during a simulation
run using perturbation. At any time during the simulation
run, the VS Command ** LINEARIZE** can be used to
apply a built-in perturbation algorithm to create A, B, C, and D matrices for
the linearized system, and write them into a MATLAB M-file. After the simulation
run has finished, M-files generated during the run can be loaded into MATLAB
for analysis. This feature is commonly used for BikeSim analysis for identifying
modes of vibration; as a VS feature it is also available for all time-domain
models.

Note: the perturbation method is not valid with HIL systems or models that have been extended in external software that has its own ODEs.

## Backing Up In Time to a Saved State

VS Solvers
have the built-in capability take a "snapshot"
of the current state of the VS Math Model and save it in memory for possible
future use. The snapshot consists of the current simulation time, plus the
current values of all state variables (including the built-in variables, those
added with VS Commands, and those added with VS API functions), and the current
values of all active Import variables (if there are any). This can be done
at constant intervals with the VS Command ** START_SAVE_TIMER**,
or only at times of interest, using the VS Command

**when a VS Event is triggered.**

`SAVE_STATE`

Another command ** RESTORE_STATE** is used to restore
a saved state. This command is triggered with a VS Event, and is done after
changing model parameters to change the behavior for the next try.

The SAVE/RESTORE capability is used internally to perform the perturbations
that underlie the ** LINEARIZE** command. The capability
is also available for advanced users involved with repetitive situations, such
as optimizations or advanced control algorithms. For example, TruckSim PBS
includes tests where the driver is required to steer the vehicle such that
the sidewall of a front tire follows a specified path with a tolerance of 50
mm. This is done with an save/restore method that checks the lateral error,
and if a failure occurs, the target is adjusted and the model jumps back in
time to continue with a new target for the controller.

CarSim engineers have worked with race engineers from NASCAR, Formula 1, ALMS, and IndyCar series to set up similar control strategies to limit braking and throttle controls for a turn. If the vehicle can't follow the path, the model jumps back in time and a modified control is attempted.

## VehicleSim Products

BikeSimCarSim

TruckSim

SuspensionSim

## VS Vehicle Model Features

Paths and RoadsMoving Objects and ADAS Sensors

## Core VehicleSim Technology

GUI, Database, and DocumentationFast and Parametric Math Model Solvers

Viewing Results: Animation and Plotting

## Advanced Applications

Simulink, LabVIEW, and ASCETVS Commands

VS API

Automation and COM

Custom Work

## Real-Time Options

Real-Time HIL TestingDriving Simulators