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

Initalizing

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:

Setting up the Solution

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: 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.

Accessing the Source Terms

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