FAQs

Is this manual up to date?

Whenever a new milestone version of EPOCH is finalised, the version number is changed and this manual is updated accordingly. The version number of the manual should match the first two digits for that of the EPOCH source code. This version number is printed to screen when you run the code. The line looks something like the following:

 Welcome to EPOCH2D version 4.16.0   (commit v4.16.0-0-g69eb0fa6-clean)

Here, only the number “4.16” is important.

Since version 3.1 of the manual, new additions and changes are mentioned in the appendix.

What is EPOCH?

EPOCH is a plasma physics simulation code which uses the Particle in Cell (PIC) method. In this method, collections of physical particles are represented using a smaller number of pseudoparticles, and the fields generated by the motion of these pseudoparticles are calculated using a finite difference time domain technique on an underlying grid of fixed spatial resolution. The forces on the pseudoparticles due to the calculated fields are then used to update the pseudoparticle velocities, and these velocities are then used to update the pseudoparticle positions. This leads to a scheme which can reproduce the full range of classical micro-scale behaviour of a collection of charged particles.

Features of EPOCH

MPI parallelised, explicit, second-order, relativistic PIC code.
Dynamic load balancing option for making optimal use of all processors when run in parallel.
MPI-IO based output, allowing restart on an arbitrary number of processors.
Data analysis and visualisation options include ITT IDL, LLNL VisIt, Mathworks MatLab and matplotlib in Python.
Control of setup and runs of EPOCH through a customisable input deck.

The origins of the code

The EPOCH family of PIC codes is based on the older PSC code written by Hartmut Ruhl and retains almost the same core algorithm for the field updates and particle push routines. EPOCH was written to add more modern features and to structure the code in such a way that future expansion of the code is made as easy as possible.

How do I obtain the code?

The latest version of EPOCH can be found on GitHub at https://github.com/Warwick-Plasma/epoch

A tarred and gzipped archive (commonly referred to as a tarball) of the latest release is always made available in the Releases section

Alternately, using git the code can be cloned using the following command. Note that it is important to include the ‘‘recursive’’ flag in order to download the SDF submodules..

git clone –recursive https://github.com/Warwick-Plasma/epoch.git

What normalisations are used in EPOCH?

Since the idea from the start was that EPOCH would be used by a large number of different users and that it should be as easy as possible to “plug in” different modules from different people into a given copy of the code, it was decided to write EPOCH in SI units. There are a few places in the code where some quantities are given in other units for convenience (for example charges are specified in multiples of the electron charge), but the entire core of the code is written in SI units.

What are those `_num` things doing everywhere?

Historically using the compiler auto-promotion of REAL to DOUBLE PRECISION was unreliable, so EPOCH uses “kind” tags to specify the precision of the code. The _num suffixes and the associated definition of REALs as REAL(num) are these “kind” tags in operation. The _num tags force numerical constants to match the precision of the code, preventing errors due to precision conversion. The important thing is that all numerical constants should be tagged with an _num tag and all REALs should be defined as REAL(num).

What is an input deck?

An input deck is text file which can be used to set simulation parameters for EPOCH without needing to edit or recompile the source code. It consists of a list of blocks which start as begin:blockname and end with end:blockname. Within the body of each block is a list of key/value pairs, one per line, with key and value separated by an equals sign. Most aspects of a simulation can be controlled using an input deck, such as the number of grid points in the simulation domain, the initial distribution of particles and initial electromagnetic field configuration. It is designed to be relatively easy to read and edit. For most projects it should be possible to set up a simulation without editing the source code at all. For more details, read the section titled “The EPOCH input deck”

I just want to use the code as a black box, or I’m just starting. How do I do that?

Begin by reading the basic examples. There’s quite a lot to learn in order to get started, so you should plan to read through all of this section. You will also need to refer to the input deck pages. Next, look at the code and have a play with some test problems. After that re-read this section. This should be enough for testing simple problems.

What is the auto-loader?

Throughout this document we will often refer to the “auto-loader” when setting up the initial particle distribution. In the input deck it is possible to specify a functional form for the density and temperature of a particle species. EPOCH will then place the particles to match the density function and set the velocities of the particles so that they match the Maxwellian thermal distribution for the temperature. The code which performs this particle set up is called the “auto-loader”.

At present, there is no way to specify a non-Maxwellian particle distribution from within the input deck. In such cases, it is necessary to edit and recompile the EPOCH source code. The recommended method for setting the initial particle properties is to use the “manual_load” function as described here.

What is a maths parser?

As previously mentioned, the behaviour of EPOCH is controlled using an input deck which contains a list of key/value pairs. The value part of the pair is not restricted to simple constants but can be a complex mathematical expression. It is evaluated at run time using a section of code called the “maths parser”. There is no need for the end user to know anything about this code. It is just there to enable the use of mathematical expressions in the input deck. Further information about this facility can be found here.

I am an advanced user, but I want to set up the code so that less experienced users can use it. How do I do that?

See here.

I want to develop an addition to EPOCH. How do I do that?

A slightly outdated developers manual exists which should be sufficient to cover most aspects of the code functionality. However, the code is written in a fairly modular and consistent manner, so reading through that is the best source of information. If you get stuck then you can post questions on the GitHub forums.

I want to have a full understanding of how EPOCH works. How do I do that?

If you really want to understand EPOCH in full, the only way is to read all of this manual and then read through the code. Most of it is commented.

How do I acknowledge use of the code?