Vecpy Documentation

Vecpy is a Python library for creating, manipulating, and using 2D and 3D vectors. Vecpy does this numerically, not symbolically, as it designed for use in projects which require a foundation for working with vectors.

Vecpy requires both numpy and matplotlib to be installed.

Installation

To install Vecpy use:

pip install vecpy-cfm

Tutorial

In this tutorial we will cover how to create 3-Dimensional vectors and use them to solve a typical Linear Algebra I style question. Let's answer the following question:

Show that $S = {(3, 1, 2), (2, 3, 0), (1, 0, 1) }$ is a basis for $\mathbb{R}^3$, and find the coordinate vector of $(8, -5, 10), (2,8,10),$ and $(1, 0, 1)$ in the basis of $S$.

First we should create the 3 vectors which form the basis

>>> import vecpy as vp
>>> vec1 = vp.Vec3d(3, 1, 2)
>>> vec2 = vp.Vec3d(2, 3, 0)
>>> vec3 = vp.Vec3d(1, 0, 1)
>>> vec1, vec2, vec3
(Vec3d(3, 1, 2), Vec3d(2, 3, 0), Vec3d(1, 0, 1))

Now that we have our vectors, we can create a basis of 3-D vectors using vp.Basis3() which takes three 3-D vectors as inputs.
Checking if our basis $S$ is indeed a basis, we simply use the isbasis() instance method.

>>> S = vp.Basis3(vec1, vec2, vec3)
>>> S.isbasis()
True

That answers the first part of the question. To find the coordinate vectors of $(8, -5, 10), (2,8,10),$ and $(1, 0, 1)$, we simply use the coordinate_vector_in_base() method on each of our vectors.

>>> print(vp.Vec3d(8, -5, 10).coordinate_vector_in_base(S))
Vec3d(4.0, -3.0, 2.0)
>>> print(vp.Vec3d(2, 8, 10).coordinate_vector_in_base(S))
Vec3d(-40.0, 16.0, 90.0)
>>> print(vp.Vec3d(1, 0, 1).coordinate_vector_in_base(S))
Vec3d(0.0, 0.0, 1.0)

How-to Guides

How to create a 3-Dimensional Vector

3D Vectors in Vecpy are stored as Vec3d objects which can be created using the following initializer:

>>> import vecpy as  vp
>>> first_3d_vector = vp.Vec3d(1, 2, 3)
>>> second_3d_vector = vp.Vec3d(2, 3, 1)

How to create a 2-Dimensional Vector

2D Vectors in Vecpy are stored as Vec2d objects which can be created using the following initializer:

>>> import vecpy as  vp
>>> first_2d_vector = vp.Vec2d(0, 1)
>>> second_2d_vector = vp.Vec2d(10, 8.5)

How to create a Basis of 3-D Vectors

Bases for $\mathbb{R}^3$ in Vecpy are stored as Basis3 objects which hold three 3-D vectors (Vec3d objects) within them. A Basis3 object is created using the following initializer:

import vecpy as vp
>>> vec1 = vp.Vec3d(3, 1, 2)
>>> vec2 = vp.Vec3d(2, 3, 0)
>>> vec3 = vp.Vec3d(1, 0, 1)
>>> my_3d_basis = vp.Basis3(vec1, vec2, vec3)
>>> print(my_3d_basis)
{ Vec3d(3, 1, 2), Vec3d(2, 3, 0), Vec3d(1, 0, 1) }

How to create a Basis of 2-D Vectors

Bases for $\mathbb{R}^2$ in Vecpy are stored as Basis2 objects which hold two 2-D vectors (Vec2d objects) within them Basis2object is created using the following initializer:

>>> import vecpy as vp
>>> vec1 = vp.Vec2d(2, 1)
>>> vec2 = vp.Vec2d(9, 2)
>>> my_2d_basis = vp.Basis2(vec1, vec2)
>>> print(my_2d_basis)
{ Vec2d(2, 1), Vec2d(9, 2) }

How to Change the Error Margin for Equality

Sometimes, due to floating point errors, two vectors which should be equal may not be shown as such by a Boolean. By default, Vecpy checks if two vectors are equal up to the 7th decimal place. To change this error margin, use the sete_equality_error command.

>>> import vecpy as vp
>>> vp.set_equality_error(4)  # changes the error margin from 7 decimal places to 4

Note, this command only takes positive integers as input!

Explanation

How the isbasis() command works

In order for a set of 3 vectors to be a basis for $\mathbb{R}^3$, it is required that the set is both linearly independent and spans $\mathbb{R}^3$. Usually, to find whether these two properties are true requires using simultaneous equations of three variables. I.e. one must show that for a basis $S = { \underline{u}, \underline{v}, \underline{w}}$ with $\underline{u}, \underline{v}, \underline{w} \in \mathbb{R}^3$, there exist some $k_1, k_2, k_3 \in \mathbb{R}$ such that any other vector $\underline{R} = k_1\underline{u} + k_2\underline{v} + k_3\underline{w}$. Also, one must show that $\underline{R} = (0,0,0) \iff k_1=k_2=k_3 = 0$.

However, a property of sets of three 3D vectors is that in fact, $$\underline{u} \cdot (\underline{v} \times \underline{w}) = \det(\underline{u},\underline{v}, \underline{w})$$ and if the determinant of the three vectors is not equal to zero, then those three vectors must be linearly independent and span $\mathbb{R}^3$. This is why the isbasis command runs the line

return self.v1 * (self.v2 @ self.v3) != 0

The isbasis() command works similarly in 2D, where we check that the determinant of the two vectors in a Basis2 object is not zero. Equivalently, this means checking that

return self.v1.x * self.v2.y != self.v2.x * self.v1.y

Brief Explanation of the orthogonal_basis_from_forward_vector() Command

This command effectively rotates the entire cartesian plane in such a way that the input vector becomes the new $z$ direction. It does this by first normalising the given vector, and taking the cross product of that with the world up vector $(0,0,1)$, this creates a vector which is at a right angle to the given forward vector. Coincidentally this vector is also always pointing along the XY-plane. With our forward vector and our "right" vector, we define the "up" vector by taking the cross product of the former two vectors, which creates a third vector perpendicular to both.

Hence, the three vectors we have created are all at right angles to each other, just like the three standard unit vectors, $\underline{e_x} = (1, 0, 0), \underline{e_y} = (0, 1, 0), $ and $\underline{e_z} = (0, 0, 1)$.

Reference

This section aims to exhaustively document every command available in Vecpy, as well as how to create an object of each class.

Vectors

3D Vectors

Using our 3D vectors from the How To section, we can perform a variety of operations on them:

Operation	Code	Output
Printing	print(first_3d_vector)	Vec3d(1, 2, 3)
Addition and Subtraction	print(first_3d_vector + second_3d_vector)	Vec3d(3, 5, 4)
Dot Product	print(first_3d_vector * second_3d_vector)	11
Cross Product	print(first_3d_vector @ second_3d_vector)	Vec3d(-7, 5, -1)
Multiplication by a Scalar Constant	print(5 * first_3d_vector)	Vec3d(5, 10, 15)
Modulus	print(abs(first_3d_vector))	3.7416573867739413
Normalisation	print(first_3d_vector.normalise())	Vec3d(0.2673, 0.5345, 0.8018)
Coordinate Vector in Basis	See Bases section

2D Vectors

Using our 2D vectors from the How To section , we can perform a variety of operations on them:

Operation	Code	Output
Printing	print(first_2d_vector)	Vec2d(0, 1)
Addition and Subtraction	print(first_2d_vector + second_2d_vector)	Vec2d(10, 9.5)
Dot Product	print(first_2d_vector * second_2d_vector)	8.5
Multiplication by a Scalar Constant	print(5 * first_2d_vector)	Vec2d(0, 5)
Modulus	print(abs(first_2d_vector))	1
Normalisation	print(second_2d_vector.normalise())	Vec2d(0.7619393177594592, 0.6476484200955404)
Coordinate Vector in Basis	See Bases section

Bases

Using our bases from the How To section, we can ensure that they really are mathematical bases (linearly independent and span $\mathbb{R}^3$), using the isbasis() command:

>>> print(my_3d_basis.isbasis())
True

Given a 3-D Vector, one can find the coordinate vector of the given vector in a basis using the coordinate_vector_in_base() command.

>>> my_vector = vp.Vec3d(2, 8, 10)
>>> print(my_vector.coordinate_vector_in_base(my_3d_basis))
Vec3d(-40.0, 16.0, 90.0)

These commands work for both 2D and 3D vectors.

Other Vector Operations

Given two vectors v1 and v2 (can be either 3-D or 2-D, but both must be of the same type!) there are several operation which involve the two vectors.

Operation	Code	Output
Projection	vp.proj(v1, v2)	Returns $\text{proj}_a b = \frac{a \cdot b}{|a|^2}a$ with $a$ = v1and $b$ = v2. i.e. the projection of v2 onto v1.
Rejection	vp.reject(v1, v2)	Returns $\text{rej}_a b = a - \text{proj}_a b$ with $a$ = v1and $b$ = v2. i.e. the rejection of v2 from v1.
Angle between Vectors	vp.angle(v1, v2)	Returns the angle between v1 and v2 in radians.
Checking for Perpendicularity	vp.isperp(v1, v2)	Returns a Boolean representing whether the two vectors are perpendicular (True) or not (False).

Visual Representations of Vectors

Sometimes it is useful to see what your vectors look like. Vecpy can be used to display a simple representation of what an array of vectors looks like if they all begin in the origin. This is done using the display() command, which takes one parameter, being a list of vectors, all the same type (i.e. either Vec2d or Vec3d).

>>> import vecpy as vp
>>> vec1 = vp.Vec3d(3, 1, 2)
>>> vec2 = vp.Vec3d(2, 3, 0)
>>> vec3 = vp.Vec3d(1, 0, 1)
>>> vp.display([vec1, vec2, vec3]) #doctest: +SKIP

Output:

The display() command used matplotlib for its functionality. For more info on using this package to display vectors, see the Matplotlib website