(sec:run-aspect:overview)= # Overview After compiling ASPECT as described above, you should have an executable file in the build directory. It can be called in the build directory as follows: ./aspect parameter-file.prm or, if you want to run the program in parallel, using something like mpirun -np 4 ./aspect parameter-file.prm to run with 4 processors. In either case, the argument denotes the (path and) name of a file that contains input parameters.[^footnote1] When you download ASPECT, there are a number of sample input files in the [cookbooks](https://github.com/geodynamics/aspect/tree/main/cookbooks) directory, corresponding to the examples discussed in {ref}`cha:cookbooks`, and input files for some of the benchmarks discussed in {ref}`cha:benchmarks` are located in the [benchmarks](https://github.com/geodynamics/aspect/tree/main/benchmarks) directory. A full description of all parameters one can specify in these files is given in {ref}`parameters`. Running ASPECT with an input file[^footnote2] will produce output that will look something like this (numbers will all be different, of course): ``` ----------------------------------------------------------------------------- -- This is ASPECT, the Advanced Solver for Problems in Earth's ConvecTion. -- . version 2.0.0-pre (include_dealii_version, c20eba0) -- . using deal.II 9.0.0-pre (master, 952baa0) -- . using Trilinos 12.10.1 -- . using p4est 2.0.0 -- . running in DEBUG mode -- . running with 1 MPI process ----------------------------------------------------------------------------- Number of active cells: 1,536 (on 5 levels) Number of degrees of freedom: 20,756 (12,738+1,649+6,369) *** Timestep 0: t=0 years Rebuilding Stokes preconditioner... Solving Stokes system... 30+3 iterations. Solving temperature system... 8 iterations. Number of active cells: 2,379 (on 6 levels) Number of degrees of freedom: 33,859 (20,786+2,680+10,393) *** Timestep 0: t=0 years Rebuilding Stokes preconditioner... Solving Stokes system... 30+4 iterations. Solving temperature system... 8 iterations. Postprocessing: Writing graphical output: output/solution/solution-00000 RMS, max velocity: 0.0946 cm/year, 0.183 cm/year Temperature min/avg/max: 300 K, 3007 K, 6300 K Inner/outer heat fluxes: 1.076e+05 W, 1.967e+05 W *** Timestep 1: t=1.99135e+07 years Solving Stokes system... 30+3 iterations. Solving temperature system... 8 iterations. Postprocessing: Writing graphical output: output/solution/solution-00001 RMS, max velocity: 0.104 cm/year, 0.217 cm/year Temperature min/avg/max: 300 K, 3008 K, 6300 K Inner/outer heat fluxes: 1.079e+05 W, 1.988e+05 W *** Timestep 2: t=3.98271e+07 years Solving Stokes system... 30+3 iterations. Solving temperature system... 8 iterations. Postprocessing: RMS, max velocity: 0.111 cm/year, 0.231 cm/year Temperature min/avg/max: 300 K, 3008 K, 6300 K Inner/outer heat fluxes: 1.083e+05 W, 2.01e+05 W *** Timestep 3: t=5.97406e+07 years ... ``` 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 {ref}`sec:run-aspect:debug-mode`), and the number of parallel processes used.[^footnote3] 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 {ref}`cha:cookbooks`: ```{literalinclude} ../../../manual/cookbooks/overview/doc/simple.prm ``` In other words, these run-time parameters specify that we should start with a geometry that represents a spherical shell (see {ref}`parameters:Geometry_20model` and {ref}`parameters:Geometry_20model/Spherical_20shell` 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 {ref}`parameters:Postprocess`). 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: ``` ksh aspect> ls -l output/ total 932 -rw-rw-r-- 1 bangerth bangerth 11134 Dec 11 10:08 depth_average.gnuplot -rw-rw-r-- 1 bangerth bangerth 11294 Dec 11 10:08 log.txt -rw-rw-r-- 1 bangerth bangerth 42 Dec 11 10:07 original.prm -rw-rw-r-- 1 bangerth bangerth 326074 Dec 11 10:07 parameters.prm -rw-rw-r-- 1 bangerth bangerth 577138 Dec 11 10:07 parameters.tex drwxr-xr-x 2 bangerth bangerth 4096 Dec 11 10:08 solution -rw-rw-r-- 1 bangerth bangerth 484 Dec 11 10:08 solution.pvd -rw-rw-r-- 1 bangerth bangerth 451 Dec 11 10:08 solution.visit -rw-rw-r-- 1 bangerth bangerth 8267 Dec 11 10:08 statistics ``` The purpose of these files is as follows: - *Screen output:* The file `output/log.txt` contains a copy of the output that is printed to the terminal when you run ASPECT. - *A listing of all run-time parameters:* The file `output/original.prm` is a copy of the parameter file that was used in this computation. It is often useful to save this file together with simulation data to allow for the easy reproduction of computations later on. 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. This file can also be used to explore all available parameters and possible options as it contains the documentation of all parameters. Finally, there is `output/parameters.tex`, that lists the parameters like `output/parameters.prm` in LaTeX format, and `output/parameters.json` in JSON format. While `output/parameters.prm` contains all parameters (with their default values if they were not specified), all formatting and comments are lost. As `output/original.prm` is identical to the prm you started ASPECT with, it preserves comments and formatting while not outputting the default values (or documentation). - *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[^footnote4] as that is widely used by a number of excellent visualization packages and also supports parallel visualization.[^footnote5] 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 `XXXXX`th time we create output files and that the file was generated by the `YYYY`th processor. VTK files can be visualized by many of the large visualization packages. In particular, the [VisIt](https://visit-dav.github.io/visit-website/) and [ParaView](https://www.paraview.org/) 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.[^footnote6] 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 {ref}`sec:run-aspect:visualizing-results`. - *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: ``` ksh # 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 {ref}`sec:methods:dimensionalize`, 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 {ref}`sec:run-aspect:visualize:stat-data`. - *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 {numref}`fig:depthaverage`. The plot shows how an initially linear temperature profile forms upper and lower boundary layers. ```{figure-md} fig:depthaverage 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 {ref}`parameters:Postprocess/Depth_20average`). 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 {ref}`parameters:Postprocess/Depth_20average`). ``` 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 {ref}`sec:methods:particles`), then visualization information for these particles will also appear in this file. See {ref}`sec:cookbooks:using-particles` for an example of how this looks like. [^footnote1]: As a special case, if you call ASPECT with an argument that consists of two dashes, “`--`”, then the arguments will be read from the standard input stream of the program. In other words, you could type the input parameters into your shell window in this case (though that would be cumbersome, ASPECT would seem to hang until you finish typing all of your input into the window and then terminating the input stream by typing `Ctrl-D`). A more common case would be to use Unix pipes so that the default input of ASPECT is the output of another program, as in a command like `cat parameter-file.prm.in | mypreprocessor | ./aspect --`, where `mypreprocessor` would be a program of your choice that somehow transforms the file `parameter-file.prm.in` into a valid input file, for example to systematically vary one of the input parameters. If you want to run ASPECT in parallel, you can do something like `cat parameter-file.prm.in | mypreprocessor | mpirun -np 4 ./aspect --`. In cases like this, `mpirun` only forwards the output of `mypreprocessor` to the first of the four MPI processes, which then sends the text to all other processors. [^footnote2]: For example by running `./aspect ../cookbooks/convection-box/convection-box.prm` in your build directory. [^footnote3]: If you used the `git` version control system to download ASPECT and/or deal.II, as in this example, you will also get the current branch, and unique revision identifier for the current version. This is very important if you modify either software between releases, or you use a development version that is not an official release. Note that this revision can not track changes you made to the software that are not part of a git commit. [^footnote4]: The output is in fact in the VTU version of the VTK file format. This is the XML-based version of this file format in which contents are compressed. Given that typical file sizes for 3d simulation are substantial, the compression saves a significant amount of disk space. [^footnote5]: The underlying deal.II package actually supports output in around a dozen different formats, but most of them are not very useful for large-scale, 3d, parallel simulations. If you need a different format than VTK, you can select this using the run-time parameters discussed in {ref}`parameters:Postprocess/Visualization`. [^footnote6]: At the time of writing this, current versions of VisIt (starting with version 2.5.1) actually have a bug that prevents them from successfully reading the `output/solution.visit` or `output/solution/solution-XXXXX.visit` files – VisIt believes that each of these files corresponds to an individual time step, rather than that a whole group of files together form one time step. This bug is not fixed in VisIt 2.6.3, but may be fixed in later versions.