postpic.datareader package

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)

Bases: postpic._field_calc.FieldAnalyzer

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.

__eq__(other)

Two dumpreader are equal, if they represent the same dump.

Assuming both dumpidentifier are paths to the dumpfiles, simple string comparison may give a “False”, although they both point to the same file: * ./path/to/file * path/to/file * /absolute/path/to/file

Therefore this functions tries to interpret the dumpidentifier as paths/to/files. In case this is successful and both files exist, the function checks if they point to the same file.

__getitem__(key)

access to everything. May return hd5 objects corresponding to the “key”.

data(key)

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

dataB(component, **kwargs)

dataE(component, **kwargs)

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.

gridkeyB(component, **kwargs)

gridkeyE(component, **kwargs)

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.

listSpecies()

name

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.

simgridpoints(axis)

simgridspacing(axis)

time()

timestep()

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

Bases: collections.abc.Sequence

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.

__getitem__(key)

name

times()

Submodules

postpic.datareader.datareader module

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

Bases: postpic._field_calc.FieldAnalyzer

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.

__eq__(other)

Two dumpreader are equal, if they represent the same dump.

Assuming both dumpidentifier are paths to the dumpfiles, simple string comparison may give a “False”, although they both point to the same file: * ./path/to/file * path/to/file * /absolute/path/to/file

Therefore this functions tries to interpret the dumpidentifier as paths/to/files. In case this is successful and both files exist, the function checks if they point to the same file.

__getitem__(key)

access to everything. May return hd5 objects corresponding to the “key”.

data(key)

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

dataB(component, **kwargs)

dataE(component, **kwargs)

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.

gridkeyB(component, **kwargs)

gridkeyE(component, **kwargs)

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.

listSpecies()

name

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.

simgridpoints(axis)

simgridspacing(axis)

time()

timestep()

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

Bases: collections.abc.Sequence

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.

__getitem__(key)

name

times()

postpic.datareader.dummy module

Dummy reader for creating fake simulation Data for testing purposes.

Stephan Kuschel 2014

class postpic.datareader.dummy.Dummyreader(dumpid, dimensions=2, randfunc=<built-in method normal of mtrand.RandomState object>, seed=0, **kwargs)

Bases: postpic.datareader.datareader.Dumpreader_ifc

Dummyreader creates fake Data for testing purposes.

Parameters:dumpid – int the dumpidentifier is the dumpid in this case. It is a float variable, that will also change the dummyreaders output (for example it will pretend to have dumpid many particles).

__eq__(other)

Two dumpreader are equal, if they represent the same dump.

Assuming both dumpidentifier are paths to the dumpfiles, simple string comparison may give a “False”, although they both point to the same file: * ./path/to/file * path/to/file * /absolute/path/to/file

Therefore this functions tries to interpret the dumpidentifier as paths/to/files. In case this is successful and both files exist, the function checks if they point to the same file.

__getitem__(key)

access to everything. May return hd5 objects corresponding to the “key”.

data(axis)

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.

grid(key, axis)

Parameters:axis – string or int the axisidentifier

Returns: list of grid points of the axis specified.

Thus only regular grids are supported currently.

gridnode(key, axis)

Parameters:axis – string or int the axisidentifier

Returns: list of grid points of the axis specified.

Thus only regular grids are supported currently.

gridoffset(key, axis)

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

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.

listSpecies()

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.

simgridpoints(axis)

time()

timestep()

class postpic.datareader.dummy.Dummysim(simidentifier, dimensions=2, **kwargs)

Bases: postpic.datareader.datareader.Simulationreader_ifc

postpic.datareader.epochsdf module

Reader for SDF File format written by the EPOCH Code.

Dependecies:

• sdf: The actual python reader for the .sdf file format written in C. It is part of the EPOCH code base and needs to be compiled and installed from there.

Written by Stephan Kuschel 2014, 2015

class postpic.datareader.epochsdf.Sdfreader(sdffile, **kwargs)

Bases: postpic.datareader.datareader.Dumpreader_ifc

The Reader implementation for Data written by the EPOCH Code in .sdf format. Written for SDF v2.2.0 or higher. SDF can be obtained without EPOCH from SDF.

Parameters:sdffile – String A String containing the relative Path to the .sdf file.

__getitem__(key)

access to everything. May return hd5 objects corresponding to the “key”.

data(key)

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

dumpsize()

returns the file size of the sdf file in bytes.

getSpecies(species, attrib)

Returns one of the attributes out of (x,y,z,px,py,pz,weight,ID,mass,charge) of this particle species. raises KeyError if the requested species or property wasnt dumped.

getderived()

Returns all Keys starting with “Derived/”.

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.

listSpecies()

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.

simgridpoints(axis)

Returns the number of grid points of the actual simulation.

time()

timestep()

class postpic.datareader.epochsdf.Visitreader(visitfile, dumpreadercls=<class 'postpic.datareader.epochsdf.Sdfreader'>, **kwargs)

Bases: postpic.datareader.datareader.Simulationreader_ifc

Reads a series of dumps specified in a .visit file. This is specifically written for .visit files from the EPOCH code, but should also work for any other code using these files.

postpic.datareader.openPMDh5 module

Support for hdf5 files following the openPMD Standard.

Dependecies:

• h5py: read hdf5 files with python

Written by Stephan Kuschel 2016

class postpic.datareader.openPMDh5.OpenPMDreader(h5file, **kwargs)

Bases: postpic.datareader.datareader.Dumpreader_ifc

The Reader implementation for Data written in the hdf5 file format following openPMD naming conventions.

Parameters:h5file – String A String containing the relative Path to the .h5 file.

__del__()

__getitem__(key)

access to everything. May return hd5 objects corresponding to the “key”.

data(key)

should work with any key, that contains data, thus on every hdf5.Dataset, but not on hdf5.Group. Will extract the data, convert it to SI and return it as a numpy array. Constant records will be detected and converted to a numpy array containing a single value only.

getSpecies(species, attrib)

Returns one of the attributes out of (x,y,z,px,py,pz,weight,ID,mass,charge) of this particle species.

getderived()

return all other fields dumped, except E and B.

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.

listSpecies()

simdimensions()

the number of spatial dimensions the simulation was using.

time()

timestep()

class postpic.datareader.openPMDh5.FileSeries(simidentifier, dumpreadercls=<class 'postpic.datareader.openPMDh5.OpenPMDreader'>, **kwargs)

Bases: postpic.datareader.datareader.Simulationreader_ifc

Reads a time series of dumps from a given directory. The simidentifier is expanded using glob in order to find matching files.

postpic.datareader.vsimhdf5 module

Reader for HDF5 File format written by the VSim Code: http://www.txcorp.com/support/vsim-support-menu/vsim-documentation Dependecies: h5py The Python actual reader for hdf5 file format. Georg Wittig, Stephan Kuschel 2014

class postpic.datareader.vsimhdf5.Hdf5reader(h5file, **kwargs)

Bases: postpic.datareader.datareader.Dumpreader_ifc

The Reader implementation for HDF5 Data written by the VSim Code. as argument h5file can be any *.h5 file of the dump of consideration.

__getitem__(key)

delivers one dataset with the key key.

dataB(axis, **kwargs)

dataE(axis, **kwargs)

getSpecies(species, attrib)

Returns one of the attributes out of (x,y,z,px,py,pz,weight,ID) of this particle species. Valid Scalar attributes are (mass, charge).

getderived()

Returns all Keys starting with “Derived/”.

grid(axis)

returns the array of the positions of all cells on axis = axis.

keys()

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

listSpecies()

returns all h5 dumps that have a attribute “mass”

simdimensions()

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

time()

timestep()

class postpic.datareader.vsimhdf5.VSimReader(path, **kwargs)

Bases: postpic.datareader.datareader.Simulationreader_ifc

Represents a full Simulation ( = Series of Dumps with equal output). The VSimReader must be initialized with the path to a folder containing all the dumps. It will then walk through all available .h5 files in this directory to identify the available timesteps of the simulation.

getDumpreader(index)