Line data    Source code

       1           0 : \cond NEVER
       2             : Distributed under the MIT License.
       3             : See LICENSE.txt for details.
       4             : \endcond
       5             : # Running and Visualizing {#tutorial_visualization}
       6             : 
       7             : \tableofcontents
       8             : 
       9             : ### Building an Executable from an Existing Source File
      10             : 
      11             : SpECTRE source files for evolution executables are located in
      12             : `src/Evolution/Executables`. Executables can be compiled by running the command
      13             : `make EXECUTABLE_NAME` where `EXECUTABLE_NAME` is the name of the executable
      14             : as defined in the `CMakeLists.txt` file located in the same directory as the
      15             : source file. For example, to compile the executable that evolves a scalar wave
      16             : using a three-dimensional domain, navigate to `$SPECTRE_HOME/build/`, then
      17             : one runs the command: `make EvolveScalarWave3D`, which then results
      18             : in an executable of the same name in the `bin` directory of the user's
      19             : build directory.
      20             : 
      21             : ### Running an Evolution Executable
      22             : 
      23             : Each SpECTRE executable reads a user-provided YAML file that specifies the
      24             : runtime settings of the evolution. This is where options such as the Domain,
      25             : AnalyticSolution, TimeStepper, etc are supplied. Example input files are kept
      26             : in `tests/InputFiles`, and are written to provide a functional base input file
      27             : which the user can then modify as desired. Copy the executable and YAML file
      28             : to a directory of your choice. The YAML file is then passed as an argument to
      29             : the executable using the flag `--input-file`. For example, for a scalar wave
      30             : evolution, run the command:
      31             : 
      32             : ```
      33             : ./EvolveScalarWave3D --input-file PlaneWave3D.yaml
      34             : ```
      35             : 
      36             : You can also use the \ref tutorial_cli "command-line interface (CLI)" to run
      37             : executables:
      38             : 
      39             : ```
      40             : ./spectre run PlaneWave3D.yaml
      41             : ```
      42             : 
      43             : By default, the example input files do not produce any output. This can be
      44             : changed by modifying the options passed to `EventsAndTriggers` or
      45             : `EventsAndDenseTriggers`:
      46             : 
      47             : \snippet PlaneWave1DObserveExample.yaml observe_event_trigger
      48             : 
      49             : This will observe the norms of the errors in the system at times
      50             : \f$0.0\f$ and \f$1.0\f$ and the field data at the start of every 50th
      51             : slab.  A successful observation will result in the creation of H5
      52             : files whose names can be specified in the YAML file under the options
      53             : `VolumeFileName` and `ReductionFileName`. One volume data file will be
      54             : produced from each Charm++ node that is used to run the
      55             : executable. Each volume data file will have its corresponding node
      56             : number appended to its file name.  Visualization of the volume data
      57             : will be described in the next sections.
      58             : 
      59             : ### Plotting data with Python
      60             : 
      61             : See the tutorial on \ref tutorial_vis_python to learn how to load and visualize
      62             : volume data in Python.
      63             : 
      64             : ### 3D Volume Data In ParaView
      65             : 
      66             : A SpECTRE executable with observers produces volume and/or reduced data h5
      67             : files. An XDMF file must be created from the volume data in order to do
      68             : visualization using ParaView. To this end we provide the tool
      69             : `generate-xdmf` in the Python command-line interface. Run it in your build
      70             : directory as `spectre generate-xdmf`. It
      71             : takes two required arguments which are passed to `--subfile-name`, and
      72             : `--output`. The
      73             : argument passed to `--subfile-name` is the name of the subfile inside the H5
      74             : volume data file where data is stored. In the above example, `--subfile-name`
      75             : would be `VolumePsiPiPhiEvery50Slabs`. The argument passed to `--output` is the
      76             : desired .xmf file name, also without filename extension. Use `--help` to see a
      77             : further description of possible arguments.
      78             : 
      79             : Open the .xmf file in ParaView and select the `Xdmf Reader`, *not* the version 3
      80             : readers. On the left hand side of the main ParaView window is a section named
      81             : `Properties`, here you must click the highlighted `Apply` button. ParaView will
      82             : now render your volume data. If you only wish to visualize a few datasets out of
      83             : a large set, we recommended unchecking the boxes for the datasets you wish to
      84             : ignore under `Point Arrays` before clicking `Apply`. Also, don't forget to check
      85             : which dataset is being used for the color under `Coloring`. The default won't
      86             : necessarily be the dataset you want.
      87             : 
      88             : \note ParaView cannot understand `.xmf` files when subfile names have colons in
      89             : them. Please avoid subfile names like `My::Subfile:Name`.
      90             : 
      91             : ### Helpful ParaView Filters
      92             : 
      93             : Here we describe the usage of filters we've found to better visualize our data.
      94             : Feel free to contribute to this section!
      95             : 
      96             : #### Removing Mesh Imprinting
      97             : You may notice what appears to be mesh imprinting on the data. The imprinting
      98             : effect can be removed by applying the `Tetrahedralize` filter. To apply the
      99             : filter select the `Filters` menu item, then `Alphabetical` and finally
     100             : `Tetrahedralize`.
     101             : 
     102             : #### Creating Derived Volume Data
     103             : New volume data can be created from the existing volume data using the
     104             : `Calculator` filter. In the `Calculator`'s text box, input a numerical
     105             : expression in terms of existing datasets evaluating to the desired
     106             : quantity. For example, a vector-valued velocity dataset can be created
     107             : from three scalar velocity component datasets using the expression
     108             : `velocity_x * iHat + velocity_y * jHat + velocity_z * kHat` and hitting
     109             : the `Apply` button. By default, this will create a new dataset `Result`.
     110             : The name of the new dataset can be changed by changing the name provided
     111             : to `Result Array Name` above the `Calculator` text box.
     112             : 
     113             : #### Visualizing Vector Fields Derived From Scalar Fields
     114             : Use the `Calculator` filter described above in "Creating Derived Volume Data"
     115             : to create a new vector-valued dataset. Once this is created, use the `Glyph`
     116             : filter and set the `Active Attributes` to the vector you wish to visualize.
     117             : Make sure that `Scale Mode` is set to `vector`.
     118             : 
     119             : ### Visualizing and Extracting Dat Files
     120             : 
     121             : Global quantities such as error norms are stored in `h5::Dat` subfiles in the
     122             : reduction/global HDF5 file. The command-line endpoint `spectre plot dat`
     123             : can be used to plot quantities, and `spectre extract-dat` can be used
     124             : to extract them into space-separated text files. These text
     125             : files can then be read with other plotting programs or viewed in an editor.
     126             : 
     127             : ### Reproducibility of Results
     128             : 
     129             : Being able to reproduce the results of simulations is important for scientific
     130             : integrity and accuracy. To this end, SpECTRE encodes the source tree,
     131             : environment variables, and a record of build information (e.g., the third-party
     132             : library versions) into the executables. From most executables these can be
     133             : retrieved using the flags `--dump-source-as filename_without_extension`,
     134             : `--dump-paths`, `--dump-build-info`, and `--dump-environment`. The flag
     135             : `--dump-only` will cause the program to exit after the information has been
     136             : dumped. You can use the `--help` flag to get more details on what flags are
     137             : available. The flag `--dump-paths` will print to screen the environment
     138             : variables `PATH`, `CPATH`, `LD_LIBRARY_PATH`, `LIBRARY_PATH`, and
     139             : `CMAKE_PREFIX_PATH` at link time. The flag `--dump-build-info` will print to
     140             : screen the contents of the `BuildInfo.txt` file generated by CMake. The flag
     141             : `--dump-environment` will print to screen the output of `printenv` at link
     142             : time. Finally, the flag `--dump-source-as filename_without_extension` will dump
     143             : the archive `filename_without_extension.tar.gz`, which contains the entire
     144             : source tree at link time. The combined above information should be enough to
     145             : reproduce simulations results to roundoff error as long as the third party
     146             : libraries used to build the executable have not changed on the system the
     147             : simulation was run on.
     148             : 
     149             : Often only data from the simulation is retained, not the entire executable. In
     150             : order to make simulations reproducible from only the HDF5 output, any HDF5 files
     151             : written with SpECTRE's HDF5 wrappers contain the info about the run, output of
     152             : `printenv` at link time, the contents of `BuildInfo.txt`, and an archive
     153             : of the source tree. These are inside the `header.hdr` group with names
     154             : `SimulationInfo`, `EnvironmentVariablesAtCompilation`, `BuildInfo`, and
     155             : `src.tar.gz`. The source archive can be extracted by running the command
     156             : ```
     157             : h5dump -d /src.tar.gz -b LE -o src.tar.gz /path/to/hdf5/file.h5
     158             : ```
     159             : You will need to make sure the argument to `-b` is the same endianness as your
     160             : computer. In the above example little endian is used.