Documentation for Hyplot
- Author:
- Sander Valcke
Astronomical Observatory
University of Ghent
Belgium
sander [dot] valcke [at] ugent [dot] be
To get hyplot up and running you roughly have to go through the following steps:
- install cmake (2.6 or above)
- install the necessary libraries (in case of error: if you have not done so already install the "dev" library of a package) (cmake should notify you of missing libraries, it does not check yet for the python version however, nor for some dev packages. I have also seen it mark packages as found when they were not so don't panick if installation fails, check the error message and you'll know which package you are lacking):
Packages:
- Qt4 (4.3 and above, need libqt4-dev)
- Python (2.6 or above)
- PyQt4 (python-qt4, python-qt4-dev)
- pyuic4 (on Ubuntu found in the pyqt4-dev-tools package)
- matplotlib (which should give you numpy)
- gsl (the gnu scientific library: gsl and/or gsl-dev)
- sip (sip4 package sip4, python-sip4, python-sip4-dev)
- compile:
- cd to the hyplot base directory
- cmake .
- make
- If everything went according to plan you should be able to run the hyplot script found in directory "rundir"
In case of any problems please feel free to contact us!
Note for Mac users: for those of you that don't know it: there are good package repositories for Mac, an example being Fink (http://www.finkproject.org/). This can save you the trouble of installing the required packages manually.
Gui mode gives you a selection of plots:
- scatter: plot particles
- grid: bin the particles onto a grid, display this grid as a 2D color image
- render: (from splash, Daniel Prices code) for SPH particles: produce a nice color image based on SPH particle smoothing lengths (and the cubic spline kernel)
- Svenzogram: a scatter plot of e.g. particle density as a function of e.g. y, for particles in a certain e.g. x-range.
Some features of the GUI:
- Plotting done by the powerful matplotlib package
- Full support for Latex in labels, titles, ...
- Working with the gui is very intuitive, you can easily change plot types (e.g. on a rendered plot of an SPH simulation: zoom in on a boundary and plot a scatter plot of that region) and/or zoom.
- The gui is setup as an MDI window, meaning that you can open lots of plots in different subwindows at the same time. These are controlled by hyplot: they do not clutter your taskbar and on closing hyplot the corresponding plots are closed.
- It is possible to apply a python script to an existing plot. This means that you have the power of matplotlib, and indeed the power of python at your disposal to modify plots at will. A simple example is adding an analytical function plot to an existing plot.
doxygen support is built-in into hyplot in the sense that is integrated into the cmake build system and most of the classes are documented in the proper style. If you have doxygen installed doing a swift "make doc" should produce a Documentation/html folder full of goodies, just open the index.html with your favourite browser and you're good to go.
Although doxygen supports python for some reason it does not interpret the standard escape sequences when present in the python way of documenting things (through docstrings). One way of solving this is by documenting python code in the doxygen way, but we prefer documenting python code the python way. This can be solved in a very simple way by using an input filter for python files. An example is doxypy: http://code.foosel.org/doxypy Then go to your Doxyfile and alter the line
FILTER_PATTERNS =
to read: FILTER_PATTERNS = *.py=doxypy.py
et voila, perfect support for standard python documentation!
Quite some work has been put into the graphical part of hyplot: the gui and the associated plotting. For plotting we started off using pgplot, where we were very soon faced with its limitations (no object-orientation, strict way of representing data, difficult to handle the colorbar, ...) but the main turnoff was that it did not have a Qt device, which we needed to be able to plot in our Qt Gui. Although a Qt device for pgplot has been developed it is not a standard part of it, using it would require people to modify and reinstall their pgplot library.
We thus decided to migrate away from pgplot, to plplot (what's in a name :p). After fully integrating plplot into the code we decided that it also did not fit our needs: standard 2D color plots did not seem to be possible Oo. We did not find any other good plotting package supporting Qt in C/C++ (or fortran, for that matter). There is however the beautiful matplotlib Python package, which does everything we want (and more!). Only downside (from our point of view, having a C/C++/Fortan code): it's Python. After some digging and toying there was a first attempt to have python create a QWidget with the plot, which was returned to the C++ part of the code. Although this approach worked it was hard to have the plot itself interact with the code. We then decided to rewrite the gui we had so far in Python, and wrapping our C++ API using sip, allowing Python to call it. Our code has thus now become a Python code with C++ extensions which do all the heavy lifting: reading/storing the data, calculating renderings, calculating CMDs, ...
And that's how we ended up with a code which is a mixture of C/C++/Fortran/Python :p
At present we are still stuck with storing our data in long, static arrays. You can thus either read the data and then copy it to those arrays (the approach used in
CDataGadget), or read it directly into those arrays. This includes reading the data into arrays in the fortran common block.
At some point this underlying static structure will disappear and it will be possible to just inherit CDataReader with your own class (like we have done with CDataGadget), overriding some virtual routines and that should do it.
