README.md 12.9 KB
Newer Older
1
    TLSDuctile is a part of eXlibris C++ Library 
Gilles MARCKMANN's avatar
Gilles MARCKMANN committed
2 3
    Copyright (c) 2010-2018 - Nicolas MOES
    Copyright (c) 2019      - Ecole Centrale de Nantes
4
    Contact : Pr. Nicolas Moës <nicolas.moes@ec-nantes.fr>
5

6 7 8
    GNU General Public License (GPL)
            
    See the LICENSE.md files for terms and conditions.  
9 10


11
=======================================================================
12 13


Kévin Moreau's avatar
Kévin Moreau committed
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
The TLSDuctile Appli
====================

Hi programmers!

In this short  README, you will find several instructions  in order to
know how to start using and/or developing the application.

A  nice  introduction  to  TLSDuctile   is  to  read  the  article  on
local/nonlocal damage evolution (Algorithm detail).


Contents
--------

  * Directory structure
  * Configuration
  * Compilation
  * Getting started
  * Good practices (development advices)
  * How to
  * Code structure (for developers)
Kévin Moreau's avatar
Kévin Moreau committed
36
  * Other (important) informations
Kévin Moreau's avatar
Kévin Moreau committed
37

Kevin Moreau's avatar
Kevin Moreau committed
38

39 40
Directory structure
-------------------
Kevin Moreau's avatar
Kevin Moreau committed
41

42
Source code is in:
Kevin Moreau's avatar
Kevin Moreau committed
43

44 45 46
  TLSDuctile/src.

Test cases are in:
Kevin Moreau's avatar
Kevin Moreau committed
47

48 49 50
  TLSDuctile/atomic_test,
  TLSDuctile/test.

Kevin Moreau's avatar
Kevin Moreau committed
51 52 53 54
In  TLSDuctile/atomic_test,  test  cases  are  either  really  simple,
to  test   one  functionality,  or  really   complicated,  to  develop
new   functionalities.  Such   functionalities  are   then  added   to
TLSDuctile/src.
55

Kevin Moreau's avatar
Kevin Moreau committed
56 57
In TLSDuctile/test, test cases are  grouped into several groups, based
on the  prefix name  of the  test case.  For example:  "dam_", "dyn_",
Kévin Moreau's avatar
Kévin Moreau committed
58 59
"plast_", "infinite_dam_"...

60 61 62 63 64 65 66 67 68 69 70 71 72


Configuration
-------------

To    have    an   example    of    a    root   CMakeLists.txt,    see
"CMakeLists.txt-template". It has to be  placed in an empty directory,
often called build.

To   see   default   options   of   TLSDuctile,   grep   "option"   in
TLSDuctile/CMakeLists.txt. To modify an option, copy the "option" line
from TLSDuctile/CMakeLists.txt to your  root CMakeLists.txt and change
either from OFF to ON or from ON to OFF.
73 74


Kévin Moreau's avatar
Kévin Moreau committed
75

76 77 78
Compilation
-----------

Kévin Moreau's avatar
Kévin Moreau committed
79
Assuming  you  are  in  your  build  directory  and  you  edited  your  root
80
CMakeLists.txt.
81 82

To generate Makefile or equivalent:
Kevin Moreau's avatar
Kevin Moreau committed
83

84 85
  cmake .    # if your root CMakeLists.txt is in build dir
  cmake ..   # if your root CMakeLists.txt is in build/.. dir
86 87 88
  ?          # other

To compile source code:
Kevin Moreau's avatar
Kevin Moreau committed
89

90 91 92
  make TLSDuctile

To compile a specific test case (dam_pull_out for example):
Kevin Moreau's avatar
Kevin Moreau committed
93

94 95
  make dam_pull_out

Kévin Moreau's avatar
Kévin Moreau committed
96
To launch  an executable (dam_pull_out for example):
Kevin Moreau's avatar
Kevin Moreau committed
97

98 99 100
  cd TLSDuctile/test/dam_pull_out <OR> cd Applis/TLSDuctile/test/dam_pull_out
  mkdir run
  cd run
Kévin Moreau's avatar
Kévin Moreau committed
101 102
  cp ../data/main.dat main.dat
  cp ../data/info.dat info.dat
103 104 105 106
  cp ../data/elasto_dam.mat mate.mat
  cp ../data/cross_ring.msh mesh.msh
  ../dam_pull_out main.dat

Kévin Moreau's avatar
Kévin Moreau committed
107 108 109 110 111
Note  1:  I believe  it  is  better to  copy  data  files in  the  run
directory because then you can  change data files without loosing data
information  from which  you  got your  results.  Moreover, your  data
directory  stay  unchanged and  you  don't  risk  to commit  new  data
parameters.
112 113 114 115 116

Note  2: You can find as well in each directory a reference.py  script
from  which  you can document to know HOW TO LAUNCH  A  SPECIFIC  TEST
CASE.

Kevin Moreau's avatar
Kevin Moreau committed
117 118
To launch an executable from a restoration archive:

119 120 121 122 123 124
  cd TLSDuctile/test/dam_pull_out <OR> cd Applis/TLSDuctile/test/dam_pull_out
  mkdir run
  cd run
  cp ../data/{main.dat,info.dat} .
  cp ../data/elasto_dam.mat mate.mat
  cp ../data/cross_ring.msh mesh.msh
Kevin Moreau's avatar
Kevin Moreau committed
125
  ../dam_pull_out main.dat restoration_archive.tar   # if you have one !
126

Kevin Moreau's avatar
Kevin Moreau committed
127
The  restoration  archive   can  be  generated  by   adding  "save  <a
Kévin Moreau's avatar
Kévin Moreau committed
128
frequency>" to the "export_manager" list, see How To.
Kevin Moreau's avatar
Kevin Moreau committed
129

Kevin Moreau's avatar
Kevin Moreau committed
130
To check if test cases work:
131 132 133

  ctest

Kevin Moreau's avatar
Kevin Moreau committed
134 135 136 137
To check if one test case works:

  ctest -R dam_pull_out

138 139 140
Note:  This  cmake  function call the reference.py  script  that  does
several checks on a few times steps not to take too much time.

141 142 143
To check if several test case works: (for example "dyn_" group)

  ctest -R dyn_*
144

145

Kévin Moreau's avatar
Kévin Moreau committed
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193

Getting Started
---------------

We  are  going  to  run   "dam_homogeneous"  test  with  both  imposed
displacement  and  imposed  force.   The  official  version  impose  a
displacement, we are going  to have a few changes to  make it impose a
force. It  is done using "echo"  and "sed" programs. It  changes BC in
main.dat and output in info.dat. Everything  else stay the same. Go to
the  build directory  and then  inside TLSDuctile/test/dam_homogeneous
and launch in a terminal:

mkdir disp
cd disp
cp ../data/elasto_dam.mat mate.mat
cp ../data/rectangle.msh mesh.msh
cp ../data/info.dat info.dat
cp ../data/main.dat main.dat

cd ..
cp -r disp force
cd force
sed -i s/"DISPLACEMENT_Y FIX_AND_MEASURE = 3."/"TRACTION_Y FIX_AND_MEASURE = 3.e9"/g main.dat  # find and replace DISPLACEMENT by TRACTION and 3. by 3.e9
echo "RIGID_LINE 13 = { DISPLACEMENT_Y FIX = 0. }" >> main.dat                                 # additional line that make the LINE 13 a RIGID line

sed -i s/"force_y 1"/"disp_y 1"/g main.dat

../dam_homogeneous main.dat 2>&1|tee out.log
cd ../disp
../dam_homogeneous main.dat 2>&1|tee out.log

cd ..
vimdiff {disp,force}/out.log

A few points about the test case:
  * the  FIX_AND_MEASURE keyword  enables a measure at  the considered
  boundary. The quantity measured is the dual quantity (reaction force
  for imposed displacement, displacement for imposed force).
  * RIGID_LINE is added  so that the imposed force is  done on a rigid
  line, it is equivalent to  imposed displacement. However, it doesn't
  give the same results...
  * in the two out.log, we see  that either ref force norm or ref disp
  norm is  null. This is related  to boundary conditions, see  How To.
  The final  "Warning" is just  a message  to say that  the simulation
  ends before the step reaches "nb_step_max" value given in info.dat.



194 195
Good practices
--------------
Kevin Moreau's avatar
Kevin Moreau committed
196

Kévin Moreau's avatar
Kévin Moreau committed
197
(These are my personal good practices that I (Kévin Moreau) tried to respect:)
198 199

* On the header
Kévin Moreau's avatar
Kévin Moreau committed
200 201 202 203 204
  - to  minimise the number  of includes by using  forward declaration
  and by coding into .cc files,
  -  to classify  includes  into  libraries from  the  closest to  the
  furthest (TLSDuctile/xTLS/Xfem/Xext/std)  (doing so  prevent headers
  from libraries that miss include to compile, which is a good thing),
205 206 207
  - to sort includes by alphabetic order.

* On methods and functions
Kévin Moreau's avatar
Kévin Moreau committed
208 209
  -  to  try  to  write  as small  functions  as  possible  (10  lines
  without counting declaration  on average is good)  since it promotes
210 211 212 213
  reusability.

* On classes
  - to try to maximize encapsulation,
Kévin Moreau's avatar
Kévin Moreau committed
214 215
  - to  comment only  on headers  excepted for  very twisted  lines of
  code, otherwise it pollutes the code.
216 217 218 219 220

* On the library (TLSDuctile)
  - to provide an single header "TLSDuctile.h" for test cases.


Kévin Moreau's avatar
Kévin Moreau committed
221 222

How to
223 224
------

Kévin Moreau's avatar
Kévin Moreau committed
225 226
* How to do export?
  Add export name in the "export_manager" list of your info.dat file:
227

Kévin Moreau's avatar
Kévin Moreau committed
228
    export_manager = { <my export name> <its frequency> }
229

Kévin Moreau's avatar
Kévin Moreau committed
230
  See dam_pull_out for example.
231

Kevin Moreau's avatar
Kevin Moreau committed
232

Kévin Moreau's avatar
Kévin Moreau committed
233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259
* How to obtain a list of possible export?
  Launch this command in a terminal in the TLSDuctile/src directory

    grep exportOnSpace\(\" *.{h,cc} |cut -d"(" -f2|cut -d',' -f1


* How to obtain the list of keywords to put in info.dat?
* How to get documentation about keywords in info.dat?
  Launch this command in a terminal in the TLSDuctile/src directory

    grep parse_data.register *.{h,cc}

  It gives you the data type (integer, real, list...) and a description.
  Launch this command in a terminal in the TLSDuctile/src directory

    grep \"integ_order\" *.{h,cc}

  It gives you where keyword "integ_order" is used in the code.


* How to export a restoration archive for restart?
  Add "save" keyword in the "export_manager" list of your info.dat file:

    export_manager = { save 100 }

  It exports a restoration archive every hundred steps.

Kevin Moreau's avatar
Kevin Moreau committed
260

Kévin Moreau's avatar
Kévin Moreau committed
261
* How to restart?
Kevin Moreau's avatar
Kevin Moreau committed
262 263 264 265 266 267
  It is realised by the helper  class PreProcessing. We assume that we
  restart at step n. Several data are needed in order to restart:
    - disp field (step n-1),
    - phi field (step n),
    - old phi field (step n-1),
    - nonlocal domain (element only) (step n),
Kévin Moreau's avatar
Kévin Moreau committed
268 269
    - computation mesh (if crack already appeared) (step n),
  There are all in the restoration archive.
Kevin Moreau's avatar
Kevin Moreau committed
270 271 272

  Things to know:
    - disp field is step n-1 one,  it is given as initial field to the
Kévin Moreau's avatar
Kévin Moreau committed
273
    Newton-Raphson loop  in Algorithm.  If the  problem is  linear and
Kevin Moreau's avatar
Kevin Moreau committed
274 275 276 277 278 279 280
    solved directly  (elastic_damage is chosen),  there is no  need to
    know this field, but it is loaded anyway.
    - The computation mesh is exported using AOMD implementation which
    exports in  ASCII. Once  reloaded, node locations  slightly differ
    because of the truncation of node coordinates. To test if restart
    restores the exact same state, uncomment the two lines of code
    in TLSGeom constructor
Kévin Moreau's avatar
Kévin Moreau committed
281

Kevin Moreau's avatar
Kevin Moreau committed
282 283
      data.ReadMesh();
      comp_mesh=data.mesh;
Kévin Moreau's avatar
Kévin Moreau committed
284

Kevin Moreau's avatar
Kevin Moreau committed
285
    and comment
Kévin Moreau's avatar
Kévin Moreau committed
286

Kevin Moreau's avatar
Kevin Moreau committed
287 288
      comp_mesh=new xMesh;
      pre_pro.loadMesh("comp", *comp_mesh);
Kévin Moreau's avatar
Kévin Moreau committed
289

Kevin Moreau's avatar
Kevin Moreau committed
290 291 292 293 294 295
    This test works  only before the emergence of a  crack (when d<1).
    Without  this  modification, you  cannot  restore  the exact  same
    solution unless you code a  binary export/import of the mesh. Good
    luck if you go for this!
    - The integration  mesh has to be rebuilt, as  well as partitions,
    it implies the regeneration of computation mesh sadly.
Kevin Moreau's avatar
Kevin Moreau committed
296 297


Kévin Moreau's avatar
Kévin Moreau committed
298 299 300 301 302 303 304 305 306 307 308 309 310 311
* How to get force/displacement curve?
  Do the following steps:
  -  Go to  your main.dat  file and  find boundary  conditions, it  is
  either TRACTION_X or DISPLACEMENT_X (or _Y or _Z).
  - At the boundary over which you want your measure check if you have
  the FIX_AND_MEASURE keyword, if not, replace FIX by FIX_AND_MEASURE.
  - Go to your info.dat file  and in the export_sensors_label list add
  either:
    * "load_factor 1 disp_x 1" if you imposed TRACTION_X,
    * "load_factor 1 force_x 1" if you imposed DISPLACEMENT_X.
  - Plot either:
    * disp_x versus load_factor*TRACTION_X (value),
    * load_factor*DISPLACEMENT_X (value) versus force_x,
  The two quantities are dual in the work sense.
Kevin Moreau's avatar
Kevin Moreau committed
312 313


Kévin Moreau's avatar
Kévin Moreau committed
314 315 316 317 318
* How to restrain damage to a specific zone?
  It is assumed you are familiar with GMSH physical tags.
  Build a partition of your domain and have different physical tags
  to each parts.
  In main.dat file, have a ZONE for each parts, example:
Kevin Moreau's avatar
Kevin Moreau committed
319

Kévin Moreau's avatar
Kévin Moreau committed
320 321
    ZONE 101 = { MAT_CLASS = ElastoDam MAT_PARAM = mate_1.mat }
    ZONE 102 = { MAT_CLASS = ElastoDam MAT_PARAM = mate_2.mat }
Kevin Moreau's avatar
Kevin Moreau committed
322

Kévin Moreau's avatar
Kévin Moreau committed
323 324 325
  Make sure Y_CRIT is smaller in  one of the two mate_*.mat files. The
  damage is  restrained to the  corresponding zone. The first  file in
  the list defines the PLANE_STATE and the MATERIAL_CLASS.
Kevin Moreau's avatar
Kevin Moreau committed
326 327 328



Kévin Moreau's avatar
Kévin Moreau committed
329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360
Code structure
--------------

                                                                --------------
                                                                | Executable |
                                                                --------------
                                                                      |
                                                                -------------
                                                                | Algorithm |  encapsulates algorithm, advances in time, do direct resolution OR Newton-Rapshon resolution of mechanical problem.
                                                                -------------
                                                                 /         \
                                                     -----------------  ----------------
    computes load_factor, delta_load_factor,         | QSFormulation |  | LinearSystem |  encapsulates solvers, API for linear solvers.
    delta_phi (from modes), all specificities        -----------------  ----------------
    of the QS alg. In dynamics, it is DynFormulation.    /           \
                                                ---------------     -------------
    gives some basic functions for assembling,  | Formulation |     | TLSSolver | is responsible for "phi" xField, computes "mean" quantities
    imposing boundary conditions. Is respon-    ---------------     -------------
    sible for "disp" xField. Common basis of                 \       /
    all formulations.                                       ----------- 
                                                            | TLSGeom |  gives all domains, API for parts, iterators and integration rules.
                                                            -----------  It is implemented using xSubMesh, no xSubMesh should appears in the rest of
                                                                         the code.

        ---------------
        | TLSMaterial |  Base class for all xMaterial used in TLSDuctile,
        ---------------  it defines the common part of all materials.


Other informations
------------------

Kévin Moreau's avatar
Kévin Moreau committed
361 362 363 364 365 366
*  Please  don't  change  material  parameters  directly  inside  data
directory (unless  you really want  to change the default  test case),
data are chosen and used in the reference.py script launched by ctest.
If it  is changed then reference  results are not the  same. Change in
material parameters have to be carefully  changed in all data files as
well as in reference.py file.
Kévin Moreau's avatar
Kévin Moreau committed
367 368

* xSubMesh  is only used  inside TLSGeom.cc and  MeshGeneration.cc, it
Kévin Moreau's avatar
Kévin Moreau committed
369
can be changed for anything else that is more optimized.