Home‎ > ‎How To's‎ > ‎

Warp Units and Variables

Warp Units

In almost all cases, Warp uses MKS units. The one notable exception is that sometimes the energy, for example top.ekin which can be used to set the initial axial kinetic energy of the beam, is in units of electron volts.

There are a number of convenient multiplying factors to convert quantities to MKS units. For example, cm will convert centimeters to meters:

x = 2.*cm

will result in x being set to 2 cm in meters. Below is a list of conversion factors and their values.

inch = 0.0254    # inches to meter
nm   = 1.e-9     # nm to meter
um   = 1.e-6     # um to meter
mm   = 1.e-3     # mm to meter
cm   = 0.01      # cm to meter
ps   = 1.0e-12   # picosecond  to second
ns   = 1.0e-9    # nanosecond  to second
us   = 1.0e-6    # microsecond to second
ms   = 1.0e-3    # millesecond to second
kV   = 1.0e3     # kV to V
keV  = 1.0e3     # keV to eV
MV   = 1.0e6     # MV to V
MeV  = 1.0e6     # MeV to eV
mA   = 1.0e-3    # mA to A
uC   = 1.0e-6    # micro-Coulombs to Coulombs
nC   = 1.0e-9    # nano-Coulombs  to Coulombs
deg  = pi/180.0  # degrees to radians

Warp also has numerous mathematical and physical constants available which can aid in setup of problem descriptions.  These include:

Mathematical Constants

pi       = 3.14159265358979323   # Pi
euler    = 0.57721566490153386   # Euler-Masceroni constant
e        = 2.718281828459045     # exp(1.)

Physical Constants

avogadro  = 6.02214129e23          # Avogadro's Number
amu       = 1.66053921e-27         # Atomic Mass Unit [kg]
clight    = 2.99792458e+8          # Speed of light in vacuum [m/s]
echarge   = 1.602176565e-19        # Proton charge [kg]
emass     = 9.10938291e-31         # Electron mass [kg]
eps0      = 8.854187817620389e-12  # Permittivity of free space [F/m]
jperev    = 1.602176462e-19        # Conversion factor, Joules per eV [J/eV]
mu0       = 1.2566370614359173e-06 # Permeability of free space [H/m]
boltzmann = 1.3806488e-23          # Boltzmann's constant [J/K]
planck    = 6.62606957e-34         # Planck's constant [J.s]



The physical constants were obtained from 2010CODATA, http://physics.nist.gov/cuu/Constants/bibliography.html.

Many variables used in Warp to express quantities such as statistical beam extents (transverse rms radii) and phase-space areas (transverse rms emittances) and are conventionally expressed in so-called "edge measures" with

    a  = 2*sqrt(<x*x>)        edge measure of x-width of transverse distribution 
    b  = 2*sqrt(<y*y>)        edge measure of y-width of transverse distribution

and

   emit_x = 4*sqrt( <x*x><x'*x'> - <x*x'><x*x'> )     edge measure of x-x' phase-space area
   emit_y = 4*sqrt( <y*y><y'*y'> - <y*y'><y*y'> )     edge measure of y-y' phase-space area

where <...> here denotes a transverse distribution average and no centroid offset (i.e., <x> = 0 = <x'>,  etc.) is assumed for simplicity. The numerical factors of 2 and 4 in the coefficients are motivated by a Kapchinskij-Vladimirskij (KV) distribution. For a KV distribution the factors give boundary-edge measures appropriate for uniformly filled beam phase-space projections. These factors are then applied to other distributions which may be far from having uniform projections. This convention was taken in Warp since the code was historically developed for simulating space-charge dominated beams where the factors are conventionally used this they apply fairly well to most distributions with strong space-charge. Care should be taken by Warp users to understand factors employed in quantities such as rms emittance measures.  Unfortunately, there is no broad standard in accelerator physics for conventions in incorporating factors for effective edge meaures in envelope and emittance definitions. 

Warp Variables and Packages

Warp has literally thousands of variables/parameters used to specify and control simulations. These include real numbers, integers, and arrays. These are organized around packages with names including:

    Name    Function
    top         Main control
    env         Envelope equation solver
    w3d        3D PIC
    wxy        Two dimensional transverse x-y slice PIC
    wrz         Two dimensional axisymmetric r-z PIC (depreciated use 3D package)
    f3d          3D electrostatic field solver
    fxy          2D fieldsolver for x-y slice PIC
    frz           2D fieldsolver for axisymmetric r-z PIC
    util          Utility routines
    fft            FFT

More information on these can be found in the source web pages. Fortran surce code files (".F" suffix) and associated variable description files (".v" suffix) can be found for each package. Variables are functionally grouped within each package constituting common blocks in the source code. 

The "top" package contains many overall simulation control parameters used by fortran routines and linked with the python interpreter interface. When obtaining documentation on specific variables like a simulation timestep top.dt, information can be obtained by (quotes are necessary):

>>> doc("dt")

and the value to the variable can be found by

>>> top.dt

to print the present value. The doc("dt") command above returns

Package:    top
Group:      InGen
Attributes: InGen dump
Type:       double
Address:    140277350102000
Comment:
Timestep size

giving the package (top) and group (InGen) within the package that the variable is defined in, variable attributes and type, address info (platform dependent), and a comment describing the variable. Much information can be deduced by examining variable description file top.v used in comping Warp. The source web pages have enhanced formatting making them easier to read.

Comments