DenseLinAlgPack_DVectorOp.hpp

// @HEADER
// ***********************************************************************
// 
// Moocho: Multi-functional Object-Oriented arCHitecture for Optimization
//                  Copyright (2003) Sandia Corporation
// 
// Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
// license for use of this work by or on behalf of the U.S. Government.
// 
// This library is free software; you can redistribute it and/or modify
// it under the terms of the GNU Lesser General Public License as
// published by the Free Software Foundation; either version 2.1 of the
// License, or (at your option) any later version.
//  
// This library is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
//  
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
// USA
// Questions? Contact Roscoe A. Bartlett (rabartl@sandia.gov) 
// 
// ***********************************************************************
// @HEADER
//

// See DenseLinAlgPack_DMatrixOp.hpp for description of naming convensions

#ifndef VECTOROP_H
#define VECTOROP_H

#include "DenseLinAlgPack_DVectorAssign.hpp"

/* * @name {\bf Basic DVector Operation Functions (Level-1 BLAS)}.
  *
  * These are functions that perform basic operations with vectors such as element-wise
  * linear algebra operations (e.g. v1 = v2 + v3, v1 = sin(v2)) and other vector 
  * related functions.  The functions that have vectors as lhs arguments come in
  * two varieties: those with a DVector object as the lhs argument (v_lhs), those with
  * a DVectorSlice object as a lhs argument (vs_lhs).  Having different functions
  * for DVector and DVectorSlice objects as lhs arguments is important because
  * Vectors resize to the rhs expression while DVectorSlice objects do not.
  *
  * Only DVectorSlice objects are used as rhs arguments however.  When DVector objects
  * are used to call these fucntions as rhs arguments, the implicit type conversion
  * to a const temp DVectorSlice will be performed to make the call work.
  * 
  * The implementations of these functions takes care of the following details:
  *
  * <ul>
  * <li> Resizing DVector LHS on assignment
  * <li> Test for aliasing of assign(...) but not other functions
  * <li> Check preconditions (sizes of arguments) if LINALGPACK_CHECK_RHS_SIZES is defined
  * </ul>
  *
  * These functions share common behavior and precondtions which are listed below.
  *
  * Preconditions for functions with a DVectorSlice object (vs_lhs) as a lhs argument
  * (e.g. vs_lhs = abs(vs_rhs), vs_lhs = vs_rhs1 + vs_rhs2).
  * <ul>
  * <li> #vs_lhs.size() ==# size of rhs expression  (throw #std::length_error#)
  * </ul>
  *
  * Preconditions for functions with two DVectorSlice objects (vs_rhs1, vs_rhs2) rhs arguments
  * (e.g. v_lhs = pow(vs_rhs1,vs_rhs2), result = trans(vs_rhs1,vs_rhs2)):
  * <ul>
  * <li> #vs_rhs1.size() == vs_rhs2.size()#  (throw #std::length_error#)
  * </ul>
  *
  * Algebric functions are named according to the types of their arguments.  For example,
  * the function for the operation vs_lhs = vs_rhs1 - vs_rhs2 is named V_VmV(...).
  * For a description of this namming format see
  * \Ref{LinAlgOpPack}
  */

// @{
//    begin Basic DVector Operation Functions

namespace DenseLinAlgPack {

/* * @name {\bf Algebraic Functions}.
  *
  * The functions assign(...) are used by the implementation of the assignment operators for
  * DVector and DVectorSlice and therefore the user can use the assignment operator to
  * perform the copies.
  */

// @{
//    begin Algebraic Functions


void Vp_S(DVectorSlice* vs_lhs, value_type alpha);
void Vt_S(DVectorSlice* vs_lhs, value_type alpha);
void Vp_StV(DVectorSlice* vs_lhs, value_type alpha, const DVectorSlice& vs_rhs);

//void assign(DVector* v_lhs, value_type alpha);
//void assign(DVector* v_lhs, const DVectorSlice& vs_rhs);
void V_VpV(DVector* v_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
void V_VmV(DVector* v_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
void V_mV(DVector* v_lhs, const DVectorSlice& vs_rhs);
void V_StV(DVector* v_lhs, value_type alpha, const DVectorSlice& vs_rhs);

//void assign(DVectorSlice* vs_lhs, value_type alpha);
//void assign(DVectorSlice* vs_lhs, const DVectorSlice& vx_rhs);
void V_VpV(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
void V_VmV(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
void V_mV(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
void V_StV(DVectorSlice* vs_lhs, value_type alpha, const DVectorSlice& vs_rhs);

/* Apply a plane (Givens) rotation.
 *
 * [  c  s ] * [ x' ] -> [ x' ]
 * [ -s  c ]   [ y' ]    [ y' ]
 *
 * See "Handbook for Matrix Computations" section 2.4
 */
void rot( const value_type c, const value_type s, DVectorSlice* x, DVectorSlice* y );

//    end Algebraic Functions
// @}

/* * @name {\bf Elementwise Math DVector / DVectorSlice Functions}. */

// @{
//    begin Elementsize Math Functions

void abs(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
void asin(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
void acos(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
void atan(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
void atan2(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
void atan2(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs, value_type alpha);
void atan2(DVectorSlice* vs_lhs, value_type alpha, const DVectorSlice& vs_rhs);
void cos(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
void cosh(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
void exp(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
void max(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
void max(DVectorSlice* vs_lhs, value_type alpha, const DVectorSlice& vs_rhs);
void min(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
void min(DVectorSlice* vs_lhs, value_type alpha, const DVectorSlice& vs_rhs);
void pow(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
void pow(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs, value_type alpha);
void pow(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs, int n);
void pow(DVectorSlice* vs_lhs, value_type alpha, const DVectorSlice& vs_rhs);
void prod(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
void sqrt(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
void sin(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
void sinh(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
void tan(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
void tanh(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);

void abs(DVector* v_lhs, const DVectorSlice& vs_rhs);
void asin(DVector* v_lhs, const DVectorSlice& vs_rhs);
void acos(DVector* v_lhs, const DVectorSlice& vs_rhs);
void atan(DVector* v_lhs, const DVectorSlice& vs_rhs);
void atan2(DVector* v_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
void atan2(DVector* v_lhs, const DVectorSlice& vs_rhs, value_type alpha);
void atan2(DVector* v_lhs, value_type alpha, const DVectorSlice& vs_rhs);
void cos(DVector* v_lhs, const DVectorSlice& vs_rhs);
void cosh(DVector* v_lhs, const DVectorSlice& vs_rhs);
void exp(DVector* v_lhs, const DVectorSlice& vs_rhs);
void max(DVector* v_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
void max(DVector* v_lhs, value_type alpha, const DVectorSlice& vs_rhs);
void min(DVector* v_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
void min(DVector* v_lhs, value_type alpha, const DVectorSlice& vs_rhs);
void pow(DVector* v_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
void pow(DVector* v_lhs, const DVectorSlice& vs_rhs, value_type alpha);
void pow(DVector* v_lhs, const DVectorSlice& vs_rhs, int n);
void pow(DVector* v_lhs, value_type alpha, const DVectorSlice& vs_rhs2);
void sqrt(DVector* v_lhs, const DVectorSlice& vs_rhs);
void sin(DVector* v_lhs, const DVectorSlice& vs_rhs);
void sinh(DVector* v_lhs, const DVectorSlice& vs_rhs);
void tan(DVector* v_lhs, const DVectorSlice& vs_rhs);
void tanh(DVector* v_lhs, const DVectorSlice& vs_rhs);
void prod( DVector* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2 );

//    end Elementsize Math Functions
// @}

/* * @name {\bf Scalar Returning and Misc DVectorSlice Functions}. */

// @{
//    begin Scalar Returning DVectorSlice Functions}

value_type dot(const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
value_type max(const DVectorSlice& vs_rhs);
value_type min(const DVectorSlice& vs_rhs);
value_type norm_1(const DVectorSlice& vs_rhs);
value_type norm_2(const DVectorSlice& vs_rhs);
value_type norm_inf(const DVectorSlice& vs_rhs);

// Misc. operations

void swap(DVectorSlice* vs1, DVectorSlice* vs2);

//    end Scalar Returning DVectorSlice Functions
// @}

} // end namespace DenseLinAlgPack

//    end Basic DVector Operation Functions
// @}

#endif // VECTOROP_H