ENH: add normalise methods for vectors and normalised function

- the vector normalise() method modifies the object inplace,
  the normalised function returns a copy.

      vector vec1(1,2,3);
      vec1.normalise();
  vs
      vector vec1(1,2,3);
      vec1 /= mag(vec1) + VSMALL;

  For const usage, can use either of these

      const vector vec2a(normalised(vector(1,2,3)));
      const vector vec2b(vector(1,2,3).normalise());

applications/test/vector/Test-vector.C

@@ -1,37 +1,97 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2018 OpenCFD Ltd.
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM 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 General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+Application
+    Test-vector
+
+Description
+    Some simple tests for vector
+
+\*---------------------------------------------------------------------------*/
+
 #include "vector.H"
 #include "IOstreams.H"
 
 using namespace Foam;
 
-int main()
+void printInfo(const vector& vec)
 {
-    Info<< vector::zero << endl
-        << vector::one << endl
-        << vector::dim << endl
-        << vector::rank << endl;
+    Info<< "vector : " << vec << nl
+        << "magSqr : " << magSqr(vec) << nl;
 
-    vector d(0.5, 0.5, 0.5);
-    d /= mag(d);
+    Info<< "component"
+        << " max:" << cmptMax(vec)
+        << " sum:" << cmptSum(vec)
+        << " prod:" << cmptProduct(vec)
+        << " mag:" << cmptMag(vec)
+        << nl << nl;
+}
 
-    vector dSmall = (1e-100)*d;
-    dSmall /= mag(dSmall);
 
-    Info<< (dSmall - d) << endl;
+void doTest(vector& vec1, vector& vec2)
+{
+    Info<<"normalised(vector1): " << normalised(vec1) << nl;
+    Info<<"vector1: " << vec1 << nl;
+    vec1.normalise();
+    Info<<"normalised: " << vec1 << nl;
 
-    d *= 4.0;
+    vector vecsmall((1e-100 * vec1));
 
-    Info<< d << endl;
+    Info<<"small: " << vecsmall << nl;
+    Info<<"small normalised: " << normalised(vecsmall) << nl;
+    Info<<"small diff: " << (vecsmall.normalise() - vec1) << nl;
 
-    Info<< d + d << endl;
+    vec1 *= 4.0;
 
-    Info<< magSqr(d) << endl;
+    Info<< "scalar mult: " << vec1 << nl;
+    Info<< "addition   : " << (vec1 + vec1) << nl;
+
+    printInfo(vec1);
+    printInfo(vec2);
+
+    Info<< "min of " << vec1 << " and " << vec2 << " = "
+        << min(vec1, vec2) << nl << nl;
+}
+
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+//  Main program:
+
+int main(int argc, char *argv[])
+{
+    Info<<"normalised: " << vector(1,2,3).normalise() << nl;
+    Info<<"normalised: " << vector(VSMALL,VSMALL,VSMALL).normalise() << nl;
+    Info<<"normalised: " <<
+        vector(ROOTVSMALL,ROOTVSMALL,ROOTVSMALL).normalise() << nl;
+
+    {
+        vector vec1(0.5, 0.5, 0.5);
+        vector vec2(0.5, 0.51, -0.5);
+
+        doTest(vec1, vec2);
+    }
 
-    vector d2(0.5, 0.51, -0.5);
-    Info<< cmptMax(d2) << " "
-        << cmptSum(d2) << " "
-        << cmptProduct(d2) << " "
-        << cmptMag(d2)
-        << endl;
-    Info<< min(d, d2) << endl;
     return 0;
 }
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

src/OpenFOAM/primitives/Vector/Vector.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2011-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2018 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -48,6 +48,7 @@ SourceFiles
 namespace Foam
 {
 
+// Forward Declarations
 template<class T> class List;
 
 /*---------------------------------------------------------------------------*\
@@ -84,34 +85,48 @@ public:
         //- Construct initialized to zero
         inline Vector(const Foam::zero);
 
-        //- Construct given VectorSpace of the same rank
+        //- Copy construct from VectorSpace of the same rank
         template<class Cmpt2>
-        inline Vector(const VectorSpace<Vector<Cmpt2>, Cmpt2, 3>&);
+        inline Vector(const VectorSpace<Vector<Cmpt2>, Cmpt2, 3>& vs);
 
-        //- Construct given three components
+        //- Construct from three components
         inline Vector(const Cmpt& vx, const Cmpt& vy, const Cmpt& vz);
 
         //- Construct from Istream
-        inline Vector(Istream&);
+        inline Vector(Istream& is);
 
 
     // Member Functions
 
-        // Access
+        //- Access to the vector x component
+        inline const Cmpt& x() const;
 
-            inline const Cmpt& x() const;
-            inline const Cmpt& y() const;
-            inline const Cmpt& z() const;
+        //- Access to the vector y component
+        inline const Cmpt& y() const;
+
+        //- Access to the vector z component
+        inline const Cmpt& z() const;
+
+        //- Access to the vector x component
+        inline Cmpt& x();
+
+        //- Access to the vector y component
+        inline Cmpt& y();
+
+        //- Access to the vector z component
+        inline Cmpt& z();
+
+
+        //- Normalise the vector by its magnitude
+        inline Vector<Cmpt>& normalise();
 
-            inline Cmpt& x();
-            inline Cmpt& y();
-            inline Cmpt& z();
 
         //- Return *this (used for point which is a typedef to Vector<scalar>.
         inline const Vector<Cmpt>& centre
         (
             const Foam::List<Vector<Cmpt>>&
         ) const;
+
 };
 
 

src/OpenFOAM/primitives/Vector/VectorI.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2011-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2018 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -115,12 +115,30 @@ template<class Cmpt>
 inline const Foam::Vector<Cmpt>& Foam::Vector<Cmpt>::centre
 (
     const Foam::List<Vector<Cmpt>>&
-)const
+) const
 {
     return *this;
 }
 
 
+template<class Cmpt>
+inline Foam::Vector<Cmpt>& Foam::Vector<Cmpt>::normalise()
+{
+    const scalar s(Foam::mag(*this));
+
+    if (s < ROOTVSMALL)
+    {
+        *this = Zero;
+    }
+    else
+    {
+        *this /= s;
+    }
+
+    return *this;
+}
+
+
 // * * * * * * * * * * * * * * * Global Operators  * * * * * * * * * * * * * //
 
 namespace Foam

src/OpenFOAM/primitives/Vector2D/Vector2D.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2011-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2018 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -78,31 +78,38 @@ public:
         //- Construct initialized to zero
         inline Vector2D(const Foam::zero);
 
-        //- Construct given VectorSpace
-        inline Vector2D(const VectorSpace<Vector2D<Cmpt>, Cmpt, 2>&);
+        //- Copy construct from VectorSpace of the same rank
+        inline Vector2D(const VectorSpace<Vector2D<Cmpt>, Cmpt, 2>& vs);
 
-        //- Construct given two components
+        //- Construct from two components
         inline Vector2D(const Cmpt& vx, const Cmpt& vy);
 
         //- Construct from Istream
-        inline Vector2D(Istream&);
+        inline Vector2D(Istream& is);
 
 
     // Member Functions
 
-        // Access
+        //- Access to the vector x component
+        inline const Cmpt& x() const;
 
-            inline const Cmpt& x() const;
-            inline const Cmpt& y() const;
+        //- Access to the vector y component
+        inline const Cmpt& y() const;
 
-            inline Cmpt& x();
-            inline Cmpt& y();
+        //- Access to the vector x component
+        inline Cmpt& x();
+
+        //- Access to the vector y component
+        inline Cmpt& y();
 
 
-        // Operators
+        //- Normalise the vector by its magnitude
+        inline Vector2D<Cmpt>& normalise();
+
+
+        //- Perp dot product (dot product with perpendicular vector)
+        inline scalar perp(const Vector2D<Cmpt>& b) const;
 
-            //- Perp dot product (dot product with perpendicular vector)
-            inline scalar perp(const Vector2D<Cmpt>& b) const;
 };
 
 

src/OpenFOAM/primitives/Vector2D/Vector2DI.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2011-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2018 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -70,6 +70,7 @@ inline const Cmpt& Foam::Vector2D<Cmpt>::x() const
     return this->v_[X];
 }
 
+
 template<class Cmpt>
 inline const Cmpt& Foam::Vector2D<Cmpt>::y() const
 {
@@ -83,6 +84,7 @@ inline Cmpt& Foam::Vector2D<Cmpt>::x()
     return this->v_[X];
 }
 
+
 template<class Cmpt>
 inline Cmpt& Foam::Vector2D<Cmpt>::y()
 {
@@ -90,6 +92,22 @@ inline Cmpt& Foam::Vector2D<Cmpt>::y()
 }
 
 
+template<class Cmpt>
+inline Foam::Vector2D<Cmpt>& Foam::Vector2D<Cmpt>::normalise()
+{
+    const scalar s(Foam::mag(*this));
+
+    if (s < ROOTVSMALL)
+    {
+        *this = Zero;
+    }
+    else
+    {
+        *this /= s;
+    }
+}
+
+
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 namespace Foam

src/OpenFOAM/primitives/VectorSpace/VectorSpace.H

@@ -49,33 +49,32 @@ SourceFiles
 namespace Foam
 {
 
-// Forward declaration of friend functions and operators
+// Forward declarations
 
 template<class Form, class Cmpt, direction Ncmpts> class VectorSpace;
 
 template<class Form, class Cmpt, direction Ncmpts>
 Istream& operator>>
 (
-    Istream&,
-    VectorSpace<Form, Cmpt, Ncmpts>&
+    Istream& is,
+    VectorSpace<Form, Cmpt, Ncmpts>& vs
 );
 
 template<class Form, class Cmpt, direction Ncmpts>
 Ostream& operator<<
 (
-    Ostream&,
-    const VectorSpace<Form, Cmpt, Ncmpts>&
+    Ostream& os,
+    const VectorSpace<Form, Cmpt, Ncmpts>& vs
 );
 
 
 /*---------------------------------------------------------------------------*\
-                           Class VectorSpace Declaration
+                         Class VectorSpace Declaration
 \*---------------------------------------------------------------------------*/
 
 template<class Form, class Cmpt, direction Ncmpts>
 class VectorSpace
 {
-
 public:
 
     //- The components of this vector space

src/OpenFOAM/primitives/VectorSpace/VectorSpaceI.H

@@ -380,6 +380,7 @@ inline typename powProduct<Form, 0>::type pow
     return 1.0;
 }
 
+
 // Form^1 = Form
 template<class Form, class Cmpt, direction Ncmpts>
 inline typename powProduct<Form, 1>::type pow
@@ -428,6 +429,17 @@ inline scalar mag
 }
 
 
+template<class Form, class Cmpt, direction Ncmpts>
+inline VectorSpace<Form, Cmpt, Ncmpts> normalised
+(
+    const VectorSpace<Form, Cmpt, Ncmpts>& vs
+)
+{
+    const scalar s(mag(vs));
+    return s < ROOTVSMALL ? Zero : vs/s;
+}
+
+
 template<class Form, class Cmpt, direction Ncmpts>
 inline VectorSpace<Form, Cmpt, Ncmpts> cmptMultiply
 (
@@ -525,6 +537,7 @@ inline Cmpt cmptAv
     return cmptSum(vs)/Ncmpts;
 }
 
+
 template<class Form, class Cmpt, direction Ncmpts>
 inline Cmpt cmptProduct
 (