Update documentation of padder mesher

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

@@ -6,96 +6,84 @@
 -# \ref S2_PADDER
 -# \ref S3_PADDER
 
-\section S1_PADDER The PADDER Algorithm
+\section S1_PADDER The SpherePadder Algorithm
 
-PADDER is an algorithm that creates a set of particules called a "discrete mesh".
-The particules are characterized by a location in space and a weight that can be considered
-as the radius of a sphere whose center is the location of the particule.
+SpherePadder is a geometric algorithm that creates a set of rigid spherical particles of different sizes called a "discrete element mesh". The centroid positions of particles are randomly generated by a "disordering" technique described in [1] that provides a polydisperse assembly with a particular size distribution. The spheres are positioned or “padded” into a tetrahedral mesh, which must be generated first. As illustrated below, SpherePadder creates a Discrete Element (DE) assembly in seven steps (see [1] for details):
 
-Discrete meshes are typically used to modelize civil components in rapid dynamic
-computation problems (seisms, chocs). These components consists in concrete parts
-embedding steal bares for reinforcement. These parts are input to the algorithm
-as standard finite elements meshes. The cells of theses meshes drive the location
-and sizing of particules.
+\image html padder_image01.png
 
-In the med representation, a discrete mesh is described as MED_BALL elements.
-A MED_BALL element is defined by a location and a radius.
+In order to increase the density of the whole packing and to fill spheres in the gaps close to the mesh boundaries (created by removing boundary spheres), SpherePadder detect `void spaces' where new spheres could be added by applying a particular geometric procedure, using tetrahedra resulting from a tridimensional Delaunay triangulation built with the sphere centers. That triangulation is generated by using the CGAL library [2].
 
-\section S2_PADDER The PADDER SALOME plugin
+DE meshes generated by SpherePadder algorithm are used in EUROPLEXUS fast dynamics software simulations [3] to model the discontinuous behaviour (fractures, fragmentation) of reinforced concrete structures under severe dynamic loads such as impacts or explosions. The characteristic size of elements does not have to be representative of concrete constituents, such as granulars or cement matrix, since the aim is to reproduce the dynamic behaviour of the simulated material at the macroscopic scale.
 
-The PADDER algoritm is integrated in the module SMESH as a SALOME
-plugin. This section illustrates how to use this plugin to create a
-discrete mesh.
+To generate DE mesh for a reinforced concrete structure, one should supply a single tetrahedral mesh for concrete and as many segment-type 1D meshes as groups of steel reinforcement bars of different diameters. The size (length) of segment-type steel reinforcement elements should correspond to the modelled bar’s diameter. SpherePadder algorithm will create steel discrete elements by using the segment’s length as the DE diameter. 
 
-In this example, we suppose that two standard meshes (Finite Elements
-Meshes) have been created and publish in the study to modelize the
-concrete part (here with the name "concrete") and the steal bars part
-(here with the name "ferrail"):
+Warning: The User should control that all steel bars of a given diameter in a mesh belong to the same mesh group, and that different steel bar groups do not use the same diameter.
 
-\image html SMESH_spadder_start.png
+\image html padder_image02.png
 
-The PADDER plugin can be invoked from the SMESH plugins menu, as
-illustrated on the figure below:
+If steel mesh is not provided, a pure concrete DE mesh is generated.
 
-\image html SMESH_spadder_menu.png
+In MED representation, DE meshes are described by using MED_BALL type structural elements. Each MED_BALL element is defined by its centroid location and a diameter.
 
-When you clic on the "PADDER mesher" item, the graphical interface of
-the PADDER plugin appears:
+Written in C++, SpherePadder is free software licensed under the terms of the GNU General Public License.
 
-\image html SMESH_spadder_plugindialog_start.png
+Bibliography:
+- [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.
+- [2] CGAL, Computational Geometry Algorithms Library. https://gforge.inria.fr.
+- [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).
 
-This interface invites you to specify input data by pressing the button
-"Input". This command opens the Input dialog box to specify the list
-of meshes and the type of the selected meshes (to be choosen between
-"concrete" or "steelbar" using the combobox on the right side of the
-input line):
+\section S2_PADDER The SpherePadder SALOME plugin
 
-\image html SMESH_spadder_inputdialog_start.png
+The SpherePadder algorithm is implemented in the SMESH module as a SALOME plugin. This section illustrates how to use this plugin to create a discrete element mesh.
 
-In the figure below, the mesh with name "concrete" has been selected
-in the study and added in the list of input file as a "concrete
-mesh". You have to input the mesh in the dialog using the rounded
-arrow icon, then specify a group name (the name of the group of
-MED_BALL created for this mesh in the resulting mesh), and finnaly
-clic on the "Add" icon:
+In this example, we consider a concrete piece with a single reinforcement bars group. Thus, two standard (Finite Element type) meshes have been created and published in the study, the first one named “concrete”, and second one named "ferrail", for the steel bars part:
 
-\image html SMESH_spadder_inputdialog_concrete.png
+\image html padder_image03.png
 
-Then, the mesh with name "ferrail" is selected and added to the list
-as a "steelbar mesh":
+The SpherePadder plugin can be activated in the SMESH plugins menu, as illustrated on the figure below:
 
-\image html SMESH_spadder_inputdialog_steelbar.png
+\image html padder_image04.png
 
-The input dialog box can be validated toreturn to the main plugin
-interface. The "Compute" button is now enable, indicating that the
-problem is ready to be computed:
+When clicking on the "PADDER mesher" item, the graphical interface of the SpherePadder plugin appears:
 
-\image html SMESH_spadder_plugindialog_compute_ready.png
+\image html padder_image05.png
 
-The command "Compute" start the job. The progression can be requested
-using the command "Refresh". In the figure below, the job is still
-running:
+This interface invites you to specify input data by pressing the button "Input". This command opens the Input dialog box allowing to specify the list and the type of selected meshes (to be chosen between "concrete" and "steelbar" using the combobox on the right side of the input line):
 
-\image html SMESH_spadder_plugindialog_compute_running.png
+\image html padder_image06.png
 
-Finally, the job is finished and the result is ready to be published
-in the SALOME study:
+In the figure below, the mesh with name "concrete" has been selected in the study and added to the list of the input file as a "concrete mesh". First, you have to choose the mesh in the dialog box using the rounded arrow icon, then specify for this mesh a group name which will be published in the final DE mesh, and finally click on the "Add" icon:
 
-\image html SMESH_spadder_plugindialog_compute_finished.png
+\image html padder_image07.png
 
-Clic on the command "Publish" to explicitly import the resulting med
-file in SMESH and published the resulting mesh in the SALOME study:
+Then, the mesh with name "ferrail" is selected and added to the list as a "steelbar mesh":
 
-\image html SMESH_spadder_plugindialog_published.png
+\image html padder_image08.png
 
-Note that this mesh contains one group for each of the input mesh. A
-group with the name specified in the input dialog has been defined for
-the set of MED_BALL created from the corresponding input mesh:
+The input dialog box has to be validated to return to the main plugin interface. The "Compute" button is now enabled, indicating that the problem is ready to be computed:
 
-\image html SMESH_spadder_end.png
+\image html padder_image09.png
+
+The command "Compute" starts the job run. The progression can be requested using the command "Refresh". In the figure below, the job is still running:
+
+\image html padder_image10.png
+
+Finally, the job is finished and the result is ready to be published in the SALOME study:
+
+\image html padder_image11.png
+
+Click on the button "Publish" to import the resulting MED file into SMESH and publish the resulting mesh in the SALOME study:
+
+\image html padder_image12.png
+
+Note that the final ED mesh contains as many groups as the used input meshes. Their names have been specified in the input dialog. For the moment, the DE mesh is shown as a set of points of equal size. In the next version, the PointSprite (sphere-like) mode will be used to show the MED_BALL elements with their real diameters.
+
+\image html padder_image13.png
 
 \section S3_PADDER Configuring the plugin
 
+
 The configuration of the plugin consists in specifying the location of
 the padder executable program for each of the SALOME resource (at
 least for the localhost resource). This specification is done in the
@@ -136,4 +124,3 @@ envpath = /usr/local/share/envPadder.sh
 \endcode
 
 */
-