gdb_fortran_tools

Table of contents

• gdb_fortran_tools
• Introduction
• Installation
• Usage example
• Commands
• Supported types
• Warnings
  • Array indexing
  • Allocatable arrays
• Additional hints
• Requirements
• Acknowledgements

Introduction

Support more advanced gdb debugging of Fortran code

• [X] Generic access to many basic numpy array operators: sum, min, max, log10, etc.
• [X] Access to custom complex on-liners
• [X] Graphics: plot, imshow, scatter
• [X] Save data: pickle, CSV

Installation

git clone https://github.com/mankoff/gdb_fortran_tools

Set an environment variable to that location (perhaps in your .bashrc or other init script).

export GFT_DIR=/path/to/gdb_fortran_tools

Edit your ~/.gdbinit file to load gdb_fortran_tools

python
import os
import sys
if 'GFT_DIR' not in os.environ:
   print(f'WARNING: environmental var GFT_DIR not found')
else:
   sys.path.insert(0, os.path.expanduser(os.environ['GFT_DIR']))
   try:
      import gdb_fortran_tools
   except:
      print("WARNING: Could not import gdb_fortran_tools")
end

Usage example

With the following code in example.F90

program main
  real, allocatable, DIMENSION(:) :: x, y
  real, allocatable, DIMENSION(:,:) :: xy
  INTEGER :: im, jm, i,j

  im = 4
  jm = 5
  
  allocate(x(im))
  allocate(y(jm))
  allocate(xy(im,jm))

  do i=1,im
     x(i) = i
     do j=1,jm
        y(j) = j
        xy(i,j) = x(i)*y(j)
     end do
  end do
  
  print *, x
  print *, y
  print *, xy
end program main

Compile it for debugging with

gfortran -g example.F90

Run gdb:

gdb ./a.out
start
break 21
continue

# traditional GDB commands
p x
ptype x

# Simple numpy accessors
np sum x
np max y
np log10 xy

# Plots
plot x
imshow xy
logshow xy
plot xy
plot x y(2:5)
scatter x y(2:5)

# arbitrary Python commands
pycmd xy print(_)
pycmd xy np.min(_[np.where(_ != 0)])
pycmd xy [item for item in _.flatten() if (item % 2) == 0]

# save to CSV
savecsv xy.csv xy

Commands

• Graphical

  imshow

  Display 2D array using matplotlib.pyplot.imshow

  imshow0

  Same as imshow but set 0 to NaN (colorbar scaling)

  logshow

  Same as imshow but display np.log10() of data

  scatter

  Display scatter plot of two vectors

  plot3d

  Display 3D plot of 2D array

  scatter3d

  Display 3D scatter plot

  hist

  Display histogram of vector

  fft

  Display FFT of vector

• Numerical

  np <function> <variable>

  Call np.function(variable) for any numpy function

  pycmd <variable> <statements(_)>

  Run any sequence of valid one-line Python statements on variable. Within statement, access variable via _ (underscore)

• I/O

  savecsv <file.csv> <variable>

  Save variable to file.csv

  savepy <filename> <variable>

  Save variable to filename in Python pickle format

  save <file> <variable>

  Save variable to file using numpy tofile function

Supported types

real*{4,8}, dimension(:), dimension(:,:), dimension(:,:,:)
integer*{4,8}, dimension(:), dimension(:,:), dimension(:,:,:)
logical

Warnings

Array indexing

• Fortran uses 1-based array indexing
• Python uses 0-based array indexing

Allocatable arrays

Note: If gdb reports

(gdb) ptype foo
type = real(kind=8), allocatable (72,0:47)

Then you need to use the syntax imshow foo(:,:)

Additional hints

You can create custom gdb commands that build on commands provided here. For example to find the range of an array, add this to your ~/.gdbinit

define mm
    np min $arg0
    np max $arg0
end            
document mm
    print min and max of an array or vector. Uses gdb_fortran_tools.
end	

Requirements

• GDB >= 7.0
• Python 3
• NumPy
• Matplotlib

Acknowledgements

Thanks to X-Neon and gdbplotlib.