<commit_before><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>The deal.II Readme</title>
    <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
    <link href="screen.css" rel="StyleSheet"/>
    <meta name="copyright" content="Copyright (C) 1998 - 2014 by the deal.II Authors"/>
    <meta name="date" content="$Date$"/>
    <meta name="svn_id" content="$Id$"/>
    <meta name="keywords" content="deal.II"/>
  </head>

  <body>


    <h4 align="center" style="color: red">
     <strong class="red">Note: Since version 8.0, deal.II uses
       <a href="http://www.cmake.org" target="_top">CMake</a> to
       configure and build. For using the previous build
       system used until deal.II version 7.3, see
       <a href="http://www.dealii.org/7.3.0/readme.html"
       target="_top">the old ReadMe file</a>.
     </strong>
     <br />
    </h4>


<h1>Installation instructions and further information
  on <acronym>deal.II</acronym> </h1>

<div class="toc">
  <ol>
    <li> <a href="#prerequisites">System requirements</a>
      <ol>
	<li> <a href="#supported">Supported platforms</a></li>
	<li> <a href="#additional-software">Additional software requirements</a></li>
      </ol>
    </li>
    <li> <a href="#installation">Installation</a>
      <ol>
	<li>  <a href="#unpacking">Unpacking</a></li>
	<li>  <a href="#configuration">Configuring and building the library</a></li>
	<li>  <a href="#documentation">Configuring and building the documentation</a></li>
	<li>  <a href="#configuration-options">Configuration options</a>
	  <ol>
	    <li> <a href="#optional">Selecting optional behavior</a></li>
	    <li> <a href="#optional-software">Optional interfaces to
		other software packages</a></li>
	    <li> <a href="#conf-details">More information on configuring
		and building the library</a></li>
	  </ol>
	</li>
      </ol>
    </li>
    <li> <a href="#problems">Problems, questions, mailing lists</a></li>
    <li> <a href="#license">License</a></li>
  </ol>
</div>

<a name="prerequisites"/>
<h2>System requirements</h2>

<a name="supported"/>
<h3>Supported platforms</h3>

<p>
  <acronym>deal.II</acronym> is mostly developed on Linux using the
  <a href="http://gcc.gnu.org">GCC</a> compiler. However, it is not
  platform specific and we strive to keep the source code C++ Standard
  compliant.
</p>

<p>
  <acronym>deal.II</acronym> supports at least the following
  platforms:
</p>
<ul>
  <li>GNU/Linux: GCC version 4.1 or later; Clang version 3.0 or later;
  ICC versions 13* or 14*</li>
  <li>Mac OS X: GCC version 4.1 or later; Clang version 3.0 or later.
    Please see the <a href="https://code.google.com/p/dealii/wiki/MacOSX"
    target="_top">deal.II Wiki</a> for installation instructions.</li>
  <li>Windows: Currently, Windows is not supported officially.
    Please have a look at the
    <a href="https://code.google.com/p/dealii/wiki/FrequentlyAskedQuestions#Can_I_use_deal.II_on_a_Windows_platform?">
      FAQ</a> and at the <a href="https://code.google.com/p/dealii/wiki/Windows"
    target="_top">deal.II Wiki</a> for some strategies to use deal.II on
    Windows.</li>
  </li>
</ul>

<p>
  Most other combinations of POSIX-style operating systems and C++
  Standard compliant compilers should also work. <i>If they don't,
  please report it as a bug.</i>
</p>


<a name="additional-software"></a>
<h3>Additional software requirements</h3>

    <p>
      In order to compile and use <acronym>deal.II</acronym>
      you need to have the following programs installed:
    </p>
    <ul>
      <li>
        <a href="http://www.cmake.org/" target="_top">CMake</a> version 2.8.8 or later
      </li>

      <li>
        <a href="http://www.gnu.org/software/make/" target="_top">GNU make</a>, version
        3.78 or later (or any other generator supported by CMake)
      </li>

      <li>
        For generating the documentation:
        <a href="http://www.perl.org/" target="_top">Perl 5.x</a>,
	<a href="http://www.doxygen.org/" target="_top">doxygen</a>
        and <code>dot</code>, which is part of the
	<a href="http://www.graphviz.org" target="_top">GraphViz</a>
        package
      </li>

      <li>
          For debugging programs, we have found that the
	  <a href="http://www.gnu.org/software/gdb/" target="_top">GNU
	    debugger GDB</a> is an invaluable tool. GDB is a text-based tool
	    not always easy to use; <a href="http://www.kdbg.org/"
	    target="_top">kdbg</a>, is one of many graphical user interfaces
	    for it. Most integrated development environments
	    like <a href="http://www.kdevelop.org/" target="_top">kdevelop</a>
	    or <a href="http://eclipse.org/" target="_top">Eclipse</a> have built
	    in debuggers as well.
	</li>

      <li> <p>
        The library generates output in formats readable by
        <a href="http://www.gnuplot.info/" target="_top">GNUPLOT</a>,
	<a href="http://www.generalmeshviewer.com/" target="_top">GMV
 	  (general mesh viewer)</a>,
	<a href="http://www.tecplot.com/" target="_top">Tecplot</a> (ASCII and binary),
        <a href="http://www.vtk.org/"
           target="_top">Visualization Toolkit (Vtk)</a>,
	<a href="http://www.avs.com" target="_top">AVS Explorer</a>,
	<a href="http://www.opendx.org" target="_top">Open DX</a>,
	<a href="http://www.povray.org" target="_top">Povray</a>,
        and directly to Encapsulated Postscript.
	</p>

        <p>
          <code>gnuplot</code>
          and a postscript viewer (for <code>eps</code>) should be
          available almost everywhere. In the last few years, most
          new visualization programs have moved to support
          <code>vtk</code>/<code>vtu</code> format. There are a number
          of excellent programs that can read <code>vtk</code> and
          <code>vtu</code>, such as
          <a href="http://www.llnl.gov/visit/" target="_top">Visit</a>,
          <a href="http://www.paraview.org/" target="_top">ParaView</a>,
	  as well as others. Povray is freely available for almost all
	  platforms. AVS is a commercial program available for most Unix
	  flavors. Tecplot is a commercial program available for Windows
	  and most Unix platforms.
	</p>
	<p>
	  In case you didn't find your favorite graphics format above,
	  adding a new writer to <acronym>deal.II</acronym> is not too
	  difficult, as only a simple intermediate format needs to be
	  converted into output (without references to cells, nodes,
	  types of finite elements, and the like).
	</p>
      </li>
    </ul>

    <a name="installation"></a>
    <h2>Installation</h2>

    <a name="unpacking"></a>
    <h3>Unpacking</h3>

    <p>
      The whole library usually comes as a <code>tar.gz</code> file,
      which is a file archive compressed with gzip. After downloading it,
      unpack it using either
    </p>
<pre>
  gunzip deal.II-X.Y.Z.tar.gz
  tar xf deal.II-X.Y.Z.tar
</pre>
<p>or, if you have GNU tar with</p>
<pre>
  tar -xvf deal.II-X.Y.Z.tar.gz
</pre>

<p><b>Note:</b> You will want to hang on to the source files
  of <acronym>deal.II</acronym> after installation as it makes
  developing much simpler. Consequently, you should do the steps above
  in a permanent directory, not on <code>/tmp</code> as one often does
  when installing software.
</p>

    <a name="configuration"></a>
    <h3>Configuring and building the library</h3>

    <p>
      <acronym>deal.II</acronym> uses the
      <a href="http://www.cmake.org/" target="_top">CMake</a>
      integrated configuration and build system. Unpacking will create a
      subdirectory <tt>deal.II/</tt> in the current directory. Then do the
      following steps:</p>

<pre>
  mkdir build
  cd build
  cmake -DCMAKE_INSTALL_PREFIX=/path/to/install/dir ../deal.II
  make install
  make test
</pre>

<p>
  These steps compile, link, install the deal.II library, and run a few
  consistency checks. The whole process should take between a few minutes
  and an hour, depending on your machine.
</p>

    <p>
      <b>Note:</b></p>
      <ul>
	<li> <code>/path/to/install/dir</code> is the directory which deal.II
	  should be installed into. This can be a directory in your home
	  directory (e.g., <code>~/bin/deal.II</code>) or a directory
	  such as <code>/usr/local</code> if you have root privileges.
	  Another option is to use something like <code>`pwd`/../installed/</code> (note the
	  backticks). Make sure the installation directory is not the same
	  as the location where you unpacked <tt>deal.II/</tt>.
	</li>

	<li> If your machine has multiple processors, use <code>make
	  -jN</code> in the last step, where <code>N</code> is the
	  number of simultaneous build processes you want <code>make</code>
	  to use at any given time. Allowing <code>make</code> to use
	  more simultaneous build processes (assuming you have that many
	  processor cores) will greatly lower the build time.
	</li>

	<li> If you do not intend to modify the <acronym>deal.II</acronym>
	  sources and recompile things, then you can remove
	  the <code>build/</code> directory after the last step.
	</li>

	<li> In principle, after installing <acronym>deal.II</acronym>, you
	  can remove the source directory as well (i.e., the directory into
	  which <code>tar</code> unpacked the file you downloaded) since
	  projects using deal.II should only need files that have been
	  installed. However, you will find it convenient to keep the source
	  files around anyway, for one reason: When
	  debugging you often end up with assertions for which you'd like to
          see the place in the library's source files that triggered it.
	</li>

	<li> The <acronym>deal.II</acronym> <code>CMake</code> system can accept a
	  significant number of configuration parameters. See the
	  discussion <a href="#configuration-options">below</a>.
	</li>

	<li> If you are changing part of the <acronym>deal.II</acronym>
	code itself, you can re-compile the library using only the
	last two commands above in the previously created build
	directory. It is also possible to change the configuration used
	in this directory by calling <code>cmake</code> a second time,
	possibly with different arguments.
	However, this sometimes leads to surprising results and you may
	not get exactly what you were hoping for. For more information,
	see <a href="users/cmake.html">here</a>.
	</li>
      </ul>

    <p>
      The commands above build and install the <acronym>deal.II</acronym>
      libraries in two variants:
    </p>
    <ul>
      <li>
	<p><i>Debug mode</i>: This version of the
	  library is compiled with compiler flags so
	  that the library contains information that can be used by debuggers.
	</p>

	<p>
	  In addition, this library contains a great number of safety
	  checks on most arguments of all functions you could possibly call.
	  These assertions have proven to be an
	  invaluable means to finding programming bugs since they will
	  almost always abort your program if something goes wrong. In our
	  experience, more than ninety per cent of all errors are invalid
	  parameters (such as vectors having the wrong size, etc.) and they
	  are usually found almost instantaneously, displaying the file
	  name and line number of where the problem occurred.
	</p>
	</li>

	<li> <i>Optimized mode</i>: You will want to link with this version of
	    the library once you know that your program is working as
	    expected. It does not contain the safety checks any more
	    and is compiled with aggressive compiler optimizations. The
	    resulting executables are smaller and will run between 2 and 10
	    times faster than the debug executables.
	</li>
      </ul>

    <p>
      At this point, you have generated everything necessary to write
      programs based on <acronym>deal.II</acronym>. If you are new to
      <acronym>deal.II</acronym>, you may want to continue with the
      <a href="doxygen/deal.II/Tutorial.html" target="_top">tutorial</a>.
    </p>

    <a name="documentation"></a>
    <h3>Configuring and building the documentation</h3>

    <p>
      All the documentation about the version that you downloaded and that can
      be found at the <a href="http://www.dealii.org/" target="_top">
      http://www.dealii.org/</a> domain  can also be generated locally. To do
      so, invoke <code>cmake</code> in the build instructions above as follows:
    </p>

<pre>
  cmake -DDEAL_II_COMPONENT_DOCUMENTATION=ON -DCMAKE_INSTALL_PREFIX=/path/install/dir ../deal.II
</pre>

<p>
  For this to succeed, you will need <a href="http://www.perl.org/"
					target="_top">Perl 5.x</a>,
  <a href="http://www.doxygen.org/" target="_top">doxygen</a>
  and <code>dot</code> (which is part of
  the <a href="http://www.graphviz.org" target="_top">GraphViz</a>
  package) to be installed.
</p>

    <p>
      Upon calling <code>make</code> and <code>make install</code>, this will
      install both this readme, other installation instructions, as well as the
      <a href="doxygen/deal.II/index.html" target="_top">manual that documents
      all functions and classes</a> as well as
      the <a href="doxygen/deal.II/Tutorial.html" target="_top"> tutorial
      of well-documented example programs</a> (the "steps").
    </p>

    <p>
      <b>Note:</b> Generating this documentation can take a <i>really long
      time</i> &mdash; running doxygen through our hundreds of thousands of
      lines of code can take 15-20 minutes even on a fast machine during which
      you will not get any output from <code>make</code>.
    </p>


    <a name="configuration-options"></a>
    <h3>Configuration options</h3>

    <p>
      <acronym>deal.II</acronym> has a large number of optional interfaces to
      other libraries. <b>By default, <code>cmake</code> will automatically
      enable support  for all external libraries it can find in default
      paths.</b>
      However, this behavior can be changed using command line switches to
      the initial call to <code>cmake</code>. A detailed description
      can be found here: <a href="users/cmake.html">Detailed build system description</a>.
    </p>

    <p>
      In the following, let us summarize the most common configuration
      options.
    </p>

    <a name="optional"/>
      <h4>Selecting optional behavior</h4>

    <ul>
      <li>
	<p>
	  <i>Threading</i>: By default, deal.II supports parallelism between
	  multiple cores on the same machine using threads and a
	  task-based model built on the
          <a href="http://threadingbuildingblocks.org/"
	  target="_top">Threading Building Blocks</a>. You can switch
	  threading off by passing the <code>-DDEAL_II_WITH_THREADS=OFF</code>
	  argument to <code>cmake</code>.
	</p>
      </li>

      <li>
	<p>
	  <i>MPI</i>: To enable parallel computations beyond a single node
	  using the <a href="http://mpi-forum.org/" target="_top">Message
	  Passing Interface (MPI)</a>, pass the
	  <code>-DDEAL_II_WITH_MPI=ON</code> argument
	  to <code>cmake</code>. If <code>cmake</code> found MPI but you
	  specifically do not want to use it, then
	  pass <code>-DDEAL_II_WITH_MPI=OFF</code>.
	</p>
      </li>

      <li>
        <p>
          <i>mesh_converter</i>: If you wish to compile and install the
          <code>mesh_converter</code> tool discussed in the documentation
	  of the <code>GridIn</code> class, specify
          <code>-DDEAL_II_COMPONENT_MESH_CONVERTER=ON</code>. (This is in fact
          the default.)
	</p>

        <p>
          <i>parameter_gui</i>: If you wish to compile and install the
          <code>parameter_gui</code> tool discussed in the documentation
	  of the <code>ParameterHandler</code> class, specify
          <code>-DDEAL_II_COMPONENT_PARAMETER_GUI=ON</code>. Beware of the
          fact that <code>parameter_gui</code> needs development packages for Qt.
	</p>
      </li>

      <li>
  <p>
    <i>64bit indices</i>: By default, deal.II use unsigned int (32bit)
    indices for degrees of freedom, using
    the <code>types::global_dof_index</code> type. This limits the number of
    unknowns to approximately four
    billions. If larger problem must be solved, pass the
    <code>-DDEAL_II_WITH_64BIT_INDICES=ON</code> argument to
    <code>cmake</code>. You will not be able to solve problems of this size on
    a single machine, but only when using clusters of computers and linear
    algebra packages PETSc or Trilinos.
    To use this option with PETSc, PESTc must be compiled
    with the option <code>--with-64-bit-indices</code>. To use this option
    with Trilinos, Trilinos 11.2 or later is needed (there is a bug in
    Trilinos 11.0 that prevents the use of 64bit indices).
  </p>
      </li>
    </ul>



    <a name="optional-software"/>
    <h4>Optional interfaces to other software packages</h4>

    <p>
      When configuring interfacing to external libraries, the
      <code>cmake</code> script by default tries to find all of these
      libraries in a number of standard locations on your file system.
      For <i>optional</i> interfaces, it gives up if the library is not
      found and <acronym>deal.II</acronym> will be built without support
      for them.
      However, there is one interface that we <i>need</i> to have: <a
      href="http://www.boost.org/" target="_top">BOOST</a>. If it is not
      found externally <code>cmake</code> will resort to the bundled boost
      version that is part of the <acronym>deal.II</acronym> tar file.
    </p>

    <p>
      The following paragraphs describe how the interfaces to the
      various packages, <acronym>deal.II</acronym> interacts with,
      can be configured.
    </p>

    <p><b>Notes:</b></p>
      <ul>
        <li>
          <b>The majority of libraries mentioned below should be readily
          packaged by most Linux distributions. Usually you need to
          install a <i>development</i> version of a library package,
          e.g. ending in <code>-dev</code> or <code>-devel</code>.
          After that <code>cmake</code> will automatically find the
          library and use it.</b>
      </li>
        <li>
          Configuring the interface to a self compiled package,
          say <code>foo</code> can usually be done by specifying
          <code>-DFOO_DIR=/path/to/foo</code>.  Alternatively, you can
          set <code>FOO_DIR</code> as an environment variable in your
          <code>.bashrc</code> or <code>.cshrc</code> file so that
          you do not have to enter this argument again the next time
          you invoke <code>cmake</code> in a fresh build directory.
          Any value passed on the command line wins over a value that
          may be found in an environment variable.
      </li>
        <li>
          To explicitly enable or disable support for
          a library <code>foo</code> use the argument
          <code>-DDEAL_II_WITH_FOO=ON</code> resp.
          <code>-DDEAL_II_WITH_FOO=OFF</code> for <code>cmake</code>.
      </li>
    </ul>

    <dl>
      <dt><a name="ARPACK"/>
	<a href="http://www.caam.rice.edu/software/ARPACK/" target="_top">ARPACK</a></dt>
      <dd>
	<p>
	  <a href="http://www.caam.rice.edu/software/ARPACK/"
	     target="_top">ARPACK</a> is a library for computing large
          scale eigenvalue problems.
          <a href="http://www.caam.rice.edu/software/ARPACK/" target="_top">ARPACK</a>
          should be readily packaged by most Linux distributions.
          (Don't forget to install a development version of the library).
          To use a self compiled version, specify
          <code>-DARPACK_DIR=/path/to/arpack</code> on the command line.

	  For a detailed description on how to compile ARPACK and linking with deal.II, see
	  <a href="external-libs/arpack.html" target="body">this page</a>.
	</p>
      </dd>

      <dt>
	<a name="blas"></a>
	<a href="http://www.netlib.org/blas/" target="_top">BLAS</a>,
	<a href="http://www.netlib.org/lapack/" target="_top">LAPACK</a>
      </dt>
      <dd>
	<p>
	  <a href="http://www.netlib.org/blas/" target="_top">BLAS</a>
	  (the <i>Basic Linear Algebra Subroutines</i>) and
	  <a href="http://www.netlib.org/lapack/" target="_top">LAPACK</a>
	  (<i>Linear Algebra Package</i>) are two packages that support
	  low-level linear algebra operations on vectors and dense
          matrices.
          Both libraries should be packaged by almost all Linux
          distributions and found automatically whenever available.
          (You might have to install development versions of the libraries
          for <acronym>deal.II</acronym> being able to use them).
          For details on how to set up <acronym>deal.II</acronym> with a
          non standard BLAS/LAPACK implementation, see the
	  <a href="users/cmake.html#advanced">advanced
            setup</a> section in the CMake ReadME.
	</p>
      </dd>

      <dt>
	<a name="functionparser"></a>
	<a href="http://warp.povusers.org/FunctionParser/">FunctionParser</a>
      </dt>
      <dd>
	<p>
	  <a href="http://warp.povusers.org/FunctionParser/">FunctionParser</a>
	  is a library that allows to enter functions in text form and have them
	  interpreted at run time. This is particularly useful in input
	  parameter files. <code>cmake</code> will usually find the version of
	  this library that comes bundled with <acronym>deal.II</acronym>.
	  The function parser library has its own license; if you want to use
	  it with deal.II, please read it and make sure that you agree with it.
	  You can find it
	  <a href="http://warp.povusers.org/FunctionParser/">here</a>. We
	  include FunctionParser in the deal.II distributions courtesy of its author,
	  <a href="http://iki.fi/warp/"><NAME></a>.
	</p>
      </dd>


      <dt><a name="HDF5"></a><a href="http://www.hdfgroup.org/HDF5/">HDF5</a></dt>
      <dd>
	<p>
	  The <a href="http://www.hdfgroup.org/HDF5/">HDF5 library</a>
	  provides graphical output capabilities in <code>HDF5/XDMF</code>
	  format.
	  <a href="http://www.hdfgroup.org/HDF5/">HDF5</a> should be
	  readily packaged by most Linux distributions.  (Don't forget
          to install a development version of the library).
	  To use a self compiled version, specify
	  <code>-DHDF5_DIR=/path/to/hdf5</code> on the command line.
	</p>
      </dd>


      <dt><a name="metis"></a><a href="http://glaros.dtc.umn.edu/gkhome/metis/metis/overview"
	     target="_top">METIS</a></dt>
      <dd>
	<p>
	  <a href="http://glaros.dtc.umn.edu/gkhome/metis/metis/overview"
		  target="_top">METIS</a> is a library that
	  provides various methods to partition
	  graphs. <acronym>deal.II</acronym> uses it in programs like the
	  step-17 tutorial to partition a mesh for parallel computing.
	  To use a self compiled version, specify
	  <code>-DMETIS_DIR=/path/to/metis</code> on the command line.
	  <acronym>deal.II</acronym> supports METIS 5 and later.
	</p>

	<p>
	  <b>Note:</b> A more modern way to support parallel computations is
	  shown in the step-40 tutorial program and is based on
	  the <code>p4est</code> library instead of METIS. See below on
	  installing <code>p4est</code>.
	</p>
      </dd>


      <dt><a name="mumps"></a><a href="http://mumps.enseeiht.fr" target="_top">MUMPS</a></dt>
      <dd>
	<p>
	  <a href="http://mumps.enseeiht.fr" target="_top">MUMPS</a>
	  (MUltifrontal Massively Parallel sparse direct Solver)
	  is a sparse direct solver that can factorize matrices within or
	  across nodes of a cluster.
	  <a href="http://mumps.enseeiht.fr" target="_top">MUMPS</a>
          should be readily packaged by most Linux distributions.
          (Don't forget to install a development version of the library).
          To use a self compiled version, provide the
	  <code>-DMUMPS_DIR=/path/to/mumps</code> argument to <code>cmake</code>.
	  For a detailed description on how to compile MUMPS (and
	  some dependencies) and linking with deal.II, see
	  <a href="external-libs/mumps.html" target="body">this page</a>.
	</p>
      </dd>


      <dt><a name="netcdf"></a><a href="http://www.unidata.ucar.edu/software/netcdf/" target="_top">NetCDF</a></dt>
      <dd>
	<a href="http://www.unidata.ucar.edu/software/netcdf/"
	   target="_top">NetCDF</a> is a library that provides services for
	reading and writing mesh data (and many other
	things). <acronym>deal.II</acronym> can use it to read meshes via
        one of the functions of the <code>GridIn</code> class.
	<a href="http://www.unidata.ucar.edu/software/netcdf/"
           target="_top">NetCDF</a> should be readily packaged by most
        Linux distributions. (Don't forget to install a development
	version of the library). To use a self compiled version, pass
	<code>-DNETCDF_DIR=/path/to/netcdf</code> to <code>cmake</code>.
      </dd>


      <dt><a name="p4est"></a><a href="http://www.p4est.org/" target="_top">p4est</a></dt>
      <dd>
	<p>
	  <a href="http://www.p4est.org/" target="_top">p4est</a>
	  is a library that <acronym>deal.II</acronym> uses to
	  distribute very large meshes across multiple processors (think
	  meshes with a billion cells on 10,000 processors). Using and
	  installing p4est is discussed <a href="external-libs/p4est.html"
					   target="body">here</a>.
	  To use a self compiled version, pass the argument
	  <code>-DP4EST_DIR=/path/to/p4est</code> to the
	  <code>cmake</code> command.
	</p>
      </dd>


      <dt><a name="petsc"></a><a href="http://www.mcs.anl.gov/petsc/"
		 target="_top">PETSc</a></dt>
      <dd>
	<p>
	  <a href="http://www.mcs.anl.gov/petsc/" target="_top">PETSc</a> is a
	  library that supports parallel linear algebra and many other things.

	  <a href="http://www.mcs.anl.gov/petsc/" target="_top">PETSc</a>
	  is already packaged by some Linux distributions and should be
	  found automatically if present. (Don't forget to install a
	  development version of the library).  To use a self compiled
	  version of PETSc, add <code>-DPETSC_DIR=/path/to/petsc
	  -DPETSC_ARCH=architecture</code> to the argument list for
	  <code>cmake</code>. The values for these arguments must be
	  the same as those specified when building PETSc.
	</p>

	<p>
	  To disable the PETSc interfaces in cases where <code>cmake</code>
	  automatically finds it, use <code>-DDEAL_II_WITH_PETSC=OFF</code>
	  More information on configuring and building PETSc can be
          found <a href="external-libs/petsc.html" target="body">here</a>.
	</p>
      </dd>


      <dt><a name="slepc"></a><a href="http://www.grycap.upv.es/slepc/" target="_top">SLEPc</a></dt>
      <dd>
	<p>
	  <a href="http://www.grycap.upv.es/slepc/"
	  target="_top">SLEPc</a> is a library for eigenvalue
	  computations that builds on PETSc. Its configuration works
	  just like that for PETSc, except that the variable to set
	  is <code>SLEPC_DIR</code>.  For the interface with SLEPc to
	  work, <acronym>deal.II</acronym>'s PETSc interface must also
	  be configured correctly (see above).
	</p>

	<p>
	  To disable the SLEPc interfaces in cases where <code>cmake</code>
	  automatically finds it, use <code>-DDEAL_II_WITH_PETSC=OFF</code>
	  More information on configuring and building SLEPc can be
          found <a href="external-libs/slepc.html" target="body">here</a>.
	</p>
      </dd>


      <dt><a name="tbb"></a><a href="http://www.threadingbuildingblocks.org/"
	     target="_top">Threading Building Blocks (TBB)</a></dt>
      <dd>
	<p>
	  The <a href="http://www.threadingbuildingblocks.org/"
	     target="_top">Threading Building Blocks (TBB)</a>
	  is a library that provides advanced services for using multiple
	  processor cores on a single machine and is used
	  in <acronym>deal.II</acronym> to parallelize many operations. If not
	  found in a system-wide location, <code>cmake</code> will
	  resort to the version bundled as part of
	  the <acronym>deal.II</acronym> download. It is always enabled unless
	  threads are explicitly disabled, see <a href="#optional">above</a>.
	</p>
      </dd>


      <dt><a name="trilinos"></a><a href="http://trilinos.sandia.gov" target="_top">Trilinos</a></dt>
      <dd>
	<p>
	  <a href="http://trilinos.sandia.gov" target="_top">Trilinos</a> is a
	  library for parallel linear algebra and all sorts of other things as
	  well.

	  To interface with a self compiled version of <a
	  href="http://trilinos.sandia.gov" target="_top">Trilinos</a>
	  add <code>-DTRILINOS_DIR=/path/to/trilinos</code> to the
	  argument list for <code>cmake</code>.  Alternatively, you can
	  also set an environment variable <code>TRILINOS_DIR</code>
	  and <code>cmake</code> will pick up this path.
	</p>

	<p>
	  To disable the Trilinos interfaces in cases where
	  <code>cmake</code> automatically finds it, use
	  <code>-DDEAL_II_WITH_TRILINOS=OFF</code> More details about
	  compatibility and configuration can be found
          <a href="external-libs/trilinos.html" target="body">here</a>.
	</p>
      </dd>


      <dt><a name="umfpack"></a><a href="http://www.cise.ufl.edu/research/sparse/umfpack/"
	     target="_top">UMFPACK</a></dt>
      <dd>
	<p>
	  <a href="http://www.cise.ufl.edu/research/sparse/umfpack/"
	     target="_top">UMFPACK</a> is a sparse direct solver that we often
	  use in prototype codes where the goal is to simply get a linear
          system solved robustly.
	  The interface will be enabled by default, either using a version
	  installed on your system of using a version that comes bundled
	  with <acronym>deal.II</acronym>.
	  It can be disabled explicitly by using the
	  <code>-DDEAL_II_WITH_UMFPACK=OFF</code> argument.
	  To use a self compiled version, pass the argument
	  <code>-DUMFPACK_DIR=/path/to/umfpack</code> to the
	  <code>cmake</code> command.
	</p>

	<p>
	  UMFPACK has its own license. To use it with deal.II, please
	  read it and make sure that you agree with it. You can find
	  the license of UMFPACK
          <a href="http://www.cise.ufl.edu/research/sparse/umfpack/">here</a>.
	  We include UMFPACK in the deal.II distributions courtesy of
	  its author, <a href="http://www.cise.ufl.edu/~davis/"><NAME></a>.
	</p>
      </dd>
    </dl>


    <a name="conf-details"/>
    <h4>More information on configuring and building the library</h4>

    <p>
      The <acronym>deal.II</acronym> <code>cmake</code> system allows far
      greater control over what exactly is configured or built than just the
      outline above. If you want to learn more about this, take a look
      <a href="users/cmake.html">here</a>. You might also be interested in
      <a href="users/cmakelists.html">CMake for user projects</a> or 
      <a href="developers/cmake-internals.html">build system internals</a>.
    </p>


    <a name="problems"></a>
    <h2>Problems, questions, mailing lists</h2>

    <p>
      Some information beyond what is covered in the documentation of
      the library may be found on the
      <a href="http://www.dealii.org" target="_top"><acronym>deal.II</acronym>
	homepage</a>, or in the
      <a href="http://code.google.com/p/dealii/wiki/FrequentlyAskedQuestions" target="_top">Frequently Asked Questions</a> section.
      If you don't find what you're looking for,
      feel free to ask on our
      <a href="http://www.dealii.org/mail.html" target="body">mailing list</a>.
    </p>

    <p>
      We are interested in any feedback, whether positive or negative,
      in order to determine the directions of future work on the
      library. We are also very much interested in incorporating any
      work and bug fixes by third parties into the library. Of course,
      you will be credited for this on
      the <a href="http://www.dealii.org/authors.html" target="_top">authors page</a>.
    </p>

    <p>
      Our institutes are evaluated at regular intervals. Consequently,
      we are interested in documenting the use of the programs and
      libraries we create. To this end, we collect
      publications with results obtained using <acronym>deal.II</acronym>. Please
      let us know if you have publications that we can add
      <a href="publications/index.html">to this page</a>.
    </p>

    <a name="license"></a>
    <h2>License</h2>

    <p>
      The deal.II library is free software; you can use it, redistribute
      it, and/or modify it under the terms of the
      <a href="http://www.gnu.org/licenses/lgpl-2.1.html">GNU Lesser General
      Public License</a> (LGPL) as published by the Free Software
      Foundation; either version 2.1 of the License, or (at your option)
      any later version.
    </p>
    <p>
      This allows you to use the library free of charge for private,
      academic, or commercial use (under the terms of the LGPL v2.1 or
      later). You are guaranteed full access to the source code and are
      encouraged to help in the further development of the library. Follow
      <a href="license.html" target="body">this link</a> for detailed
      information.
    </p>
    <p>
      Please note:</p>
      <ul>
	<li>
          Detailed license information can be found following
          <a href="license.html" target="body">this link</a>.
	</li>
	<li>
          <b>As a contributor to this project, you agree that any of your
          contributions be licensed under the same terms and conditions as
          the license of the deal.II project granted to you.</b>
	</li>
        <li>
          We, <a href="http://www.dealii.org/authors.html" target="_top">the deal.II Authors</a>, do not require
          copyright assignments for contributions. This means that the
          copyright for code contributions in the deal.II project is held by
          its respective contributors who have each agreed to release their
          contributed code under the terms of the LGPL v2.1 or later.
	</li>
	<li>
          In addition to the terms imposed by the LGPL (version 2.1 or
          later), we ask for the courtesy that scientific publications
          presenting results obtained with this libraries acknowledge its
          use. Please cite one of the papers referenced
          <a href="publications/index.html">here</a>.
	</li>
	<li>
          <acronym>deal.II</acronym> can interface with a number of <a
            href="#optional-software">other packages</a> that you either
          have to install yourself. They are, of course, covered by their
          own licenses. In addition, deal.II comes bundled with copies of
          <a href="http://www.cise.ufl.edu/research/sparse/umfpack/"
            target="_top">UMFPACK</a>,
          <a href="http://threadingbuildingblocks.org/"
            target="_top">Threading Building Blocks</a>,
          <a href="http://www.boost.org/" target="_top">BOOST</a> and
          <a href="http://warp.povusers.org/FunctionParser/"
            target="_top">FunctionParser</a>, courtesy of their authors.
          These are also covered by their own licenses; please refer to
          their webpages for more information.
	</li>
      </ul>

  <hr />
  <address>
    <a href="http://www.dealii.org/authors.html" target="_top">The deal.II Authors</a>
    $Date$
  </address>
  <div class="right">
    <a href="http://validator.w3.org/check?uri=referer" target="_top">
      <img style="border:0" src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
    <a href="http://jigsaw.w3.org/css-validator/check/referer" target="_top">
      <img style="border:0;width:88px;height:31px" src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
  </div>

  </body>
</html>
<commit_msg>Remove a note that only pertains to versions that are by now older than a year.<commit_after><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>The deal.II Readme</title>
    <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
    <link href="screen.css" rel="StyleSheet"/>
    <meta name="copyright" content="Copyright (C) 1998 - 2014 by the deal.II Authors"/>
    <meta name="date" content="$Date$"/>
    <meta name="svn_id" content="$Id$"/>
    <meta name="keywords" content="deal.II"/>
  </head>

  <body>



<h1>Installation instructions and further information
  on <acronym>deal.II</acronym> </h1>

<div class="toc">
  <ol>
    <li> <a href="#prerequisites">System requirements</a>
      <ol>
	<li> <a href="#supported">Supported platforms</a></li>
	<li> <a href="#additional-software">Additional software requirements</a></li>
      </ol>
    </li>
    <li> <a href="#installation">Installation</a>
      <ol>
	<li>  <a href="#unpacking">Unpacking</a></li>
	<li>  <a href="#configuration">Configuring and building the library</a></li>
	<li>  <a href="#documentation">Configuring and building the documentation</a></li>
	<li>  <a href="#configuration-options">Configuration options</a>
	  <ol>
	    <li> <a href="#optional">Selecting optional behavior</a></li>
	    <li> <a href="#optional-software">Optional interfaces to
		other software packages</a></li>
	    <li> <a href="#conf-details">More information on configuring
		and building the library</a></li>
	  </ol>
	</li>
      </ol>
    </li>
    <li> <a href="#problems">Problems, questions, mailing lists</a></li>
    <li> <a href="#license">License</a></li>
  </ol>
</div>

<a name="prerequisites"/>
<h2>System requirements</h2>

<a name="supported"/>
<h3>Supported platforms</h3>

<p>
  <acronym>deal.II</acronym> is mostly developed on Linux using the
  <a href="http://gcc.gnu.org">GCC</a> compiler. However, it is not
  platform specific and we strive to keep the source code C++ Standard
  compliant.
</p>

<p>
  <acronym>deal.II</acronym> supports at least the following
  platforms:
</p>
<ul>
  <li>GNU/Linux: GCC version 4.1 or later; Clang version 3.0 or later;
  ICC versions 13* or 14*</li>
  <li>Mac OS X: GCC version 4.1 or later; Clang version 3.0 or later.
    Please see the <a href="https://code.google.com/p/dealii/wiki/MacOSX"
    target="_top">deal.II Wiki</a> for installation instructions.</li>
  <li>Windows: Currently, Windows is not supported officially.
    Please have a look at the
    <a href="https://code.google.com/p/dealii/wiki/FrequentlyAskedQuestions#Can_I_use_deal.II_on_a_Windows_platform?">
      FAQ</a> and at the <a href="https://code.google.com/p/dealii/wiki/Windows"
    target="_top">deal.II Wiki</a> for some strategies to use deal.II on
    Windows.</li>
  </li>
</ul>

<p>
  Most other combinations of POSIX-style operating systems and C++
  Standard compliant compilers should also work. <i>If they don't,
  please report it as a bug.</i>
</p>


<a name="additional-software"></a>
<h3>Additional software requirements</h3>

    <p>
      In order to compile and use <acronym>deal.II</acronym>
      you need to have the following programs installed:
    </p>
    <ul>
      <li>
        <a href="http://www.cmake.org/" target="_top">CMake</a> version 2.8.8 or later
      </li>

      <li>
        <a href="http://www.gnu.org/software/make/" target="_top">GNU make</a>, version
        3.78 or later (or any other generator supported by CMake)
      </li>

      <li>
        For generating the documentation:
        <a href="http://www.perl.org/" target="_top">Perl 5.x</a>,
	<a href="http://www.doxygen.org/" target="_top">doxygen</a>
        and <code>dot</code>, which is part of the
	<a href="http://www.graphviz.org" target="_top">GraphViz</a>
        package
      </li>

      <li>
          For debugging programs, we have found that the
	  <a href="http://www.gnu.org/software/gdb/" target="_top">GNU
	    debugger GDB</a> is an invaluable tool. GDB is a text-based tool
	    not always easy to use; <a href="http://www.kdbg.org/"
	    target="_top">kdbg</a>, is one of many graphical user interfaces
	    for it. Most integrated development environments
	    like <a href="http://www.kdevelop.org/" target="_top">kdevelop</a>
	    or <a href="http://eclipse.org/" target="_top">Eclipse</a> have built
	    in debuggers as well.
	</li>

      <li> <p>
        The library generates output in formats readable by
        <a href="http://www.gnuplot.info/" target="_top">GNUPLOT</a>,
	<a href="http://www.generalmeshviewer.com/" target="_top">GMV
 	  (general mesh viewer)</a>,
	<a href="http://www.tecplot.com/" target="_top">Tecplot</a> (ASCII and binary),
        <a href="http://www.vtk.org/"
           target="_top">Visualization Toolkit (Vtk)</a>,
	<a href="http://www.avs.com" target="_top">AVS Explorer</a>,
	<a href="http://www.opendx.org" target="_top">Open DX</a>,
	<a href="http://www.povray.org" target="_top">Povray</a>,
        and directly to Encapsulated Postscript.
	</p>

        <p>
          <code>gnuplot</code>
          and a postscript viewer (for <code>eps</code>) should be
          available almost everywhere. In the last few years, most
          new visualization programs have moved to support
          <code>vtk</code>/<code>vtu</code> format. There are a number
          of excellent programs that can read <code>vtk</code> and
          <code>vtu</code>, such as
          <a href="http://www.llnl.gov/visit/" target="_top">Visit</a>,
          <a href="http://www.paraview.org/" target="_top">ParaView</a>,
	  as well as others. Povray is freely available for almost all
	  platforms. AVS is a commercial program available for most Unix
	  flavors. Tecplot is a commercial program available for Windows
	  and most Unix platforms.
	</p>
	<p>
	  In case you didn't find your favorite graphics format above,
	  adding a new writer to <acronym>deal.II</acronym> is not too
	  difficult, as only a simple intermediate format needs to be
	  converted into output (without references to cells, nodes,
	  types of finite elements, and the like).
	</p>
      </li>
    </ul>

    <a name="installation"></a>
    <h2>Installation</h2>

    <a name="unpacking"></a>
    <h3>Unpacking</h3>

    <p>
      The whole library usually comes as a <code>tar.gz</code> file,
      which is a file archive compressed with gzip. After downloading it,
      unpack it using either
    </p>
<pre>
  gunzip deal.II-X.Y.Z.tar.gz
  tar xf deal.II-X.Y.Z.tar
</pre>
<p>or, if you have GNU tar with</p>
<pre>
  tar -xvf deal.II-X.Y.Z.tar.gz
</pre>

<p><b>Note:</b> You will want to hang on to the source files
  of <acronym>deal.II</acronym> after installation as it makes
  developing much simpler. Consequently, you should do the steps above
  in a permanent directory, not on <code>/tmp</code> as one often does
  when installing software.
</p>

    <a name="configuration"></a>
    <h3>Configuring and building the library</h3>

    <p>
      <acronym>deal.II</acronym> uses the
      <a href="http://www.cmake.org/" target="_top">CMake</a>
      integrated configuration and build system. Unpacking will create a
      subdirectory <tt>deal.II/</tt> in the current directory. Then do the
      following steps:</p>

<pre>
  mkdir build
  cd build
  cmake -DCMAKE_INSTALL_PREFIX=/path/to/install/dir ../deal.II
  make install
  make test
</pre>

<p>
  These steps compile, link, install the deal.II library, and run a few
  consistency checks. The whole process should take between a few minutes
  and an hour, depending on your machine.
</p>

    <p>
      <b>Note:</b></p>
      <ul>
	<li> <code>/path/to/install/dir</code> is the directory which deal.II
	  should be installed into. This can be a directory in your home
	  directory (e.g., <code>~/bin/deal.II</code>) or a directory
	  such as <code>/usr/local</code> if you have root privileges.
	  Another option is to use something like <code>`pwd`/../installed/</code> (note the
	  backticks). Make sure the installation directory is not the same
	  as the location where you unpacked <tt>deal.II/</tt>.
	</li>

	<li> If your machine has multiple processors, use <code>make
	  -jN</code> in the last step, where <code>N</code> is the
	  number of simultaneous build processes you want <code>make</code>
	  to use at any given time. Allowing <code>make</code> to use
	  more simultaneous build processes (assuming you have that many
	  processor cores) will greatly lower the build time.
	</li>

	<li> If you do not intend to modify the <acronym>deal.II</acronym>
	  sources and recompile things, then you can remove
	  the <code>build/</code> directory after the last step.
	</li>

	<li> In principle, after installing <acronym>deal.II</acronym>, you
	  can remove the source directory as well (i.e., the directory into
	  which <code>tar</code> unpacked the file you downloaded) since
	  projects using deal.II should only need files that have been
	  installed. However, you will find it convenient to keep the source
	  files around anyway, for one reason: When
	  debugging you often end up with assertions for which you'd like to
          see the place in the library's source files that triggered it.
	</li>

	<li> The <acronym>deal.II</acronym> <code>CMake</code> system can accept a
	  significant number of configuration parameters. See the
	  discussion <a href="#configuration-options">below</a>.
	</li>

	<li> If you are changing part of the <acronym>deal.II</acronym>
	code itself, you can re-compile the library using only the
	last two commands above in the previously created build
	directory. It is also possible to change the configuration used
	in this directory by calling <code>cmake</code> a second time,
	possibly with different arguments.
	However, this sometimes leads to surprising results and you may
	not get exactly what you were hoping for. For more information,
	see <a href="users/cmake.html">here</a>.
	</li>
      </ul>

    <p>
      The commands above build and install the <acronym>deal.II</acronym>
      libraries in two variants:
    </p>
    <ul>
      <li>
	<p><i>Debug mode</i>: This version of the
	  library is compiled with compiler flags so
	  that the library contains information that can be used by debuggers.
	</p>

	<p>
	  In addition, this library contains a great number of safety
	  checks on most arguments of all functions you could possibly call.
	  These assertions have proven to be an
	  invaluable means to finding programming bugs since they will
	  almost always abort your program if something goes wrong. In our
	  experience, more than ninety per cent of all errors are invalid
	  parameters (such as vectors having the wrong size, etc.) and they
	  are usually found almost instantaneously, displaying the file
	  name and line number of where the problem occurred.
	</p>
	</li>

	<li> <i>Optimized mode</i>: You will want to link with this version of
	    the library once you know that your program is working as
	    expected. It does not contain the safety checks any more
	    and is compiled with aggressive compiler optimizations. The
	    resulting executables are smaller and will run between 2 and 10
	    times faster than the debug executables.
	</li>
      </ul>

    <p>
      At this point, you have generated everything necessary to write
      programs based on <acronym>deal.II</acronym>. If you are new to
      <acronym>deal.II</acronym>, you may want to continue with the
      <a href="doxygen/deal.II/Tutorial.html" target="_top">tutorial</a>.
    </p>

    <a name="documentation"></a>
    <h3>Configuring and building the documentation</h3>

    <p>
      All the documentation about the version that you downloaded and that can
      be found at the <a href="http://www.dealii.org/" target="_top">
      http://www.dealii.org/</a> domain  can also be generated locally. To do
      so, invoke <code>cmake</code> in the build instructions above as follows:
    </p>

<pre>
  cmake -DDEAL_II_COMPONENT_DOCUMENTATION=ON -DCMAKE_INSTALL_PREFIX=/path/install/dir ../deal.II
</pre>

<p>
  For this to succeed, you will need <a href="http://www.perl.org/"
					target="_top">Perl 5.x</a>,
  <a href="http://www.doxygen.org/" target="_top">doxygen</a>
  and <code>dot</code> (which is part of
  the <a href="http://www.graphviz.org" target="_top">GraphViz</a>
  package) to be installed.
</p>

    <p>
      Upon calling <code>make</code> and <code>make install</code>, this will
      install both this readme, other installation instructions, as well as the
      <a href="doxygen/deal.II/index.html" target="_top">manual that documents
      all functions and classes</a> as well as
      the <a href="doxygen/deal.II/Tutorial.html" target="_top"> tutorial
      of well-documented example programs</a> (the "steps").
    </p>

    <p>
      <b>Note:</b> Generating this documentation can take a <i>really long
      time</i> &mdash; running doxygen through our hundreds of thousands of
      lines of code can take 15-20 minutes even on a fast machine during which
      you will not get any output from <code>make</code>.
    </p>


    <a name="configuration-options"></a>
    <h3>Configuration options</h3>

    <p>
      <acronym>deal.II</acronym> has a large number of optional interfaces to
      other libraries. <b>By default, <code>cmake</code> will automatically
      enable support  for all external libraries it can find in default
      paths.</b>
      However, this behavior can be changed using command line switches to
      the initial call to <code>cmake</code>. A detailed description
      can be found here: <a href="users/cmake.html">Detailed build system description</a>.
    </p>

    <p>
      In the following, let us summarize the most common configuration
      options.
    </p>

    <a name="optional"/>
      <h4>Selecting optional behavior</h4>

    <ul>
      <li>
	<p>
	  <i>Threading</i>: By default, deal.II supports parallelism between
	  multiple cores on the same machine using threads and a
	  task-based model built on the
          <a href="http://threadingbuildingblocks.org/"
	  target="_top">Threading Building Blocks</a>. You can switch
	  threading off by passing the <code>-DDEAL_II_WITH_THREADS=OFF</code>
	  argument to <code>cmake</code>.
	</p>
      </li>

      <li>
	<p>
	  <i>MPI</i>: To enable parallel computations beyond a single node
	  using the <a href="http://mpi-forum.org/" target="_top">Message
	  Passing Interface (MPI)</a>, pass the
	  <code>-DDEAL_II_WITH_MPI=ON</code> argument
	  to <code>cmake</code>. If <code>cmake</code> found MPI but you
	  specifically do not want to use it, then
	  pass <code>-DDEAL_II_WITH_MPI=OFF</code>.
	</p>
      </li>

      <li>
        <p>
          <i>mesh_converter</i>: If you wish to compile and install the
          <code>mesh_converter</code> tool discussed in the documentation
	  of the <code>GridIn</code> class, specify
          <code>-DDEAL_II_COMPONENT_MESH_CONVERTER=ON</code>. (This is in fact
          the default.)
	</p>

        <p>
          <i>parameter_gui</i>: If you wish to compile and install the
          <code>parameter_gui</code> tool discussed in the documentation
	  of the <code>ParameterHandler</code> class, specify
          <code>-DDEAL_II_COMPONENT_PARAMETER_GUI=ON</code>. Beware of the
          fact that <code>parameter_gui</code> needs development packages for Qt.
	</p>
      </li>

      <li>
  <p>
    <i>64bit indices</i>: By default, deal.II use unsigned int (32bit)
    indices for degrees of freedom, using
    the <code>types::global_dof_index</code> type. This limits the number of
    unknowns to approximately four
    billions. If larger problem must be solved, pass the
    <code>-DDEAL_II_WITH_64BIT_INDICES=ON</code> argument to
    <code>cmake</code>. You will not be able to solve problems of this size on
    a single machine, but only when using clusters of computers and linear
    algebra packages PETSc or Trilinos.
    To use this option with PETSc, PESTc must be compiled
    with the option <code>--with-64-bit-indices</code>. To use this option
    with Trilinos, Trilinos 11.2 or later is needed (there is a bug in
    Trilinos 11.0 that prevents the use of 64bit indices).
  </p>
      </li>
    </ul>



    <a name="optional-software"/>
    <h4>Optional interfaces to other software packages</h4>

    <p>
      When configuring interfacing to external libraries, the
      <code>cmake</code> script by default tries to find all of these
      libraries in a number of standard locations on your file system.
      For <i>optional</i> interfaces, it gives up if the library is not
      found and <acronym>deal.II</acronym> will be built without support
      for them.
      However, there is one interface that we <i>need</i> to have: <a
      href="http://www.boost.org/" target="_top">BOOST</a>. If it is not
      found externally <code>cmake</code> will resort to the bundled boost
      version that is part of the <acronym>deal.II</acronym> tar file.
    </p>

    <p>
      The following paragraphs describe how the interfaces to the
      various packages, <acronym>deal.II</acronym> interacts with,
      can be configured.
    </p>

    <p><b>Notes:</b></p>
      <ul>
        <li>
          <b>The majority of libraries mentioned below should be readily
          packaged by most Linux distributions. Usually you need to
          install a <i>development</i> version of a library package,
          e.g. ending in <code>-dev</code> or <code>-devel</code>.
          After that <code>cmake</code> will automatically find the
          library and use it.</b>
      </li>
        <li>
          Configuring the interface to a self compiled package,
          say <code>foo</code> can usually be done by specifying
          <code>-DFOO_DIR=/path/to/foo</code>.  Alternatively, you can
          set <code>FOO_DIR</code> as an environment variable in your
          <code>.bashrc</code> or <code>.cshrc</code> file so that
          you do not have to enter this argument again the next time
          you invoke <code>cmake</code> in a fresh build directory.
          Any value passed on the command line wins over a value that
          may be found in an environment variable.
      </li>
        <li>
          To explicitly enable or disable support for
          a library <code>foo</code> use the argument
          <code>-DDEAL_II_WITH_FOO=ON</code> resp.
          <code>-DDEAL_II_WITH_FOO=OFF</code> for <code>cmake</code>.
      </li>
    </ul>

    <dl>
      <dt><a name="ARPACK"/>
	<a href="http://www.caam.rice.edu/software/ARPACK/" target="_top">ARPACK</a></dt>
      <dd>
	<p>
	  <a href="http://www.caam.rice.edu/software/ARPACK/"
	     target="_top">ARPACK</a> is a library for computing large
          scale eigenvalue problems.
          <a href="http://www.caam.rice.edu/software/ARPACK/" target="_top">ARPACK</a>
          should be readily packaged by most Linux distributions.
          (Don't forget to install a development version of the library).
          To use a self compiled version, specify
          <code>-DARPACK_DIR=/path/to/arpack</code> on the command line.

	  For a detailed description on how to compile ARPACK and linking with deal.II, see
	  <a href="external-libs/arpack.html" target="body">this page</a>.
	</p>
      </dd>

      <dt>
	<a name="blas"></a>
	<a href="http://www.netlib.org/blas/" target="_top">BLAS</a>,
	<a href="http://www.netlib.org/lapack/" target="_top">LAPACK</a>
      </dt>
      <dd>
	<p>
	  <a href="http://www.netlib.org/blas/" target="_top">BLAS</a>
	  (the <i>Basic Linear Algebra Subroutines</i>) and
	  <a href="http://www.netlib.org/lapack/" target="_top">LAPACK</a>
	  (<i>Linear Algebra Package</i>) are two packages that support
	  low-level linear algebra operations on vectors and dense
          matrices.
          Both libraries should be packaged by almost all Linux
          distributions and found automatically whenever available.
          (You might have to install development versions of the libraries
          for <acronym>deal.II</acronym> being able to use them).
          For details on how to set up <acronym>deal.II</acronym> with a
          non standard BLAS/LAPACK implementation, see the
	  <a href="users/cmake.html#advanced">advanced
            setup</a> section in the CMake ReadME.
	</p>
      </dd>

      <dt>
	<a name="functionparser"></a>
	<a href="http://warp.povusers.org/FunctionParser/">FunctionParser</a>
      </dt>
      <dd>
	<p>
	  <a href="http://warp.povusers.org/FunctionParser/">FunctionParser</a>
	  is a library that allows to enter functions in text form and have them
	  interpreted at run time. This is particularly useful in input
	  parameter files. <code>cmake</code> will usually find the version of
	  this library that comes bundled with <acronym>deal.II</acronym>.
	  The function parser library has its own license; if you want to use
	  it with deal.II, please read it and make sure that you agree with it.
	  You can find it
	  <a href="http://warp.povusers.org/FunctionParser/">here</a>. We
	  include FunctionParser in the deal.II distributions courtesy of its author,
	  <a href="http://iki.fi/warp/"><NAME></a>.
	</p>
      </dd>


      <dt><a name="HDF5"></a><a href="http://www.hdfgroup.org/HDF5/">HDF5</a></dt>
      <dd>
	<p>
	  The <a href="http://www.hdfgroup.org/HDF5/">HDF5 library</a>
	  provides graphical output capabilities in <code>HDF5/XDMF</code>
	  format.
	  <a href="http://www.hdfgroup.org/HDF5/">HDF5</a> should be
	  readily packaged by most Linux distributions.  (Don't forget
          to install a development version of the library).
	  To use a self compiled version, specify
	  <code>-DHDF5_DIR=/path/to/hdf5</code> on the command line.
	</p>
      </dd>


      <dt><a name="metis"></a><a href="http://glaros.dtc.umn.edu/gkhome/metis/metis/overview"
	     target="_top">METIS</a></dt>
      <dd>
	<p>
	  <a href="http://glaros.dtc.umn.edu/gkhome/metis/metis/overview"
		  target="_top">METIS</a> is a library that
	  provides various methods to partition
	  graphs. <acronym>deal.II</acronym> uses it in programs like the
	  step-17 tutorial to partition a mesh for parallel computing.
	  To use a self compiled version, specify
	  <code>-DMETIS_DIR=/path/to/metis</code> on the command line.
	  <acronym>deal.II</acronym> supports METIS 5 and later.
	</p>

	<p>
	  <b>Note:</b> A more modern way to support parallel computations is
	  shown in the step-40 tutorial program and is based on
	  the <code>p4est</code> library instead of METIS. See below on
	  installing <code>p4est</code>.
	</p>
      </dd>


      <dt><a name="mumps"></a><a href="http://mumps.enseeiht.fr" target="_top">MUMPS</a></dt>
      <dd>
	<p>
	  <a href="http://mumps.enseeiht.fr" target="_top">MUMPS</a>
	  (MUltifrontal Massively Parallel sparse direct Solver)
	  is a sparse direct solver that can factorize matrices within or
	  across nodes of a cluster.
	  <a href="http://mumps.enseeiht.fr" target="_top">MUMPS</a>
          should be readily packaged by most Linux distributions.
          (Don't forget to install a development version of the library).
          To use a self compiled version, provide the
	  <code>-DMUMPS_DIR=/path/to/mumps</code> argument to <code>cmake</code>.
	  For a detailed description on how to compile MUMPS (and
	  some dependencies) and linking with deal.II, see
	  <a href="external-libs/mumps.html" target="body">this page</a>.
	</p>
      </dd>


      <dt><a name="netcdf"></a><a href="http://www.unidata.ucar.edu/software/netcdf/" target="_top">NetCDF</a></dt>
      <dd>
	<a href="http://www.unidata.ucar.edu/software/netcdf/"
	   target="_top">NetCDF</a> is a library that provides services for
	reading and writing mesh data (and many other
	things). <acronym>deal.II</acronym> can use it to read meshes via
        one of the functions of the <code>GridIn</code> class.
	<a href="http://www.unidata.ucar.edu/software/netcdf/"
           target="_top">NetCDF</a> should be readily packaged by most
        Linux distributions. (Don't forget to install a development
	version of the library). To use a self compiled version, pass
	<code>-DNETCDF_DIR=/path/to/netcdf</code> to <code>cmake</code>.
      </dd>


      <dt><a name="p4est"></a><a href="http://www.p4est.org/" target="_top">p4est</a></dt>
      <dd>
	<p>
	  <a href="http://www.p4est.org/" target="_top">p4est</a>
	  is a library that <acronym>deal.II</acronym> uses to
	  distribute very large meshes across multiple processors (think
	  meshes with a billion cells on 10,000 processors). Using and
	  installing p4est is discussed <a href="external-libs/p4est.html"
					   target="body">here</a>.
	  To use a self compiled version, pass the argument
	  <code>-DP4EST_DIR=/path/to/p4est</code> to the
	  <code>cmake</code> command.
	</p>
      </dd>


      <dt><a name="petsc"></a><a href="http://www.mcs.anl.gov/petsc/"
		 target="_top">PETSc</a></dt>
      <dd>
	<p>
	  <a href="http://www.mcs.anl.gov/petsc/" target="_top">PETSc</a> is a
	  library that supports parallel linear algebra and many other things.

	  <a href="http://www.mcs.anl.gov/petsc/" target="_top">PETSc</a>
	  is already packaged by some Linux distributions and should be
	  found automatically if present. (Don't forget to install a
	  development version of the library).  To use a self compiled
	  version of PETSc, add <code>-DPETSC_DIR=/path/to/petsc
	  -DPETSC_ARCH=architecture</code> to the argument list for
	  <code>cmake</code>. The values for these arguments must be
	  the same as those specified when building PETSc.
	</p>

	<p>
	  To disable the PETSc interfaces in cases where <code>cmake</code>
	  automatically finds it, use <code>-DDEAL_II_WITH_PETSC=OFF</code>
	  More information on configuring and building PETSc can be
          found <a href="external-libs/petsc.html" target="body">here</a>.
	</p>
      </dd>


      <dt><a name="slepc"></a><a href="http://www.grycap.upv.es/slepc/" target="_top">SLEPc</a></dt>
      <dd>
	<p>
	  <a href="http://www.grycap.upv.es/slepc/"
	  target="_top">SLEPc</a> is a library for eigenvalue
	  computations that builds on PETSc. Its configuration works
	  just like that for PETSc, except that the variable to set
	  is <code>SLEPC_DIR</code>.  For the interface with SLEPc to
	  work, <acronym>deal.II</acronym>'s PETSc interface must also
	  be configured correctly (see above).
	</p>

	<p>
	  To disable the SLEPc interfaces in cases where <code>cmake</code>
	  automatically finds it, use <code>-DDEAL_II_WITH_PETSC=OFF</code>
	  More information on configuring and building SLEPc can be
          found <a href="external-libs/slepc.html" target="body">here</a>.
	</p>
      </dd>


      <dt><a name="tbb"></a><a href="http://www.threadingbuildingblocks.org/"
	     target="_top">Threading Building Blocks (TBB)</a></dt>
      <dd>
	<p>
	  The <a href="http://www.threadingbuildingblocks.org/"
	     target="_top">Threading Building Blocks (TBB)</a>
	  is a library that provides advanced services for using multiple
	  processor cores on a single machine and is used
	  in <acronym>deal.II</acronym> to parallelize many operations. If not
	  found in a system-wide location, <code>cmake</code> will
	  resort to the version bundled as part of
	  the <acronym>deal.II</acronym> download. It is always enabled unless
	  threads are explicitly disabled, see <a href="#optional">above</a>.
	</p>
      </dd>


      <dt><a name="trilinos"></a><a href="http://trilinos.sandia.gov" target="_top">Trilinos</a></dt>
      <dd>
	<p>
	  <a href="http://trilinos.sandia.gov" target="_top">Trilinos</a> is a
	  library for parallel linear algebra and all sorts of other things as
	  well.

	  To interface with a self compiled version of <a
	  href="http://trilinos.sandia.gov" target="_top">Trilinos</a>
	  add <code>-DTRILINOS_DIR=/path/to/trilinos</code> to the
	  argument list for <code>cmake</code>.  Alternatively, you can
	  also set an environment variable <code>TRILINOS_DIR</code>
	  and <code>cmake</code> will pick up this path.
	</p>

	<p>
	  To disable the Trilinos interfaces in cases where
	  <code>cmake</code> automatically finds it, use
	  <code>-DDEAL_II_WITH_TRILINOS=OFF</code> More details about
	  compatibility and configuration can be found
          <a href="external-libs/trilinos.html" target="body">here</a>.
	</p>
      </dd>


      <dt><a name="umfpack"></a><a href="http://www.cise.ufl.edu/research/sparse/umfpack/"
	     target="_top">UMFPACK</a></dt>
      <dd>
	<p>
	  <a href="http://www.cise.ufl.edu/research/sparse/umfpack/"
	     target="_top">UMFPACK</a> is a sparse direct solver that we often
	  use in prototype codes where the goal is to simply get a linear
          system solved robustly.
	  The interface will be enabled by default, either using a version
	  installed on your system of using a version that comes bundled
	  with <acronym>deal.II</acronym>.
	  It can be disabled explicitly by using the
	  <code>-DDEAL_II_WITH_UMFPACK=OFF</code> argument.
	  To use a self compiled version, pass the argument
	  <code>-DUMFPACK_DIR=/path/to/umfpack</code> to the
	  <code>cmake</code> command.
	</p>

	<p>
	  UMFPACK has its own license. To use it with deal.II, please
	  read it and make sure that you agree with it. You can find
	  the license of UMFPACK
          <a href="http://www.cise.ufl.edu/research/sparse/umfpack/">here</a>.
	  We include UMFPACK in the deal.II distributions courtesy of
	  its author, <a href="http://www.cise.ufl.edu/~davis/"><NAME></a>.
	</p>
      </dd>
    </dl>


    <a name="conf-details"/>
    <h4>More information on configuring and building the library</h4>

    <p>
      The <acronym>deal.II</acronym> <code>cmake</code> system allows far
      greater control over what exactly is configured or built than just the
      outline above. If you want to learn more about this, take a look
      <a href="users/cmake.html">here</a>. You might also be interested in
      <a href="users/cmakelists.html">CMake for user projects</a> or 
      <a href="developers/cmake-internals.html">build system internals</a>.
    </p>


    <a name="problems"></a>
    <h2>Problems, questions, mailing lists</h2>

    <p>
      Some information beyond what is covered in the documentation of
      the library may be found on the
      <a href="http://www.dealii.org" target="_top"><acronym>deal.II</acronym>
	homepage</a>, or in the
      <a href="http://code.google.com/p/dealii/wiki/FrequentlyAskedQuestions" target="_top">Frequently Asked Questions</a> section.
      If you don't find what you're looking for,
      feel free to ask on our
      <a href="http://www.dealii.org/mail.html" target="body">mailing list</a>.
    </p>

    <p>
      We are interested in any feedback, whether positive or negative,
      in order to determine the directions of future work on the
      library. We are also very much interested in incorporating any
      work and bug fixes by third parties into the library. Of course,
      you will be credited for this on
      the <a href="http://www.dealii.org/authors.html" target="_top">authors page</a>.
    </p>

    <p>
      Our institutes are evaluated at regular intervals. Consequently,
      we are interested in documenting the use of the programs and
      libraries we create. To this end, we collect
      publications with results obtained using <acronym>deal.II</acronym>. Please
      let us know if you have publications that we can add
      <a href="publications/index.html">to this page</a>.
    </p>

    <a name="license"></a>
    <h2>License</h2>

    <p>
      The deal.II library is free software; you can use it, redistribute
      it, and/or modify it under the terms of the
      <a href="http://www.gnu.org/licenses/lgpl-2.1.html">GNU Lesser General
      Public License</a> (LGPL) as published by the Free Software
      Foundation; either version 2.1 of the License, or (at your option)
      any later version.
    </p>
    <p>
      This allows you to use the library free of charge for private,
      academic, or commercial use (under the terms of the LGPL v2.1 or
      later). You are guaranteed full access to the source code and are
      encouraged to help in the further development of the library. Follow
      <a href="license.html" target="body">this link</a> for detailed
      information.
    </p>
    <p>
      Please note:</p>
      <ul>
	<li>
          Detailed license information can be found following
          <a href="license.html" target="body">this link</a>.
	</li>
	<li>
          <b>As a contributor to this project, you agree that any of your
          contributions be licensed under the same terms and conditions as
          the license of the deal.II project granted to you.</b>
	</li>
        <li>
          We, <a href="http://www.dealii.org/authors.html" target="_top">the deal.II Authors</a>, do not require
          copyright assignments for contributions. This means that the
          copyright for code contributions in the deal.II project is held by
          its respective contributors who have each agreed to release their
          contributed code under the terms of the LGPL v2.1 or later.
	</li>
	<li>
          In addition to the terms imposed by the LGPL (version 2.1 or
          later), we ask for the courtesy that scientific publications
          presenting results obtained with this libraries acknowledge its
          use. Please cite one of the papers referenced
          <a href="publications/index.html">here</a>.
	</li>
	<li>
          <acronym>deal.II</acronym> can interface with a number of <a
            href="#optional-software">other packages</a> that you either
          have to install yourself. They are, of course, covered by their
          own licenses. In addition, deal.II comes bundled with copies of
          <a href="http://www.cise.ufl.edu/research/sparse/umfpack/"
            target="_top">UMFPACK</a>,
          <a href="http://threadingbuildingblocks.org/"
            target="_top">Threading Building Blocks</a>,
          <a href="http://www.boost.org/" target="_top">BOOST</a> and
          <a href="http://warp.povusers.org/FunctionParser/"
            target="_top">FunctionParser</a>, courtesy of their authors.
          These are also covered by their own licenses; please refer to
          their webpages for more information.
	</li>
      </ul>

  <hr />
  <address>
    <a href="http://www.dealii.org/authors.html" target="_top">The deal.II Authors</a>
    $Date$
  </address>
  <div class="right">
    <a href="http://validator.w3.org/check?uri=referer" target="_top">
      <img style="border:0" src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
    <a href="http://jigsaw.w3.org/css-validator/check/referer" target="_top">
      <img style="border:0;width:88px;height:31px" src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
  </div>

  </body>
</html>

{'fraction_non_alphanumeric': 0.12563816096505495, 'fraction_numerical': 0.004313331730565259, 'mean_word_length': 3.0383780696744718, 'pattern_counts': {'":': 0, '<': 1826, '<?xml version=': 0, '>': 1826, 'https://': 6, 'lorem ipsum': 0, 'www.': 124, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6682734', 'n_tokens_mistral': 23318, 'n_tokens_neox': 21966, 'n_words': 7582}