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             : ### Building an Executable from an Existing Source File
       8             : 
       9             : SpECTRE source files for evolution executables are located in
      10             : `src/Evolution/Executables`. Executables can be compiled by running the command
      11             : `make EXECUTABLE_NAME` where `EXECUTABLE_NAME` is the name of the executable
      12             : as defined in the `CMakeLists.txt` file located in the same directory as the
      13             : source file. For example, to compile the executable that evolves a scalar wave
      14             : using a three-dimensional domain, one runs the command:
      15             : `make EvolvePlaneWave3D`, which then results in an executable of the same name
      16             : in the `bin` directory of the user's build directory.
      17             : 
      18             : ### Running an Evolution Executable
      19             : 
      20             : Each SpECTRE executable reads a user-provided YAML file that specifies the
      21             : runtime settings of the evolution. This is where options such as the Domain,
      22             : AnalyticSolution, TimeStepper, etc are supplied. Example input files are kept
      23             : in `tests/InputFiles`, and are written to provide a functional base input file
      24             : which the user can then modify as desired. Copy the executable and YAML file
      25             : to a directory of your choice. The YAML file is then passed as an argument to
      26             : the executable using the flag `--input-file`. For example, for a scalar wave
      27             : evolution, run the command:
      28             : `./EvolvePlaneWave3D --input-file Input3DPeriodic.yaml`.
      29             : By default, the example input files do not produce any output. This can be
      30             : changed by modifying the options passed to `EventsAndTriggers`:
      31             : 
      32             : \snippet PlaneWave1DObserveExample.yaml observe_event_trigger
      33             : 
      34             : This will observe the norms of the errors in the system every three
      35             : slabs starting with slab five and the volume data of Psi at the start
      36             : of slabs 0 and 100. Be sure to keep the Completion event, as without
      37             : it the executable will run indefinitely. In this case, it will terminate
      38             : after 100 slabs. A successful observation will result in the
      39             : creation of H5 files whose names can be specified in the YAML file
      40             : under the options `VolumeFileName` and `ReductionFileName`. One volume
      41             : data file will be produced from each Charm++ node that is used to run
      42             : the executable. Each volume data file will have its corresponding node
      43             : number appended to its file name.  Visualization of the volume data
      44             : will be described in the next section.
      45             : 
      46             : ### 3D %Data Volume %Data In ParaView
      47             : 
      48             : A SpECTRE executable with observers produces volume and/or reduced data h5
      49             : files. An XDMF file must be created from the volume data in order to do
      50             : visualization using ParaView. To this end we provide the python executable
      51             : `GenerateXdmf.py` in the `Visualization/Python` directory. `GenerateXdmf.py`
      52             : takes two arguments which are passed to `--file-prefix` and `--output`. The
      53             : argument passed to `--file-prefix` is the name of the H5 volume data, leaving
      54             : out the node number and extension. The argument passed to `--output` is the
      55             : desired .xmf file name, also without filename extension. Use `--help` to see a
      56             : further description of possible arguments.
      57             : 
      58             : Open the .xmf file in ParaView and select the `Xdmf Reader`, *not* the version 3
      59             : readers. On the left hand side of the main ParaView window is a section named
      60             : `Properties`, here you must click the highlighted `Apply` button. ParaView will
      61             : now render your volume data. If you only wish to visualize a few datasets out of
      62             : a large set, we recommended unchecking the boxes for the datasets you wish to
      63             : ignore under `Point Arrays` before clicking `Apply`.
      64             : 
      65             : ### Helpful ParaView Filters
      66             : 
      67             : Here we describe the usage of filters we've found to better visualize our data.
      68             : Feel free to contribute to this section!
      69             : 
      70             : #### Removing Mesh Imprinting
      71             : You may notice what appears to be mesh imprinting on the data. The imprinting
      72             : effect can be removed by applying the `Tetrahedralize` filter. To apply the
      73             : filter select the `Filters` menu item, then `Alphabetical` and finally
      74             : `Tetrahedralize`.
      75             : 
      76             : #### Creating Derived Volume Data
      77             : New volume data can be created from the existing volume data using the
      78             : `Calculator` filter. In the `Calculator`'s text box, input a numerical
      79             : expression in terms of existing datasets evaluating to the desired
      80             : quantity. For example, a vector-valued velocity dataset can be created
      81             : from three scalar velocity component datasets using the expression
      82             : `velocity_x * iHat + velocity_y * jHat + velocity_z * kHat` and hitting
      83             : the `Apply` button. By default, this will create a new dataset `Result`.
      84             : The name of the new dataset can be changed by changing the name provided
      85             : to `Result Array Name` above the `Calculator` text box.
      86             : 
      87             : #### Visualizing Vector Fields Derived From Scalar Fields
      88             : Use the `Calculator` filter described above in "Creating Derived Volume Data"
      89             : to create a new vector-valued dataset. Once this is created, use the `Glyph`
      90             : filter and set the `Active Attributes` to the vector you wish to visualize.
      91             : Make sure that `Scale Mode` is set to `vector`.
      92             : 
      93             : ### Reproducibility of Results
      94             : 
      95             : Being able to reproduce the results of simulations is important for scientific
      96             : integrity and accuracy. To this end, SpECTRE encodes the source tree,
      97             : environment variables, and a record of the third party library versions into the
      98             : executables. From most executables these can be retrieved using the flags
      99             : `--dump-source-as filename_without_extension`, `--dump-paths`,
     100             : `--dump-library-version`, and `--dump-environment`. The flag `--dump-only` will
     101             : cause the program to exit after the information has been dumped. You can use the
     102             : `--help` flag to get more details on what flags are available. The flag
     103             : `--dump-paths` will print to screen the environment variables `PATH`, `CPATH`,
     104             : `LD_LIBRARY_PATH`, `LIBRARY_PATH`, and `CMAKE_PREFIX_PATH` at link time. The
     105             : flag `--dump-library-versions` will print to screen the contents of the
     106             : `LibraryVersions.txt` file generated by CMake. The flag `--dump-environment`
     107             : will print to screen the output of `printenv` at link time. Finally, the flag
     108             : `--dump-source-as filename_without_extension` will dump the archive
     109             : `filename_without_extension.tar.gz`, which contains the entire source tree at
     110             : link time. The combined above information should be enough to reproduce
     111             : simulations results to roundoff error as long as the third party libraries
     112             : used to build the executable have not changed on the system the simulation was
     113             : run on.
     114             : 
     115             : Often only data from the simulation is retained, not the entire executable. In
     116             : order to make simulations reproducible from only the HDF5 output, any HDF5 files
     117             : written with SpECTRE's HDF5 wrappers contain the info about the run, output of
     118             : `printenv` at link time, the contents of `LibraryVersions.txt`, and an archive
     119             : of the source tree. These are inside the `header.hdr` group with names
     120             : `SimulationInfo`, `EnvironmentVariablesAtCompilation`, `LibraryVersions`, and
     121             : `src.tar.gz`. The source archive can be extracted by running the command
     122             : ```
     123             : h5dump -d /src.tar.gz -b LE -o src.tar.gz /path/to/hdf5/file.h5
     124             : ```
     125             : You will need to make sure the argument to `-b` is the same endianness as your
     126             : computer. In the above example little endian is used.