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

Examples

>>> 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
Returns:: Cross product of the two vectors.
Return type:: Vector3

dot(other)

Calculate dot product with other vector.

Parameters:: other (Vector3) – other vector
Returns:: Dot product of the two vectors.
Return type:: float

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.

slerp(other, t): Return a spherical linear interpolation between self and other vector.

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

Examples

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

Returns:: Affine transformation of vector u by matrix F.
Return type:: Vector3

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
Returns:: Dot product of the two vectors.
Return type:: float

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

Examples

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

cross(other): Returns the scalar magnitude of the 2D cross product.

property direction: Returns direction of the vector in degrees.

dot(other)

Calculate dot product with other vector.

Parameters:: other (Vector2) – other vector
Returns:: Dot product of the two vectors.
Return type:: float

normalized(): Returns normalized (unit length) vector.

classmethod random(): Create random 2D vector.

rotate(theta): Return the vector rotated counter-clockwise by angle theta in degrees.

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

Examples

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

Returns:: Affine transformation of vector u by matrix F.
Return type:: Vector2

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
Returns:: Dot product of the two vectors.
Return type:: float

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

Examples

>>> 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.
Returns:: Eigenvectors of the matrix.
Return type:: tuple of Vector3 or Vector3

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

Examples

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

Returns:: Matrix defined by individual components.
Return type:: Matrix3

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.
Returns:: Eigenvectors scaled by eigenvalues.
Return type:: tuple of Vector3 or Vector3

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

Examples

>>> 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.
Returns:: Eigenvectors of the matrix.
Return type:: tuple of Vector2 or Vector2

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

Examples

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

Returns:: Matrix defined by individual components.
Return type:: Matrix2

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.
Returns:: Eigenvectors scaled by eigenvalues.
Return type:: tuple of Vector2 or Vector2