Material Hydraulic Script Examples

Download the blankModel.rs3v3 for this example.

from rs3.RS3Modeler import RS3Modeler
from rs3.properties.PropertyEnums import *
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 = 60203
RS3Modeler.startApplication(port)

2026-03-13 16:27:39,414 - Rocscience.RS3 - INFO - Attempting to start the application at C:\Program Files\Rocscience\RS3\RS3 and binding server to port 60203...

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. Create and Get Material

Get the first material in the list.

material1 = model.getAllMaterialProperties()[0]
material1.getMaterialName()

'Soil'

newMaterialName = "New Material"
model.createNewMaterialProperty(newMaterialName)
newMaterial = model.getMaterialPropertyByName(newMaterialName)
newMaterial.getMaterialName()

'New Material'

2. Set Hydraulic Properties

2.1 Static Water

model.ProjectSettings.Groundwater.setGroundwaterMethod(GroundwaterMethodType.GW_SURFACES)
model.ProjectSettings.Groundwater.getGroundwaterMethod()

<GroundwaterMethodType.GW_SURFACES: 'GW_SURFACES'>

material1.Hydraulic.setProperties(PorosityValue=0.25)
material1.Hydraulic.getProperties()

{'PorosityValue': 0.25,
 'VoidRatio': 0.43,
 'DefineMaximumNegativePoreWaterPressure': False,
 'MaximumNegativePoreWaterPressure': 0.0,
 'UseBiotsCoefficientForCalculatingEffectiveStress': True,
 'UseCustomBiotsCoefficient': False,
 'BiotsCoefficient': 0.995}

2.1.1 Set Ru

userDefinnedRuValueName = "Ru=1.2"
material1.Hydraulic.StaticGroundwater.createNewWaterCondition(userDefinnedRuValueName, HydraulicParameterType.RU, 1.2)
material1.Hydraulic.StaticGroundwater.setWaterConditions(StaticWaterModes.USER_DEFINED_VALUE, userDefinnedRuValueName)
material1.Hydraulic.StaticGroundwater.getWaterConditions()

'Ru=1.2'

2.1.2 Set PWP

userDefinnedPWPValueName = "PWP=98.1"
material1.Hydraulic.StaticGroundwater.createNewWaterCondition(userDefinnedPWPValueName, HydraulicParameterType.PWP, 98.1)
material1.Hydraulic.StaticGroundwater.setWaterConditions(StaticWaterModes.USER_DEFINED_VALUE, userDefinnedPWPValueName)
material1.Hydraulic.StaticGroundwater.getWaterConditions()

'PWP=98.1'

2.1.3 Set Water Surface

waterSurfaceName = "Water Surface"
model.createNewWaterByLocationProperty(waterSurfaceName)
waterSurface = model.getWaterByLocationPropertyByName(waterSurfaceName)
waterSurface.setWaterSurfaceLocation([(0, 0, -5), (0, 30, -5), (30, 30, -5), (30, 0, -5)])
material1.Hydraulic.StaticGroundwater.setWaterConditions(StaticWaterModes.WATER_SURFACE, waterSurfaceName)
material1.Hydraulic.StaticGroundwater.getWaterConditions()

'Water Surface'

2.1.4 Set Water Grid

waterGridName = "Water Grid"
model.createNewWaterGridProperty(waterGridName)
waterGrid = model.getWaterGridPropertyByName(waterGridName)
waterGrid.setIs3D(True)
waterGrid.setWaterGridPoints([(0, 0, 0, -5), (0, 30, 0, -5), (30, 30, 0, -5), (30, 0, 0, -5)])
material1.Hydraulic.StaticGroundwater.setWaterConditions(StaticWaterModes.PWP_POINT_SET, waterGridName)
material1.Hydraulic.StaticGroundwater.getWaterConditions()

'Water Grid'

2.1.5 Set to Dry

material1.Hydraulic.StaticGroundwater.setWaterConditions(StaticWaterModes.DRY)
material1.Hydraulic.StaticGroundwater.getWaterConditions()

'Dry'

2.2 FEA Groundwater

model.ProjectSettings.Groundwater.setGroundwaterMethod(GroundwaterMethodType.GW_STEADYSTATE)
model.ProjectSettings.Groundwater.getGroundwaterMethod()

<GroundwaterMethodType.GW_STEADYSTATE: 'GW_STEADYSTATE'>

material1.Hydraulic.FEAGroundwater.setHydraulicModelType(HydraulicModelType.GARDNER)
material1.Hydraulic.FEAGroundwater.getHydraulicModelType()

<HydraulicModelType.GARDNER: 2>

material1.Hydraulic.FEAGroundwater.Gardner.setA(1.1)
material1.Hydraulic.FEAGroundwater.Gardner.getA()

1.1

customHydraulicModelName = "Custom Hydraulic Model"
model.createNewCustomHydraulicModel(customHydraulicModelName)
customHydraulicModel = model.getCustomHydraulicModelPropertyByName(customHydraulicModelName)
customHydraulicModel.setWaterContentInputType(WCInputType.BY_WATER_CONTENT)
customHydraulicModel.setPermeabilityFunction([(1.1, 2.2), (3.3, 4.4)])
customHydraulicModel.setWaterContentFunction([(11.1, 22.2), (33.3, 44.4)])

material1.Hydraulic.FEAGroundwater.setHydraulicModelType(HydraulicModelType.CUSTOM, customHydraulicModelName)
material1.Hydraulic.FEAGroundwater.getHydraulicModelType()

'Custom Hydraulic Model'

Save and close the model.

model.close(True)

Close the program.

modeler.closeProgram()

Full Script

# Material Hydraulic 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 *
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 = 60203
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. Create and Get Material
# Get the first material in the list.
material1 = model.getAllMaterialProperties()[0]
material1.getMaterialName()
newMaterialName = "New Material"
model.createNewMaterialProperty(newMaterialName)
newMaterial = model.getMaterialPropertyByName(newMaterialName)
newMaterial.getMaterialName()

# 2. Set Hydraulic Properties
# 2.1 Static Water
model.ProjectSettings.Groundwater.setGroundwaterMethod(GroundwaterMethodType.GW_SURFACES)
model.ProjectSettings.Groundwater.getGroundwaterMethod()
material1.Hydraulic.setProperties(PorosityValue=0.25)
material1.Hydraulic.getProperties()
# 2.1.1 Set Ru
userDefinnedRuValueName = "Ru=1.2"
material1.Hydraulic.StaticGroundwater.createNewWaterCondition(userDefinnedRuValueName, HydraulicParameterType.RU, 1.2)
material1.Hydraulic.StaticGroundwater.setWaterConditions(StaticWaterModes.USER_DEFINED_VALUE, userDefinnedRuValueName)
material1.Hydraulic.StaticGroundwater.getWaterConditions()
# 2.1.2 Set PWP
userDefinnedPWPValueName = "PWP=98.1"
material1.Hydraulic.StaticGroundwater.createNewWaterCondition(userDefinnedPWPValueName, HydraulicParameterType.PWP, 98.1)
material1.Hydraulic.StaticGroundwater.setWaterConditions(StaticWaterModes.USER_DEFINED_VALUE, userDefinnedPWPValueName)
material1.Hydraulic.StaticGroundwater.getWaterConditions()
# 2.1.3 Set Water Surface
waterSurfaceName = "Water Surface"
model.createNewWaterByLocationProperty(waterSurfaceName)
waterSurface = model.getWaterByLocationPropertyByName(waterSurfaceName)
waterSurface.setWaterSurfaceLocation([(0, 0, -5), (0, 30, -5), (30, 30, -5), (30, 0, -5)])
material1.Hydraulic.StaticGroundwater.setWaterConditions(StaticWaterModes.WATER_SURFACE, waterSurfaceName)
material1.Hydraulic.StaticGroundwater.getWaterConditions()
# 2.1.4 Set Water Grid
waterGridName = "Water Grid"
model.createNewWaterGridProperty(waterGridName)
waterGrid = model.getWaterGridPropertyByName(waterGridName)
waterGrid.setIs3D(True)
waterGrid.setWaterGridPoints([(0, 0, 0, -5), (0, 30, 0, -5), (30, 30, 0, -5), (30, 0, 0, -5)])
material1.Hydraulic.StaticGroundwater.setWaterConditions(StaticWaterModes.PWP_POINT_SET, waterGridName)
material1.Hydraulic.StaticGroundwater.getWaterConditions()
# 2.1.5 Set to Dry
material1.Hydraulic.StaticGroundwater.setWaterConditions(StaticWaterModes.DRY)
material1.Hydraulic.StaticGroundwater.getWaterConditions()

# 2.2 FEA Groundwater
model.ProjectSettings.Groundwater.setGroundwaterMethod(GroundwaterMethodType.GW_STEADYSTATE)
model.ProjectSettings.Groundwater.getGroundwaterMethod()
material1.Hydraulic.FEAGroundwater.setHydraulicModelType(HydraulicModelType.GARDNER)
material1.Hydraulic.FEAGroundwater.getHydraulicModelType()
material1.Hydraulic.FEAGroundwater.Gardner.setA(1.1)
material1.Hydraulic.FEAGroundwater.Gardner.getA()
customHydraulicModelName = "Custom Hydraulic Model"
model.createNewCustomHydraulicModel(customHydraulicModelName)
customHydraulicModel = model.getCustomHydraulicModelPropertyByName(customHydraulicModelName)
customHydraulicModel.setWaterContentInputType(WCInputType.BY_WATER_CONTENT)
customHydraulicModel.setPermeabilityFunction([(1.1, 2.2), (3.3, 4.4)])
customHydraulicModel.setWaterContentFunction([(11.1, 22.2), (33.3, 44.4)])
material1.Hydraulic.FEAGroundwater.setHydraulicModelType(HydraulicModelType.CUSTOM, customHydraulicModelName)
material1.Hydraulic.FEAGroundwater.getHydraulicModelType()

# Save and close the model.
model.close(True)

2026-03-13 16:28:34,875 - Rocscience.RS3 - INFO - Attempting to start the application at C:\Program Files\Rocscience\RS3\RS3 and binding server to port 60203...