-
Notifications
You must be signed in to change notification settings - Fork 13
/
read.html
93 lines (83 loc) · 10.9 KB
/
read.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
<!doctype html>
<html>
<head>
<title>Trilinos Tutorial READ_ME</title>
</head>
<body bgcolor="F0F0FF">
<div style="FLOAT: left;"id="contents"><table border=1 cellpadding=6 bgcolor=white><td>Contents:
<ol><li><a href="#main">Overview</a></li>
<li><a href="#layout">General layout</a></li>
<li><a href="#builds">Trilinos Examples</a>
<ul><li><a href="#make">Makefiles</a></li>
<li><a href="#cmake">CMake</a></li>
<li><a href="#shell">runit.sh Script</a></li>
<li><a href="#gui">Optika Gui</a></li></ul></li>
<li><a href="#custom">Inserting User Code</a></li>
<li><a href="#samples">Sample Files</a></li>
<li><a href="#version">Version Info</a></li>
<li><a href="#download">Download Links</a></li>
</ol></td></table></div>
<div style="FLOAT: right;"><img src="trilinoslogo.jpg" alt="Trilinos logo" width=200pix></div>
<div id="text"><center><table cellpadding= 6 bgcolor=white><td>
<div id="main"><h3>Welcome to the Trilinos tutorial!</h3>
<h4>Overview</h4>
<p>The Trilinos Project is an effort to develop algorithms and enabling technologies within an object-oriented software framework for the solution of large-scale, complex multi-physics engineering and scientific problems. </p>
<p>This tutorial contains examples illustrating how to use many Trilinos packages as well as how to build and compile code that links against Trilinos libraries. The Tutorial was designed on and for the HPCLinux distribution for which there is a link in the <a href="#download">Downloads</a> section. As such, the instructions reflect the assumption that the tutorial is being used in the HPCLinux environment. However with minimal changes the tutorial should be usable in other environments. A simple setup script is provided to load the correct modules for working in the HPCLinux environment. To invoke the script, simply run the command <code>source setup.sh</code>. This tutorial also provides a simple framework to work with trilinos code. The tutorial examples can be built and run in multiple ways, as described in the <a href="#builds">Trilinos Examples</a> section. For information on how to easily build your own code into this environment see the <a href="#custom">Inserting User Code</a> section.
For more information on how to use and work with the examples see the <A HREF="http://code.google.com/p/trilinos/wiki/TrilinosHandsOnTutorial">Trilinos Hands-On Tutorial</A> which contains details about the beginner examples.</p>
<p>This tutorial also contains instructions for building an application code called Tramonto, which uses several Trilinos libraries in the HPCLinux environment. Those instructions can be found in the <a href="tramonto.html">tramonto.html</a> document.</p>
</div>
<div id="layout"><h4>General Layout</h4>
<p>Within this directory there are several subdirectories. The directories <code>beginner, advanced</code>, and <code>custom</code> each contain sets of examples. Each example is located in a separate directory containing source code, a Makefile, and a CMakeLists.txt file. </p>
<hr>
<p>The general format is: Trilinos_tutorial/<em>set_of_examples/specific_example</em></p>
<p>For example: Trilinos_tutorial/beginner/Epetra_Simple_Vector</p>
<p>This folder contains the files <em>"Epetra_Simple_Vector.cpp"</em> and <em>"Makefile"</em>as well as <em>"CMakeLists.txt"</em> for the CMake build.</p>
<hr>
</div>
<div id="builds"><h4>Trilinos Examples</h4>
<p>This tutorial shows several different methods to build and run code using Trilinos. These range from using traditional <a href="#make">Makefiles</a> to a <a href="#cmake">CMake</a> build system complete with several tests. There is also a <a href="#shell">shell script</a> as well as a <a href="#gui">GUI</a> that provide convenient ways to run examples build using the Makefile system. As stated above it is important to have the correct modules loaded to run most of these examples, so execute the command <code>source setup.sh</code> in this main directory before attempting to run an example.
</p>
</div>
<div id="make"><h5>Using Makefiles</h5>
<p>The Makefile framework is capable of compiling all of the examples by simply typing <code>make</code> in the home directory. This shows a simple way to compile multiple examples at once as well as how to use a hierarchical structure with makefiles. Examples can also be individually compiled using the same command in the specific example directory. The Makefiles generate the executable for the example which can then be moved and run independently (assuming the correct modules are loaded). For a commented example of a makefile, see the Epetra_Simple_Vector <a href="./beginner/Epetra_Simple_Vector/Makefile"><code>Makefile</code></a>.</p>
</div>
<div id="cmake"><h5>Using CMake</h5>
<p>The CMake build option can be used to compile and run tests as well as examples. When operating outside of the HPCLinux environment, the first step is to point the <code>-DCMAKE_PREFIX_PATH</code> option inside of the <code>cmake_build/live-cmake</code> configuration script to a trilinos installation. The separate <code>cmake_build</code> build directory is used to prevent overwriting important files like the Makefiles used for the Makefile-based build. Using a build directory that is distinct from your source directory is always recommended when using CMake as this will keep your source directory clean. Running the script will generate all of the necessary files within the build directory. Next type <code>make</code> to compile all of the examples and tests. After the build completes, several tests can be run using <code>ctest</code>. This provides some assurance that the tutorial is working correctly.</p>
<p> Like the Makefile build system, CMake is a hierarchical build system. To see how it is set up look at the <code>CMakeLists.txt</code> files in the source code directory system. For a commented example of a CMakeLists.txt file, see the Teuchos_Parameter List test's <a href="./ctests/Teuchos_ParameterList/CMakeLists.txt">file</a>. This example also shows how to set up tests using ctest as well as link other code to the examples.</p>
</div>
<div id="shell"><h5>Using the runit.sh script</h5>
<p>This script works on top of the Makefile system in building and executing the examples. The <code>runit.sh</code> script takes a target example directory as well as a number of processors to use. To see more specific script usage, run the script without parameters or with the -h tag. Executing this shell script compiles and runs the code. It also outputs the results to the terminal and saves the output into a file in the specific example directory as <code>[EXE_DIR].log</code>. The script is capable of running individual examples and also the entire beginner suite.</p>
</div>
<div id="gui"><h5>Using the Optika GUI</h5>
<p>Contained within Trilinos is a package called Optika that can be used to create a simple Graphical User Interface (GUI). A GUI is provided in this tutorial that can run the example suite. The GUI can be opened by running the command <code>./tutorial_gui</code>. The Makefile-based build is used by default, but the GUI can also be made to run against the cmake build by running the command <code>./tutorial_gui cmake</code>. The tutorial_gui executable provides a simple interface to choose an example and provide parameters. For the advanced examples there will be another parameterlist containing additional parameters that can be accessed by expanding the Advanced Parameter List Option and any subsequent Parameter Lists. After setting the desired values, the "submit" button will run the example with the given parameters and output the results to the terminal. The .log files will also be available in the logs folder in the home directory of this tutorial. When you are finished, simply close the GUI and it will prompt to save the current inputs into an xml file which can be later loaded back into the GUI. But, be careful loading xml files like this because an incompatible xml file will cause the program to fail. </p>
</div>
<hr>
<div id="custom"><h4>Inserting User Code</h4>
<p>Adding user code into this tutorial framework is rather straight forward. The simplest way to add user code is to replace the file custom/My_Example/My_Example.cpp with the your custom code. Examples with custom names can be added to the Makefile system or the CMake system by modeling the addition off of the existing examples.</p>
<p>For the Makefile-based system, copy the source code into a new directory (for this example assume the code is called <code>myCode1.cpp</code>). To keep with the pattern (though it's not necessary) we would place this code in a directory with the filepath custom/myCode1/ . Next, copy the existing Makefile from any of the beginner examples, replacing all occurrences of the example name with the name of the custom source code. In this case that would be "myCode1". The Makefile should then work with the custom code. </p>
<p>Using CMake is a very similar procedure to using make. The only difference is the name of the helper file. However for CMake you must also inform the top-level system to build your file by editing the <code>CMakeLists.txt</code> in the parent directories to include the new example. This can be done by adding the line <code>add_subdirectory(myCode1)</code> to the parent <code>CMakeLists.txt</code> file.</p>
<p>If you're feeling really adventurous you can try to integrate a GUI for your code. For examples that may help you towards this endeavor see the <a href ="#samples">Sample Files</a> section that follows this.</p>
<b>Note: Due to some problem with the current VM you may have to include the file <code>aprepro_vhelp.h</code> in source files. This header can be found in the home directory of this tutorial.</b>
</div>
<hr>
<div id="samples"><h4>Sample Files</h4>
<p>Here are several example files that are documented to show how the parts of various helper files work
<ul><li>Example <a href="beginner/Epetra_Simple_Vector/Makefile">Makefile</a></li>
<li>Example <a href="ctests/Teuchos_ParameterList/CMakeLists.txt">CMakeLists.txt</a></li>
<li>Example <a href="gui/tutorial_gui/tutorial_gui.cpp.txt">GUI Source</a><br>
The source code for the optika GUI provided in this tutorial.</li>
<li>Example <a href="gui/tutorial_gui/gui.xml">GUI xml Document</a><br>
The xml document for formatting the optika GUI.</li></ul>
</p>
</div>
<div id="version"><hr>
<p style="text-align:center"><strong>This current tutorial works with trilinos version 10.10.0</strong></p>
<hr>
<p>This tutorial was tested against the latest version of the ParaTools VM retrieved from the paratools site on 7/20/12</p></div>
<div id="download"><h4>Downloads</h4>
<p>Here are additional links to the download pages of VirtualBox and the latest virtual machine:
<br><A HREF="https://www.virtualbox.org/wiki/Downloads">VirtualBox Download</A>
<br><A HREF="http://www.paratools.com/HPCLinux/">HPCLinux VM</A></p></div>
</td></table></div>
</body>
</html>