/gdb_fortran_tools

Tools to help debug Fortran code with gdb - plotting, saving, and Numpy functions.

Primary LanguagePythonMIT LicenseMIT

gdb_fortran_tools

Table of contents

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.