4.1 Overview

After compiling ASPECT as described above, you should have an executable file in the main directory. It can be called as follows:

or, if you want to run the program in parallel, using something like

to run with 32 processors. In either case, the argument denotes the (path and) name of a file that contains input parameters.⁷ When you download ASPECT, there are a number of sample input files in the cookbooks directory, corresponding to the examples discussed in Section 5, and input files for some of the benchmarks discussed in Section 5.4 are located in the benchmarks directory. A full description of all parameters one can specify in these files is given in Section A.

Running ASPECT with an input file will produce output that will look something like this (numbers will all be different, of course):

The output starts with a header that lists the used ASPECT, deal.II, Trilinos and p4est versions as well as the mode you compiled ASPECT in (see 4.3), and the number of parallel processes used⁸. With this information we strive to make ASPECT models as reproducible as possible.

The following output depends on the model, and in this case was produced by a parameter file that, among other settings, contained the following values (we will discuss many such input files in Section 5:

In other words, these run-time parameters specify that we should start with a geometry that represents a spherical shell (see Sections ?? and ?? for details). The coarsest mesh is refined 4 times globally, i.e., every cell is refined into four children (or eight, in 3d) 4 times. This yields the initial number of 1,536 cells on a mesh hierarchy that is 5 levels deep. We then solve the problem there once and, based on the number of adaptive refinement steps at the initial time set in the parameter file, use the solution so computed to refine the mesh once adaptively (yielding 2,379 cells on 6 levels) on which we start the computation over at time $t=0$.

Within each time step, the output indicates the number of iterations performed by the linear solvers, and we generate a number of lines of output by the postprocessors that were selected (see Section ??). Here, we have selected to run all postprocessors that are currently implemented in ASPECT which includes the ones that evaluate properties of the velocity, temperature, and heat flux as well as a postprocessor that generates graphical output for visualization.

While the screen output is useful to monitor the progress of a simulation, its lack of a structured output makes it not useful for later plotting things like the evolution of heat flux through the core-mantle boundary. To this end, ASPECT creates additional files in the output directory selected in the input parameter file (here, the output/ directory relative to the directory in which ASPECT runs). In a simple case, this will look as follows:

The purpose of these files is as follows:

• A listing of all run-time parameters: The output/parameters.prm file contains a complete listing of all run-time parameters. In particular, this includes the ones that have been specified in the input parameter file passed on the command line, but it also includes those parameters for which defaults have been used. It is often useful to save this file together with simulation data to allow for the easy reproduction of computations later on.

  There is a second file, output/parameters.prm, that lists these parameters in LATEX format.

• Graphical output files: One of the postprocessors chosen in the parameter file used for this computation is the one that generates output files that represent the solution at certain time steps. The screen output indicates that it has run at time step 0, producing output files that start with output/solution/solution-00000. Depending on the settings in the parameter file, output will be generated every so many seconds or years of simulation time, and subsequent output files will then start with output/solution/solution-00001, all placed in the output/solution subdirectory. This is because there are often a lot of output files: For many time steps, times the number of processors, so they are placed in a subdirectory so as not to make it more difficult than necessary to find the other files.

  At the current time, the default is that ASPECT generates this output in VTK format⁹ as that is widely used by a number of excellent visualization packages and also supports parallel visualization.¹⁰ If the program has been run with multiple MPI processes, then the list of output files will be output/solution/solution-XXXXX.YYYY denoting that this the XXXXXth time we create output files and that the file was generated by the YYYYth processor.

  VTK files can be visualized by many of the large visualization packages. In particular, the Visit and ParaView programs, both widely used, can read the files so created. However, while VTK has become a de-facto standard for data visualization in scientific computing, there doesn’t appear to be an agreed upon way to describe which files jointly make up for the simulation data of a single time step (i.e., all files with the same XXXXX but different YYYY in the example above). Visit and Paraview both have their method of doing things, through .pvtu and .visit files. To make it easy for you to view data, ASPECT simply creates both kinds of files in each time step in which graphical data is produced, and these are then also placed into the subdirectories as output/solution/solution-XXXXX.pvtu and output/solution/solution-XXXXX.visit.

  The final two files of this kind, output/solution.pvd and output/solution.visit, are files that describes to Paraview and Visit, respectively, which output/solution/solution-XXXXX.pvtu and output/solution/solution-XXXXX.YYYY.vtu jointly form a complete simulation. In the former case, the file lists the .pvtu files of all timesteps together with the simulation time to which they correspond. In the latter case, it actually lists all .vtu that belong to one simulation, grouped by the timestep they correspond to. To visualize an entire simulation, not just a single time step, it is therefore simplest to just load one of these files, depending on whether you use Paraview or Visit.¹¹ Because loading an entire simulation is the most common use case, these are the two files you will most often load, and so they are placed in the output directory, not the subdirectory where the actual .vtu data files are located.

  For more on visualization, see also Section 4.4.

• A statistics file: The output/statistics file contains statistics collected during each time step, both from within the simulator (e.g., the current time for a time step, the time step length, etc.) as well as from the postprocessors that run at the end of each time step. The file is essentially a table that allows for the simple production of time trends. In the example above, and at the time when we are writing this section, it looks like this:
  # 1: Time step number 
  # 2: Time (years) 
  # 3: Iterations for Stokes solver 
  # 4: Time step size (year) 
  # 5: Iterations for temperature solver 
  # 6: Visualization file name 
  # 7: RMS velocity (m/year) 
  # 8: Max. velocity (m/year) 
  # 9: Minimal temperature (K) 
  # 10: Average temperature (K) 
  # 11: Maximal temperature (K) 
  # 12: Average nondimensional temperature (K) 
  # 13: Core-mantle heat flux (W) 
  # 14: Surface heat flux (W) 
  0 0.000e+00 33 2.9543e+07 8                             "" 0.0000 0.0000 0.0000 0.0000    ... 
  0 0.000e+00 34 1.9914e+07 8 output/solution/solution-00000 0.0946 0.1829 300.00 3007.2519 ... 
  1 1.991e+07 33 1.9914e+07 8 output/solution/solution-00001 0.1040 0.2172 300.00 3007.8406 ... 
  2 3.982e+07 33 1.9914e+07 8                             "" 0.1114 0.2306 300.00 3008.3939 ... 
    

  The actual columns you have in your statistics file may differ from the ones above, but the format of this file should be obvious. Since the hash mark is a comment marker in many programs (for example, gnuplot ignores lines in text files that start with a hash mark), it is simple to plot these columns as time series. Alternatively, the data can be imported into a spreadsheet and plotted there.

  Note: As noted in Section 2.3, ASPECT can be thought of as using the meter-kilogram-second (MKS, or SI) system. Unless otherwise noted, the quantities in the output file are therefore also in MKS units.

  A simple way to plot the contents of this file is shown in Section 4.4.2.

• Output files generated by other postprocessors: Similar to the output/statistics file, several of the existing postprocessors one can select from the parameter file generate their data in their own files in the output directory. For example, ASPECT’s “depth average” postprocessor will write depth-average statistics into the file output/depth_average.gnuplot. Input parameters chosen in the input file control how often this file is updated by the postprocessor, as well as what graphical file format to use (if anything other than gnuplot is desired).

  By default, the data is written in text format that can be easily visualized, see for example Figure 2. The plot shows how an initially linear temperature profile forms upper and lower boundary layers.

  ---

  
  

  Figure 2: Example output for depth average statistics. On the left axis are 13 time steps, on the right is the depth (from the top at 0 to the bottom of the mantle on the far right), and the upwards pointing axis is the average temperature. This plot is generated by gnuplot, but the depth averages can be written in many other output formats as well, if preferred (see Section ??).

  ---

There are other parts of ASPECT that may also create files in the output directory. For example, if your simulation includes advecting along particles (see Section 2.15), then visualization information for these particles will also appear in this file. See Section 5.2.5 for an example of how this looks like.