Vectors and Vector Arrays

bewegung offers vectors and vector arrays. Both of them are available in 2D and 3D variants. Both vectors and vector arrays can interact with each other as well as with matrices.

Note

Besides simple vector algebra, a lot of bewegung’s functions and methods expect geometric input using vector objects.

Vector Classes

The vector classes describe individual vectors in 2D and 3D space. Vectors are “statically typed”, i.e. all components are of one single type, and use Python number types (sub-classes of numbers.Number). The data type of a vector is exposed through its dtype property.

The Vector base class

class bewegung.Vector(meta=None)

Abstract base class for all vector types.

Not intended to be instantiated.

Parameters

meta (Optional[Dict[str, Union[str, bytes, Number]]]) – A dict holding arbitrary metadata

property meta: Dict[str, Union[str, bytes, numbers.Number]]

meta data dict

Return type

Dict[str, Union[str, bytes, Number]]

The Vector2D class

class bewegung.Vector2D(x, y, dtype=None, meta=None)

A single vector in 2D space.

Mutable.

Parameters

  • x (Number) – x component. Must have the same type like y.

  • y (Number) – y component. Must have the same type like x.

  • dtype (Optional[Type[Number]]) – Data type. Derived from x and y if not explicitly provided.

  • meta (Optional[Dict[str, Union[str, bytes, Number]]]) – A dict holding arbitrary metadata.

__add__(other)

Add operation between vectors or a vector and a vector array

Parameters

other (Any) – Another vector

Return type

Union[Vector2DABC, NotImplementedType]

__eq__(other)

Equality check between vectors

Parameters

other (Any) – Another vector

Return type

Union[bool, NotImplementedType]

__matmul__(other)

Scalar product between vectors

Parameters

other (Any) – Another vector

Return type

Union[Number, NotImplementedType]

__mod__(other)

Is-close check (relevant for dtype float) between vectors

Parameters

other (Any) – Another vector

Return type

Union[bool, NotImplementedType]

__mul__(other)

Multiplication with scalar

Parameters

other (Any) – A number

Return type

Union[Vector2DABC, NotImplementedType]

__repr__()

String representation for interactive use

Return type

str

__sub__(other)

Substract operator between vectors or a vector and a vector array

Parameters

other (Any) – Another vector

Return type

Union[Vector2DABC, NotImplementedType]

property angle: float

The vector’s angle in radians, computed on demand

Return type

float

as_dtype(dtype)

Generates new vector with desired data type and returns it.

Parameters

dtype (Type[Number]) – Desired data type of new vector

Return type

Vector2DABC

as_ndarray(dtype='f4')

Exports vector as a numpy.ndarry object, shape (2,).

Parameters

dtype (Union[str, Type[Number], dtype]) – Desired numpy data type of new vector

Return type

ndarray

as_polar_tuple()

Exports vector as a tuple of polar coordinates

Return type

Tuple[float, float]

as_tuple()

Exports vector as a tuple

Return type

Tuple[TypeVar(N, bound= Number), TypeVar(N, bound= Number)]

copy()

Copies vector & meta data

Return type

Vector2DABC

property dtype: Type[numbers.Number]

(Python) data type of vector components

Return type

Type[Number]

classmethod from_polar(cls, radius, angle, meta=None)

Generates vector object from polar coordinates

Parameters

  • radius (Number) – A radius

  • angle (Number) – An angle in radians

  • meta (Optional[Dict[str, Union[str, bytes, Number]]]) – A dict holding arbitrary metadata

Return type

Vector2DABC

property mag: float

The vector’s magnitude, computed on demand

Return type

float

mul(scalar)

In-place multiplication with scalar

Parameters

scalar (Number) – Vector is multiplied with this number.

property ndim: int

Number of dimensions

Return type

int

update(x, y)

Updates vector components

Parameters

  • x (Number) – x component. Must have the same type like y.

  • y (Number) – y component. Must have the same type like x.

update_from_vector(other)

Updates vector components with data from another vector

Parameters

other (Vector2DABC) – Another vector. Remains unchanged.

property x: numbers.Number

x component

Return type

Number

property y: numbers.Number

y component

Return type

Number

The Vector3D class

class bewegung.Vector3D(x, y, z, dtype=None, meta=None)

A single vector in 3D space.

Mutable.

Parameters

  • x (Number) – x component. Must have the same type like y and z.

  • y (Number) – y component. Must have the same type like x and z.

  • z (Number) – z component. Must have the same type like x and y.

  • dtype (Optional[Type[Number]]) – Data type. Derived from x, y and z if not explicitly provided.

  • meta (Optional[Dict[str, Union[str, bytes, Number]]]) – A dict holding arbitrary metadata.

__add__(other)

Add operation between vectors or a vector and a vector array

Parameters

other (Any) – Another vector

Return type

Union[Vector3DABC, NotImplementedType]

__eq__(other)

Equality check between vectors

Parameters

other (Any) – Another vector

Return type

Union[bool, NotImplementedType]

__matmul__(other)

Scalar product between vectors

Parameters

other (Any) – Another vector

Return type

Union[Number, NotImplementedType]

__mod__(other)

Is-close check (relevant for dtype float) between vectors

Parameters

other (Any) – Another vector

Return type

Union[bool, NotImplementedType]

__mul__(other)

Multiplication with scalar

Parameters

other (Any) – A number

Return type

Union[Vector3DABC, NotImplementedType]

__repr__()

String representation for interactive use

Return type

str

__sub__(other)

Substract operator between vectors or a vector and a vector array

Parameters

other (Any) – Another vector

Return type

Union[Vector3DABC, NotImplementedType]

as_dtype(dtype)

Generates new vector with desired data type and returns it.

Parameters

dtype (Type[Number]) – Desired data type of new vector

Return type

Vector3DABC

as_geographic_tuple()

Exports vector as a tuple of geographic coordinates (radius, lon, lat)

Return type

Tuple[float, float, float]

as_ndarray(dtype='f4')

Exports vector as a numpy.ndarry object, shape (3,).

Parameters

dtype (Union[str, Type[Number], dtype]) – Desired numpy data type of new vector

Return type

ndarray

as_polar_tuple()

Exports vector as a tuple of polar coordinates

Return type

Tuple[float, float, float]

as_tuple()

Exports vector as a tuple

Return type

Tuple[TypeVar(N, bound= Number), TypeVar(N, bound= Number), TypeVar(N, bound= Number)]

copy()

Copies vector & meta data

Return type

Vector3DABC

property dtype: Type[numbers.Number]

(Python) data type of vector components

Return type

Type[Number]

classmethod from_geographic(cls, radius, lon, lat, meta=None)

Generates vector object from geographic polar coordinates

Parameters

  • radius (Number) – A radius

  • lon (Number) – An angle in degree

  • lat (Number) – An angle in degree

  • meta (Optional[Dict[str, Union[str, bytes, Number]]]) – A dict holding arbitrary metadata

Return type

Vector3DABC

classmethod from_polar(cls, radius, theta, phi, meta=None)

Generates vector object from polar coordinates

Parameters

  • radius (Number) – A radius

  • theta (Number) – An angle in radians

  • phi (Number) – An angle in radians

  • meta (Optional[Dict[str, Union[str, bytes, Number]]]) – A dict holding arbitrary metadata

Return type

Vector3DABC

property lat: float

The vector’s geographic latitude in degree, computed on demand

Return type

float

property lon: float

The vector’s gepgraphic longitude in degree, computed on demand

Return type

float

property mag: float

The vector’s magnitude, computed on demand

Return type

float

mul(scalar)

In-place multiplication with scalar

Parameters

scalar (Number) – Vector is multiplied with this number.

property ndim: int

Number of dimensions

Return type

int

property phi: float

The vector’s phi in radians, computed on demand

Return type

float

property theta: float

The vector’s theta in radians, computed on demand

Return type

float

update(x, y, z)

Updates vector components

Parameters

  • x (Number) – x component. Must have the same type like y and z.

  • y (Number) – y component. Must have the same type like x and z.

  • z (Number) – z component. Must have the same type like x and y.

update_from_vector(other)

Updates vector components with data from another vector

Parameters

other (Vector3DABC) – Another vector. Remains unchanged.

property x: numbers.Number

x component

Return type

Number

property y: numbers.Number

y component

Return type

Number

property z: numbers.Number

z component

Return type

Number

Vector Array Classes

The vector array classes describe arrays of individual vectors in 2D and 3D space. Vector arrays are “statically typed” and use numpy arrays for storing data. Just like numpy.ndarray objects, they expose a dtype property.

The VectorArray base class

class bewegung.VectorArray(meta=None)

Abstract base class for all vector array types.

Not intended to be instantiated.

Parameters

meta (Optional[Dict[str, ndarray]]) – A dict holding arbitrary metadata

property meta: Dict[str, numpy.ndarray]

meta data dict

Return type

Dict[str, ndarray]

The VectorArray2D class

class bewegung.VectorArray2D(x, y, dtype=None, meta=None)

An array of vectors in 2D space.

Mutable.

Parameters

  • x (ndarray) – x components. Must have the same dtype like y.

  • y (ndarray) – y components. Must have the same dtype like x.

  • meta (Optional[Dict[str, ndarray]]) – A dict holding arbitrary metadata.

  • dtype (Union[str, Type[Number], dtype, None]) –

__add__(other)

Add operation between vector arrays or a vector array and a vector

Parameters

other (Any) – Another vector array of equal length

Return type

Union[VectorArray2DABC, NotImplementedType]

__eq__(other)

Equality check between vector arrays

Parameters

other (Any) – Another vector array of equal length

Return type

Union[bool, NotImplementedType]

__getitem__(idx)

Item access, returning an independent object - either a bewegung.Vector2D (index access) or a bewegung.VectorArray2D (slicing)

Parameters

idx (Union[int, slice]) – Either an index or a slice

Return type

Union[Vector2D, VectorArray2DABC]

__iter__()

Iterator interface (1/2)

Return type

VectorArray2DABC

__len__()

Length of array

Return type

int

__matmul__(other)

Scalar product between vector arrays

Parameters

other (Any) – Another vector array of equal length

Return type

Union[ndarray, NotImplementedType]

__mod__(other)

Is-close check between vector arrays

Parameters

other (Any) – Another vector array of equal length

Return type

Union[bool, NotImplementedType]

__mul__(other)

Multiplication with scalar

Parameters

other (Any) – A number

Return type

Union[VectorArray2DABC, NotImplementedType]

__next__()

Iterator interface (2/2)

Return type

Vector2D

__repr__()

String representation for interactive use

Return type

str

__sub__(other)

Substract operator between vector arrays or a vector array and a vector

Parameters

other (Any) – Another vector array of equal length

Return type

Union[VectorArray2DABC, NotImplementedType]

property angle: numpy.ndarray

The vectors’ angles in radians, computed on demand

Return type

ndarray

as_list()

Exports a list of bewegung.Vector2D objects

Return type

List[Vector2D]

as_ndarray(dtype='f4')

Exports vector array as a numpy.ndarry object, shape (len(self), 2).

Parameters

dtype (Union[str, Type[Number], dtype]) – Desired numpy data type of new vector

Return type

ndarray

as_polar_tuple()

Exports vector array as a tuple of polar vector components in numpy.ndarry objects

Return type

Tuple[ndarray, ndarray]

as_tuple(copy=True)

Exports vector array as a tuple of vector components in numpy.ndarry objects

Parameters

copy (bool) – Provide a copy of underlying numpy.ndarry

Return type

Tuple[ndarray, ndarray]

as_type(dtype)

Exports vector array as another vector array with new dtype

Parameters

dtype (Union[str, Type[Number], dtype]) – Desired numpy data type of new vector array

Return type

VectorArray2DABC

copy()

Copies vector array & meta data

Return type

VectorArray2DABC

property dtype: numpy.dtype

(numpy) data type of vector array components

Return type

dtype

classmethod from_iterable(cls, obj, dtype='f4')

Generates vector array object from an iterable of bewegung.Vector2D objects

Parameters

  • obj (Iterable[Vector2D]) – iterable

  • dtype (Union[str, Type[Number], dtype]) – Desired numpy data type of new vector array

Return type

VectorArray2DABC

classmethod from_polar(cls, radius, angle, meta=None)

Generates vector array object from arrays of polar vector components

Parameters

  • radius (ndarray) – Radius components

  • angle (ndarray) – Angle components in radians

  • meta (Optional[Dict[str, ndarray]]) – A dict holding arbitrary metadata

Return type

VectorArray2DABC

property mag: numpy.ndarray

The vectors’ magnitudes, computed on demand

Return type

ndarray

mul(scalar)

In-place multiplication with scalar

Parameters

scalar (Number) – Vector array is multiplied with this number.

property ndim: int

Number of dimensions

Return type

int

update_from_vectorarray(other)

Updates vector components with data from another vector array

Parameters

  • x – x components. Must have the same dtype like y.

  • y – y components. Must have the same dtype like x.

  • other (VectorArray2DABC) –

property x: numpy.ndarray

x components, mutable

Return type

ndarray

property y: numpy.ndarray

y components, mutable

Return type

ndarray

The VectorArray3D class

class bewegung.VectorArray3D(x, y, z, dtype=None, meta=None)

An array of vectors in 3D space.

Mutable.

Parameters

  • x (ndarray) – x components. Must have the same dtype like y and z.

  • y (ndarray) – y components. Must have the same dtype like x and z.

  • z (ndarray) – z components. Must have the same dtype like x and y.

  • meta (Optional[Dict[str, ndarray]]) – A dict holding arbitrary metadata.

  • dtype (Union[str, Type[Number], dtype, None]) –

__add__(other)

Add operation between vector arrays or a vector array and a vector

Parameters

other (Any) – Another vector array of equal length

Return type

Union[VectorArray3DABC, NotImplementedType]

__eq__(other)

Equality check between vector arrays

Parameters

other (Any) – Another vector array of equal length

Return type

Union[bool, NotImplementedType]

__getitem__(idx)

Item access, returning an independent object - either a bewegung.Vector3D (index access) or a bewegung.VectorArray3D (slicing)

Parameters

idx (Union[int, slice]) – Either an index or a slice

Return type

Union[Vector3D, VectorArray3DABC]

__iter__()

Iterator interface (1/2)

Return type

VectorArray3DABC

__len__()

Length of array

Return type

int

__matmul__(other)

Scalar product between vector arrays

Parameters

other (Any) – Another vector array of equal length

Return type

Union[ndarray, NotImplementedType]

__mod__(other)

Is-close check between vector arrays

Parameters

other (Any) – Another vector array of equal length

Return type

Union[bool, NotImplementedType]

__mul__(other)

Multiplication with scalar

Parameters

other (Any) – A number

Return type

Union[VectorArray3DABC, NotImplementedType]

__next__()

Iterator interface (2/2)

Return type

Vector3D

__repr__()

String representation for interactive use

Return type

str

__sub__(other)

Substract operator between vector arrays or a vector array and a vector

Parameters

other (Any) – Another vector array of equal length

Return type

Union[VectorArray3DABC, NotImplementedType]

as_geographic_tuple()

Exports vector array as a tuple of geographic coordinate components in numpy.ndarry objects (radius, lon, lat)

Return type

Tuple[ndarray, ndarray, ndarray]

as_list()

Exports a list of bewegung.Vector3D objects

Return type

List[Vector3D]

as_ndarray(dtype='f4')

Exports vector array as a numpy.ndarry object, shape (len(self), 3).

Parameters

dtype (Union[str, Type[Number], dtype]) – Desired numpy data type of new vector

Return type

ndarray

as_polar_tuple()

Exports vector array as a tuple of polar vector components in numpy.ndarry objects

Return type

Tuple[ndarray, ndarray, ndarray]

as_tuple(copy=True)

Exports vector array as a tuple of vector components in numpy.ndarry objects

Parameters

copy (bool) – Provide a copy of underlying numpy.ndarry

Return type

Tuple[ndarray, ndarray, ndarray]

as_type(dtype)

Exports vector array as another vector array with new dtype

Parameters

dtype (Union[str, Type[Number], dtype]) – Desired numpy data type of new vector array

Return type

VectorArray3DABC

copy()

Copies vector array & meta data

Return type

VectorArray3DABC

property dtype: numpy.dtype

(numpy) data type of vector array components

Return type

dtype

classmethod from_geographic(cls, radius, lon, lat, meta=None)

Generates vector array object from arrays of geographic polar vector components

Parameters

  • radius (ndarray) – Radius components

  • lon (ndarray) – Angle components in degree

  • lat (ndarray) – Angle components in degree

  • meta (Optional[Dict[str, ndarray]]) – A dict holding arbitrary metadata

Return type

VectorArray3DABC

classmethod from_iterable(cls, obj, dtype='f4')

Generates vector array object from an iterable of bewegung.Vector3D objects

Parameters

  • obj (Iterable[Vector3D]) – iterable

  • dtype (Union[str, Type[Number], dtype]) – Desired numpy data type of new vector array

Return type

VectorArray3DABC

classmethod from_polar(cls, radius, theta, phi, meta=None)

Generates vector array object from arrays of polar vector components

Parameters

  • radius (ndarray) – Radius components

  • theta (ndarray) – Angle components in radians

  • phi (ndarray) – Angle components in radians

  • meta (Optional[Dict[str, ndarray]]) – A dict holding arbitrary metadata

Return type

VectorArray3DABC

property lat: float

The vectors’ geographic latitude in degree, computed on demand

Return type

float

property lon: float

The vectors’ gepgraphic longitude in degree, computed on demand

Return type

float

property mag: numpy.ndarray

The vectors’ magnitudes, computed on demand

Return type

ndarray

mul(scalar)

In-place multiplication with scalar

Parameters

scalar (Number) – Vector array is multiplied with this number.

property ndim: int

Number of dimensions

Return type

int

property phi: numpy.ndarray

The vectors’ phis in radians, computed on demand

Return type

ndarray

property theta: numpy.ndarray

The vectors’ thetas in radians, computed on demand

Return type

ndarray

update_from_vectorarray(other)

Updates vector components with data from another vector array

Parameters

  • x – x components. Must have the same dtype like y and z.

  • y – y components. Must have the same dtype like x and z.

  • z – z components. Must have the same dtype like x and y.

  • other (VectorArray3DABC) –

property x: numpy.ndarray

x components, mutable

Return type

ndarray

property y: numpy.ndarray

y components, mutable

Return type

ndarray

property z: numpy.ndarray

z components, mutable

Return type

ndarray