Globally Overriding Units Through Conventions

Unit conventions

In addition to locally overriding the unit definition of an identifier in a particular statement, you can also globally override the default format for data exchange using READ and WRITE, DISPLAY and SOLVE statements by selecting an appropriate unit convention. A convention offers a global medium to specify alternative (scaled) units for multiple quantities, units, and identifiers. In addition, one can specify alternative representations for a calendar in a convention.

Effect of conventions

Once you have selected a convention, AIMMS will interpret all data transfer with an external component according to the units that are specified in the convention. When no convention has been selected for a particular external component, AIMMS will use the default convention, i.e. apply the unit as specified in the declaration of an identifier. For a compound quantity not present in a convention, AIMMS will apply the convention to all composing atomic units used in the compound quantity.

Convention attributes

Conventions must be declared before their use. The list of attributes of a Convention declaration are described in this table.

Attribute	Value-type	See also page
Text	string
Comment	comment string
PerIdentifier	convention-list/reference
PerQuantity	convention-list
PerUnit	convention-list
TimeslotFormat	timeslot-format-list	Working in Multiple Time Zones

Convention list

A convention list is a simple list associating single quantities, units and identifiers with a particular (scaled) unit expression. The specified unit expressions must be consistent with the base unit of the quantity, the specified unit, or the identifier unit, respectively.

Syntax

convention-list:

Customizable conventions

In addition to a fixed convention list, the PerIdentifier attribute also accepts a reference to a unit-valued parameter defined over the set AllIdentifiers or a subset thereof. In that case, the convention will dynamically construct a convention list based on the contents of the unit-valued parameter.

Example

The following declaration illustrates the use of a Convention to define the more common units in the Anglo-American unit system at the quantity level, the unit level and the identifier level.

Convention AngloAmericanUnits {
    PerIdentifier  : {
        GasolinePurchase : gallon,
        PersonalHeight   : feet
    }
    PerQuantity    : {
        Velocity         : mph,
        Temperature      : degF,
        Length           : mile
    }
    PerUnit        : {
        cm               : inch,
        m                : yard,
        km               : mile
    }
}

Customizable example

Assuming that IdentifierUnits is a unit-valued parameter defined over AllIdentifiers, the following Convention declaration illustrates a convention that can be customized at runtime by modifying the contents of the unit parameter IdentifierUnits.

Convention CustomizableConvention {
    PerIdentifier  : IdentifierUnits;
}

Application order

For a particular identifier, AIMMS will select a unit from a convention in the following order.

• If a unit has been specified for the identifier, AIMMS will use it.

• If the identifier can be associated with a specific quantity in the convention, AIMMS will use the unit specified for that quantity.

• In all other cases AIMMS will apply the convention to an atomic unit directly, or to all composing atomic units used in a compound unit.

Timeslot format list

In addition to globally overriding units, Conventions can also be used, through the TimeslotFormat attribute, to override the time slot format of calendars. You may need to specify alternative time slot formats, for instance, when you are reading data from an external database or file, in which all dates are not specified in the same time zone as the one your model assumes. The TimeslotFormat attribute of a Convention is discussed in full detail in Working in Multiple Time Zones.

The Convention attribute

You can declare more than one convention in your model. A Convention attribute can be specified for the following node types in the model tree, which all correspond to an external component:

• the main model (used for the end-user interface or as default for all other external components),

• a mathematical program,

• a file (also when used to refer to a DLL containing a library of external procedures and functions used by AIMMS), and

• a database table or procedure.

The value of the Convention attribute can be a specific convention declared in your model, or a string or element parameter referring to a particular unit convention.

Convention semantics

For data exchange with all aforementioned external components AIMMS will select a unit convention in the following order.

• If an external component has a nonempty Convention attribute, AIMMS will use that convention.

• For display in the user interface, or for data exchange with external components without a Convention attribute, AIMMS will use the convention specified for the main model (see also Model Declaration and Attributes), if present.

• If the main model and external components have no Convention attribute, AIMMS will use the default convention, i.e. use the unit as specified in the declaration of each identifier.

Example

The following declaration of a File identifier shows the use of the Convention attribute. All the output to the file ResultFile will be displayed in Anglo-American units.

File ResultFile {
    Name       : "Output\\result.dat";
    Convention : AngloAmericanUnits;
}