# Unit Expressions

Unit expressions

Unit expressions can be used at various places in an AIMMS model, such as:

the

`BaseUnit`

attribute of a`Quantity`

declaration (defined in The Quantity Declaration),in a local unit override of a numerical (sub-)expression (discussed in Locally Overriding Units)

in a convention list of the

`PerUnit`

,`PerQuantity`

or`PerIdentifier`

attributes of a`Convention`

(see also Globally Overriding Units Through Conventions), oron the right hand side of an assignment to a unit parameter (see Unit-valued Parameters).

The syntax of a unit expression is straightforward, and given below.

Syntax

*unit-expression:*

Unit symbols and references

The simplest form of unit expression is just a unit symbol, as defined
in either the `BaseUnit`

or the `Conversion`

attribute of a
`Quantity`

declaration. A reference to either a (scalar or indexed)
unit parameter (see Unit-valued Parameters) or to the `.Unit`

suffix of any identifier with an associated unit (see
Associating Units with Model Identifiers), is a second form of unit expression.

Unit operators and functions

More complex unit expressions can be obtained by applying the binary
unit operators `*`

, `/`

and `^`

, with the usual left-to-right
evaluation order. The following rules apply:

the operand on the right of the

`*`

operator must be a unit expression, while the operand on the left can either be a unit expression or a numerical expression (expressing a numeric scale factor),both operands of the

`/`

operator must be unit expressions, andthe operand on the left of the

`^`

operator must be a unit expression, while the exponent operand must be an integer numerical expression.

In addition, AIMMS supports a number of unit functions, which can create new unit values or construct associated unit values from a given unit expression (see Unit-valued Functions).

Three types of unit expressions

However, AIMMS requires that any unit expressions uniquely falls into one of the three categories

unit constant,

simple unit expression, or

computed unit expression.

Unit constants

*Unit constants* are unit expressions which consist solely of unit
symbols, scalar constants and the three unit operators `*`

, `/`

and
`^`

. Unit constants can be used in

the

`BaseUnit`

attribute of a`Quantity`

,the lists associated with a

`Convention`

, andthe unit-valued function

`Unit`

.

In addition, unit constants can be

displayed and entered via the AIMMS graphical user interface,

assigned to unit parameters through data statements (see Format of Text Data Files), and

exchanged with external data sources via the

`READ`

and`WRITE`

statements (see The READ and WRITE Statements).

Simple unit expressions

*Simple unit expressions* are an extension of unit constants. They are
unit expressions which consist solely of unit symbols, unit references
without indexing, scalar constants and the three unit operators `*`

,
`/`

and `^`

. Simple unit expressions can be used in

local unit overrides, and

assignments to unit parameters.

Computed unit expressions

Computed unit expression can use the full range of unit expressions,
with the exception of unit constants. If you want to refer to unit
constants within the context of a computed unit expression, you must
embed it within a call to the function `Unit`

, discussed in the next
section. Computed unit expressions can be used

in assignments to unit parameters, and

as an argument of the functions

`ConvertUnit`

,`AtomicUnit`

and`EvaluateUnit`

(see Unit-valued Functions and Converting Unit Expressions to Numerical Expressions).

## Unit-valued Functions

Unit-valued functions

AIMMS supports the following unit-valued functions:

`Unit`

(*unit-constant*)`StringToUnit`

(*unit-string*)`AtomicUnit`

(*unit-expr*)`ConvertUnit`

(*unit-expr*,*convention*)

The function `Unit`

The function `Unit`

simply returns its argument, which must be a unit
constant. The function `Unit`

is available to allow the usage of unit
constants within computed unit expressions (as discussed in the previous
section).

The function `StringToUnit`

The function `StringToUnit`

converts a string, which represents a unit
expression, to the corresponding unit value. You can use this function,
for instance, after reading external string data that needs to be
converted to real unit values for further use in your model.

The function `AtomicUnit`

With the function `AtomicUnit`

you can retrieve the atomic unit
expression corresponding to the unit expression passed as the argument
to the function. Thus, the unit expression

```
AnIdentifier.Unit / AtomicUnit(AnIdentifier.Unit)
```

will result in a (unitless) unit value that exactly represents the scale
factor between the unit of an identifier and its associated atomic unit
expression. You can obtain the corresponding numerical value, to be used
in numerical expressions, by applying the function `EvaluateUnit`

discussed in the next section.

The function `ConvertUnit`

The function `ConvertUnit`

returns the unit value corresponding to the
unit expression of the first argument, but taking into consideration the
convention specified in the second argument. If the first argument
contains a reference to a `.Unit`

suffix, AIMMS will apply the full
range of conversions including those specified in the `PerIdentifier`

attribute of the convention.

Examples

The expression

```
ConvertUnit(AnIdentifier.Unit, ConventionUsed)
```

returns the associated unit of the identifier `AnIdentifier`

as if the
convention `ConventionUsed`

were active. A further example of the use
of the function `ConvertUnit`

is given in Unit-based Scaling of Mathematical Programs.

## Converting Unit Expressions to Numerical Expressions

Numeric value of a unit expression

Although numerical values and unit values are two very distinct data types in AIMMS, the distinction between the two in real life applications is not always as strict. For instance, in the previous section the computation of the ratio between a unit and its associated atomic unit expression returned a unit value, which represents nothing more than a (unitless) scale factor. In practice, however, it is the numeric scale factor value that is of interest, and can be used in numerical computations.

The function `EvaluateUnit`

Using the function `EvaluateUnit`

you can compute the numerical value
associated with a computed unit expression. Its syntax is:

`EvaluateUnit`

(*computed-unit-expression*)

The numeric function value precisely corresponds to one unit of the specified computed unit expression, measured in the evaluated unit of its argument.

Example

The following assignment to the scalar parameter `ScaleFactor`

computes the (unitless) scale factor between the unit of an identifier
and its associated atomic unit expression.

```
ScaleFactor := EvaluateUnit( AnIdentifier.Unit / AtomicUnit(AnIdentifier.Unit) );
```

Extension of local overrides

As you will see in the next section, the function `EvaluateUnit`

offers extension the local unit override capability. The argument of
`EvaluateUnit`

can be a computed unit expression (see
Unit Expressions), whereas local unit overrides can only accept
simple unit expressions.