# 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 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`]

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)

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 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)

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 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`

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 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`