Maths Scripting

While Evolution scripting varies depending on context, there are some common rules that apply to all scripts.

Reading and writing attributes

Lets look at the following script:

new_attribute = 10

If you run the script above, an attribute called new_attribute will be created per block or solid in the model you are referring to, and the attribute will be set to the integer (10).

Similarly, you can create a string attribute as follows:

new_attribute = "10"

You can also create attributes by reading existing data using the block and solid keywords, as follows:

new_attribute = block.block_tonnes

In the above 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. This 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 apply a similar script for solid models.

If 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 follows:

new_attribute = define(block.block_tonnes)

This means that new_attribute only exists inside your script and it will not be added to the block model. The same concept applies to solid models when using the solid keyword.

Numerical operators

Operators are symbols used to define the operations performed within an expression. In report formulas, these operators are grouped into distinct categories, as outlined in the table below.

expression1 + expression2

expression1 - expression2

expression1 * expression2

expression1 / expression2

expression1 & expression2

expression1 | expression2

expression1 = expression2

expression1 <> expression2

expression1 < expression2

expression1 > expression2

expression1 <= expression2

expression1 => expression2

myfilter = define(block.CenX > 1)

mycolumn = sum(block.CenX)

result = expression1 ^ exponent

String manipulation

You can create strings in all Evolution scripts using concatenation. Concatenation is where you add strings together to create a new string, as shown in 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 that use the contains keyword can only be used for filters. If you need to use contains in a maths script, you need to use the keyword within an if function, as follows: 

new_attribute_string = define("10")
new_attribute_contains = if(new_attribute_string contains "1", 10, 4)
// new_attribute_contains = 10     

Various functions are also supported that let you check or modify strings. See String functions on this page for a complete listing.

Maths scripting functions

The following functions are available in Evolution maths scripts.

General functions

define()

Defines an attribute value for use within a script without adding it to the model.

Usage	define(value)
Parameters	value: A numerical or string value.
Returns	The value, which can be assigned to a local attribute variable.
Example	local_attribute = define(100) // local_attribute has the value 100 local_attribute = define(block.block_tonnes) // local_attribute has the value of block.block_tonnes

if()

Evaluates a condition and returns one of two values depending on whether the condition is true or false.

Usage	if(condition, true_value, false_value)
Parameters	condition: A logical expression that evaluates to true or false. true_value: The value to return if condition evaluates to true. false_value: The value to return if condition evaluates to false.
Returns	true_value if condition evaluates to true, false_value otherwise.
Example	original_value = define(10) new_value = if(original_value > 9, 9, 0) // new_value is now 9

String functions

The following string functions are available in Evolution maths scripts:

• endswith

• pack

• remove

• replace

• split

• startswith

• substring

• toupper

• tolower

• tonumber

endswith()

Checks whether a string ends with a given substring.

Usage	endswith(string, substring)
Parameters	string: The string to check. substring: The substring to check for at the end of the string.
Returns	True if string ends with substring, false otherwise.
Example	name = define("cumulative_grade") name_check = endswith(name, "grade") // name_check is now true

pack()

Returns a copy of a string with all spaces removed.

Usage	pack(string)
Parameters	string: The string to remove spaces from.
Returns	A copy of string with spaces removed.
Example	name = define("ore zone 1") packed_name = pack(name) // packed_name is now "orezone1"

remove()

Removes a substring defined by an index and a length from a string.

Usage	remove(string, i, length)
Parameters	string: The string to remove the substring from. i: The zero-based index in string at which the substring starts. length: The length of the substring to remove. Note:  If i or length are out of range, they will be rounded to the closest in-range value.
Returns	A new string with the specified substring removed.
Example	name = define("orebody") short_name = remove(name, 3, 4) // short_name is now "ore"

replace()

Replaces all occurrences of a substring in a string with another string.

Usage	replace(string, substring, replacement)
Parameters	string: The string where replacements will be made. substring: The substring to be replaced. replacement: The string to replace substring with.
Returns	A new string with all occurrences of substring replaced with replacement.
Example	name = define("drillhole") new_name = replace(name, "drill", "bore") // new_name is now "borehole"

split()

Splits a string on all instances of a delimiter and returns the nth substring from the result.

Usage	split(string, delimiter, index_of_substring_to_return)
Parameters	string: The string to split. delimiter: A character or string to split by (for example, _) . index_of_substring_to_return: The zero-based index of the substring to return (0 for the first substring, 1 for the second, etc.).
Returns	The nth substring after splitting, where n=index_of_substring_to_return. If index_of_substring_to_return is out of range, returns the first or last substring, whichever is closer.
Example	original_string = define("ore_waste") split_substring = split(original_string, "_", 1) // split_substring is now "waste"

startswith()

Checks whether a string starts with a given substring.

Usage	startswith(string, substring)
Parameters	string: The string to check. substring: The substring to look for at the start of string.
Returns	True if string starts with substring, otherwise false.
Example	name = define("rocktype") starts_with_rock = startswith(name, "rock") // starts_with_rock is now true

substring()

Returns a portion of a string defined by a starting position and a length.

Usage	substring(string, i, length)
Parameters	string: The string to check. i: The zero-based index where the substring begins. length: The length of the substring you want to return. Note:  If length is out of range, it is rounded to the closest in-range value.
Returns	A substring of the specified length starting at i.
Example	name = define("ore_waste") name_substring = substring(name,4,5) // name_substring is now "waste"

toupper()

Converts all characters in a string to uppercase.

Usage	toupper(string)
Parameters	string: The string to make uppercase.
Returns	An uppercase version of the string.
Example	name = define("rock") name_upper = toupper(name) // name_upper is now "ROCK"

tolower()

Converts all characters in a string to lowercase.

Usage	tolower(string)
Parameters	string: The string to make lowercase.
Returns	A lowercase version of the string.
Example	name = define("ROCK") name_lower = tolower(name) // name_lower is now "rock"

tonumber()

Converts a string into a number.

Usage	tonumber(string, fallback_value)
Parameters	string: The string to convert to a number. fallback_value: The value to return if the string cannot be converted.
Returns	The numerical value represented by string, or fallback_value if conversion fails.
Example	string_value = define("10") numerical_value = tonumber(string_value, 0.0) // numerical_value is now 10 string_value = define("rock") numerical_value = tonumber(string_value , 0.0) // numerical_value is now 0.0

Numerical functions

The following functions for operating on numerical values are available in Evolution maths scripts:

• rounddown

• roundup

• sqrt

• tostring

rounddown()

Rounds a number down to a specified number of decimal places.

Usage	rounddown(number, decimal_places)
Parameters	number: The number to be rounded. decimal_places: The number of decimal places to round down to.
Returns	The rounded number.
Example	original_value = define(10.45) rounded_value = rounddown(original_value, 1) // rounded_value is now 10.4

roundup()

Rounds a number up to a specified number of decimal places.

Usage	roundup(number, decimal_places)
Parameters	number: The number to be rounded. decimal_places: The number of decimal places to round up to.
Returns	The rounded number.
Example	original_value = define(10.45) rounded_value = roundup(original_value,1) // rounded_value is now 10.5

sqrt()

Returns the square root of a number.

Usage	sqrt(number)
Parameters	number: The number to take the square root of.
Returns	The square root of number.
Example	distance = sqrt(25) // distance is now 5

tostring()

Converts a numeric value into a string.

Usage	tostring(number)
Parameters	number: The numeric value to convert to a string.
Returns	The string representation of number.
Example	numerical_value = define(10) string_value = tostring(numerical_value) // string_value is now "10"

Mathematical functions

Evolution also provides the following maths functions when you type math. in a script editor:

See also:  Maths Scripts for Block Models, Maths Scripts for Solid Models, Maths scripts during dynamic solids import, Creating solid attributes using scripts for dynamic solids pits