Getting Started¶

PlatRock has two user interfaces, namely the “script / CLI” and the “graphic / WebUI”. Both interfaces can be ran locally (on local ressources) as well as remotely (on a distant server ressources). The technical means used to achive that are summarized below:

	Script interface (CLI)	Graphical interface
Local	Shell	PlatRock-WebUI on localhost
Remote	SSH	PlatRock-WebUI on remote server

Note that unlike PlatRock which is licensed under GPLv3, PlatRock-WebUI is closed-source and its usage is restricted to authorized users only.

INSTALLATIONS¶

Prerequisites¶

At the moment PlatRock is only tested on debian-based platform unix distros. Prior to PlatRock installation, please check that the following dependencies are satisfied.

python >= 3.10, which is the default on modern linux distros ;
gdal (which can be installed on debian-based systems with sudo apt install g++ python3-dev libgdal-dev).

Modern python package uses python virtual environments, so do PlatRock. You can use the virtual environment manager you want, below are two examples.

In any case, don’t forget to install the libgdal-dev package as mentionned above.

Using pipx¶

Install pipx on your disto:

sudo apt install pipx

Then install PlatRock from pypi repository or gitlab:

pipx install platrock #the more stable release, from pipy
 # OR
pipx install git+https://gitlab.com/platrock/platrock.git@dev #the latest development banch, may be unstable

You should normally be able to launch PlatRock by simply invoking it:

platrock myscript.py

You can also import it in your own python script, but in this case you must activate the corresponding venv created by pipx before:

pipx list #shows all pipx venv created, find platrock venv path
 # Usually, the command to activate PlatRock venv would be:
source "/home/$USER/.local/share/pipx/venvs/platrock/bin/activate"

In your script:

import platrock

Using poetry¶

PlatRock uses poetry as packaging/dependency manager. You can install PlatRock using poetry. First install poetry and git.

Then download platrock:

git clone https://gitlab.com/platrock/platrock.git`
cd platrock

Install PlatRock in ./.venv/:

poetry install

Finally launch PlatRock:

poetry run platrock myscript.py

Or import PlatRock from your own script, don’t forget to activate PlatRock venv first:

poetry shell

In your script:

import platrock

Optional modules¶

Realtime 3D viewer for testing 3D models:

pip3 install pyqt5 vtk

Siconos for models with rocks shape integration:

See https://nonsmooth.gricad-pages.univ-grenoble-alpes.fr/siconos/install_guide/install_guide.html

Documentation creation¶

Dependencies :

pip3 install sphinx sphinx-rtd-theme

Compilation :

make html

Note

Pdf creation will require a latex distribution and the pre-conversion of all svg source images to pdf format. First install dependencies:

sudo apt install texlive texlive-latex-extra dvipng latexmk inkscape

Then the compilation in three steps:

Automatic images conversion: find -type f -name '*.svg' -exec sh -c 'f=$(basename $1 .svg);d=$(dirname $1);inkscape {} --export-pdf="$d/$f.pdf"' sh {} ;

Creation of tex file: sphinx-build -b latex path_to_doc_source_dir path_to_doc_build_dir

Pdf creation: cd path_to_doc_build_dir && pdflatex PlatRock.tex

PlatRock CLI¶

Usage :

platrock script_name.py

or, for a more verbose (but slower) mode:

platrock -ll=info script_name.py

TwoD Model¶

### SETUP ###

# Create a terrain object from a terrain csv file.
# If the file has dhp_mean, dhp_std and trees_density columns, the forest can be enabled
T=TwoD.Objects.Terrain("./TwoD_terrain.txt")

# Use a dictionnary to store the initial rocks properties:
rocks_start_params={
	'nb_rocks':100,			# number of rocks
	'rocks_min_vol':0.1,		# rocks volume start range
	'rocks_max_vol':0.1,	# rocks volume end range
	'rocks_density':2650.,	# rocks density
	'rocks_min_x':1.,		# rocks initial x position start range
	'rocks_max_x':2.,		# rocks initial x position end range
	'rocks_min_z':5.,		# rocks initial height start range
	'rocks_max_z':8.,		# rocks initial height end range
	'rocks_vx':0.1,			# rocks initial horizontal velocity
	'rocks_vz':-2.,			# rocks initial vertical velocity
	'rocks_angVel':0.		# rocks initial angular velocity
}

# Create a simulation object with all parameters:
s=TwoD.Simulations.Simulation(
	terrain=T,								# the terrain
	rocks_start_params=rocks_start_params,	# the rocks initial properties
	gravity=9.8,							# gravity (note the positive value)
	checkpoints_x=[50,85,205],				# the checkpoints horizontal positions
	checkpoints_angles=[90, 120, 180],		# the checkpoints angles (90 is vertical)
	checkpoints_max_heights=[2, 30, -1],	# the checkpoints heights, negative for semi-infinite
	enable_forest=True
)

s.override_forest_params = True
s.override_trees_density = 400
s.override_trees_dhp_mean = 50
s.override_trees_dhp_std = 1
# s.override_roughness = 0
### LAUNCH SIMULATION ###

#s.rocks_volumes=[2.]*s.nb_rocks #optionnaly tweak the rocks volumes, be carefull not to the change the list lenght !
#s.rocks_start_x=[2.]*s.nb_rocks #optionnaly tweak the rocks start x positions, be carefull not to the change the list lenght !
#s.rocks_start_z=[10.]*s.nb_rocks #optionnaly tweak the rocks start heights, be carefull not to the change the list lenght !

s.run()	#launch the simulation and wait until it is terminated

# uncomment below to store an hdf5 file with detailed trajectories
#s.output.write_to_h5("my_2D_simulation_results.h5")

### DISPLAY ###

#Show matplotlib window
import platrock.GUI.Plot2D as Plot2D

# Draw the terrain
Plot2D.draw_terrain(T)

# Draw the rocks trajectories
Plot2D.plot_sample_trajectories(s,with_contacts=1)

# Show the checkpoints
Plot2D.plot_checkpoints(s)

TwoDShape (Siconos) Model¶

T=TwoDShape.Objects.Terrain("./TwoDShape_terrain.txt")

rocks_start_params={
	'nb_rocks':10,				# number of rocks
	'rocks_min_x':1.,			# rocks initial x position start range
	'rocks_max_x':2.,			# rocks initial x position end range
	'rocks_min_z':5.,			# rocks initial height start range
	'rocks_max_z':8.,			# rocks initial height end range
	'rocks_vx':2,				# rocks initial horizontal velocity
	'rocks_vz':0,				# rocks initial vertical velocity
	'rocks_angVel':0.,			# rocks initial angular velocity
	'random_rocks_ori':True,	# all rocks launched in different orientation (enabling this voids rocks_ori)
	'rocks_ori':45,				# initial ori of the rock
	'rocks_density':2650.,		# rocks density
	'rocks_min_vol':1.,		# rocks volume start range
	'rocks_max_vol':10.,	# rocks volume end range
}

s=TwoDShape.Simulations.Simulation(
	terrain=T,
	name="2DShape-test",
	rocks_start_params=rocks_start_params,
	checkpoints_x=[50,100,221],				# the checkpoints horizontal positions
	checkpoints_angles=[330, 120, 180+35],	# the checkpoints angles (90 is vertical)
	checkpoints_max_heights=[10, 20, 30],	# the checkpoints heights, negative for semi-infinite
)

s.current_rock=TwoDShape.Objects.Random( #a random convex shape
	aspect_ratio=3,
	nbPts=6, #number of vertices to generate
	nb_diff_shapes=3 #the number of times to generate new random shapes along the nb_rocks simulations
)
#s.current_rock=TwoDShape.Objects.Ellipse(aspect_ratio=2,nbPts=6)
#s.current_rock=TwoDShape.Objects.Rectangle(aspect_ratio=1.5)
# s.current_rock=TwoDShape.Objects.PointsList( # manually enter the points of the polygon
# 	rocks_pointslist_string = """
# 		2.5 1.3
# 		3. 1.
# 		2. 1.
# 	""" #NOTE: rocks_pointslist_string can be a points string or a path to a file
# )

#s.rocks_volumes=[2.]*s.nb_rocks #optionnaly tweak the rocks volumes, be carefull not to the change the list lenght !
#s.rocks_start_x=[2.]*s.nb_rocks #optionnaly tweak the rocks start x positions, be carefull not to the change the list lenght !
#s.rocks_start_z=[10.]*s.nb_rocks #optionnaly tweak the rocks start heights, be carefull not to the change the list lenght !

# s.override_rebound_params = True
# s.override_mu = 0.1
# s.override_mu_r = 0.1
# s.override_e = 0
# s.enable_forest = True
# s.export_hdf5 = True

s.run()

#Show matplotlib window
import platrock.GUI.Plot2D as Plot2D

# Draw the terrain
Plot2D.draw_terrain(T)

# Draw the rocks trajectories
Plot2D.plot_sample_trajectories(s,with_contacts=1)

# Show the checkpoints
Plot2D.plot_checkpoints(s)

ThreeD Model (spherical rocks, PlatRock engine)¶

### SETUP ###

# Create the terrain default parameters, which will be used wherever:
#	-there is no polygon on the face
#	-one attribute is not set for the polygon on the face
#	-no geojson is given
default_faces_params={
	"R_n":0.9,
	"R_t":0.9,
	"roughness":0.15,
	"phi":30,
	"v_half":5,
	"bounce_model_number":2
}

# Create a terrain object from a raster file and a geojson for parameters:
T=ThreeD.Objects.Terrain(
	DEM_asc="./dem_5m.asc",							# the raster file
	soil_params_geojson="./soil.geojson",			# the soil geojson with polygons
	forest_params_input_file="./forest.geojson",	# the forest geojson with polygons
	#forest_params_input_file="./trees.xyd",		# an onther way to import forest
	default_faces_params=default_faces_params		# for polygons not covered by the geojson
)

# Generate random forest everywhere in the terrain (should not be used with forest_params_input_file above).
#T.generate_random_forest(200,30,10)	# density, mean dhp, dhp standard deviation

class My_3D_simclass(ThreeD.Simulations.Simulation):
	def before_rock_launch_tasks(self,*args,**kwargs):
		print(self.current_rock_number)
		super().before_rock_launch_tasks(*args,**kwargs)
		# self.current_rock.vel[0] = -50
		# self.current_rock.vel[2] = 50
		# self.current_rock.vel[1] = 2

# Create a simulation object with all parameters:
s=My_3D_simclass(
	terrain=T,											# the terrain
	rocks_start_params_geojson="./block.geojson",		# the rocks initial properties in a geojson
	checkpoints_geojson="./checkpoints.geojson",		# polylines in a geojson for checkpoints
	engines=[	 										# the main loop functions (operations)
		# update the verlet list if necessary:
		ThreeD.Engines.Verlet_update(use_cython=True, dist_factor=5),
		# detect all contacts between the rock and the elements within the verlet lists:
		ThreeD.Engines.Contacts_detector(use_cython=True),
		# Non-smooth contact dynamics interactions for rocks-terrain contacts:
		ThreeD.Engines.Rock_terrain_nscd_basic_contact(),
		# Non-smooth contact dynamics interactions for rocks-trees contacts:
		ThreeD.Engines.Rock_tree_nscd_basic_contact(),
		# move the rock:
		ThreeD.Engines.Nscd_integrator(use_cython=True),
	],
	gravity=9.8,	# gravity (positive)
	enable_forest=False,
)

### LAUNCH SIMULATION ###
#s.rocks_start_params[0]["params"]["rocks_volumes"]=[1.]*10  #optionnaly tweak the rocks volumes for the first start zone, be carefull not to the change the list lenght !
#s.rocks_start_params[1]["params"]["rocks_volumes"]=[2.]*10  #optionnaly tweak the rocks volumes for the second start zone, be carefull not to the change the list lenght !
s.run(GUI=False)

# uncomment below to write an hdf5 file with detailed results
#s.output.write_to_h5("my_3D_simulation_results.h5")

### POSTPROCESSINGS ###

#Create a Postprocessing object, rasterized at 5 meters:
pp=platrock.Common.ThreeDPostprocessings.ThreeDPostprocessing(s)

# Postprocess the data (results will be into the pp object)
pp.run()

#Show the matplotlib map (view from sky of the rasterized terrain):
pp.plot()
pp.plot.draw_terrain(s)
pp.plot.plot_checkpoints(s)

#Optionnaly draw trees:
if(s.enable_forest):
	pp.plot.draw_forest(T)

#Draw a map of rocks count (crossings) over the raster:
pp.plot.draw_rocks_count(pp.raster)

# Velocities are also available:
#pp.plot.draw_mean_vel(pp.raster)

# Kinetic energy too:
#pp.plot.draw_mean_Ec(pp.raster)

# Draw each rock precise trajectory:
pp.plot.draw_sample_trajectories(s,20)

# Uncomment below to output asc files: crossings, velocities, heights
#pp.raster.output_to_asc()

ThreeD Model (parallelepiped rocks, Siconos engine)¶

### SETUP ###
platrock.web_ui = True
import numpy as np
class My_3D_simclass(ThreeDShape.Simulations.Simulation):
	pass
	# def before_rock_launch_tasks(self,*args,**kwargs):
	# 	print(self.current_rock_number)
	# 	self.random_generator=np.random.RandomState(self.current_rock_number)
	# 	super().before_rock_launch_tasks(*args,**kwargs)
		# self.current_rock.vel[0] = -50
		# self.current_rock.vel[2] = 50
		# self.current_rock.vel[1] = 2
# Create the terrain default parameters, which will be used wherever:
#	-there is no polygon on the face
#	-one attribute is not set for the polygon on the face
#	-no geojson is given
default_faces_params={
	"e":0.2,
	"mu":10,
	"mu_r":0.5
}

# Create a terrain object from a raster file and a geojson for parameters:
T=ThreeDShape.Objects.Terrain(
	DEM_asc="./dem_5m.asc",							# the raster file
	params_geojson="./soil.geojson",				# the soil geojson with polygons
	#forest_params_input_file="./forest.geojson",
	default_faces_params=default_faces_params,
)


# Create a simulation object with all parameters:
s=My_3D_simclass(
	terrain=T,												# the terrain
	rocks_start_params_geojson="block.geojson",				# the rocks initial properties in a geojson
	checkpoints_geojson="./checkpoints.geojson",			# polylines in a geojson for checkpoints
	gravity=9.8,											# gravity (positive)
	random_seed = 0
)

# s.override_rebound_params = True
# s.override_e = 0
# s.override_mu = 3
# s.override_mu_r = 0

# LAUNCH SIMULATION ###
s.run(GUI=False)
#s.output.write_to_h5("my_3D_simulation_results.h5")

# POSTPROCESSINGS ###

#Create a Postprocessing object, rasterized at 5 meters:
# pp=platrock.Common.ThreeDPostprocessings.ThreeDPostprocessing(s,5)

## Postprocess the data (results will be into the pp object)
# pp.run()

##Show the matplotlib graph (view from sky of the rasterized terrain):
# pp.plot()
# pp.plot.draw_terrain(s)
# pp.plot.plot_checkpoints(s)

# ### Draw a map of rocks count over the raster:
# #pp.plot.draw_mean_vel(pp.raster)

# pp.plot.draw_rocks_count(pp.raster)

# ## Draw the rocks trajectories:
# pp.plot.draw_sample_trajectories(s)

WebUI¶

To start PlatRock-WebUI on the server or the local machine :

platrock-webui path_to_the_project_dir

This command will launch the webserver, reachable locally with a web-browser at http://127.0.0.1:8080. The path_to_the_project_dir directory will store all simulations and projects informations, it can be initially empty.

Projects Management¶

On the project tab, the left panel is dedicated to project management. The following actions are available: select, add, edit informations, delete, save. On the right tab, all simulations that belong to the currently selected project are displayed. You can either click on a simulation title to display it (hence change to “simulation” tab), or click on one of the small actions icons to achieve quick operations.

TwoD Model¶

Example of a TwoD simulation tab. After you have imported a terrain, you can adjust the parameters thanks to 3 main tables:

rocks start parameters,
checkpoints parameters,
terrain/soil parameters.

Note

To import a terrain you will have to input a well formated text file. Please find a description of this file here or use a template in platrock examples directory.

Parameters zones¶

During the terrain importation process PlatRock will automatically define parameters zones (one zone per color in the terrain parameters table). Consecutive terrain segments are grouped in a zone if they have the exact same parameters set. You can then change the parameter of the whole zone by filling the corresponding line in the parameters table.

Topography editing¶

One can modify the topography by right-clicking one of the terrain points. A contextual menu will appear, allowing to:

Move an existing point
Remove an existing point
Add a new point
Split a parameters zone into two zones

Parameters overrides¶

It is possible to override (replace) the parameters of the whole terrain by specific values. Tick the “Force rebound parameters everywhere” checkbox to activate a new table, then enter the desired parameters. They will be effective for the next runs, but the original terrain parameters can still be restaured by unticking the checkbox.

Forest parameters¶

To take forest into consideration for the rockfall simulation, tick the “enable forest” checkbox. Then the forest parameters can either be:

set into the parameters zones if the forest characteristics are not homegeneous ;
set globally for the whole terrain.

TwoDShape Model¶

The TwoDShape simulation tab is similar to the TwoD tab, only some parameters are different.

The imported terrain file should follow the template that can be found in the examples directory. Also, the rocks start parameters include some options to define the rocks shape:

ThreeD Models¶

The simulation tab for ThreeD simulations is slightly different from the TwoD ones. It shares the same toolbar and the main layout, but the parameters handling is different due to their nature:

the parameters applies to polygons (projected on the terrain);
the checkpoints are polylines.

Terrain importation¶

Click “import terrain” to show the corresponding pop-up in which some files will be requested. Each line in the pop-up corresponds to one file, and example files can be find in the examples directory. Hover the lines to get more informations on the requested files specification:

DEM (*.asc): Digital elevation model in ESRI ASCII grid format.
Rocks parameters (*.geojson): Polygons data into GeoJSON container with attributes: number, z, vz, (volume || (length, width, height)).
Soil parameters (*.geojson): Polygons data into GeoJSON container with attributes (depending on rebound types): R_n, R_t, roughness, bounce_mod, phi, v_half, e, mu, mu_r.
Forest parameters (*.geojson, *.xyd): xyd file OR polygons data into GeoJSON container with attributes: density, dhp_mean, dhp_std.
Checkpoints (*.geojson): Multilines data into GeoJSON container.

The GeoJSON files can be created with QGIS. In case of rocks, soil and forest parameters, polygons or multipolygons should be created and each polygon must contain the corresponding parameters as meta-data. Checkpoints must be multilines, without meta-data.

Once the terrain and the parameters are imported, they will show up –and can be modified– in the main simulation tab. The edition can be done in the same fashion as in TwoD models, and the polygons/multilines will appear as overlays in the graphical view of the terrain.

Forest parameters¶

On the terrain importation popup, one can note that the forest can either be a GeoJSON file (in which case the trees will be generated based on the polygons parameters), or a xyd file. In the latter case, a basic text file with trees positions and diameters is expected.

Simulation type selection¶

The selection between spherical model (builtin physical engine) and the polygonal model (siconos engine, which can deal with rocks shape) can be done thanks to a dropdown menu. Note that the corresponding parameters must be set to be able to select a model, otherwise its selection will be disabled.

_images/WebUI_ThreeD_General_ModelSelection.svg

Simulations results overview¶

Once the simulation is finished, the graphical view of the terrain will be updated with:

a sample of trajectories of the rocks ;
various output rasters.

_images/WebUI_ThreeD_General_Rasters.svg

The shown output raster data can be selected in the left-side dropdown menu. To improve their visibility, the parameters polygons and checkpoints can be hidden thanks to buttons on the right side of the graph.

Getting Started¶

INSTALLATIONS¶

Prerequisites¶

Using pipx¶

Using poetry¶

Optional modules¶

Documentation creation¶

PlatRock CLI¶

TwoD Model¶

TwoDShape (Siconos) Model¶

ThreeD Model (spherical rocks, PlatRock engine)¶

ThreeD Model (parallelepiped rocks, Siconos engine)¶

WebUI¶

Projects Management¶

Simulations Toolbar¶

TwoD Model¶

Parameters zones¶

Topography editing¶

Parameters overrides¶

Forest parameters¶

TwoDShape Model¶

ThreeD Models¶

Terrain importation¶

Forest parameters¶

Simulation type selection¶

Simulations results overview¶