User Tools

Site Tools


Tool On Objects Language

Tools-On-Objects Language, is an interactive language for manipulating structured data objects including multi-dimensioned arrays, sets and geometric objects. TOOL is the only 1) language needed throughout the whatIf? platform.

One Language to Rule Them All

TOOL is used throughout the whatIf? platform and is the only language the modeller will need to know.

In the process of building and using a model there are 4 places where code is required and typically there are at least 2 languages to accomplish these tasks:

  • Preparation and manipulation of historical data
  • Model implementation
  • Data input creation
  • Displaying data and report writing

In the whatif platform TOOL is used for all of those tasks, more specifically:

  • coding the model itself through a customized editor with features to simplify coding
  • importing/exporting and manipulating data as various types of files and formats: Import/Export channels
  • interact with the user to allow them to create data
  • display and analyze data by manipulating the data and displaying tables, graphs, and maps
  • interactively test code and check data through a TOOL console


TOOL inspired by other array languages such as:

One of the main concepts taken from these is that one object can inform another. This is used extensively in TOOL for the dimensions of variables. Each dimension of a variable is one of 3 types of objects: set, category, or sequence.


TOOL is fourth-generation programming language (abbreviated 4GL) specifically designed for handling large arrays of multi-dimensional data. This makes it well suited for model building.

Specialized algorithms for model building are built into TOOL for efficiency and simplicity and they are called tools. There are currently 137 tools in TOOL and this list is ever growing as a need arises. Here are a few common modelling constructs built into TOOL:

  • Stock flow in various forms for the evolving stocks over time
  • Population cohort model
  • Convolution
  • Life table
  • …and many more!

Why 4GL?

Here's an excerpt from

“In the evolution of computing, the 4GL followed the 3GL in an upward trend toward higher abstraction and statement power.

The natural-language, block-structured mode of the third-generation programming languages improved the process of software development. However, 3GL development methods can be slow and error-prone. It became clear that some applications could be developed more rapidly by adding a higher-level programming language and methodology which would generate the equivalent of very complicated 3GL instructions with fewer errors. In some senses, software engineering arose to handle 3GL development. 4GL and 5GL projects are more oriented toward problem solving and systems engineering.”

Multidimensional Support

TOOL handles multidimensional arrays (objects) in a way that makes the math as simple as working with single-value (i.e. scalar) variables. For example to multiply a population stock variable which is broken down by region(reg), gender(gen), time(t) and age(a) by a survival rate by only region time and age the math is simply:

survivors[reg,gen,t,a] = population[reg,gen,t,a] * survivalRate[reg,t,a]

TOOL automatically handles the mismatch of dimensions by using the same survival rate for each gender and produces a 4 dimensional output. All TOOL functions handle multidimensional objects.

Dimensional Analysis

Dimensional Analysis is a process which is run as a part of the model design process within Documentor. It is essentially “running” the model without the data, and it tests for proper coding syntax as well as shape consistency and coherency.

Every variable in a whatIf? model has a shape which is a definition of the attributes in terms object type (array, scalar, set), data type (real numbers, integers), the number of dimensions and the dimension name(s), its standard international unit of measure, its alternate unit of measure, and its entity. Information pertaining to shape is created during the design process in Documentor.

Every operation using and creating variables keeps track of shape to produce coherent and consistent data throughout the model. Every tool has the ability to check the shapes and operations for this consistency and this all done during Dimensional Analysis. With errors reported to the user.

Unit Conversions Handled

All the data stored in TOOL objects is stored in its primary SI units (International System of Units). The units the data is to be displayed, called the alternate unit of measure (altUom), in is set on the object to simplify viewing data. The relationship between any altUom and SI units are specified in a conversion table.

For example consider a petajoule and a tonne in SI units,

1e-15 petajoule = 1 m2kg/s2

0.001 tonne = 1 kg

are represented internally as:

altUom m kg s C rad sterad conversion
petajoule 2 1 -2 1e-15
tonne 1 0.001

Import/Export channels

TOOL is used to read and write data external to the model and it supports various formats and file types as described in the following article:

Data Format vs File Format

Occasionally, for complex source data files, a pre-processor script written in another language (e.g. AWK, Perl, R) may be used.
concepts/tool.txt · Last modified: 2010/11/12 15:52 by marcus.williams