topsy 0.8.1

topsy - An astrophysics simulation visualization package based on webgpu, using pynbody for reading data

https://github.com/user-attachments/assets/b185c3b8-8658-4f7d-96de-e976959e7ad6

topsy

This package visualises simulations, and is an add-on to the pynbody analysis package. Its name nods to the TIPSY project. It is built using wgpu, which is a future-facing GPU standard (with thanks to the python wgpu bindings).

At the moment, topsy is experimental, but has proven to work well in a variety of environments. It is mainly developed and optimized on Apple M-series chips, but has also been shown to work on NVidia GPUs.

The future development path will depend on the level of interest from the community.

Installing

You will need python 3.11 or later, running in a UNIX variant (basically MacOS, Linux or if you're on Windows you need WSL). You can then install topsy using pip as usual:

pip install topsy

This will install topsy and its dependencies (including pynbody itself) into your current python environment. (If it fails, check that you have python 3.11 or later, and pip is itself up-to-date using pip install -U pip.)

Alternative 1: install into isolated environment using pipx

You can also install topsy into its own isolated environment using pipx:

pipx install topsy

The command line tool will now be available, but you won't have access to the topsy package from your existing python environment. This can be useful if you don't want to risk disturbing anything.

Alternative 2: install into new environment using venv and pip

If you want to play with topsy without disturbing your existing installation, but also want to be able to use topsy from python scripts or jupyter etc, I recommend using venv:

# 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:
deactivate 

For more information about venv, see its tutorial page.

Alternative 3: install unreleased versions or contribute to development

As usual, you can also install direct from github, e.g.

pip install git+https://github.com/pynbody/topsy

Or clone the repository and install for development using

pip install -e .

from inside the cloned repository.

Trying it out

Very quick start

Once topsy is installed, if you just want to try it out and you don't have a suitable simulation snapshot to hand, you can download some from the tangos tutorial datasets (5.1GB). You need to untar them (tar -xzf tutorial_changa.tar.gz from your command line), then you can type topsy pioneer50h128.1536gst1.bwK1.000832 to visualise that file's dark matter content.

More detailed description

If using from the command line, pass topsy the path to the simulation that you wish to visualise.

You can (and probably should) also tell it what to center on using the -c flag, 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 gas to show gas particles or -p star for stars. Note that the particle type cannot be changed once the window is open (although you can open a separate window for each particle type; see below).

If your particles have other quantities defined on them (such as temp for gas particles), you can view the density-weighted average quantity by passing -q temp. The quantity to visualise can also be changed by selecting it via the main window controls (see below).

To open more than one visualisation window on different files or with different parameters, you can pass multiple groups of parameters separated by +, for example to see separate views of the gas and dark matter you could launch topsy with:

topsy -c halo-1 -p gas my_simulation + -c halo-1 -p dm my_simulation

You can choose to link the rotation/zoom of multiple views using the toolbar (see below).

Using SSPs

If you have stars in your simulation, you can try rendering using pynbody's SSP tables, using the command-line flag --render-mode rgb, or by selecting the RGB option in the colormap. Make sure you are visualising stars rather than any other particles e.g.

topsy -c halo-1 -p s --render-mode rgb my_simulation 

Even better, if you have an HDR display (e.g. recent Macbook Pros), you can use the --render-mode rgb-hdr flag to render in HDR mode.
Note in HDR mode that the magnitude range specified applies to the SDR range, i.e. HDR brightnesses extend beyond the specified maximum surface brightness limit. The exact brightest magntiude that can be displayed will depend on your display hardware.

Controls in the main window

The view in the topsy window can be manipulated as follows:

• To spin around the centre, drag the mouse.
• To zoom in and out, use the mouse scroll wheel.
• To move the centre, double click on a target (topsy will determine its depth), or shift-drag to move in x-y plane.
• To rescale the colours to an appropriate range for the current view, press r(ange)
• To return the view to the original orientation and zoom, press h(ome)

There is also a toolbar at the bottom of the window with some buttons:

• - start recording actions (rotations, scalings, movements and more). Press again to stop.
• - render the recorded actions into an mp4 file. You will be prompted about various options and a filename.
• - load and save the recorded actions to a file for later use.
• - save a snapshot of the current view to an image file.
• - link this window to other topsy windows, so that rotating, scaling or moving one does the same to the other
• - open colormap control; this lets you select the rendering mode, min/max values, the quantity to visualise, the matplotlib colormap and more.

Using from jupyter

It is possible to use topsy within a jupyter notebook. Graphics are rendered on the jupyter server, and displayed within the notebook.

To open a topsy view within your jupyter notebook, try

import topsy 
topsy.load("/path/to/simulation", particle="gas")

Note that you can interact with this widget in exactly the same way as the native window produced by topsy. Most of the same options you can pass on the command line are also available via this load function (type help(topsy.load) for details).