Documentation for PSvector

Name of code:
Psvector

Organization:
University of California, Los Angeles / University of Mississippi

Author:
Alon S. Barlevy, Atef Z. Elsherbeni, and Yahya Rahmat-Samii

Category:
User Interface (output)

Purpose:
To create postscript files showing vector field distributions in any desired plane cut (or cuts) in a Finite Difference Time Domain (FDTD) algorithm.

Language:
FORTRAN 77, creating a postscript file. Postscript files can be viewed using Ghostview or printed to a postscript printer.

Computers on which code runs:
Code was tested on IBM RISC 6000 and PC using Windows 95.

Availability:
Can be downloaded at no charge. Just click here, and then use the ``Save As'' option in your browser, to a copy of the fortran code on your machine.
Alon Barlevy (310)206-4801 barlevy@ee.ucla.edu
Atef Elsherbeni (601)232-5382 atef@olemiss.edu

Description:
This utility is developed to create postscript files showing vector field distributions in any desired plane cut (x-y, y-z, or x-z plane cuts) in a finite difference time domain (FDTD) algorithm. This utility is not a stand alone program, but a collection of subroutines developed using FORTRAN 77. The output of these subroutines is a postscript file. The postscript files can be viewed using Ghostview or printed to a postscript printer. This routine was tested on IBM RISC 6000 workstations and on PC's running Windows 95 operating system.

The user defines the dimensions for the plot, and the program automatically scales the plot to the defined dimensions. The program also automatically chooses a scale for the vectors, such that the largest arrow size does not touch the next vector (provided that two consecutive vectors do not point in opposite directions). The length of the vector is proportional to the amplitude of the field value.

By calling this routine repeatedly, different plots can be put on the same page, or on different pages. When there are different plots (in the same postscript file) an option is given whether to rescale the vector plots to one uniform scale, or have a different scale for each plot. The advantage of having different scales is to allow one to see features that might not otherwise be observable.

Limitations and approximations:
There are no approximation in this code, since this code is only designed to display data, not calculate data. One major limitation is that the vector field is only plotted for the components of the vector in the plane of the cut. For example, if the desired plane cut is a x-y cut, then the output will only show the x and y components of the chosen electric (magnetic) vector field for a desired value of z and time. The z-component of the vector field will not be displayed.

Disclaimer
THIS SOFTWARE IS PROVIDED FREE OF CHARGE FOR EDUCATIONAL USE. THE INFORMATION AND CODE IS PROVIDED AS DESCRIBED ABOVE WITHOUT WARRANTY OF ANY KIND. THE AUTHORS WILL NOT BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES DIRECTLY OR INDIRECTLY RELATED TO THE USE OF THIS SOFTWARE.

Example of use:
To use the subroutine, simply type

        call PSVF      (del1,N1s,N1e,Eys,iskip1,
     &                  del2,N2s,N2e,Ezs,iskip2,
     &                  Nx,Ny,Nz,Iplane,icut,PSfile,ipost,totalf,
     &                  tns,delx,dely,delz,io,iolast,units,grid)

in your FDTD code. An example of such a call, as well as a list explaining the input variables is given below.

! ...........................................................                                                                   
! The following is an example on how to call the PS Vector Field
!      if (mod(n,20).eq.0 .and. n .lt. 800) then
!        io = n/20 - 1
!        iolast = nstop/20 - 1
!
! The following is for E field components
!        PSFile='Esxup.PS'  ! one file to get the appropriate scale
!        tns = t*1.e+9
!        del1 = dely
!        del2 = delz  
!        n1s = 40
!        n1e = 70
!        n2s = 1
!        n2e = nz 
!        iskip1 = 1
!        iskip2 = 1
!        Iplane = 2 
!        Icut = 13
!        units = 'V/m'
!        grid = .false.
!        totalf =.true.
!        call PSVF      (del1,N1s,N1e,Eys,iskip1,
!     &                  del2,N2s,N2e,Ezs,iskip2,
!     &                  Nx,Ny,Nz,Iplane,icut,PSfile,ipost,totalf,
!     &                  tns,delx,dely,delz,io,iolast,units,grid)

The variables are as follows:

! parameters:
! del1,del2: FDTD cell size in horizontal and vertical directions (in m)
! Ns1,Ne1:   Starting and ending indices for horizontal vector. The word
!            horizontal reffers to the direction on the postscript plot.
! Ns2,Ne2:   Starting and ending indices for vertical vector. The word
!            vertical reffers to the direction on the postscript plot.
! E1,E2:     FDTD field values. They can be either Electric or Magnetic
!            fields. E1 reffers to the horizontal component, and E2 
!            reffers to the vertical component
! Iskip1,Iskip2: Skip values in horizontal and vertical directions
! Nx,Ny,Nz: Actual dimensions of field arrays E1,E2 in FDTD code
! Iplane:   The plane cut (1 for x-y , 2 for y-z , 3 for x-z)
! Icut:     The level of cut in the specified plane cut
! PSFile: File name of the PS output
! Ipost:  Unit number for the PS file (i.e. open(unit=Ipost)). Make sure
!         that this is not an open unit used in the FDTD code.
! Iscrach: Unit number for a scratch file that is internal to the postscript
!          routine. Make sure that this is not an open unit used in the FDTD
!          code.
! totalf: logical variable for the scattered (false) or total (true) field
! tns:    Time in ns
! delx, dely,delz: cell sizes in x,y,z directions (in m)
! io:
! iolast:
! units: This is a string variable that can only be be either 'V/m' or 'A/m'.
!        This option is used to detect if the vector plot is
!        for electric or magnetic field. It is necessary to determine the 
!        shift and accurate number of FDTD grid points to be uesd.
! grid:  = .true. if fine grid is desired.
!        = .false. if fine grid is not desired.