% ZED
\input dvidoc
\dvidoc % comment or delete this line to format for laserwriter
\ifdvidoc\else \magnification\magstep1 \fi
%
\def\date{\number\month/\number\day/\number\year}
\headline={\ifnum\pageno>1 {\fiverm ZED \hfil}\fi}
\footline={\tenrm \ifnum\pageno<2 {\fiverm\date\ \hfil}
   \else \rlap{\fiverm\date} \hss\folio\hss \fi}
%
\def\codevar#1{\ifdvidoc\uppercase{#1}\else{\tt #1}\fi}
%
\def\cmdhead #1\par{\medbreak\longitem{\codevar{#1}}}
%
% \longitem is like \item except its argument is left adjusted, and if it's
% wider than \parindent then the text following is pushed over to make room.
\def\longitem#1{%       B. Langdon, 11/88.
  \setbox0=\hbox{#1\enspace}  \dimen0=-\wd0
  \hangindent=\parindent
  \advance\dimen0 by \hangindent  \ifdim\dimen0<0pt \relax \dimen0=0pt \fi
  \leavevmode\kern -\hangindent \unhbox0 \kern\dimen0
  \ignorespaces
}
%
\let\hfilbreak=\allowbreak      % this gives overfull hboxes with default tolerance.
%\def\hfilbreak{\hfil\penalty9999\hfilneg}      % this almost always breaks
%\let\hfilbreak=\relax
%
\def\newline{\hfil\break}
%-----------------------------------
\def\H/{\codevar{history}}      % TeXbook, p. 204; spaces after \H/ are not lost.
\def\S/{\codevar{state}}
%
\centerline{\bf ZED (Zohar EDitor)}
\medskip
\centerline{A. Bruce Langdon}
\centerline{Physics Department}
\centerline{Lawrence Livermore National Laboratory}

\bigskip
{\narrower
ZED is an interactive code, able to read, manipulate and display graphically
the time-dependent data from simulation codes.
ZED was begun in 1974 by B. Langdon and B. Lasinski to postprocess time history
files from runs of ZOHAR, a 2D electromagnetic particle-in-cell code.
At Berkeley, Princeton and Livermore MFE it was applied and extended in
imaginative ways to other codes by W. Nevins, N. Otani,..., and others.
In its original (1974-1987) form, the commands were individually interpreted
in LRLTRAN, adding new commands was clumsy, and the command syntax was stilted.
The versions at LCC (the internal Livermore center) and at NMFECC
evolved separately for years.
In 1987 Nevins suggested that ZED be reborn as a Basis `package'.
Basis is a combined interactive interpreter/graphics/code system to which
anyone can readily add commands and the Fortran subprograms to implement them.
This document describes the Basis implementation of ZED.
\par}

\bigbreak
\centerline{\bf Availability}
\nobreak\medskip

\tolerance=5000
At MFECC, ZED for the Cray-2 is publicly available from CFS directory
\hfilbreak \hbox{\codevar{/zohar/cray2/zed}}. The files include:

\codevar{xzed}
is the executable file.

\codevar{zedlib}
is a LIB file which includes \codevar{zedmac}, the part of ZED written in the Basis
language, and the sources files needed to make \codevar{xzed}.
Also, \codevar{zed.tex} is the \TeX\ source for this manual;
\codevar{zed.doc} \ifdvidoc (what you are reading now) \fi
is a straight ASCII file to print or view on a terminal.
\codevar{ebal} is a Basis-language file; read after \codevar{init}, it will
read and display the various particle and field energies and fluxes and
form an energy balance.
\codevar{pbal} is like \codevar{ebal}, but for the $x$-component of momentum.

\bigbreak
\centerline{\bf How to use ZED now}
\nobreak\medskip

First, get a copy of the Basis system manual[1] and read the first chapter. 

Commands implemented now let you create Basis variables that contain the
time histories of physical variables from their time histories saved in the
\H/ and \S/ files.
You then have the full power of Basis to do as you will with them.
This already empowers you to do much of what old ZED did, and much more that
it didn't.

The time dependence of many quantities in the simulation is written into the
file \H/.
The file \S/ contains in addition the time step, particle species' names, etc,
and descriptive information about the simulation
(plus other data like the electromagnetic fields that pertains only to the
time step when the state file was made.)
\H/ and \S/ are not human readable text files, they hold numbers and text in
Cray hardware representation.\footnote{(a)}{The format of \H/ and \S/ is indicated
in source files \codevar{szedc} and \codevar{var.zed} in \codevar{zedlib},
and of course in the ZOHAR routines \codevar{writstat}, \codevar{readstat},
\codevar{tset} and \codevar{mdset}.}
The Fortran functions \codevar{getstate} and \codevar{gethist},
together with the Basis-language functions \codevar{init}, \codevar{readh}, etc.,
read from \S/ and \H/ and create Basis variables
holding the interesting values.

\bgroup
\ifdvidoc
  \parindent=10em
\else
  \parindent=5em
\fi
\tolerance=1000         % make alignment of narrow paragraphs less strict.
\cmdhead init

The first command you give is \codevar{init}.
Often the files are renamed to indicate the problem name
(e.g., \codevar{hprob}, \codevar{sprob}) or time step (e.g., \codevar{h6000}, \codevar{s6000}).
Then you run `\codevar{init prob}' or `\codevar{init 6000}'.

\cmdhead get

A list of variables to be read from \H/ is accumulated.
Variable `\codevar{elg}' is added to the list by the command
\hfilbreak `\codevar{get elg}'.
This translates to \hfilbreak `\codevar{gets("elg")}'.
You may call `\codevar{gets}' directly if the variable name is computed.
For example, `\codevar{gets("ke"//format(is,0))}' when \codevar{is=2}
 adds `\codevar{ke2}' to the list.

\cmdhead readh

This command takes the list accumulated by the `\codevar{get}' commands,
reads from \H/, and creates Basis arrays holding the time series.
In the example above, after readh there will be two new arrays, \codevar{elg} and \codevar{ke2}.
You then could do `\codevar{plot elg, time}' to plot the electrostatic field
energy {\it versus} time.

\cmdhead steps first, last [, iskip]

Usually \codevar{readh} reads from step 0 to the last step of the simulation.
This command confines the times steps to \hfilbreak\codevar{(first,last)}.
Optionally it resets \codevar{iskip}, whose meaning is that only time steps
that are multiples of \codevar{iskip} are retained.
If \codevar{iskip=2}, then e.g., \codevar{elg(i)} corresponds to time step
2\codevar{i} and \codevar{elg} is subscripted roughly
\hfilbreak \codevar{(first/2:last/2)}.
\par\hang
If indexed variables are to be used, \codevar{iskip} must be a multiple of
\codevar{ismode} (see \codevar{modes}).

\cmdhead modes

\H/ is divided into two parts. The first holds time records for quantities that are
more or less global, like kinetic energy for all electrons, or are particular,
like the $x$ position of a planar shock.
The records present are printed by \codevar{init}.
The second part holds time records of quantities that have a name and one or two
indices, like a field at a particular grid point, or a coordinate
of a particle.
The list in human-readable form is in array \codevar{lblm}.
\par\hang
At present, \codevar{get} and \codevar{readh} work with only one part at a time.
You toggle between them with the \codevar{modes} command.
\par\hang
Values in the modes section are not in general saved every time step,
but at steps that are multiple of \codevar{ismode}, an input variable to ZOHAR.
In ZOHAR by default \codevar{ismode=2}.

\cmdhead ploth xyz

plots history variable \codevar{xyz} versus time.
If \codevar{xyz} is a complex variable, the real and imaginary
parts are plotted using solid and dashed lines in the lower half of the frame.
In the upper half, the modulus squared is plotted, semilog.
(Of course you can also use the Basis plot interface.)
\par\hang
If \codevar{xyz} is from the history file,
i.e., it is in the \codevar{varsh} or \codevar{varsm} list,
it is labelled instead with the corresponding ``nice'' name from
\codevar{lblh} or \codevar{lblm} (see `Variable naming').

\cmdhead spect(f)

Value is the Blackman-Tukey power spectra of time variable \codevar{f}.
To get spectrum for subinterval of the full time step range
\codevar{(istepl,istepu)}, do \codevar{spect(f(il:iu))}.
Remember, \codevar{il} and \codevar{iu} are the actual steps
divided by \codevar{iskip}.

\cmdhead sparam lagwidth [datawidth [wmax]]

Set lag window and data window widths (in steps) and maximum frequency
to be displayed by default in spectrum plots.

\cmdhead ints var [wmin wmax]

(Soon) Integrate spectrum in \codevar{var}.
\ifdvidoc\else
$$
(\hbox{\codevar{ints f w1 w2}})_\omega
  = \int_{\hbox{\codevar{w1}}}^\omega\, f(\omega),
  \quad \codevar{w1} \le \omega < \codevar{w2}
$$
\fi
Useful in finding out how much power is {\it between} two frequencies.

\cmdhead mem

(Later)
Form `maximum entropy method' spectra. 

\cmdhead reset

Clears memory. Might be used before switching to another ZOHAR run.

\cmdhead fll

Prints ZED's memory size. 

\egroup % restore normal \parindent

\bigbreak
\noindent
\centerline{\bf Variable naming}
\nobreak\medskip
ZOHAR history records include items whose names have blanks or characters not
legal in Basis variables: `\codevar{field px}', `\codevar{ex-ey}'.
So you must refer to `\codevar{fieldpx}' and `\codevar{exey}' instead.
Worse, indexed records have a name and two indices, and an index may be negative.
For example, \allowbreak `\codevar{Bz(x,ky) 20 3}' is field
\ifdvidoc
Bz, Fourier transformed over y, evaluated at x grid point 20, mode 3.
\else
$B_z$, Fourier transformed over $y$, evaluated at $x$ grid point 20 ($x=20\Delta x$),
mode 3 ($k_y = 3\times 2\pi/L_y$).
\fi
This is stored in Basis variable `\codevar{bzxk20\$3}'.
The \$ separates the two indices. In a negative index number, a \% replaces
the minus.
Arrays \codevar{varsh} and \codevar{varsm} hold the list of these ugly things
for globals and modes, respectively,
while \codevar{lblh} and \codevar{lblm} hold the list of nice names.
You may wish to use Basis' \codevar{define} so you can refer to these
by nicer names.

\bigbreak
\noindent
\centerline{\bf ZOHAR's variables in \codevar{history}}
\nobreak\medskip
While the modes variables are entirely specified by user input
and there may not even be any, the global variables are chosen by
statements at the beginning of subroutine \codevar{tset}.
These vary slightly from version to version and the number of particle species,
but the following are standard:

\cmdhead n1, n2, ...

are the number of active particles of species 1, 2, ...

\cmdhead ke1, px1, ke2, ...

are the kinetic energies and momenta of active particles of species 1, 2, ...

\cmdhead kl1, kl2, ...

are cumulative kinetic energies of particles of species 1, 2, ... {\it lost}
due to particles leaving through the left or right side.
Particles entering make a {\it negative} contribution.

\cmdhead l pxl1, r pxl1, ...
 
are cumulative $x$ momenta of particles of species 1 {\it lost} 
due to particles leaving through the left or right side, respectively.
Particles entering make a {\it negative} contribution.

\medskip\hang ..and similarly for \codevar{py1}, etc.

\cmdhead field px

Electromagnetic momenta in x direction, etc.

\cmdhead l pxlf, r pxlf

cumulative fluxes of the $x$ component of the field momentum out of the system,
i.e. the time integral of the Maxwell stress tensor averaged
averaged over $y$ at the left and right sides.

\cmdhead elg, ex-ey, bz

field energies associated with the `electrostatic' field, $E_x$ plus $E_y$,
and $B_z$, respectively.

\cmdhead wleybz, wreybz

cumulative Poynting fluxes. The electromagnetic energies into the left side
and out through the right side, averaged over $y$.

\medskip\hang ..and similarly for \codevar{bx-by}, \codevar{ez},
\codevar{wlezby} and \codevar{wrezby}.

\cmdhead bz left, bz right

is $B_z$ averaged over $y$ at the left and right sides. The contribution of the
incoming electromagnetic waves is subtracted; this only really works in vacuum.

\medskip\hang ..and similarly for \codevar{ez left} and \codevar{ez right}.

\cmdhead clock

is the real clock time in decimal hours. Use this to review your strategies
for getting production time.

\medbreak
In the relativistic shock version (\codevar{code} $=$ ``zirs''), there are
in addition:

\cmdhead l bflux, r bflux

Cumulative magnetic field flux through the left and right sides.
\ifdvidoc\else
The change in magnetic flux inside the system is
$$
\int_0^T dt \int_0^{L_x} \int_0^{L_y} dx\,dy {\partial B_z \over \partial t}
 = c \int_0^T dt \int_0^{L_y} dy [E_y(x=0) - E_y(x=L_x)]
$$
in which we used Faraday's law and integrated by parts.
\fi

\cmdhead xshock

\medbreak
\noindent Notes

The energies and momenta are the totals divided by $L_y$ in versions periodic in $y$,
and by $L_x L_y$ in versions periodic in $x$ and $y$.

\bigbreak
\noindent
\centerline{\bf The future}
\nobreak\medskip

User experience will guide evolution of ZED and of this report.

It would not be difficult to teach ZED to read field information from
\codevar{state} and to read the particle files.

\bigbreak
\centerline{\bf Customizing ZED}
\nobreak\medskip

The simplest customization is to add your own functions and macros in a file
to be read by Basis in addition to \codevar{zedmac}.

Other versions of ZOHAR, and other codes that write \codevar{history} files,
have \codevar{state} laid out differently, or no \codevar{state} file at all.
You can revise \codevar{init} and \codevar{getstate} accordingly;
all the files are available in CFS.

\bigbreak
\centerline{\bf Acknowledgements}
\nobreak\medskip
ZED derives its extensibility and its new power from the Basis system.
We are grateful for additions to Basis that ZED depends on.

\bigbreak
\centerline{\bf References}
\nobreak\medskip
\def\ref#1. {\item{[#1]}}
\bgroup\parskip=\medskipamount

\ref 1.
P. Dubois, Z. Motteler, P. Willmann {\it et al}, ``The Basis System'',
LLNL report M-225, available on-line at the LCC and NMFECC.

\ref 2.
ZOHAR is described in
``Electromagnetic and Relativistic Plasma Simulation Models'',
A. B. Langdon and B. F. Lasinski, in {\it Methods in Computational Physics},
ed.\ by B. Alder, S. Fernbach and M. Rotenberg, vol.\ ed.\ J. Killeen,
(Academic Press, New York, 1976), Vol.\ 16, p.\ 327-366.

\egroup % restore old parskip

\bigbreak
\centerline{\bf Appendix: How it works}
\nobreak
\bye