Making Plots

The visualization tools shipped with GRBoondi heavily rely on python and the massively parallel visit utility. You should definitely use python 3 for all these scripts. If you would like to create movies, you will also need ffmpeg.

The visit version used to build these tools is 3.3.3 and the python version was 3.9.1. It's therefore recommended you use at least this python version and visit version 3.3

The ffmpeg version used is 5.1.3, so any later version should work fine.

If you have any problems using versions later than these listed version, I ask you reach out to me to figure out what the issue is.

See Visualization for the specific usage of the plotting tools.

Installation

You can install all the python packages using pip.

python -m pip install "matplotlib>=3.9.1" "numpy>=2.0.0" "pandas>=2.2.2"

Besides python and its packages, the only extra program you will need to install is visit. You can grab the 3.3 version from here. Follow the visit installation guide to install visit in your home directory, unless your cluster already supports it.

Examples and Software Testing

GRBoondi contains a plethora of test routines to verify the correctness of the software. One of these routines includes test functions for the Post-Processing modules, located in GRBoondi/Tests/PostProcessing_test. Executing the command ./runtests executes the test suite and populates several output directories. For example, in the GRBoondi/Tests/PostProcessing_test/2d_plots directory, there are several 2D plots of the Lorentz norm of the Proca field, $A_{\mu}A^{\mu}$, around a Kerr black hole. This data was produced from the ProcaKerrBH example. The Asquared0000.png file is shown below:

A movie generated from the post-processing routines is also created from the series of images in the 2d_plots/ directory. The movie is shown below. As it is only a test program to verify the functionality of the post-processing routines, the movie is fairly short.

Asquared.mp4

The combined plot generated from the integral plotter (IntegralsPlot.py) is shown below:

An example of a 3D movie is shown here:

Asquared.mp4

All the parameter files used in creating these plots are located in GRBoondi/Test/PostProcessing_test/ with self-explanatory filenames.

Plot Parameters: A Complete Guide

A list of all the plot parameters and a brief explanation are listed here. They are broadly separated into two classes: The Integral parameters and the 2D/3D parameters. Since the 2D and 3D plot routines use visit, they share many of the same parameters.

Integral Plot Parameters

• Header
  • data_path
    • absolute or relative path to the directory containing the integrals data
  • data_filename
    • Name of the integrals output file, e.g. 'Integrals.dat'
  • verbosity
    • verbosity flag specifying how much information should be printed to the terminal. Possible values: 0 and 1
• VariableData
  • plot_variables
    • A space-separated list of all variables to be plotted. Must exist in the header lines of the integrals.dat file
  • one_plot
    • Flag specifying whether the plots of all the plot variables should be consolidated into a single image, e.g. the 'combined.png' image shown above.
  • linestyles
    • a space-separated list of various linestyles to use for each plot variable. Can either be empty or a list of characters whose length matches the length of plot_variables. The possible characters are elucidated here.
• PlotConfig
  • xscaling
    • The type of scaling for the x-axis. Can either be 'linear' or 'log'
  • yscaling
    • The type of scaling for the y-axis. Can either be 'linear' or 'log'
  • plotstyle
    • The overall style for the plot images. See this url for the possible choices.
  • set_xlim
    • Flag specifying whether the x-axis should be truncated or not.
  • xlim
    • A space-separated list of two values specifying the lower and upper bounds for the x-axis, respectively.
  • xlabel
    • The label to be printed below the x-axis
• Output
  • fileform
    • The file format to be used when saving the image, e.g. '.png', '.svg', etc.
  • dpi
    • The resolution of the images in dots-per-inch
  • output_plot_path
    • The absolute or relative path to the directory in which the plots will be saved. Directory must exist!

2D and 3D Plot Parameters

• Header

  • hdf5_path
    • absolute or relative path to the directory containing the hdf5 files
  • plot_header
    • prefix name of the files to be plotted, as named in the simulation parameter chk_prefix or plot_prefix, e.g. 'GeneralizedProcap_'
  • verbosity
    • verbosity of the messages to be printed to terminal
  • plot_type
    • type of plot to generate, e.g. '2d' or '3d'

• EngineConfig

  • host
    • host name of the computer/cluster, e.g. 'localhost'
  • use_parallel
    • flag specifying whether VisIt should parallelize the plotting algorithms
  • number_processes
    • if use_parallel=1, specifies the number of MPI processes to spawn
  • number_nodes
    • if use_parallel=1, specifies the number of compute nodes to allocate
  • partition
    • if use_parallel=1, specifies the scheduling queue to execute the parallel job on. Check your clusters available scheduling queues for available names
  • job_cmd
    • if use_parallel=1, specifies the scheduler command to use. For example, if 'slurm' is the sheduler, this could be srun, sbatch, mpirun, etc. Check the available commands for your specific job scheduler for options
  • time_limit
    • if use_parallel=1, sets the time limit for the parallel job
  • job_name
    • if use_parallel=1, sets the name of the job
  • additional_sub_args
    • if use_parallel=1, sends additional arguments to the command specified by job_cmd during execution. For example, using 'slurm' and 'srun', this could be '--cpus-per-task=1'.

• VariableData

  • plot_variables
    • a space-separated case-sensitive list of variable names to be plotted from the loaded hdf5 files.
  • set_plot_bounds_<i>
    • flag specifying the i-th variable listed in plot_variables should be clipped. For example, to bound the plot values of the 3rd plot variable, then set set_plot_bounds_3 = 1
  • plot_variables_range_<i>
    • a two-element space-separated list of the lower and upper bounds of the plot variable values, respectively. The bounds are only applied of set_plot_bounds_<i> = 1. For example, if set_plot_bounds_3 = 1, then this could be plot_variables_range_3 = 0.001 1.

• AnnotationConfig

  • userInfoFlag
    • flag that determines if the VisIt user information should be printed on the plot
  • databaseInfoFlag
    • flag that determines if the database information should be printed on the plot
  • legendInfoFlag
    • flag that determines if the legend should be printed on the plot
  • timeInfoFlag
    • flag that determines if the time information of the plot should be printed on the plot
  • backgroundColor
    • background color of the plot image
  • foregroundColor
    • foreground color of the plot image

• PlotConfig

  • plotscaling
    • determines the scaling of the plot variable values. Options: 'log' or 'linear'

• Output

  • fileform
    • format of the file the images are saved to, e.g. '.png', '.svg', '.jpg., etc.
  • quality
    • Effects the overall quality of the image on a scale from 0 to 100 if the file format is a jpeg.
  • make_movie
    • flag the determines if a movie should be made from the series of images using ffmpeg
  • movie_framerate
    • if make_movie=1, determines the framerate in seconds of the generated movie
  • output_plot_path
    • absolute or relative directory path the plot images should be saved in
  • output_movie_path
    • absolute or relative directory path movies should be saved in
  • overwrite_plots
    • flag that determines if previously generated plots should be overwritten

3D Specific Parameters

• AnnotationConfig

  • axes3Dvisible
    • flag that turns the axes on and off
  • bboxFlag
    • flag specifying whether the bounding box of the 3D plot should be visible
  • traidFlag
    • flag specifying whether a small triad axis should be visible in the bottom corner of the 3D plot to determine the directions of each axis

• PlotConfig

  • lightingFlag
    • flag that determines if lighting should be activated for the volume plots
  • legendFlag
    • flag the determines if the plot legend should be printed on the plot
  • opacityAttenuation
    • on a scale from 0.0 to 1.0, determines the overall multiplier for the opacity. A value of 0.0 means the plot values will be invisible and a value of 1.0 means the opacity follows exactly the opacity function. For example, if $f(x,y,z)$ is the opacity function that determines the visibility of the plot values, then the opacity attenuation multiplies this function as $\text{opacityAttenuation} * f(x,y,z)$.
  • opacityMode
    • determines the type of opacity function to employ. Options: freeform, gaussian, colortable. Gaussian applies a generic gaussian function as the opacity function. colortable uses the chosen colortable as the opacity function. freeform allows the user to specify a function, specified by a 100-element array. The array spans the entire range of the plot variable values. For example, the 0-th element of the array corresponds to the opacity value for the smallest value of the plot variable. Similarly, the last element of the array corresponds to the opacity value for the largest value of the plot variable. Each element of the array then corresponds linearly to each value of the plot variables between the smallest and largest values.
  • ramp_min
    • if opacityMode = freeform, specifies the minimum value of the normalized plot values where the opacity begins to linearily increase. See this section of the visualization section of the wiki
  • ramp_min
    • if opacityMode = freeform, specifies the maximum value of the normalized plot values where the opacity reaches a maximum.
  • useColorVarMin
    • flag specifying if the color scheme should set a minimum value of the plot values that is used for coloring
  • colorVarMin
    • minimum value of the plot variable that should be used for the color scheme
  • useColorVarMax
    • flag specifying if the color scheme should set a maximum value of the plot values that is used for coloring
  • ColorVarMax
    • maximum value of the plot variable that should be used for the color scheme
  • useOpacityVarMin
    • flag specifying if the opacity function should set a minimum value of the plot values that is used for opacity
  • opacityVarMin
    • minimum value of the plot variable that should be used for opacity
  • useOpacityVarMax
    • flag specifying if the opacity function should set a maximum value of the plot values that is used for opacity
  • opacityVarMax
    • maximum value of the plot variable that should be used for opacity
  • renderertype
    • type of 3d renderer to use. Options: default, raycasting, raycastingintegration, raycastinglivr, raycastingospray. See this doc for additional details
  • sampling
    • type of sampling to perform. Options: rasterization, kernelbased, trilinear
  • samplesPerRay
    • if raycasting is chosen as the renderertype, this specifies how many samples are taken per ray

• ViewConfig

  • viewNormal
    • space-separated list of 3 elements specifying the normal vector for the camera plane
  • focus space-separated list of 3 numbers specifying the 3D point where the camera should focus. Also functions as the origin of theviewNormal` vector
  • viewUp
    • space-separated list of 3 numbers specifying the vector defining the direction of 'up'
  • viewAngle
    • the angle in degrees of the camera lense, analogous to choosing a wide/narrow angle lense
  • parallelScale
    • distance along the view axis to the focus point
  • nearPlane
    • distance along the view axis from the camera that is in focus. Sets the 'near' region
  • farPlane
    • distance along the view axis from the camera that is in focus. Sets the 'far' region
  • imageReductionFactor
    • factor by which the size of the image is reduced
  • imagePan
    • space-separated list of two values that determined the offset of the camera in the plane specified by the viewNormal vector
  • imageZoom
    • absolute zoom factor. Analogous to zooming in the camera
  • perspective ` - flag specifying whether perspective should be activated. This tells visit to account for distance in generating the image. See this doc for more detail
  • eyeAngle
    • Sets the distance between the two 'eyes' of the camera observer. See this doc for more detail.
  • centerOfRotationSet
    • space-separated list of 3 values the determine the point around which the plot is rotated
  • centerOfRotation
    • space-separated list of 3 values the determine the point around which the plot is rotated
  • axis3DScaleFlag
    • flag specifying if the 3D axes should be scaled
  • axis3DScales
    • space-separated list of 3 values that determine the overall scaling of each axis.
  • shear
    • space-separated list of 3 values that determine the shear of the volume plot

2D Specific Parameters

• AnnotationConfig

  • axes2Dvisible
    • flag that turns the axes on and off

• PlotConfig

  • xscaling
    • scaling of the x-axis. Can be either 'log' or 'linear'
  • yscaling
    • scaling of the y-axis. Can be either 'log' or 'linear'
  • colortable
    • name of the color scheme to use for the plot values
  • invertcolortable
    • flag specifying whether the values of the color scheme should be inverted
  • centering
    • Indicates how the plot variables values are attached to the mesh on which the variable is defined. Options: zonal, natural, nodal. See this section of the VisIt docs for a more detailed explanation. nodal centering interpolates values between the nodes of the mesh, producing a more 'smooth' image, while 'zonal' produces a single color value for each cell, producing a more 'blocky' image.

• SliceConfig

  • origintype
    • the type of origin to use for the slicing plane. Options: point, intercept, percent, zone, node
  • axistype
    • the type of axis to use for the slicing plane's normal. Options: XAxis, YAxis, ZAxis, Arbitrary, ThetaPhi
  • origin
    • the origin point of the slicing plane
  • normal_vec
    • the normal vector of the slicing plane

• MeshConfig

  • activatemesh
    • flag specifying whether the mesh should be included in the plot image
  • meshopacity
    • opacity of the mesh, if activatemesh=1
  • meshcolor
    • RGBA color of the mesh lines

• ViewConfig

  • viewportcoords
    • space-separated list of 4 numbers specifying the area of the visualization window in which the 2D plot is shown, in the format of "x0 x1 y0 y1", where the lower-left part of the visualization window is (0,0) and the upper-right corner is (1,1). Hence, the viewportcoords specify the normalized coordinates in this box where the plot is shown
  • plot_u_min
    • the minimum x-coordinate
  • plot_u_max
    • the maximum x-coordinate
  • plot_v_min
    • the minimum y-coordinate
  • plot_v_max
    • the maximum y-coordinate