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 .athdf, .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++ .athdf, .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.

Example: Run a 1D shock tube and plot the initial and final density and pressure.

./configure.py \
  --prob shock_tube
make clean
make -j
bin/athena \
  -i inputs/hydro/athinput.sod \
  -d example

vis/python/plot_lines.py \
  example/Sod.block0.out1.00000.tab,,example/Sod.block0.out1.00025.tab, \
  x1v \
  rho,press,rho,press \
  example/lines.png \
  --styles=--,--,-,- \
  --colors b,r,b,r \
  --labels '$\rho_\mathrm{initial}$,$p_\mathrm{initial}$,$\rho_\mathrm{final}$,$p_\mathrm{final}$' \
  --x_min=-0.5 \
  --x_max=0.5 \
  --x_label '$x$'

---

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/φ-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.

Example: Run the Orszag-Tang vortex test and plot the final gas pressure, along with stream lines for the magnetic field.

./configure.py \
  -b \
  --prob=orszag_tang \
  -hdf5
make clean
make -j
bin/athena \
  -i inputs/mhd/athinput.orszag-tang \
  -d example \
  output2/file_type=hdf5 \
  mesh/nx1=100 \
  mesh/nx2=100 \
  meshblock/nx1=100 \
  meshblock/nx2=100

vis/python/plot_slice.py \
  example/OrszagTang.out2.00100.athdf \
  press \
  example/slice.png \
  --colormap plasma \
  --vmin 0.0 \
  --vmax 0.36 \
  --stream Bcc

---

plot_spherical.py

Makes a 2D color plot of a single quantity from an Athena++ .athdf file in spherical coordinates (spherical_polar, schwarzschild, or kerr-schild). The data will either be vertical (φ = 0,π) or horizontal (θ = π/2). A stream plot of a vector field from the same file can be overlayed. Data, including vector directions, is plotted in the expected way, for example in the x/y-plane rather than the r/φ-plane.

Caution: In general relativity the conversion from the original coordinates to Cartesian coordinates for plotting is not exactly metric-preserving. Instead, plots are made assuming r, θ, and φ are the standard spherical coordinates in Minkowski spacetime. This script does not account for black hole mass or spin in any way.

Note: This script requires the SciPy Python module if making stream plots.

Usage: plot_spherical.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:

• -m, --midplane: flag indicating plot should be in the plane θ = π/2 rather than φ = 0,π.
• -a, --average: flag indicating φ-averaging should be done.
• -l, --level: refinement level to be used in plotting; defaults to maximum level in file.
• -r, --r_max: maximum radial extent of plot.
• --logr: flag indicating data should be plotted logarithmically in radius.
• -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.
• -s, --stream: name of vector quantity to use to make stream plot.
• --stream_average: flag indicating φ-averaging should be done on stream plot data.
• --stream_density: density of stream lines; default 1.0.
• --stream_samples: linear size of stream line sampling grid; default 100.
• --theta_compression: compression parameter h in θ = π * x² + (1-h)/2 * sin(2*π*x²).

Note: If --average or --stream_average are set, even midplane plots are averaged in φ. If making a stream plot with --stream <name> then <name>1, <name>2, etc. must be quantities found in the file. Stream plots can take some time to produce, especially with large values of --stream_samples. --theta_compression should be set if and only if the data was generated on a grid with such compression.

Example: Run the spherical blast wave off-center in spherical coordinates and plot the final density in a vertical slice.

./configure.py \
  --prob blast \
  --coord spherical_polar \
  -hdf5
make clean
make -j
bin/athena \
  -i inputs/hydro/athinput.blast_sph \
  -d example \
  output1/file_type=hdf5 \
  mesh/x2min=0.0 \
  mesh/x2max=3.141592653589793 \
  mesh/ix2_bc=polar \
  mesh/ox2_bc=polar \
  mesh/nx3=32 \
  mesh/x3min=0.0 \
  mesh/x3max=6.283185307179586 \
  mesh/ix3_bc=periodic \
  mesh/ox3_bc=periodic

vis/python/plot_spherical.py \
  example/Blast.out1.00040.athdf \
  rho \
  example/spherical.png \
  --colormap RdBu_r \
  --vmin 0.1 \
  --vmax 10.0 \
  --logc