Package: topsy
topsyThis package visualises simulations, and is an add-on to thepynbodyanalysis package.
Its name nods to theTIPSYproject.
It is built usingwgpu, which is a future-facing GPU standard (with thanks to thepython wgpu bindings).At the moment,topsyis a bit of a toy project, but it already works quite well with zoom
(or low resolution) simulations. The future development path will depend on the level
of interest from the community.InstallingYou will need python 3.10 or later, running in a UNIX variant (basically MacOS, Linux or if you're on Windows you needWSL). You can then installtopsyusingpipas usual:pip install topsyThis will install topsy and its dependencies (includingpynbodyitself) into
your current python environment. (If it fails, check that you have python 3.10
or later, andpipis itself up-to-date usingpip install -U pip.)As usual, you can also install direct from github, e.g.pip install git+https://github.com/pynbody/topsyOr clone the repository and install for development usingpip install -e .from inside the cloned repository.If you want to play withtopsywithout disturbing your current installation,
I recommend usingvenv:# create a toy environment
python -m venv visualiser-env

# activate the new environment
source visualiser-env/bin/activate 

# install
pip install topsy

... other commands ...

# get your old environment back:
deactivateFor more information about venv, see itstutorial page.Trying it outQuick start: if you just want to try it out and you don't have a
suitable simulation snapshot to hand, you can download some
from thetangos tutorial datasets (4.8GB).
You need to untar them (tar -xzf tutorial_changa.tar.gzfrom your command line), then
you can typetopsy pioneer50h128.1536gst1.bwK1.000832to visualise that file's
dark matter content.Long version:The package provides one simple command calledtopsy, to be
called straight from your shell. Passtopsythe path to the
simulation that you wish to visualise.You can (and probably should) also
tell it what to center on using the-cflag, to which valid arguments are:-c none(just loads the file without changing the centering)-c halo-1(uses the shrink sphere center of halo 1; or you can change 1 to any other number)-c zoom(uses the shrink sphere center on the highest resolution particles, without loading a halo catalogue)-c all(uses the shrink sphere center on all particles in the file)By default, it will show you dark matter particles. To change this pass-p gasto show gas particles or-p starfor
stars.If your particles have other quantities defined on them (such astempfor gas particles), you can view the
density-weighted average quantity by passing-q temp. Other quantities can be seleBy default, topsy uses matplotlib'stwilight_shiftedcolormap. To change this pass, for example,-m viridis, or the name
of any othermatplotlib colormap.
This can also be changed in real-time from the topsy window.Controls in the main windowIf everything works, a window will pop up with a beautiful rendering of your simulation. Make sure the window
is in focus (for some reason on MacOS I sometimes have to switch to another application then back to
python to get this to work). Then you can use the following controls:To spin around the centre, drag the mouse.To zoom in and out, use the mouse scroll wheel.To move the centre, hold shift while dragging the mouse.To rescale the colours to an appropriate range for the current view, pressr(ange)To return the view to the original orientation and zoom, pressh(ome)To save a snapshot of the current image as a pdf presss(ave)Using from jupyterThanks tojupyter-rfb, it is possible to usetopsywithin a jupyter notebook. This requires a little more
knowledge than the command line version, but is still fairly straight-forward if
you are familiar withpynbody. To open a topsy view within your jupyter notebook,
tryimportpynbodyimporttopsyf=pynbody.load("/path/to/file")f.physical_units()h=f.halos()pynbody.analysis.halo.center(h[1])vis=topsy.topsy(f.dm)vis.canvasThis loads your data intof, performs some centering, creates thetopsyviewer and then the final line (vis.canvas) instructsjupyterto bring up the interactive widget.Note that you can interact with this widget in exactly the same way as the native window produced bytopsy. Additionally, you can manipulate things on the fly. For example, you can typevis.quantity_name = 'temp'to immediately switch to viewing temperature (compare with the-qflag above).