Rocky Tutorial

Static Angle of
Repose Test
Lesson 2 – Post-Processing with
Scripts

2024 R1 - © ANSYS, Inc. All rights reserved // 1

1.1. Lesson 2 (Part B): Post-Processing with Scripts

1.1.1. OBJECTIVES
The purpose of this tutorial is to calculate the Static Angle of Repose (SAOR) using two methods:
manually using Cross Plots and automatically using a Python script.

• We will continue from where we left off in Part A.

You will learn how to:

• Use a cross plot to measure the SAOR

• Open the PrePost Script panel

• Import and run a saved Python script

• Interpret the results from the executed script

• Modify the Python script

And you will use these features:

• Cross Plot window

• PrePost Script panel

• API:PrePost Manual

Important:

Even though this tutorial involves running only one SAOR test, other simulations must be
done in order to calibrate the particle model in full.

1.1.2. OPEN PROJECT

1. If you completed Part A of this tutorial, ensure that the Rocky project is open. (Part B will continue
from where Part A left off.)

2. If you did not complete Part A, do all of the following:

a. Download the dem_tut02_files.zip file.

b. Unzip dem_tut02_files.zip to your working directory.

2024 R1 - © ANSYS, Inc. All rights reserved // 2

 c. Open Rocky 2024 R1. (Look for Rocky 2024 R1 in the Program Menu or use the desktop
shortcut.)

Important:

To make use of the Rocky project file provided, you must have Rocky 2024 R1 or
later. If you have an earlier version of Rocky, please upgrade Rocky to the latest
version or complete Part A from scratch.

d. From the Rocky program, click the Open Project button, find the dem_tut02_files folder,
then from the tutorial_02_pre-processing folder, open the tutorial_02_pre-processing.rocky
file.

e. Process the simulation. (From the Simulation toolbar, click the Start button.)

1.1.3. POST-PROCESSING: MANUAL METHOD

Now that the project has completed processing, we can begin to analyze it. Let's start with the
manual method first.

In this method, the Static Repose Angles (green lines) will be calculated manually by following these
steps:

• Generation of a plot with the particle distribution along X and Y directions

• Measurement of the length and height using the chart scale

• Calculation of the angles using trigonometric relationships

2024 R1 - © ANSYS, Inc. All rights reserved // 3

1.1.4. CROSS PLOT
The Cross Plot is used to create a scatter plot, which allows you to compare two properties of the
Particles/Geometry one on the X-axis and another on the Y-axis for a given Output.

In this tutorial, we will use a Cross Plot to see the projection of the particles pile in the XY plane. In
order to do that, the Particle Y-Coordinate will be plotted against the Particle X-Coordinate.

To create the Cross Plot, do all of the following:

1. From the Window menu, click New Cross Plot, or use the shortcut Ctrl+R.

2. From the Data panel, select Particles and then from the Data Editors panel, select the Properties
tab.

3. Click and drag Particle Y-Coordinate over the plot window and then release.

4. From the Select Source Curves window that appears, select Particle X-Coordinate from the
Domain drop-down list, and then click OK.

2024 R1 - © ANSYS, Inc. All rights reserved // 4

Unlike the (Multi) Time Plot, which shows a single value per output for all the Particles, the Cross
Plot shows all the Particles' values, but for only a single Output.

You can choose what instant to analyze using the Time toolbar.

Select the Time at 4.6 s to measure the Static Repose Angles.

The result is shown below.

1.1.5. PLOT SETTINGS

Rocky plots can be edited by right-clicking anywhere on the plot grid.

Cross Plot

2024 R1 - © ANSYS, Inc. All rights reserved // 5

Multi Time Plot

• Export and Copy: Copy the plot or data; save the plot as a .png, .bmp or .jpg image file; or save
a .csv data file.

• Title Format: Display/hide the plot title, and edit it.

• Legend Format: Display/hide the curves legend, and edit it.

• Canvas Background: Change the plot area color and display/hide grid lines.

• Curve Colors: Select curves coloring method: one color for each curve (Unique), identical colors
for the same curves in the same or different entities (Particles/Geometries/Processes) (Property
Based), or identical colors for the same or different curves in the same entities (Entity Based).

• Axes Colors: Enable/disable the axis coloring according to the curve color.

• Axes Layout: Toggle between independent axes for each curve (By Property), or a single axis for
2024 R1 - © ANSYS, Inc. All rights reserved // 6
 the same units (By Quantity).

• Time Mark: Enable/disable the vertical dotted line synchronized with the selected instant in the
Time toolbar.

• Annotations: Add a custom text over the plot at any XY point.

• Settings: Open the Windows Editor panel for additional controls.

1.1.6. AXES SETTINGS

Now, let's modify and re-scale the plot:

1. Right-click the cross plot view and then select Settings. (Or in the top left corner of the plot, select
the Configure Window icon.)

2. In the Window Editors panel, select the Axes tab, and then under Axis, multi-select both proper-
ties.

3. Under Values, change the Limits option to User Defined.

4. Set the value for Min, Max and Step for the two separate axes as shown below.

2024 R1 - © ANSYS, Inc. All rights reserved // 7

1.1.7. MEASURING RESULTS – MANUAL METHOD

• SAOR (1): Δx= 0.220 m; Δy= 0.155 m

2024 R1 - © ANSYS, Inc. All rights reserved // 8

• SAOR (2): Δx= 0.160 m; Δy= 0.150 m

Note:

The values you end up with in your project may vary slightly from the ones shown in this
tutorial.

1.1.8. CALCULATIONS – MANUAL METHOD

Once the values are measured, simple calculations can be done outside of Rocky using a spreadsheet
or calculator:

• SAOR(1): Δx= 0.220 m; Δy= 0.155 m

– SAOR=atan(0.155/0.220) ~ 35.2°

• SAOR (2): Δx= 0.160 m; Δy= 0.150 m

– SAOR=atan(0.150/0.160) ~ 43.1°

Although these values were measured using the cross plot's axis scale, they can be measured using
the mouse. To do that, hold the Shift key and then click the plot to show the cursor's value.

1.1.9. POST-PROCESSING: AUTOMATIC METHOD

You can also post-process your results automatically by using a Python script.

Important:

The provided script was designed for cases with higher particle counts than what was
simplified for this tutorial. As a result, tutorial results may vary significantly.

In this method, the Static Angle of Repose (SAOR) will be calculated using the following steps:

• At a given output, a parallelepiped slice is divided into N vertical cells and placed at the pile center
(as shown).

• In each of these cells, the maximum particle height is collected.

• Then, the parallelepiped slice is rotated 10 degrees around the vertical axis (Y-direction), and the
maximum height of each cell is collected again. This step is repeated 36 times.

• Using the average of the collected maximum heights for each cell, a regression line is created and
the Static Angle of Repose is calculated.

2024 R1 - © ANSYS, Inc. All rights reserved // 9

1.1.10. PREPOST SCRIPT PANEL
In Rocky, you can automate frequent tasks in one of two ways:

• Within Rocky, you can record Scripts of the exact steps you take in the user interface.

• Outside of Rocky, you can write Scripts using the Python programming language that makes use
of the API:PrePost.

Although they are generated in different ways, both methods can be played (executed) in the PrePost
Script panel.

For this tutorial, we will focus on using a previously created script.

1. To start, show the PrePost Script panel by selecting it from the Tools menu.

• (1) Scripts shared across projects: Lists the scripts that can be used for any Rocky project.

• (2) Project scripts: Lists the scripts that can be used for this project only.

• (3) Lists all available scripts that are saved in the default folder for the selected tab.

• (4) Record Script: Creates a script by recording the commands you execute manually in the user
interface.

2024 R1 - © ANSYS, Inc. All rights reserved // 10

• (5) Playback PrePost Script: Executes the selected script.

• (6) Open PrePost Scripts Directory: Based upon the selected tab, opens the default folder where
scripts are saved.

• (7) Reload PrePost Scripts from the Filesystem: Refreshes the available scripts list based upon
the default folder for the selected tab.

• (8) Help: Displays some PrePost Script assistance content.

Tip:

More PrePost Script panel content is available in the User Manual. (From the Help menu,
point to Manuals, and then click User Manual.)

The Scripts shared across projects tab of the PrePost Script panel will show all the scripts you have
saved in Rocky's default folder: %HOMEPATH%DocumentsRockyScripts.

Now, let's add the provided script to this panel and run it:

1. Ensure the Scripts shared across projects tab is selected.

2. Click the Open Scripts Directory button. This should take you to the Scripts folder listed above.

3. From dem_tut02_files folder you downloaded earlier, find the script folder and then copy and
paste the provided script script_calibration_SAOR.py to the folder you just opened.

4. The new script will appear in the PrePost Scripts panel on the Scripts shared across projects
tab (as shown).
2024 R1 - © ANSYS, Inc. All rights reserved // 11
5. With this new script selected, click the Playback Script button (as shown).

1.1.11. SCRIPT RESULTS

After the script finishes the calculation, the resulting plot will be displayed:

The dashed regression lines are used to compute the SAOR of the pile.

The black dots represent the average of the maximum heights for each vertical cell.

The dark red area represents the minimum of the maximum heights for each vertical cell.

The light red area represents the maximum of the maximum heights for each vertical cell.

Note:

This script was designed for cases with higher particle counts than what was simplified for
this tutorial. As a result, your tutorial results may vary significantly.

1.1.12. SCRIPT RESULTS

In addition, a Results folder is created in the same place as the Rocky project.

2024 R1 - © ANSYS, Inc. All rights reserved // 12

This folder contains the following files:

• Experiment_saor.png: The output image of the script.

• experiment_data_points.csv: File containing the points used for fitting the lines.

• angles.json: Text file containing the calculated angles.

1.1.13. SCRIPT RESULTS

The provided script is based on Calibration 1: Static Angle of Repose test of the Rocky Calibration
Suite.

• Further information about this calibration test or other available calibration tests can be found in
the Rocky Calibration Suite page.

As previously shown, the SAOR is calculated from the result of two linear regressions, one starting
from the bottom of the pile and another one starting from the top of the pile.

Both linear regressions are performed initially with minimum number of points. Then, more points
are iteratively added to the regressions until certain conditions are fulfilled. Such details are explained
in the Calibration 1: Static Angle of Repose documentation.

2024 R1 - © ANSYS, Inc. All rights reserved // 13

The more particles you have, the better your results will be and the closer will be the SAOR calculated
From Top to the one calculated From Bottom.

Tip:

A smaller Particle Size or a larger Cylinder will increase particle count.

1.1.14. CALIBRATION SUITE AND MATERIAL WIZARD

For additional particle calibration tests, consider making use of the following resources, both of which
are available on the Customer Portal.

The Rocky Calibration Suite contains:

• Eight pre-made Rocky projects representing common bench tests

• Simplified project setup using pre-processing scripts

• Automatic post-processing reports

The Material Wizard can be used as a time-saving starting point for your calibration process. For

2024 R1 - © ANSYS, Inc. All rights reserved // 14

more details access the Material Wizard Page.

1.1.15. MODIFYING THE SCRIPT

You can change some parameters within the script to have a better resolution of your repose angles
calculations.

The main parameters are:

• N_DIVISIONS_FACTOR (line 31):

– Controls the cell size, which is defined by N_DIVISIONS_FACTOR Particle Size. As a consequence,
the higher the factor, the bigger the cell size.

– The default value is 1.5.

• N_SAMPLES (line 33):

– For each SAOR calculation, this defines the number of times the parallelepiped rotates and collects
the maximum height.

– The default value is 36, which rotates the parallelepiped 10 degrees for each collection.

– Increasing this number (thereby reducing the angle of rotation) will give you more points to
average.

• LIN_REG_INI (line 35):

– Initial number of points for the linear regressions.

– The default value is 3.

To modify the script, do the following:

1. From the PrePost Script panel, from the Scripts shared across projects tab, click the Open
PrePost Scripts Directory button.

2. From the directory dialog, right-click the script file you want to edit, and then open it with your
favorite Python editor. (For example, Visual Studio Code.)

2024 R1 - © ANSYS, Inc. All rights reserved // 15

3. Modify it as desired, and then save the file as a .py extension.

Important:

In order for Rocky to recognize it, the script file name must begin with script_.

1.1.16. HELP – API:PREPOST MANUAL

For further information on what Rocky APIs can be used within your scripts, we suggest searching
the Rocky API:PrePost Manual.

To access it, from the Rocky Help menu, point to Manuals, and then click API:PrePost Manual.

2024 R1 - © ANSYS, Inc. All rights reserved // 16

In the Rocky API:PrePost Help window, from the Contents tab, click Basic Scripting using
API:PrePost to learn how to set up a basic project.

To see the list of APIs available for scripting, navigate through the Class Reference section.

2024 R1 - © ANSYS, Inc. All rights reserved // 17

 Tip:

Additional scripting APIs are available in the Rocky code. To access

these, from the Rocky Tools menu, enable the Python Shell panel.

1.1.17. HELP – USER MANUAL

This completes Part B of this tutorial.

For further information on any topic presented, we suggest searching the User
Manual, which provides in-depth descriptions of the tools and parameters.

To access these options, from the main Toolbar click Help, point to Manuals, and then
click User Manual.
 1.1.18. CONCLUSION
Rocky was used to verify the repose profile of particles in order to calculate the Static Angle of
Repose.

Note:

Even though this tutorial involves running only one SAOR test, other
simulations must be done in order to calibrate the particle model in full.

During this tutorial, it was possible to:

• Use a Cross Plot to manually measure the angles

• Use the PrePost Script panel to run a Python script that measured the angles automatically

• Find and make use of the API:PrePost Manual for modifying

Python scripts What's Next?

• Now that you understand the basics on how to set up a script, you are ready to
move on to Part C and learn about PrePost Scripts and the Rocky Scheduler.