PDELab
======

This is the 2.0.0 release of PDELab, a PDE discretization toolkit built
on top of the DUNE framework [0]. License information can be found in the file
COPYING.

PDELab 2.0 is a major release containing a large number of new features and improvements.
Most importantly, the DOF handling and the interface to linear algebra have been completely
rewritten, bringing improvements like faster and more memory-efficient matrix pattern
construction, easier iteration over DOF vectors, built-in support for applying arbitrary
permutations to the DOF order, among others. Another important new feature is the ability
to do computations on non-overlapping grids without storing the ghost DOFs, reducing both
the parallelization overhead and the complexity of the underlying code, in particular when
using AMG. Finally, it is now possible to do adaptive calculations with nested function spaces.
For details and an overview of the bug fixes in this release, see the changelog below.

If you need help, please ask on our mailinglist [1]. Bugs can also be submitted
to the PDELab bugtracker at [2] instead.

******************************************************************************************
This release of PDELab is designed to work with the 2.3.1+ release of the DUNE libraries.

WARNING: Do not try to use PDELab 2.0 with the 2.3.0 release of the core modules as there
         are known issues, most importantly the AMG will not work!
******************************************************************************************


Changes
=======

PDELab 2.0
----------

- The TypeTree library is now an external dependency. See README for information on
  how to obtain it.

- PDELab now supports building with CMake in addition to autotools.

- The DOF handling and the linear algebra backends have been completely rewritten to allow
  for more flexibility (nested vectors / matrices, more elaborate blocking / DOF reordering).
  Most of these changes are transparent to the average user, but you will have to change the
  typedef of your vector and matrix backends. Changing the matrix backend might also speed up
  matrix pattern construction (see below for further details). If you have been working with
  some of the internals of the GridFunctionSpace (e.g. by writing your own discrete grid functions
  that need to load data from a solution vector), you will have to adapt your code to the new
  index mapping and DOF access structure. See the file doc/README.Changes-2.0 for further details.

- There has been an important change to the way nested GridFunctionSpaces can be used: It is no longer
  allowed to use a GridFunctionSpace on its own and then integrate it into a larger system of spaces at
  a later time. Trying to do so will result in an exception at run time. This change was necessary as
  part of the move to the new DOF handling.

- There is a new, vastly improved pattern building algorithm for ISTL matrices, which is a lot faster
  than the old version and also avoid the problem of requiring twice as much memory as the final matrix
  during pattern construction. This new algorithm can be selected by using  (less memory, a lot faster).
  You can select the new algorithm by using the new class Dune::PDELab::istl::BCRSMatrixBackend. The
  new algorithm requires you to supply an approximate guesstimate of the average number of matrix entries
  per row, which you pass to the constructor of the matrix backend. That matrix backend is then passed
  to the constructor of the GridOperator. After matrix construction, you can query the matrix container
  for statistics about the pattern creation process, in particular about the quality of your guess. If
  your guess was bad, the performance (both memory and run time wise) will slowly degrade, so you should
  try to pass in a good value, even though it does not have to be optimal. All of the examples in the
  Howto have been ported to the new backend and can be used as a template for porting user programs.

- There are a number of new finite element maps, e.g. Brezzi-Douglas-Marini, a larger number of
  Raviart-Thomas elements, and new QkDG finite element maps.

- General overhaul of many FiniteElementMaps: Instead of having different classes depending
  on the order and dimension, there is now usually a single class that can be parameterized
  using template parameters. The old headers and classes have been deprecated and will be
  removed after the 2.0 release.

- As part of the new DOF handling, FiniteElementMaps now need to export some information about
  the DOF layout, in particular whether they are fixed size (i.e. always attach the same number
  of DOFs to an entity of given GeometryType) and if they do, the number of those DOFs. This
  extra information allows us to avoid a grid traversal for fixed size FEMs.

- The ExplicitOneStepMethod now supports limiters. There is a rather minimal interface (the limiter
  gets called at the beginning of each stage with the old solution and at the end of each stage with
  the new one). It uses a virtual interface, allowing you to switch limiters at run time.

- Nonoverlapping grids can now be used without creating DOFs on the ghost partition, improving surface-to-
  volume ratio and simplifying the AMG implementation for nonoverlapping grids. In order to use this
  mode, you have to pass a special OrderingTag to the leaf GridFunctionSpaces and define them on a GridView
  that is restricted to the InteriorBorder partition. See dune/pdelab/test/testnonoverlapping.cc for
  an example.

- The constraints files were cleaned up. Now all constraints files have been moved to the directory
  dune/pdelab/constraints (instead of the previous split between dune/pdelab/constraints and
  dune/pdelab/finiteelementmap). The infrastructure headers are now in dune/pdelab/constraints/common.
  The old headers are still there in this release, but they have been deprecated and will be removed after
  2.0.

- There is new support infrastructure for automatically disassembling the GridFunctionSpace of a system
  and outputting all of the components to a VTK file. See doc/README.Changes-2.0 for further information.

- The new VectorGridFunctionSpace can be used to represent vector-valued fields. It acts like a combination
  of a scalar GridFunctionSpace and a PowerGridFunctionSpace on top of it. As an added bonus, it will
  automatically be detected by the new VTK output code and will be written as a vector-valued solution to
  VTK.

- The adaptivity support has been fixed and now also works for systems of variables. As long as there are
  no hanging nodes, it should also work for arbitrary discretizations.

- The new PermutedOrdering is a decorator that can be used to wrap an existing ordering tag and perform
  arbitrary permutations of the DOFs in that underlying ordering.

- The ISTL vector backend now provides an iterator for flat iteration over the scalar entries in the vector,
  automatically traversing a possible block structure. This can be very useful when you want to simply dump
  or load the contents of a vector for debug or restart purposes.

- The GridOperatorSpace, which had been broken for a long time, has now been completely removed.

- The GridFunctionSpace data handles have been completely rewritten and now support communication per
  entity or per DOF. To avoid code duplication, they have been split into data handles and gather/scatter
  objects responsible for the actual data handling.

- There have been numerous improvements and bugfixes in the local operators.

- The method Dune::PDELab::istl::raw(x) provides idempotent access to the naked ISTL objects from the
  PDELab wrappers. They will also work correctly if passed an unpacked ISTL objects by returning the
  object itself.

- The StdVectorBackend is gone, but you can use the new simple backend instead. This new backend even
  provides a basic CRS matrix.

- The constructors of the StationaryLinearProblemSolver have been modified to use same order of parameters
  as the one of the Newton solver. Moreover, there are now also constructors that load the parameters from
  a Dune::ParameterTree. The old constructors have been deprecated and will be removed after PDELab 2.0.

- The Eigen backend is mostly functional now and works correctly with the new ordering infrastructure.

- A number of optimizations to the GridOperator and its engines make for important performance improvements
  when working with higher-order methods that have a large number of DOFs per element.

- It is now possible to use a diagonal local matrix for the jacobian assembly to reduce the required memory
  from N^2 to N if N is the number of DOFs per element.

Releasy history

  - PDELab 2.0.0
    - Fix instructions for obtaining dune-typetree.
    - Link libdunepdelab against libdunecommon.
    - Documentation fixes.

  - PDELab 2.0.0-rc2
    - Buildsystem fixes to include missing headers etc.
    - Improved handling of constraints engine storage in GridFunctionSpace
    - Fix PkFEM for k >= 3 in 2D, which was broken due to a bug in the variant
      selection. Also extended interpolation tests to cover this case.
    - Improvements to coding style and correctness in some places
    - Check for correct cell GeometryType in PkFEM and VariableMonomFEM
    - Fix broken testordering
    - Add infrastructure support required for parallel computations with the
      dune-multidomain extension module

  - PDELab 2.0.0-rc1
    - initial release candidate


PDELab 1.1
----------

This is the first release of PDELab after the move from Subversion to Git for
version control. You CANNOT find this release on the Subversion server. If you prefer
to directly check out the sources instead of using the provided tarballs, please see
our website for information on how to access the Git repository.

- In the directory boilerplate/ you can find a lot of useful infrastructure classes
  to simplify writing most PDELab programs. For examples on how to use the boilerplate
  infrastructure, take a look at the Howto.

- There is now a Jacobi preconditioner for scalar nonoverlapping problems, along
  with a BiCGStab-based backend using it.

- Improved support for calculations with complex field type.

- The parameter class interface for Stokes problems has been redesigned to increase
  commonality between CG and DG versions.

- Working adaptivity, including hanging nodes. This functionality is currently restricted
  to scalar problems.

- Reimplemented support for matrix-free methods using GridOperator::jacobian_apply().

- We fixed most of the deprecation warnings due to deprecated APIs in the core modules.

- Fix for builds from repository with recent versions of autotools.

- Numerous bug fixes.

  - PDELab 1.1.0
    - Improved documentation for nonoverlapping AMG solvers

  - PDELab 1.1-rc2
    - fix for compilation problem with boilerplate examples in Howto
    - build tarballs using GNU tar and make sure they work without automake installed

  - PDELab 1.1-rc1
    - initial release candidate


Caveats
=======

The following list is a non-exhaustive overview of possible problems you might
encounter with this release.

Assembler
--------

Solvers
-------

* Both the Newton solver and the linear solve currently allocate a new matrix on
  each call to apply(), which can incur a significant overhead if they are
  called frequently (e.g. for instationary problems). This will be fixed in a
  later release.

Linear Algebra Backends
-----------------------

* Due to changes in the ISTL backend, users who construct their own solvers
  directly from ISTL primitives will have to make sure to use native ISTL types
  and variables for this. These can be accessed by the nested typedef ::BaseT
  and the method .base() for both vectors and matrices. For an example, see
  src/convection-diffusion/poisson.cc in dune-pdelab-howto. In general, we
  encourage usage of the predefined solver backends, though.

* The PETSc [3] backend is currently broken.

* The alternative backends for Eigen [4] is not as mature as the ISTL backend yet.

General
-------

* Compile times can be really long for non-trivial problems. Some developers
  have had good success with using the clang compiler instead of GCC during
  development and bug-testing to reduce compile times.

* After PDELab 2.0, the minimum compiler requirement of PDELab will be increased
  to GCC 4.5. Please be aware of this change in minimum requirements.

Links
=====

0. http://www.dune-project.org
1. http://lists.dune-project.org/mailman/listinfo/dune-pdelab
2. http://users.dune-project.org/projects/dune-pdelab/issues
3. http://www.mcs.anl.gov/petsc/
4. http://eigen.tuxfamily.org
