PLUTO IDL Tools

This page was created by the IDL library routine mk_html_help. For more information on this routine, refer to the IDL Online Help Navigator or type:

     ? mk_html_help

at the IDL command line prompt.

Last modified: Sat Jun 26 13:26:39 2021.


List of Routines


Routine Descriptions

COLORBAR2

[Next Routine] [List of Routines]
 NAME:
   COLORBAR2

 PURPOSE:
       The purpose of this routine is to add a color bar to the current
       graphics window.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:
       Graphics, Widgets.

 CALLING SEQUENCE:
       COLORBAR

 INPUTS:
       None.

 KEYWORD PARAMETERS:

       BOTTOM:   The lowest color index of the colors to be loaded in
                 the bar.

       CHARSIZE: The character size of the color bar annotations. Default is 1.0.

       COLOR:    The color index of the bar outline and characters. Default
                 is !P.Color..

       DIVISIONS: The number of divisions to divide the bar into. There will
                 be (divisions + 1) annotations. The default is 6.

       FONT:     Sets the font of the annotation. Hershey: -1, Hardware:0, True-Type: 1.

       FORMAT:   The format of the bar annotations. Default is '(I5)'.

       INVERTCOLORS: Setting this keyword inverts the colors in the color bar.

       MAXRANGE: The maximum data value for the bar annotation. Default is
                 NCOLORS.

       MINRANGE: The minimum data value for the bar annotation. Default is 0.

       MINOR:    The number of minor tick divisions. Default is 2.

       NCOLORS:  This is the number of colors in the color bar.

       POSITION: A four-element array of normalized coordinates in the same
                 form as the POSITION keyword on a plot. Default is
                 [0.88, 0.15, 0.95, 0.95] for a vertical bar and
                 [0.15, 0.88, 0.95, 0.95] for a horizontal bar.

       RANGE:    A two-element vector of the form [min, max]. Provides an
                 alternative way of setting the MINRANGE and MAXRANGE keywords.

       RIGHT:    This puts the labels on the right-hand side of a vertical
                 color bar. It applies only to vertical color bars.

       TITLE:    This is title for the color bar. The default is to have
                 no title.

       TOP:      This puts the labels on top of the bar rather than under it.
                 The keyword only applies if a horizontal color bar is rendered.

       VERTICAL: Setting this keyword give a vertical color bar. The default
                 is a horizontal color bar.

 COMMON BLOCKS:
       None.

 SIDE EFFECTS:
       Color bar is drawn in the current graphics window.

 RESTRICTIONS:
       The number of colors available on the display device (not the
       PostScript device) is used unless the NCOLORS keyword is used.

 EXAMPLE:
       To display a horizontal color bar above a contour plot, type:

       LOADCT, 5, NCOLORS=100
       CONTOUR, DIST(31,41), POSITION=[0.15, 0.15, 0.95, 0.75], $
          C_COLORS=INDGEN(25)*4, NLEVELS=25
       COLORBAR, NCOLORS=100, POSITION=[0.15, 0.85, 0.95, 0.90]

 MODIFICATION HISTORY:

   Original version by David Fanning
   Last modified by A. Mignone, 1st May 2011

(See colorbar2.pro)


DISPLAY

[Previous Routine] [Next Routine] [List of Routines]

 NAME:      DISPLAY

 AUTHOR:    Andrea Mignone (mignone@ph.unito.it)

 PURPOSE:   Make a tvscl image with axis, colorbar, and all the
            nice stuffs.

 SYNTAX:  display, img[,x1=x1][,x2=x2][,BACKGROUND=value]
                  [,CBDIV=integer][,CHARSIZE=value][,COLOR=value][,/EPS]
                  [,FILENAME=string][,IMAX=value][,IMIN=value]
                  [,IMSIZE=value][,LABEL1=string][,LABEL2=string]
                  [,/SMOOTH][,TITLE=string][,/HBAR][,/VBAR][,/XSYM][,/YSYM]
                  [,/XLOG],[,/YLOG][,XRANGE=[min,max]][,YRANGE=[min,max]]
                  [,NWIN=integer][,/POLAR][,{LFT,RGT,TOP,BOT}=value]


 KEYWORDS:


      x1 =    a one 1-D array with the horizontal coordinates
              dim(x1) = first dimension of img;

      x2 =    a one 1-D array with the vertical coordinates
              dim(x2) = second dimension of img; both
              x1 and x2 must be present one wish to
              scale axis to coordinates

      BACKGROUND = in integer value in the range [1,255] giving the 
                   background color.

      CBDIV      = an integer number specifying the number of 
                   divisions to divide the colorbar into.

      CHARSIZE   = size of characters.

      COLOR      = an integer in the range [1,255] giving contour and 
                   colorbar should be > 0 and <= 255

      /EPS       = when this keyword is set, it produces eps output.
                   the image keeps the aspect ratio with a default
                   horizontal extent of 10cm. Use imsize to shrink/enlarge it.

      FILENAME   = a string giving the name of the file where output is saved;
                   only works when /eps is used.

      IMAX       = maximum floating value to which img should be scaled to;

      IMIN       = minimum floating value to which img should be scaled to;

      IMSIZE     = a magnification/shrinking scale factor;
                   for example, imsize=2.0 produces an image twice
                   as big as the original.
                   When graphics is NOT eps, it can also be a two
                   element arrays giving the new image sizes

      LABEL1     = a string label for the x1 - axis

      LABEL2     = a string label for the x2 - axis

      NWIN       = an integer selecting the window.

      /POLAR     = maps a polar (r,phi) domain into cartesian
                   coordinates. The user must also supply the
                   x1 (= r) and x2 (= phi) coordinates. It also
                   recomended that imsize = [nx,ny] be given, where
                   nx and ny are the final number of points in the
                   cartesian map.

      /SMOOTH    = smooth the image using cubic interpolation when resizing

      TITLE      = string title of the plot

      /HBAR      = add horizontal color bar at the bottom of the plot

      /VBAR      = add a vertical color bar to the right of the plot

      /XSYM      = symmetrize the image with respect to the x-axis

      /YSYM      = symmetrize the image with respect to the y-axis

      XRANGE     = a two-element vector specifying the abscissa of the
                    lower and upper boundary for the displayed image.

      YRANGE     = a two-element vector specifying the ordinata of the
                   lower and upper boundary for the displayed image.

      /XLOG      = set a logarithmic scaling for the x-axis. 
                   CAUTION: the input grid must be regularly spaced in log scale.

      /YLOG      = set a logarithmic scaling for the y-axis.
                   CAUTION: the input grid must be regularly spaced in log scale.

     /UNIFORM    = do not attempt to regrid the image and display as it is,
                   without interpolating
     LFT,RGT     = these parameters can be used to specify the margin (in pixels)
     BOT,TOP       between the plot borders and the left (lft), right (rgt),
                   top (top) and bottom (bot) side of the window.


  EXAMPLES:

    * Example #1: Display the logarithm of the intial density and put axis, 
                  horizontal colorbar and title:

      IDL> display, alog(rho(0)), x1 = x1, x2 = x2, title = "My title", /hbar

    * Example #2: Display another image in a different window with a 
                  vertical colorbar using the red - blue color table:

      IDL> loadct,33
      IDL> display, img2, x1 = x1, x2 = x2, /vbar, nwin = 1

    * Example #3: Display a subdomain of the original density map and leave 
                  extra space to the right of the plot for extra annotations:

      IDL> display, alog(rho(0)), x1 = x1, x2 = x2, $
                    xrange=[0.3,0.7], yrange=[0.4,0.8],rgt = 120

    * Example #4: Mapping an image from polar to Cartesian on a 400x400 grid:

      IDL> display, img, x1 = x1, x2 = x2, /polar, ims = [400,400]

    * Example #5: Mapping an image from spherical to Cartesian:

      IDL> display, img, x1 = x1, x2 = 0.5*!PI - x2, /polar, ims = [400,400]


  LAST MODIFIED:   Dec 09, 2019 by A.Mignone (mignone@to.infn.it)

(See display.pro)


EXTREMA

[Previous Routine] [Next Routine] [List of Routines]

 NAME:      EXTREMA

 AUTHOR:    Andrea Mignone

 SYNTAX:    indx = EXTREMA(f)

 PURPOSE:   Find maxima in a 1D array f[].
            On output, indx is an integer array whose elements are the
            indices of the extrema of f.
            If no maximum is found, return -1.

 ARGUMENTS:

   f        a 1D array

 KEYWORD:   none

 LAST MODIFIED:   Dec 21, 2016 by A. Mignone 

(See extrema.pro)


FIELD_LINE[1]

[Previous Routine] [Next Routine] [List of Routines]
 NAME:     FIELD_INTERP
 
 AUTHOR:   A. Mignone
 
 PURPOSE:  Linearly interpolate the vector (Vx, Vy, Vz) defined on the 
           grid (x,y,z) at the point with coordinate (xp, yp, zp) 

 SYNTAX    FIELD_INTERP, Vx, Vy, x, y, z, coord
 
 ARGUMENTS:

   Vx,Vy, Vz:    Vector components to be interpolated;
   x,y,z:        1-D coordinate arrays; 
   coord:        a three-element vector with the coordinates of 
                 the point where interpolation is required.
 
 LAST MODIFIED:  June 19, 2013 by A. Mignone (mignone@ph.unito.it)

(See field_line.pro)


FIELD_LINE[2]

[Previous Routine] [Next Routine] [List of Routines]

 NAME:    FIELD_LINE

 AUTHOR:  A. Mignone (mignone@ph.unito.it)

 PURPOSE: Given a 2 or 3D vector field (Vx, Vy) or (Vx, Vy, Vz) computes the 
          field line passing through the point (seed) [xseed, yseed, zseed].
          The line is computed by solving a system of ODE of the form
          
            dx/dt = Vx(x,y,z)
            dy/dt = Vy(x,y,z)
            dz/dt = Vz(x,y,z)
           
          Integration stops when either the domain boundaries are reached or 
          the max number of iteration is exceeded.

 SYNTAX: FIELD_LINE, Vx, Vy, Vz, x, y, z, seed = seed, pnt_list[,step=step]
                     [,method=method][,maxstep=maxstep][,minstep=minstep][,tol=tol]


 ARGUMENTS:

   Vx,Vy,Vz: 3D arrays giving the three vector components. In 2D, both Vz
             and z must be scalars and equal to 0.

   x,y,z:    1D coordinate arrays on top of which Vx, Vy and Vz are defined.
             In 2D, set z to be 0.0

   seed:     a 3-element array giving the point coordinates through which the
             field line goes. 

   pnt_list: on output, in contains 2D array giving the field line coordinates
             {x,y,z} = {pnt_list[0,*], pnt_list[1,*], pnt_list[2,*]} (in 3D) or
             {x,y }  = {pnt_list[0,*], pnt_list[1,*]} (in 3D) 
             

 KEYWORDS:

   step:   a scalar giving the initial step size. Default is (mean) grid spacing.

   method: a string giving the integration method. The possible choices are:

            "RK2"   explicit, fixed step, 2nd order Runge-Kutta methods.
            "RK4"   explicit, fixed step, 4th order Runge-Kutta methods.
            "BS23"  explicit, adaptive stepsize Runge-Kutta-Fehlberg of order 
                    3 with local truncation error based on a 2nd-order accurate
                    embedded solution.
            "CK45"  explicit, adaptive stepsize Cask-Karp of order 
                    5 with local truncation error based on a 4th-order accurate
                    embedded solution.

           The default is "RK2". Use an adaptive stepsize integrator
           when the field line does not close on itself inside the domain.
 

   maxstep: a scalar giving the maximum allowed integration step.
            Default is 100*step.

   minstep: a scalar giving the minimum allowed integration step. 
            Default is 0.05*step.

   tol:   a scalar value giving the relative tolerance during adaptive stepsize
          integration. It is ignored for fixed step-size integration (such as RK2, RK4)
         
     

 EXAMPLE:

   * compute a field line tangent to the vector field (Bx1,Bx2) in 2D at the 
     point with coordinate (-1,2) using the Bogacki-Shampine method with relative
     tolerance 1.e-4:

   IDL> field_line, Bx1, Bx2, 0.0 x1, x2, 0.0, seed=[-1,2], pl, method="BS23", tol=1.e-4
   IDL> oplot, pl[0,*], pl[1,*]  ; overplot on current window

   * Same as before but in 3D and at the point [-1,2,0.5]:

   IDL> field_line, Bx1, Bx2, Bx3, x1, x2, x3, seed=[-1,2,0.5], pl, method="BS23", tol=1.e-4
    

 LAST MODIFIED:    Dec 12, 2018 by A. Mignone (mignone@to.infn.it)

(See field_line.pro)


FIND_SHOCK

[Previous Routine] [Next Routine] [List of Routines]

 NAME:         FIND_SHOCK

 AUTHOR:       Andrea Mignone (mignone@to.astro.it)

 PURPOSE:      Find shocks in a multidimensional plane

 SYNTAX:       array = FIND_SHOCK(p, vx, vy, vz
                                  [,eps_min=eps_min][,eps_max=eps_max])

 DESCRIPTION:  shockfind returns a multi-D array (with dimensionality
               equal to the input arrays) whose elements are
               numbers between 0 (no shock) and 1 (strong shock).

               A shock is detected when div.V < 0
               and |grad p|*dl_min/p > eps_min. 

               The strength of the shock is controlled by

               eps_min <  |grad p|/p < eps_max

               This function requires PTOOLS.

 ARGUMENTS and KEYWORDS:

              p:    an array giving the pressure distribution
              vx:   an array giving the x-component of velocity
              vy:   an array giving the y-component of velocity
              vz:   an array giving the z-component of velocity
              eps_min:  the minimum threshold for a shock to exist
              eps_max:  the maximum strength of a shock (in units
                        of |grad p|/p).


 LAST MODIFIED:   May 30, 2016 by A.Mignone (mignone@to.astro.it)

(See find_shock.pro)


FOURIER[1]

[Previous Routine] [Next Routine] [List of Routines]
 NAME:        FOURIER_1D

 AUTHOR:      A. Mignone (mignone@to.infn.it)

 PURPOSE:     Compute the fast Fourier transform of a 1D array or a
              mutldimensional array in a specific direction.
              Return the complex FFT along with the frequency array
              sorted in ascending order.

 SYNTAX:      FOURIER_1D, Q, xi, Qk, kxi[,/POWER][,DIMENSION=DIMENSION]

 ARGUMENTS:

   Q  [in]     A 1, 2 or 3D array to which the Fast Fourier Transform should
               be applied.
   xi  [in]    The coordinate array (e.g. time or space) in the
               direction across the FFT is desired.  
   Qk [out]    The output FFT array with dimensions identical to
               those of the input array.
   kxi [out]   The frequency array (output) corresponding to xi.

 KEYWORDS:

   DIMENSION   A scalar indicating the dimension across which to calculate
               the FFT.

   POWER      When enabled, the output array Qk will contain the normalized
              power.

(See fourier.pro)


FOURIER[2]

[Previous Routine] [Next Routine] [List of Routines]
 NAME:        FOURIER_2D

 AUTHOR:      A. Mignone (mignone@to.infn.it)

 PURPOSE:     Compute the fast Fourier transform of a 2D array.
              Return the 2D complex FFT along with the frequency arrays
              sorted in ascending order.

 SYNTAX:      FOURIER_2D, Q, x, y, Qk, kx, ky[, /POWER]

 ARGUMENTS:

   Q  [in]     The 2D array to which the Fast Fourier Transform should
               be applied.
   x  [in]     The coordinate array (e.g. time or space) relative to 1st dim.
   y  [in]     The coordinate array (e.g. time or space) relative to 2nd dim.
   Qk [out]   ĘThe output FFT array with dimensions identical to
               those of the input array.
   kx [out]    The frequency array (output) for the 1st dim.
   ky [out]    The frequency array (output) for the 2nd dim.

 KEYWORDS:

   POWER      When enabled, the output array Qk will contain the normalized
              power.

(See fourier.pro)


FOURIER[3]

[Previous Routine] [Next Routine] [List of Routines]
 NAME:        FOURIER_3D

 AUTHOR:      A. Mignone (mignone@to.infn.it)

 PURPOSE:     Compute the fast Fourier transform of a 2D array.
              Return the 2D complex FFT along with the frequency arrays
              sorted in ascending order.

 SYNTAX:      FOURIER_3D, Q, x, y, z, Qk, kx, ky, kz[, /POWER]

 ARGUMENTS:

   Q  [in]     The 2D array to which the Fast Fourier Transform should
               be applied.
   x  [in]     The coordinate array (e.g. time or space) relative to 1st dim.
   y  [in]     The coordinate array (e.g. time or space) relative to 2nd dim.
   z  [in]     The coordinate array (e.g. time or space) relative to 3rd dim.
   Qk [out]   ĘThe output FFT array with dimensions identical to
               those of the input array.
   kx [out]    The frequency array (output) for the 1st dim.
   ky [out]    The frequency array (output) for the 2nd dim.
   kz [out]    The frequency array (output) for the 3rd dim.

 KEYWORDS:

   POWER      When enabled, the output array Qk will contain the normalized
              power.

(See fourier.pro)


FOURIER[4]

[Previous Routine] [Next Routine] [List of Routines]
 NAME:        FOURIER

 AUTHOR:      A. Mignone (mignone@to.infn.it)

 PURPOSE:     Compute the fast Fourier transform of a 1- or 2D multidimensional
              array.
              Return the complex FFT along with the frequency array(s).
              This function is actually a wrapper for FOURIER_1D or FOURIER_2D.

 SYNTAX:      FOURIER, Q, x, Qk, kx[, /POWER][DIMENSION=DIMENSION]   (in 1D)

                or

              FOURIER, Q, x, y, Qk, kx,ky[, /POWER]                  (in 2D)
              

 ARGUMENTS:

   Q  [in]     The 1D or 2D array to which the Fast Fourier Transform should
               be applied.
   x  [in]     The coordinate array (e.g. time or space) relative to 1st dim.
   y  [in]     The coordinate array (e.g. time or space) relative to 2nd dim.
   Qk [out]    The output FFT array with dimensions identical to
               those of the input array.
   kx [out]    The frequency array (output) for the 1st dim.
   ky [out]    The frequency array (output) for the 2nd dim.


 KEYWORDS:

   DIM        A scalar indicating the dimension across which to calculate
              the FFT.
   POWER      When enabled, the output array Qk will contain the normalized
              power.

 EXAMPLES:

   IDL> Nx = 2048
   IDL> x  = 0.0 + DINDGEN(Nx)/(Nx-1.0); Generate a uniform grid in [0,1] 
   IDL> twopi = 2.0*!PI*x
   IDL> ; Build simple array with three frequencies
   IDL> Q  = 5.0*sin(twopi) + 2.0*cos(10.0*twopi) + cos(30.0*twopi)
   IDL> FOURIER, Q, x, Qk, k, /POWER
   IDL> PLOT, k, pwr, psym=-6,xrange=[-64,64], xstyle=1


 LAST MODIFIED:   March 29, 2019 by A. Mignone

(See fourier.pro)


GET_FRAME

[Previous Routine] [Next Routine] [List of Routines]


  NAME:      get_frame

  AUTHOR:    Andrea Mignone

  PURPOSE:   grab window's content and write
             an image file. The output file name is required.

  SYNOPSIS:  get_frame,name=name[,/jpg][,/tiff][,/png][,/ppm]
                                [,/gif][,quality=quality]


  KEYWORDS:  describe the image format.


  EXAMPLES
  
    #1 Read the current window content and dump it to rho.jpg:
    IDL> get_frame, name = "rho", /jpg


  LAST MODIFIED: Jan 13 2006 by A. Mignone (mignone@to.astro.it)


(See get_frame.pro)


H5LOAD

[Previous Routine] [Next Routine] [List of Routines]

 NAME:      H5LOAD

 AUTHOR:    C. Zanni

 REQUIRES:  HDF5 support.

 PURPOSE:   Read PLUTO variables stored in a (pixie) HDF5 data file 
            (static grid).  It is automatically called by PLOAD when the 
            /H5 keyword is supplied.

 SYNTAX:    H5LOAD, filename

 ARGUMENTS

   filename   = the data file name

 KEYWORDS 

   /SILENT    Set this keyword to suppress output

 LAST MODIFIED

   Sept 25, 2012 by C. Zanni (zanni@oato.inaf.it)

(See h5load.pro)


HDF5LOAD

[Previous Routine] [Next Routine] [List of Routines]

 NAME:      HDF5LOAD

 AUTHOR:    A. Mignone, O. Tesileanu, C. Zanni

 REQUIRES:  HDF5 support.

 PURPOSE:   Read a HDF5 Chombo data-file and store its content on the 
            variables vars. It is automatically called by PLOAD when the 
            /HDF5 keyword is supplied.

 SYNTAX:    HDF5LOAD, nout[, VAR=string][, FILENAME=string][, /INTERP]
                          [,LEVEL=value][,{X | Y | Z}RANGE=[min,max]]
                          [, /NO_VAR_MATCH][,/NODATA]

 KEYWORDS

   VAR      = the variable name, e.g. "rho" or "bx2"
   FILENAME = the file name. If omitted, "data.nnnn.hdf5" is assumed.
   LEVEL    = the output level resolution (default = 0)
   INTERP   = set this keyword if you wish to interpolate a coarse level
              down to the resolution of the selected level using bilinear
              interpolation provided by REBIN. Otherwise nearest REBIN uses
              nearest neighbor sampling for both magnification and minification.
   X1RANGE = a 2 element vector giving the x-range of the portion
             to be extracted.
   X2RANGE = a 2 element vector giving the y-range of the portion
             to be extracted.
   X3RANGE = a 2 element vector giving the z-range of the portion
             to be extracted.
   NO_VAR_MATCH = do not try to match variable names with those provides 
                  by PLUTO and copy the corresponding storage areas
                  (e.g. rho, vx1, vx2, etc...). In other words, all variables 
                  read from the HDF file are stores inside vars(i,j,k,nv). 
                  Useful when HDF5LOAD is called by another function (e.g.
                  HDF5CUT).

 EXAMPLES:

  * Example #1: read "data.0002.hdf5" and set the output file resolution
                equivalent to the 4th level of refinement:

                IDL> HDF5LOAD, 2, lev=4


  * Example #2: read "data.0005.hdf5" and set the output file resolution
                equivalent to the 2th level of refinement:

                IDL> HDF5LOAD, 5, lev=2, var="v1"


 LAST MODIFIED

   Sept 7, 2015 by A. Mignone (mignone@ph.unito.it) & C. Zanni (zanni@oato.inaf.it)

(See hdf5load.pro)


MIRROR

[Previous Routine] [Next Routine] [List of Routines]
 NAME:   MIRROR
 
 AUTHOR:   A. Mignone

 PURPOSE:  Build a symmetric image out of a bidimensional array a.

 SYNTAX:  MIRROR, a[, LEFT=left][, RIGHT=right][, TOP=top][, BOTTOM=bottom]

 ARGUMENTS:  

   a   = 2D array

 KEYWORDS

  One keyword between LEFT, ..., BOTTOM should be given with values equal to

  1 = reflect the image w/ respect to the axis
     [useful w/ reflective boundary conditions]

  2 = reflect the image w/ respect to the axis midpoint
      [useful w/ point-reflective boundary conditions]

  3 = do not reflect, simply copy the array
      [useful w/ periodic boundary conditions]

 LAST MODIFIED:   Aug 21, 2012 by A. Mignone (mignone@ph.unito.it)

(See mirror.pro)


OPLOTBOX

[Previous Routine] [Next Routine] [List of Routines]

 NAME:      OPLOTBOX

 AUTHOR:    A. Mignone

 PURPOSE:   overplot the AMR box layout on the current window.
            The axis of the plot should be scaled to physical units.
            (e.g. display should have been called with x1=x1,x2=x2 keywords).


 SYNTAX:    OPLOTBOX, [, CTAB=integer][, CVAL=vector][, LRANGE=[min,max]][, /POLAR]
                      [,_EXTRA=extra]
                      

 KEYWORDS

   CTAB = an integer giving the color table to be used when plotting
          the boxes. Default is the current color table.
          When CTAB=12 or CTAB=23, color indices are pre-defined to
          default values so that level 0 is always red, level 1 is green,
          and so forth.

   CVAL = on output, it returns an array of integers with the 
             corresponding color indices used to draw the boxes.
             Useful for legends.
   LRANGE = a two element integer array of the form [minlev, maxlev] giving
            the minimum and maximum levels to be plotted.
            
   /POLAR  = plot the AMR box layout over a /POLAR display (spherical and polar coordinates) 

   OPLOTBOX also accepts keyword inheritance via the _EXTRA keyword to be passed to plots

 EXAMPLES:

  * Example #1: plot boxes on the current graphic device: 

                IDL> OPLOTBOX

  * Example #2: display density maps leaving extra space for a
                legend plot (rgt=140), overplot the boxes and then 
                add a legend:

              IDL> display,q,x1=x1,x2=x2,rgt = 140
              IDL> oplot,cval=vals
              IDL> legend, ["Level "+strcompress(string(indgen(4)),/remove_all)],$
                   line=0,colors=vals,pos=[0.83,0.9],/normal,spac=0.1


 LAST MODIFIED

   May 17th, 2011 by A. Mignone (mignone@ph.unito.it)

(See oplotbox.pro)


PARTICLES_LOAD[1]

[Previous Routine] [Next Routine] [List of Routines]

 NAME:      PARTICLES_BINARY_LOAD

 AUTHOR:    Andrea Mignone

 PURPOSE:

   Read PLUTO particle file in .flt or .dbl binary data format. 
   Called from PARTICLES_LOAD with the /FLOAT (or no) keywords.
   
 SYNTAX:

   PARTICLES_BINARY_LOAD, fname[, /FLOAT][, /SILENT], endianity, err
   
 ARGUMENTS:

   fname      The name of a valid .flt or .dbl particle file.

 KEYWORDS:

    LP        Keyword to denote LP module. Needed to avoid printing Totparticles
              nchunk values, which are not defined for other modules.s
  
 EXAMPLES:

  * Example #1: Load the 10-th particles output file:

    IDL> PARTICLES_LOAD, 10


 LAST MODIFIED:

  Mar 08, 2021 by D. Mukherjee & A. Mignone (dipanjan.mukherjee@unito.it)

(See particles_load.pro)


PARTICLES_LOAD[2]

[Previous Routine] [Next Routine] [List of Routines]

 NAME:      PARTICLES_VTK_LOAD

 AUTHOR:    Andrea Mignone

 PURPOSE:

   Read PLUTO particles file in .vtk data format. 
   Called from PARTICLES_LOAD with the /VTK keyword.
   
 SYNTAX:

   PARTICLES_VTKLOAD, fname
   
 ARGUMENTS:

   fname      The name of a valid .vtk paticle file.

 KEYWORDS:


 EXAMPLES:

  * Example #1: Load the 10-th particles output file:

    IDL> PARTICLES_LOAD, /VTK,10


 LAST MODIFIED:

  April 6, 2018 by D. Mukherjee (dipanjan.mukherjee@unito.it)

(See particles_load.pro)


PARTICLES_LOAD[3]

[Previous Routine] [Next Routine] [List of Routines]

 NAME:      PARTICLES_LOAD

 AUTHOR:    Andrea Mignone

 PURPOSE:  

   Read PLUTO particles file in .dbl, .flt and .vtk format.
   By default, if neither /VTK or /FLOAT are given, double precision 
   raw-binary files are read (particles.nnnn.dbl). 
   
   Data is read and stored in the 'particle' array of structures which has
   variables size depending on the actual number of particles (nparticles).
   Both particle and nparticles can be shared among different routines using
   the PLUTO_VAR common block.    

 SYNTAX:

   PARTICLES_LOAD, nout[, DIR=DIR][, SILENT=SILENT][, FLOAT=FLOAT][, VTK = VTK]

 ARGUMENTS:

   nout  = the output number, e.g., 0,1,2, ...
   nchunk = the particle sub-file for a given nout. e.g. nchunk=1 if particles.0001_ch00.dbl
           is to be loaded. nchunk=0 by default and may be omitted for particles.0001_ch00.dbl

 KEYWORDS:

   DIR        the directory name where output files are located (e.g. 
              DIR = 'Data1/'). Default is current directory.

   /SILENT    set this keyword to suppress printing information

   /FLOAT     set this keyword to read single precision binary datafile
              (particles.nnnn.flt).

   /FLT       short for FLOAT with same function. Shorter name for easier usage.
 
              
   /VTK       set this keyword to read .vtk particle files.
              In this case, the PARTICLES_VTKLOAD procedure is invoked.
   
   /LP        set this keyword to read particle output for Lagrangian Particle (LP) module

 EXAMPLES:

  * Example #1: Load the 10-th particles output file in single precision
                and print the x2-component of velocity of the 4-th particle:

    IDL> PARTICLES_LOAd,10,/FLOAT      ;--Loads particles from particles.0010.flt.00
    IDL> PRINT,particles[4].vx2

    IDL> PARTICLES_LOAd,10,1,/FLOAT    ;--Loads particles from particles.0010.flt.01
    IDL> PARTICLES_LOAd,10,/FLOAT,/ALL ;--Loads particles from all particles.0010.flt.*

 LAST MODIFIED:

  October 19, 2018 by D. Mukherjee (dipanjan.mukherjee@unito.it)

(See particles_load.pro)


PARTICLES_OPLOT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:      PARTICLES_OPLOT

 AUTHOR:    Andrea Mignone

 PURPOSE:  

   Overlay point particles on a pre-existing 2D plot.

 SYNTAX:

   PARTICLES_OPLOT, particles,
                   [, cvalue_max = cvalue_max][, cvalue_min = cvalue_min]
                   [, field=field][, symsize=symsize]


 ARGUMENTS:

   none

 KEYWORDS:

   symsize      = the symbol size. By default particles are plotted with
                  circles.


   color        = defines the color of the particle. To color all particles
		   with same value, put one number. To color each particle 
		   differently based on some attribute e.g. particle kinetic energy
                  or part.color, give an array of size number of particles. The 
                  color is normalised to lie in range 0-255 of the session's color
                  table. Default 255.


   cmax         = the maximum value of the color to be plotted. Values higher are
		   set to 255.


   cmin         = the minimum value of the color to be plotted. Values lower are
		   set to 0.


   x1p          = An array of dimension: nparticles, giving the x1 coordinates
		   to be plotted


   x2p          = An array of dimension: nparticles, giving the x2 coordinates 
                  to be plotted. 
		   For 2D plots, default is x1=x1,x2=x2. Need not be specified.
		   For 3D runs, x1,x2 should be specified if x3 coordinate
		   needs to be plotted.
		   

 EXAMPLES:

  * Example #1: Load fluid and particles data. Overplot them.

    IDL> PLOAD, 10                    ; Load fluid data file (in .dbl format)
    IDL> DISPLAY,rho, x1=x1, x2=x2    ; Display density
    IDL> PARTICLES_LOAD, 10           ; Load particle data file (int .dbl format)
    IDL> PARTICLES_OPLOT, particles   ; Overlay particles on the plot generated
                                      ; by previous DISPLAY call.

  * Example #2: Overplot just a subsamples of particles

    IDL> Ek    = 0.5*(particle.vx1^2 + particle.vx2^2 + particle.vx3^2)
    IDL> indx  = WHERE (Ek GT 0.9*MAX(Ek)); Select most energetic particles
    IDL> part1 = particle(indx) 
    IDL> PARTICLES_OPLOT, part1        


  * Example #3: Overplot for 3D PLUTO data array to make x-z slice

    IDL> PLOAD, 1, var='vx3'                                        
    IDL> PARTICLES_LOAD,1                                         
    IDL> DISPLAY, x1=x1, x2=x3, (vx3[*,nx2/2,*]), /vbar   

    ;---Select particles in the y=0 plane. See particles_slice.pro for more.
    IDL> part1 = PARTICLES_SLICE(particles, xar=x2, dx=dx2, /xz) 

    ;---Plot all particles with color=255 
    IDL> PARTICLES_OPLOT, part, x1p=part1.x1, x2p=part.x3, color=255

    ;---Plot particles with color based on value of field color
    IDL> PARTICLES_OPLOT,part, x1p=part.x1, x2p=part.x3, $
        color=part.color, cvalue_min=0, cvalue_max=4

    ;---Plot particles with color based on kinetic energy
    IDL>  ek = 0.5*(part.vx1^2.+part.vx2^2.+part.vx3^2.)         
    IDL>  PARTICLES_OPLOT, part, x1p=part.x1, x2p=part.x3, color=ek 


 LAST MODIFIED:

 June 15, D. Mukherjee (dipanjan.mukherjee@unito.it) 

(See particles_oplot.pro)


PLOAD[1]

[Previous Routine] [Next Routine] [List of Routines]
 NAME: PRINT_MEMORY_USAGE

 PURPOSE: print memory usage in megabytes

(See pload.pro)


PLOAD[2]

[Previous Routine] [Next Routine] [List of Routines]
 NAME:      ARRAY_EXTRACT

 AUTHOR:    Andrea Mignone (mignone@ph.unito.it)

 PURPOSE:   extract a sub-array from a 2 or 3D data set

 SYNTAX:    ARRAY_EXTRACT, q, x1range, x2range, x3range, indx[, /SILENT][, /VECTOR]

 ARGUMENT:

   q          an associated file variable with a 2D structure,
              e.g., q[k] = f(i,j). 

   x1range    a 2D vector [min,max] specifying the x1 bounds of the 
              sub-domain to be extracted.

   x2range    a 2D vector [min,max] specifying the x2 bounds of the 
              sub-domain to be extracted.

   x3range    a 2D vector [min,max] specifying the x1 bounds of the 
              sub-domain to be extracted.

   indx       a 6 element integer array containing the grid indices of
              the extracted array [ibeg, iend, ..., kbeg, kend]

 KEYWORDS: 

   /SILENT      suppress output

   /VECTOR      When this keyword is supplied, the input associated file variable
                is assumed to have a 3D structure of the type q[k] = f(c, i, j) where 
                'c' specify the vector component (useful for VTK extraction).

 LAST MODIFIED:

   August 1st, 2013 by A. Mignone (mignone@ph.unito.it)

(See pload.pro)


PLOAD[3]

[Previous Routine] [Next Routine] [List of Routines]

 NAME:      PLOAD

 AUTHOR:    Andrea Mignone

 PURPOSE:  

   Provides a convenient and flexible way to read PLUTO data files written
   in different formats: binary (.dbl/.flt), hdf5 (.dbl.h5/.flt.h5), VTK (.vtk)
   and  chombo-hdf5 (.hdf5).
   Data is read and stored in the three common blocks PLUTO_GRID (grid-related
   information), PLUTO_VAR (variable arrays) and PLUTO_RUN (time-step info).
   PLOAD must be invoked prior to any other function for properly initializing 
   the common blocks containing useful information specific to  the data being
   read. 
   The common blocks are:

   PLUTO_GRID -> contains grid information: this is read using
                 the READ_PLUTO_GRID function.

      NX1  =  number of points in the x1 direction
      NX2  =  number of points in the x2 direction
      NX3  =  number of points in the x3 direction
      x1  =  1-D array of NX1 points containing the x1 zone centers
      x2  =  1-D array of NX2 points containing the x2 zone centers
      x3  =  1-D array of NX3 points containing the x3 zone centers
      dx1 =  1-D array of NX1 points containing mesh widths
      dx2 =  1-D array of NX2 points containing mesh widths
      dx3 =  1-D array of NX3 points containing mesh widths
      xpos = a 2D array containing the x-coordinate values (useful for 
             non-Cartesian geometry);
      ypos = same as xpos but containing y-coordinate values.
      AMRLevel = an array of structures, each containing a collection of
                 rectangular AMR boxes (see HDF5LOAD) 
      AMRBoxes = an array giving the level number as a function of the 
                 coordinate indices.

   PLUTO_VAR -> contains the number of variables (=NVAR) and the corresponding
                file names:

      rho           = density
      vx1, vx2, vx3 = velocity components
      Bx1, Bx2, Bx3 = magnetic field components
      prs           = pressure
      tr1, ...      = passive scalars
      Bx1s, Bx2s, Bx3s = staggered components of magnetic field (only with 
                         double precision binary data files) available with 
                         constrained transport.
      Ex1s, Ex2s, Ex3s = staggered components of electric field (only with 
                         double precision binary data files) available with 
                         constrained transport in Resistive RMHD.
                      
   PLUTO_RUN -> contains time-related information:

      t     = time at the corresponding output number
      dt    = time step at the corresponding output number
      nlast = the last written file

   File and variable names are read from the corresponding .out file (e.g. 
   flt.out, dbl.out, dbl.h5.out, etc...)

  
 SYNTAX:

   PLOAD, nout[, /ASSOC,][,DIR=string][, /FLOAT][,/H5][,/HDF5][,/NODATA]
              [,SHRINK=integer][,/SILENT][, VAR=string][,/VTK][,/XYASSOC]
              [{X1 | X2 | X3}RANGE=[min,max]][, _EXTRA = extra]

 ARGUMENTS:

   nout = the sequential output number, e.g., 0,1,2, ...

 KEYWORDS:

   /ASSOC   = use IDL file-association rather than storing files into memory,
              This can be particularly useful for large data sets.

   DIR      = the directory name where output files are located (e.g. 
              DIR = 'Data1/'). Default is current directory.

   /FLOAT   = set this keyword if you wish to read single precision
              data rather than double.
              The default will try to read dbl (if possible) and
              will automatically switch to /float if dbl.out is not found.

   /H5      = assume data is in (pixie) HDF5 format used by the static grid
              version of PLUTO. Double precision data files (.dbl.h5) are 
              searched for by default. 
              Single precision files (.flt.h5) can be read by specifying 
              also the /FLOAT keyword.

   /HDF5    = assume data is in a Chombo HDF5 data file.
              When this keyword is specified, PLOAD only acts as a wrapper 
              for the HDF5LOAD  procedure which actually reads the HDF5
              datafile(s).
              In this case, different KEYWORDs are supported, see the 
              documentation for HDF5LOAD.

   /NODATA  = read grid information only. Do not attempt to read/store
              data (useful for large data sets)

   SHRINK   = an integer number > 1 specifying how much the data has to be 
              shrinked in all directions (only for .dbl and .flt data formats). 
              The original array is never stored into memory and resampling is 
              done slice by slice.
              Beware that the grid is redefined accordingly.
              Useful for large 3-D data sets.
              IMPORTANT: non-uniform mesh are not properly accounted for
                         and the interpolation may be inaccurate.

   /SILENT  = set this keyword to suppress output generated by pload.

   VAR      = the name of a particular variable to be loaded, e.g., "prs" (only
              for .dbl or .flt data formats). The remainig ones are ignored.

   /VTK     = assume data is in VTK format (single precision).

   /XYASSOC = associate an array of 2-D data out of a 3-D data file (only for 
              .dbl and .flt data formats). Each index 'k' of the array 
              corresponds to an XY plane sliced at different z=z(k).

   X1RANGE   = a 2-element vector in the form [xbeg,xend]
               giving the x1 axis range to be extracted from the data
               (only for .dbl and .flt data formats).
               Only the specified subset is stored into memory and the grid
               is redefined accordingly. Useful for large datasets.

   X2RANGE   = same as x1range but for the x2-axis.

   X3RANGE   = same as x1range but for the x3-axis.


   Please note that '/XYASSOC' and 'SHRINK' are mutually incompatible.

 EXAMPLES:

  * Example #1: retrieves the 10th output data set in double precision 
                from the "My_Data/" directory and store data in the 
                variables {rho, vx1, vx2, ...}:

    IDL> PLOAD, 10, DIR = 'My_Data/'


  * Example #2:  open all files and associate the variables {rho,vx1,...}
                 to of 2D XY slices at constant z planes.
                 For instance, rho(k) will be a 2D slice containing density
                 in the XY plane at z=z(k):

    IDL> PLOAD, /FLOAT, /XYASSOC, 7


  * Example #3: open the single-precision datafile containing 'rho'
                and resize the whole array by making it a factor of 2 smaller.
                The new grid will be halved respect to the original one.
                Other variables will be discarded:

    IDL> PLOAD, /FLOAT, 84, VAR="rho", SHRINK=2


  * Example #4: extract a 3D portion of the domain from a VTK file using 
                the range keywords. 
                The content is stored into {rho,vx1,vx2,...}.

    IDL> PLOAD, 1, /VTK, X1RANGE=[0, 40], X2RANGE=[-10,10], X3RANGE=[-10,10]


  * Example #5: load "vx2" from a HDF5 Chombo-data file "data.0004.hdf5"
                with the uniform resolution corresponding to level 3:

    IDL> PLOAD,/hdf5,4,level=3, var="vx2"


 LAST MODIFIED:

  May 25, 2018 by A. Mignone (mignone@ph.unito.it)

(See pload.pro)


POLAR

[Previous Routine] [Next Routine] [List of Routines]

 NAME:      polar

 AUTHOR:    Andrea Mignone

 PURPOSE:   Interpolates the surface array a from polar coordinates (r, theta) to
            rectangular coordinates (x, y).
            On output, a is replaced by the array in cartesian coordinates,
            while r becomes x, theta becomes y. The array a can be
            irregularly gridded. This function uses the polar_surface
            routine of IDL.

            Note: if spherical polar coordinates
                  are use, then simply let
                  x2 = !pi/2. - x2

 SYNTAX:    polar, a, x1, x2[,sample=sample][,missing=missing]

 KEYWORD & PARAMETERS:

        see IDL manual page for polar_surface.


 DATE:     Aug 20, 2004

(See polar.pro)


PTOOLS[1]

[Previous Routine] [Next Routine] [List of Routines]

 NAME:        PAVERAGE

 AUTHOR:      A. Mignone (mignone@ph.unito.it)

 SYNTAX:      q_av = PAVERAGE(q, /geometry, dir=dir)

 PURPOSE:     compute the volume-average of a 2D or 3D array "q" over the 
              computational grid defined during the most recent call to the 
              PLOAD function.
              On output, "q_av" is either a scalar - if the average is taken
              over all directions - or an array of reduced size if the 
              average considers only some of the coordinates.
              The dimensionality of the array decreases by one each time 
              a coordinate axis is averaged down.

 ARGUMENTS:   

   q          2D or 3D array with (NX1,NX2) or (NX1,NX2,NX3) points, 
              respectively.
                      
 KEYWORDS:

   /geometry   Specify the geometry to be adopted. 
               Options are: /polar, /cylindrical (2D) and /spherical.
               If none is given, a Cartesian mesh will be assumed.

   dir         an array of integers giving the directions over which 
               the average has to be taken. 
               For instance, dir=[0,1,1] will average along x2 and x3 and
               the output will be a 1D array function of x1.
              
 EXAMPLES:

  * Example #1: compute the average of density in 3D spherical coordinates,

    IDL> rho_av = PAVERAGE(rho,/spherical)

  * Example #2: compute the average of vorticity along the phi and z 
                directions in 3D polar coordinates:

    IDL> w = PCURL(v1,v2,/polar)
    IDL> wr = PAVERAGE(w,dir=[0,1,1],/polar)

 LAST MODIFIED:   Jan 29, 2012 by A. Mignone (mignone@ph.unito.it)

(See ptools.pro)


PTOOLS[2]

[Previous Routine] [Next Routine] [List of Routines]

 NAME:        PDIFF

 AUTHOR:      A. Mignone (mignone@ph.unito.it)

 SYNTAX:      dq = PDIFF(q, /X1_DIR, /X2_DIR, /X3_DIR, /PERIODIC)

 PURPOSE:     Compute the derivative of a 2D or 3D array "q" in the 
              direction given by either one of /X1_DIR, /X2_DIR or /X3_DIR.
              The computational grid is defined from the most recent call 
              to the PLOAD function.
              On output, "dq" is an array of the same size containing
              the derivative of the function computed using standard
              central finite differences. At boundaries, one sided 
              backward of forward differences are used, unless the /PERIODIC
              keyword is used.

 ARGUMENTS:   

   q          2D or 3D array with (NX1,NX2) or (NX1,NX2,NX3) points, 
              respectively.
                      
   Xn_DIR     either one of X1_DIR, X2_DIR, X3_DIR setting the direction 
              (x1, x2 or x3) along which the derivative should be
              taken.

 KEYWORDS:

   PERIODIC   assume the domain is periodic in the specified direction. 
              Central difference is used throughout, including boundaries.
              
 LAST MODIFIED:   Dec 28, 2016 by A. Mignone (mignone@ph.unito.it)

(See ptools.pro)


PTOOLS[3]

[Previous Routine] [Next Routine] [List of Routines]

 NAME:        PCURL

 AUTHOR:      A. Mignone (mignone@ph.unito.it)

 SYNTAX:      curl_v = PCURL(v1,v1[,v3],/geometry)

 PURPOSE:     compute the curl of a vector field {v1,v2} (in 2D) or 
              {v1,v2,v3} (in 2.5D or 3D) on the computational grid defined
              during the most recent call to the PLOAD function.
              On output, "curl_v" contains the three components of the curl
              stored as 

                 dq[*,*,*,0] -> (curl_v)_x1
                 dq[*,*,*,1] -> (curl_v)_x2
                 dq[*,*,*,2] -> (curl_v)_x3
              
              Note: if only 2 vector components are supplied, the output
                    consists in a single 2D array w which, in the case
                    Cartesian coordinates, is w = dv2/dx1 - dv1/dx2.
 ARGUMENTS:   

   v1,v2[,v3]   2D or 3D arrays with (NX1,NX2) or (NX1,NX2,NX3) points, 
                respectively, giving the vector components along the 
                three coordinate directions.
                       
 KEYWORDS:

   geometry   specify the geometry. 
              Possible options are /cylindrical (only 2D), /polar or /spherical. 
              If none is given, Cartesian coordinates are assumed.
                          
 EXAMPLES:

  * Example #1: compute the vorticity in 2D polar coordinates:

    IDL> drho = PCURL(vx1, vx2, /polar)

  * Example #2: compute the three components of the electric current in 3D
                Cartesian coordinates and take the modulus:

    IDL> J = PCURL(Bx1, Bx2, Bx3)
    IDL> J2 = J[*,*,*,0]^2 + J[*,*,*,1]^2 + J[*,*,*,2]^2

 LAST MODIFIED:   Dec 28, 2016 by A. Mignone (mignone@ph.unito.it)

(See ptools.pro)


PTOOLS[4]

[Previous Routine] [Next Routine] [List of Routines]

 NAME:        PGRAD

 AUTHOR:      A. Mignone (mignone@ph.unito.it)

 SYNTAX:      dq = PGRAD(q,/GEOMETRY)

 PURPOSE:     compute the gradient of a scalar function "q" on the 
              computational grid defined during the most recent call to
              the PLOAD function.
              On output "dq" contains the three components of the gradient
              stored as 

                 dq[*,*,*,0] -> dq/dx1
                 dq[*,*,*,1] -> dq/dx2
                 dq[*,*,*,2] -> dq/dx3
              
 ARGUMENTS:   

   q          a 2D or 3D array with (NX1,NX2) or (NX1,NX2,NX3) points, 
              respectively. Grid information must already have been stored
              during the most recent call to PLOAD function.

 KEYWORDS:

   GEOMETR   specify the geometry. 
             Possible options are /POLAR or /SPHERICAL. 
             If none is given, Cartesian coordinates are assumed.
                          
 EXAMPLES:

  * Example #1: compute the gradient of rho in spherical coordinates:

    IDL> drho = PGRAD(rho, /SPHERICAL)

 LAST MODIFIED:   Dec 28, 2016 by A. Mignone (mignone@ph.unito.it)

(See ptools.pro)


PTOOLS[5]

[Previous Routine] [Next Routine] [List of Routines]

 NAME:        PDIV

 AUTHOR:      A. Mignone (mignone@ph.unito.it)

 SYNTAX:      div_v = PDIV(v1,v2[,v3],/geometry)

 PURPOSE:     compute the divergence of a vector field {v1,v2} (in 2D) or 
              {v1,v2,v3} (in 2.5D or 3D) on the computational grid defined
              during the most recent call to the PLOAD function.
              On output, "div_v" contains the divergence.
              
 ARGUMENTS:   

   v1,v2[,v3]   2D or 3D arrays with (NX1,NX2) or (NX1,NX2,NX3) points, 
                respectively, giving the vector components along the 
                three coordinate directions.
                       
 KEYWORDS:

   geometry   specify the geometry. 
              Possible options are /polar or /spherical. 
              If none is given, Cartesian coordinates are assumed.
                          
 EXAMPLES:

  * Example #1: compute the vorticity in 2D polar coordinates:

    IDL> divB = PDIV(Bx1,Bx2, /polar)


 LAST MODIFIED:   Dec 28, 2016 by A. Mignone (mignone@ph.unito.it)

(See ptools.pro)


PUT_EPS

[Previous Routine] [Next Routine] [List of Routines]

  NAME:      put_eps

  AUTHOR:    Andrea Mignone

  PURPOSE:   Put a single encapsulated postscript figure in
             a multi-plot file.

  SYNTAX:    put_eps, data, x, y, pos
             [,xtitle=xtitle][,ytitle=ytitle][,title=title][,charsize=charsize]
             [,dmax = dmax][,dmin = dmin][,/vbar][,/hbar][,color=color]
             [,cbwidth=cbwidth][,cbcharsize=cbcharsize][cbdiv=cbdiv]
             [,cbformat=cbformat][,cbposition=cbposition]
             [,/noxticks][,/noyticks][,xrange=xrange][,yrange=yrange]

             where data is a two-dimensional array, x and y
             are the coordinates, pos=[x0,y0,x1,y1] is the position
             of the figure in the multiplot file,
             calculated with set_multi_plot_pos.

  KEYWORDS:


     xtitle = the string name for the x-axis

     ytitle = the string name for the y-axis

     title  = the string name for the title

     dmax   = a floating point number giving the maximum value
              data value to which the image should be scaled to.

     dmin   = a floating point number giving the minimum value
              data value to which the image should be scaled to.

     vbar   = set this keyword to put a vertical colorbar to the right
              of the image.

     hbar   = set this keyword to put a horizontal colorbar to
              the top of the image.

     color   = an integer giving the color (in the current color table)
               of the axis.

     charsize = size of characters used for colorbar

     noxticks = suppress x-tick marks

     noyticks = suppress y-tick marks

     sample   = increase resolution by combining sub-sampling and
                interpolation.

     xrange = a two element vector giving the range in the x direction

     yrange = a two element vector giving the range in the y direction

  COLORBAR CONTROL KEYWORDS:

     cbwidth    = the horizontal extent of the colorbar in units
                  of the image (only if /vbar or /hbar is given).

     cbcharsize = size of characters used for colorbar

     cbdiv      = the number of divisions of the colorbar.

     cbformat   = the string format used in the colorbar

     cbposition = lower left position of the colorbar

  LAST MODIFIED:  Dec 12, 2018 by A. Mignone (mignone@ph.unito.it)

(See put_eps.pro)


REGRID

[Previous Routine] [Next Routine] [List of Routines]

  NAME:      REGRID

  AUTHOR:    Andrea Mignone (mignone@ph.unito.it)

  PURPOSE:   Linearly interpolate irregularly-gridded data to a
             a regular grid. Interpolation is done
             separately row by row and column by column.
             On output the original arrays are replaced with the
             the new ones.

  SYNTAX:    REGRID, img, x1, x2[,n1=integer][,n2=integer]
                     [, {X | Y}RANGE = [min,max]]



    img = a 2-D array.

    x1  = a 1-D array with the abscissa of img

    x2  = a 1-D array with the ordinata of img


  NOTICE: On output, img, x1 and x2 are replaced by the new
          regridded arrays. x1 and x2 will have uniform spacing.



  KEYWORDS:

    n1  = the number of points in the regular grid (x direction)

    n2  = the number of points in the regular grid (y direction)

    XRANGE = a two dimensional vector [xbeg, xend] defining
             the lower and upper points of the new grid in
             the x direction

    YRANGE = a two dimensional vector [ybeg, yend] defining
             the lower and upper points of the new grid in
             the y direction



  LAST MODIFIED:  Feb 4, 2006

(See regrid.pro)


SET_MULTI_PLOT_POS

[Previous Routine] [Next Routine] [List of Routines]

  NAME:      set_multi_plot_pos

  AUTHOR:    Andrea Mignone (mignone@to.astro.it)

  PURPOSE:   Compute position coordinates for multi plot figures

  SYNTAX:    pos = set_multi_plot_pos(ncol,nrow),
                   [,top=top][,bot=bot][,lft=lft][,rgt=rgt]
                   [,xsep=xsep][,ysep=ysep]


             where nrow and ncol are the number of rows and columns
             in the plot. Note: this function only computes
             the coordinates for the position vector; it does not
             produce any plot!
             On output, pos(i,j,*) will be a 1-D array giving
             the position of the plot as (x,y,x+xsep,y+ysep).
             For example, in a 2 x 2 multiplot figure you have

             pos(0,0)    pos(1,0)

             pos(0,1)    pos(1,1)

  KEYWORDS:


       top = a scalar specifying the space between the top margin and
             the first row

       bot = a scalar specifying the space between the bottom margin and
             the last row

       lft = a scalar specifying the space between the left margin and
             the first column

       rgt = a scalar specifying the space between the right margin and
             the last column

       xsep = horizontal separation between plots

       ysep = vertical separation between plots


  LAST MODIFIED:  March 12, 2007

(See set_multi_plot_pos.pro)


TEMPERATURE

[Previous Routine] [Next Routine] [List of Routines]

 NAME:        TEMPERATURE

 AUTHOR:      A. Mignone (mignone@ph.unito.it)

 SYNTAX:      Tmp = TEMPERATURE(Unit_Vel=Unit_Vel)

 PURPOSE:     Compute and return the temperature (in K) from PLUTO Data files.
              Temperature is calculated as T = p/rho * mu(X) * V0*mu/kB,
              where mu(x) is the mean molecular weight (re-implemented here),
              mu is the mean molecular weight, kB is the Boltzmann constant and
              V0 is the unit velocity (in c.g.s units).
              It employs pressure, density and chemical composition (when 
              SNEq or MINEq) are used.

 ARGUMENTS:

   Unit_Vel   The unit velocity (in cm/s) used by PLUTO

 KEYWORDS:

 LAST MODIFIED:   July 12, 2014 by A. Mignone (mignone@ph.unito.it)

(See temperature.pro)


VECFIELD

[Previous Routine] [Next Routine] [List of Routines]

  NAME:      VECFIELD

  AUTHOR:    A. Mignone (mignone@ph.unito.it)

  PURPOSE:   Produces a two-dimensional velocity field plot. 

  SYNTAX:    VECFIELD, U, V, X, Y[,SPACING=value][,/POLAR][,EXTRA]

  KEYWORDS:

       U = the X component of the two-dimensional field. 
           u must be a two-dimensional array.

       V = the Y component of the two-dimensional field. 
           v must be a two-dimensional array.

       X = the x-coordinate

       Y = the y-coordinate

       SPACING = the spacing between one arrow and the next
                 Higher values will produce a more "rarefied" plot

       POLAR = set this keyword if the input data are in polar coordinates
               (i.e. U = vr, V = vphi, x = r, y = phi) and the vector plot
               should be output in cartesian coordinates.
               This is useful when combined with DISPLAY, e.g.,

               IDL> DISPLAY,x1=x1,x2=x2,/polar,rho
               IDL> VECFIELD,v1,v2,x1,x2,/POLAR,/OVERPLOT
               
               Note: for spherical input data (u,v)=(vr,vth) simply call 
                     VECFIELD with x2 -> 0.5*!PI-x2 and v -> -v.

       EXTRA = all the keyword accepted by velovect, such as

               /overplot, length, etc...


  LAST MODIFIED:    Aug 27, 2012

(See vecfield.pro)


VTK_LOAD

[Previous Routine] [Next Routine] [List of Routines]

 NAME:      VTK_LOAD

 AUTHOR:    A. Mignone

 PURPOSE:   Read PLUTO variables stored in a VTK data file. 
            It is automatically called by PLOAD when the /VTK keyword
            is supplied.

 SYNTAX:    VTK_LOAD, filename[, KSLICE=integer][, /SILENT][, VAR=string]
            [, {X1 | X2 | X3}RANGE=[left,right]]

 ARGUMENTS

   filename   the data file name

 KEYWORDS 

   KSLICE        Set this keyword to an integer specifying the array index
                 of the 3rd coordinate. This will read and store a 2D array
                 (e.g. rho[*,*] at z = z[k]) rather then the full 3D array.
                 Useful for large datasets.

   /SILENT       Set this keyword to suppress output.

   VAR           the name of a particular variable to be loaded, e.g., 
                 "prs". The remainig ones are ignored.

   {X1 | X2 | X3}RANGE    A 2 elements array giving the desired data range of 
                          the axis.
                          

 LAST MODIFIED

   Dec 5, 2013 by A. Mignone (mignone@ph.unito.it)

(See vtk_load.pro)


WRITE_VTK

[Previous Routine] [List of Routines]

 NAME: WRITE_VTK

 AUTHOR:  Andrea Mignone (mignone@ph.unito.it)

 PURPOSE:  Create a VTK data file out of a PLUTO binary file assuming
           the grid information previously obtained with pload. 
           A scalar VTK file is created if only one argument is given;
           otherwise a VTK vector file is created if 3 arguments are given.
   
 SYNTAX: WRITE_VTK, QX[, QY, QZ][,FILENAME=string][,VARNAME=string]
                      [/APPEND][REBIN_ARRAY=REBIN_ARRAY]

 ARGUMENTS:

   QX    = a 3D single-precision (float) binary data to be written
           in the VTK file.

   QY,QZ = the y- and z- components of the vector fields to be 
           written.

   FILENAME = the name of the output VTK file. Default is "data.vtk". 

   VARNAME  = the name of the variable appearing in the VTK header.
              Default is "IDL_var".

 KEYWORDS:

  /APPEND:       open file and append data
  REBIN_ARRAY:   an array of integers giving the dimension of the rebinned
                 array. For instance, setting rebin_array=[nx1/2,nx2/2,nx3/2]
                 will produce an array with halved size.
                 The original array and coordinates will be replaced by
                 new ones.

 LAST MODIFIED:

  Dec 19, 2013 by A. Mignone (mignone@ph.unito.it)
   

(See write_vtk.pro)