nubs/vectorix

A vector library.

vectorix

A PHP vector library., _(*1)

, _(*2)

, _(*3)

, _(*4)

Requirements

This library requires PHP 5.6, or newer., _(*5)

Installation

This package uses composer so you can just add nubs/vectorix as a dependency to your composer.json file or execute the following command:, _(*6)

composer require nubs/vectorix

Vector

The Vector class represents an immutable Euclidean vector and its associated operations., _(*7)

All operations on the vector will return a new vector with the results. For example,, _(*8)

$a = new \Nubs\Vectorix\Vector([1, 5]);
$b = $a->multiplyByScalar(2);

// $a is not changed.  Once a vector is created, it is immutable.
assert($a->components() === [1, 5]);

// Results of operations (like multiplyByScalar) are returned where they can be
// used.
assert($b->components() === [2, 10]);

The keys of a vector's components are preserved through operations. Because of this, vectors MUST have the same keys in order to use them together. For example,, _(*9)

$a = new \Nubs\Vectorix\Vector(['i' => 5, 'j' => 9]);
$b = new \Nubs\Vectorix\Vector(['i' => 1, 'j' => 2]);

$c = $a->add($b);
var_dump($c->components());
// array(2) {
//   'i' =>
//   int(6)
//   'j' =>
//   int(11)
// }

$d = new \Nubs\Vectorix\Vector([5, 9]);

$e = $c->subtract($d);
// PHP Fatal error:  Uncaught exception 'Exception' with message 'The vectors'
// components must have the same keys'

Creating a Vector

Constructor

/**
 * @param array<int|float> $components The components of the vector.
 */
public function __construct(array $components)

The primary method for creating a vector is, of course, the constructor. It takes an array of the components of the vector (e.g., x, y, and z components). Components can be integers, floats, or a combination thereof., _(*10)

// Create a 3-dimensional vector.
$a = new \Nubs\Vectorix\Vector([2, 3, -1]);

// Create a 2-dimension vector with named components.
$b = new \Nubs\Vectorix\Vector(['x' => 1.7, 'y' => -5.3]);

Null Vectors

/**
 * @param int $dimension The dimension of the vector to create.  Must be at least 0.
 * @return self The zero-length vector for the given dimension.
 * @throws Exception if the dimension is less than zero.
 */
public static function nullVector($dimension)

When needing a null vector (a vector with zero magnitude), this static method makes creating one easy. All of its components will be initialized to the integer 0., _(*11)

$a = \Nubs\Vectorix\Vector::nullVector(3);
var_dump($a->components());
// array(3) {
//   [0] =>
//   int(0)
//   [1] =>
//   int(0)
//   [2] =>
//   int(0)
// }

Properties of a Vector

Components

/**
 * @return array<int|float> The components of the vector.
 */
public function components()

The components method returns the components of the vector with keys kept intact., _(*12)

$a = new \Nubs\Vectorix\Vector([7, 4]);
var_dump($a->components());
// array(2) {
//   [0] =>
//   int(7)
//   [1] =>
//   int(4)
// }

Dimension

/**
 * @return int The dimension/cardinality of the vector.
 */
public function dimension()

The dimension of a vector is the number of components in it. This is also referred to as "cardinality"., _(*13)

$a = new \Nubs\Vectorix\Vector([5.2, 1.4]);
var_dump($a->dimension());
// int(2)

Length

/**
 * @return float The length/magnitude of the vector.
 */
public function length()

The length, or magnitude of a vector is the distance from the origin to the point described by the vector., _(*14)

It is always returned as a floating point number., _(*15)

$a = new \Nubs\Vectorix\Vector([3, 4]);
var_dump($a->length());
// double(5)

Tests

Equality

/**
 * @param self $b The vector to check for equality.
 * @return bool True if the vectors are equal and false otherwise.
 */
public function isEqual(self $b)

The isEqual method tests to see if the two vectors are equal. They are only equal if their components are identical (including same keys)., _(*16)

$a = new \Nubs\Vectorix\Vector([1, 2]);
$b = new \Nubs\Vectorix\Vector([1, 2]);
$c = new \Nubs\Vectorix\Vector([5, 7]);

var_dump($a->isEqual($b));
// bool(true)

var_dump($a->isEqual($c));
// bool(false)

Same Dimension

/**
 * @param self $b The vector to check against.
 * @return bool True if the vectors are of the same dimension, false otherwise.
 */
public function isSameDimension(self $b)

The isSameDimension method tests to see if the two vectors both have the same dimension., _(*17)

$a = new \Nubs\Vectorix\Vector([1, 2]);
$b = new \Nubs\Vectorix\Vector([5, 1]);
$c = new \Nubs\Vectorix\Vector([5, 8, 2]);

var_dump($a->isSameDimension($b));
// bool(true)

var_dump($a->isSameDimension($c));
// bool(false)

Same Vector Space

/**
 * @param self $b The vector to check against.
 * @return bool True if the vectors are the same vector space, false otherwise.
 */
public function isSameVectorSpace(self $b)

The isSameVectorSpace method tests to see if the two vectors both belong to the same vector space., _(*18)

The vector space is defined in this library by the dimension of the vectors, and the keys of the vectors' components., _(*19)

$a = new \Nubs\Vectorix\Vector([1, 2]);
$b = new \Nubs\Vectorix\Vector([5, 1]);
$c = new \Nubs\Vectorix\Vector([2, 1, 7]);
$d = new \Nubs\Vectorix\Vector(['x' => 3, 'y' => 2]);

var_dump($a->isSameVectorSpace($b));
// bool(true)

var_dump($a->isSameVectorSpace($c));
// bool(false)

var_dump($a->isSameVectorSpace($d));
// bool(false)

Basic Operations

Addition

/**
 * @param self $b The vector to add.
 * @return self The sum of the two vectors.
 * @throws Exception if the vectors are not in the same vector space.
 */
public function add(self $b)

The add method performs vector addition. The two vectors must belong to the same vector space., _(*20)

The result is a new vector where each component is the sum of the corresponding components in the two vectors., _(*21)

$a = new \Nubs\Vectorix\Vector([7, -2]);
$b = new \Nubs\Vectorix\Vector([-1, 5]);

$c = $a->add($b);
var_dump($c->components());
// array(2) {
//   [0] =>
//   int(6)
//   [1] =>
//   int(3)
// }

Subtraction

/**
 * @param self $b The vector to subtract from this vector.
 * @return self The difference of the two vectors.
 * @throws Exception if the vectors are not in the same vector space.
 */
public function subtract(self $b)

The subtract method performs vector subtraction. The two vectors must belong to the same vector space., _(*22)

The result is a new vector where each component is the difference of the corresponding components in the two vectors, _(*23)

$a = new \Nubs\Vectorix\Vector([5, 7]);
$b = new \Nubs\Vectorix\Vector([-1, 6]);

$c = $a->subtract($b);
var_dump($c->components());
// array(2) {
//   [0] =>
//   int(6)
//   [1] =>
//   int(1)
// }

Scalar Multiplication

/**
 * @param int|float $scalar The real number to multiply by.
 * @return self The result of the multiplication.
 */
public function multiplyByScalar($scalar)

The multiplyByScalar function performs scalar multiplication of a vector with a scalar value., _(*24)

The result is a new vector where each component is the multiplication of that component with the scalar value., _(*25)

$a = new \Nubs\Vectorix\Vector([2, 8, -1]);
$b = 5;

$c = $a->multiplyByScalar($b);
var_dump($c->components());
// array(3) {
//   [0] =>
//   int(10)
//   [1] =>
//   int(40)
//   [2] =>
//   int(-5)
// }

Scalar Division

/**
 * @param int|float $scalar The real number to divide by.
 * @return self The result of the division.
 * @throws Exception if the $scalar is 0.
 */
public function divideByScalar($scalar)

The divideByScalar function performs scalar division of a vector with a scalar value. This is the same as multiplying the vector by 1 / scalarValue., _(*26)

Trying to divide by zero will throw an exception., _(*27)

The result is a new vector where each component is the division of that component with the scalar value., _(*28)

$a = new \Nubs\Vectorix\Vector([4, 12, -8]);
$b = 2;

$c = $a->divideByScalar($b);
var_dump($c->components());
// array(3) {
//   [0] =>
//   double(2)
//   [1] =>
//   double(6)
//   [2] =>
//   double(-4)
// }

Dot Product

/**
 * @param self $b The vector to multiply with.
 * @return int|float The dot product of the two vectors.
 * @throws Exception if the vectors are not in the same vector space.
 */
public function dotProduct(self $b)

The dotProduct method performs a dot product between two vectors. The two vectors must belong to the same vector space., _(*29)

$a = new \Nubs\Vectorix\Vector([1, 3, -5]);
$b = new \Nubs\Vectorix\Vector([4, -2, -1]);
var_dump($a->dotProduct($b));
// int(3)

Cross Product

/**
 * @param self $b The vector to multiply with.
 * @return self The cross product of the two vectors.
 * @throws Exception if the vectors are not 3-dimensional.
 * @throws Exception if the vectors are not in the same vector space.
 */
public function crossProduct(self $b)

The crossProduct method computes the cross product between two three-dimensional vectors. The resulting vector is perpendicular to the plane containing the two vectors., _(*30)

$a = new \Nubs\Vectorix\Vector([2, 3, 4]);
$b = new \Nubs\Vectorix\Vector([5, 6, 7]);

$c = $a->crossProduct($b);
var_dump($c->components());
// array(3) {
//   [0] =>
//   int(-3)
//   [1] =>
//   int(6)
//   [2] =>
//   int(-3)
// }

Other Operations

Normalization

/**
 * @return self The normalized vector.
 * @throws Exception if the vector length is zero.
 */
public function normalize()

The normalize method returns the unit vector with the same direction as the original vector., _(*31)

$a = new \Nubs\Vectorix\Vector([3, 3]);
$b = $a->normalize();
var_dump($b->components());
// array(2) {
//   [0] =>
//   double(0.70710678118655)
//   [1] =>
//   double(0.70710678118655)
// }

Projection

/**
 * @param self $b The vector to project this vector onto.
 * @return self The vector projection of this vector onto $b.
 * @throws Exception if the vector length of $b is zero.
 * @throws Exception if the vectors are not in the same vector space.
 */
public function projectOnto(self $b)
/*

The projectOnto method computes the vector projection of one vector onto another. The resulting vector will be colinear with $b., _(*32)

$a = new \Nubs\Vectorix\Vector([4, 0]);
$b = new \Nubs\Vectorix\Vector([3, 3]);

$c = $a->projectOnto($b);
var_dump($c->components());
// array(2) {
//   [0] =>
//   double(2)
//   [1] =>
//   double(2)
// }

Scalar Triple Product

/**
 * @param self $b The second vector of the triple product.
 * @param self $c The third vector of the triple product.
 * @return int|float The scalar triple product of the three vectors.
 * @throws Exception if the vectors are not 3-dimensional.
 * @throws Exception if the vectors are not in the same vector space.
 */
public function scalarTripleProduct(self $b, self $c)

The scalarTripleProduct method computes the scalar triple product. This value represents the volume of the parallelepiped defined by the three vectors., _(*33)

$a = new \Nubs\Vectorix\Vector([-2, 3, 1]);
$b = new \Nubs\Vectorix\Vector([0, 4, 0]);
$c = new \Nubs\Vectorix\Vector([-1, 3, 3]);

var_dump($a->scalarTripleProduct($b, $c));
// int(-20)

Vector Triple Product

/**
 * @param self $b The second vector of the triple product.
 * @param self $c The third vector of the triple product.
 * @return self The vector triple product of the three vectors.
 * @throws Exception if the vectors are not 3-dimensional.
 * @throws Exception if the vectors are not in the same vector space.
 */
public function vectorTripleProduct(self $b, self $c)

The vectorTripleProduct method computes the vector triple product., _(*34)

$a = new \Nubs\Vectorix\Vector([-2, 3, 1]);
$b = new \Nubs\Vectorix\Vector([0, 4, 0]);
$c = new \Nubs\Vectorix\Vector([-1, 3, 3]);

$d = $a->vectorTripleProduct($b, $c);
var_dump($d->components());
// array(3) {
//   [0] =>
//   int(12)
//   [1] =>
//   int(20)
//   [2] =>
//   int(-36)
// }

Angle Between Vectors

/**
 * @param self $b The vector to compute the angle between.
 * @return float The angle between the two vectors in radians.
 * @throws Exception if either of the vectors are zero-length.
 * @throws Exception if the vectors are not in the same vector space.
 */
public function angleBetween(self $b)

The angleBetween method computes the angle between two vectors in radians., _(*35)

$a = new \Nubs\Vectorix\Vector(array(0, 5));
$b = new \Nubs\Vectorix\Vector(array(3, 3));
var_dump($a->angleBetween($b));
// double(0.78539816339745)

License

vectorix is licensed under the MIT license. See LICENSE for the full license text., _(*36)