math module

The apsg.math module provides basic linear algebra classes for structural geology. It includes 2D and 3D vectors (Vector2, Vector3), axial vectors (Axial2, Axial3), and matrices (Matrix2, Matrix3) with operations commonly used in orientation analysis.

The main APSG namespace provides lowercase aliases for commonly used classes (e.g. vec2 for Vector2, vec for Vector3, matrix for Matrix3). See Welcome to APSG’s documentation! for the full list.

Usage

3D vectors:

>>> from apsg import vec
>>> v = vec(1, 2, 3)
>>> v.magnitude()
>>> v.normalized()
>>> v.geo
>>> v.angle(vec(0, 0, 1))

Vector arithmetic:

>>> u = vec(45, 30)   # from trend/plunge
>>> v = vec(1, 0, 0)
>>> u + v
>>> u.cross(v)
>>> u.dot(v)

2D vectors:

>>> from apsg import vec2
>>> v2 = vec2(1, 0)

Matrices:

>>> from apsg import matrix
>>> m = matrix([[1, 0, 0], [0, 2, 0], [0, 0, 3]])
>>> m.eigenvalues()
>>> m.eigenvectors()

Rotations:

>>> from apsg import vec
>>> v = vec(1, 0, 0)
>>> v.rotate(vec(0, 0, 1), 90)

Classes:

Vector3(*args, **kwargs)	A class to represent a 3D vector.
Axial3(*args, **kwargs)	A class to represent a 3D axial vector.
Vector2(*args, **kwargs)	A class to represent a 2D vector.
Axial2(*args, **kwargs)	A class to represent a 2D axial vector.
Matrix3(*args, **kwargs)	A class to represent a 3x3 matrix.
Matrix2(*args, **kwargs)	A class to represent a 2x2 matrix.

class apsg.math.Vector3(*args, **kwargs)

Bases: Vector

A class to represent a 3D vector.

There are different way to create Vector3 object:

• without arguments create default Vector3 (1, 0, 0)

• with single argument v, where

  • v could be Vector3-like object

  • v could be string ‘x’, ‘y’ or ‘z’ - principal axes of coordinate system

  • v could be tuple of (x, y, z) - vector components

• with 2 arguments plunge direction and plunge

• with 3 numerical arguments defining vector components

Parameters:

• azi (float) – plunge direction of linear feature in degrees

• inc (float) – plunge of linear feature in degrees

Example

>>> vec()
>>> vec(1,2,-1)
>>> vec('y')
>>> vec(120, 30)
>>> v = vec(1, -2, 1)

angle(other)

Return the angle to the vector other

cross(other)

Calculate cross product with other vector.

Parameters:

other (Vector3) – other vector

dot(other)

Calculate dot product with other vector.

Parameters:

other (Vector3) – other vector

property geo

Return tuple of plunge direction and signed plunge

is_upper()

Return True if vector points towards negative Z direction

lower()

Change vector direction to point towards positive Z direction

normalized()

Returns normalized (unit length) vector

classmethod random()

Create random 3D vector

rotate(axis, theta)

Return the vector rotated around axis through angle theta. Right-hand rule applies

slerp(other, t)

Return a spherical linear interpolation between self and other vector

Note that for non-unit vectors the interpolation is not uniform

transform(F, **kwargs)

Return affine transformation of vector u by matrix F.

Parameters:

F – transformation matrix

Keyword Arguments:

norm – normalize transformed vectors. [True or False] Default False

Returns:

vector representation of affine transformation (dot product) of self by F

Example

# Reflexion of y axis. >>> F = [[1, 0, 0], [0, -1, 0], [0, 0, 1]] >>> u = Vector3([1, 1, 1]) >>> u.transform(F) Vector3(1, -1, 1)

classmethod unit_x()

Create unit length vector in x-direction

classmethod unit_y()

Create unit length vector in y-direction

classmethod unit_z()

Create unit length vector in z-direction

uv()

Returns normalized (unit length) vector

property z

Return z-component of the vector

class apsg.math.Axial3(*args, **kwargs)

Bases: Vector3

A class to represent a 3D axial vector.

Note: the angle between axial data cannot be more than 90°

dot(other)

Calculate dot product with other vector.

Parameters:

other (Vector3) – other vector

class apsg.math.Vector2(*args, **kwargs)

Bases: Vector

A class to represent a 2D vector.

There are different way to create Vector2 object:

• without arguments create default Vector2 (0, 0, 1)

• with single argument v, where

  • v could be Vector2-like object

  • v could be string ‘x’ or ‘y’ - principal axes of coordinate system

  • v could be tuple of (x, y) - vector components

  • v could be float - unit vector with given angle to ‘x’ axis

• with 2 numerical arguments defining vector components

Parameters:

ang (float) – angle between ‘x’ axis and vector in degrees

Example

>>> vec2()
>>> vec2(1, -1)
>>> vec2('y')
>>> vec2(50)
>>> v = vec2(1, -2)

cross(other)

Returns the magnitude of the vector that would result from a regular 3D cross product of the input vectors, taking their Z values implicitly as 0 (i.e. treating the 2D space as a plane in the 3D space). The 3D cross product will be perpendicular to that plane, and thus have 0 X & Y components (thus the scalar returned is the Z value of the 3D cross product vector).

Note that the magnitude of the vector resulting from 3D cross product is also equal to the area of the parallelogram between the two vectors. In addition, this area is signed and can be used to determine whether rotating from V1 to V2 moves in an counter clockwise or clockwise direction.

property direction

Returns direction of the vector in degrees

dot(other)

Calculate dot product with other vector.

Parameters:

other (Vector2) – other vector

normalized()

Returns normalized (unit length) vector

classmethod random()

Random 2D vector

rotate(axis, theta)

Return the vector rotated through angle theta. Right hand rule applies

transform(*args, **kwargs)

Return affine transformation of vector u by matrix F.

Parameters:

F – transformation matrix

Keyword Arguments:

norm – normalize transformed vectors. [True or False] Default False

Returns:

vector representation of affine transformation (dot product) of self by F

Example

# Reflexion of y axis. >>> F = [[1, 0], [0, -1]] >>> u = vec2([1, 1]) >>> u.transform(F) Vector2(1, -1)

classmethod unit_x()

Create unit length vector in x-direction

classmethod unit_y()

Create unit length vector in y-direction

uv()

Returns normalized (unit length) vector

class apsg.math.Axial2(*args, **kwargs)

Bases: Vector2

A class to represent a 2D axial vector.

Note: the angle between axial data cannot be more than 90°

dot(other)

Calculate dot product with other vector.

Parameters:

other (Vector2) – other vector

class apsg.math.Matrix3(*args, **kwargs)

Bases: Matrix

A class to represent a 3x3 matrix.

There are different way to create Matrix3 object:

• without arguments create default identity Matrix3

• with single argument of Matrix3-like object

Parameters:

v – 2-dimensional array-like object

Example

>>> matrix()
Matrix3
[[1 0 0]
 [0 1 0]
 [0 0 1]]
>>> A = matrix([[2, 1, 0], [0, 0.5, 0], [0, -0.5, 1]])

property E1

First eigenvalue

property E2

Second eigenvalue

property E3

Third eigenvalue

property V1

First eigenvector

property V2

Second eigenvector

property V3

Third eigenvector

eigenvectors(which=None)

Return eigenvectors as Vector3 objects.

Parameters:

which – if None returns sorted tuple of eigenvectors. If int returns given eigenvalue. Default None.

classmethod from_comp(**kwargs)

Return Matrix3 defined by individual components. Default is zero matrix.

Keyword Arguments:

• xx (float) – tensor component M_xx

• xy (float) – tensor component M_xy

• xz (float) – tensor component M_xz

• yx (float) – tensor component M_yx

• yy (float) – tensor component M_yy

• yz (float) – tensor component M_yz

• zx (float) – tensor component M_zx

• zy (float) – tensor component M_zy

• zz (float) – tensor component M_zz

Example

>>> M = matrix.from_comp(xy=1, zy=-0.5)
>>> M
[[ 0.   1.   0. ]
 [ 0.   0.   0. ]
 [ 0.  -0.5  0. ]]

scaled_eigenvectors(which=None)

Return eigenvectors with magnitudes of eigenvalues as Vector3 objects

Parameters:

which – if None returns sorted tuple of eigenvectors. If int returns given eigenvector. Default None.

property xz

Return xz-element of the matrix

property yz

Return yz-element of the matrix

property zx

Return zx-element of the matrix

property zy

Return zy-element of the matrix

property zz

Return zz-element of the matrix

class apsg.math.Matrix2(*args, **kwargs)

Bases: Matrix

A class to represent a 2x2 matrix.

There are different way to create Matrix2 object:

• without arguments create default identity Matrix2

• with single argument of Matrix2-like object

Parameters:

v – 2-dimensional array-like object

Example

>>> matrix2()
Matrix2
[[1 0]
 [0 1]]
>>> A = Matrix2([[2, 1],[0, 0.5]])

property E1

First eigenvalue

property E2

Second eigenvalue

property V1

First eigenvector

property V2

Second eigenvector

eigenvectors(which=None)

Return eigenvectors as Vector2 objects.

Parameters:

which – if None returns sorted tuple of eigenvectors. If int returns given eigenvector. Default None.

classmethod from_comp(**kwargs)

Return Matrix2 defined by individual components. Default is zero matrix.

Keyword Arguments:

• xx (float) – tensor component M_xx

• xy (float) – tensor component M_xy

• yx (float) – tensor component M_yx

• yy (float) – tensor component M_yy

Example

>>> M = matrix2.from_comp(xy=2)
>>> M
Matrix2
[[0. 2.]
 [0. 0.]]

scaled_eigenvectors(which=None)

Return eigenvectors with magnitudes of eigenvalues as Vector2 objects

Parameters:

which – if None returns sorted tuple of eigenvectors. If int returns given eigenvector. Default None.