Introduction

POSTPIC

The open source particle-in-cell post processor.

Particle-in-cell simulations are a valuable tool for the simulation of non-equelibrium systems in plasma- or astrophysics. Such simulations usually produce a large amount of data consisting of electric and magnetic field data as well as particle positions and momenta. While there are various PIC codes freely available, the task of post-processing – essentially condensing the large amounts of data into small units suitable for plotting routines – is typically left to each user individually. As post-processing may be a time consuming and error-prone process, this python package has been developed.

Postpic can handle two different types of data:

Field data

which is data sampled on a predefined grid, such as electic and magnetic fields, particle- or charge densities, currents, etc. Fields are usually the data, which can be plotted directly. See postpic.Field.

Particle data

which is data of multiple particles and for each particle positions (x, y, z) and momenta (px, py, pz) are known. Particles usually also have weight, charge, time and a unique id. Postpic can transform particle data to field data using the same algorithm and particle shapes, which are used in most PIC Simulations. The particle-to-grid routines are written in C for maximum performance. See postpic.MultiSpecies.

What is postpic?

Postpic is an open-source package aiming to ease the postprocessing of particle-in-cell simulation data. Particle-in-cell simulations are often used to simulate the behaviour of plasmas in non-equilibrium states.

The Datareader package contains methods and interfaces to read data from any Simulation.

The basic concept consits of two different types of readers:

The Dumpreader

This has to be subclassed from Dumpreader_ifc and allows to read a single dump created by the simulation. To identify which dump should be read its initialized with a dumpidentifier. This dumpidentifier can be almost anything, but in the easiest case this is the filepath pointing to a single file containing every information about this simulation dump. With this information the dumpreader must be able to read all data regarding this dump (which is a lot: X, Y, Z, Px, Py, Py, weight, mass, charge, ID,.. for all particle species, electric and magnetic fields on grid, the grid itself, mabe particle ids,…)

The Simulationreader

This has to be subclassed from Simulationreader_ifc and allows to read a full list of simulation dumps. Thus an alternate Name for this class could be “Dumpsequence”. This allows the code to track particles from different times of the simulation or create plots with a time axis.

Stephan Kuschel 2014

postpic.datareader.chooseCode(code)

Chooses appropriate reader for the given simulation code. After choosing a preset of the correct reader, the functions postpic.readDump() and postpic.readSim() are setup for this preset.

Parameters:code (string) –

Possible options are:

• ”DUMMY”: dummy class creating fake data.
• ”EPOCH”: .sdf files written by EPOCH1D, EPOCH2D or EPOCH3D.
• ”openPMD”: .h5 files written in openPMD Standard
• ”piconGPU”: same as “openPMD”
• ”VSIM”: .hdf5 files written by VSim.

postpic.datareader.readDump(dumpidentifier, **kwargs)

After using the fucntion postpic.chooseCode(), this function should be the main function for reading a dump into postpic.

Parameters:

• dumpidentifier (str) – Identifies the dump. For most dumpreaders this is a string poining to the file or folder. See what the specific reader of your format expects.
• **kwargs – will be forwarded to the dumpreader.

Returns:

the dumpreader for this specific data dump.

Return type:

Dumpreader

postpic.datareader.readSim(simidentifier, **kwargs)

After using the function postpic.chooseCode(), this function should be the main function for reading a simulation into postpic. A simulation is equivalent to a series of dumps in a specific order (not neccessarily time order).

Parameters:

• simidentifier (str) – Identifies the simulation. For EPOCH this should be a string pointing to a .visit file. Specifics depend on the current simreader class, as set by chooseCode.
• **kwargs – will be forwarded to the simreader.

Returns:

the Simulationreader

postpic.datareader.setdumpreadercls(dumpreadercls)

Sets the class that is used for reading dumps on later calls of postpic.readDump().

Parameters:dumpreadercls (Dumpreader_ifc) –

Note

This should only be used, for testing. A set of presets is provided by postpic.chooseCode().

postpic.datareader.setsimreadercls(simreadercls)

Sets the class that is used for reading a simulation on later calls of postpic.readSim().

Parameters:simreadercls (Simulationreader_ifc) –

Note

This should only be used, for testing. A set of presets is provided by postpic.chooseCode().

class postpic.datareader.Dumpreader_ifc(dumpidentifier, name=None)

Interface class for reading a single dump. A dump contains informations about the simulation at a single timestep (Usually E- and B-Fields on grid + particles).

Any Dumpreader_ifc implementation will always be initialized using a dumpidentifier. This dumpidentifier can be anything, that points to the data of a dump. In the easiest case this is just the filename of the dump holding all data of that timestep (for example .sdf file for EPOCH, .hdf5 for some other code).

The dumpreader should provide all necessary informations in a unified interface but at the same time it should not restrict the user to these properties of there dump only. The recommended implementation is shown here (EPOCH and VSim reader work like this): All (!) data, that is saved in a single dump should be accessible via the self.__getitem__(key) method. Together with the self.keys() method, this will ensure, that every dumpreader works as a dictionary and every dump attribute is accessible via this dictionary.

• Level 0:

__getitem__ and keys(self) are level 0 methods, meaning it must be possible to access everthing with those methods.

• Level 1:

provide direct data access by forwarding the requests to the corresponding Level 0 or Level 1 methods.

• Level 2:

provide user access to the data by forwarding the request to Level 1 or Level 2 methods, but NOT to Level 0 methods.

If some attribute wasnt dumped a KeyError must be thrown. This allows classes which are using the reader to just exit if a needed property wasnt dumped or to catch the KeyError and proceed by actively ignoring it.

It is highly recommended to also override the functions __str__ and gridpoints.

Parameters:dumpidentifier – variable type whatever identifies the dump. It is recommended to use a String here pointing to a file.

data(key)

access to every raw data. needs to return numpy arrays corresponding to the “key”.

getSpecies(species, attrib)

This function gives access to any of the particle properties in ..helper.attribidentify This method can behave in the following ways: 1) Return a list of scalar properties for each particle of this species 2) Return a single float (i.e. 1.2, NOT [1.2]) to show that

every particle of this species has the same scalar value to thisdimmax property assigned. This might be quite often used for charge or mass that are defined per species.

3. Raise a KeyError if the requested property or species wasn dumped.

gridnode(key, axis)

The grid nodes along “axis”. Grid nodes include the beginning and the end of the grid. Example: If the grid has 20 grid points, it has 21 grid nodes or grid edges.

gridoffset(key, axis)

offset of the beginning of the first cell of the grid.

gridpoints(key, axis)

Number of grid points along “axis”. It is highly recommended to override this method due to performance reasons.

gridspacing(key, axis)

size of one grid cell in the direction “axis”.

keys()

Returns:a list of keys, that can be used in __getitem__ to read any information from this dump.

simdimensions()

the number of spatial dimensions the simulations was using. Must be 1, 2 or 3.

simextent(axis)

returns the extent of the actual simulation box. Override in your own reader class for better performance implementation.

class postpic.datareader.Simulationreader_ifc(simidentifier, name=None)

Interface for reading the data of a full Simulation.

Any Simulationreader_ifc implementation will always be initialized using a simidentifier. This simidentifier can be anything, that points to the data of multiple dumps. In the easiest case this can be the .visit file.

The Simulationreader_ifc is subclass of collections.Sequence and will thus behave as a Sequence. The Objects in the Sequence are supposed to be subclassed from Dumpreader_ifc.

It is highly recommended to also override the __str__ function.

Parameters:simidentifier – variable type something identifiying a series of dumps.

postpic.readDump(dumpidentifier, **kwargs)

After using the fucntion postpic.chooseCode(), this function should be the main function for reading a dump into postpic.

Parameters:

• dumpidentifier (str) – Identifies the dump. For most dumpreaders this is a string poining to the file or folder. See what the specific reader of your format expects.
• **kwargs – will be forwarded to the dumpreader.

Returns:

the dumpreader for this specific data dump.

Return type:

Dumpreader

postpic.readSim(simidentifier, **kwargs)

After using the function postpic.chooseCode(), this function should be the main function for reading a simulation into postpic. A simulation is equivalent to a series of dumps in a specific order (not neccessarily time order).

Parameters:

• simidentifier (str) – Identifies the simulation. For EPOCH this should be a string pointing to a .visit file. Specifics depend on the current simreader class, as set by chooseCode.
• **kwargs – will be forwarded to the simreader.

Returns:

the Simulationreader