Project Settings Script Examples#
Download the blankModel.rs3v3 for this example.
You may jump to a specific section by selecting the table on content on the right side of the page.
from rs3.RS3Modeler import RS3Modeler
from rs3.projectSettings.ProjectSettingEnums import *
import os
import shutil
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 = 60103
RS3Modeler.startApplication(port)
2026-03-13 17:00:36,601 - Rocscience.RS3 - INFO - Attempting to start the application at C:\Program Files\Rocscience\RS3\RS3 and binding server to port 60103...
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"{current_dir}\example_models\blankModel.rs3v3"
copiedModelPath = rf"{current_dir}\example_models\copiedModel.rs3v3"
_ = shutil.copy(blankModelPath, copiedModelPath)
Open the copied model file.
model = modeler.openFile(copiedModelPath)
1. Units#
Change the units will impact almost all properties in the project. Therefore, we highly recommend you to set the correct unit at the beginning of the project.
units = model.ProjectSettings.Units
units.getUnitSystem()
<UnitSystemType.METRIC_KPA: 'RFC_METRIC_KPA'>
By default, properties will be reset when the new unit system is set.
units.setUnitSystem(UnitSystemType.METRIC_MPA)
units.getUnitSystem()
<UnitSystemType.METRIC_MPA: 'RFC_METRIC_MPA'>
units.getTimeUnits()
<TimeUnitsType.DAYS: 'DAYS'>
units.getPermeabilityUnits()
<PermeabilityUnitsType.METER_SECONDS: 'METER_SECONDS'>
units.setTimeUnits(TimeUnitsType.HOURS)
units.getTimeUnits()
<TimeUnitsType.HOURS: 'HOURS'>
units.setPermeabilityUnits(PermeabilityUnitsType.METER_SECONDS)
units.getPermeabilityUnits()
<PermeabilityUnitsType.METER_SECONDS: 'METER_SECONDS'>
2. Stages#
stages = model.ProjectSettings.Stages
2.1 Stage Names#
Get defined stages.
originalStageNames = stages.getDefinedStageNames()
originalStageNames
['Stage 1', 'Stage 2', 'Stage 3', 'Stage 4', 'Stage 5']
Rename every stage through a for loop.
stageNames = ["Initial Conditions", "Excavate Tunnel", "Excavate Foundation", "Pour Concrete Foundation", "Loading Foundation"]
for i in range(len(originalStageNames)):
stageNum = i+1
stages.setName(stageNum, stageNames[i])
newStageName = stages.getName(stageNum)
print(f"The new stage name of stage {stageNum} is {newStageName}")
The new stage name of stage 1 is Initial Conditions
The new stage name of stage 2 is Excavate Tunnel
The new stage name of stage 3 is Excavate Foundation
The new stage name of stage 4 is Pour Concrete Foundation
The new stage name of stage 5 is Loading Foundation
2.2 Set Total Number of Stages#
Add three more stages to the current model. The new stages will use the default stage names.
stages.setTotalNumberOfStages(8)
stages.getDefinedStageNames()
['Initial Conditions',
'Excavate Tunnel',
'Excavate Foundation',
'Pour Concrete Foundation',
'Loading Foundation',
'Stage 6',
'Stage 7',
'Stage 8']
Reduce the number of stages will delete stages from the last stage.
stages.setTotalNumberOfStages(5)
stages.getDefinedStageNames()
['Initial Conditions',
'Excavate Tunnel',
'Excavate Foundation',
'Pour Concrete Foundation',
'Loading Foundation']
2.3 Add or Delete Stages#
Add 2 stages at the end of the project
stages.addStages(2, -1)
Remove 2 stages from the end
stages.removeStages(2, -1)
Add 3 stages after the stage 2
stages.addStages(3, 2)
Remove 3 stages starting from stage 3 (removes stages 3, 4, 5)
stages.removeStages(3, 3)
Add 2 stages at the end (same as passing -1)
stages.addStages(numberOfStages=2)
Remove 2 stages from the end (same as passing -1 explicitly)
stages.removeStages(numberOfStages=2)
Add 1 stage after the stage 5
stages.addStages(numberOfStages=1, referenceStage=5)
Remove 1 stage at stage 6
stages.removeStages(numberOfStages=1, startingStage=6)
2.4 Set time and PWP Method#
When the groundwater model is set to transient analysis, time and pore water pressure (PWP) method are required.
model.ProjectSettings.Groundwater.setGroundwaterMethod(GroundwaterMethodType.GW_TRANSIENT)
model.ProjectSettings.Groundwater.setPWPMethodByStage(True)
stages.setTime(2, 1.5)
stages.getTime(2)
1.5
stages.setPWPMethod(2, PWPMethod.GW_SURFACES)
stages.getPWPMethod(2)
<PWPMethod.GW_SURFACES: 'GW_SURFACES'>
3. Stress Analysis#
stressAnalysis = model.ProjectSettings.StressAnalysis
Get properties as a dictionary.
stressAnalysis.getProperties()
{'Iterations': 500,
'Tolerance': 0.001,
'NumberLoadSteps': 10,
'IterationsMin': 20,
'LoadIncrementInitial': 0.1,
'LoadIncrementMin': 0.05,
'LoadIncrementMax': 1.0,
'IterationsTrackConvergence': 5,
'ScaleForceIncrementUp': True,
'ScaleForceIncrementUpVal': 1.3,
'ScaleForceIncrementDown': True,
'ScaleForceIncrementDownVal': 0.5,
'IsAcceleratedConvergenceActive': True,
'AccelerateInitialStiffness': True,
'AlphaMin': 0.1,
'AlphaMax': 10.0,
'AbortUponFailure': False,
'EnableFileRecovery': True,
'TensileFailureReduceHoekBrownTensileStrengthToZero': False,
'TensileFailureReduceShearStrengthToResidual': True,
'UseDefaultMaterialForAdvancedMaterialsOutsidePlasticRegion': True}
Set multiple properties at the same time.
stressAnalysis.setProperties(Iterations=520, Tolerance=0.005)
stressAnalysis.getProperties()
{'Iterations': 520,
'Tolerance': 0.005,
'NumberLoadSteps': 10,
'IterationsMin': 20,
'LoadIncrementInitial': 0.1,
'LoadIncrementMin': 0.05,
'LoadIncrementMax': 1.0,
'IterationsTrackConvergence': 5,
'ScaleForceIncrementUp': True,
'ScaleForceIncrementUpVal': 1.3,
'ScaleForceIncrementDown': True,
'ScaleForceIncrementDownVal': 0.5,
'IsAcceleratedConvergenceActive': True,
'AccelerateInitialStiffness': True,
'AlphaMin': 0.1,
'AlphaMax': 10.0,
'AbortUponFailure': False,
'EnableFileRecovery': True,
'TensileFailureReduceHoekBrownTensileStrengthToZero': False,
'TensileFailureReduceShearStrengthToResidual': True,
'UseDefaultMaterialForAdvancedMaterialsOutsidePlasticRegion': True}
Get a single property.
stressAnalysis.getConvergenceCriteriaType()
<StressConvergenceCriteriaType.ABSOLUTE_FORCE_ENERGY: 'ABSOLUTE_FORCE_ENERGY'>
Set a single property.
stressAnalysis.setConvergenceCriteriaType(StressConvergenceCriteriaType.ABSOLUTE_ENERGY)
stressAnalysis.getConvergenceCriteriaType()
<StressConvergenceCriteriaType.ABSOLUTE_ENERGY: 'ABSOLUTE_ENERGY'>
4. Solver Options#
solverOptions = model.ProjectSettings.SolverOptions
Get the current analaysis type and set it to the new type.
solverOptions.getAnalysisType()
<AnalysisType.UNCOUPLED: 'UNCOUPLED'>
solverOptions.setAnalysisType(AnalysisType.COUPLED_BIOT)
solverOptions.getAnalysisType()
<AnalysisType.COUPLED_BIOT: 'COUPLED_BIOT'>
Get the current solver type and change it to the new type.
solverOptions.getSolverType()
<SolverType.AUTO: 'AUTO'>
solverOptions.setSolverType(SolverType.DIRECT_CPU)
solverOptions.getSolverType()
<SolverType.DIRECT_CPU: 'DIRECT'>
5. Groundwater#
groundwater = model.ProjectSettings.Groundwater
groundwater.getProperties()
{'PoreFluidUnitWeight': 9.81,
'IsNegativePorePressureCutoff': False,
'NegativePorePressureCutoff': 0.0,
'PWPMethodByStage': True,
'MaxNumIterations': 500,
'Tolerance': 0.001,
'LoadSteps': 10,
'TimeSteps': 1,
'IsScaleTolerance': True,
'IsAddFluidBodyForce': True,
'FluidBulkModulus': 2200000.0}
groundwater.setProperties(PoreFluidUnitWeight=10.0, PWPMethodByStage=False)
groundwater.getProperties()
{'PoreFluidUnitWeight': 10.0,
'IsNegativePorePressureCutoff': False,
'NegativePorePressureCutoff': 0.0,
'PWPMethodByStage': False,
'MaxNumIterations': 500,
'Tolerance': 0.001,
'LoadSteps': 10,
'TimeSteps': 1,
'IsScaleTolerance': True,
'IsAddFluidBodyForce': True,
'FluidBulkModulus': 2200000.0}
groundwater.getGroundwaterMethod()
<GroundwaterMethodType.GW_TRANSIENT: 'GW_TRANSIENT'>
groundwater.setGroundwaterMethod(GroundwaterMethodType.GW_NONE)
groundwater.getGroundwaterMethod()
<GroundwaterMethodType.GW_NONE: 'GW_NONE'>
6. Shear Strength Reduction#
ssr = model.ProjectSettings.ShearStrengthReduction
Turn on shear strength reduction analysis.
ssr.setSRFIsOn(True)
ssr.getProperties()
{'SRFIsOn': True,
'InitialEstimateOfSRF': 1.0,
'SRFAuto': True,
'SRFTolerance': 0.01,
'SRFStepSize': 0.2,
'FinalSRF': 2.0,
'AccelerateSRF': False,
'SRFAccelerateAdvanced': True,
'ApplySSRToMohrCoulombTensileStrength': True,
'SRFUserdefined': False,
'StressAnalysisTolerance': 0.001,
'MaximumNumberOfIterations': 500}
ssr.setProperties(AccelerateSRF=True)
ssr.getProperties()
{'SRFIsOn': True,
'InitialEstimateOfSRF': 1.0,
'SRFAuto': True,
'SRFTolerance': 0.01,
'SRFStepSize': 0.2,
'FinalSRF': 2.0,
'AccelerateSRF': True,
'SRFAccelerateAdvanced': True,
'ApplySSRToMohrCoulombTensileStrength': True,
'SRFUserdefined': False,
'StressAnalysisTolerance': 0.001,
'MaximumNumberOfIterations': 500}
ssr.setSRFAccelerateAdvanced(False)
ssr.getSRFAccelerateAdvanced()
False
ssr.setSRFUserdefined(True)
ssr.setSSRConvergenceType(SSRConvergenceType.ABSOLUTE_FORCE)
ssr.getSSRConvergenceType()
<SSRConvergenceType.ABSOLUTE_FORCE: 'ABSOLUTE_FORCE'>
ssr.setSRFIsOn(False)
7. Dynamic#
dynamic = model.ProjectSettings.Dynamic
Turn on dynamic analysis.
dynamic.setIsDynamicOn(True)
dynamic.getProperties()
{'IsDynamicOn': True,
'IsRayleighDampingbyAlphaMOn': True,
'AlphaM': 1.5,
'BetaK': 0.002,
'Frequency1': 5.0,
'Frequency2': 20.0,
'DampingRatio1': 0.0,
'DampingRatio2': 0.0,
'NumTimeSteps': 1,
'Beta': 0.25,
'Gamma': 0.5}
dynamic.setIsRayleighDampingbyAlphaMOn(False)
dynamic.getIsRayleighDampingbyAlphaMOn()
False
dynamic.setProperties(Frequency1=10, Frequency2=25)
dynamic.getProperties()
{'IsDynamicOn': True,
'IsRayleighDampingbyAlphaMOn': False,
'AlphaM': 1.5,
'BetaK': 0.002,
'Frequency1': 10.0,
'Frequency2': 25.0,
'DampingRatio1': 0.0,
'DampingRatio2': 0.0,
'NumTimeSteps': 1,
'Beta': 0.25,
'Gamma': 0.5}
Save and close the model.
model.close(True)
Close the program.
modeler.closeProgram()
Full Script#
# Project Settings 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.projectSettings.ProjectSettingEnums import *
import os
import shutil
# 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 = 60103
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"{current_dir}\example_models\blankModel.rs3v3"
copiedModelPath = rf"{current_dir}\example_models\copiedModel.rs3v3"
_ = shutil.copy(blankModelPath, copiedModelPath)
# Open the copied model file.
model = modeler.openFile(copiedModelPath)
# 1. Units
# Change the units will impact almost all properties in the project.
# Therefore, we highly recommend you to set the correct unit at the beginning of the project.
units = model.ProjectSettings.Units
# By default, properties will be reset when the new unit system is set.
units.setUnitSystem(UnitSystemType.METRIC_MPA)
units.setTimeUnits(TimeUnitsType.HOURS)
units.setPermeabilityUnits(PermeabilityUnitsType.METER_SECONDS)
# 2. Stages
stages = model.ProjectSettings.Stages
# 2.1 Stage Names
# Get defined stages.
originalStageNames = stages.getDefinedStageNames()
# Rename every stage through a for loop.
stageNames = ["Initial Conditions", "Excavate Tunnel", "Excavate Foundation", "Pour Concrete Foundation", "Loading Foundation"]
for i in range(len(originalStageNames)):
stageNum = i+1
stages.setName(stageNum, stageNames[i])
newStageName = stages.getName(stageNum)
print(f"The new stage name of stage {stageNum} is {newStageName}")
# 2.2 Set Total Number of Stages
# Add three more stages to the current model. The new stages will use the default stage names.
stages.setTotalNumberOfStages(8)
# Reduce the number of stages will delete stages from the last stage.
stages.setTotalNumberOfStages(5)
# 2.3 Add or Delete Stages
# Add 2 stages at the end of the project
stages.addStages(2, -1)
# Remove 2 stages from the end
stages.removeStages(2, -1)
# Add 3 stages after the stage 2
stages.addStages(3, 2)
# Remove 3 stages starting from stage 3 (removes stages 3, 4, 5)
stages.removeStages(3, 3)
# Add 2 stages at the end (same as passing -1)
stages.addStages(numberOfStages=2)
# Remove 2 stages from the end (same as passing -1 explicitly)
stages.removeStages(numberOfStages=2)
# Add 1 stage after the stage 5
stages.addStages(numberOfStages=1, referenceStage=5)
# Remove 1 stage at stage 6
stages.removeStages(numberOfStages=1, startingStage=6)
# 2.4 Set time and PWP Method
# When the groundwater model is set to transient analysis,
# time and pore water pressure (PWP) method are required.
model.ProjectSettings.Groundwater.setGroundwaterMethod(GroundwaterMethodType.GW_TRANSIENT)
model.ProjectSettings.Groundwater.setPWPMethodByStage(True)
stages.setTime(2, 1.5)
stages.setPWPMethod(2, PWPMethod.GW_SURFACES)
# 3. Stress Analysis
stressAnalysis = model.ProjectSettings.StressAnalysis
# Set multiple properties at the same time.
stressAnalysis.setProperties(Iterations=520, Tolerance=0.005)
# Set a single property.
stressAnalysis.setConvergenceCriteriaType(StressConvergenceCriteriaType.ABSOLUTE_ENERGY)
# 4. Solver Options
solverOptions = model.ProjectSettings.SolverOptions
# Set the current analysis to the new type.
solverOptions.setAnalysisType(AnalysisType.COUPLED_BIOT)
# Get the current solver type and change it to the new type.
solverOptions.setSolverType(SolverType.DIRECT_CPU)
# 5. Groundwater
groundwater = model.ProjectSettings.Groundwater
groundwater.setProperties(PoreFluidUnitWeight=10.0, PWPMethodByStage=False)
groundwater.setGroundwaterMethod(GroundwaterMethodType.GW_NONE)
# 6. Shear Strength Reduction
ssr = model.ProjectSettings.ShearStrengthReduction
# Turn on shear strength reduction analysis.
ssr.setSRFIsOn(True)
ssr.setProperties(AccelerateSRF=True)
ssr.setSRFAccelerateAdvanced(False)
ssr.setSRFUserdefined(True)
ssr.setSSRConvergenceType(SSRConvergenceType.ABSOLUTE_FORCE)
ssr.setSRFIsOn(False)
# 7. Dynamic
dynamic = model.ProjectSettings.Dynamic
# Turn on dynamic analysis.
dynamic.setIsDynamicOn(True)
dynamic.setIsRayleighDampingbyAlphaMOn(False)
dynamic.setProperties(Frequency1=10, Frequency2=25)
# Save and close the model.
model.close(True)
2026-03-13 17:01:35,239 - Rocscience.RS3 - INFO - Attempting to start the application at C:\Program Files\Rocscience\RS3\RS3 and binding server to port 60103...
The new stage name of stage 1 is Initial Conditions
The new stage name of stage 2 is Excavate Tunnel
The new stage name of stage 3 is Excavate Foundation
The new stage name of stage 4 is Pour Concrete Foundation
The new stage name of stage 5 is Loading Foundation