mainpage.dox

#error Documentation only.

namespace Spacy
{
/*! \mainpage %Spacy documentation
 * 
 * \section sec_intro Introduction
 * %Vhat is a library that aims at
 * - providing an abstraction layer for the implementation of algorithms in a vector space setting (function space oriented algorithms)
 * - providing a simple interface for sharing and comparing algorithms
 * - having fun while developing algorithms
 * - leaving you all freedom you want to implement your fancy algorithm (as long as you don't violate the mathematical structure of vector spaces)
 * 
 * \section sec_overview Overview
 * The basis of %Spacy is an abstraction layer for vector space settings. The interface of %Spacy essentially builds on type erasure techniques.  C++11/14-features such
 * as <a href="http://en.cppreference.com/w/cpp/language/value_category">R-values</a> are used, so make sure to use the
 * compiler option -std=c++1y.
 *
 * \subsection sub_concepts Main concepts
 * - First there is a vector space class (::Spacy::VectorSpace), which models a \ref ::Spacy::makeBanachSpace() "Banach space" <span lang="latex"> 
 *   (X,||.||)</span> or a \ref ::Spacy::makeHilbertSpace() "Hilbert space" <span lang="latex"> (X,(.,.))</span>. Thus, vector spaces provide access to a Norm and possibly a ScalarProduct. Moreover, vector spaces can be 
 *   related to each other as primal or dual spaces. Eventually they can generate vectors.
 * - a Vector can be any class satisfying the @ref Spacy::VectorConcept "VectorConcept", i.e. vectors must be vectors in a pure mathematical sense (almost).
 * - an Operator (see @ref Spacy::OperatorConcept "OperatorConcept") is a mapping vector spaces.
 * - a Functional (see @ref Spacy::FunctionalConcept "FunctionalConcept") is a mapping from a vector spaces into the space of real numbers \f$ \mathbb{R} \f$.
 * - a LinearOperator( see @ref Spacy::LinearOperatorConcept "LinearOperatorConcept") is a linear mapping between vector spaces that provides a solver for numerically evaluating its inverse. In addition linear operators satisfy the @ref Spacy::VectorConcept  "VectorConcept".
 *
 * \section sec_usage_fenics Usage with FEnics
 * Examples for nonlinear PDEs and optimal control problems with <a href="http://www.fenicsproject.org">FEniCS</a> are given in Examples/FEniCS.
 *
 * \subsection sub_usage_fenics_pde Nonlinear PDEs with FEniCS
 * For an operator equation \f$A(x)=0\f$, discretized with FEniCS ('L' denoting the residual form and 'a' the gradient form),
 * simplest usage is as follows
 * @code
 * ...
 * MyFEniCSExample::FunctionSpace V{mesh}
 * MyFEniCSExample::LinearForm L{V};
 * MyFEniCSExample::BilinearForm a{V,V};
 * ...
 *
 * // Create function space.
 * auto domain = Spacy::FEniCS::makeHilbertSpace(V);
 *
 * // Create operator mapping into the dual space of domain (which is, due to the Hilbert space structure, associated with domain itself).
 * // You can also specify the range space if it differs from the dual space of domain
 * // This is illustrated in the PDE example for Kaskade 7
 * auto A = Spacy::FEniCS::makeOperator( L , a , domain );
 *
 * // Solve with covariant Newton method with initial guess x0=0.
 * auto x = Spacy::covariantNewton(A);
 *
 *
 * // Copy solution back to dolfin::Function.
 * dolfin::Function u(V);
 * Spacy::FEniCS::copy(x,u);
 * ...
 * @endcode
 * 
 * 
 * \section sec_usage_kaskade Usage with Kaskade 7
 * Examples for nonlinear PDEs and optimal control problems with <a href="http://www.zib.de/projects/kaskade7-finite-element-toolbox">Kaskade 7</a> are given in Examples/Kaskade.
 *
 * \subsection sub_usage_kaskade_pde Nonlinear PDEs with Kaskade 7
 * For an operator equation \f$A(x)=0\f$, discretized with Kaskade 7 and with another scalar product,
 * usage is as follows
 * @code
 * ...
 * auto h1Space = Kaskade::FEFunctionSpace< ContinuousLagrangeMapper<double,LeafView> >{(} gridManager , gridManager.grid().leafView() , order };
 * ...
 * auto variableSetDescription = VariableSetDescription{ spaces , {"x"} };
 * Functional F{ ... };
 * ...
 *
 * // Create domain and range space.
 * auto domain = Spacy::Kaskade::makeHilbertSpace( space );
 * auto range  = Spacy::Kaskade::makeHilbertSpace( space );
 *
 * // Create operator
 * auto A = Spacy::Kaskade::makeOperator( F , domain , range );
 *
 * // Set induced scalar product on domain space.
 * auto x0 = domain.vector();
 * domain.setScalarProduct( InducedScalarProduct( A.linearization(x0) );
 *
 * // Solve with covariant Newton method with initial guess x0=0.
 * auto x = Spacy::covariantNewton( A , x0 );
 *
 *
 * // copy solution back to dolfin::Function
 * typename VariableSetDescription::VariableSet u( variableSetDescription );
 * Spacy::Kaskade::copy( x , u );
 * ...
 * @endcode
 */
}