Beam Result Script Example

Download the RS3_Result_Scripting_Example folder for this example.

from rs3.RS3Modeler import RS3Modeler
from rs3.results.ResultEnums import BeamsDataType
from rs3.Geometry import Point, Cube
import os

Get the current folder directory.

current_dir = os.path.dirname(os.path.abspath(""))

Specify a port number that is not in use and start the RS3 program.

port = 60502
RS3Modeler.startApplication(port)

2026-03-13 17:04:39,395 - Rocscience.RS3 - INFO - Attempting to start the application at C:\Program Files\Rocscience\RS3\RS3 and binding server to port 60502...

Connect with the RS3 Modeler.

modeler = RS3Modeler(port)

For the demonstration purposes only, the model is copied for reuse. You may change the model path to your own model path.

model = modeler.openFile(rf"{current_dir}\example_models\RS3_Result_Scripting_Example\RS3_Result_Scripting_Example.rs3v3")

1. Get Node Results

1.1 Define a box region to filter beam elements (optional)

A cube region is defined by two corners. Only mesh nodes inside or intersecting the box will be returned. If you omit the region in the next step, all nodes in the model would be returned.

The goal of this example is to query the beam on the right wall of the tunnel. Therefore, define a cube region that includes the queried beam.

beam_query_region = Cube(
    corner1=Point(x=10.5, y=-1.0, z=-10.5),
    corner2=Point(x=11.5, y=31.0, z=-9.5),
)

1.2 Get the beam results object for the desired stage(s)

getBeamResults returns a list: one entry per stage requested. Here we request only stage 3, so the list has one element at index 0.

beam_results_list = model.Results.getBeamResults(stageNumber=[3])
beam_results_stage_3 = beam_results_list[0]

1.3 Get all beam node results for this stage

The query region is passed in to filter the beam we aim to query.

beam_node_results_list = beam_results_stage_3.getBeamNodeResults(region=beam_query_region)

Build a lookup: NodeID -> nodal result object. This is used later to get coordinates for each node attached to an element.

beam_node_by_id = {nr.NodeID: nr for nr in beam_node_results_list}
print(f"Beam: node results in region for stage 3: {len(beam_node_results_list)}")

Beam: node results in region for stage 3: 109

1.4 Get beam element results within the region

beam_element_results_list = beam_results_stage_3.getBeamElementResults(region=beam_query_region)
print(f"Beam: element results in region for stage 3: {len(beam_element_results_list)}")

Beam: element results in region for stage 3: 108

1.5 Take one element and read its per-node result values

Each element has attached nodes. getResults(…) returns a list of values, one per node of the element (in the same order as AttachedNodeIDs).

Based on the coordinates of nodes, this element locates at around one third of the tunnel.

element_index = 0
selected_beam_element = beam_element_results_list[element_index]
beam_attached_node_ids = selected_beam_element.AttachedNodeIDs
axis_force_per_node = selected_beam_element.getNodeResult(BeamsDataType.AXIS_FORCE)
beam_disp_per_node = selected_beam_element.getNodeResult(BeamsDataType.DISPLACEMENT_TOTAL)

print(f"Beam element ID {selected_beam_element.ElementID}, nodal results:")
for i in range(len(beam_attached_node_ids)):
    node_id = beam_attached_node_ids[i]
    nodal_result = beam_node_by_id[node_id]
    print(
        f"  Node {node_id}: (x, y, z, Axis Force, Total Displacement) = "
        f"({nodal_result.XCoordinate}, {nodal_result.YCoordinate}, {nodal_result.ZCoordinate}, "
        f"{axis_force_per_node[i]}, {beam_disp_per_node[i]})"
    )

Beam element ID 87991, nodal results:
  Node 3420: (x, y, z, Axis Force, Total Displacement) = (10.99802672842827, 12.48457786636161, -10.062790519529315, -14.273378942008405, 0.019423629801735173)
  Node 3421: (x, y, z, Axis Force, Total Displacement) = (10.99802672842827, 12.76386542774327, -10.062790519529315, -14.273378942008405, 0.018018400683144545)

Since accessing results doesn’t change the model, close the model without saving.

model.close(False)

Close the program.

modeler.closeProgram()

Full Script

# Beam Result Script Example
# Download the [RS3_Result_Scripting_Example folder](https://github.com/Rocscience/rs3-scripting/tree/main/docs/example_code/example_models/RS3_Result_Scripting_Example) for this example.
from rs3.RS3Modeler import RS3Modeler
from rs3.results.ResultEnums import BeamsDataType
from rs3.Geometry import Point, Cube
import os
# Get the current folder directory.
current_dir = os.path.dirname(os.path.abspath(""))
# Specify a port number that is not in use and start the RS3 program.
port = 60502
RS3Modeler.startApplication(port)
# Connect with the RS3 Modeler.
modeler = RS3Modeler(port)
# For the demonstration purposes only, the model is copied for reuse. You may change the 
# model path to your own model path.
model = modeler.openFile(rf"{current_dir}\example_models\RS3_Result_Scripting_Example\RS3_Result_Scripting_Example.rs3v3")

# 1. Get Node Results
# 1.1 Define a box region to filter beam elements (optional)
# A cube region is defined by two corners. Only mesh nodes inside or intersecting the box 
# will be returned. If you omit the region in the next step, all nodes in the model would 
# be returned.
# The goal of this example is to query the beam on the right wall of the tunnel. Therefore, 
# define a cube region that includes the queried beam.
beam_query_region = Cube(
    corner1=Point(x=10.5, y=-1.0, z=-10.5),
    corner2=Point(x=11.5, y=31.0, z=-9.5),
)

# 1.2 Get the beam results object for the desired stage(s)
# getBeamResults returns a list: one entry per stage requested. Here we request only stage 3, 
# so the list has one element at index 0.
beam_results_list = model.Results.getBeamResults(stageNumber=[3])
beam_results_stage_3 = beam_results_list[0]

# 1.3 Get all beam node results for this stage
# The query region is passed in to filter the beam we aim to query.
beam_node_results_list = beam_results_stage_3.getBeamNodeResults(region=beam_query_region)
# Build a lookup: NodeID -> nodal result object. This is used later to get coordinates for 
# each node attached to an element.
beam_node_by_id = {nr.NodeID: nr for nr in beam_node_results_list}
print(f"Beam: node results in region for stage 3: {len(beam_node_results_list)}")

# 1.4 Get beam element results within the region
beam_element_results_list = beam_results_stage_3.getBeamElementResults(region=beam_query_region)
print(f"Beam: element results in region for stage 3: {len(beam_element_results_list)}")

# 1.5 Take one element and read its per-node result values
# Each element has attached nodes. getResults(...) returns a list of values, one per node of 
# the element (in the same order as AttachedNodeIDs).
# Based on the coordinates of nodes, this element locates at around one third of the tunnel.
element_index = 0
selected_beam_element = beam_element_results_list[element_index]
beam_attached_node_ids = selected_beam_element.AttachedNodeIDs
axis_force_per_node = selected_beam_element.getNodeResult(BeamsDataType.AXIS_FORCE)
beam_disp_per_node = selected_beam_element.getNodeResult(BeamsDataType.DISPLACEMENT_TOTAL)
print(f"Beam element ID {selected_beam_element.ElementID}, nodal results:")
for i in range(len(beam_attached_node_ids)):
    node_id = beam_attached_node_ids[i]
    nodal_result = beam_node_by_id[node_id]
    print(
        f"  Node {node_id}: (x, y, z, Axis Force, Total Displacement) = "
        f"({nodal_result.XCoordinate}, {nodal_result.YCoordinate}, {nodal_result.ZCoordinate}, "
        f"{axis_force_per_node[i]}, {beam_disp_per_node[i]})"
    )
    
# Since accessing results doesn't change the model, close the model without saving.
model.close(False)

2026-03-13 17:05:31,695 - Rocscience.RS3 - INFO - Attempting to start the application at C:\Program Files\Rocscience\RS3\RS3 and binding server to port 60502...

Beam: node results in region for stage 3: 109
Beam: element results in region for stage 3: 108
Beam element ID 87991, nodal results:
  Node 3420: (x, y, z, Axis Force, Total Displacement) = (10.99802672842827, 12.48457786636161, -10.062790519529315, -14.273378942008405, 0.019423629801735173)
  Node 3421: (x, y, z, Axis Force, Total Displacement) = (10.99802672842827, 12.76386542774327, -10.062790519529315, -14.273378942008405, 0.018018400683144545)