Kornucopia has been designed and coded so that variables and other entities of data type k_units will work naturally with many MATLAB functions and syntax. This means the following type of commands can be used:
k_unitsVariables( 'Hz,
in, s' ); |
In the above syntax example, the following were variables of data type k_units:
Hz, in, s, fApplied, yAmp, t, y, curve
In the commands shown above, the *, sin, pi, and concatenation braces, [ ], were standard MATLAB operators, functions, or a constant.
MATLAB is able to process the commands shown above because Kornucopia overloaded these MATLAB functions and operators so that they can recognize and properly execute when entities of data type k_units are supplied to them. The user does not need to do anything special, the overloading is all handled by the installation of Kornucopia software on your computer. Before we review the list of MATLAB functions overloaded by Kornucopia, it is instructive to provide some further explanation of overloading.
When any function is used in a command, MATLAB looks to see if it knows how to handle the data types that are supplied to the function through its arguments. If a data type is unknown to the function, then MATLAB looks to see if the unknown (to the function) data type has an overloaded definition of the function. If it does, then MATLAB passes all the input arguments to that data type's class for it's version of the function to be executed. In essence, what is occurring, is that only when a function does not know how to process a particular data type, then the function's operation is passed to the class of that data type. Otherwise the normal function's code is executed as expected.
Kornucopia has overloaded over 80 MATLAB functions and operators so that the user experiences an efficient and natural MATLAB feel to their work when using the k_units data type. Provided in the listings that follow are all the overloads provided by Kornucopia. It is noted with MATLAB's hundreds of functions, there will be cases where there is no Kornucopia overload for a given MATLAB function (or user function). These cases are discussed after the listing below (Click here for that specific section).
Kornucopia overloads over 80 MATLAB functions and operators. This means that for those functions and operators with overloads, you can supply to them entities of data type k_units and they will simply work, very much like they would if you supplied normal MATLAB double data type (or similar). You do NOT need to use the A.Data syntax with these functions and operators.
Arithmetic math operators and functions
+, -, *, /, \, ^, .*, ./, .\, .^
sqrt, sum, prod, diff, ceil, floor, round
Relational operators
>, >=, <, <=, ==, ~=
Trigonometry
sin, cos, tan, cot, sec, csc
asin, acos, atan, acot, asec, acsc
sinh, cosh, tanh, coth, sech, csch
asinh, acosh, atanh, acoth, asech, acsch
Logs and Exponents
log, log10, log2, exp
Complex numbers and angles
abs, real, imag, conj, angle, unwrap
Descriptive statistics
mean, median, std, min, max
Reshaping arrays
cat, horzcat, vertcat
flipud, fliplr, flipdim, flip
Is something
isempty, iscolumn, isrow, isvector, isscalar
isreal, isfinite, isinf, isnan
Matrix operations
transpose, ctranspose
cross, dot
colon
display, disp, num2str
Please note the following:
The display of k_units data types is controlled by two Kornucopia global options 'numericFormatTypeDisplayed' and 'numericPrecisionDisplayed' (see k_get and k_set functions for more details). These global display options were introduced in Kornucopia® ML™ version 3.0-11 to improve the display output of k_units data types.
Also starting in Kornucopia®
ML™ version 3.0-11, a new num2str
format was introduced for Kornucopia; the 'k'
and 'K' formats (click
here to learn more). These formats return the more compact
of a f-format (fixed-point notation)
and an e-format (scientific notation) processing of the input
while also keeping trailing zeros (which both f
and e formats also do). The capitalization
('k' or 'K'
) controls if the e-format is 'e'
and 'E' . The g-formats that MATLAB
offers behave differently than Kornucopia's k-formats; the
g-formats remove trailing zeros.
An example use of the k-format with num2str
would be:
txt = num2str(myVar, '%.5k');
If myVar was of type k_units, then MATLAB would pass the num2str evaluation to Kornucopia where it would properly interpret the k-format. Depending on the numeric value inside myVar, Kornucopia would return the more compact of an f-format (fixed-point notation) and an e-format (scientific notation) processing of the input (with precision set to 5).
It is noted that if myVar was NOT of type k_units, then MATLAB would solely process the command and throw and error as MATLAB does not directly understand k-format.
Syntax operators and functions
subsref, subsasgn - functions for overloading indexing with ( ), and { } parentheses, as well as using "." notation.
Most Kornucopia overloaded MATLAB functions behave similar to their native MATLAB function behavior. However, due to the column-oriented nature of the k_units data type, there are certain conditions where some overloaded functions will behave differently from the native MATLAB behavior. These cases are described here.
Overload of functions mean(A,dim), median(A,dim), min(A,B,dim), max(A,B,dim), and std(A,w,dim)
These function compute the given operations of A in a column-wise nature (even for when A is a 1xn row vector) unless the optional argument, dim, is supplied as the value 2, and then the given operation is computed row-wise.
It is noted that native MATLAB behavior would compute the given operation for when A is a 1xn row vector (and dim is not supplied), in a row-wise manner. As noted above, Kornucopia does not do this for when A is a 1xn row vector (and dim is not supplied). In this case, Kornucopia still process the result column-wise. Beyond this specific case, the behavior of the Kornucopia overload matches that of native MATLAB behavior for these functions.
For the functions min and max, the 2nd argument, B, can be [] or a variable. See the MATLAB documentation for more details.
For the function std, the second option argument, w, is a flag controlling the normalization used, where 0 uses the "n-1" form of standard deviation and 1 uses the "n" form of standard deviation. If the second argument is omitted or supplied as [], then 0 is assumed. This is consistent with native MATLAB behavior.
Since MATLAB has hundreds of functions, there will be cases where there is no Kornucopia overload for a given MATLAB function (or user function). If you need to use a function that has not been overloaded, simply supply just the numerical data from the k_units data type via A.Data where A is the name of your variable (this is shown in the code box below).
If a k_units data type is supplied to a MATLAB function that Kornucopia has NOT overloaded, then the user will likely see a MATLAB error of one of two likely forms:
An error stating something like
"Undefined
function 'XXX' for input arguments of type 'k_units'"
(where XXX is the MATLAB or user function that was being executed).
A MATLAB error dump that might have several levels in it which there may ultimately be an error statement like that above or some other Kornucopia error statement, typically referencing that a variable was indexed improperly or some other type of error.
In the first case, it definitely means that there is no Kornucopia overload for the MATLAB function in question. In the second case, it may mean this or it may mean that you simply have a syntax error. In the event that you believe the issue is lack of an overloaded function, a simple solution to the problem is to feed the MATLAB function just the primary data from the k_units variable by using A.Data syntax on the k_units variable (where A is assumed here to be your variable name). Doing this results in just a normal array of data (just numbers) being fed as the argument into the MATLAB function and likely a result of data type double being returned by the MATLAB function. Below is a simple demonstration where the variable myStuff is of data type k_units.
yFfilt = filter(b,a,y); % If y is k_units data type, this will cause error.
|
One note on the example above: If you are trying to perform DSP filtering of your data, look at the function k_filter, it is likely to do what you want more directly.