Code covered by the BSD License

### Highlights fromphysunits module from FORTRAN

from physunits module from FORTRAN by Naor Movshovitz
A toolbox that handles dimensioned variables

phhelp.html
Physunits Toolbox Documentation

# Physunits Toolbox Documentation

## Contents

The Physunits toolbox is an attempt to confer dimensional ‘awareness’ to the MATLAB environment. The motivation for this, as well as a suggested way to go about it, are explained in Automated computation and consistency checking of physical dimensions and units in scientific programs, Petty, G.W., Software - Practice and Experience, (Volume 31, Issue 11, 19 June 2001)

The author of the same has also made available for download a FORTRAN 90 module that implements this idea in the FORTRAN language. The module and paper can be downloaded from http://rain.aos.wisc.edu/~gpetty/physunits.html .

The Physunits toolbox is based on the above module, and expands it, while trying to adhere consistently to MATLAB standards and practices.

## How it works

The PHYSUNITS toolbox works by defining the PREAL class, with a PREAL data type and overloaded functions to support it. An object of type PREAL represents a physical quantity. It has two fields:

• value - The numerical value, which must be a numerical type with zero imaginary part.

• units - A vector of 7 numbers, representing the physical dimensions associated with value.

The format for the units vector is [length, mass, time, temperature, electric current, amount of matter, luminous intensity], but this format is usually transparent to the user, who defines her variables via an interface structure.

The overloaded functions and operators are then responsible for enforcing consistency in all operations involving PREAL variables. In particular:

• Addition of two variables is only possible if they have the same dimensions.

• Exponents must be dimensionless.

• Transcendental functions accept dimensionless arguments only.

• Binary logical operations can only be performed on variables having the same dimensions.

## Using the PREAL class

The PREAL class constructor accepts two arguments: a scalar real number, and a vector of 7 real numbers; and creates a PREAL object using these arguments for the value and units fields. This is a cumbersome and error prone method but, fortunately, the user will rarely need to use it directly. Instead she calls the function setUnits, which returns an interface structure that greatly facilitates the definition and use of dimensioned variables.

The interface structure contains predefined variables of type PREAL, representing the basic SI units as well as many other units, derived units, constants of nature, parameters, etc. Get this structure by calling the setUnits function. Once this interface structure is present in your workspace, you can the use the predefined variables. Define new PREAL variables by multiplying a predefined PREAL by a DOUBLE.

Tip: In Matlab version 7 (R14) or higher use the auto completion feature to find the names of predefined variables. If you have the output of the setUnits function in the variable y, type y in the command line followed by a period (.), then hit TAB to get a list of all variables contained in y. Type the first characters in a variable name and hit TAB again to narrow down the search.

## Examples

In the command window, get the interface structure by calling setUnits:

`si=setUnits;`

Create PREAL variables by multiplying double literals with the predefined unit variables:

```x=2*si.meter

x =

2 m

dr=1e-3*si.m

dr =

0.001 m

F=12*si.newton

F =

12 m kg s^-2
```

Operations on PREAL types follow the rules of physical dimensions:

```x^2

ans =

4 m^2

x+dr

ans =

2.001 m

sin(dr/x)
ans =

5.0000e-004

F*dr

ans =

0.012 m^2 kg s^-2
```

You can use the double function to convert a preal variable to a double. (This function simply discards the units field of the variable.)

```fprintf('Work done is %g joules.\n',double(F*dr))
Work done is 0.012 joules.```

Attempting an illegal operation results in an error:

```x+F
Error using ==> preal.plus
Attempt to add dimensionally inconsistent preals```

Notice that, as a bonus, the physunits toolbox can be used as a unit converter.

```fprintf('One joule equals %g ergs.\n',double(si.joule/si.erg))
fprintf('One dyne equals %g Newtons.\n',double(si.dyne/si.newton))
One joule equals 1e+007 ergs.
One dyne equals 1e-005 Newtons.```

## Sample program

A short sample program that demonstrates the PREAL class can be found in ...\physunits\iceball.m.

## Extending the Physunits toolbox

Anyone who will use the Physunits toolbox will undoubtedly discover that new capabilities need to be added. More than likely, these will include more functions that need to be overloaded for the PREAL class. If you get an error message from MATLAB complaining that function so-and-so is not defined for class PREAL, then you should simply define it for the PREAL class by putting an m-file with the same name in the @preal directory. For example, the function sin is defined for the PREAL class. Take a look in the file sin.m that resides in the @preal directory to see how it is defined. With this function as a reference it should not be difficult to define the asin function also for the PREAL class should you find it necessary.

Another improvement you are likely to need is the addition of more predefined variables used often in your work. This may be done by editing the setUnits function, and adding the required definitions at the end of the file.

## Disabling the Physunits toolbox

Using physical units in calculations is helpful and natural for scientists and engineers, but the need to use a user-defined type instead of the standard DOUBLE class comes with a penalty on performance. Long calculations involving PREAL variables may become too slow. A way to ‘switch off’ the dimensional awareness of the code is therefore desirable. Converting all PREAL variables into doubles with the double function is not practical. Instead, use the physunits function with the 'off' flag at the beginning of your code.

```physunits off
PHYSUNITS disabled.```

This causes all subsequent variables defined as PREALs in the code to be treated as regular double variables. The rest of the code should run exactly as it would were it written without any use of PREALs.

The recommended practice is therefore to use PREAL variables with physical dimensions throughout the code, enjoying the benefits of automatic consistency checks, dimensional tracking, and dimensional display, during development and debugging. When the code is ready for the ‘operational’ run, a one-line command at the beginning will restore performance and efficiency to optimal.