Plotting Scripts

Overview

Athena++ is bundled with several Python scripts designed to plot data generated by the code. These are meant to give users a quick and easy way to visualize the data, as well as to provide a launching point for development of more customized analysis tools for a given project.

The scripts are located in vis/python/. The are:

• plot_lines.py, which makes line plots from .hst or .tab files;
• plot_slice.py, which plots either 2D data or 2D slices of 3D data in .athdf files;
• plot_spherical.py, which plots vertical or midplane slices of data in spherical coordinates, properly accounting for geometry.

The scripts are detailed below. All scripts can be run with the -h option to print usage help. All scripts require the Matplotlib Python module.

---

plot_lines.py

Makes a line plot of one quantity versus another. Multiple relations from multiple files can be overplotted. Data must come from Athena++ .hst or .tab files.

Usage: plot_lines.py <data_files> <x_names> <y_names> <output_file> [<options>]

Positional arguments:

• data_files: comma-separated list of input files.
• x_names: comma-separated list of abscissas.
• y_names: comma-separated list of ordinates.
• output_file: name of output to be (over)written; use show to show interactive plot instead.
• Note: The first three arguments allow multiple quantities from multiple files to be overplotted. For convenience, the three lists are automatically extended to have the same length as the longest one. Any such extensions repeat the last given entry. Also, empty entries (i.e. no characters appearing between two commas) indicate the previous entry should be repeated.

Optional arguments:

• -s, --styles: comma-separated list of line or marker styles, such as - or o; use the -s=<styles> or --styles=<styles> form of the argument if the first entry begins with a dash; empty entries are interpreted as solid lines.
• -c, --colors: comma-separated list of color codes, such as k, blue, or #123abc; empty entries result in black (single line) or default color cycling (multiple lines).
• -l, --labels: comma-separated list of labels for legend; empty entries are not added to legend; strings can include mathematical notation inside $...$.
• --x_log: flag indicating x-axis should be logarithmically scaled.
• --y_log: flag indicating y-axis should be logarithmically scaled.
• --x_min: minimum for x-axis.
• --x_max: maximum for x-axis.
• --y_min: minimum for y-axis.
• --y_max: maximum for y-axis.
• --x_label: label to use for x-axis.
• --y_label: label to use for y-axis.
• Note: Empty entries in --styles, --colors, and --labels refer to no characters appearing between commas. For --styles and --colors the last entry is repeated as necessary to match the number of entries in the positional arguments.

---

plot_slice.py

Makes a 2D color plot of a single quantity from an Athena++ .athdf file. 3D data will be sliced, averaged, or summed as requested. A stream plot of a vector field from the same file can be overlayed.

Caution: This script is best used with data in Cartesian (or Minkowski) coordinates. Plots are made in the coordinate space, for example in the r/phi-plane rather than the x/y-plane in spherical and cylindrical coordinates. Averaging and summing are done in a naive way, with no attempt to account for variations in cell volumes along the chosen direction. Stream plots are similarly done as simply as possible, without accounting for subtleties with vector bases. For an alternative in spherical coordinates, see plot_spherical.py.

Usage: plot_slice.py <data_file> <quantity> <output_file> [<options>]

Positional arguments:

• data_file: name of input file, possibly including path.
• quantity: name of quantity to be plotted.
• output_file: name of output to be (over)written, possibly including path; use show to show interactive plot instead.

Optional arguments:

• -d, --direction: direction orthogonal to slice for 3D data; must be 1, 2, or 3 (default).
• --slice_location: coordinate value along which slice is to be taken; default 0.
• -a, --average: flag indicating averaging should be done in orthogonal direction for 3D data.
• -s, --sum: flag indicating summation should be done in orthogonal direction for 3D data.
• -l, --level: refinement level to be used in plotting; defaults to maximum level in file.
• --x_min: minimum extent of plot in first plotted direction (not necessarily x).
• --x_max: maximum extent of plot in first plotted direction (not necessarily x).
• --y_min: minimum extent of plot in second plotted direction (not necessarily y).
• --y_max: maximum extent of plot in second plotted direction (not necessarily y).
• -f, --fill: flag indicating image should fill plot area, even if this distorts the aspect ratio.
• -c, --colormap: name of Matplotlib colormap to use instead of default.
• --vmin: data value to correspond to colormap minimum; use the --vmin=<vmin> form of the argument if the value has a negative sign.
• --vmax: data value to correspond to colormap maximum; use the --vmax=<vmax> form of the argument if the value has a negative sign.
• --logc: flag indicating data should be colormapped logarithmically.
• --stream: name of vector quantity to use to make stream plot.
• --stream_average: flag indicating stream plot should be averaged in orthogonal direction for 3D data.
• --stream_density: density of stream lines; default 1.0.
• Note: The result when using --sum is the same as when using --average but multiplied by the full width of the domain in the collapsed direction. --fill is recommended for non-Cartesian coordinates. If making a stream plot with --stream <name> then <name>1, <name>2, etc. must be quantities found in the file.