GRINS-0.8.0
grins.page
Go to the documentation of this file.
1 /*! \mainpage GRINS: General Reacting Incompressible Navier-Stokes
2 
3 <b>Version \version</b>, Build Date: \builddate
4 <br><br>
5 Built by: \builduser on \buildhost
6 <hr>
7 
8 \section overview Overview
9 
10 The GRINS code has been developed to serve as a test bed for
11 numerical methods, based on finite elements, for multiphysics problems
12 involving various forms of incompressible flow.
13 It is written in object-oriented C++ and leverages heavily the
14 C++ finite element library
15 <a href="http://libmesh.sourceforge.net">libMesh</a>. Although the majority of GRINS is
16 contained in a library, example applications
17 are included as well, including a generic solver.
18 
19 Thanks for your interest in GRINS. To aid in usage, this manual is
20 further divided into the following subsections:
21 
22 <ul>
23 <li> \subpage installation
24 <li> \subpage inputFile
25 <!-- <li> <a href="http://buildbot.ices.utexas.edu/docs/buildbot/hpct/build/docs/html/lcov/build/src/index.html">Buildbot Coverage</a> -->
26 </ul>
27 
28 \section bugs Reporting Bugs
29 
30 Bugs in the code and errors or omissions in the documentation can be
31 reported to pbauman@ices.utexas.edu. Requests and contributions are
32 welcome at the same e-mail address. All bug reports should include:
33 <ul>
34 
35 <li>the version number of GRINS (versioning information can
36 be obtained by running the <B><code>version</code></B> binary located in the
37 bin/ directory of a local GRINS installation),
38 <li>the hardware and operating system,
39 <li>the local compiler version number,
40 <li>a description of the bug behavior, and ideally,
41 <li>a short program which reproduces the bug.
42 </ul>
43 
44 \section licence License
45 Copyright (C) 2010,2011 The PECOS Development Team
46 \copydoc LicenseGPL
47 
48 \section acknowledgements Acknowledgments
49 \copydoc Acknowledgments
50 
51 \section pecos-center More Information About PECOS
52 \copydoc About
53 
54 */
55 
56 /*! \page inputFile Example GRINS Input File
57 
58 This is an example input file for use with the generic solver
59 included with GRINS.
60 Note that GRINS is using
61 the <a href="http://getpot.sourceforge.net/">GetPot</a> parsing tool
62 shipped with <a href="http://libmesh.sourceforge.net">libMesh</a>. Note
63 that the default comment delimiter is defined as the \# sign and
64 comments can begin at the beginning of a line or after a variable
65 declaration to aid in documenting the input file. The parsing
66 mechansism is keyword driven and can be organized into multiple
67 sections. Consequently, you are allowed to have variables of the same
68 name so long as they are within unique section definitions. Note also
69 that because the parsing mechanism is keyword driven, the input
70 directives can be specified in \e arbitrary order. There is no
71 requirement to maintain a specific variable declaration pattern.
72 
73 <hr>
74 
75 \include input_2d.in
76 
77 */
78 
79 /*! \page installation Installation/Linkage
80 
81 GRINS uses the GNU autotools suite (autoconf, automake, and libtool)
82 for its development build system. This system is popular among the
83 Linux development community and provides a familiar build environment
84 for end users.
85 
86 To build GRINS starting from a release distribution, untar the distribution and
87 enter the top-level directory.
88 
89 <div class="fragment"><pre class="fragment">
90  > tar xvfz grins-$(VERSION).tar.gz
91  > cd grins-$(VERSION)/
92 </pre></div>
93 
94 <h2>Configuration Requirements</h2>
95 
96 GRINS requires that the <a href="http://libmesh.sourceforge.net">libMesh</a>
97 be available locally, along with the <a href="http://libmesh.sourceforge.net">libMesh</a>
98 dependencies. Note that GRINS has been developed and tested on revision 4887 of
99 trunk. If <a href="http://libmesh.sourceforge.net">libMesh</a> is installed and available
100 within your default login environment, then GRINS should automatically configure
101 against the available installation. If, however, your <a href="http://libmesh.sourceforge.net">libMesh</a>
102 installation is in a non-standard location, use
103 the <tt>--with-libmesh</tt> option to specify the location.
104 
105 To date, GRINS has been successfully built and tested with the gcc 4.4, 4.5, and 4.6 compilers
106 and the Intel 11.1 compilers.
107 
108 <b>Installation Directory</b>: Use the <tt>--prefix</tt> option to
109 specify your desired top-level installation directory for GRINS. The
110 examples below all configure GRINS to be installed in the user's ~/bin/grins
111 directory.
112 
113 <em>Configure with libMesh from default login environment:</em> <br>
114 
115 \code > ./configure --prefix=$HOME/bin/grins \endcode
116 
117 <em>Or, configure with libMesh from a specific directory:</em> <br>
118 
119 \code > ./configure --prefix=$HOME/bin/grins --with-libmesh=$MY_LIBMESH_DIR \endcode
120 
121 <em>Or, configure with specific compilers:</em> <br>
122 
123 \code > ./configure CXX=g++ --prefix=$HOME/bin/grins \endcode
124 
125 <h2> Other Configuration Options </h2>
126 
127 GRINS can optionally be built with other libraries as well. In particular, GRINS leverages the
128 <a href="https://red.ices.utexas.edu/projects/software/wiki/GRVY">GRVY</a> library for
129 some performance timing capabilities.
130 
131 <em>Configure with libGRVY and enable grvy timers :</em> <br>
132 
133 \code > ./configure --with-grvy=$MY_GRVY_DIR --enable-grvy-timers \endcode
134 
135 To enable verification using the method of manufactured solutions, GRINS uses
136 the <a href="https://red.ices.utexas.edu/projects/software/wiki/MASA">MASA</a>
137 library. Although GRINS can configure and build with
138 <a href="https://red.ices.utexas.edu/projects/software/wiki/MASA">MASA</a>, it is currently not
139 using these capabilities. This is planned for the next release.
140 
141 <em>Configure with MASA:</em> <br>
142 
143 \code > ./configure --with-masa=$MY_MASA_DIR \endcode
144 
145 Configure help can also be accessed at the command line:
146 
147 \code> ./configure --help \endcode
148 
149 <h2> Library Build </h2>
150 
151 Once configured, issue a <tt>make</tt> to build the software. If successful, this
152 will build GRINS (static and dynamic libraries and executables).
153 
154 \code > make \endcode
155 
156 If you have multiple cores at your disposal, a parallel buid can accelerate
157 the build time. If there are 4 cores avaiable, then the following will build
158 using 4 threads, thereby leveraging 4 processors.
159 
160 \code > make -j 4\endcode
161 
162 <b> Verifying the build:</b> To verify that the software is working
163 properly, a test option is provided to run a short suite of
164 functionality tests against the local build. To run, issue a <tt>make
165 check</tt> to run the tests. Note that these tests may take a few minutes
166 depending upon optimization level and architecture.
167 If successfull, output similar to the
168 following will be generated.
169 
170 \code
171  > make check
172 -------------------------------------------------------
173  Initializing Incompressible Navier-Stokes tests.
174 -------------------------------------------------------
175 PASS: navier_stokes_tests.sh
176 PASS: test_ns_couette_flow_2d_x.sh
177 PASS: test_ns_couette_flow_2d_y.sh
178 PASS: test_ns_poiseuille_flow.sh
179 PASS: test_axi_ns_poiseuille_flow.sh
180 PASS: test_axi_ns_con_cyl_flow.sh
181 -------------------------------------------------------
182  Initializing Thermally Driven Flow tests.
183 -------------------------------------------------------
184 PASS: thermally_driven_flow_tests.sh
185 PASS: test_thermally_driven_2d_flow.sh
186 PASS: test_axi_thermally_driven_flow.sh
187 PASS: test_thermally_driven_3d_flow.sh
188 -------------------------------------------------------
189  Finalizing all regression tests. Don't worry be happy.
190 -------------------------------------------------------
191 PASS: finalize.sh
192 ===================
193 All 11 tests passed
194 ===================
195 \endcode
196 
197 <h2> Installation </h2>
198 
199 After the build is complete, issue a <tt>make install</tt> to install
200 GRINS. This will install the header files, libraries, executables,
201 and examples.
202 The installation will consist of four top-level
203 directories housing the library, include files, executables, and
204 example files. An example of the top-level directories after
205 installation is shown below:
206 
207 \code > make install \endcode
208 
209 Top-level GRINS installation directory:
210 
211 \code
212  > ls $HOME/bin/grins/
213  bin examples include lib
214 \endcode
215 
216 <h2>Library Linkage</h2>
217 
218 Although a generic solver is shipped with the code, you may wish to
219 write your own application code. To link an external application with the library, the
220 \c include directory must be added to the compilers include search
221 path in order to access the necessary header files. The \c lib directory should also be added
222 to the linker search path along with a request to link against the
223 GRINS library. Several example link steps are provided below. These
224 examples assume that the GRINS library has been successfully built and
225 installed previously in the users's ~/bin/grins directory:
226 
227 \code > $(CXX) -I$HOME/bin/grins/include app.c -L$HOME/bin/grins/lib -lgrins \endcode
228 
229 To embed the dynamic library search path for the GRINS library
230 directly into the application executable, use an additional linker
231 option as follows:
232 
233 \code > $(CXX) -I$HOME/bin/grins/include app.c -L$HOME/bin/grins/lib \
234  -Wl,-rpath,$HOME/bin/grins/lib -lgrins \endcode
235 
236 */
237 
238 

Generated on Tue Dec 19 2017 12:47:27 for GRINS-0.8.0 by  doxygen 1.8.9.1