177 lines
6 KiB
Text
177 lines
6 KiB
Text
/*! \page tut Tutorial
|
|
|
|
This chapter will introduce the user to the basics of the MASA library.
|
|
This chapter assumes the user has already built and linked the MASA library
|
|
into their codebase. Now, you desire to access the magic of MASA
|
|
and begin the process of verification of your codebase.
|
|
|
|
This tutorial will detail the essential subroutines for any MASA program.
|
|
The c++ MASA bindings are used throughout, but a tutorial using the Fotran90
|
|
or C-code would be essentially unchanged.
|
|
|
|
<h1> Initalizing </h1>
|
|
|
|
To begin, any MASA program will call \c masa_init. This routine initalizes
|
|
a manufactured solution class of some particular type. It requires two inputs:
|
|
the manufactured solution class name as well as a unique name for this solution.
|
|
|
|
Thus, to initalize a one dimensional euler equation manufactured solution with
|
|
the unique name of 'nick', the function call would look something like:
|
|
|
|
\code
|
|
masa_init("nick","euler_1d");
|
|
\endcode
|
|
|
|
The unique name allows you to initalize several manufactured solutions of the same
|
|
problem type, should you so desire. This can be useful if you want to access several
|
|
manufactured solutions of the same type with different parameter sets.
|
|
You cannot, of course, specify several manufactured solutions with the same unique name!
|
|
|
|
Please be careful when specifying the second string: this \em must match the unique
|
|
identifier for that masa solution. Failing to match here will likely result in MASA aborting.
|
|
|
|
A logical question to ask at this juncture is where can you find a list of the
|
|
available manufactured solutions? The available solutions can be found several ways:
|
|
|
|
<ul>
|
|
<li> Browsing the available manufactured solutions page of this documentation
|
|
<li> Running the display_solutions executable in your examples directory
|
|
<li> Browsing through the solutions interactively using MASAshell (also in the examples dir)
|
|
<li> Calling the function: \c masa_printid()
|
|
</ul>
|
|
|
|
<h2> Setting up the Solution </h2>
|
|
|
|
Having initalized the solution, you need to set the variables to some reasonable value.
|
|
This will depend on your particular problem, but let's continue with the 1d euler example.
|
|
|
|
Firstly, let's determine \em what variables need to be set. A list of variables for
|
|
your solution can be found by:
|
|
|
|
<ul>
|
|
<li> Browsing the particular manufactured solution's page in this documentation
|
|
<li> Selecting the solution and then displaying the variables interactively using MASAshell
|
|
<li> Calling the function: \c masa_display_param()
|
|
</ul>
|
|
|
|
The output from masa_display_param() for our euler1d example will look something like:
|
|
\code
|
|
|
|
MASA :: Solution has 14 variables.
|
|
*-------------------------------------*
|
|
Gamma is set to: Uninitialized
|
|
L is set to: Uninitialized
|
|
R is set to: Uninitialized
|
|
a_px is set to: Uninitialized
|
|
a_rhox is set to: Uninitialized
|
|
a_ux is set to: Uninitialized
|
|
k is set to: Uninitialized
|
|
mu is set to: Uninitialized
|
|
p_0 is set to: Uninitialized
|
|
p_x is set to: Uninitialized
|
|
rho_0 is set to: Uninitialized
|
|
rho_x is set to: Uninitialized
|
|
u_0 is set to: Uninitialized
|
|
u_x is set to: Uninitialized
|
|
*-------------------------------------*
|
|
|
|
\endcode
|
|
|
|
Thus, euler_1d has 14 variables, all of which should be set to something.
|
|
We can set a value of a parameter in MASA using the function, \c masa_set_param.
|
|
|
|
\c masa_set_param takes as input a string and a double. The string specifies the
|
|
parameter we are setting and the double will become the parameter's new value.
|
|
This overwrites the any previous value the paramter may have had.
|
|
|
|
Continuing our example, let's set a_rhox to 33.33 (repeating, of course).
|
|
In our code, this would look like:
|
|
|
|
\code
|
|
|
|
masa_set_param("a_rhox",33.3333333333333)
|
|
|
|
\endcode
|
|
|
|
Now, checking \c masa_display_param, we can see we have set the value of a_rhox:
|
|
|
|
\code
|
|
|
|
MASA :: Solution has 14 variables.
|
|
*-------------------------------------*
|
|
Gamma is set to: Uninitialized
|
|
L is set to: Uninitialized
|
|
R is set to: Uninitialized
|
|
a_px is set to: Uninitialized
|
|
a_rhox is set to: 33.3333333333333
|
|
a_ux is set to: Uninitialized
|
|
k is set to: Uninitialized
|
|
mu is set to: Uninitialized
|
|
p_0 is set to: Uninitialized
|
|
p_x is set to: Uninitialized
|
|
rho_0 is set to: Uninitialized
|
|
rho_x is set to: Uninitialized
|
|
u_0 is set to: Uninitialized
|
|
u_x is set to: Uninitialized
|
|
*-------------------------------------*
|
|
|
|
\endcode
|
|
|
|
At this point, we could continue the same process for
|
|
each remaining variable.
|
|
|
|
To save you the tedium of doing this, MASA has graciously provided
|
|
default values for all manufactured solution classes.
|
|
In general, the default values have been selected to provide reasonable
|
|
test conditions for verification and whenever possible, defauls
|
|
correspond to some simple physical constraints
|
|
(such as not producing negative energy, or density, etc.).
|
|
|
|
A user can invoke these defaults using the routine: \c masa_init_param().
|
|
For our euler1d problem, the defaults look like:
|
|
|
|
\code
|
|
|
|
MASA :: Solution has 14 variables.
|
|
*-------------------------------------*
|
|
Gamma is set to: 16.1
|
|
L is set to: 3.02
|
|
R is set to: 1.01
|
|
a_px is set to: 6.151
|
|
a_rhox is set to: 1.2
|
|
a_ux is set to: 0.03
|
|
k is set to: 1.38
|
|
mu is set to: 0.091
|
|
p_0 is set to: 0.1984
|
|
p_x is set to: 3.151
|
|
rho_0 is set to: 91.5
|
|
rho_x is set to: 5.13
|
|
u_0 is set to: 0.191
|
|
u_x is set to: 1.63
|
|
*-------------------------------------*
|
|
|
|
\endcode
|
|
|
|
Note that setting the defaults \em will \em overwrite \em all \em previously
|
|
\em initalized \em values for the masa parameters! So if you desire to
|
|
alter the default values, call \c masa_set_param \em after \c masa_init_param.
|
|
|
|
Finally, you have initalized all the parameters and you are ready to move on
|
|
... Or are you? Are you certain you initalized every parameter? Do you really
|
|
want to verify this by checking \c masa_display_param()? Luckily, MASA provides
|
|
an alternative. The subroutine \c masa_sanity_check() will check that every
|
|
parameter has been set to \em something.
|
|
|
|
<h2> Accessing the Source Terms </h2>
|
|
|
|
|
|
\code
|
|
> ls $HOME/bin/masa/
|
|
examples/ include/ lib/
|
|
\endcode
|
|
|
|
|
|
For further examples (including c-code and fortran), the user is directed
|
|
to the examples directory included in the MASA distribution.
|
|
|
|
*/
|