README.md 3.92 KB
Newer Older
1
postpic
2
=======
Stephan Kuschel's avatar
Stephan Kuschel committed
3

4
[![Build Status](https://travis-ci.org/skuschel/postpic.svg?branch=master)](https://travis-ci.org/skuschel/postpic)
5
[![PyPI version](https://badge.fury.io/py/postpic.png)](http://badge.fury.io/py/postpic)
6
[![Documentation Status](https://readthedocs.org/projects/postpic/badge/?version=latest)](https://postpic.readthedocs.org/)
7

Stephan Kuschel's avatar
typos    
Stephan Kuschel committed
8
Postpic is an open-source post-processor for Particle-in-cell (PIC) simulations written in python. If you are doing PIC Simulations (likely for you PhD in physics...) you need tools to provide proper post-processing to create nice graphics from many GB of raw simulation output data -- regardless of what simulation code you are using.
Stephan Kuschel's avatar
Stephan Kuschel committed
9
10
11
12
13

**For working examples, please go to  https://github.com/skuschel/postpic-examples**

The (technical, but complete) documentation is hosted on
https://postpic.readthedocs.io/en/latest/
14

Stephan Kuschel's avatar
Stephan Kuschel committed
15

16
Idea of postpic
17
18
---------------

Stephan Kuschel's avatar
Stephan Kuschel committed
19
The basic idea of postpic is to calculate the plots you are interested in just from the basic data the simulation provides. This data includes electric and magnetic fields and a tuple (`weight`, `x`, `y`, `z`, `px`, `py`, `pz`, `id`, `mass`, `charge`, `time`) for every macro-particle. Anything else you like to look at (for example a spectrum at your detector) should just be calculated from these values. This is exactly what postpic can do for you, and even more:
20

21
postpic has a unified interface for reading the required simulation data. If the simulation code of your choice is not supported by postic, this is the perfect opportunity to add a new datareader.
22

23
Additionally postpic can plot and label your plot automatically. This makes it easy to work with and avoids mistakes. Currently matplotlib is used for that but this is also extensible.
24
25


Stephan Kuschel's avatar
Stephan Kuschel committed
26

Stephan Kuschel's avatar
Stephan Kuschel committed
27
28
Installation
------------
29

30
Postpic can be used with `python2` and `python3`. However the usage of `python3` is recommended.
31

32
**Users** should install the latest version directly from github using `pip` (python package manager):
33

Stephan Kuschel's avatar
Stephan Kuschel committed
34
`pip install --user git+https://github.com/skuschel/postpic.git`
35

36
37
Please note that, depending on your system python setup, `pip` may default to `python2`.
In that case you will need use `pip3` instead to make sure that postpic is installed for `python3`:
Stephan Kuschel's avatar
Stephan Kuschel committed
38

39
40
41
42
43
44
45
`pip3 install --user git+https://github.com/skuschel/postpic.git`

The latest *release* is also available in the python package index [pypi](https://pypi.python.org/pypi/postpic/), thus it can be installed by using the python package manager pip:

`pip install --user postpic`

In both cases the `--user` option makes sure that the package can be installed without `root` privileges by installing it into your user profile.
46

Stephan Kuschel's avatar
Stephan Kuschel committed
47
**Developers** should clone the git repository (or their fork of it) and install it using
48

49
`pip install --user -e .`
50

Stephan Kuschel's avatar
Stephan Kuschel committed
51
This command will link the current folder to global python scope, such that changing the code will immediately update the installed package.
52

Stephan Kuschel's avatar
Stephan Kuschel committed
53
**After installing** you should be able to import it into any python session using `import postpic`.
54

Stephan Kuschel's avatar
Stephan Kuschel committed
55
56
57
58
Postpic's main functions should work but there is still much work to do and lots of documentation missing. If postpic awakened your interest you are welcome to contribute. Even if your programming skills are limited there are various ways how to contribute and adopt postpic for your particular research. Read [CONTRIBUTING.md](../master/CONTRIBUTING.md).


Postpic in Science
59
60
------------------

61
If you use postpic for your research and present or publish results, please show your support for the postpic project and its [contributers](https://github.com/skuschel/postpic/graphs/contributors) by:
62
63
64
65

  * Add a note in the acknowledgements section of your publication.
  * Drop a line to one of the core developers including a link to your work to make them smile (there might be a public list in the future).

Stephan Kuschel's avatar
Stephan Kuschel committed
66

67
68
69
70
License
-------

Postpic is released under GPLv3+. See [http://www.gnu.org/licenses/gpl-howto.html](http://www.gnu.org/licenses/gpl-howto.html) for further information.