Joint Script Examples#
Download the blankModel.rs3v3 for this example.
from rs3.RS3Modeler import RS3Modeler
from rs3.properties.PropertyEnums import *
import os
import shutil
Get the current folder directory.
current_dir = os.path.abspath("")
Specify a port number that is not in use and start the RS3 program.
port = 60303
RS3Modeler.startApplication(port)
2026-03-13 17:19:55,800 - Rocscience.RS3 - INFO - Attempting to start the application at C:\Program Files\Rocscience\RS3\RS3 and binding server to port 60303...
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.
blankModelPath = rf"{os.path.dirname(current_dir)}\example_models\blankModel.rs3v3"
copiedModelPath = rf"{os.path.dirname(current_dir)}\example_models\copiedModel.rs3v3"
_ = shutil.copy(blankModelPath, copiedModelPath)
Open the copied model file.
model = modeler.openFile(copiedModelPath)
1. Create and Get Joint#
Get the first joint in the list.
joint1 = model.getAllJointProperties()[0]
joint1.getJointName()
'Joint 1'
Create a new joint and get the joint by name.
joint2Name = "Joint 2"
model.createNewJointProperty(joint2Name)
joint2 = model.getJointPropertyByName(joint2Name)
joint2.getJointName()
'Joint 2'
2. Set Joint Properties#
joint1.setConstitutiveModel(JointConstitutiveModelTypes.MOHR_COULOMB)
joint1.getConstitutiveModel()
<JointConstitutiveModelTypes.MOHR_COULOMB: 'MOHR_COULOMB'>
joint1.getProperties()
{'InitialJointDeformation': True,
'Permeable': True,
'ApplySSR': True,
'ApplyPorePressure': True,
'ApplyAdditionalPressureInsideJoint': False,
'AdditionalPressureInsideJoint': 0.0,
'ApplyStageFactors': False}
joint1.setInitialJointDeformation(False)
joint1.setApplyAdditionalPressureInsideJoint(True)
joint1.setAdditionalPressureType(AdditionalPressureType.PRESSURE)
joint1.setAdditionalPressureInsideJoint(150)
joint1.MohrCoulomb.getProperties()
{'DilationAngle': 0.0,
'NormalStiffness': 100000.0,
'ShearStiffness': 10000.0,
'Cohesion': 0.0,
'FrictionAngle': 35.0,
'TensileStrength': 0.0,
'DefineResidualStrength': False,
'Directional': False,
'ResidualCohesion': 0.0,
'ResidualFrictionAngle': 0.0,
'ResidualTensileStrength': 0.0}
joint1.MohrCoulomb.setDefineResidualStrength(True)
joint1.MohrCoulomb.setProperties(TensileStrength=10, ResidualTensileStrength=5)
joint1Properties = joint1.MohrCoulomb.getProperties()
joint1Properties
{'DilationAngle': 0.0,
'NormalStiffness': 100000.0,
'ShearStiffness': 10000.0,
'Cohesion': 0.0,
'FrictionAngle': 35.0,
'TensileStrength': 10.0,
'DefineResidualStrength': True,
'Directional': False,
'ResidualCohesion': 0.0,
'ResidualFrictionAngle': 0.0,
'ResidualTensileStrength': 5.0}
3. Copy Joint Properties#
joint2.setConstitutiveModel(JointConstitutiveModelTypes.MOHR_COULOMB)
joint2.getConstitutiveModel()
<JointConstitutiveModelTypes.MOHR_COULOMB: 'MOHR_COULOMB'>
joint2.MohrCoulomb.getProperties()
{'DilationAngle': 0.0,
'NormalStiffness': 100000.0,
'ShearStiffness': 10000.0,
'Cohesion': 0.0,
'FrictionAngle': 35.0,
'TensileStrength': 0.0,
'DefineResidualStrength': False,
'Directional': False,
'ResidualCohesion': 0.0,
'ResidualFrictionAngle': 0.0,
'ResidualTensileStrength': 0.0}
joint2.MohrCoulomb.setProperties(**joint1Properties)
joint2.MohrCoulomb.getProperties()
{'DilationAngle': 0.0,
'NormalStiffness': 100000.0,
'ShearStiffness': 10000.0,
'Cohesion': 0.0,
'FrictionAngle': 35.0,
'TensileStrength': 10.0,
'DefineResidualStrength': True,
'Directional': False,
'ResidualCohesion': 0.0,
'ResidualFrictionAngle': 0.0,
'ResidualTensileStrength': 5.0}
4. Set Stage Factors#
Turn on the stage factors of joints.
joint1.setApplyStageFactors(True)
joint1.MohrCoulomb.setAllowSlipStartFromStage(3)
Joints take both constitutive model properties and hydraulic properties. When you create the stage factors for joints, the overall controls are under the Joint class.
Now, create a stage factor for stage 2 and get the stage factors of hydraulic properties of the joint at stage 2.
joint1.StageFactorInterface.createStageFactor(2)
newJointStageFactor_s2 = joint1.StageFactorInterface.getDefinedStageFactors()[2]
Get the current stage factor of additional pressure inside joint.
newJointStageFactor_s2.getAdditionalPressureInsideJointFactor()
1.0
Set stage factor of additional pressure inside joint.
newJointStageFactor_s2.setAdditionalPressureInsideJointFactor(1.5)
Get stage factors of all stages and check stage factor of additional pressure inside joint at stage 2.
stageFactors_s2 = joint1.StageFactorInterface.getStageFactor(2)
stageFactors_s2.getAdditionalPressureInsideJointFactor()
1.5
Similarly, change the stage factor of dilation angle under Mohr Coulomb joint module.
newMohrCoulombJointStageFactor_s2 = joint1.MohrCoulomb.StageFactorInterface.getDefinedStageFactors()[2]
newMohrCoulombJointStageFactor_s2.setDilationAngleFactor(1.3)
newMohrCoulombJointStageFactor_s2.getDilationAngleFactor()
1.3
Create another stage factor for stage 4 and set the stage factor of additional pressure inside joint.
joint1.StageFactorInterface.createStageFactor(4)
newJointStageFactor_s4 = joint1.StageFactorInterface.getDefinedStageFactors()[4]
newJointStageFactor_s4.setAdditionalPressureInsideJointFactor(2.1)
newJointStageFactor_s4.getAdditionalPressureInsideJointFactor()
2.1
5. Delete Joint Stage Factor#
Get the dictionary of all stage factors.
jointStageFactors = joint1.StageFactorInterface.getDefinedStageFactors()
jointStageFactors
{2: <rs3.properties.joint.Joint.JointDefinedStageFactorBase at 0x1cca5b5e450>,
4: <rs3.properties.joint.Joint.JointDefinedStageFactorBase at 0x1cc961d7350>}
Remove stage factors at stage 4.
jointStageFactors.pop(4)
<rs3.properties.joint.Joint.JointDefinedStageFactorBase at 0x1cc961d7350>
Set the dictionary back and check the defined stage factors. Now only stage 2 has stage factors defined.
joint1.StageFactorInterface.setDefinedStageFactors(jointStageFactors)
joint1.StageFactorInterface.getDefinedStageFactors()
{2: <rs3.properties.joint.Joint.JointDefinedStageFactorBase at 0x1cc961d7460>}
6. Delete Joint#
Delete joint2.
model.deleteJointProperty(joint2Name)
Check if joint2 still exist in the joint list.
allJoints = model.getAllJointProperties()
for joint in allJoints:
print(joint.getJointName())
Joint 1
Save and close the model.
model.close(True)
Close the program.
modeler.closeProgram()
Full Script#
# Joint Script Examples
# Download the [blankModel.rs3v3](https://github.com/Rocscience/rs3-scripting/tree/main/docs/example_code/example_models/blankModel.rs3v3) for this example.
from rs3.RS3Modeler import RS3Modeler
from rs3.properties.PropertyEnums import *
import os
import shutil
# Get the current folder directory.
current_dir = os.path.abspath("")
# Specify a port number that is not in use and start the RS3 program.
port = 60303
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.
blankModelPath = rf"{os.path.dirname(current_dir)}\example_models\blankModel.rs3v3"
copiedModelPath = rf"{os.path.dirname(current_dir)}\example_models\copiedModel.rs3v3"
_ = shutil.copy(blankModelPath, copiedModelPath)
# Open the copied model file.
model = modeler.openFile(copiedModelPath)
# 1. Create and Get Joint
# Get the first joint in the list.
joint1 = model.getAllJointProperties()[0]
# Create a new joint and get the joint by name.
joint2Name = "Joint 2"
model.createNewJointProperty(joint2Name)
joint2 = model.getJointPropertyByName(joint2Name)
# 2. Set Joint Properties
joint1.setConstitutiveModel(JointConstitutiveModelTypes.MOHR_COULOMB)
joint1.setInitialJointDeformation(False)
joint1.setApplyAdditionalPressureInsideJoint(True)
joint1.setAdditionalPressureType(AdditionalPressureType.PRESSURE)
joint1.setAdditionalPressureInsideJoint(150)
joint1.MohrCoulomb.setDefineResidualStrength(True)
joint1.MohrCoulomb.setProperties(TensileStrength=10, ResidualTensileStrength=5)
joint1Properties = joint1.MohrCoulomb.getProperties()
# 3. Copy Joint Properties
joint2.setConstitutiveModel(JointConstitutiveModelTypes.MOHR_COULOMB)
joint2.MohrCoulomb.setProperties(**joint1Properties)
# 4. Set Stage Factors
# Turn on the stage factors of joints.
joint1.setApplyStageFactors(True)
joint1.MohrCoulomb.setAllowSlipStartFromStage(3)
# Joints take both constitutive model properties and hydraulic properties.
# When you create the stage factors for joints, the overall controls are under
# the Joint class.
# Now, create a stage factor for stage 2 and get the stage factors of hydraulic
# properties of the joint at stage 2.
joint1.StageFactorInterface.createStageFactor(2)
newJointStageFactor_s2 = joint1.StageFactorInterface.getDefinedStageFactors()[2]
# Set stage factor of additional pressure inside joint.
newJointStageFactor_s2.setAdditionalPressureInsideJointFactor(1.5)
# Get stage factors of all stages and check stage factor of additional pressure inside joint at stage 2.
stageFactors_s2 = joint1.StageFactorInterface.getStageFactor(2)
# Similarly, change the stage factor of dilation angle under Mohr Coulomb joint module.
newMohrCoulombJointStageFactor_s2 = joint1.MohrCoulomb.StageFactorInterface.getDefinedStageFactors()[2]
newMohrCoulombJointStageFactor_s2.setDilationAngleFactor(1.3)
# Create another stage factor for stage 4 and set the stage factor of additional pressure inside joint.
joint1.StageFactorInterface.createStageFactor(4)
newJointStageFactor_s4 = joint1.StageFactorInterface.getDefinedStageFactors()[4]
newJointStageFactor_s4.setAdditionalPressureInsideJointFactor(2.1)
# 5. Delete Joint Stage Factor
# Get the dictionary of all stage factors.
jointStageFactors = joint1.StageFactorInterface.getDefinedStageFactors()
# Remove stage factors at stage 4.
jointStageFactors.pop(4)
# Set the dictionary back and check the defined stage factors. Now only stage 2 has stage factors defined.
joint1.StageFactorInterface.setDefinedStageFactors(jointStageFactors)
# 6. Delete Joint
# Delete joint2.
model.deleteJointProperty(joint2Name)
# Check if joint2 still exist in the joint list.
allJoints = model.getAllJointProperties()
for joint in allJoints:
print(joint.getJointName())
# Save and close the model.
model.close(True)
2026-03-13 17:20:48,468 - Rocscience.RS3 - INFO - Attempting to start the application at C:\Program Files\Rocscience\RS3\RS3 and binding server to port 60303...
Joint 1