[cig-commits] commit 2282 by bangerth to /var/svn/dealii/aspect

[dealii.demon at gmail.com]

Revision 2282

Provide another section on how to set up models.

U   trunk/aspect/doc/manual/manual.tex
U   trunk/aspect/doc/manual.pdf
U   trunk/aspect/doc/modules/changes.h


http://www.dealii.org/websvn/revision.php?repname=Aspect+Repository&path=%2F&rev=2282&peg=2282

Diff:
Modified: trunk/aspect/doc/manual/manual.tex
===================================================================
--- trunk/aspect/doc/manual/manual.tex	2014-01-28 17:07:39 UTC (rev 2281)
+++ trunk/aspect/doc/manual/manual.tex	2014-01-29 14:54:16 UTC (rev 2282)
@@ -2424,12 +2424,74 @@
 that show thermal convection (Section~
ef{sec:cookbooks-simple}), setups
 that try to model geophysical situations (Section~
ef{sec:cookbooks-geophysical})
 and setups that are used to benchmark spect{} to ensure correctness or to test accuracy
-of our solvers (Section~
ef{sec:cookbooks-benchmarks}).
+of our solvers (Section~
ef{sec:cookbooks-benchmarks}). Before we get there,
+however, we will review how one usually approaches setting up computations in
+Section~
ef{sec:cookbooks-overview}.
 
 
ote{The input files discussed in the following sections can generally be
   found in the 	exttt{cookbooks/} directory of your spect{} installation.}
 
 
+\subsection{How to set up computations}
+\label{sec:cookbooks-overview}
+
+spect{}'s computations are controlled by input parameter files such as those
+we will discuss in the following sections.%
+ootnote{You can also extend spect{} using plugins -- i.e., pieces of code
+you compile separately and either link into the spect{} executable itself, or
+reference from the input file. This is discussed in
+Section~
ef{sec:extending}.}
+Basically, these are just regular text files you can edit with programs like
+	exttt{gedit}, 	exttt{kwrite} or 	exttt{kate} when working on Linux, or
+something as simple as 	exttt{NotePad} on Windows. When setting up these input
+files, you basically have to describe everything that characterizes the
+computation you want to do. In particular, this includes the following:
+egin{itemize}
+  \item What internal forces act on the medium (the equation)?
+  \item What external forces do we have (the right hand side)
+  \item What is the domain (geometry)?
+  \item What happens at the boundary for each variable involved (boundary
+ conditions)?
+  \item How did it look at the beginning (initial conditions)? 
+\end{itemize}
+For each of these questions, there are one or more input parameters (sometimes
+grouped into sections) that allow you to specify what you want. For example, to
+choose a geometry, you will typically have a block like this in your input file:
+egin{lstlisting}[frame=single,language=prmfile,escapechar=\%]
+set Dimension = 2
+subsection Geometry model
+  set Model name = box % \index[prmindex]{Model name} \index[prmindexfull]{Geometry model!Model name} %
+
+  subsection Box
+    set X extent = 1 % \index[prmindex]{X extent} \index[prmindexfull]{Geometry model!Box!X extent} %
+    set Y extent = 1 % \index[prmindex]{Y extent} \index[prmindexfull]{Geometry model!Box!Y extent} %
+  end
+end
+\end{lstlisting}
+This indicates that you want to do a computation in 2d, using a rectangular
+geometry (a ``box'') with edge length equal to one in both the $x$- and
+$y$-directions. Of course, there are other geometries you can choose from for
+the 	exttt{Model name} parameter, and consequently other subsections that
+specify the details of these geometries.
+
+If you go down the list of questions about the setup above, you have already
+done the majority of the work describing your computation. The remaining
+parameters you will typically want to specify have to do with the computation
+itself. For example, what variables do you want to output and how often? What
+statistics do you want to compute. The following sections will give ample
+examples for all of this, but using the questions above as a guideline is
+already a good first step.
+
+
ote{It is of course possible to set up input files for computations
+completely from scratch. However, in practice, it is often simpler to go
+through the list of cookbooks already provided and find one that comes close to
+what you want to do. You would then modify this cookbook until it does what you
+want to do. The advantage is that you can start with something you already know
+works, and you can inspect how each change you make -- changing the
+details of the geometry, changing the material model, or changing what is being
+computed at the end of each time step -- affects what you get.}
+
+
 \subsection{Simple setups}
 \label{sec:cookbooks-simple}
 

Modified: trunk/aspect/doc/manual.pdf
===================================================================
(Binary files differ)

Modified: trunk/aspect/doc/modules/changes.h
===================================================================
--- trunk/aspect/doc/modules/changes.h	2014-01-28 17:07:39 UTC (rev 2281)
+++ trunk/aspect/doc/modules/changes.h	2014-01-29 14:54:16 UTC (rev 2282)
@@ -8,10 +8,16 @@
 </p>
 
 <ol>
+  <li>New: The manual has a new subsection at the top of the ``Cookbooks''
+  section providing a bit of an outline of how one sets up situations.
+  <br>
+  (Wolfgang Bangerth 2014/01/29)
 
   <li>New: Linear algebra can be done using PETSc instead of Trilinos. For
-  this deal.II needs to be configured with PETSc and the define USE_PETSC
-  needs to be set in global.h. This feature is still experimental.
+  this, deal.II needs to be configured with PETSc and the preprocessor
+  define <code>USE_PETSC</code>
+  needs to be set in the Aspect file <code>include/aspect/global.h</code> before
+  compiling. This feature is still experimental.
   <br>
   (Timo Heister, Ian Rose 2014/01/21)