diff --git a/doxygen/cantera.page b/doxygen/cantera.page new file mode 100644 index 000000000..ffabd913f --- /dev/null +++ b/doxygen/cantera.page @@ -0,0 +1,146 @@ +/*! \mainpage The MASA Library + +Version \version, Build Date: \builddate + +Built by: \builduser on \buildhost +
+ +\section overview Overview + +The MASA (Manufactured Analytical Solutions Abstraction) library is +a software interface that provides access to all manufactured solutions to + be used by various models throughout the PECOS center. +The library is written in +C++, but provides an API for development in C and Fortran. + +Thanks for your interest in MASA. To aid in usage, this manual is +further divided into the following subsections: + + + + + + +\section bugs Reporting Bugs + +Bugs in the code and errors or omissions in the documentation can be +reported to masa-dev@ices.utexas.edu. Requests and contributions are +welcome at the same e-mail address. All bug reports should include: + + +\section licence License +Copyright (C) 2010 The PECOS Development Team +\copydoc LicenseLGPL + +\section acknowledgements Acknowledgments +\copydoc Acknowledgments + +\section pecos-center More Information About PECOS +\copydoc About2 + + */ + + +/*! \page model Library Overview + +\copydoc LicenseLGPL + +The MASA (Manufactured Analytical Solutions Abstraction) library is a software interface that provides access +to various manufactured solutions for a wide variety of differential equations. The library is written in C++, +and provides an API for development in C and Fortran. + +

Software Verification

+ +Verification of numerical computations, in which one asks if numerical results are an accurate representation of the solution +to the mathematical model that is being solved, is relatively well understood. It requires +careful attention to good software engineering practices, continuous software testing, and control of numerical +discretization errors, through error estimation and adaptivity. While verification processes are well understood, +they require substantial effort. As verification of numerical results is a prerequisite for reliable computational +predictions, verification processes are integral to all activities in scientific computation. + +MASA is designed to simplify the verification process by providing a common repository of manufactured solutions +for common problems in scientific computation. + +

Manufactured Solution Generation

+ +The analytical solutions used in this library were generated using symbolic manipulation software, such as Maple. + +

PECOS Center Background

+ +The Center for Predictive Engineering and COmputational Sciences (PECOS) is a DOE-funded Center +of Excellence within the Institute for Computational Engineering and Sciences (ICES) +at The University of Texas at Austin. PECOS is one of five such centers sponsored under +the Predictive Science Academic Alliance Program (PSAAP) of the National Nuclear Security +Administration’s Advanced Simulation and Computing Program. + +PECOS brings together an interdisciplinary, multi-university team with partners at the +DOE National Labs and NASA. The goal of the PECOS Center is to develop the next generation +of advanced computational methods for predictive simulation of multiscale, multiphysics phenomena, +and to apply these methods to the analysis of vehicles reentering the atmosphere. In pursuing +this research, PECOS is advancing the science and modeling of atmospheric reentry, and +the science of predictive simulation. + +

Developers

+ +Developers of the MASA library include: + +Paul Bauman + +Kemelli Estacio-Hiroms + +Nicholas Malaya + +Todd Oliver + +Onkar Sahni + +Karl W. Schulz + +Chris Simmons + +Roy Stogner + +

Citing MASA

+ +A paper detailing the MASA library has been submitted for publication. +Upon acceptance, this section will be updated. +Please check back for details on how to cite MASA. + +*/ + + +/*! \page mms_avail Available Manufactured Solutions + +The following sections detail all available manufactured solutions in MASA. + + + +*/ + +/*! \page tut Tutorial + +The following sections detail all available manufactured solutions in MASA. + +*/ diff --git a/doxygen/install.page b/doxygen/install.page new file mode 100644 index 000000000..e15962efe --- /dev/null +++ b/doxygen/install.page @@ -0,0 +1,187 @@ +/*! \page install Installation/Linkage + +libMASA uses the GNU autotools suite (autoconf, automake, and libtool) +for its development build system. This system is popular among the +Linux development community and provides a familiar build environment +for end users. + +To build libMASA starting from a release distribution, untar the distribution and +enter the top-level directory. + +
+ > tar xvfz masa-$(VERSION).tar.gz
+ > cd masa-$(VERSION)/            
+
+ +

Configuration Requirements

+ +Since libMASA provides a Fortran interface, a valid Fortran90 compiler is +also required. To date, libMASA has been successfully tested with \e +gfortran and the Intel \e ifort compilers. The configuration step +will look for available compilers in the user environment but as with +any \e autoconf based configuration, these can be overridden with +command line arguments (by setting \c CXX, \c FC, and \c F77 +appropriately). + +Installation Directory: Use the --prefix option to +specify your desired top-level installation directory for MASA. The +examples below all configure libMASA to be installed in the user's ~/bin/masa +directory. + +Once configured, issue a make to build the software. If successful, this +will build the libMASA library (static and dynamic versions) and several +examples. + +\code > make \endcode + + Verifying the build: To verify that the software is working +properly, a test option is provided to run a short suite of +functionality tests against the local build. To run, issue a make +check to run the tests. If successful, output similar to the +following will be generated. + +\code + > make check + +------------------------------------------------------- +Initializing MASA Tests +------------------------------------------------------- +PASS: init.sh +PASS: misc +PASS: fail_cond +PASS: catch_exception +PASS: register +PASS: poly +PASS: uninit +PASS: pass_func +PASS: purge +PASS: heat_const_steady +PASS: heat_var_steady +PASS: heat_const_unsteady +PASS: heat_var_unsteady +PASS: euler1d +PASS: euler2d +PASS: euler3d +PASS: euler_transient_1d +PASS: euler_chem_1d +PASS: ns2d +PASS: ns3d +PASS: ns3d_phys +PASS: n2d3d +PASS: axi_euler +PASS: axi_cns +PASS: rans_sa +PASS: sod + +------------------------------------------------------- +Initializing CMASA Tests +------------------------------------------------------- +PASS: c_init.sh +PASS: c_misc +PASS: c_purge +PASS: c_heat1dsc +PASS: c_heat2dsc +PASS: c_heat3dsc +PASS: c_euler1d +PASS: c_euler2d +PASS: c_euler3d +PASS: c_euler_chem_1d +PASS: c_navierstokes2d +PASS: c_navierstokes3d + +------------------------------------------------------- +Initializing FortMASA Tests +------------------------------------------------------- +PASS: f_init.sh +MASA :: selected mytest +PASS: f_misc +PASS: f_purge +PASS: f_heat +PASS: f_euler1d +PASS: f_euler2d +PASS: f_euler3d +PASS: f_euler_chem_1d +PASS: f_cns2d +PASS: f_cns3d + +------------------------------------------------------- +Initializing MASA Examples Tests +------------------------------------------------------- +PASS: example_test.sh + +------------------------------------------------------- +Finalizing MASA Tests, have a well verified day +------------------------------------------------------- +PASS: finalize.sh +=================== +All 50 tests passed +=================== + +\endcode + +

Installation

+ +After the build is complete, issue a make install to install +the library. The installation will consist of three top-level +directories housing the library, include files, and +example files. An example of the top-level directories after +installation is shown below: + +\code > make install \endcode + +Top-level libMASA installation directory: + +\code + > ls $HOME/bin/masa/ + examples/ include/ lib/ +\endcode + +

Library Linkage

+ +To link an external C/C++ or Fortran application with the library, the +\c include directory must be added to the compilers include search +path in order to access the masa.h header file (or for Fortran, the \c +lib directory should be added to access the pre-compiled +masa F90 module). The \c lib directory should also be added +to the linker search path along with a request to link against the +libMASA library. Several example link steps are provided below. These +examples assume that the libMASA library has been successfully built and +installed previously in the users's ~/bin/masa directory: + +

C/C++ Example

+ +\code > $(CC) -I$HOME/bin/masa/include app.c -L$HOME/bin/masa/lib -lmasa \endcode + +If you set your PKG_CONFIG_PATH environment variable to contain +$HOME/lib/pkgconfig you can use pkg-config to +lookup the relevant linking information automatically: + +\code > $(CC) `pkg-config --cflags masa` app.c `pkg-config --libs masa` \endcode + +

Fortran Example

+ +Fortran applications also require linking against the fmasa library: + +\code > $(FC) -I$HOME/bin/masa/lib app.f90 -L$HOME/bin/masa/lib -lfmasa -lmasa \endcode + +As with C/C++, users can use make use of pkg-config: + +\code > $(FC) `pkg-config --variable=fflags masa` app.f90 `pkg-config --variable=flibs masa` \endcode + +To embed the dynamic library search path for the libMASA library +directly into the application executable, use an additional linker +option as follows: + +

C/C++ Example

+ +\code > $(CC) -I$HOME/bin/masa/include app.c -L$HOME/bin/masa/lib \ + -Wl,-rpath,$HOME/bin/masa/lib -lmasa \endcode + + +Important Note: F90 module file formats are not consistent +across multiple compilers. Therefore, a Fortran application and the libMASA +F90 interface \em must be built with the same Fortran compiler family to ensure +compatibility. + + +*/ diff --git a/doxygen/tutorial.page b/doxygen/tutorial.page new file mode 100644 index 000000000..d09fa8ae2 --- /dev/null +++ b/doxygen/tutorial.page @@ -0,0 +1,177 @@ +/*! \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. + +*/