|
|
Before starting with this guide please make sure that ExaHyPE has been installed correctly by following the [installation guide](Intro).
|
|
|
|
|
|
# The acoustic wave equation
|
|
|
The acoustic wave equation describes the propagation of an wave through a material. This
|
|
|
equation assumes that all movements are only small perturbations over the background flow
|
|
|
field. They can be obtained by linearizing the more general Euler equations over this back-
|
|
|
ground field. This clearly cannot work for complex flows, e.g. for supersonic “booms”.
|
|
|
We describe our material by the parameters $K_0$ , which is the so-called bulk-modulus and by
|
|
|
the density $\rho_0$ . We solve here for velocity $v$ and pressure $p$ in one dimension
|
|
|
|
|
|
|
|
|
# Step 1: Setting up a specification file
|
|
|
The first step to writing an ExaHyPE application users is a specification file. The specification file is passed to the ExaHyPE toolkit, which creates glue code, empty application-specific classes and optionally application and architecture tailored core routines. In the next step these application specific classes will be filled with the PDE terms.
|
|
|
|
|
|
Let's start from a template for an ADER-DG specification file:
|
|
|
|
|
|
```
|
|
|
exahype-project ##Name
|
|
|
/*Set paths*/
|
|
|
peano-kernel-path const = ./Peano
|
|
|
exahype-path const = ./ExaHyPE
|
|
|
output-directory const = ./ApplicationExamples/Acoustic
|
|
|
architecture const = noarch
|
|
|
log-file = mylogfile.log
|
|
|
plotter-subdirectory const = Writers
|
|
|
|
|
|
/*Configure the domain*/
|
|
|
computational-domain
|
|
|
dimension const = 2
|
|
|
width = ##domain width
|
|
|
offset = ##offset
|
|
|
end-time = ##final time
|
|
|
end computational-domain
|
|
|
|
|
|
/*Configure shared memory settings*/
|
|
|
/*shared-memory
|
|
|
identifier = dummy
|
|
|
configure = {background-tasks:8}
|
|
|
cores = 8
|
|
|
properties-file = sharedmemory.properties
|
|
|
end shared-memory*/
|
|
|
|
|
|
/*Optimiziation: DO N0T TOUCH*/
|
|
|
global-optimisation
|
|
|
fuse-algorithmic-steps = all
|
|
|
fuse-algorithmic-steps-rerun-factor = 0.99
|
|
|
fuse-algorithmic-steps-diffusion-factor = 0.99
|
|
|
spawn-predictor-as-background-thread = off
|
|
|
spawn-amr-background-threads = off
|
|
|
/* 0.0 und 0.8 sind schon mal zwei Faktoren */
|
|
|
disable-vertex-exchange-in-time-steps = on
|
|
|
time-step-batch-factor = 0.0
|
|
|
disable-metadata-exchange-in-batched-time-steps = off
|
|
|
double-compression = 0.0
|
|
|
spawn-double-compression-as-background-thread = off
|
|
|
end global-optimisation
|
|
|
|
|
|
/*Defines the hyperbolic PDE*/
|
|
|
solver ADER-DG ADERSolver
|
|
|
variables const = ##variables
|
|
|
order const = ##polynomial order of the simulation
|
|
|
maximum-mesh-size = ##mesh size
|
|
|
time-stepping = globalfixed
|
|
|
type const = nonlinear
|
|
|
terms const = ##PDE terms, ie fluxes, sources etc
|
|
|
optimisation const = generic
|
|
|
language const = C
|
|
|
|
|
|
/*##Add plotters here if needed */
|
|
|
/*plot vtk::Cartesian::vertices::ascii VtkWriter
|
|
|
variables const = ##Number of variables to be plotted
|
|
|
time = ##Start time of the plotter
|
|
|
repeat = ##Plotting interval
|
|
|
output = ##File suffix
|
|
|
end plot */
|
|
|
end solver
|
|
|
|
|
|
end exahype-project
|
|
|
```
|
|
|
|
|
|
Set up a new directory *Acoustic* in ApplicationExamples to hold the new acoustic application. Copy the template above there and name it acoustic.exahype.
|
|
|
|
|
|
In this file all place holders are marked by ## and need to be filled to get a working application. All other options are only used for optimizations and don't need to be touched or understood for now. When you want to begin optimizing your application the [Guidebook](http://www.peano-framework.org/exahype/guidebook.pdf) gives a detailed overview of the options.
|
|
|
|
|
|
For now let's go through the place holders one by one and fill them in:
|
|
|
|
|
|
## `exahype-project`##Name
|
|
|
* The name of the project. Choose something short to name your project, e.g. Acoustic.
|
|
|
|
|
|
```javascript
|
|
|
exahype-project
|
|
|
```
|
|
|
## `output-directory const`
|
|
|
* Defines where the the code body will be generated relative to the root directory
|
|
|
* In our case we use *./ApplicationExamples/Acoustic*
|
|
|
|
|
|
```javascript
|
|
|
output-directory const = ./ApplicationExamples/Acoustic
|
|
|
```
|
|
|
|
|
|
## `computational-domain`
|
|
|
* Here we define the number of dimensions, the simulated domain and the physical end time of the application
|
|
|
* The acoustic equations can be defined in two or three dimensions, we want to do our simulation on the cube $`[-0.5,0.5]^3`$ and for one second:
|
|
|
|
|
|
```javascript
|
|
|
computational-domain
|
|
|
dimension const = 3
|
|
|
width = 1.0, 1.0, 1.0
|
|
|
offset = -0.5, -0.5, -0.5
|
|
|
end-time = 1.0
|
|
|
end computational-domain
|
|
|
```
|
|
|
|
|
|
## `solver ADER-DG` ...
|
|
|
* This region defines the characteristics of the simulated PDE and the used solver.
|
|
|
* `variables const` By lokking at the formula you see that the SWE consist of 3 quantities $'h,hu,hv'$ which we will denote with h and a vector p of length 2.
|
|
|
* `order const` The polynomial degreee of the high order representation. We'll use order 3.
|
|
|
* `maximum-mesh-size` The maximum size of a single cell. ExaHyPE always has to hold a power of 3 cells in one dimension<sup>1</sup>. By setting this value you define an lower limit for the number of cells which is the rounded up to the next power of 3. For our example setting `maximum-mesh-size` to 0.05 gives us a theoretical number of 20 cells in one dimension. The next power of three is 27, so our mesh will end up with 27 cells in each dimension and a mesh size of $`\frac{1}{27}`$.
|
|
|
* `type const` Here you can choose between a linear or nonlinear PDE. SWE are nonlinear (as the flux is).
|
|
|
* `terms const` The type of terms that occur in the PDE system. SWE only hold a flux.
|
|
|
|
|
|
```javascript
|
|
|
solver ADER-DG SWE_ADERDG
|
|
|
variables const = h:1,p:2
|
|
|
order const = 3
|
|
|
/* 27 points: 0.05, 9 points: 0.15 */
|
|
|
maximum-mesh-size = 0.05
|
|
|
time-stepping = globalfixed
|
|
|
type const = nonlinear
|
|
|
terms const = flux
|
|
|
optimisation const = generic
|
|
|
language const = C
|
|
|
end solver
|
|
|
```
|
|
|
<sup>1</sup> The explanation for this takes too long at this point, but believe me there is a reason.
|
|
|
|
|
|
## Adding a plotter
|
|
|
* In this example we add a simple vtk output plotter which is sufficient for our needs.
|
|
|
* Uncomment the plotter lines after `language const` and before `end solver` and fill in the missing information:
|
|
|
|
|
|
```javascript
|
|
|
plot vtk::Cartesian::vertices::ascii VtkWriter
|
|
|
variables const = 3
|
|
|
time = 0.0
|
|
|
repeat = 1e-2
|
|
|
output = ./swe
|
|
|
end plot
|
|
|
```
|
|
|
* This results in a writer plotting all 3 variables every 0.02 seconds starting at time 0. The files will have a prefix swe and be placed in the project directory.
|
|
|
|
|
|
# Run the Toolkit
|
|
|
To generate the code body apply the toolkit to the specification file we just created. Go back to the ExaHyPE root directory and hit :
|
|
|
|
|
|
```sh
|
|
|
./Toolkit/toolkit.sh ApplicationExamples/SWE_Test/SWE_ADERDG.exahype
|
|
|
```
|
|
|
The Toolit will end with `setup build environment ... ok` if it terminated successful, else you'll receive a detailed error message.
|
|
|
|
|
|
Go back to ApplicationExamples/SWE_Test/ you should see several automatically generated files:
|
|
|
|
|
|
```sh
|
|
|
ls SWE_Test
|
|
|
> AbstractSWE_ADERDG.cpp AbstractSWE_ADERDG.h KernelCalls.cpp Makefile README_generated.md SWE_ADERDG.cpp SWE_ADERDG.h SWE_ADERDG_Variables.h VtkWriter.cpp VtkWriter.h
|
|
|
|
|
|
``` |