|
|
In this Topic Hide
Only a few of the approx. 200 functions are documented here. For the rest, please refer to the Script Reference Manual/Function Reference. The ones detailed here are the functions that accept and return numeric values and that could conceivably used for graph plots.
Returns absolute value or magnitude of argument. This function is identical to the mag() function.
Same as phase() except the result wraps at 180/-180 degrees.
Same as phase_rad() except the result wraps at $\pi/-\pi$ radians.
Returns the arc tangent of its argument. If degrees option is set return value is in degrees otherwise radians.
Return cosine of argument in radians. Use cos_deg if the argument is in degrees.
Returns 20*log10(mag(argument))
Returns the derivative of the argument with respect to its reference (x-values). If the argument has no reference the function returns the derivative with respect to the argument's index - in effect a vector containing the difference between successive values in the argument.
Returns e raised to the power of argument. If the argument is greater than 709.016, an overflow error occurs.
| Arg1 | Vector to be processed |
| Arg2 | String specifying window type. Possible values are: Hanning (default) and None |
Performs a Fast Fourier Transform on supplied vector. The number of points used is the next binary power higher than the length of argument 1. Excess points are zero-filled. Window used may be Hanning (default) or None.
Users should note that using this function applied to raw transient analysis data will not produce meaningful results as the values are unevenly spaced. If you apply this function to simulation data, you must either specify that the simulator outputs at fixed intervals (select the Output at interval option in the Choose Analysis dialog box) or you must interpolate the results using the Interp() function. (The FFT plotting menu items run a script which interpolate the data if it detects that the results are unevenly spaced. Use of these menus does not require special consideration by the user.)
Further information on FFTs can be found in Fourier Analysis.
| Arg1 | Vector to be filtered |
| Arg2 | Filter coefficients |
| Arg3 | Initial conditions. Default - all zero |
Performs Finite Impulse Response digital filtering on supplied vector. This function performs the operation:
\[ y_n = x_n \cdot c_0 + x_{n-1} \cdot c_1 + x_{n-2} . c_2 ... \]
Where:
The third argument provide the history of $x$ i.e. $x_{-1}, x_{-2}$ etc. as required.
The operation of this function (and also the IIR() function) is simple but its application can be the subject of several volumes! Below is the simple case of a four sample rolling average. In principle an almost unlimited range of FIR filtering operations may be performed using this function. Any text on Digital Signal Processing will provide further details.
Users should note that using this function applied to raw transient analysis data will not produce meaningful results as the values are unevenly spaced. If you apply this function to simulation data, you must either specify that the simulator outputs at fixed intervals (select the Output at interval option in the Choose Analysis dialog box) or you must interpolate the results using the Interp() function.
Suppose a vector VOUT exist in the current group (simulation results). The following will plot VOUT with a 4 sample rolling average applied
| Plot FIR(vout, [0.25, 0.25, 0.25, 0.25]) |
Alternatively, the following does the same
| Plot FIR(vout, 0.25*unitvec(4)) |
Returns the argument truncated to the next lowest integer.
| Floor(3.45) = 3 |
| Floor(7.89) = 7 |
| Floor(-3.45) = -4 |
Returns the group delay of the argument. Group delay is defined as:
\[ \frac{d\left(\text{phase}\left(y\right)\right)}{dx}\cdot\frac{1}{2\pi} \]
where y is the supplied vector and x is its reference. The GroupDelay() function expects the result of AC analysis where y is a voltage or current and its reference is frequency.
This function will yield an error if its argument is complex and has no reference.
| Arg1 | Vector |
| Arg2 Number of bins |
Creates a histogram of argument 1 with the number of bins specified by argument 2. The bins are divided evenly between the maximum and minimum values in the argument.
Histograms are useful for finding information about waveforms that are difficult to determine by other means. They are particularly useful for finding flat areas such as the flat tops of pulses as these appear as well defined peaks. The Histogram() function is used in the rise and fall time scripts for this purpose.
Users should note that using this function applied to raw transient analysis data will produce misleading results as the simulation values are unevenly spaced. If you apply this function to simulation data, you must either specify that the simulator outputs at fixed intervals (select the Output at interval option in the Choose Analysis dialog box) or you must interpolate the results using the Interp() function.
| Arg1 | Test |
| Arg2 | Result if test TRUE |
| Arg3 | Result if test FALSE |
Arg2 and Arg3 must both be the same type
If the first argument evaluates to TRUE (i.e. non-zero) the function will return the value of argument 2. Otherwise it will return the value of argument 3. Note that the type of arguments 2 and 3 must both be the same. No implicit type conversion will be performed on these arguments.
| Arg1 | Vector to be filtered |
| Arg2 | Coefficients |
| Arg3 | Initial conditions - default zero |
Performs Infinite Impulse Response digital filtering on supplied vector. This function performs the operation:
\[ y_n = x_n . c_0 + y_{n-1} . c_1 + y_{n-2} . c_2 ... \]
Where:
The third argument provide the history of $y$ i.e. $y_{-1}, y_{-2}$ etc. as required.
The operation of this function (and also the FIR() function) is simple but its application can be the subject of several volumes! In principle an almost unlimited range of IIR filtering operations may be performed using this function. Any text on Digital Signal Processing will provide further details.
Users should note that using this function applied to raw transient analysis data will not produce meaningful results as the values are unevenly spaced. If you apply this function to simulation data, you must either specify that the simulator outputs at fixed intervals (select the Output at interval option in the Choose Analysis dialog box) or you must interpolate the results using the Interp() function. The following graph shows the result of applying a simple first order IIR filter to a step:
The coefficients used give a time constant of 10 * the sample interval. In the above the sample interval was 1μSec so giving a 10μSec time constant. As can be seen a first order IIR filter has exactly the same response as an single pole RC network. A general first order function is:
\[ y_n = x_n . c_0 + y_{n-1} . c_1 \]
where
The above example is simple but it is possible to construct much more complex filters using this function. While it is also possible to place analog representations on the circuit being simulated, use of the IIR function permits viewing of filtered waveforms after a simulation run has completed. This is especially useful if the run took a long time to complete.
Returns imaginary part of argument.
Integrates the argument with respect to its reference (x-values).
The function uses simple trapezoidal integration.
An error will occur if the argument supplied has no reference.
| Arg1 | Vector to be interpolated |
| Arg2 | Number of points in result |
| Arg3 | Interpolation order |
| Arg4 | (Boolean) include last point |
Returns a vector with length specified by argument 2 obtained by interpolating the vector supplied as argument 1 at evenly spaced intervals. The optional third argument specifies the interpolation order. This can be any integer 1 or greater but in practice there are seldom reasons to use values greater than 4.
The Interp() function overcomes some of the problems caused by the fact that raw transient analysis results are unevenly spaced. It is used by the FFT plotting scripts to provide evenly spaced sample points for the FFT() function. The Interp() function also makes it possible to perform operations on two vectors that originated from different transient runs and therefore will have different sample points.
Returns 1 (=TRUE) if the supplied argument is complex and 0 (=FALSE) if the argument is any other type
Returns the number of elements in the argument. The result will be 1 for a scalar and 0 for an empty value.
The length() function is the only function which will not return an error if supplied with an empty value. Empty variables are returned by some functions when they cannot produce a return value. All other functions and operators will yield an error if presented with an empty value and abort any script that called it.
Returns the natural logarithm of the argument.
If the argument is real and 0 or negative an error will result. If the argument is complex it will return a complex result even if the imaginary part is 0 and the real part negative.
E.g.
| ln(-1) |
will produce an error. But:
| ln((-1,0)) |
will give the answer $(0,3.1415926535897931) = j\pi$.
An error will always occur if both real and imaginary parts are zero.
See notes for the log10() function.
Returns log to base 10 of argument. In general, we recommend using log10 rather than log. Software products of all types vary in their interpretation of log(). Some treat it as log to the base 10 and others treat it as log to the base $e$. By using log10() there will never be any doubt.
See notes for the ln() function
The data output by the simulator when running an AC or TF analysis is complex. As described in Using ln() with Negative or Complex Values, all SIMetrix logarithm functions correctly handle complex arguments and return a complex value. This means that the following expression to calculate dB will not produce the expected result:
| 20*log(data) |
where data is a value produced by an AC analysis simulation. What you should do is:
| 20*log(mag(data)) |
The mag() function will convert the complex data to real values which is actually what is intended. Better still use:
| db(data) |
This is equivalent to 20*log(mag(data)).
Note that the graph system will always plot the magnitude of complex data. But, any expression presented for plotting will be evaluated as complex and only the final result is converted to real. So 20*log(data) will be plotted as mag(20*log(data)). This is not the same as 20*log(mag(data)) when data is complex.
Returns the magnitude of the argument. This function is identical to the abs() function.
Returns index of the array element in argument 1 with the largest magnitude.
| Arg1 | Vector | ||||
| Arg2 | Minimum value. Default $-\infty$ | ||||
| Arg3 |
Options array. Possible values are:
|
Returns an array of values holding every maximum point in the supplied vector whose value is above argument 2. The value returned - if noInterp is not specified - is obtained by fitting a parabola to the maximum and each point either side then calculating the x,y location of the point with zero slope. If noInterp is specified, the peak values are those found in argument 1 without any interpolation. The vector returned by this function has an attached reference which contains the x values of the maximum points. If xSort is not specified, the vector is arranged in order of descending y values i.e. largest y value first, smallest last. Otherwise, they are organised in ascending x-values.
| Arg1 | Vector |
| Arg2 | Start x value |
| Arg3 | End x value |
Returns the largest value found in the vector in the interval defined by start x value and end x value. If the vector is complex the operation will be performed on the magnitude of the vector.
Returns the average of all values in supplied argument. If the argument is complex the result will also be complex.
| Arg1 | Vector |
| Arg2 | Start x value. Default: start of vector |
| Arg3 | End x value. Default: end of vector |
Returns the integral of the supplied vector between the ranges specified by arguments 2 and 3 divided by the span (= arg 3 -arg 2). If the values supplied for argument 2 and/or 3 do not lie on sample points, second order interpolation will be used to estimate y values at those points.
Returns index of the array element in argument 1 with the smallest magnitude.
| Arg1 | Vector | ||||
| Arg2 | Maximum value. Default $+\infty$ | ||||
| Arg3 |
Options array. Possible values are:
|
Returns array of values holding every minimum point in the supplied vector whose value is below argument 2. The value returned - if noInterp is not specified - is obtained by fitting a parabola to the minimum and each point either side then calculating the x,y location of the point with zero slope. If noInterp is specified, the values are those found in argument 1 without any interpolation. The vector returned by this function has an attached reference which contains the x values of the minimum points. If xSort is not specified, the vector is arranged in order of ascending y values i.e. smallest y value first, largest last. Otherwise, they are organised in ascending x values.
| Arg1 | Vector |
| Arg2 | Start x value |
Returns the smallest value found in the vector in the interval defined by start x value and end x value. If the vector is complex the operation will be performed on the magnitude of the vector.
Returns the input vector scaled such that the magnitude of its largest value is unity. If the argument is complex then so will be the return value.
Returns the phase of the argument. ph() is identical to phase() and return the phase in degrees.
The ph() and phase() functions produces a continuous output i.e. it does wrap from 180 degrees to -180 degrees.
Identical to the ph() and phase() functions except that the result is in radians.
| Arg1 | Vector |
| Arg2 | Start index. Default: 0 |
| Arg3 | End index. Default: vector length -1 |
Returns a vector which is a range of the input vector in argument 1. The range extends from the indexes specified by arguments 2 and 3. If argument 3 is not supplied the range extends to the end of the input vector. If neither arguments 2 or 3 are supplied, the input vector is returned unmodified.
Returns the real part of the complex argument.
Returns the reference or x-values of the argument.
Returns a vector of the accumulative RMS value of the input. Unlike RMS1() this function returns a vector which can be plotted.
| Arg1 | Vector |
| Arg2 | Start x value. Default: start of vector |
| Arg3 | End x value. Default: end of vector |
Returns the root mean square value of the supplied vector between the ranges specified by arguments 2 and 3. If the values supplied for argument 2 and/or 3 do not lie on sample points, second order interpolation will be used to estimate y values at those points.
Returns a vector with each element a random value between 0 and the absolute value of the argument's corresponding element.
| Arg1 | Vector |
| Arg2 | Start x value. Default: start of vector |
| Arg3 | End x value. Default: end of vector |
Similar to RMS1 function but returns the root of the sum without performing an average.
Returns 1 if argument is greater than 0 otherwise returns 0.
Return sine of argument in radians. Use sin_deg if the argument is in degrees.
Returns the square root of the argument. If the argument is real and negative, an error will result. If however the argument is complex a complex result will be returned.
Identical to the RootSumOfSquares() function.
Return tan of argument in radians. Use tan_deg if the argument is in degrees.
| Arg1 | Data |
| Arg2 | Start x Value |
| Arg3 | End x value |
Returns a portion of the input vector with defined start and end points. Interpolation will be used to create the first and last points of the result if the start and end values do not coincide with actual points in the input vector.
Arguments 2 and 3 define the beginning and end of the vector.
Suppose we have a vector called VOUT which was the result of a simulation running from 0 to 1mS. We want to perform some analysis on a portion of it from $250\mu S$ to $750\mu S$. The following call to Truncate would do this:
| Truncate(VOUT, 250u, 750u) |
If VOUT did not actually have points at $250\mu S$ and $750\mu S$ then the function would create them by interpolation. Note that the function will not extrapolate points before the start or after the end of the input vector.
Returns a vector consisting of all 1's. Argument specifies length of vector.
Returns a vector with length specified by the argument. The value in each element of the vector equals its index.
| Arg1 | Input vector |
| Arg2 | Y value |
| Arg3 | Interpolation order (1 or 2) |
| Arg4 | Direction of slope. 0 = any, 1 = +ve, -1 = -ve |
Returns an array of values specifying the horizontal location(s) where the specified vector (argument 1) crosses the given y value (argument 2) in the direction specified by argument 4. If the vector never crosses the given value, an empty result is returned. The sampled input vector is interpolated to produce the final result. Interpolation order is specified by argument 3.
Returns a vector with y-values of argument 1and x-values of argument 2. This function provides a means of creating X-Y plots using the .GRAPH control. See Simulator Reference Manual/Command Reference/.GRAPH for details.
| Arg1 | Input vector |
| Arg2 | Y value |
| Arg3 | Interpolation order |
Returns an array of values (usually a single value) specifying the vertical value of the specified vector (argument 1) at the given x value (argument 2). If the given x-value is out of range an empty result is returned. The sampled input vector is interpolated to produce the final result. Interpolation order is specified by argument 3.
|