[cantera+autotools]: adding the tutorial and install pages
This commit is contained in:
Nicholas Malaya
parent
bb6321c998
commit
4426d9059c
3 changed files with 510 additions and 0 deletions
146
doxygen/cantera.page
Normal file
146
doxygen/cantera.page
Normal file
|
|
@ -0,0 +1,146 @@
|
|||
/*! \mainpage The MASA Library
|
||||
|
||||
<b>Version \version</b>, Build Date: \builddate
|
||||
|
||||
Built by: \builduser on \buildhost
|
||||
<hr>
|
||||
|
||||
\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:
|
||||
|
||||
<ul>
|
||||
<li> \subpage model "Library Overview" </li>
|
||||
<li> \subpage install "Installation/Linkage" </li>
|
||||
<li> \link masa.h C/C++ Interface \endlink </li>
|
||||
<li> \subpage apif "Fortran Interface" </li>
|
||||
<li> \link tut "Tutorial" </li>
|
||||
<li> \subpage mms_avail "Available Manufactured Solutions"</li>
|
||||
<li> \subpage add_sol "Adding Additional Manufactured Solutions to MASA" </li>
|
||||
<li> <a href="http://buildbot.ices.utexas.edu/docs/buildbot/masa/docs/html/lcov/build/src/index.html">Buildbot Coverage</a> </li>
|
||||
</ul>
|
||||
|
||||
<!-- \subpage apiF Fortran API -->
|
||||
<!-- \subpage examples Examples -->
|
||||
|
||||
\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:
|
||||
<ul>
|
||||
<li>the version number of the MASA library,
|
||||
<li>the hardware and operating system,
|
||||
<li>the compiler used, including version number and compilation options,
|
||||
<li>a description of the bug behavior, and ideally,
|
||||
<li>a short program which reproduces the bug.
|
||||
</ul>
|
||||
|
||||
\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.
|
||||
|
||||
<h2>Software Verification</h2>
|
||||
|
||||
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.
|
||||
|
||||
<h2>Manufactured Solution Generation</h2>
|
||||
|
||||
The analytical solutions used in this library were generated using symbolic manipulation software, such as Maple.
|
||||
|
||||
<h2>PECOS Center Background</h2>
|
||||
|
||||
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.
|
||||
|
||||
<h2> Developers </h2>
|
||||
|
||||
Developers of the MASA library include:
|
||||
|
||||
Paul Bauman
|
||||
|
||||
Kemelli Estacio-Hiroms
|
||||
|
||||
<a href="mailto:nick@ices.utexas.edu">Nicholas Malaya</a>
|
||||
|
||||
Todd Oliver
|
||||
|
||||
Onkar Sahni
|
||||
|
||||
Karl W. Schulz
|
||||
|
||||
Chris Simmons
|
||||
|
||||
Roy Stogner
|
||||
|
||||
<h2> Citing MASA </h2>
|
||||
|
||||
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.
|
||||
|
||||
<ul>
|
||||
<li> \subpage heat </li>
|
||||
<li> \subpage laplace </li>
|
||||
<li> \subpage euler </li>
|
||||
<li> \subpage cns </li>
|
||||
<li> \subpage sod </li>
|
||||
<li> \subpage rans </li>
|
||||
</ul>
|
||||
|
||||
*/
|
||||
|
||||
/*! \page tut Tutorial
|
||||
|
||||
The following sections detail all available manufactured solutions in MASA.
|
||||
|
||||
*/
|
||||
187
doxygen/install.page
Normal file
187
doxygen/install.page
Normal file
|
|
@ -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.
|
||||
|
||||
<div class="fragment"><pre class="fragment">
|
||||
> tar xvfz masa-$(VERSION).tar.gz
|
||||
> cd masa-$(VERSION)/
|
||||
</pre></div>
|
||||
|
||||
<h2>Configuration Requirements</h2>
|
||||
|
||||
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).
|
||||
|
||||
<b>Installation Directory</b>: Use the <tt>--prefix</tt> 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 <tt>make</tt> to build the software. If successful, this
|
||||
will build the libMASA library (static and dynamic versions) and several
|
||||
examples.
|
||||
|
||||
\code > make \endcode
|
||||
|
||||
<b> Verifying the build:</b> 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 <tt>make
|
||||
check</tt> 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
|
||||
|
||||
<h2> Installation </h2>
|
||||
|
||||
After the build is complete, issue a <tt>make install</tt> 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
|
||||
|
||||
<h2>Library Linkage</h2>
|
||||
|
||||
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:
|
||||
|
||||
<h3>C/C++ Example</h3>
|
||||
|
||||
\code > $(CC) -I$HOME/bin/masa/include app.c -L$HOME/bin/masa/lib -lmasa \endcode
|
||||
|
||||
If you set your <tt>PKG_CONFIG_PATH</tt> environment variable to contain
|
||||
<tt>$HOME/lib/pkgconfig</tt> you can use <ahref="http://pkg-config.freedesktop.org/wiki/"><tt>pkg-config</tt></a> to
|
||||
lookup the relevant linking information automatically:
|
||||
|
||||
\code > $(CC) `pkg-config --cflags masa` app.c `pkg-config --libs masa` \endcode
|
||||
|
||||
<h3>Fortran Example</h3>
|
||||
|
||||
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:
|
||||
|
||||
<h3>C/C++ Example</h3>
|
||||
|
||||
\code > $(CC) -I$HOME/bin/masa/include app.c -L$HOME/bin/masa/lib \
|
||||
-Wl,-rpath,$HOME/bin/masa/lib -lmasa \endcode
|
||||
|
||||
|
||||
<b>Important Note:</b> 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.
|
||||
|
||||
|
||||
*/
|
||||
177
doxygen/tutorial.page
Normal file
177
doxygen/tutorial.page
Normal file
|
|
@ -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.
|
||||
|
||||
<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.
|
||||
|
||||
*/
|
||||
Loading…
Add table
Reference in a new issue