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 section. 58 : 59 : ### 3D Data Volume Data In ParaView 60 : 61 : A SpECTRE executable with observers produces volume and/or reduced data h5 62 : files. An XDMF file must be created from the volume data in order to do 63 : visualization using ParaView. To this end we provide the tool 64 : `generate-xdmf` in the Python command-line interface. Run it in your build 65 : directory as `spectre generate-xdmf`. It 66 : takes two required arguments which are passed to `--subfile-name`, and 67 : `--output`. The 68 : argument passed to `--subfile-name` is the name of the subfile inside the H5 69 : volume data file where data is stored. In the above example, `--subfile-name` 70 : would be `VolumePsiPiPhiEvery50Slabs`. The argument passed to `--output` is the 71 : desired .xmf file name, also without filename extension. Use `--help` to see a 72 : further description of possible arguments. 73 : 74 : Open the .xmf file in ParaView and select the `Xdmf Reader`, *not* the version 3 75 : readers. On the left hand side of the main ParaView window is a section named 76 : `Properties`, here you must click the highlighted `Apply` button. ParaView will 77 : now render your volume data. If you only wish to visualize a few datasets out of 78 : a large set, we recommended unchecking the boxes for the datasets you wish to 79 : ignore under `Point Arrays` before clicking `Apply`. Also, don't forget to check 80 : which dataset is being used for the color under `Coloring`. The default won't 81 : necessarily be the dataset you want. 82 : 83 : \note ParaView cannot understand `.xmf` files when subfile names have colons in 84 : them. Please avoid subfile names like `My::Subfile:Name`. 85 : 86 : ### Helpful ParaView Filters 87 : 88 : Here we describe the usage of filters we've found to better visualize our data. 89 : Feel free to contribute to this section! 90 : 91 : #### Removing Mesh Imprinting 92 : You may notice what appears to be mesh imprinting on the data. The imprinting 93 : effect can be removed by applying the `Tetrahedralize` filter. To apply the 94 : filter select the `Filters` menu item, then `Alphabetical` and finally 95 : `Tetrahedralize`. 96 : 97 : #### Creating Derived Volume Data 98 : New volume data can be created from the existing volume data using the 99 : `Calculator` filter. In the `Calculator`'s text box, input a numerical 100 : expression in terms of existing datasets evaluating to the desired 101 : quantity. For example, a vector-valued velocity dataset can be created 102 : from three scalar velocity component datasets using the expression 103 : `velocity_x * iHat + velocity_y * jHat + velocity_z * kHat` and hitting 104 : the `Apply` button. By default, this will create a new dataset `Result`. 105 : The name of the new dataset can be changed by changing the name provided 106 : to `Result Array Name` above the `Calculator` text box. 107 : 108 : #### Visualizing Vector Fields Derived From Scalar Fields 109 : Use the `Calculator` filter described above in "Creating Derived Volume Data" 110 : to create a new vector-valued dataset. Once this is created, use the `Glyph` 111 : filter and set the `Active Attributes` to the vector you wish to visualize. 112 : Make sure that `Scale Mode` is set to `vector`. 113 : 114 : ### Visualizing and Extracting Dat Files 115 : 116 : Global quantities such as error norms are stored in `h5::Dat` subfiles in the 117 : reduction/global HDF5 file. The command-line endpoint `spectre plot dat` 118 : can be used to plot quantities, and `spectre extract-dat` can be used 119 : to extract them into space-separated text files. These text 120 : files can then be read with other plotting programs or viewed in an editor. 121 : 122 : ### Reproducibility of Results 123 : 124 : Being able to reproduce the results of simulations is important for scientific 125 : integrity and accuracy. To this end, SpECTRE encodes the source tree, 126 : environment variables, and a record of build information (e.g., the third-party 127 : library versions) into the executables. From most executables these can be 128 : retrieved using the flags `--dump-source-as filename_without_extension`, 129 : `--dump-paths`, `--dump-build-info`, and `--dump-environment`. The flag 130 : `--dump-only` will cause the program to exit after the information has been 131 : dumped. You can use the `--help` flag to get more details on what flags are 132 : available. The flag `--dump-paths` will print to screen the environment 133 : variables `PATH`, `CPATH`, `LD_LIBRARY_PATH`, `LIBRARY_PATH`, and 134 : `CMAKE_PREFIX_PATH` at link time. The flag `--dump-build-info` will print to 135 : screen the contents of the `BuildInfo.txt` file generated by CMake. The flag 136 : `--dump-environment` will print to screen the output of `printenv` at link 137 : time. Finally, the flag `--dump-source-as filename_without_extension` will dump 138 : the archive `filename_without_extension.tar.gz`, which contains the entire 139 : source tree at link time. The combined above information should be enough to 140 : reproduce simulations results to roundoff error as long as the third party 141 : libraries used to build the executable have not changed on the system the 142 : simulation was run on. 143 : 144 : Often only data from the simulation is retained, not the entire executable. In 145 : order to make simulations reproducible from only the HDF5 output, any HDF5 files 146 : written with SpECTRE's HDF5 wrappers contain the info about the run, output of 147 : `printenv` at link time, the contents of `BuildInfo.txt`, and an archive 148 : of the source tree. These are inside the `header.hdr` group with names 149 : `SimulationInfo`, `EnvironmentVariablesAtCompilation`, `BuildInfo`, and 150 : `src.tar.gz`. The source archive can be extracted by running the command 151 : ``` 152 : h5dump -d /src.tar.gz -b LE -o src.tar.gz /path/to/hdf5/file.h5 153 : ``` 154 : You will need to make sure the argument to `-b` is the same endianness as your 155 : computer. In the above example little endian is used.