src/Tools/padder/doc/input/padder_userguide.doc

   1 /*!
   2
   3 \page padder_userguide_page Use the padder SMESH Plugin
   4
   5 -# \ref S1_PADDER
   6 -# \ref S2_PADDER
   7 -# \ref S3_PADDER
   8
   9 \section S1_PADDER The SpherePadder Algorithm
  10
  11 SpherePadder is a geometric algorithm that creates a set of rigid
  12 spherical particles of different sizes called a "discrete element
  13 mesh". The centroid positions of particles are randomly generated by a
  14 "disordering" technique described in [1] that provides a polydisperse
  15 assembly with a particular size distribution. The spheres are
  16 positioned or “padded” into a tetrahedral mesh, which must be
  17 generated first. As illustrated below, SpherePadder creates a Discrete
  18 Element (DE) assembly in seven steps (see [1] for details):
  19
  20 \image html padder_image01.png
  21
  22 In order to increase the density of the whole packing and to fill
  23 spheres in the gaps close to the mesh boundaries (created by removing
  24 boundary spheres), SpherePadder detect `void spaces' where new spheres
  25 could be added by applying a particular geometric procedure, using
  26 tetrahedra resulting from a tridimensional Delaunay triangulation
  27 built with the sphere centers. That triangulation is generated by
  28 using the CGAL library [2].
  29
  30 DE meshes generated by SpherePadder algorithm are used in EUROPLEXUS
  31 fast dynamics software simulations [3] to model the discontinuous
  32 behaviour (fractures, fragmentation) of reinforced concrete structures
  33 under severe dynamic loads such as impacts or explosions. The
  34 characteristic size of elements does not have to be representative of
  35 concrete constituents, such as granulars or cement matrix, since the
  36 aim is to reproduce the dynamic behaviour of the simulated material at
  37 the macroscopic scale.
  38
  39 To generate DE mesh for a reinforced concrete structure, one should
  40 supply a single tetrahedral mesh for concrete and as many segment-type
  41 1D meshes as groups of steel reinforcement bars of different
  42 diameters. The size (length) of segment-type steel reinforcement
  43 elements should correspond to the modelled bar’s
  44 diameter. SpherePadder algorithm will create steel discrete elements
  45 by using the segment’s length as the DE diameter.
  46
  47 Warning: The User should control that all steel bars of a given
  48 diameter in a mesh belong to the same mesh group, and that different
  49 steel bar groups do not use the same diameter.
  50
  51 \image html padder_image02.png
  52
  53 If steel mesh is not provided, a pure concrete DE mesh is generated.
  54
  55 In MED representation, DE meshes are described by using MED_BALL type
  56 structural elements. Each MED_BALL element is defined by its centroid
  57 location and a diameter.
  58
  59 Written in C++, SpherePadder is free software licensed under the terms
  60 of the GNU General Public License.
  61
  62 Bibliography:
  63 - [1] J.-F.Jerier, V.Richefeu, D.Imbault, F.-V. Donzé, “Packing spherical discrete elements for large scale simulations”, Computer Methods in Applied Mechanics and Engineering 199 (2010) 1668–1676.
  64 - [2] CGAL, Computational Geometry Algorithms Library. https://gforge.inria.fr.
  65 - [3] EUROPLEXUS: a computer program for the finite element simulation of fluid–structure systems under transient dynamic loading. http://europlexus.jrc.ec.europa.eu, (User’s Manual).
  66
  67 \section S2_PADDER The SpherePadder SALOME plugin
  68
  69 The SpherePadder algorithm is implemented as an external software
  70 program. This external program is integrated in the SMESH module as a
  71 SALOME plugin that manage the execution of the SpherePadder program
  72 from within the SALOME framework. This section illustrates how to use
  73 this plugin to create a discrete element mesh.
  74
  75 In this example, we consider a concrete piece with a single
  76 reinforcement bars group. Thus, two standard (Finite Element type)
  77 meshes have been created and published in the study, the first one
  78 named “concrete”, and second one named "ferrail", for the steel bars
  79 part:
  80
  81 \image html padder_image03.png
  82
  83 The SpherePadder plugin can be activated in the SMESH plugins menu, as
  84 illustrated on the figure below:
  85
  86 \image html padder_image04.png
  87
  88 When clicking on the "PADDER mesher" item, the graphical interface of
  89 the SpherePadder plugin appears:
  90
  91 \image html padder_image05.png
  92
  93 This interface invites you to specify input data by pressing the
  94 button "Input". This command opens the Input dialog box allowing to
  95 specify the list and the type of selected meshes (to be chosen between
  96 "concrete" and "steelbar" using the combobox on the right side of the
  97 input line):
  98
  99 \image html padder_image06.png
 100
 101 In the figure below, the mesh with name "concrete" has been selected
 102 in the study and added to the list of the input file as a "concrete
 103 mesh". First, you have to choose the mesh in the dialog box using the
 104 rounded arrow icon, then specify for this mesh a group name which will
 105 be published in the final DE mesh, and finally click on the "Add"
 106 icon:
 107
 108 \image html padder_image07.png
 109
 110 Then, the mesh with name "ferrail" is selected and added to the list
 111 as a "steelbar mesh":
 112
 113 \image html padder_image08.png
 114
 115 The input dialog box has to be validated to return to the main plugin
 116 interface. The "Compute" button is now enabled, indicating that the
 117 problem is ready to be computed:
 118
 119 \image html padder_image09.png
 120
 121 The command "Compute" starts the job run. The progression can be
 122 requested using the command "Refresh". In the figure below, the job is
 123 still running:
 124
 125 \image html padder_image10.png
 126
 127 Finally, the job is finished and the result is ready to be published
 128 in the SALOME study:
 129
 130 \image html padder_image11.png
 131
 132 Click on the button "Publish" to import the resulting MED file into
 133 SMESH and publish the resulting mesh in the SALOME study:
 134
 135 \image html padder_image12.png
 136
 137 Note that the final ED mesh contains as many groups as the input
 138 meshes. Their names have been specified in the input dialog. For the
 139 moment, the DE mesh is shown as a set of points of equal size:
 140
 141 \image html padder_image13.png
 142
 143 In the next version, the PointSprite (sphere-like) mode will be used
 144 to show the MED_BALL elements with their real diameters. Then the
 145 above example should look like on the following capture (realized in
 146 module GEOM for illustration):
 147
 148 \image html padder_sphererendering.png
 149
 150 \section S3_PADDER Configuring the SpherePadder SALOME plugin
 151
 152 The configuration of the plugin consists in specifying the location of
 153 the padder executable program (padder.exe) and its runtime environment
 154 file (padder.env). This configuration is automatically done at
 155 installation process of the SALOME plateform, on the basis of the
 156 environment variable PADDERHOME that localizes the installation root
 157 of the SpherePadder external program. This installation process
 158 creates a configuration file padder.cfg located in the folder
 159 <SMESH_ROOT_DIR>/share/salome/plugins/smesh, where <SMESH_ROOT_DIR> is
 160 the installation root directory of the SMESH module.
 161
 162 In the case where you have to specify a different configuration than
 163 the generated configuration, you must edit the file padder.cfg. This
 164 file defines a list of computing resources, and at least a local
 165 resource (a padder program working on your local host), and a remote
 166 resource (a padder program working on a remote host):
 167
 168 \code
 169 # This section specify the configurations to be used respectively for
 170 # the local execution and the remote execution. The value for 'local'
 171 # and 'remote' keys must be the name of a configuration section in
 172 # this file. The default key must specify a value between "local" or
 173 # "remote" to indicate the user preference.
 174 [resources]
 175 local   = localhost
 176 remote  = nepal
 177
 178 [preferences]
 179 defaultres = local
 180
 181 # The following sections defines the available configurations.
 182 # The name of the section can be choosen arbitrary. But the value of
 183 # the resname key MUST be the name of a SALOME resource defined in the
 184 # catalog of resources (CatalogResources.xml).
 185
 186 # For each section:
 187 # - resname : the name of the SALOME resource to be used in this configuration
 188 # - binpath : the path to the padder executable program on this resource
 189 # - envpath : the path to the environment file on this resource
 190 [localhost]
 191 resname = localhost
 192 binpath = /home/.programs/salome/workspace/V6_4_BR/SMESH/install/share/salome/resources/smesh/padderexe/padder.exe
 193 envpath = /home/.programs/salome/workspace/V6_4_BR/SMESH/install/share/salome/resources/smesh/padderexe/envPadder.sh
 194
 195 [nepal]
 196 resname = nepal@nepal
 197 binpath = /usr/local/bin/padder.exe
 198 envpath = /usr/local/share/envPadder.sh
 199 \endcode
 200
 201 The resource labels (localhost and nepal in the above example) must
 202 correspond to existing computing resources of SALOME. These resources
 203 are specified in the SALOME configuration CatalogResources.xml,
 204 located at the root directory of your SALOME application. The
 205 resources catalog is supposed to contain at least the localhost
 206 resource of type 'ssh' defined as follow:
 207
 208 \code
 209 <!DOCTYPE ResourcesCatalog>
 210 <resources>
 211
 212    <!-- Generic configuration that should works on every workstation -->
 213    <machine name="localhost" hostname="localhost"
 214             protocol="ssh" batch="ssh_batch"
 215             memInMB="500" CPUFreqMHz="0" nbOfNodes="1" nbOfProcPerNode="1"/>
 216
 217 </resources>
 218 \endcode
 219
 220 Note that these SALOME computing resources can be graphically edited
 221 using the JOBMANAGER module (see JOBMANAGER documentation).
 222
 223 The typical error message when trying to use the padder plugin while
 224 the localhost resource is not correctly defined is :
 225
 226 \code
 227 ERR: the job with jobid = 0 can't be started
 228 ERR: No batchmanager for that cluster - Bad batch description of the resource"
 229 \endcode
 230
 231 This error message is display in the graphical interface of the plugin
 232 when you request a computing of your mesh:
 233
 234 \image html padder_error_noresource.png
 235
 236 Another typical error when using the padder plugin is due to the ssh
 237 configuration between your client host and the execution host:
 238
 239 \code
 240 ERR: the job with jobid = 0 can't be started
 241 ERR: Error of connection on remote host ! status = 65280
 242 \endcode
 243
 244 This error message is display in the graphical interface of the plugin
 245 when you request a computing of your mesh:
 246
 247 \image html padder_error_noconnection.png
 248
 249 The underlying batch system for executing padder jobs is based on a
 250 ssh communication between the client local host and the execution host
 251 (see the protocol specified in the CatalogResources.xml file above),
 252 even if the executive host is your local host (i.e. the same as the
 253 client host). Then, a ssh connection must be configured so that the
 254 underlying batch system could work properly, even between your local
 255 host and itself. The configuration could be done using a set of
 256 instruction as follow in a shell terminal (see ssh documentation for
 257 details):
 258
 259 \code
 260 ssh-keygen
 261 ssh-copy-id -i ~/.ssh/id_rsa.pub <username>@<hostname>
 262 \endcode
 263
 264 You can check the configuration by testing that you can connect to the
 265 host <hostname> with the login <username> without being asked a
 266 password:
 267
 268 \code
 269 ssh <username>@<hostname>
 270 \endcode
 271
 272 */