Units in LTPDA


The handling of physical units is one of the key features of LTPDA. The following sections show how to deal with them.

Supported units

LTPDA supports the SI units and many others. A unit object allows to handle the unit string and the exponent of the prefix. Here is an example:

>> unit('aF / nN')
------ unit/1 -------
strs: { 'F' 'N' }  [1x2]
exps: [1 -1]
vals: [-18 -9]
---------------------
The list of supported units is accessible by typing:
>> unit.supportedUnits
The list of supported prefixes is accessible by typing:
>> unit.supportedPrefixes

User-defined units

Units can be defined by the user. For that, the LTPDA Preferences interface can be used.

Setting units

Physical units for objects can be set when building them, via the an entry in parameter list:

>> a1 = ao([1:10], [2:2:20], plist('xunits', 'K', 'yunits', 'Pa'))
----------- ao 01: a1 -----------
 
       name: ''
       data: (1,2) (2,4) (3,6) (4,8) (5,10) ...
             -------- xydata [x, y] --------
              
                  x:  [1 10], double
                  y:  [1 10], double
                 dx:  [0 0], double
                 dy:  [0 0], double
             xunits:  [K]
             yunits:  [Pa]
             -------------------------------
              
       hist: ao / ao / 11c33bf1421898d27b94853f646e22673ebc750d
description: 
       UUID: 5ba41239-aa65-4c5b-9146-105fc5f4b4e6
---------------------------------
>> m = miir(plist('type', 'lowpass', 'fs', 10, 'fc', 0.1, 'iunits', 'N', 'ounits', 'm'))
------ miir/1 -------
          b: [1 -0.9390625058174924]
     histin: 0
      ntaps: 2
         fs: 10
     infile: 
          a: [0.030468747091253801 0.030468747091253801]
    histout: 0
     iunits: [N]
     ounits: [m]
       hist: miir.hist 
   procinfo: []
   plotinfo: []
       name: lowpass
description: 
       UUID: 4e15bfea-bae8-496f-be51-96dacfd82b7f
---------------------
Units can also be set via the setYunits and setXunits methods:
>> a1.setYunits('N / m^2')
----------- ao 01: ans -----------
 
       name: ''
       data: (1,2) (2,4) (3,6) (4,8) (5,10) ...
             -------- xydata [x, y] --------
              
                  x:  [1 10], double
                  y:  [1 10], double
                 dx:  [0 0], double
                 dy:  [0 0], double
             xunits:  [K]
             yunits:  [N m^(-2)]
             -------------------------------
              
       hist: ao / setYunits / 11c33bf1421898d27b94853f646e22673ebc750d
description: 
       UUID: 24b96137-5427-4565-9359-3804b45948ef
----------------------------------
Similarly, setIunits and setOunits exist for filter objects. More in following sections.

Unit propagation in methods

The LTPDA methods implement unit checking and propagation.

>> V = ao(1, plist('yunits', 'V'));
>> N = ao(10, plist('yunits', 'N'));
>> d = V/N
----------- ao 01: (V / N) -----------
 
       name: (V / N)
       data: 0.1
             -------- cdata [vals] ------------
                  y:  [1x1], double
                 dy:  [0x0], double
             yunits:  [V N^(-1)]
             ----------------------------------
              
       hist: ao / mrdivide / 11c33bf1421898d27b94853f646e22673ebc750d
description: 
       UUID: 41c9e535-a153-417e-9acc-76232d26d0b6
--------------------------------------
>> a1 = ao(plist('waveform', 'noise', 'sigma', 1, 'fs', 10, 'nsecs', 10000, 'yunits', 'm s^-2'));
>> s1 = sqrt(psd(a1))
----------- ao 01: sqrt(PSD(noise)) -----------
 
       name: sqrt(PSD(noise))
       data: (0,0.0742969798142685) (0.0001,0.188581537118303) (0.0002,0.0973085901222778) (0.0003,0.0364681549203924) (0.0004,0.183740667882419) ...
             -------- fsdata [x, y] --------
              
                  x:  [1 50001], double
                  y:  [1 50001], double
                 dx:  [0 0], double
                 dy:  [0 0], double
             xunits:  [Hz]
             yunits:  [m s^(-2) Hz^(-1/2)]
               enbw:  0.000200435
                 fs:  10
                 t0:  1970-01-01 00:00:00.000 UTC
               navs:  1
             -------------------------------
              
       hist: ao / sqrt / 11c33bf1421898d27b94853f646e22673ebc750d
description: 
       UUID: 9a90bea2-5c4e-4f0f-a62b-7224ee0fe332
-----------------------------------------------

Units checking means it is not possible to add apples to bananas:

>> m1 = ao(plist('waveform', 'noise', 'sigma', 1, 'fs', 10, 'nsecs', 10000, 'yunits', 'nT'));
>> d1 = a1 + m1
Error using ao/elementOp>isDataCompatible (line 348)
### Y units should be equivalent for the plus operator [m s^(-2)] <-> [nT]
Error in ao/elementOp>operateData (line 310)
  if isDataCompatible(a1, a2, op)
Error in ao/elementOp/operateSingleObject (line 270)
    res.data = operateData(a1, a2, op, axis);
Error in ao/elementOp (line 153)
      operateSingleObject(res, a1, [], a2, []);
Error in ao/plus (line 38)
  res = ao.elementOp(callerIsMethod, @getInfo, @getDefaultPlist, op, opname, opsym, aosNames, varargin(:)); 

Units simplification

Physical units can be a bit involved after a few operations. LTPDA offers the possibility to simplify them, via the simplifyUnits method:

>> V = ao(1, plist('yunits', 'nV'));
>> N = ao(10, plist('yunits', 'V/N'));
>> r = V/N
----------- ao 01: (V / N) -----------
 
       name: (V / N)
       data: 0.1
             -------- cdata [vals] ------------
                  y:  [1x1], double
                 dy:  [0x0], double
             yunits:  [nV V^(-1) N]
             ----------------------------------
              
       hist: ao / mrdivide / 11c33bf1421898d27b94853f646e22673ebc750d
description: 
       UUID: ec071cb3-3663-4e00-8a7a-2176679847df
--------------------------------------

>> r1 = r.simplifyYunits
----------- ao 01: (V / N) -----------
 
       name: (V / N)
       data: 1e-10
             -------- cdata [vals] ------------
                  y:  [1x1], double
                 dy:  [0x0], double
             yunits:  [N]
             ----------------------------------
              
       hist: ao / simplifyYunits / 11c33bf1421898d27b94853f646e22673ebc750d
description: 
       UUID: b9a5d863-5ece-469a-bf80-664b21a15321
--------------------------------------
Please notice that also the prefixes are simplified, by scaling the values. It is possible to force the method not to scale the prefixes, or to specify a list of units to ignore:
>> r2 = r.simplifyYunits(plist('prefixes', false))
----------- ao 01: (V / N) -----------
 
       name: (V / N)
       data: 0.1
             -------- cdata [vals] ------------
                  y:  [1x1], double
                 dy:  [0x0], double
             yunits:  [nN]
             ----------------------------------
              
       hist: ao / simplifyYunits / 11c33bf1421898d27b94853f646e22673ebc750d
description: 
       UUID: 4dc04ef2-cdd0-44d4-a42f-0b70e609aa52
--------------------------------------

SI units

The toSI method is available to help expressing the units only in term of the fundamental SI units.



©LTP Team