Analysis

As discussed in Outputs, AthenaK supports multiple output formats. Depending on the format, there may be multiple ways to analyze the data.

Using AI assistants to make plots

Modern AI coding assistants (for example those built into editors such as Cursor, or command-line agents) are often the fastest way to explore and visualize AthenaK output, and they increasingly make many of the simplest bespoke plotting scripts unnecessary. Rather than hunting for or maintaining a one-off script, you can describe the figure you want and let the assistant write and run the plotting code for you.

A few tips that make this work well:

  • Point the assistant at the data readers. AthenaK ships small, well-documented readers in vis/python (for example bin_convert.py for .bin files). Ask the assistant to use these so it parses the file format correctly instead of guessing. The ASCII .hst and .tab files can be read directly with numpy.

  • Be specific about the request. State the input file, the variable, the slice (plane and location for 3D data), the colormap, the normalization (linear/log, vmin/vmax), and whether you want a single frame or an animation over a sequence of dumps.

  • Iterate. Ask for adjustments (“use a log scale”, “overplot the analytic solution”, “add the AMR block boundaries”) the same way you would refine any plot.

  • Verify the physics. AI-generated code is convenient but not infallible: sanity check units, derived quantities, and slice locations against a known case before trusting a new figure.

For quantitative or repeatable analysis you may still want a committed script, but for quick inspection and figure generation an AI assistant working directly against the output files is usually the shortest path.

Repository analysis tools

The AthenaK repository contains a number of simple scripts for reading data, all inside the vis/python directory.

plot_slice.py

This script can be used to read a .bin output, slice it (for 3D data), and plot an output variable. Here is an example:

python3 plot_slice.py -d y \      # Slice along the y axis
                      -l 0.0 \    # Slice location
                      --cmap viridis \                     # Matplotlib colormap
                      --norm log --vmin 1e-10 --vmax 1.0 \ # Colorbar normalization
                      --horizon \                          # Plot horizon location
                      gr_torus.mhd_w_bcc.00010.bin \       # input file
                      dens \                               # variable to plot
                      show                                 # show or output filename

This produces an output like the following:

torus

Additional arguments can be seen by using the -h option or reading the instructions at the beginning of the script.

plot_tab.py

This script can be used for quickly looking at tabulated data, including animations. Consider the following example:

python3 plot_tab.py -i tab/Sod.mhd_w_bcc.00000.tab \  # input file (stem if -n given)
                    -v dens \                          # variable to plot
                    -n 51                              # number of frames to read

This will generate an animation starting using Sod.mhd_w_bcc.[00000..00050].tab as inputs. The last frame will look something like the following:

st_rho

plot_hst.py

TODO

External analysis tools

AthenaK .vtk outputs can be read by any tool that reads legacy VTK files. .hst and .tab files are written as whitespace-separated ASCII files, so they can easily be read using numpy or similar tools. The .bin format is a bespoke format, so there are not currently plugins for major visualization suites. However, there are still some ways to read these files, either by converting them to a different format or using custom analysis tools.

Converting to Athena++ XDMF files

The make_athdf.py script can be used to convert .bin files into Athena++ .athdf files, which can be read into visualization software like VisIt or Paraview via their XDMF readers. In theory this also makes it possible to use many Athena++ tools (see the Athena++ wiki for more information), though be aware that AthenaK does have some small differences in naming conventions that can sometimes lead to incompatibilities.

Example:

python3 make_athdf.py bin/tov.mhd_w_bcc

This will glob all *.bin files with the stem tov.mhd_w_bcc, such as tov.mhd_w_bcc.00000.bin, tov.mhd_w_bcc.00001.bin, etc., and write out the corresponding .athdf and .athdf.xmdf files.

AthenaK-compatible libraries and tools

Some users have developed and shared their own analysis tools:

  • plot-tools: a collection of scripts maintained by Jacob Fields. Many of them are targeted toward numerical relativity applications, such as a utility for compact object trackers or the ejecta analysis scripts, though the basic file reading and plotting scripts are compatible with any dataset.

  • wongutils: a suite of tools developed by George Wong. These tools are excellent for 3D GRMHD data in Kerr-Schild spacetimes, such as accretion disks, and they include robust utilities for coordinate transformations, swapping between observer-frame and fluid-frame quantities, etc.

If you are interested in sharing your own analysis tools, please let us know!