Skip to content

12. Running the solver ​

The studio now runs the solver of the case. The solver is a program of its own, tut12_heat, which does not use FIGURE: it reads heat.inp, iterates, prints a residual per iteration and writes the field. The studio starts it as a process, shows what it prints in a log view, plots the residuals as they arrive, shows the progress in a status bar, tells the user when it ends, and can stop it.

docs/examples/src/tut12_run.F90, run as tut12_run --examples /tmp/figure-studio --case /tmp/figure-studio/plate

What this chapter adds to chapter 11's program, tut11_input.F90:

  • start_run: Start the solver on the case, saved first
  • follow_run: Every frame, whichever panel is shown
  • draw_run: The Run panel
  • draw_status: The status bar
  • changed: draw_menus, draw_panels, draw_studio

The whole programs: tut12_run.F90, the studio, and tut12_heat.F90, the solver: successive over-relaxation of Laplace's equation on the plate, the sides and the body held at their temperatures or insulated. Its output, one line per iteration, is all the studio knows of it:

fortran
write(output_unit, '(A,I6,A,ES9.3)') 'iteration ', it, '  residual ', residual
flush(output_unit)                                ! the studio reads each line as it is printed
call wait(pace)

flush sends each line at once: without it the run time keeps the output in a buffer, and the studio would get the lines in bursts. --pace 3 slows this small case down (3 ms a line), so that a run can be watched.

Starting it ​

fortran
subroutine start_run()
!< Start the solver on the case, saved first.
character(len=512) :: args(4) !< The solver and its arguments.
integer(int32)     :: stat    !< Status of the start.

if (edited) call save_case()                      ! the solver reads the file: save the edits first
if (edited) return
call output%clear()
deallocate(iters, res)
allocate(iters(0), res(0))
args(1) = solver_path                             ! no shell: the program and its arguments, an array
args(2) = case_dir
args(3) = '--pace'                                ! a small case: slowed down, to be watched
args(4) = '3'
call solver%start(args, stat=stat)
if (stat /= FIG_OK) then
   call app%notify('The solver does not start: '//figure_last_error(), kind='error')
   return
endif
started = .true.
run_status = 'running'
endsubroutine start_run
  • solver%start(args) starts the program args(1) with the other elements as its arguments: an array, without a shell, so a case folder with blanks in its name needs no quoting (Arguments: no shell). solver_path, set once at the program's start from get_command_argument(0), is tut12_heat next to the studio's own executable.
  • stat tells a start that failed (no such program), with figure_last_error()'s message.
  • The arguments are copied into a fixed-length array first: gfortran 16 writes past the end of an array built by a constructor with a type-spec, [character(len=512) :: path, dir], from deferred-length variables.
  • The studio saves the case first: the solver reads the file, not the form. A save that fails leaves the case edited, and the solver is not started.

Following it ​

fortran
call solver%poll(lines)                           ! the complete lines since the last poll
call output%add(lines)
do k = 1_int32, size(lines, kind=int32)
   if (index(lines(k), 'iteration ') /= 1) cycle
   read(lines(k)(11:), *, iostat=ios) it, word, r ! "iteration    42  residual 1.234E-04"
   if (ios == 0) then
      iters = [iters, it]
      res = [res, r]
   endif
enddo
if (solver%running()) return
started = .false.                                 ! it ended: once
if (solver%killed()) then
   run_status = ICON_SQUARE//' stopped'
   call app%notify('The run was stopped', kind='warning')
elseif (solver%exit_code() == 0_int32) then
   write(run_status, '(A,I0,A,ES8.2)') 'converged in ', nint(iters(size(iters))), ' iterations, residual ', &
                                       res(size(res))
   call app%notify('The solver '//trim(run_status), kind='success', seconds=10.0_real64)
else
   write(run_status, '(A,I0,A)') '[!!] the solver failed, exit code ', solver%exit_code(), ': see the log'
   call app%notify(trim(run_status), kind='error')
endif
  • follow_run runs every frame, whichever panel is shown: FIGURE reads the solver's output on a thread of its own and wakes the frame loop, and solver%poll(lines) gives the complete lines printed since the last poll.
  • output%add(lines) appends them to a log_view_object, a ring of lines (the last 10000 by default).
  • The studio reads each iteration line with a list-directed read and appends the iteration and the residual to two arrays.
  • Once solver%running() is .false., the run is over: solver%killed() after Stop, else solver%exit_code(), 0 when the solver converged. app%notify(text, kind=) tells the user in the corner of the window (Notifications), with the kind's colour and icon.

The Run panel ​

fortran
call ig_begin_disabled(.not. can_run())           ! one run at a time
if (ig_button(ICON_PLAY//' Run')) call start_run()
call ig_end_disabled()
call ig_same_line()
call ig_begin_disabled(.not. solver%running())
if (ig_button(ICON_SQUARE//' Stop')) call solver%kill() ! the solver ends; follow_run tells
call ig_end_disabled()
call ig_same_line()
call ig_text(trim(run_status))
if (ig_begin_child('log', width=380.0_real64)) call output%draw('output') ! only the lines in view
call ig_end_child()
call ig_same_line()
if (size(res) == 0) then
   call ig_text_disabled('The residuals, as the solver prints them.')
elseif (ip_begin_plot('Residuals', width=-1.0_real64, height=-1.0_real64)) then
   call ip_setup_axes('iteration', 'residual', auto_fit=.true., yscale='log') ! follows the data as it grows
   call ip_line('residual', iters, res)
   call ip_end_plot()
endif
  • Run is greyed out while the solver runs (one process per process_object); Stop while it does not. solver%kill() asks the solver to end; the next frames see it ended, killed.
  • output%draw('output') draws the lines in view, in a region of their own, and follows the end while it is scrolled to the bottom (The log view). A click chooses a line, ctrl+c copies it.
  • The residuals are plotted on a logarithmic axis (yscale='log', Axes), and auto_fit=.true. fits the axes to the data in every frame, so the plot follows the curve as it grows (Plots).
fortran
if (ig_begin_menu('Run')) then
   if (ig_menu_item(ICON_PLAY//' Run', shortcut='F5', enabled=can_run())) call start_run()
   if (ig_menu_item(ICON_SQUARE//' Stop', shortcut='Shift+F5', enabled=solver%running())) call solver%kill()
   call ig_end_menu()
endif

The Run menu offers the same actions with F5 and shift+F5.

A status bar ​

fortran
if (ig_begin_side_bar('status', 'bottom', 30.0_real64)) then ! left out of the dock space, as the tools' bar
   if (solver%running()) then
      fraction = -1.0_real64                      ! indeterminate until two residuals are known
      if (size(res) > 1) fraction = min(1.0_real64, max(0.0_real64, &
                                        log(res(1) / res(size(res))) / log(res(1) / inp%tolerance)))
      call ig_progress_bar(fraction, width=200.0_real64)
      call ig_same_line()
      if (size(res) > 0) write(run_status, '(A,I0,A,ES8.2)') 'running: iteration ', nint(iters(size(iters))), &
                                                              ', residual ', res(size(res))
   endif
   call ig_text(trim(run_status))
endif
call ig_end()
  • The status bar is a bar along the bottom of the window (ig_begin_side_bar(..., 'bottom', 30)), declared before the tools' bar so that it spans the whole width; notifications are drawn above it.
  • ig_progress_bar(fraction) shows how far the residual has come towards the tolerance, on a logarithmic scale; a negative fraction draws an indeterminate bar, a band sliding to and fro, until two residuals are known (Progress bars).

A solver still running when the studio quits is stopped with it: a process started this way belongs to the program (The two modes; detached=.true. starts one that outlives it).

What you learned

A program of your own run as a process, its arguments as an array; its output read every frame into a log view and parsed into a plot that follows it; its end told apart (converged, failed, stopped) and announced in a notification; a status bar with a progress bar. Reference: Processes and tasks, The log view, Notifications, Progress bars, Plots.

Run it: build it as chapter 7 shows (with tut12_heat beside it), then ./tut12_run --examples /tmp/studio --case /tmp/studio/plate.

Next: 13. The result field: the field as a heatmap, its colormap and legend, contour lines and probes.

Released under the MIT licence.