Python Scripts for Block and Solid Models

Source file: python-scripts-for-block-and-solid-models.htm

Evolution allows you to create Python scripts for both block and solids models. Python scripts work similarly to regular maths scripts, however, they offer you a greater range of functions, such as loops and if conditions. Python also contains the get and set functions, which allow you to specify and set attributes in your model. After writing the desired script, you can prompt Evolution to run the script over each block in the model. You can also create customised report scripts in Python. See Python Report Scripting for more information.

Note:  The required Python version is built-in to the Evolution package.

To create a Python script, right-click on the desired block or solid model in the project explorer and select Add Python Maths Script from the context menu.

Evolution will add a Python script to a folder named Math Scripts, located within the model folder.

Tip:  You can rename the script. Simply right-click on the Python file, select Rename, and then enter the new name in the name field.

Double-click on the script file in the project explorer. Evolution will open the Python script in your workspace.

Retrieving and setting column data

You can retrieve and set the column data by using the following Python functions:

Function Origin Blocks Origin Solids
get block.get("attributeName")
Equivalently: block.get(Attribute.attributeName))
solid.get("attributeName")
(Equivalently: solid.get(Attribute.attributeName))
set block.set("attributeName", value)
(Equivalently: block.set(Attribute.attributeName, value))
solid.set("attributeName", value)
(Equivalently: solid.set(Attribute.attributeName, value))
Important
If an existing model attribute has the same name as a Python keyword, you must append an underscore after that attribute name in the Python script. For example, an attribute called as must become as_ in the script, as follows: solid.set(Attribute.as_, 5).
Note that new attributes added to a model using Python maths cannot have the same name as reserved keywords.
In Python, appending an underscore to a variable name is a common convention to avoid conflicts with reserved keywords.
Therefore, the resulting maths script behaviour is as follows:
  • If there is an existing as attribute, you must reference it in your Python maths script as as_, but the model attribute name will remain as.

  • If you add a new attribute as_, you must reference it in your Python maths script as as_, and the newly added model attribute will be named as_.

The keywords are case-sensitive. The reserved keywords for the Python 3.11.5 version that Evolution is using are as follows:
FalseNoneTrueandasassertasync
awaitbreakclasscontinuedefdelelif
elseexceptfinallyforfromglobalif
importinislambdanonlocalnotor
passraisereturntrywhilewithyield

Note:  You can specify attributes by using either quotation marks ("Region") or by using the attribute prefix (Attribute.Region).

Note:  Common numerical operators and functions apply to Python scripting (see Formulas and Scripts), however, the syntax differs from regular maths scripts.

The following image displays an example Python script, where we have used a get function to get the attribute waste from the model. We multiply the waste column values by four and assign the result to the variable waste_var. We then set a new attribute, new_waste, to the values of the variable waste_var, using the set function.

The following image displays an example Python script that sets the Region column value under the following conditions:

  • If the RockType value of a solid is 1, the Region column values are set to 1.

  • If the RockType value of a solid is not 1, Evolution sets the Region column to the default value.

To view and change the default values, see Settings.

Applying a script

Once you finish writing your script, you can apply it to the project by selecting Run Script.

You can check the changes using pivot reports (see Pivot Reporting for more information) or the Properties tab in the Viewer tab window. The image below shows how the script you apply can be reflected in the Properties tab.