Provided by: libmath-gsl-perl_0.39-1build2_amd64 bug

NAME

       Math::GSL::Vector - Functions concerning vectors

SYNOPSIS

           use Math::GSL::Vector qw/:all/;
           my $vec1 = Math::GSL::Vector->new([1, 7, 94, 15 ]);
           my $vec2 = $vec1 * 5;
           my $vec3 = Math::GSL::Vector>new(10);   # 10 element zero vector
           my $vec4 = $vec1 + $vec2;

           # set the element at index 1 to 9
           # and the element at index 3 to 8
           $vec3->set([ 1, 3 ], [ 9, 8 ]);

           my @vec = $vec2->as_list;               # return elements as Perl list

           my $dot_product = $vec1 * $vec2;
           my $length      = $vec2->length;
           my $first       = $vec1->get(0);

           # access raw GSL object to call low-level functions
           my $raw         = $vec1->raw;
           my $element     = gsl_vector_get($raw, 2);

Objected Oriented Interface to GSL Math::GSL::Vector

   Math::GSL::Vector->new()
       Creates a new Vector of the given size.

           my $vector = Math::GSL::Vector->new(3);

       You can also create and set directly the values of the vector like this :

          my $vector = Math::GSL::Vector->new([2,4,1]);

   raw()
       Get the underlying GSL vector object created by SWIG, useful for using gsl_vector_*
       functions which do not have an OO counterpart.

           my $vector    = Math::GSL::Vector->new(3);
           my $gsl_vector = $vector->raw;
           my $stuff      = gsl_vector_get($gsl_vector, 1);

   swap()
       Exchanges the values in the vectors $v with $w by copying.

           my $v = Math::GSL::Vector->new([1..5]);
           my $w = Math::GSL::Vector->new([3..7]);
           $v->swap( $w );

   reverse()
       Reverse the elements in the vector.

           $v->reverse;

   min()
       Returns the minimum value contained in the vector.

          my $vector = Math::GSL::Vector->new([2,4,1]);
          my $minimum = $vector->min;

   max()
       Returns the minimum value contained in the vector.

          my $vector = Math::GSL::Vector->new([2,4,1]);
          my $maximum = $vector->max;

   length()
       Returns the number of elements contained in the vector.

          my $vector = Math::GSL::Vector->new([2,4,1]);
          my $length = $vector->length;

   $v->norm($p)
       Returns the p-norm of $v, which defaults to the Euclidean (p=2) norm when no argument is
       given.

           my $euclidean_distance = $v->norm;

   normalize($p)
       Divide each element of a vector by its norm, hence creating a unit vector.  Returns the
       vector for chaining.  If you just want the value of the norm without changing the vector,
       use "norm()". The default value for $p is 2, which gives the familiar Euclidean distance
       norm.

           my $unit_vector = $vector->normalize(2);

       is the same as

           my $unit_vector = $vector->normalize;

   as_list()
       Gets the content of a Math::GSL::Vector object as a Perl list.

           my $vector = Math::GSL::Vector->new(3);
           ...
           my @values = $vector->as_list;

   get()
       Gets the value of an of a Math::GSL::Vector object.

           my $vector = Math::GSL::Vector->new(3);
           ...
           my @values = $vector->get(2);

       You can also enter an array of indices to receive their corresponding values:

           my $vector = Math::GSL::Vector->new(3);
           ...
           my @values = $vector->get([0,2]);

   set()
       Sets values of an of a Math::GSL::Vector object.

           my $vector = Math::GSL::Vector->new(3);
           $vector->set([1,2], [8,23]);

       This sets the second and third value to 8 and 23.

   copy()
       Returns a copy of the vector, which has the same length and values but resides at a
       different location in memory.

           my $vector = Math::GSL::Vector->new([10 .. 20]);
           my $copy   = $vector->copy;

DESCRIPTION

       Here is a list of all the functions included in this module :

       "gsl_vector_alloc($x)"
        Create a vector of size $x

       "gsl_vector_calloc($x)"
        Create a vector of size $x and initializes all the elements of the vector to zero

       "gsl_vector_alloc_from_block"
       "gsl_vector_alloc_from_vector"
       "gsl_vector_free($v)"
        Free a previously allocated vector $v

       "gsl_vector_view_array($base, $n)"
        This function returns a vector view of an array reference $base. The start of the new
        vector is given by $base and has $n elements. Mathematically, the i-th element of the new
        vector v' is given by, v'(i) = $base->[i] where the index i runs from 0 to $n-1. The
        array containing the elements of v is not owned by the new vector view. When the view
        goes out of scope the original array will continue to exist. The original memory can only
        be deallocated by freeing the original pointer base. Of course, the original array should
        not be deallocated while the view is still in use.

       "gsl_vector_const_view_array($base, $n)"
        This function is equivalent to gsl_vector_view_array but can be used for arrays which are
        declared const.

       "gsl_vector_view_array_with_stride($base, $stride, $n)"
        This function returns a vector view of an array reference $base with an additional
        $stride argument. The subvector is formed in the same way as for gsl_vector_view_array
        but the new vector has $n elements with a step-size of $stride from one element to the
        next in the original array. Mathematically, the i-th element of the new vector v' is
        given by, v'(i) = $base->[i*$stride] where the index i runs from 0 to $n-1. Note that the
        view gives direct access to the underlying elements of the original array. A vector view
        $view can be passed to any subroutine which takes a vector argument just as a directly
        allocated vector would be, using $view->{vector}.

       "gsl_vector_const_view_array_with_stride($base, $stride, $n)"
        This function is equivalent to gsl_vector_view_array_with_stride but can be used for
        arrays which are declared const.

       "gsl_vector_subvector($v, $offset, $n)"
        Return a vector_view type which contains a subvector of $v, with a size of $size,
        starting from the $offset position

       "gsl_vector_subvector_with_stride($v, $offset, $stride, $size)"
        Return a vector_view type which contains a subvector of $v, with a size of $size,
        starting from the $offset position and with a $stride step between each element of $v

       "gsl_vector_const_subvector"
       "gsl_vector_get($v, $i)"
        Return the $i-th element of a raw vector $v, where $v is a Math::GSL::Vector object. For
        example:

            my $third_element = gsl_vector_get($v->raw, 3);

       "gsl_vector_set($v, $i, $x)"
        Return the vector $v with his $i-th element set to $x

       "gsl_vector_ptr"
       "gsl_vector_const_ptr"
       "gsl_vector_set_zero($v)"
         set all the elements of $v to 0

       "gsl_vector_set_all($v, $x)"
        set all the elements of $v to $x

       "gsl_vector_set_basis($v, $i)"
        set all the elements of $v to 0 except for the $i-th element which is set to 1 and return
        0 if the operation succeeded, 1 otherwise.

       "gsl_vector_fread($file, $v)"
        This function reads into the vector $v from the open stream $file opened with gsl_fopen
        function from the Math::GSL module in binary format. The vector $v must be preallocated
        with the correct length since the function uses the size of $v to determine how many
        bytes to read. The return value is 0 for success and 1 if there was a problem reading
        from the file.

       "gsl_vector_fwrite($file, $v)"
        This function writes the elements of the vector $v to the stream $file opened with
        gsl_fopen function from the Math::GSL module in binary format. The return value is 0 for
        success and 1 if there was a problem writing to the file. Since the data is written in
        the native binary format it may not be portable between different architectures.

       "gsl_vector_fscanf($file, $v)"
        This function reads formatted data from the stream $file opened with gsl_fopen function
        from the Math::GSL module into the vector $v. The vector $v must be preallocated with the
        correct length since the function uses the size of $v to determine how many numbers to
        read. The function returns 0 for success and 1 if there was a problem reading from the
        file.

       "gsl_vector_fprintf($file, $v, $format)"
        This function writes the elements of the vector $v line-by-line to the stream $file
        opened with gsl_fopen function from the Math::GSL module using the format specifier
        $format, which should be one of the "%g", "%e" or "%f" formats for floating point numbers
        and "%d" for integers. The function returns 0 for success and 1 if there was a problem
        writing to the file.

       "gsl_vector_memcpy($dest, $src)"
        This function copies the elements of the vector $src into the vector $dest and return 0
        if the operation succeeded, 1 otherwise. The two vectors must have the same length.

       "gsl_vector_reverse($v)"
        reverse the order of the elements of the vector $v and return 0 if the operation
        succeeded, 1 otherwise

       "gsl_vector_swap($v, $v2)"
        swap the values of the vectors $v and $v2 and return 0 if the operation succeeded, 1
        otherwise

       "gsl_vector_swap_elements($v, $i, $j)"
        permute the elements at position $i and $j in the vector $v and return 0 if the operation
        succeeded, 1 otherwise.

       "gsl_vector_max($v)"
         return the maximum value in the vector $v

       "gsl_vector_min($v)"
        return the minimum value in the vector $v

       "gsl_vector_minmax($v)"
        return two values, the first is the minimum value in the vector $v and the second is the
        maximum value.

       "gsl_vector_max_index($v)"
        return the position of the maximum value in the vector $v

       "gsl_vector_min_index($v)"
        return the position of the minimum value in the vector $v

       "gsl_vector_minmax_index"
        return two values, the first is the position of the minimum value in the vector $v and
        the second is the position of the maximum value.

       "gsl_vector_add($v, $v2)"
        add the elements of $v2 to the elements of $v, the two vectors must have the same length
        and return 0 if the operation succeeded, 1 otherwise.

       "gsl_vector_sub($v, $v2)"
        subtract the elements of $v2 from the elements of $v, the two vectors must have the same
        length and return 0 if the operation succeeded, 1 otherwise.

       "gsl_vector_mul($v, $v2)"
        multiply the elements of $v by the elements of $v2, the two vectors must have the same
        length and return 0 if the operation succeeded, 1 otherwise.

       "gsl_vector_div($v, $v2)"
        divides the elements of $v by the elements of $v2, the two vectors must have the same
        length and return 0 if the operation succeeded, 1 otherwise.

       "gsl_vector_scale($v, $x)"
        multiplty the elements of the vector $v by a constant $x and return 0 if the operation
        succeeded, 1 otherwise.

       "gsl_vector_add_constant($v, $x)"
        add a constant $x to the elements of the vector $v and return 0 if the operation
        succeeded, 1 otherwise.

       "gsl_vector_isnull($v)"
        verify if all the elements of the vector $v are null, return 0 if it's the case, 1
        otherwise.

       "gsl_vector_ispos($v)"
        verify if all the elements of the vector $v are positive, return 0 if it's the case, 1
        otherwise.

       "gsl_vector_isneg($v)"
        verify if all the elements of the vector $v are negative, return 0 if it's the case, 1
        otherwise.

       "gsl_vector_isnonneg($v)"
        verify if all the elements the vector $v are not negative, return 0 if it's the case, 1
        otherwise.

       Precision on the vector_view type : every modification you'll make on a vector_view will
       also modify the original vector.  For example, the following code will zero the even
       elements of the vector $v of length $size, while leaving the odd elements untouched :

       "$v_even= gsl_vector_subvector_with_stride ($v, 0, 2, $size/2);"
       "gsl_vector_set_zero ($v_even->{vector});"

       For more information on the functions, we refer you to the GSL offcial documentation:
       <http://www.gnu.org/software/gsl/manual/html_node/>

EXAMPLES

       Here is an example using both interfaces.

           use Math::GSL::Vector qw/:all/;

           print "We'll create this vector : [0,1,4,9,16] \n";
           my $vector = Math::GSL::Vector->new([0,1,4,9,16]);
           my ($min, $max) = gsl_vector_minmax_index($vector->raw);

           print "We then check the index value of the maximum and minimum values of the vector. \n";
           print "The index of the maximum should be 4 and we received $max \n";
           print "The index of the minimum should be 0 and we received $min \n";
           print "We'll then swap the first and the third elements of the vector \n";

           gsl_vector_swap_elements($vector->raw, 0, 3);
           my @got = $vector->as_list;
           print "The vector should now be like this : [9,1,4,0,16] \n";
           print "and we received : [ @got ]\n";

AUTHORS

       Jonathan "Duke" Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>

COPYRIGHT AND LICENSE

       Copyright (C) 2008-2011 Jonathan "Duke" Leto and Thierry Moisan

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.