Input File for QuickPIC

Introduction

QuickPIC requires an input file for initializing the simulation. When QuickPIC starts running, it will look for the input file named "qpinput.json" and read parameters from this file. If the file does not exist in the same folder where the executable file is located, the program will stop with an error message.

The Format of the Input File

The format of the input file is JSON. You can find more information about JSON at here. It should be noted that JSON does not allow trailing commas. In addition, JSON does not allow comment. However, in QuickPIC we use JSON-FORTRAN which can ignore all the comments before processing the file. In "qpinput.json", you can add any comment after an exclamation mark "!", and any text following this "!" will be ignored until the end of line is reached.

Several Concepts

QuickPIC Input File

In "qpinput.json", there are "simulation", "beam", "species" and "field" sessions. All parameters are using normalized units unless it is specified.

The "simulation" session

In the "simulation" session, we define several basic simulation parameters:

"nodes" : integer array (2) -- The first component define the MPI processors used in each stage; the second component define the number of stages in the simulation.

"indx" : integer -- The number of cells in x diretion is $2^{indx}$ .

"indy" : integer -- The number of cells in y diretion is $2^{indy}$ .

"indz" : integer -- The number of cells in z diretion is $2^{indz}$ .

Note that indx and indy should be the same currently.

"box" : session -- The size of the simulation box.

"x" : real array(2) -- Starting and end coordinates in x direction.
"y" : real array(2) -- Starting and end coordinates in y direction.
"z" : real array(2) -- Starting and end coordinates in $\xi$ direction.

"boundary" : string -- The boundary condition for the simulation. The current available option is "conducting".

"n0" : real -- The plasma density (in the unit of $cm^{-3}$ ) for the normalized units.

"time" : real -- The length the simulation will run for.

Note that the initial time is always zero.

"dt" : real -- Time step for pushing the relativistic particle beam

"nbeams" : integer -- Total number of particle beams.

"nspecies" : integer -- Total number of plasma species.

"dump_restart" : logical -- If true, the code will dump the restart files during the simulation

"ndump_restart" : integer -- If it is equal to n, the code will dump the restart files every n steps.

"read_restart" : logical -- If true, the code will read the restart files when it starts.

"restart_timestep" : integer -- The number at which step the code will start when "read_restart" is true.

"iter" : integer -- The number of iterations the code will use when solving the plasma response.

"verbose" : integer -- The larger the number is the more information will be writtent in the log files.

The "beam" session

In "qpinput.json", the "beam" is an array. Each component in "beam" is a session that defines the parameters related to each particle beam.

1. Tri-Gaussian Beam

"profile" : 0 -- The profile ID for Tri-Gaussian beam with the same charge for each beam particle.

"evolution" : logical -- If it is true, the code will push the beam particles every time step.

"np" : integer array(3) -- The product of three components is the total number of simulated particles for this beam.

"npmax" : integer -- The number of particles the code will allocate memory for each MPI processors.

"q" : real -- The charge for each beam particle. E.g., it is -1.0 for an electron and 1.0 for a proton or positron.

"m" : real -- The rest mass for each beam particle. E.g. it is 1.0 for an electron and 1836.15267389 for a proton.

"gamma" : real -- The Lorentz facter for the average energy of the particle beam.

"peak_density" : real -- The peak beam density.

"quiet_start" : logical -- If it is true, the code will initialize the beam particles using the "quiet start" method.

"center" : real array(3) -- The coordinates of the beam center.

"sigma" : real array(3) -- The rms values for the beam size in each direction.

"sigma_v" : real array(3) -- The rms values for the beam momentum in each direction.

"centroid_x" : real array(3) -- The parameters define the centroid of the beam in x direction. The centroid along $\xi$ ) is , where is the beam center in direction.

"centroid_y" : real array(3) -- The parameters define the centroid of the beam in y direction. The centroid along is , where is the beam center in direction.

"diag" : session array(*), optional -- For the beam, we have three examples for the diagnostic session:

Example 1 : 3D beam charge desntiy

{
"name" : ["charge"],
"ndump" : 1
}

"name" : string array(*)-- Available option is "charge" for dumping beam charge density.
"ndump" : ingteger -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.

Example 2 : 2D slice of the beam charge desntiy

{
"name" : ["charge"],
"ndump" : 1,
"slice" : [["xz", 129],["yz",129],["xy",20]]
}

"name" : string array(*) -- Available option is "charge" for dumping beam charge density.
"ndump" : integer -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.
"slice" : array(*) -- Each component is a two-componet array containing a string and an integer. The string is "xz", "yz" or "xy" indicating the slice orientation. The integer is the position of that slice in the cell number.

Note that the position of the center slice in x (y, z) in the box is .

Example 3 : Particle raw data for the beam.

{
"name" : ["raw"],
"ndump" : 1,
"sample" : 10
}

"name" : string array(*) -- Available option is "raw" for dumping beam particle raw data
"ndump" : integer -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.
"sample" : For sample = i, the code will dump one particle raw data from every i particles.

2. Transversely bi-Gaussian and longitudinally piece-wise Beam

"profile" : 1 -- The profile ID for transversely bi-Gaussian and longitudinally piece-wise beam with the same charge for each beam particle.

"evolution" : logical -- If it is true, the code will push the beam particles every time step.

"np" : integer array(3) -- The product of three components is the total number of simulated particles for this beam.

"npmax" : integer -- The number of particles the code will allocate memory for each MPI processors.

"q" : real -- The charge for each beam particle. E.g., it is -1.0 for an electron and 1.0 for a proton or positron.

"m" : real -- The rest mass for each beam particle. E.g. it is 1.0 for an electron and 1836.15267389 for a proton.

"gamma" : real -- The Lorentz facter for the average energy of the particle beam.

"peak_density" : real -- The beam density is the product of "peak_density" and "piecewise_fz".

"piecewise_fz" : real array(*) -- The longitudinal piecewise density values for the beam.

"piecewise_z" : real array(*) -- The longitudinal piecewise z values for the beam.

Note that this array should be monotonically increasing. The size of "piecewise_density" should be the same as the size of "piecewise_s"

"quiet_start" : logical -- If it is true, the code will initialize the beam particles using the "quiet start" method.

"center" : real array(3) -- The coordinates of the beam center.

Note that the value of center(3) is the for initializing the beam centroid.

"sigma" : real array(2) -- The rms values for the beam size in transverse directions.

"sigma_v" : real array(3) -- The rms values for the beam momentum in all directions.

"centroid_x" : real array(3) -- The parameters define the centroid of the beam in x direction. The centroid along $\xi$ ) is , where is the beam center in direction.

"centroid_y" : real array(3) -- The parameters define the centroid of the beam in y direction. The centroid along is , where is the beam center in direction.

"diag" : session array(*), optional -- For the beam, we have three examples for the diagnostic session:

Example 1 : 3D beam charge desntiy

{
"name" : ["charge"],
"ndump" : 1
}

"name" : string array(*)-- Available option is "charge" for dumping beam charge density.
"ndump" : ingteger -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.

Example 2 : 2D slice of the beam charge desntiy

{
"name" : ["charge"],
"ndump" : 1,
"slice" : [["xz", 129],["yz",129],["xy",20]]
}

"name" : string array(*) -- Available option is "charge" for dumping beam charge density.
"ndump" : integer -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.
"slice" : array(*) -- Each component is a two-componet array containing a string and an integer. The string is "xz", "yz" or "xy" indicating the slice orientation. The integer is the position of that slice in the cell number.

Note that the position of the center slice in x (y, z) in the box is .

Example 3 : Particle raw data for the beam.

{
"name" : ["raw"],
"ndump" : 1,
"sample" : 10
}

"name" : string array(*) -- Available option is "raw" for dumping beam particle raw data
"ndump" : integer -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.
"sample" : For sample = i, the code will dump one particle raw data from every i particles.

3. Longitudinally Gaussian Beam with Twiss parameters

"profile" : 2 -- The profile ID for longitudinally Gaussian beam with Twiss parameters. Each beam particle has the same charge.

"evolution" : logical -- If it is true, the code will push the beam particles every time step.

"np" : integer array(3) -- The product of three components is the total number of simulated particles for this beam.

"npmax" : integer -- The number of particles the code will allocate memory for each MPI processors.

"q" : real -- The charge for each beam particle. E.g., it is -1.0 for an electron and 1.0 for a proton or positron.

"m" : real -- The rest mass for each beam particle. E.g. it is 1.0 for an electron and 1836.15267389 for a proton.

"gamma" : real -- The Lorentz facter for the average energy of the particle beam.

"peak_density" : real -- The peak beam density.

"quiet_start" : logical -- If it is true, the code will initialize the beam particles using the "quiet start" method.

"center" : real array(3) -- The coordinates of the beam center.

"sigmaz" : real -- The rms value for the beam size in z direction.

"sigma_vz" : real -- The rms value for the beam momentum in z direction.

"alpha" : real array(2) -- The alpha parameter for the beam in two transverse directions.

"beta" : real array(2) -- The beta parameter for the beam in two transverse directions.

Note that beta is normalized by the plasma skin depth.

"emittance" : real array(2) -- The normalized emittance for the beam in two transverse directions.

Note that emittance is normalized by the plasma skin depth.

"diag" : session array(*), optional -- For the beam, we have three examples for the diagnostic session:

Example 1 : 3D beam charge desntiy

{
"name" : ["charge"],
"ndump" : 1
}

"name" : string array(*)-- Available option is "charge" for dumping beam charge density.
"ndump" : ingteger -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.

Example 2 : 2D slice of the beam charge desntiy

{
"name" : ["charge"],
"ndump" : 1,
"slice" : [["xz", 129],["yz",129],["xy",20]]
}

"name" : string array(*) -- Available option is "charge" for dumping beam charge density.
"ndump" : integer -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.
"slice" : array(*) -- Each component is a two-componet array containing a string and an integer. The string is "xz", "yz" or "xy" indicating the slice orientation. The integer is the position of that slice in the cell number.

Note that the position of the center slice in x (y, z) in the box is .

Example 3 : Particle raw data for the beam.

{
"name" : ["raw"],
"ndump" : 1,
"sample" : 10
}

"name" : string array(*) -- Available option is "raw" for dumping beam particle raw data
"ndump" : integer -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.
"sample" : For sample = i, the code will dump one particle raw data from every i particles.

The "species" session

In "qpinput.json", the "species" is an array. Each component in "species" is a session that defines the parameters related to each plasma particle.

1. Transversely Uniform Plasma

"profile" : 0 -- The profile ID for the transversely uniform plasma.

"ppc" : integer array(2) -- The numbers of simulated particles per cell in x and y directions.

"q" : real -- The charge for each plasma particle. E.g., it is -1.0 for an electron.

"m" : real -- The rest mass for each plasma particle. E.g. it is 1.0 for an electron and 1836.15267389 for a proton.

"density" : real -- The density of the plasma.

"longitudinal_profile" : string -- It can be "uniform" or "piecewise".

"piecewise_density" : real array(*) -- The density array for the longitudinal piecewise plasma profile.

Note that the actual plasma density will be the product of the "density" value and "piecewise_density" value.

"piecewise_s" : real array(*) -- The s array for the longitudinal piecewise plasma profile.

Note that minimum value of this array should not be larger than 0.0 and the maximum value should not be smaller than "time" in the "simulation" session. This array should be monotonically increasing. The size of "piecewise_density" should be the same as that of "piecewise_s"

"diag" : session array(*), optional -- For the species, we have two examples for the diagnostic session:

Example 1 : 3D desntiy diagnostics for the species

{
"name" : ["charge","jx"],
"ndump" : 1
}

"name" : string array(*)-- Available options are "charge" (for dumping species charge density) and "jx", "jy" and "jz" (for dumping species current densities).
"ndump" : ingteger -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.

Example 2 : 2D slice of the species desntiy

{
"name" : ["charge"],
"ndump" : 1,
"slice" : [["xz", 129],["yz",129]]
}

"name" : string array(*) -- Available options are "charge" (for dumping species charge density) and "jx", "jy" and "jz" (for dumping species current densities).
"ndump" : integer -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.
"slice" : array(*) -- Each component is a two-componet array containing a string and an integer. The string is "xz", "yz" or "xy" indicating the slice orientation. The integer is the position of that slice in the cell number.

Note that the position of the center slice in x (y, z) in the box is .

2. Hollow Channel with Sharp Edge

"profile" : 10 -- The profile ID for the hollow channel with sharp edge.

"ppc" : integer array(2) -- The numbers of simulated particles per cell in x and y directions.

"q" : real -- The charge for each plasma particle. E.g., it is -1.0 for an electron.

"m" : real -- The rest mass for each plasma particle. E.g. it is 1.0 for an electron and 1836.15267389 for a proton.

"density" : real -- The density of the plasma.

"longitudinal_profile" : string -- It can be "uniform" or "piecewise".

"piecewise_density" : real array(*) -- The density array for the longitudinal piecewise plasma profile.

Note that the actual plasma density will be the product of the "density" value and "piecewise_density" value.

"piecewise_s" : real array(*) -- The s array for the longitudinal piecewise plasma profile.

Note that minimum value of this array should not be larger than 0.0 and the maximum value should not be smaller than "time" in the "simulation" session. This array should be monotonically increasing. The size of "piecewise_density" should be the same as that of "piecewise_s"

"center" : real array(2) -- The center of the hollow channel.

"inner_radius" : real array(2) -- The inner ellipse radii of the hollow channel.

"outer_radius" : real array(2) -- The outer ellipse radii of the hollow channel.

"diag" : session array(*), optional -- For the species, we have two examples for the diagnostic session:

Example 1 : 3D desntiy diagnostics for the species

{
"name" : ["charge","jx"],
"ndump" : 1
}

"name" : string array(*)-- Available options are "charge" (for dumping species charge density) and "jx", "jy" and "jz" (for dumping species current densities).
"ndump" : ingteger -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.

Example 2 : 2D slice of the species desntiy

{
"name" : ["charge"],
"ndump" : 1,
"slice" : [["xz", 129],["yz",129]]
}

"name" : string array(*) -- Available options are "charge" (for dumping species charge density) and "jx", "jy" and "jz" (for dumping species current densities).
"ndump" : integer -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.
"slice" : array(*) -- Each component is a two-componet array containing a string and an integer. The string is "xz", "yz" or "xy" indicating the slice orientation. The integer is the position of that slice in the cell number.

Note that the position of the center slice in x (y, z) in the box is .

3. Hollow Channel with a Gaussian Wall

"profile" : 11 -- The profile ID for the hollow channel with a Gaussian wall

"ppc" : integer array(2) -- The numbers of simulated particles per cell in x and y directions.

"q" : real -- The charge for each plasma particle. E.g., it is -1.0 for an electron.

"m" : real -- The rest mass for each plasma particle. E.g. it is 1.0 for an electron and 1836.15267389 for a proton.

"density" : real -- The density of the plasma.

"longitudinal_profile" : string -- It can be "uniform" or "piecewise".

"piecewise_density" : real array(*) -- The density array for the longitudinal piecewise plasma profile.

Note that the actual plasma density will be the product of the "density" value and "piecewise_density" value.

"piecewise_s" : real array(*) -- The s array for the longitudinal piecewise plasma profile.

Note that minimum value of this array should not be larger than 0.0 and the maximum value should not be smaller than "time" in the "simulation" session. This array should be monotonically increasing. The size of "piecewise_density" should be the same as that of "piecewise_s"

"center" : real array(2) -- The center of the hollow channel.

"radius" : real -- The radius of the hollow channel (distance between the center of the channel and the center of the wall).

"width" : real -- The rms width of the wall.

"diag" : session array(*), optional -- For the species, we have two examples for the diagnostic session:

Example 1 : 3D desntiy diagnostics for the species

{
"name" : ["charge","jx"],
"ndump" : 1
}

"name" : string array(*)-- Available options are "charge" (for dumping species charge density) and "jx", "jy" and "jz" (for dumping species current densities).
"ndump" : ingteger -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.

Example 2 : 2D slice of the species desntiy

{
"name" : ["charge"],
"ndump" : 1,
"slice" : [["xz", 129],["yz",129]]
}

"name" : string array(*) -- Available options are "charge" (for dumping species charge density) and "jx", "jy" and "jz" (for dumping species current densities).
"ndump" : integer -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.
"slice" : array(*) -- Each component is a two-componet array containing a string and an integer. The string is "xz", "yz" or "xy" indicating the slice orientation. The integer is the position of that slice in the cell number.

Note that the position of the center slice in x (y, z) in the box is .

4. Hollow Channel with a Piecewise radial profile

"profile" : 12 -- The profile ID for the hollow channel with a piecewise radial profile.

"ppc" : integer array(2) -- The numbers of simulated particles per cell in x and y directions.

"q" : real -- The charge for each plasma particle. E.g., it is -1.0 for an electron.

"m" : real -- The rest mass for each plasma particle. E.g. it is 1.0 for an electron and 1836.15267389 for a proton.

"density" : real -- The density of the plasma is the product of "density" and "piecewise_radial_density".

"longitudinal_profile" : string -- It can be "uniform" or "piecewise".

"piecewise_density" : real array(*) -- The density array for the longitudinal piecewise plasma profile.

Note that the actual plasma density will be the product of the "density" value and "piecewise_density" value and "piecewise_radial_density" value.

"piecewise_s" : real array(*) -- The s array for the longitudinal piecewise plasma profile.

Note that minimum value of this array should not be larger than 0.0 and the maximum value should not be smaller than "time" in the "simulation" session. This array should be monotonically increasing. The size of "piecewise_density" should be the same as that of "piecewise_s"

"center" : real array(2) -- The center of the hollow channel.

"piecewise_radial_density" : real array(*) -- The density array for the radial piecewise plasma profile.

Note that the actual plasma density will be the product of the "density" value and "piecewise_density" value and "piecewise_radial_density" value.

"piecewise_r" : real array(*) -- The r array for the radial piecewise plasma profile.

This array should be monotonically increasing. The size of "piecewise_radial_density" should be the same as that of "piecewise_r"

"diag" : session array(*), optional -- For the species, we have two examples for the diagnostic session:

Example 1 : 3D desntiy diagnostics for the species

{
"name" : ["charge","jx"],
"ndump" : 1
}

"name" : string array(*)-- Available options are "charge" (for dumping species charge density) and "jx", "jy" and "jz" (for dumping species current densities).
"ndump" : ingteger -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.

Example 2 : 2D slice of the species desntiy

{
"name" : ["charge"],
"ndump" : 1,
"slice" : [["xz", 129],["yz",129]]
}

"name" : string array(*) -- Available options are "charge" (for dumping species charge density) and "jx", "jy" and "jz" (for dumping species current densities).
"ndump" : integer -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.
"slice" : array(*) -- Each component is a two-componet array containing a string and an integer. The string is "xz", "yz" or "xy" indicating the slice orientation. The integer is the position of that slice in the cell number.

Note that the position of the center slice in x (y, z) in the box is .

The "field" session

In the "field" session, we have the "diag" sessions for setting the diagnostics for field quantities.

"diag" : session array(*), optional -- For the fields, we have two examples for the diagnostic session:

Example 1 : 3D field diagnostics

{
"name" : ["ex","ez"],
"ndump" : 1
},

"name" : string array(*)-- Available options are "ex", "ey", "ez", "bx", "by", "bz" and "psi" (which is the pseudo potention of the plasma wake).
"ndump" : ingteger -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.

Example 2 : 2D slice of the field.

{
"name" : ["ex","by","ez","psi"],
"ndump" : 1,
"slice" : [["xz", 129],["yz", 129]]
}

"name" : string array(*)-- Available options are "ex", "ey", "ez", "bx", "by", "bz" and "psi" (which is the pseudo potention of the plasma wake).
"ndump" : ingteger -- For ndump = i, the code will dump the data every i time steps. If i = 0, the code will not dump the data.
"slice" : array(*) -- Each component is a two-componet array containing a string and an integer. The string is "xz", "yz" or "xy" indicating the slice orientation. The integer is the position of that slice in the cell number.

Note that the position of the center slice in x (y, z) in the box is .

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Input File for QuickPIC

Introduction

The Format of the Input File

Several Concepts

QuickPIC Input File

The "simulation" session

The "beam" session

1. Tri-Gaussian Beam

2. Transversely bi-Gaussian and longitudinally piece-wise Beam

3. Longitudinally Gaussian Beam with Twiss parameters

The "species" session

1. Transversely Uniform Plasma

2. Hollow Channel with Sharp Edge

3. Hollow Channel with a Gaussian Wall

4. Hollow Channel with a Piecewise radial profile

The "field" session

Clone this wiki locally