A Math Minion formula always evaluates to what I call a "minion value". This critter can be any of the types below.
A numeric value consists of one or more floating point numbers, with an associated conversion unit type such as length, time, temperature, dimensionless etc. The numbers are always represented as a matrix, with a scalar just being a 1 by 1 matrix, a column array having 1 column and multiple rows and a row array having 1 row and multiple columns.
Elements can be accessed using the array indexing operator [ ] (See formula indices).
Operations on numeric values also calculate the result's conversion unit type. For instance the formula:
450 km / 4 h
would return a velocity value.
A string values consists of one or more text values. Like numerics, these values are always in a matrix, with a single string just being a 1 by 1 matrix, a column array having 1 column and multiple rows and a row array having 1 row and multiple columns.
Each element in a string matrix can be string of any length and any number of lines.
A table value is the result returned by operations on a data table tool, but it also can be returned by parameters of other tools or can result from various function calls.
It consists of one or more columns (fields), each with its own name and conversion unit type.
Each row in the table can be thought of as similar to a record in a database.
Elements can be accessed using the indexing operator [ ]. Column names or arrays of names can also be used for the column index.
A tool reference is simply a value that points to another tool.
When the name of an expression tool is used as formula, it evaluates to the minion value calculated by the expression's formula. Similarly a matrix reference will be replaced by a numeric value and a data table reference with a table value.
However other tools don't have values intrinsically associated with their names and a formula consisting of just their name will become a tool reference.
For instance if a model has an ordinary differential equation solver calling integ and an expression x with a formula that is just:
integ
then a formulas:
integ.dy
and
x.dy
will both return the derivative values of the integ solver.
This can be useful when the expression with the tool reference is designated is an input expression as it allows formulas in the model access to the parameters of a tool that is referenced from the parent model.
Arrays of tool references can be created by using the tools parameter of of model or by using the index operation [] with a model. The tools parameter will return an array of all the tools in the model, while the index operator will return an array of tools with names matching the string contained in the operator. The string can contain * wild card characters which will match any number of arbitrary characters. For instance
model1["field*"]
would return all the tools in model1 whose names started with "field".
An index of "value" can be used with references to expression tool to get its value, Thus
model1["field*"]["value"]
and assuming all the "field" tools were scalar expressions, would return an array with all the values of those fields. Note you must be sure all the expression have the same unit type.
If the index string is prefixed with "type:" or "notes:" then the tool type ("Expression", "Model", etc.) or the tool's notes are searched rather than the tool name.
If you are familiar with regular expressions, note that the index value is converted to a regular expression with a prefix of "^" and a postfix of "$" and the "*" characters replaced with ".*". This means you are free to use other regular expression features in the search term. For instance:
myModel["x[\d]+"]
would return all the tools in myModel whose names consist of an "x" followed by one or more digits.
You can prefix the index string with type: or notes: to have the string that follows match the tool type name, e.g. Expression or the tool notes. Thus:
myModel["type:model"]
Would find all the model tools contained in myModel.
Tool arrays can be particularly useful in constructing reports with values from various models that represent things like forms.
Finally a tool reference can be made to any tool using the self parameter. For example a reference to a data table named dtable would look like:
dtable.self
but this a mainly historical holdover that is retained for backwards compatibility.
The jsonparse function creates a javascript object from a JSON string and encapsulates it in a Math Minion jsonvalue.
This value is just displayed as a JSON string, but its members can be referenced with standard dot notation and some special index formats to create Math Minion string and number values.
See Formulas.JsonValue model in the Getting Started session for details.
If there is not enough information to evaluate a formula, or if there is an error, then the value will be empty. All formulas that reference an empty value will also evaluate to empty.