# Reference: Spline

Model ElementReference_Spline defines spline with two or three independent variables.

## Description

The spline data can be specified in two different ways: 1) Write a Spline_Read user defined subroutine to read the data from a file or 2) Directly embed the data points in the XML input file. The first approach is preferred when either the number of data points is very large or the data is stored in a binary file. The latter approach is preferred for small to medium sized curves (<1000 points).

Splines have many varied applications in MotionSolve. Some of these are listed below.

• Forces: They are used to define nonlinear characteristics for the forces. The spline may represent a spring force vs. deformation characteristic or a damping force vs. deformation velocity characteristic. This data is frequently measured experimentally.
• Motions: They are used to define displacements vs. time, velocity vs. time, and/or acceleration vs. time data. As with forces, this data is frequently measured experimentally.
• Variables, Diffs: Splines may be used to define relationships that are difficult to describe analytically.

Interpolation for the Reference_Spline data can be done either using the AKIMA (AKISPL) or the CUBIC (CUBSPL) interpolation method. These functions are supported in the MotionSolve expression language. Both AKIMA and CUBIC use cubic polynomials to perform interpolation, but differ in many important ways.

The AKIMA fitting algorithm uses local methods to calculate the spline coefficients. No matrices are ever inverted. For this reason, it is preferred when the reference spline has many data points. The key disadvantage with this method is that is has non-smooth derivatives, especially when the data points are not equally spaced. The AKIMA method consequently must never be used for interpolating Motion data.

The Cubic fitting algorithm ensures a much smoother fit by utilizing natural splines. Consequently, it is much better at calculating derivatives of the resulting spline. However, it is not good at modeling sharp corners in the data.

For splines with two independent variables (3D splines), the interpolation along the second independent variable is always linear, regardless of the choice of interpolation along the first independent variable.

## Format


<Reference_Spline
id                  = "integer"
[ label               = "string" ]
[ linear_extrap       = { "TRUE" | "FALSE" } ]
{
usrsub_dll_name     = "valid_path_name"
usrsub_fnc_name     = "custom_fnc_name" >
|
script_name         = valid_path_name
interpreter         = "PYTHON" | "MATLAB"
usrsub_fnc_name     = "custom_fnc_name" >

file_name           = "valid_file_name"
[ block_name          = "valid_block_name" ]

| num_x               = "integer"
[ num_z               = "integer" ] >
< !-- X      Y for Z1      Y for Z2      Y for ZNUM_Z -->
x1         y1,1     y1,2     ...        y1,NUM_Z
x2         y2,1     y2,2     ...        y2,NUM_Z
...
XNUM_X     yNUM_X,1  yNUM_X,2  ...        yNUM_X,NUM_Z

}
<!-- Z values -->
Z1   Z2  …   ZNUM_Z
</Reference_Spline>

## Attributes

id
Element identification number (integer>0). This is a number that is unique among all Reference_Spline elements.
label
The name of the Reference_Spline element.
linear_extrap

A logical flag that specifies how MotionSolve is to deal with the situation when the independent coordinate falls out of the range of data provided.

The value TRUE indicates that MotionSolve is to use linear extrapolation to estimate the spline value.

The value FALSE indicates that MotionSolve should not extrapolate; instead it should return an error.

num_x
Specifies the number of X points in the spline. Use this option only when the data is directly embedded in the XML file.
num_z
Specifies the number of Z points in the spline. Use this option only when the data is directly embedded in the XML file. This parameter is only required for 3D splines.
usrsub_dll_name
Specifies the path and name of the DLL or shared library containing the user subroutine, Spline_Read. After reading the data, Spline_Read calls Put_Spline to transfer the data to MotionSolve. MotionSolve uses this information to load the user subroutine Spline_Read in the DLL at run time. Use only when the data is contained in an external file.
usrsub_fnc_name
Specifies an alternative name for the user subroutine Spline_Read.
script_name
Specifies the path and name of the user written script that contains the routine specified by usrsub_fnc_name.
interpreter
Specifies the interpreted language that the user script is written in. Valid choices are MATLAB or PYTHON.
file_name
Specifies the path and name of the file containing the spline data. Use only when the data is contained in an external file.
block_name
Specifies the block name containing the spline data. A single file may contain several blocks of data. This parameter is optional. Use only when the data is contained in an external file.

## Example

The following example depicts an experimentally measured steering wheel angle versus time profile that is to be used in a motion definition. The data is embedded directly in the XML input file. The abscissa (x-value) represents simulation time and the ordinate (y-value) represents the steering wheel angle.

<Reference_Spline
id            = "301001"
num_x         = "11">
0.00E+00   1.09E+00
1.00E-01   6.88E+00
2.00E-01   2.52E+00
3.00E-01   3.02E+00
4.00E-01   3.30E+00
5.00E-01   3.23E+00
6.00E-01  -8.91E-02
7.00E-01  -4.20E+00
8.00E-01  -3.00E+00
9.00E-01   2.05E+00
1.00E+00   0.04E+00
</ Reference_Spline>

The second example demonstrates an alternate implementation of the previous one. The key difference is that the data is now encapsulated in an external file. A user defined subroutine, Spline_Read, is used to read the data. Spline_Read calls Put_Spline to populate the MotionSolve database with the spline data.

/staff/gates/curveData/wheel.so is the DLL containing the user defined Spline_Read that reads the spline data. After reading the data, it calls the solver utility function Put_Spline to put the reference spline data into solver memory.

/staff/gates/curveData/springs/wheel_1.dat contains the spline data. The file contains several blocks of data. The data of interest is stored in the block called wheel_angle.

<Reference_Spline
id                  = "301001"
usrsub_dll_name     = "/staff/gates/curveData/wheel.so"
file_name           = "/staff/gates/curveData/springs/wheel_1.dat"
block_name          = "wheel_angle">
</ Reference_Spline>

The following example demonstrates a 3D spline.

<Reference_Spline
id                 = "301001"
num_x              = "5"
num_z              = "3">
<!--    X            Y for Z1      Y for Z2      Y for Z3 -->
0.0000000E+00   0.0000000E+00  0.0000000E+00  0.0000000E+00
2.5000000E-01   5.0000000E-01  7.0000000E-01  9.0000000E-01
5.0000000E-01   0.0000000E+00  0.0000000E+00  0.0000000E+00
7.5000000E-01   5.0000000E-01  7.0000000E-01  9.0000000E-01
1.0000000E+00   0.0000000E+00  0.0000000E+00  0.0000000E+00
<!-- Z values -->
0.0 1.0 20.0
</Reference_Spline>