Notes for developers¶
Note
There is a makefile with handy targets for running tests, etc - use make list
to show these.
Setup¶
One should install PythiaPlotter in “editable” mode using pip.
This is easily done using make installe
(note the e), or
make reinstalle
to uninstall and reinstall.
Developers should install the packages in tests/requirements.txt
for
running the tests, and docs/requirements.txt
for making the docs:
pip install docs/requirements.txt
pip install tests/requirements.txt
Design Notes¶
The program is designed to be easy to extend in the event that more support needs to be added for different input or output formats. Because of this, there is a strong divide between the parsing part of the program, and the plotting/printing part.
These two parts communicate by exchanging an Event
object,
which contains a NetworkX MultiDiGraph
object that holds the graph structure and particles.
In addition, there is a divide between the physical objects in an event, and the structure that connects them. This offers several advantages:
- uniform way to access particle relationships regardless of input or output mode
- separation of physical particle attributes from graph structure and attributes (e.g. parent nodes, etc)
- separation of visual attributes from physical attributes.
The last point is important: this way, we can easily assign a NodeAttr
object to each node, and an EdgeAttr
to each edge, to hold the display
options and decouple the visual attributes from the physical attributes.
By sub-classing those *Attr
objects for different output formats,
we can easily implement a new output format without interference with other output formats.
Testing¶
There are various make targets to run tests easily:
make test
: run unit testsmake test-examples
: run full execution of the program, for a variety of input optionsmake cov
: run coverage.py and make a HTML reportmake benchmark
: run performance metrics (mostly timing of components)
There are also various targets for linting, etc:
make lint
: run pylintmake lint-py3
: run pylint’s python3 checker Note this is not perfect!make flake
: run flake8
Docs can be made locally by doing make docs
.
Conventions / Style¶
Lines should be < 100 lines, but sometimes going over makes more sense than horrible linebreaks. Try and fix all linter errors/warnings, but sometimes they are silly. Use Numpy-style for docstrings. All code should be compatible with python 2.7 and >=3.4. The compatibilty with 2.7 is because a significant proportion of HEP is still forced to use it, but at the same time we should forsee migration to python 3.