1D EM-PIC code

1D, electro-magnetic, fully relativistic, Particle-in-Cell code, using a finite-difference EM field solver

Classes

class Current

Electric current density class

This class allows access to the electric current density data structures in the simulation. An object of this class is created automatically when creating a Simulation object.

See Also

Simulation

Instance variables

var Jx

Jx current density component

Grid of (scalar) Jx field values excluding guard cells

Returns

Jx : numpy.array, (nx)

X component values of the current density

var Jy

Jy current density component

Grid of (scalar) Jy field values excluding guard cells

Returns

Jy : numpy.array, (nx)

Y component values of the current density

var Jz

Jz current density component

Grid of (scalar) Jz field values excluding guard cells

Returns

Jz : numpy.array, (nx)

Z component values of the current density

Methods

def report(jc)

Save diagnostic information to disk. Files will be saved in the CURRENT directory below the current working directory.

Parameters

jc : {0,1,2}

Current density component to save, must be one of 0 (x), 1 (y) or 2 (z)

class Density (type='uniform', start=0.0, end=0.0, n=1.0, ramp=[0.0, 0.0], custom=None)

Class representing charge density profiles for particle species initialization

Parameters

type : str, optional

Density profile type, one of "uniform", "empty", "step", "slab" or "custom", defaults to "uniform"

start : float, optional

Position of the plasma start position for "step", "slab" or "ramp" profiles, defaults to 0.0

end : float, optional

Position of the plasma end position for the "slab" or "ramp" profiles, defaults to 0.0

n : float, optional

Reference density to use, multiplies density profile value, defaults to 1.0

ramp : list of float

2 element list specifying the required density at the start and end positions for the "ramp" density profile, defaults to [0.,0.]

custom : function, optional

Custom density function, defaults to None

See Also

Species

Instance variables

var end

Position of the plasma end position for "slab" or "ramp" profiles

Returns

end : float

Position of the plasma end position

var n

Reference density to use

Returns

n : float

Reference density to use

var ramp

Initial and final density values for the "ramp" profile

Returns

ramp : numpy.array, (2)

[start,end] density values

var start

Position of the plasma start position for "step", "slab" or "ramp" profiles

Returns

start : float

Position of the plasma start position

var type

Density profile type

Returns

type : {'uniform', 'empty', 'step', 'slab', 'ramp','custom'}

Density profile type

Methods

def copy()

Object copy.

class EMF

Electro-Magnetic fields class

This class allows access to the EM field data structures in the simulation. An object of this class is created automatically when creating a Simulation object.

See Also

Simulation

Instance variables

var Bx

Bx field component

Grid of (scalar) Bx field values excluding guard cells

Returns

Bx : numpy.array, (nx)

X component values of the magnetic field.

var Bx_part

Bx field component (as seen by particles)

Grid of (scalar) Bx field values excluding guard cells. If external fields are enabled this will be the sum of the self- consistent fields and the external fields

Returns

Bx_part : numpy.array, (nx)

X component values of the total magnetic field.

var By

By field component

Grid of (scalar) By field values excluding guard cells

Returns

By : numpy.array, (nx)

Y component values of the magnetic field.

var By_part

By field component (as seen by particles)

Grid of (scalar) Bx field values excluding guard cells. If external fields are enabled this will be the sum of the self- consistent fields and the external fields

Returns

By_part : numpy.array, (nx)

Y component values of the total magnetic field.

var Bz

Bz field component

Grid of (scalar) Bz field values excluding guard cells

Returns

Bz : numpy.array, (nx)

Z component values of the magnetic field.

var Bz_part

Bz field component (as seen by particles)

Grid of (scalar) Bx field values excluding guard cells. If external fields are enabled this will be the sum of the self- consistent fields and the external fields

Returns

Bz_part : numpy.array, (nx)

Z component values of the total magnetic field.

var Ex

Ex field component

Grid of (scalar) Ex field values excluding guard cells

Returns

Ex : numpy.array, (nx)

X component values of the electric field.

var Ex_part

Ex field component (as seen by particles)

Grid of (scalar) Ex field values excluding guard cells. If external fields are enabled this will be the sum of the self- consistent fields and the external fields

Returns

Ex_part : numpy.array, (nx)

X component values of the total electric field.

var Ey

Ey field component

Grid of (scalar) Ey field values excluding guard cells

Returns

Ey : numpy.array, (nx)

Y component values of the electric field.

var Ey_part

Ey field component (as seen by particles)

Grid of (scalar) Ey field values excluding guard cells. If external fields are enabled this will be the sum of the self- consistent fields and the external fields

Returns

Ey_part : numpy.array, (nx)

Y component values of the total electric field.

var Ez

Ez field component

Grid of (scalar) Ey field values excluding guard cells

Returns

Ez : numpy.array, (nx)

Z component values of the electric field.

var Ez_part

Ez field component (as seen by particles)

Grid of (scalar) Ex field values excluding guard cells. If external fields are enabled this will be the sum of the self- consistent fields and the external fields

Returns

Ez_part : numpy.array, (nx)

Z component values of the total electric field.

var bc_type

Type of boundary conditions to be used for EM fields

Returns

bc_type : {'periodic', 'open'}

Type of boundary conditions

var box

Simulation box physical size

Returns

box : float

Simulation box size

var dx

Cell size used for the EMF object

Returns

dx : int

Cell size

var energy

EM field energy per field component

Returns

energy : numpy.array, (6)

Total energy in each field component. Electric field energy is in the first 3 values and magnetic field energy is in the last 3 values.

Note

These values are recalculated each time this function is called.

var n_move

Number of cell moves by the moving simulation window

Returns

n_move : int

Number of cell moves by the moving simulation window

var nx

Grid size used for the EMF object

Returns

nx :int

Number of grid cells for the simulation

var solver_type

Field solver algorithm used

Returns

solver : 'Yee'

Field solver, currently only 'Yee' is supported

Methods

def init_fld(init)

Sets initial EM field values. This method can only be called before the simulation starts.

Parameters

init : InitialField

Initial field parameters

See Also

InitialField

Note

Use of this function has been deprecated and will be removed soon. Use the init_fld parameter of the Simulation class instead.

def report(type, fc)

Save diagnostic information to disk. Files will be saved in the EMF directory below the current working directory.

Parameters

type : {'E','B','Ep','Bp'}

Type of data to save, must be one of 'E' (electric field), 'B' (magnetic field), 'Ep' (self-consistent + external electric field), 'Bp' (self-consistent + external magnetic field)

fc : {0,1,2}

Field component to save, must be one of 0 (x), 1 (y) or 2 (z)

def set_ext_fld(ext)

Sets external EM field values. This method can only be called before the simulation starts.

Parameters

ext : ExternalField

External field parameters

See Also

ExternalField

Note

Use of this function has been deprecated and will be removed soon. Use the ext_fld parameter of the Simulation class instead.

class ExternalField (E_type='none', B_type='none', E_0=[0.0, 0.0, 0.0], B_0=[0.0, 0.0, 0.0], E_custom=None, B_custom=None)

Used for defining external EM fields in the simulation

Parameters

E_type : {'none','uniform','custom'}, optional

Type of external electric field to use, must be one of 'none' (no external field), 'uniform' (uniform external field) or 'custom' (custom external field defined by a function), defaults to 'none'

B_type : {'none','uniform','custom'}, optional

Type of magnetic electric field to use, must be one of 'none' (no external field), 'uniform' (uniform external field) or 'custom' (custom external field defined by a function), defaults to 'none'

E_0 : list of float, optional

3 element list specifying electric field value for 'uniform' external field type, defaults to [0.,0.,0.]

B_0 : list of float, optional

3 element list specifying magnetic field value for 'uniform' external field type, defaults to [0.,0.,0.]

E_custom : `function``

Python function for calculating all 3 components of external electric field at every cell

B_custom : `function``

Python function for calculating all 3 components of external magnetic field at every cell

Instance variables

var B_0

Magnetic field value for 'uniform' external field type

Returns

B0 : numpy.ndarray, (3)

Vector field value for 'uniform' external field type

var B_custom

Python function used for 'custom' external B field type

Returns

func : function

Python function for calculating all 3 components of external magnetic field at every cell

var B_type

Type of external B field

Returns

type : {'none','uniform','custom'}

Type of external field

var E_0

Electric field value for 'uniform' external field type

Returns

E0 : numpy.ndarray, (3)

Vector field value for 'uniform' external field type

var E_custom

Python function used for 'custom' external E field type

Returns

func : function

Python function for calculating all 3 components of external electric field at every cell

var E_type

Type of external E field

Returns

type : {'none','uniform','custom'}

Type of external field

Methods

def copy()

Object copy.

class InitialField (E_type='none', B_type='none', E_0=[0.0, 0.0, 0.0], B_0=[0.0, 0.0, 0.0], E_custom=None, B_custom=None)

Used for defining initial EM fields in the simulation

Parameters

E_type : {'none','uniform','custom'}, optional

Type of initial electric field to use, must be one of 'none' (no initial field), 'uniform' (uniform initial field) or 'custom' (custom initial field defined by a function), defaults to 'none'

B_type : {'none','uniform','custom'}, optional

Type of initial electric field to use, must be one of 'none' (no initial field), 'uniform' (uniform initial field) or 'custom' (custom initial field defined by a function), defaults to 'none'

E_0 : list of float, optional

3 element list specifying electric field value for 'uniform' initial field type, defaults to [0.,0.,0.]

B_0 : list of float, optional

3 element list specifying magnetic field value for 'uniform' initial field type, defaults to [0.,0.,0.]

E_custom : `function``

Python function for calculating all 3 components of initial electric field at every cell

B_custom : `function``

Python function for calculating all 3 components of initial magnetic field at every cell

Instance variables

var B_0

Magnetic field value for 'uniform' initial field type

Returns

E0 : numpy.ndarray, (3)

Vector field value for 'uniform' initial field type

var B_custom

Python function used for 'custom' initial B field type

Returns

func : function

Python function for calculating all 3 components of initial magnetic field at every cell

var B_type

Type of initial B field

Returns

type : {'none','uniform','custom'}

Type of initial field

var E_0

Electric field value for 'uniform' initial field type

Returns

E0 : numpy.ndarray, (3)

Vector field value for 'uniform' initial field type

var E_custom

Python function used for 'custom' initial E field type

Returns

func : function

Python function for calculating all 3 components of initial electric field at every cell

var E_type

Type of initial E field

Returns

type : {'none','uniform','custom'}

Type of initial field

Methods

def copy()

Object copy.

class Laser (start=0.0, fwhm=0.0, rise=0.0, flat=0.0, fall=0.0, a0=0.0, omega0=0.0, polarization=0.0)

Class representing laser pulses. Laser pulses are added to the simulation using the Simulation.add_laser() method.

Parameters

start : float, optional

Position of the starting (leading) point for the laser envelope, defaults to 0.

fwhm : float, optional

Full width at half-max of the laser pulse. If set it overrides the rise, flat, and fall parameters, defaults to 0

rise, flat, fall : float, optional

Rise time (rise), flat time (flat) and fall time (fall) of the temporal envelope, default to 0

a0 : float, optional

Normalized vector potential value at peak intensity of the laser pulse, default to 0

omega0 : float, optional

Laser frequency in simulation units, defaults to 0

polarization : float, optional

Laser polarization in radians measured in reference to the y direction, defaults to 0

See Also

Simulation

Instance variables

var a0

Normalized vector potential value at peak intensity of the laser pulse

Returns

a0 : float

Normalized vector potential value

var fall

Fall length of laser envelope

Returns

fall : float

fall length of laser envelope

var flat

Flat length of laser envelope

Returns

flat : float

flat length of laser envelope

var fwhm

FWHM of laser envelope

Returns

fwhm : float

Full width at half-max of the laser pulse

var omega0

Laser frequency in simulation units

Returns

omega0 : float

Laser frequency

var polarization

Laser polarization in radians measured in reference to the y direction

Returns

pol : float

Polarization angle

var rise

Rise length of laser envelope

Returns

rise : float

Rise length of laser envelope

var start

Start position of laser envelope

Returns

start : float

Position of the starting (leading) point for the laser envelope

class Simulation (nx, box, dt, species=None, report=None, mov_window=False, smooth=None, init_fld=None, ext_fld=None)

ZPIC EM1D Simulation class

Parameters

nx : int

Number of grid cells for the simulation

box : float

Simulation box (phyiscal) size, in simulation units

dt : float

Simulation time step, in simulation units

species : Species or list of Species, optional

Particle species to use in the simulation, defaults to None (no particles)

report : function, optional

Python function used for simulation reporting, defaults to None

mov_window : bool, optional

Use a moving simulation window, defaults to False

smooth : Smooth, optional

Electric current smoothing options, defaults to None

init_fld : InitialField, optional

Initial EM fields for the simulation, defaults to None (0 initial fields)

ext_fld : ExternalField, optional

External EM fields for the simulation, defaults to None

See Also

Species Smooth InitialField ExternalField

Instance variables

var box

Simulation box physical size

Returns

box : float

Simulation box size

var current

Simulation electric current density object

Returns

current : Current

Simulation electric current density object

var dt

Time step used for the simulation

Returns

dt :float

Time step

var dx

Cell sizes used for the simulation

Returns

dx : float

Cell size

var emf

Simulation EM fields object

Returns

emf : EMF

Simulation EM fields object

var n

Current simulation iteration number

This number is advanced automatically by calls to the iter() and run() methods

Returns

n : int

Current simulation iteration number

var n_move

Number of cell moves by the moving simulation window

Returns

n_move : int

Number of cell moves by the moving simulation window

var nx

Grid size used for the simulation

Returns

nx : int

Number of grid cells for the simulation

var report

Report function for the simulation

This function will be called once before each time step when using the run() method.

Returns

report : function

Report function for the simulation

var species

Simulation particle species list

Returns

species : list of Species

Simulation particle species list

var t

Current simulation time value

This value is advanced automatically by calls to the iter() and run() methods

Returns

t : float

Current simulation simulation time

Methods

def add_laser(laser)

Adds laser pulse to the simulation

Parameters

laser : Laser

Laser pulse to be added to the simulation

See Also

Laser

def iter()

Advance simulation 1 iteration.

def run(tmax)

Advance simulation up to time tmax. If specified earlier, the report function will be called before each iteration.

Parameters

tmax : float

Intended final simulation time. If smaller than current simulation time, a warning message will be displayed

def set_moving_window()

Turns on moving window for the simulation

Note

Use of this function has been deprecated and will be removed soon. Use the mov_window parameter of the Simulation class instead.

def set_smooth(smooth)

Sets electric current smoothing (digital filtering) parameters

Parameters

smooth : Smooth

Smooth object specifying smoothing parameters

See Also

Smooth

Note

Use of this function has been deprecated and will be removed soon. Use the smooth parameter of the Simulation class instead.

class Smooth (xtype='none', ytype='none')

Digital smoothing parameter for the Electric current density.

Parameters

xtype : {'none', 'binomial', 'compensated'}, optional

Type of digital filtering to apply along the x direction, defaults to 'none'

xlevel : int

Number of filtering passes to apply along the x direction, defaults to 0

Instance variables

var xlevel

Level of digital filtering to use along x

Returns

xlevel : int

Number of filtering passes to apply along x

var xtype

Type of digital filtering to use along x

Returns

xtype : {'none', 'binomial', 'compensated'}

Type of digital filtering to use along x

class Species (name, m_q, ppc, ufl=[0.0, 0.0, 0.0], uth=[0.0, 0.0, 0.0], density=None, n_sort=16, bc_type='periodic')

Class representing particle species. Particle data can be accessed (read/write) using the particles property.

Parameters

name : str

Name used to identify the particle species

m_q : float

Mass over charge ration in for particles in the species in simulaition units (e.g. for electrons use -1)

ppc : list

Number of particles per cell in the form [nx,ny]

ufl : list, optional

Initial fluid (generalized) velocity for the particles, defaults to [0,0,0] (no fluid velocity)

uth : list, optional

Initial thermal velocity for the particles, defaults to [0,0,0] (no thermal velocity).

density : Density, optional

Density profile for the particle species specified as using a Density object. Defaults to None which corresponds to a uniform density of value 1

n_sort : int, optional

Number of iterations between particle sort, defaults to 16

bc_type : {'periodic', 'open'}, optional

Type of boundary conditions to be used for the species, must be one of 'periodic' (periodic boundaries), 'open' (absorbing boundaries), defaults to 'periodic'

See Also

Density

Instance variables

var bc_type

Type of boundary conditions to be used for the species

Returns

bc_type : {'periodic', 'open'}

Type of boundary conditions

var dt

Time step used for advancing the species

Returns

dt : float

Time step in simulation units

var dx

Cell size used for the species

Returns

dx :float

Cell size

var energy

Total kinetic energy of particle species

Returns

ene : float

Time-centered total kinetic energy of particle species

Note

To ensure the correct time-centering the particle kinetic energy is calculated during the particle advance, so it will be 0 before the first iteration is completed

var iter

Last iteration completed by the particle species

Returns

iter : int

Iteration number

var n_move

Number of cell moves by the moving simulation window

Returns

n_move : int

Number of cell moves by the moving simulation window

var n_sort

Number of iterations between sorting particle data buffer

Returns

n_sort : int

Number of iteration between sorts

var particles

ndarray of particle data

Allows full read/write access to particle data

var ppc

Number of particles per cell used for initializing new particles from density profile.

Returns

ppc : float

Number of particles per cell

Methods

def add(ix, x, u)

Adds a new particle to the particle buffer

Parameters

ix : int[:]

New particle cell index

x : float[:]

New particle position inside the cell

u : float[:]

New particle (generalized velocity)

def charge()

Calculate charge density of particle species

Returns

n : numpy.array, (nx)

Charge density of particle species. Array will jhave the same shape as the simulation grid

def phasespace(quants, pha_nx, pha_range)

Calculate phasespace density of particle species

Parameters

quants : list of str

2 element list of quantities to use for "pha" diagnostics. Each quantity must be one of 'x1', 'u1', 'u2' or 'u3'

pha_nx : list of int, optional

2 element list specifying the size of the phasespace grid

pha_range : list of float, optional

2x2 element list specifying the physical limits of the phasespace grid in the form [[xmin,xmax],[ymin,ymax]]

Returns

pha : numpy.ndarray, (pha_nx[0],pha_nx[1])

Phasespace density of particle species.

def report(type, quants=[], pha_nx=[], pha_range=[])

Saves diagnostic information to disk

Parameters

type : {"charge", "pha", "particles"}

Type of information to save, must be one of "charge" (charge density), "pha" (phasespace density), or "particles" (raw particle data)

quants : list, optional

2 element list of quantities to use for "pha" diagnostics. Each quantity must be one of 'x1', 'u1', 'u2' or 'u3'

pha_nx : list of int, optional

2 element list specifying the size of the phasespace grid

pha_range : list of float, optional

2x2 element list specifying the physical limits of the phasespace grid in the form [[xmin,xmax],[ymin,ymax]]