doc/UserGuide/postProcessing/monitoring.txt

   1 === Monitoring and managing jobs
   2
   3 This section is concerned primarily with successful running of {project} jobs
   4 and extends on the basic execution of solvers described in
   5 <<sec_runningApplications>>. When a solver is executed, it reports the status
   6 of equation solution to standard output, 'i.e.' the screen, if the `level`
   7 debug switch is set to 1 or 2 (default) in filename:DebugSwitches[] in the
   8 filename:<prefix>etc/controlDict[] file. An example from the beginning of the
   9 solution of the dirname:cavity[] tutorial is shown below where it can be seen
  10 that, for each equation that is solved, a report line is written with the
  11 solver name, the variable that is solved, its initial and final residuals and
  12 number of iterations.
  13
  14 -------------------------------------------------------------------------------
  15 Starting time loop
  16
  17 Time = 0.005
  18
  19 Courant Number mean: 0 max: 0
  20 DILUPBiCG:  Solving for Ux, Initial residual = 1, Final residual = 2.96338e-06, No Iterations 8
  21 DILUPBiCG:  Solving for Uy, Initial residual = 0, Final residual = 0, No Iterations 0
  22 DICPCG:  Solving for p, Initial residual = 1, Final residual = 7.55402e-07, No Iterations 35
  23 time step continuity errors : sum local = 5.03809e-09, global = 4.40722e-19, cumulative = 4.40722e-19
  24 DICPCG:  Solving for p, Initial residual = 0.523591, Final residual = 9.72352e-07, No Iterations 34
  25 time step continuity errors : sum local = 1.07766e-08, global = 2.93897e-19, cumulative = 7.34619e-19
  26 ExecutionTime = 0.02 s  ClockTime = 0 s
  27
  28 Time = 0.01
  29
  30 Courant Number mean: 0.0514108 max: 0.585722
  31 DILUPBiCG:  Solving for Ux, Initial residual = 0.148584, Final residual = 7.15711e-06, No Iterations 6
  32 DILUPBiCG:  Solving for Uy, Initial residual = 0.256618, Final residual = 8.94127e-06, No Iterations 6
  33 DICPCG:  Solving for p, Initial residual = 0.379232, Final residual = 3.38648e-07, No Iterations 34
  34 time step continuity errors : sum local = 3.15698e-09, global = 1.94222e-19, cumulative = 9.28841e-19
  35 DICPCG:  Solving for p, Initial residual = 0.286937, Final residual = 5.99637e-07, No Iterations 33
  36 time step continuity errors : sum local = 6.08774e-09, global = 5.80474e-19, cumulative = 1.50932e-18
  37 ExecutionTime = 0.02 s  ClockTime = 0 s
  38
  39 Time = 0.015
  40
  41 Courant Number mean: 0.0761501 max: 0.758286
  42 DILUPBiCG:  Solving for Ux, Initial residual = 0.0448669, Final residual = 2.39894e-06, No Iterations 6
  43 DILUPBiCG:  Solving for Uy, Initial residual = 0.0782408, Final residual = 1.45948e-06, No Iterations 7
  44 DICPCG:  Solving for p, Initial residual = 0.109591, Final residual = 5.81093e-07, No Iterations 32
  45 time step continuity errors : sum local = 4.70049e-09, global = -5.90607e-20, cumulative = 1.45025e-18
  46 DICPCG:  Solving for p, Initial residual = 0.0826507, Final residual = 7.26561e-07, No Iterations 31
  47 time step continuity errors : sum local = 5.95385e-09, global = -5.75718e-20, cumulative = 1.39268e-18
  48 ExecutionTime = 0.02 s  ClockTime = 0 s
  49 -------------------------------------------------------------------------------
  50
  51 ==== The `job` script for running jobs
  52
  53 The user may be happy to monitor the residuals, iterations, Courant number
  54 'etc.' as report data passes across the screen. Alternatively, the user can
  55 redirect the report to a log file which will improve the speed of the
  56 computation. The `job` (((`job` script/alias)))(((script/alias,`job`))) script
  57 provides useful options for this purpose with the following executing the
  58 specified '<solver>' as a background process and redirecting the output to a
  59 file named filename:log[]:
  60
  61 -------------------------------------------------------------------------------
  62 $freefoam job <solver>
  63 -------------------------------------------------------------------------------
  64
  65 For further options the user should execute `freefoam job -help`. The user may
  66 monitor the filename:log[] file whenever they wish, using the `UNIX` `tail`
  67 command, typically with the option:-f[] (`follow') option which appends the new
  68 data as the filename:log[] file grows:
  69
  70 -------------------------------------------------------------------------------
  71 $ tail -f log
  72 -------------------------------------------------------------------------------
  73
  74 ==== The `log` script for monitoring jobs
  75
  76 There are limitations to monitoring a job by reading the log file, in
  77 particular it is difficult to extract trends over a long period of time. The
  78 `log` (((`log` script/alias)))(((script/alias,`log`))) script is therefore
  79 provided to extract data of residuals, iterations, Courant number 'etc.' from a
  80 log file and present it in a set of files that can be plotted graphically. The
  81 script is executed by:
  82
  83 -------------------------------------------------------------------------------
  84 $ freefoam log <logFile>
  85 -------------------------------------------------------------------------------
  86
  87 The files are stored in a subdirectory of the case directory named
  88 dirname:logs[]. Each file has the name filename:<var>_<subIter>[] where
  89 '<var>' is the name of the variable specified in the log file and '<subIter>'
  90 is the iteration number within the time step. Those variables that are solved
  91 for, the initial residual takes the variable name '<var>' and final residual
  92 takes __<var>__++FinalRes++. By default, the files are presented in two-column
  93 format of time and the extracted values.
  94
  95 For example, in the dirname:cavity[] tutorial we may wish to observe the
  96 initial residual of the `Ux` equation to see whether the solution is converging
  97 to a steady-state. In that case, we would plot the data from the
  98 filename:logs/Ux_0[] file as shown in <<fig_UxResidual>>. It can be seen here
  99 that the residual falls monotonically until it reaches the convergence
 100 tolerance of math:[10^{-5}].
 101
 102 [[fig_UxResidual]]
 103 .Initial residual of `Ux` in the dirname:cavity[] tutorial
 104 image::{builddir}postProcessing/assets/UxResidual.{gfx-fmt}[]
 105
 106 `log` generates files for everything it feasibly can from the filename:log[]
 107 file. In the dirname:cavity[] tutorial example, this includes:
 108
 109 - the Courant number, filename:Courant_0[];
 110 - `Ux` equation initial and final residuals, filename:Ux_0[] and
 111   filename:UxFinalRes_0[], and iterations, filename:UxIters_0[] (and equivalent
 112   `Uy` data);
 113 - cumulative, global and local continuity errors after each of the 2 `p`
 114   equations, filename:contCumulative_0[], filename:contGlobal_0[],
 115   filename:contLocal_0[] and filename:contCumulative_1[],
 116   filename:contGlobal_1[], filename:contLocal_1[];
 117 - residuals and iterations from the the 2 `p` equations filename:p_0[],
 118   filename:pFinalRes_0[], filename:pIters_0[] and filename:p_1[],
 119   filename:pFinalRes_1[], filename:pIters_1[];
 120 - and execution time, filename:executionTime[].