File: ug.doc

package info (click to toggle)
dune-uggrid 2.6.0-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 4,712 kB
  • sloc: cpp: 64,245; ansic: 755; makefile: 5
file content (207 lines) | stat: -rw-r--r-- 11,820 bytes parent folder | download | duplicates (3)
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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
/****************************************************************************/
/*D
   ug - software library for the development of applications solving partial differential equations

WHAT IS UG:
   UG is a software toolbox that allows you to build applications
   that solve partial differential equations with state of the art techniques
   like multigrid, unstructured meshes, adaptivity and parallelism. 
   The idea is that as much code as possible can be reused for many different 
   problems and numerical methods. Of course every abstraction has its strengths
   and weaknesses but we believe that UG may be of great help to many people.

MAIN FEATURES OF UG:

.  Grids - UG was primarily written to ease the development of multigrid methods
   for practical problems. The basic mesh data structure allows hierarchical local
   refinement (and coarsening) of completely unstructured meshes. Currently triangular and quadrilateral
   elements in 2D and tetrahedral elements in 3D are supported. Work on hexahedral and
   pyramidal elements is in progress.

.  Solvers - UG stores matrices and vectors in a sparse matrix data structure that
   is independent of the geometric structure of the mesh. Any number of degrees of
   freedom can be placed in the nodes, edges, faces (3D) and elements of the mesh. This
   allows also the implementation of mixed or non-conforming finite elements for
   systems of partial differential equations. For some standard cases ready-to-use
   multigrid components are available.

.  Graphics - UG has built in graphics and a multiple window graphical user
   interface. E.g. in 3D color plots or vector plots on arbitrary planar cuts
   through the unstructured mesh can be plotted without writing lengthy files to disk.
   This functionality is available on standard X11 basis and the Apple Macintosh.
   In batch mode binary graphics files can be written for film animation and postscript
   conversion.

.  Interpreter - UG has a powerful command language that can be used to elegantly
   specify parameters, doing parameter studies, producing films from instationary calculations etc.

.  Parallelism - Version 2 of UG has been parallelized on MIMD message-passing architectures.
   This version is only 2D and allows only degrees of freedom in the nodes of the mesh. However,
   it has dynamic load balancing capabilites for unstructured, locally refined multigrid hierarchies
   and is highly portable (interfaces for PVM, MPI, PARIX, NXlib, T3D are available).
   Work is in progress to provide the extended functionality of ug3 on parallel architectures. A
   smooth migration for existing serial applications will be possible.

.  Applications - Five ready-to-run applications are shipped with the current
   distribution. These are: diffusion equation on triangular meshes with piecewise
   linear finite elements, diffusion equation on triangular meshes discretized with
   non-conforming P1 elements, linear elasticity with linear, conforming elements
   on triangles, Navier-Stokes equations discretized with a Finite-Volume method
   on triangular and quadrilateral meshes and diffusion equation in 3D.
   Several other applications are being developed with UG that are not publicly available:~
   two-phase flow in porous media, density driven flow in porous media, Euler equations,
   compressible Navier-Stokes equations, Plasticity, ...

THE BASIC IDEA:
   A typical application developed using the `ug` library can be divided into three 
   layers: application layer, problem class layer and ug layer. The layers perform
   the following tasks.

.   application~layer - description of the domain shape and the boundary conditions. This
    is done using a general interface that is independent of the specific problem to solve.
 
.   problem~class~layer - implements the partial differential equation with a set of different 
	solvers, estimators and discretisations. As far as the solver is concerned there are a number
    of methods built into the ug layer that can be used in the standard cases.

.   ug~layer - the ug layer itself is completely problem independent and is responsible
    for managing unstructured, locally refined meshes in two and three dimensions, drawing
    grids and results, managing multiple windows in a graphical user interface, providing
    a powerful script language etc. 

.vb
      
       layers of the UG software system:

        _____________________________________
       |                                     | 
       |        application layer:           | 
       |                                     | 
       | geometry, cofficient functions,     | 
       | boundary conditions                 | 
       |                                     | 
       +-------------------------------------+
       |                                     | 
       |         problem class layer:        | 
       |                                     | 
       | discretization, solver, estimator   | 
       |                                     | 
       +-------------------------------------+
       |                                     | 
       |            ug layer:                | 
       |                                     | 
       |         user interface              | 
       |                                     | 
       |  grid manager  graphics  numprocs   | 
       |                                     | 
       |       devices     low tasks         | 
       |_____________________________________| 
.ve


MODULAR STRUCTURE OF THE UG KERNEL:
	A module is considered in the 
	context of `ug` as a set of one or more source files which realize a specific functionality. 
	This viewpoint is closely related to the abstract data type (ADT) with data structures and 
	operations on them. The implementation of `ug` tries to follow the ADT concept 
	in a rather strict manner with the goal of high independency between the single modules.
	This should ensure the typical software engineering demands and create a basis for flexible 
	software which is portable and can be modified or extended to your needs with a small amount of work.  

    The ug layer itself has again an internal modular structure. The modules of the
    ug layer are the following.

.   'grid~management~(gm)' - The grid manager module performs all operations which manipulate the grid. It controls the creation 
	and deletion of new elements during refine and provides a well defined interface to the layers above.
	For more details see man page gm.

.   'graphics~(graph)' -
	This module of `ug` realizes a small 2/3D color graphics model. Some features are scalar or vector plots 
	with arbitrary viewpoint and cutplanes on the viewed domain,solution or grid.

.   'user~interface~(ui)' -
	The core of 'ui' is a command interpreter which provides a script language and gives access to 
	commands of your application. This allows to type in all commands directly into the command line
	interface furthermore it is possible to combine a series of commands and control statements of the script
	language in separate file. This script file can then be executed as one unity.

.   'devices~(dev)' -
	`devices` defines an abstract device interface with a fixed functionality.

.   'numerical~procedures~(numerics)' -
	The numerical procedures are a toolset for the construction of new solvers on very high languages level.
	Since they are implemented as commands, it is possible to access them on the skript or command line level.
	This allows a quick and easy formulation of your appropriate solver and rapid prototyping of new ideas.

.   'low~tasks~(low)' -
	This module handles low tasks as providing memory management, treating machine architecture and operation system 
	dependencies. 

INSTALLATION:
	For installation purposes read the manual page 'Installation' or the file 'README.install'. It will give you a
	detailed description about the installation and compilation process of `ug` and related applications.

DOCUMENTATION:
    UGs documentation is included in formatted comments in the source code. The
    documentation is extracted from the source code with the program 'doctext'
    which is available freely from William A. Gropp of Argonne National Laboratory.
    The documentation is available in postscript form (formatted by LaTeX) and
    as UNIX manual pages that can be read by either 'man' or 'xman'.

WHERE TO GO NEXT:
.   You should now read the file 'README.install' in the top level ug directory
    which explains the installation process in detail. The installation procedure will also
    explain how to access the manual pages. If you have problems with compilation, you should
    read the man page 'makefiles' that explains how the makefiles work and how UG can be
    adapted to different sites.

.   modules - We suppose now that UG has been compiled successfully and that you can access the manual
    pages. The next page to read is 'modules' which gives an overview of the UGs files and directories.

.   sample_session - Probably you now want to see whether UG really works. The man page 'sample_session'
    will guide you through your first steps with UG.

.   Applications - May be the next step is now to play around with the application supplied with UG.
    The manual section 'Problem Class & Appl Overview' accessible with the X manual browser (xugman command)
    or the chapters 1,4,7 in the application manual (applmanual.ps) are the appropriate place to start.
    If you change the application source file (e.g. 'diff2da.c' or 'cd3da.c') do not forget to type 'make'
    to rebuild the application. By reading the manual pages of the section 'Problem Class & Appl Overview'
    and looking at the application source code ('diff2da.c' or 'cd3da.c') you should be able to modify
    the domains, boundary conditions and coefficient functions for an existing application and also
    how to implement a new problem.

.   Commands - Another important thing to do is to explore all the commands that are available on UGs
    shell window. For that information see either the section 'ug Commands' from the X manual browser (xugman
    command) or chapter 2 in the Programmers Manual (progmanual.ps).
    Here you can also find a (more) detailed description of the commands used in the sample session.

.   Interpreter - The manual page 'Interpreter' describes the usage of UGs script language (the '*.scr' files).
    A good thing is also to look into the existing script files in order to see how commands are used.

    
HOW TO SOLVE YOUR PARTIAL DIFFERENTIAL EQUATION:
    If the p.d.e. you want to solve is not already supported by UG you will have to
    write your own problem class library and application. This of course is a major task that requires
    much more insight in UGs data structures and functions. The best thing to do
    is to try to understand how an existing problem class works (e.g. 'diff2d') by
    looking at the source code and reading manual pages about the functions and
    data structures that are encounterd on the way. Some important pages to read
    are pointed out below.

.   DATASTRUCTURE - This page provides an entry point to the description of the
    basic data structures that describe domains, problems, grids, etc.

.   numerics - provides an entry point to the BLAS routines, multigrid components,
    nonlinear solution strategies that have been implemented in reusable form. If
    you can use one of these methods things are simplified greatly.

.   GRAPH - provides an entry point in UGs graphics routines. 


ACKNOWLEDGEMENTS:
    We appreciate the use of the 'doctext' program written by William A. Gropp
    of Argonne National Laboratory.

D*/
/****************************************************************************/