2 Copyright (C) 2015-2016 EDF
4 This file is part of SALOME HYDRO module.
6 SALOME HYDRO module is free software: you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation, either version 3 of the License, or
9 (at your option) any later version.
11 SALOME HYDRO module is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with SALOME HYDRO module. If not, see <http://www.gnu.org/licenses/>.
19 #########################################
21 #########################################
23 * **Georeferencing**: The projection system depends on the geographic location of the study
24 and must be selected and stored to facilitate study follow up. The reference projection
25 in metropolitan France is Lambert 93.
26 **All data imported into SALOME HYDRO must be in the same (unique) reference frame.**
27 SALOME HYDRO does not propose a coordinate converter.
29 * **Local reference point**: The Cartesian coordinate values, **always expressed in metres**,
30 in a given projection system often represent very large numbers.
31 The Lambert 93 coordinates of a point in continental France, for example,
32 are of the order (400 000, 6 500 000).
33 A simple shift of the origin results in a local reference point,
34 reducing the size of the numbers to be handled.
35 To improve numerical precision in the different study steps (geometry, meshing, simulation, etc.),
36 **the use of a local reference point is highly recommended.**
37 SALOME HYDRO displays coordinates in both coordinate systems (local and global)
38 and automatically applies the translations on import and export.
40 * **Constraint line**: Line used to support and structure the mesh.
41 In SALOME, these lines are defined in the Geometry (GEOM module) as "edge".
42 Not every line created in the HYDRO module will necessarily be kept in the geometry.
44 * **Hydraulic axis**: The orientation of river flow.
45 Often obtained by connecting the low points of a succession of cross profiles.
47 * **Crest line**: Line joining the highest points of an embankment.
49 * **Partition**: This is a segmentation of the space into **regions** and **zones**.
50 The concepts of zones and regions are introduced in the practice exercise to follow.
51 The boundaries of a region correspond to the constraint lines of the mesh.
52 The regions can be divided into several zones with each zone corresponding
53 to a computational mode for the bathymetry.
55 * **Land Cover Map** : A map describing the region of interest, giving the kind of land cover
56 (for instance: forest, cultivated area, town...), following the *Corine Land Cover* classification.
58 * **Strickler table** : Gives the *Stricker coefficient* (friction)
59 for each kind of land cover (entry of the *Corine Land Cover* classification).
60 These coefficients must be redefined on each case, following the type of calculation.
63 ################################################
64 Main steps in a study using SALOME-HYDRO
65 ################################################
67 .. |etapesEtude| image:: /../_static/etapesEtude.png
70 SALOME contains all the modules needed to start a Telemac study.
72 The SALOME-HYDRO application gathers the HYDRO and HYDRO-SOLVER modules,
73 which form the heart of the SALOME system, onto a single platform that integrates the Telemac2D system.
75 The following figure summarises the general steps and the tools used within the SALOME platform.
79 The study will be carried out using the following SALOME modules:
93 * HYDRO: images and/or plans are imported
95 * HYDRO: contour lines of **natural features** (rivers, islands, etc.) and **artificial features**
96 (embankments, channels, obstacles, etc.) are created or imported
98 * HYDRO: bathymetry / altitude fields or series of river profiles are loaded
100 * HYDRO: object elements representing the natural and artificial features are constructed,
102 * HYDRO : a Land Cover Map and a Strickler table are created or imported
104 * HYDRO: a **calculation case** is created by selecting the objects relevant to the case;
105 the **zones** (each associated to a specific method of bathymetry calculation) are grouped into **regions**
106 (the boundaries of which correspond to mesh constraint lines; these are the faces of the final SALOME geometry)
108 * HYDRO: the case is exported to GEOM
110 * GEOM: the case is taken up in GEOM to complete the identification of the groups associated
111 to the different regions of the domain and the boundary conditions
113 * SMESH: the mesh assumptions ("hypotheses" in the dialogs) and algorithms are chosen,
114 the mesh is calculated and the corresponding MED file is exported
116 * HYDROSOLVER: the Z interpolation Python script giving z coordinates on mesh nodes
117 from the MED file and the calculation case is generated and executed
119 * HYDROSOLVER: the Strickler Python script giving Strickler coefficients on mesh nodes
120 from the MED file and the calculation case is generated and executed
122 * HYDROSOLVER: the physical and numerical parameters of the simulation are defined (case file)
124 * HYDROSOLVER: the calculation is executed
126 * PARAVIS: the results are analysed
128 The sequential logic of the operating steps in the HYDRO module itself is as follows
129 (see the different types of manipulated objects in the tree on the left):
133 Satellite imagery and/or maps of the study area are used to locate the absolute and relative positions of the elements to be represented in the mesh. These images must be georeferenced in the same system of coordinates
134 as all the data (for example, Lambert 93). This may, for instance, be a geoportal screenshot.
138 The bathymetries in the form of point cloud and/or cross profile datasets that constitute the terrain model
139 on which the mesh will be based are imported into the project.
143 Polylines (imported into and/or created in SALOME) are used to define the contours of the natural and artificial
144 objects that will intervene in the calculation case. These lines are closed in the general case and some of them will form the mesh constraint lines. Splined polylines permit to define contours without there being any necessity
145 for the mesh based on them to use the points on the line: only the general shape counts. Lines can be drawn with
146 the mouse or imported from a file.Les polylignes (importées et/ou construites dans SALOME) permettent de définir
147 les contours des différents objets
151 These are composite elements comprising, for example, land surfaces, islands, lakes, etc.
152 A bathymetry can generally be associated to them.
154 * ARTIFICIAL OBJECTS:
156 This step involves building structural elements, such as embankments, canals and channels of known geometry.
158 * CALCULATION CASES :
160 When the calculation case is defined, the objects to be meshed are selected and any issues concerning
161 the bathymetric coverage (overlaps/gaps) are resolved.
163 This is a description of a typical sequence;
164 moving backwards and forwards between the various steps is perfectly possible and will certainly occur.
166 Preliminary data requirements
167 =============================
169 * For the image files: have map or photo background image files and have identified in the working system
170 the coordinates of 2 or 3 points that are well-distributed over the image (far enough apart to ensure high precision).
171 With three points, an affine transformation of the image can be applied in the unlikely case that the latter is not
172 consistent with direct vertical (orthographic) projection.
174 * Have bathymetry data available in ASCII format.
176 For the moment, the bathymetry files must have either an .xyz (3 columns x,y,z) or an .asc extension
177 (raster grid-type format, as provided in the IGN Alti database, for example).
179 * If cross profiles are available for the river, they can be given either on xyz format with an empty line
180 between each profile, or on SinusX format (see description below).
185 Plans, maps and photos are imported into the Images folder of the study tree in the Hydro module.
186 The idea is to work from satellite images and/or maps of the area to be meshed,
187 georeferenced in the same system of coordinates as all the data (Lambert93 for example).
188 It is possible to find the intersection of two images, to fusion the images and to clip an image using a polyline.
190 Image manipulation is introduced in the subsequent exercise.
192 Selection of a local reference point
193 ====================================
195 **It is strongly advised to change the origin of the local coordinate system**
196 to avoid having to deal with very large numbers and to increase the calculation precision,
197 particularly for the mesh generation.
199 To do so, the *Hydro/change local CS* menu must be used to enter the coordinates of the new origin.
204 The procedure is explained in the exercise section.
206 * **Note** : If the altitudes are less than 0, the bathymetry may be hidden by the maps or photos
207 (which are at Z = 0 by convention).
208 If the bathymetry needs to be seen at the same time as the images, this can be achieved either
209 by switching to the bottom view, or by editing the bathymetry
210 ("edit imported bathymetry" context menu) to invert the Z values while verifying for example
211 the alignment of the maps and the bathymetry
212 (and not forgetting to revert to the original Z values afterwards!).
214 Retrieving bathymetry data from old mesh
215 ----------------------------------------
217 Precise details of the procedure for the following operations remain to be finalized.
218 The Python scripts mentioned below are not provided with this version;
219 they require adaptation on a case by case basis.
221 * It is possible to retrieve an old mesh from a case study by converting the data from selafin format (.slf)
222 to .med format (dedicated format for the Salomé platform in general),
223 using the integrated file converter in SALOME-HYDRO
225 * Based on the old mesh, it may be necessary to apply a translation (for example +2,000,000)
226 to the y-position of the nodes to switch to a known georeferencing system
227 (for example LambertIIEtendu).
229 * The bathymetry (depth field Z) is then retrieved using a Python script which creates an .xyz file
230 (x node position, y node position, associated Z field).
232 * This .xyz file is converted into Lambert 93 using the Circé freeware (under Windows).
234 * The edge node positions are then retrieved using a Python script that traverses the nodes,
235 determines whether they are at the boundary edge and creates a file in which each boundary retrieved
236 is formatted for direct import into the HYDRO module.
238 * This procedure enables isolating the contour of the site, bridge piers and islands, if there are any.
240 Importing line-type objects
241 ===========================
243 The SinusX (ASCII) format described in the appendix permits describing several line and profile types.
244 Files in this format that respect the conventions detailed in the appendix can be imported into SALOME HYDRO.
249 Definition : lines in the XY plane, generally used to define contours and zones.
254 There are two types of profile: georeferenced or not.
256 Georeferenced profiles are defined in XYZ coordinates and others in XZ (XY).
257 Utility: embankment, canal, channel and river sections.
259 A single cross-section is defined for a channel, canal or an embankment and a series of profiles for a river.
261 For an embankment, the value Z=0 corresponds to the crest line, for a channel it is the bottom line.
263 Only symmetrical profiles (in relation to the crest or bottom line) are considered.
268 River described by a series of cross profiles, ordered along an upstream-downstream line which passes
269 through these profiles. This line can be the hydraulic axis, though this is not compulsory.
271 The stream files can be XYZ files in which each profile is separated by an empty line.
276 Polyline-type contours are needed to create the geometry. They are used to construct the terrain model,
277 islands and the minor river bed, as well as embankments, channels, canals, roads and so forth.
279 The bathymetry or maps can be displayed when entering contours as an orientation guide.
284 There are two types of polyline in SALOME:
286 * Polylines (broken lines composed of a series of straight segments, to describe a geometric object)
288 * Splines (set of arcs that form a smooth parametric curve with a continuous derivative,
289 to describe a natural curve, which will adapt to the fineness of the discretisation).
291 The use of splines enables contours to be defined without any need for the mesh based on these
292 to adhere to all the points on the line: only the general shape counts.
294 The procedure is detailed in the exercise below.
296 it is possible to build lines mixing polylines and splines.
297 See below the chapter on polyline manipulation.
299 Embankment or channel profiles
300 ------------------------------
302 These types of profile can be imported or drawn.
303 The drawing procedure is detailed in the practical exercise.
308 Only the import of these profiles is supported.
310 Creating "natural" objects of the "immersible zone" type
311 ========================================================
313 An **immersible zone** will be meshed. Dry islands can be excluded from the mesh.
314 In SALOME HYDRO, this type of island is differentiated from the others by deactivating the Submersible attribute.
316 Creating an immersible zone consists in the creation of a geometric face from one of the contours previously drawn.
317 This is achieved by entering the polyline (compulsory) on which the face will be built
318 and the desired bathymetry (optional) to associate with this geographical zone.
320 * **Note**: the bathymetry is optional when creating natural objects, particularly islands.
322 * **Note**: It is possible to change the display order of the different natural and artificial objects,
323 which are all by convention in the z=0 plane, to put the small objects "above".
325 Creating "stream" type "natural" objects
326 ========================================
328 The procedure is explained in detail in a later chapter.
330 Creating embankment or channel-type "artificial" objects
331 ========================================================
333 Details of the operating procedure are provided in a later chapter.
338 Complex geometric objects (buildings, etc.) imported from GEOM to constitute the dry zones
339 ("islands" or assimilated). These objects must be put into the local reference frame coordinates
340 before importing them.
342 Strickler coefficient tables, Land Cover maps
343 =============================================
345 It is possible to build a Strickler coefficents map (friction) on the domain of interest.
347 Maps giving the type of soils (Land Cover Map) can be obtained on various websites.
348 For instance, with a Geographical Information System tool like *Qgis*, "Corine Land Cover" maps
349 can be downloaded and edited.
350 These maps follow a standard classification of soils.
352 For each study, the Strickler coefficents associated to the Land Cover Map should be adapted, following each type of soil
355 The Land Cover Maps are either imported from Qgis or created from scratch in SALOME-HYDRO.
356 The Land Cover Maps can always be edited in SALOME-HYDRO: add, suppress, regroup, modify zones...
358 Calculation case set-up
359 =======================
361 When configuring a calculation case, it is possible to select only some of the previously defined objects.
362 The choice depends on the case complexity and several cases at different levels of complexity
363 (details such as bridge piers, for example, being accounted for or not) can be created from the same object base.
365 The domain is enclosed with a given polygonal contour defining its boundaries.
367 The overlapping of different objects creates "conflicts" between zones for which choices have to be made
368 in terms of the bathymetry computation.
370 Splitting the overlapping objects into different zones constitutes the **partition** or segmentation operation.
372 Zones may be regrouped into homogeneous regions in the target mesh structure, to avoid the use of contours
373 that we do not want to keep as constraint lines.
375 In the calculation case, specific lines onto which the boundary conditions will be applied can be identified.
377 The result is exported into the geometry module.
379 The procedure is explained in detail in the practical exercise.
381 Geometry: GEOM module
382 =====================
384 Once the calculation case is completed and exported, it appears in the GEOM module.
386 This module must be activated to be able to view and modify the exported case.
388 In GEOM, the calculation case is seen under the name <case name>_N to which is attached
389 the contour(s) selected when the calculation case was defined.
391 Certain mesh parts may need to be identified:
393 * Faces: to mesh certain zones in a different way
395 * Segments: to define the boundary conditions.
397 The procedure is explained in detail in the practical exercise.
399 * **Note**: The geometry module may be used to define a certain number of mesh constraints; for example,
400 fixed points can defined in the mesh (which could for instance correspond to measurement points).
401 **Any modification to the geometry results in the creation of a new object and the loss of the groups
402 defined in the initial object. Groups must therefore be created last, on the final geometry,
403 and modifications that provoke the loss of the HYDRO module automatic definitions should be avoided,
404 if and whenever possible.**
409 Users should refer to the SALOME training materials for guidance on the use of the SMESH Module.
411 The procedure for SALOME HYDRO is detailed in the exercise below.
419 In hydrodynamics, it is vital to know the bathymetry value at each computational node.
421 The bathymetry is calculated zone by zone, with each zone associated to a specific method of calculation:
425 * From river profiles
427 * From embankments and canal/channel axes and cross-sections
429 * From the CAD of the obstacles
431 For the point clouds, a script is available in version 1.0 enabling to interpolate the bathymetry onto the mesh.
432 This script uses an algorithm which takes either the Z value of the closest point or the Z value interpolated
433 on a prior triangulation of the data points.
435 The procedure is explained in detail in the practical exercise.
437 Input of physical/numerical data for TELEMAC
438 ============================================
440 The HYDROSOLVER module is used to input these parameters and to assemble the calculation case.
442 Description of the boundary conditions
443 --------------------------------------
445 Each boundary condition region corresponds to a named group in the mesh.
446 The types of boundary condition associated to a group are defined in a file whose syntax is given
447 in the practical example.
449 Dans le module HYDROSOLVER, un outil permet d'associer des types de condition limites aux groupes concernés ans le maillage,
451 Editing the Case file
452 ---------------------
454 The calculation parameters are defined in the Case file with the TELEMAC 2D syntax
455 (using either EFICAS editor provided in GYDROSOLVER module or a standard text editor).
457 List of files needed by TELEMAC 2D
458 ----------------------------------
460 To be completed, see the example case.
462 Starting and monitoring the simulation
463 ======================================
465 The HYDROSOLVER module is used to start TELEMAC 2D.
467 The procedure is explained in the example case.
472 The PARAVIS module is used to exploit the results.
473 Reference can be made to the SALOME training materials for further information on the use of the PARAVIS module.