Formulas and Scripts
Source file: evolution-scripting.htm
Evolution formulas and scripts are used to modify model attributes, make new attributes based on existing model attributes or present information in a report format.
Evolution formulas and scripts can be used in a number of places. These include:
-
Transform files that are used to import model data. For more information, click on the following links:
-
Maths Scripts that are used to modify model data.
-
Python Scripts allow you to apply scripts to the block and solid models, and to create fully customisable script reports. For more information, see Python Scripts for Block and Solid Models and Python Report Scripting.
-
Filters such as the dynamic filter for model visualisation and filters used when creating relational dependency sets in solids for example.
Common rules
While Evolution Scripting depends on the context applied, there are some common rules that apply to all scripts.
Reading and writing attributes
Lets looking at the following trivial script:
new_attribute = 10
If you run this script, an attribute called new_attribute will be created per block/solid in the model you are referring to, and it will be set to the integer, 10.
Similarly, you can create a string attribute:
new_attribute = "10"
You can also create attributes by reading existing data using the following keywords: block and solid. For example:
new_attribute = block.block_tonnes
In this example, we access an existing attribute called block_tonnes from the block model using the block. notation and assign it to a new attribute called new_attribute. That means that every block in the block model will have an attribute called new_attribute with a value equal to the attribute block_tonnes. You can do a similar thing in solid/reserve models.
Suppose you only want to create an attribute to refer to within your script for clarity purposes. You can wrap the definition inside a define statement as shown below.
new_attribute = define(block.block_tonnes)
This means that new_attribute only exists inside your script and won’t be added to the block model. The same concept applies to solid models when using the solid keyword.
Other keywords are available. You can read more about other keywords used by clicking here, however they can only be used in reporting scripts.
Numerical operators
Operators are symbols that can be used to specify which operations to perform in an expression.
Report formula operators fall into various categories. Click on each for additional information.
| Category | Operators |
|---|---|
| Arithmetic | + - * / |
| Logical | & | |
| Relational | = <> < > <= >= |
| Assignment | = |
| Power | ^ |
Arithmetic
Addition
The addition operator (+) computes the sum of its two operands.
expression1 + expression2
The addition operator will only work with numeric expressions.
Subtraction
The subtraction operator (-) will subtract the value of the second operand from the first.
expression1 - expression2
The subtraction operator will only work with numeric expressions.
Multiplication
The multiplication operator (*) computes the product of its two operands.
expression1 * expression2
The multiply operator will only work with numeric expressions.
Division
The division operator (/) divides its first operand by its second operand.
expression1 / expression2
The division operator will only work with numeric expressions.
Logical
And
The and operator (&) computes the logical AND of its operands. That is to say, the returned result is true if both its operands evaluate to true, otherwise false.
expression1 & expression2
The and operator will only work with boolean expressions.
Or
The or operator (|) computes the logical OR of its operands. That is to say, the returned result is false if both its operands evaluate to false, otherwise true.
expression1 | expression2
The or operator will only work with boolean expressions.
Relational
Equal
The equality operator (=) returns true if the values of each of its operands are equal, otherwise false.
expression1 = expression2
The equality operator should not be confused with the Assignment operator. The symbol itself is the same; the difference is the context in which it is used. For example:
filter = define(block.Stage = "one")
The first = symbol is an assignment operator. The second = symbol is an equality operator. I.e.: "Stage is equal to one".
Not Equal
The inequality operator (<>) returns false if both its operands are equal, otherwise false.
expression1 <> expression2
Less Than
The less-than operator (<) returns true if the first operand is less than the second, otherwise false.
expression1 < expression2
The less-than operator will only work with numeric expressions.
Greater Than
The greater-than operator (>) returns true if the first operand is greater than the second, otherwise false.
expression1 > expression2
The greater-than operator will only work with numeric expressions.
Less Than or Equal
The less-than-or-equal operator (<=) returns true if the first operand is less than OR equal to the second, otherwise false.
expression1 <= expression2
The less-than-or-equal operator will only work with numeric expressions.
Greater than or Equal
The greater-than-or-equal operator (>=) returns true if the first operand is greater than OR equal to the second, otherwise false.
expression1 >= expression2
The greater-that-or-equal operator will only work with numeric expressions.
Assignment
The assignment operator (=) takes the expression on its right and assigns it to the field on its left.
This can be used for both creating definitions and for specifying output columns.
Definition example
The addition operator (+) computes the sum of its two operands.
myfilter = define(block.CenX > 1)
In this example, an expression is being defined and assigned to a temporary field named myfilter.
Output Column Example
mycolumn = sum(block.CenX)
In this example, the value of the expression on the right is output as a column in the report.
Power
The power operator (^) raises a number to the power of another number.
result = expression1 ^ exponent
The power operator will only work with numeric expressions.
String manipulation
You can create strings in all Evolution scripts using concatenation. Concatenation is where you add strings together to create a new string. Refer to the example below.
new_attribute_concat = "str" + "str2" // new_attribute_concat = "strstr2"
You can check if a string attribute contains another string by using the keyword contains. The expression will return a Boolean value. Therefore, expressions which use the contains keyword can only be used for filters. If you need to use contains in a Maths Script, then you need to use the keyword within an if function. Refer to the example below.
new_attribute_string = define("10")
new_attribute_contains = if(new_attribute_string contains "1", 4, 10)
// new_attribute_contains = 10
Common functions
Here are a list of common functions used in Evolution Scripting:
if
if(expression, value_to_return_if_true, value to return if false)
Description
Evaluates the given expression.
Parameters
Accepts three parameters: a boolean expression, the value the function returns if the expression is True and the value the function returns if the expression is False.
Return Value
If the boolean expression is True, the function returns the second parameter.
If the boolean expression is False, the function returns the third parameter.
Example
new_attribute = define(10) new_attribute_if = if( new_attribute > 9, 9, 0) // new_attribute_if = 9
pack
pack(string)
Description
Removes all spaces in a string.
Parameters
Accepts one string parameter.
Return Value
Returns a string with all spaces removed.
Example
new_attribute = define("str str2")
new_attribute_pack = pack(new_attribute)
// new_attribute_pack = "strstr2"
remove
remove(string, i, len)
Description
Removes a substring of length len from string, starting from the index i.
Parameters
Accepts three parameters: a string, an index, i, and a length, len. If the index or length are out of range, they are rounded to the closest in-range values.
Return Value
Returns a substring.
Example
new_attribute = define("string")
new_attribute_remove = remove(new_attribute, 3, 3)
// new_attribute_remove = "str"
replace
replace(string, substring1, substring2)
Description
Replaces all instances of substring1 in string with substring2.
Parameters
Accepts three string parameters: string, substring1 and substring2.
Return Value
Returns a string with all instances of substring1 replaced with substring2.
Example
new_attribute = define("string")
new_attribute_replace = replace(new_attribute,"ing","ong")
// new_attribute_replace = "strong"
rounddown
Description
Rounds numbers down to the specified number of decimal places.
Parameters
Accepts two parameters: number, that is the number you want to round down and the decimal places you want to round the number down to.
Return Value
Returns a number to the decimal places specified. For example, 7.44 becomes 7.4 when rounding down to one decimal place.
Example
new_attribute = define(10.45) new_attribute_rd = rounddown(new_attribute,1) // new_attribute_rd = 10.4
roundup
roundup(number, decimalPlaces)
Description
Rounds numbers up to the specified number of decimal places.
Parameters
Accepts two parameters: number, that is the number you want to round up and the decimal places you want to round the number up to.
Return Value
Returns a number to the decimal places specified. For example, 7.44 becomes 7.5 when rounding up to one decimal place.
Example
new_attribute = define(10.45) new_attribute_ru = roundup(new_attribute,1) // new_attribute_ru = 10.5
split
split(string, delimiter, index)
Description
Splits a string on all instances of a delimiter, then returns the substring at the specified index.
Parameters
Accepts three parameters: a string, a delimiter such as "_" or a space for example and an index.
Return Value
Returns a substring that was created by splitting the string on a specified delimiter. If the index is out of range, it returns either the first or last substring (whichever is closer).
Example
new_attribute = define("str1_str2")
new_attribute_split = split(new_attribute,"_",0)
// new_attribute_split = "str1"
substring
substring(string,i,len)
Description
Returns a substring of length len from string, starting from the character at index i.
Parameters
Accepts three parameters: a string, index, i, the starting point of the substring you want to return and len, the length of the substring you want to return.
Return Value
Returns a substring of length len. If the length is out of range, it is rounded to the closest in-range value.
Example
new_attribute = define("string")
new_attribute_substring = substring(new_attribute,3,3)
// new_attribute_substring = "ing"
toupper
toupper(string)
Description
Converts all characters in a string to uppercase.
Parameters
Accepts on parameter: a string.
Return Value
Returns a string in uppercase.
Example
new_attribute = define("string")
new_attribute_upper = toupper(new_attribute)
// new_attribute_upper = "STRING"
tolower
tolower(string)
Description
Converts all characters in a string to lowercase.
Parameters
Accepts one parameter: a string.
Return Value
Returns a string in lowercase.
Example
new_attribute = define("STRING")
new_attribute_lower = tolower(new_attribute)
// new_attribute_lower = "string"
tonumber
tonumber(string, double)
Description
Casts the given string to a number.
Parameters
Accepts two parameters: a string and a double.
Return Value
Returns a number, either the converted string or if this fails, the default double value that you provide.
Example
new_attribute = define("10")
new_attribute_number = tonumber(new_attribute, 10.0)
// new_attribute_number = 10
tostring
tostring(number)
Description
Converts the given number to a string.
Parameters
Accepts one parameter: a number.
Return Value
Returns a string.
Example
new_attribute = define(10) new_attribute_string = tostring(new_attribute) // new_attribute_string = "10"
