/*! \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.

*/
