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), or

• on 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, and

• the 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, and

• the 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.