Warp can be run interactively or non-interactively from the same installation. In this section we assume that Warp has been installed as described in the Installation How To. In addition to specific Warp functions and variables used to setup and describe the problem which are detailed in the code documentation, the full programming power of python with efficient numerical extensions provided by NumPy are available for use in setting up simulations and the graphics package pygist is available for formulating diagnostics. Extensive documentation for python, NumPy, and pygist can be found online (see linked web pages above) and are not covered here. Basic functions of pygist within the context it is employed in Warp are outlined in Basic Plotting.
In subsections below we first cover Interactive Runs and Non-Interactive Runs of Warp in the serial mode using a simple example "simulation" to create an x-y plot. The examples in these two subsections are not simulations but they provide a simple way to understand how to execute the code and obtain documentation. Next, the subsection Warp Simulation Script Outline provides a basic organizational schematic of a typical Warp simulation script. Details of simulation script elements are provided in the various How To's on this site. There are example input scripts provided on this site that can be adapted to simulate a wide variety of problems. Finally, the subsection Command Line Arguments covers passing run options into Warp.
Interactive Runs
First execute python in a terminal window and import Warp within python.
% python
>>> from warp import *
Subsequent commands can then be entered in python to describe and advance a simulation by setting and using Warp variables and functions described in other How To's. Basic information on Warp commands can be obtained by executing the documentation function:
>>> warphelp()
The functions
>>> warpfortran() # List of fortran routines linked with python
>>> warpscripts() # List of python scripts
provide more information on fortran subroutines accessible via python and python scripts. Further information on a particular Warp variable, linked fortran function name(), or python script name.py can be found by:
>>> doc("name")
For documentation on python scripts and linked fortran functions, the quotes are often not necessary. More information can be obtained on a python script name.py by:
>>> from name import *
>>> namedoc()
Commands making up a Warp simulation are often saved in a script file created with a text editor to be read into Warp. Examples of scripts used to generate Warp simulations can be found in Example simulation scripts. Here, we illustrate how the basic procedure can be carried out several ways with a simple example "runs" to produce an x-y plot. This example also helps illustrate how Warp diagnostic plots made in a run are typically saved. First, consider a run making an x-y plot with gist graphics via the commands in a file plot.py containing the following lines:
# Read in Warp
from warp import *
# Setup graphics output
setup()
# Make a simple x-y plot of y = x**2 for x in the interval[0,10]
x = arange(11)
y = x**2
plg(y, x) # plot graph
fma() # frame advance (sends plot to graphics output file)
More information on the x-y plotting commands above can be found in Basic Plotting.
Executing the script
% python -i plot.py
creates a cgm output file plot.000.cgm containing the plot in the directory which python is run. Because of the "-i" option, after the commands in plot.py are executed, the Python prompt is given, allowing further operations. More commands can be entered or python can then be quit with [ctrl-d] to terminate the run. The file plot.000.cgm contains the x-y plot frame which can be viewed with a cgm viewer as explained in Basic Plotting. 000 is an automatically generated output number which is incremented by one from the last value each time the script is run.
Non-Interactive Runs
The same simple x-y plot script plot.py described above in the subsection Interactive Runs can be executed non-interactively by:
% python plot.py
In this case the python process will terminate after execution of plot.py. Such commands can be submitted in batch mode with the specific synatax depending on the operating system used.
Details of simulation setup vary widely since Warp python scripts and linked source code modules can be applied with tremendous flexibility to a wide range of problems. Even a common physical problem can be described by a broad range of setup approaches and numerical procedures within Warp. Details of simulation components are provided in the various How To's (see sidebar) on this site. Several example simulation scripts are provided to provide a template for a range of simulations. These can be adapted to specific problems using information in the How To's. If necessary, members of the Warp development team can be contacted for advice.
Below we functionally outline a basic 3D simulation script saved in a file, say script.py which can be created an modified with a standard text editor:
# Read in Warp
from warp import *
# Setup graphics output
setup()
# Setup Lattice defining accelerator
# see "Lattice" How To
... python code to set variables and call lattice setup functions
# Setup initial beam
# see "Particles" How To
... python code to describe species and distribution parameters of initial beam
# Setup particle moving
# see "Particles" How To
... python code to setup particle mover including timestep etc.
# Setup simulation mesh and field solver
# see "Field Solver" How To
... python code to set mesh variables and setup fieldsolver
# Setup simulation diagnostics
# see "Diagnostics" How To
... python code to setup diagnostics
# Generate code
package("w3d")
generate()
# Advance simulation, say 1000 timesteps
step(1000)
# Save dump of run, if desired
# see Saving/Retrieving Data How To
dump()
Details can differ significantly and there is no strict order that must be adhered to.
This script can be run interactively
% python -i script.py
or non-interactively
% python script.py
as described in the previous subsections.
Several types of runs are possible including 3D, r-z, transverse x-y slide, and envelope simulations. Details of the setup may vary for each class of run. For example, for other than envelope model runs, an appropriate field solver and spatial mesh must be setup. In many cases, different classes of runs are possible to carry out with minimal modifications between 3D, r-z, and x-y slice simulations. An appropriate package() call must be made before the code is generated:
package("w3d") # 3D PIC
package("wrz") # r-z axisymmetric PIC (r-z mover, depreciated recommend use w3d)
package("wxy") # transverse x-y slice PIC advanced slice-to-slice
package("env") # envelope (moment) model: often used to setup 3D and r-z simulations
Usually, outside of the envelope solver, only one call to generate() can be made within a single Warp run. Usually when a r-z run is done, the w3d package is used: the particles are moved in 3D and an r-z axisymmetric field solver and mesh is setup for the particle deposition and fieldsolve. Warp also has several other packages not listed here to keep the discussion simple.
Warp accepts several command line arguments, as described here.
-p, --decomp npx npy npz
Specify the domain decomposition when running in parallel. The npx, npy, and npz are the number of domains along the x, y, and z axes. Note that npx*npy*npz must be the same as the total number of processors.
--pnumb string
Specify the runnumber to use, instead of the automatically incremented three digit number. Any arbitrary string can be specified.
User specified command line arguments can be added by defining them at the top of the input file before importing warp. For example, the following sets up the command line argument myarg:
import warpoptions
warpoptions.parser.add_argument('--myarg', dest='myarg', type=float,default=0.)
from warp import *
The specified value can then be accessed in the input file after importing warp.
myarg = warpoptions.options.myarg
Then, Warp can be started with the defined command line option.
% python -i myinputfile.py --myarg 7.0
See the optparse module for a full description of the add_option command - there is much flexibility.