MastHEad

 

Kornucopia-Compatible Data Types

 

One of the ways Kornucopia makes MATLAB syntax easier is to allow use of Kornucopia-compatible data types in many expressions intended for input arguments of data type k_units. To explain how this works and benefits you, we first define what makes a Kornucopia-compatible data type.

Simply put, a Kornucopia-compatible data type is any data type (or entity), A, that can be successfully converted to a k_units data type of the class k_units (denoted as B, below) via

    B = k_units(A).

The Kornucopia function k_units, in the expression above, is also called the constructor function for the class k_units. Data types (or entities) that yield an error for this function evaluation are not Kornucopia-compatible data types. 

Kornucopia enhances MATLAB syntax flexibility because it allows users to input entities of type k_units and/or Kornucopia-compatible data types into all Kornucopia functions and many Kornucopia-overloaded MATLAB operators and functions. All of these Kornucopia-related functions and operators are designed with the following logic:

  1. Each input argument that technically should be of a k_units data type is checked for its type.

  2. If the input is of type k_units, it is passed into the function or operator "as is".

  3. If the input is not of type k_units, then Kornucopia internally temporarily attempts to convert the input argument to a k_units data type via
    B = k_units(A), where A denotes the given input argument.  Note that this is an internal temporary conversion, meaning Kornucopia does not actually change the input's actual data type in the workspace in which the input exists.

The MATLAB data types that are Kornucopia-compatible are described below (A is the assumed name of the input entity):

tmp = seconds(tmp);

tmp = timetable2table(tmp).  This action results in a column with the name Timestamp being prepended to the variable tmp which is now a table data type.

Below we demonstrate a few typical usage cases. The yellow highlighted region denotes the specific location of its use in the example.

Example 1
Consider the case of integrating acceleration, a, with respect to time, t, where each variable is a vector of data type k_units. We need to include an initial velocity of Vo = -20*m/s in the integration. We use the k_integrate function to directly and easily integrate the data, including the initial condition Vo.  The integration function expects input arguments of type k_units or Kornucopia-compatible data types.

Below we show two "explicit" ways to perform the integration calculation.

Method A
Vo = k_units(-20, 'm/s')
V = k_integrate(t, a, Vo)

Method B
k_unitsVariables('m, s')
Vo = -20*m/s
V = k_integrate(t, a, Vo)

Method A uses the function k_units to explicitly create the variable Vo, which is now of a k_units data type. Method B uses the function k_unitsVariables to easily create two variables in the MATLAB workspace, m and s. These variables represent 1 meter and 1 second, respectively, and both are of data type k_units. We then use natural math notation to define Vo , which becomes of type k_units because doing math with any entity of data type k_units results in a quantity of data type k_units.

Below is a syntax that takes advantage of entering the initial velocity as a char-string (a Kornucopia-compatible data type).

Method C
V = k_integrate(t, a, '-20*m/s')

In the Method C syntax, the function k_integrate internally converts, as described previously, the string '-20*m/s' to an argument of type k_units during its processing.

For completeness, it is noted that either or both the variables t and a could have been MATLAB tables (or some other Kornucopia-compatible data type) instead of k_units typed variables. Just like with the initial velocity argument, the k_integrate function would have internally temporarily converted these other arguments to k_units data type while doing its evaluation. Moreover, had the integration been with a quantity that was dimensionless or had no units, then the input arguments could have also been a numeric array of data (since such an array has no units).

This next example demonstrates a few math operations, including some using Kornucopia-compatible data types.

Example 2
Following from example 1 above, consider that the variable a is a k_units typed column vector of acceleration and has appropriate units associated with it. The variable a represents the acceleration of a body moving in space over time. If the body has a mass, say M = 5*kg, then we can compute the inertial force via F = M*a.

Three different explicit approaches to compute the force are:

Method A
M = k_units(5, 'kg')
F = M*a

Method B
k_unitsVariables('kg')
F = (5*kg)*a

Method C
k_unitsVariables('kg')
M = 5*kg
F = M*a

Here is an approach that uses a Kornucopia-compatible syntax  of a string in the math expression (highlighted in yellow)

Method D
F = '5*kg'*a 

In the Method D approach, MATLAB's times operator, *, sees two arguments presented to it, the string '5*kg' and the variable a which holds a k_units data type. Since Kornucopia has overloaded this MATLAB times operator, MATLAB passes the calculation to Kornucopia because at least one argument of the operator was of data type k_units. This allows Kornucopia to then recognize and convert the string input to a k_units typed argument and complete the multiplication operation. This type of behavior works with + and over 80 other MATLAB operators and functions (see Overloaded MATLAB Functions ).

Thus, this will NOT work: F = '5*kg'*'8*m/s^2'.   There is no k_units data types in the expression.