Skip to content

Latest commit

 

History

History
265 lines (171 loc) · 9.41 KB

documentation.md

File metadata and controls

265 lines (171 loc) · 9.41 KB

ZPIC-CUDA Documentation

Simulation parameters

ZPIC-CUDA simulation objects are instances of the Simulation class:

Simulation( uint2 const ntiles, uint2 const nx, float2 const box, float dt )

The constructor takes the following parameters:

  • ntiles - Number of tiles to be used for partitioning the simulation grid
  • nx - Individual tile grid size (global grid size will be ntitles * nx)
  • box- Global simulation box size (in simulation units)
  • dt - Simulation time step (in simulation units)

Adding particle species

Particle species can be added to the simulation using the Simulation::add_species() method:

void add_species( std::string const name, float const m_q, uint2 const ppc, Density::Profile const & dens, UDistribution::Type const & udist )
  • name - Name of the particle species. Used for diagnostics only.
  • m_q - Mass over charge ratio of individual particles in simulation units. For electrons this would be $-1.0$.
  • ppc - Number of particles per cell to use
  • dens - Initial density profile, see "Initial density profile" section below for details.
  • udist - Initial velocity (u) distribution, see "Initial velocity (u) distribution" section below for details.

Setting a moving window

After adding all the particle species to the simulation, users can set the "moving window" algorithm using the Simulation::set_moving_window() method:

void set_moving_window()

No further action is required.

Advancing the simulation one time step

The simulation can be made to advance 1 iteration by calling the Simulation::advance() method:

void advance()

This will complete all the steps in the particle-in-cell loop, namely:

  • Zeroing the current
  • Advancing the species (and depositing the current)
  • Advancing the EM fields
  • Advancing the iteration number

Getting global enery report

A global energy report (particles, electric field, magnetic field, total energy ) can be generated by calling the Simulation::energy_info() method:

void energy_info()

Initial density profile

Initial density profiles are set using sub-classes of the Density::Profile class. Available options are:

Uniform density

Density::Uniform( float const n0 )`

Uniform plasma density

  • n0 - Plasma density (in simulation units)

Step density profile

Density::Step( coord::cart dir, float const n0, float const pos )

Step-like plasma density, injects uniform plasma after a given position. Can be set in both x and y directions.

  • dir - step direction, must be either coord::x or coord::y
  • n0 - Plasma density (in simulation units)
  • pos - Step position (in simulation units)

Slab profile

Slab( coord::cart dir, float const n0, float begin, float end )

Slab-like plasma density, injects uniform plasma density only inside given range. Can be set in both x and y directions.

  • dir - slab normal direction, must be either coord::x or coord::y
  • n0 - Plasma density (in simulation units)
  • begin - Lower slab boundary position (in simulation units)
  • end - Upper slab boundary position (in simulation units)

Spherical density profile

Uniform spherical plasma, injects uniform plasma density centered about a given position

Sphere( float const n0, float2 center, float radius )
  • n0 - Plasma density (in simulation units)
  • center - Sphere center position (in simulation units)
  • radius - Sphere radius (in simulation units)

Initial velocity (u) distribution

The initial velocity distribution of simulation particles is set using sub-classes of the UDistribution::Type class. Available options are:

None

UDistribution::None()

Sets 0 velocity for all particles.

Cold

UDistribution::Cold( float3 const ufl )

Sets a cold (0 temperature) beam with a given fluid velocity.

  • ufl - Particle fluid velocity (in simulation units)

Thermal

UDistribution::Thermal( float3 const uth, float3 const ufl )

Sets a normal thermal distribution with both thermal and fluid velocity components.

  • uth - Thermal distribution width (in simulation units)
  • ufl - Fluid velocity (in simulation units)

ThermalCorr

UDistribution::ThermalCorr( float3 const uth, float3 const ufl, int const npmin )

Sets a normal thermal distribution with both thermal and fluid velocity components corrected for local fluctuation. Before adding the global fluid velocity component, local fluid velocity resulting from low particle per cell numbers / PRNG variation is removed from the distribution. The distribution thermal width is preserved.

  • uth - Thermal distribution width (in simulation units)
  • ufl - Fluid velocity (in simulation units)
  • npmin - Minimum number of particles in local cell to apply correction. Must be > 1.

Electric current filtering

Electric current filtering can be set using sub-classes of the Filter::Digital class. These can be set using the Current::set_filter() method, e.g.:

sim.current->set_filter( Filter::Binomial ( coord::x, 2 ) );

Available options are:

None

Digital::None()

Does no filtering. This is the default behavior.

Binomial

Digital::Binomial( coord::cart dir, unsigned int order_ = 0 )

Applies a binomial filter ([1,2,1] kernel) a number of times along the specified direction.

  • dir - Direction for the filter, must be either coord::x or coord::y
  • order_ - Number of kernel passes. Defaults to 1 (1 pass)

Compensated

Digital::Compensated( coord::cart dir, unsigned int order_ = 0 )

Applies a binomial filter ([1,2,1] kernel) a number of times along the specified direction, followed by 1 pass of special kernel (compensator) that eliminates $k^3$ dependence in the filter response close to $k=0$ (i.e. makes the filter sharper).

Laser pulses

Laser pulses are added to the simulation using sub-classes of the Laser::Pulses class, as parameters to the EMF::add_laser() method. The object constructor sets default values for all laser parameters, and the user must then set the individual parameters one by one before adding the laser.

Currently lasers can only be launched along the x direction, propagating from left to right.

The laser EM field is filtered using a compensated filter (see the Electric Current Filtering section) to eliminate spurious high order frequency field components. This behavior can be controlled (or disabled) using the filter parameter. Please note that there will be a minor decrease in laser filed amplitude.

Plane wave

Laser::PlaneWave()

Launches a plane wave:

  • start - Front edge of the laser pulse (in simulation units)

  • fwhm - FWHM of the laser pulse duration (in simulation units)

  • rise, flat, fall - Rise, flat and fall time of the laser pulse (in simulation units)

  • a0 - Normalized peak vector potential of the pulse

  • omega0 - Laser frequency, normalized to the plasma frequency

  • polarization - Polarization angle in radians (defaults to 0). A value of 0 has the E-field polarized in the simulation plane (along y) while a value of $\pi/2$ has the E-field polarized outside of the simulation plane (along z).

  • cos_pol, sin_pol - Cosine and sine of the polarization angle (optional). If set, these values override the polarization parameter to set the laser polarization, and allow for greater accuracy in specifying the polarization angle. Note that values are not checked for consistency.

  • filter - Filter order (defaults to 1). Controls the number of passes of the digital filter. Setting this value to 0 disables filtering the laser pulse prior to injection.

Gaussian beam

Laser::Gaussian()

Launches a Gaussian beam. The beam parameters are the same as the plane wave parameters, plus:

  • W0 - Gaussian beam waist (in simulation units)
  • focus - Focal plane position along the x direction (in simulation units). Can be set outside the simulation box
  • axis - y position of the propagation axis (in simulation units)

Boundary conditions

Each simulation object (sim.emf, sim.current and sim.species[i]) has specific boundary condition options. Available options are:

  • EM Fields
    • emf::bc::none - Edge grid cells are not processed
    • emf::bc::periodic - Periodic boundary conditions
    • emf::bc::pmc - Perfect magnetic conductor (reflecting)
    • emf::bc::pec - Perfect electric conductor (electric)
  • Currents
    • current::bc::none - Edge grid cells are not processed
    • current::bc::periodic - Periodic boundary conditions
    • current::bc::reflecting - Reflecting boundary conditions (current deposited outside the simulation domain is folded into the box)
  • Species
    • species::bc::open - Particles leaving the simulation box are absorbed
    • species::bc::periodic - Periodic boundary conditions

By default, all simulation objects are initialized to periodic boundary conditions. Setting a moving window will enforce none boundary conditions (open for species) for along the x direction for simulation objects. Specific types of boundary conditions can be set using the *::set_bc( new_bc ) method.

Utilities (util.cuh)

  • deviceCheck()
    • Checks if there are any synchronous or asynchronous errors from CUDA calls. If any errors are found the routine will print out the error messages and exit the program
  • malloc_host( buffer, size )
    • Allocates page-locked memory on the host. In case of failure the routine will isse an error and abort.