  ***************************************************************************
  * All the software  contained in this library  is protected by copyright. *
  * Permission  to use, copy, modify, and  distribute this software for any *
  * purpose without fee is hereby granted, provided that this entire notice *
  * is included  in all copies  of any software which is or includes a copy *
  * or modification  of this software  and in all copies  of the supporting *
  * documentation for such software.                                        *
  ***************************************************************************
  * THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED *
  * WARRANTY. IN NO EVENT, NEITHER  THE AUTHORS, NOR THE PUBLISHER, NOR ANY *
  * MEMBER  OF THE EDITORIAL BOARD OF  THE JOURNAL  "NUMERICAL ALGORITHMS", *
  * NOR ITS EDITOR-IN-CHIEF, BE  LIABLE FOR ANY ERROR  IN THE SOFTWARE, ANY *
  * MISUSE  OF IT  OR ANY DAMAGE ARISING OUT OF ITS USE. THE ENTIRE RISK OF *
  * USING THE SOFTWARE LIES WITH THE PARTY DOING SO.                        *
  ***************************************************************************
  * ANY USE  OF THE SOFTWARE  CONSTITUTES  ACCEPTANCE  OF THE TERMS  OF THE *
  * ABOVE STATEMENT.                                                        *
  ***************************************************************************

   AUTHORS:

       Roman Andreev
       RICAM, Austrian Academy of Sciences, Austria
       Email: roman.andreev@oeaw.ac.at

   REFERENCE:
       
    -  Space-time discretization of the heat equation
       NUMERICAL ALGORITHMS, 67 (2014), pp. 713-731

   SOFTWARE REVISION DATE:

       V1.1, December 2013

   SOFTWARE LANGUAGE:

       MATLAB 8.0

======================================================================
SOFTWARE
======================================================================

The present Matlab code is a minimal working example of a space-time
Petrov-Galerkin discretization for parabolic evolution equations.

The software has been developed using MATLAB version 8.0 (R2012b).
No other MathWorks products or toolboxes are required.

The software makes use of the spatial finite element code by

   Alberty, J., Carstensen, C., Funken, S.A.
   Remarks around 50 lines of Matlab
   Numerical Algorithms, 20 (1999), pp. 117-137
   
======================================================================
HOW TO INSTALL 
======================================================================

No installation or configuration is necessary. 
Open Matlab and navigate to the spacetime/ folder. 
Run the function spacetime.m using the command "spacetime"

======================================================================
TUTORIAL AND TESTS
======================================================================

The function spacetime.m will output comments on its progress and
finish with a figure of several subplots showing temporal snapshots 
of the computed solution to a model parabolic evolution equation.
A PDF file of the plot is written in the current directory.

See the documentation below for more information.

======================================================================
PACKAGE
======================================================================

The package contains the following files.

Meta:
  README.txt      - This file
  Contents.m      - Displayed upon calling "help spacetime"

Demo function:
  spacetime       - Solves the heat equation and shows solution snapshots

Temporal FEM:
  femT_assemE     - Mass and stiffness matrices for 1d P1 Lagrange FEM
  femT_assemF     - Mass matrix of 1d piecewise constant functions
  femT_assemFE    - Temporal finite element matrices MtFE and CtFE

Space-time FEM:
  femTX_assemLoad - Assemble the space-time load vector

Spatial FEM:
  femX_b          - The spatial load vector
  femX_init       - Initialize the spatial FEM
  femX_MA         - Spatial mass and stiffness matrices
  femX_masma3     - Spatial element mass matrix for a triangle
  femX_masma4     - Spatial element mass matrix for a parallelogram
  femX_show       - Plot a finite element function
  femX_stima3     - Spatial element stiffness matrix for triangles
  femX_stima4     - Spatial element stiffness matrix for parallelograms

Problem data:
  data_f          - Source function
  data_g          - Neumann data
  data_h          - Initial condition

Solver:
  glsqr           - Generalized LSQR iterative solver

Quadrature:
  QR_GauLeg       - Gauss-Legendre quadrature
  QR_Trapz        - Trapezoidal quadrature

To set up the spatial FEM, the function femX_init accesses the data files:
  femX_coordinates.dat
  femX_dirichlet.dat
  femX_elements3.dat
  femX_elements4.dat
  femX_neumann.dat

======================================================================
PARALLELIZATION
======================================================================

The functions spacetime.m and femTX_assemLoad.m contain "parfor" loops
to mark parts of the code that are easily parallelizable at no cost in
code conciseness and still consititute a large portion of run time. 

Note that "parfor" may not be effective without a preceding call to
"matlabpool" (currently part the Matlab parallel computing toolbox).
Please read the Matlab documentation using "help parfor" for more.

======================================================================
DOCUMENTATION
======================================================================

More information can be found in the papers referenced above

