XML Format

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>


Figure 1.

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>

Comments

  1. Many of the algorithms in MotionSolve are non-linear and iterative solution schemes are commonly used. It is possible that during the iterations, the independent coordinate for the spline may fall outside the range of data provided. This is not too serious, especially if the converged solution lies within the range provided. Use linear_extra = TRUE to do this.
  2. You should be concerned about the quality of your solution when the converged value of a solution requires extrapolated spline data. This is an indication that your Reference_Spline did not have the required range of data in it. It is best if you add more data points to the Reference_Spline when this happens.
  3. Spline fitting algorithms are typically not very good at handling sharp corners in the spline data. In order to minimize unrealistic shapes in the interpolated data, increase the density of points at locations where you know the spline is going to change its slope quickly.
  4. Frequently, Reference_Splines are used to store experimental data. Experimental data tends to be noisy and has a lot of high frequency content. Such data can significantly slow the performance of MotionSolve (or any other solver). Use low pass filters or some other signal processing mechanism to remove noise from the measured signal before providing it to MotionSolve. Low pass filters can be found in the Math Reference.
  5. The Reference_Spline is not the same as a Reference_ParamCurve. The former just fits data without assuming any underlying parameterization. The latter is used to define parameterized, curvilinear shapes in 3-D space.