Knowledge Base Article

Unit Programming Functions

vCalc units are implemented in objects known as Amounts.  Amounts have a value, an associate unit and a powerful set of functions.  Parameters are designated as Amounts (having units) in the Equation Editor Algorithm Tab in both the algorthm code and in the user input UI where you can designate units for the input parameters.

To create an input parameter, you have to define a parameter using the ".args" extension.  See the following example:

                      def h = args.h   //create an input paremeter named h
                      def w = args.w  //create an input paremeter named w

Once you've entered the two lines of code, vCalc's Equation Editor will pop-up two lines at the bottom of the algorthm with options associated with the input parameters (h and w in the example above).  In the Input Paremeter windon, you can select units for the paremeter.  You can select a specific class (e.g. length) and unit type (e.g. meters), or you can select "Any" from a class and the default will be used.  In any case, the user can toggle to different units in the class (i.e. to compatible units)

Now that you have paremeter that are amounts, you have a lot of functions you can employ.  These include the following:

  • .to()  converts your amount to a compatible unit.  For example, the two lines that follow convert h and w to centimeters and kilograms respectively.
    • def h ="cm").estimatedValue convert to cm then throw away units
    • def w ="kg").estimatedValue convert to kg then throw away units
  • ."unit"  does not convert to a unit, but directly turns a number into an Amount with the units designated.  For example, the next line makes parameter B an amount with the value of BSA and the units meters squared.
    • B = BSA."m^2"
  • .estimatedValue takes an amount and captures its value without units, and creates just a real number.  Sometimes this is very important, because there are many algorithms that violate unit operations.  For example fractional exponents are troublesome to Amounts.  A common medical formula for the Body Surface area uses such fractional exponents (BSA = 0.008883 * h0.663 * w0.444) where h and w are height in centimeters and weight in kilgrams respectively and yet the results are in square meters of skin.   Also, some complex algorthms with numerous conditional statements (if, switch, etc) are hard for the unit handling algorithm to keep track of the resulting units.    In such cases, we often convert to ( .to() ) a unit that we use as the base and then convert the Amount to a real number using .estimatedValue for the rest of the algorithm, and then rely on the programmer to cast the real back into the correct unit as in the example just above this.  The following line takes an input parameter "Vm", converts it to cubic meters, and then treats it like a real number in parameter X.
    • def h ="cm").estimatedValue  // Convert h to centimeters and then throw away the units.
    • def w ="kg").estimatedValue // Convert w to kilograms and then throw away the units.
    • def BSA = 0.008883 * h**(0.663 ) * w**(0.444)
    • return BSA
  • .getUnit() returns the units of the Amount.  For example:  return   this converts z to the units of h

The list of unit is as follows: