MOOCHO (Single Doxygen Collection)  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
DenseLinAlgPack_DVectorOp.hpp
Go to the documentation of this file.
1 // @HEADER
2 // ***********************************************************************
3 //
4 // Moocho: Multi-functional Object-Oriented arCHitecture for Optimization
5 // Copyright (2003) Sandia Corporation
6 //
7 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
8 // license for use of this work by or on behalf of the U.S. Government.
9 //
10 // Redistribution and use in source and binary forms, with or without
11 // modification, are permitted provided that the following conditions are
12 // met:
13 //
14 // 1. Redistributions of source code must retain the above copyright
15 // notice, this list of conditions and the following disclaimer.
16 //
17 // 2. Redistributions in binary form must reproduce the above copyright
18 // notice, this list of conditions and the following disclaimer in the
19 // documentation and/or other materials provided with the distribution.
20 //
21 // 3. Neither the name of the Corporation nor the names of the
22 // contributors may be used to endorse or promote products derived from
23 // this software without specific prior written permission.
24 //
25 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
26 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
29 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
30 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
31 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
32 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
33 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
34 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
35 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 //
37 // Questions? Contact Roscoe A. Bartlett (rabartl@sandia.gov)
38 //
39 // ***********************************************************************
40 // @HEADER
41 //
42 
43 // See DenseLinAlgPack_DMatrixOp.hpp for description of naming convensions
44 
45 #ifndef VECTOROP_H
46 #define VECTOROP_H
47 
49 
50 /* * @name {\bf Basic DVector Operation Functions (Level-1 BLAS)}.
51  *
52  * These are functions that perform basic operations with vectors such as element-wise
53  * linear algebra operations (e.g. v1 = v2 + v3, v1 = sin(v2)) and other vector
54  * related functions. The functions that have vectors as lhs arguments come in
55  * two varieties: those with a DVector object as the lhs argument (v_lhs), those with
56  * a DVectorSlice object as a lhs argument (vs_lhs). Having different functions
57  * for DVector and DVectorSlice objects as lhs arguments is important because
58  * Vectors resize to the rhs expression while DVectorSlice objects do not.
59  *
60  * Only DVectorSlice objects are used as rhs arguments however. When DVector objects
61  * are used to call these fucntions as rhs arguments, the implicit type conversion
62  * to a const temp DVectorSlice will be performed to make the call work.
63  *
64  * The implementations of these functions takes care of the following details:
65  *
66  * <ul>
67  * <li> Resizing DVector LHS on assignment
68  * <li> Test for aliasing of assign(...) but not other functions
69  * <li> Check preconditions (sizes of arguments) if LINALGPACK_CHECK_RHS_SIZES is defined
70  * </ul>
71  *
72  * These functions share common behavior and precondtions which are listed below.
73  *
74  * Preconditions for functions with a DVectorSlice object (vs_lhs) as a lhs argument
75  * (e.g. vs_lhs = abs(vs_rhs), vs_lhs = vs_rhs1 + vs_rhs2).
76  * <ul>
77  * <li> #vs_lhs.size() ==# size of rhs expression (throw #std::length_error#)
78  * </ul>
79  *
80  * Preconditions for functions with two DVectorSlice objects (vs_rhs1, vs_rhs2) rhs arguments
81  * (e.g. v_lhs = pow(vs_rhs1,vs_rhs2), result = trans(vs_rhs1,vs_rhs2)):
82  * <ul>
83  * <li> #vs_rhs1.size() == vs_rhs2.size()# (throw #std::length_error#)
84  * </ul>
85  *
86  * Algebric functions are named according to the types of their arguments. For example,
87  * the function for the operation vs_lhs = vs_rhs1 - vs_rhs2 is named V_VmV(...).
88  * For a description of this namming format see
89  * \Ref{LinAlgOpPack}
90  */
91 
92 // @{
93 // begin Basic DVector Operation Functions
94 
95 namespace DenseLinAlgPack {
96 
97 /* * @name {\bf Algebraic Functions}.
98  *
99  * The functions assign(...) are used by the implementation of the assignment operators for
100  * DVector and DVectorSlice and therefore the user can use the assignment operator to
101  * perform the copies.
102  */
103 
104 // @{
105 // begin Algebraic Functions
106 
107 
109 void Vp_S(DVectorSlice* vs_lhs, value_type alpha);
111 void Vt_S(DVectorSlice* vs_lhs, value_type alpha);
113 void Vp_StV(DVectorSlice* vs_lhs, value_type alpha, const DVectorSlice& vs_rhs);
114 
116 //void assign(DVector* v_lhs, value_type alpha);
118 //void assign(DVector* v_lhs, const DVectorSlice& vs_rhs);
120 void V_VpV(DVector* v_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
122 void V_VmV(DVector* v_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
124 void V_mV(DVector* v_lhs, const DVectorSlice& vs_rhs);
126 void V_StV(DVector* v_lhs, value_type alpha, const DVectorSlice& vs_rhs);
127 
129 //void assign(DVectorSlice* vs_lhs, value_type alpha);
131 //void assign(DVectorSlice* vs_lhs, const DVectorSlice& vx_rhs);
133 void V_VpV(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
135 void V_VmV(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
137 void V_mV(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
139 void V_StV(DVectorSlice* vs_lhs, value_type alpha, const DVectorSlice& vs_rhs);
140 
142 /* Apply a plane (Givens) rotation.
143  *
144  * [ c s ] * [ x' ] -> [ x' ]
145  * [ -s c ] [ y' ] [ y' ]
146  *
147  * See "Handbook for Matrix Computations" section 2.4
148  */
149 void rot( const value_type c, const value_type s, DVectorSlice* x, DVectorSlice* y );
150 
151 // end Algebraic Functions
152 // @}
153 
154 /* * @name {\bf Elementwise Math DVector / DVectorSlice Functions}. */
155 
156 // @{
157 // begin Elementsize Math Functions
158 
160 void abs(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
162 void asin(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
164 void acos(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
166 void atan(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
168 void atan2(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
170 void atan2(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs, value_type alpha);
172 void atan2(DVectorSlice* vs_lhs, value_type alpha, const DVectorSlice& vs_rhs);
174 void cos(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
176 void cosh(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
178 void exp(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
180 void max(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
182 void max(DVectorSlice* vs_lhs, value_type alpha, const DVectorSlice& vs_rhs);
184 void min(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
186 void min(DVectorSlice* vs_lhs, value_type alpha, const DVectorSlice& vs_rhs);
188 void pow(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
190 void pow(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs, value_type alpha);
192 void pow(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs, int n);
194 void pow(DVectorSlice* vs_lhs, value_type alpha, const DVectorSlice& vs_rhs);
196 void prod(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
198 void sqrt(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
200 void sin(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
202 void sinh(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
204 void tan(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
206 void tanh(DVectorSlice* vs_lhs, const DVectorSlice& vs_rhs);
207 
209 void abs(DVector* v_lhs, const DVectorSlice& vs_rhs);
211 void asin(DVector* v_lhs, const DVectorSlice& vs_rhs);
213 void acos(DVector* v_lhs, const DVectorSlice& vs_rhs);
215 void atan(DVector* v_lhs, const DVectorSlice& vs_rhs);
217 void atan2(DVector* v_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
219 void atan2(DVector* v_lhs, const DVectorSlice& vs_rhs, value_type alpha);
221 void atan2(DVector* v_lhs, value_type alpha, const DVectorSlice& vs_rhs);
223 void cos(DVector* v_lhs, const DVectorSlice& vs_rhs);
225 void cosh(DVector* v_lhs, const DVectorSlice& vs_rhs);
227 void exp(DVector* v_lhs, const DVectorSlice& vs_rhs);
229 void max(DVector* v_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
231 void max(DVector* v_lhs, value_type alpha, const DVectorSlice& vs_rhs);
233 void min(DVector* v_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
235 void min(DVector* v_lhs, value_type alpha, const DVectorSlice& vs_rhs);
237 void pow(DVector* v_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
239 void pow(DVector* v_lhs, const DVectorSlice& vs_rhs, value_type alpha);
241 void pow(DVector* v_lhs, const DVectorSlice& vs_rhs, int n);
243 void pow(DVector* v_lhs, value_type alpha, const DVectorSlice& vs_rhs2);
245 void sqrt(DVector* v_lhs, const DVectorSlice& vs_rhs);
247 void sin(DVector* v_lhs, const DVectorSlice& vs_rhs);
249 void sinh(DVector* v_lhs, const DVectorSlice& vs_rhs);
251 void tan(DVector* v_lhs, const DVectorSlice& vs_rhs);
253 void tanh(DVector* v_lhs, const DVectorSlice& vs_rhs);
255 void prod( DVector* vs_lhs, const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2 );
256 
257 // end Elementsize Math Functions
258 // @}
259 
260 /* * @name {\bf Scalar Returning and Misc DVectorSlice Functions}. */
261 
262 // @{
263 // begin Scalar Returning DVectorSlice Functions}
264 
266 value_type dot(const DVectorSlice& vs_rhs1, const DVectorSlice& vs_rhs2);
268 value_type max(const DVectorSlice& vs_rhs);
270 value_type min(const DVectorSlice& vs_rhs);
272 value_type norm_1(const DVectorSlice& vs_rhs);
274 value_type norm_2(const DVectorSlice& vs_rhs);
276 value_type norm_inf(const DVectorSlice& vs_rhs);
277 
278 // Misc. operations
279 
281 void swap(DVectorSlice* vs1, DVectorSlice* vs2);
282 
283 // end Scalar Returning DVectorSlice Functions
284 // @}
285 
286 } // end namespace DenseLinAlgPack
287 
288 // end Basic DVector Operation Functions
289 // @}
290 
291 #endif // VECTOROP_H
void max(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs1, const DVectorSlice &vs_rhs2)
vs_lhs = max(vs_rhs1,vs_rhs2)
void pow(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs1, const DVectorSlice &vs_rhs2)
vs_lhs = pow(vs_rhs1,vs_rhs2)
void Vp_StV(DVectorSlice *vs_lhs, value_type alpha, const DVectorSlice &vs_rhs)
vs_lhs += alpha * vs_rhs (BLAS xAXPY)
void sinh(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs)
vs_lhs = sinh(vs_rhs)
void atan2(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs1, const DVectorSlice &vs_rhs2)
vs_lhs = atan(vs_rhs1/vs_rhs2)
void abs(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs)
vs_lhs = abs(vs_rhs)
VectorSliceTmpl< value_type > DVectorSlice
void V_VpV(DVector *v_lhs, const DVectorSlice &vs_rhs1, const DVectorSlice &vs_rhs2)
v_lhs = alpha (elementwise)
void asin(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs)
vs_lhs = asin(vs_rhs)
void sin(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs)
vs_lhs = sin(vs_rhs)
void cosh(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs)
vs_lhs = cosh(vs_rhs)
value_type norm_2(const DVectorSlice &vs_rhs)
result = ||vs_rhs||2 (BLAS xNRM2)
void prod(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs1, const DVectorSlice &vs_rhs2)
vs_lhs(i) = vs_rhs1(i) * vs_rhs2(i), i = 1...n
void V_StV(DVector *v_lhs, value_type alpha, const DVectorSlice &vs_rhs)
v_lhs = alpha * vs_rhs
void atan(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs)
vs_lhs = atan(vs_rhs)
void Vp_S(DVectorSlice *vs_lhs, value_type alpha)
vs_lhs += alpha
void exp(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs)
vs_lhs = exp(vs_rhs)
value_type norm_1(const DVectorSlice &vs_rhs)
result = ||vs_rhs||1 (BLAS xASUM)
void V_VmV(DVector *v_lhs, const DVectorSlice &vs_rhs1, const DVectorSlice &vs_rhs2)
v_lhs = vs_rhs1 - vs_rhs2
void sqrt(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs)
vs_lhs = sqrt(vs_rhs)
void Vt_S(DVectorSlice *vs_lhs, value_type alpha)
vs_lhs *= alpha (BLAS xSCAL) (*** Note that alpha == 0.0 is handeled as vs_lhs = 0.0)
FortranTypes::f_dbl_prec value_type
Typedef for the value type of elements that is used for the library.
void V_mV(DVector *v_lhs, const DVectorSlice &vs_rhs)
v_lhs = - vs_rhs
void tanh(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs)
vs_lhs = tanh(vs_rhs)
value_type norm_inf(const DVectorSlice &vs_rhs)
result = ||vs_rhs||infinity (BLAS IxAMAX)
void acos(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs)
vs_lhs = acos(vs_rhs)
void tan(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs)
vs_lhs = tan(vs_rhs)
void swap(DVectorSlice *vs1, DVectorSlice *vs2)
swap(vs1, vs2). Swaps the contents of vs1 and vs2
void rot(const value_type c, const value_type s, DVectorSlice *x, DVectorSlice *y)
void cos(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs)
vs_lhs = cos(vs_rhs)
void min(DVectorSlice *vs_lhs, const DVectorSlice &vs_rhs1, const DVectorSlice &vs_rhs2)
vs_lhs = min(vs_rhs1,vs_rhs2)
value_type dot(const DVectorSlice &vs_rhs1, const DVectorSlice &vs_rhs2)
result = vs_rhs1' * vs_rhs2 (BLAS xDOT)