pirs.core.trageom subpackage

This subpackage defins only one class, pirs.core.trageom.Vector3 representing a vector (coordinate) in three-dimensional space. The main functionality of this class is to perform conversion between cartesian, cylindrical and spherical coordinate systems (CS). A user can work (set and get) attributes representing coordinates in these coordinate systems and the class unsures that all coordinates are everytime consistent.

from pirs.core.trageom import Vector3, pi2, pi

v1 = Vector3(car=(1, 0, 0))   # x, y, z
v2 = Vector3(cyl=(1, 0, 1))   # r, theta, z
v3 = Vector3(sph=(1, 0, 0))   # R, theta, phi

print 'rotate v1:'
print v1.car
v1.t += pi2
print v1.car

print 'stretch v2 2 times:'
print v2.car
v2.R *= 2.
print v2.car

print 'flip v3:'
print v3.car
v3.p = pi 
print v3.car

rotate v1:
(1.0, 0.0, 0.0)
(0.0, 1.0, 0.0)
stretch v2 2 times:
(1.0, 0.0, 1.0)
(2.0, 0.0, 2.0000000000000004)
flip v3:
(0.0, 0.0, 1.0)
(-0.0, -0.0, -1.0)

A vector instance is initialized by passing a coordinate 3-tuple to the constructor. Read-only attributes car, cyl and sph return coordinates in the correspondent CS. Properties x, y, , z, r, t, z, R, t, p can be set. In the above, the v1 vector is first specified using the cartesian CS. The coordinates and the CS type is stored internaly and can be used later to compute coordinates in the other CS. When t is changed, first, coordinates in the cylindrical CS are computed from the previously defined cartesian coordinates. Then, the theta cylindrical variable is updated and the internal CS type is set to the cylindrical CS. When we call the Vector3.car for the second time, i.e. after Vector3.t was set, the cartesian coordinates are computed from internally stored cylindrical coordinates and returned as a 3-tuple.

class pirs.core.trageom.Vector3(car=None, cyl=None, sph=None)

Vector in three-dimensional space.

Coordinate conversion between cartesian (car), cylindrical (cyl) and spherical (sph) coordinate systems is performed “on demand”, i.e. when values of these coordinates are inquired by user.

Vectors are created by specifying a 3-tuple containing coordinates in cartesian, cylinder, or spherical coordinate system (CS):

>>> v1 = Vector3(  car=(1, 0, 0) )     # cartesian coordinates
>>> v2 = Vector3(  cyl=(1, 0, 0) )     # cylinder coordinates
>>> v3 = Vector3(  sph=(1, 0, pi2))    # spherical coordinates (pi2 is defined in the module as pi2 = pi/2)

The order of values in tuples is the following:

(x, y, z)       # for cartesian CS
(r, theta, z)   # for cylinder CS
(R, theta, phi) # for spherical CS

Coordinates R and r used in the spherical and cylinder CS, have different meaning: R is the vector’s length, r is the length of vector’s projection onto xy plane.

If the type of coordinate system is not given explicitly, the cartesian is assumed. The following two definitions are equal:

>>> v4 = Vector3(     (1, 0, 0)) 
>>> v5 = Vector3( car=(1, 0, 0))
>>> v4 == v5
True

If incomplete tuples are specified, they are augmented by zeroes:

>>> v1 = Vector3((1,))
>>> v2 = Vector3((1, 0, 0))
>>> v1 == v2
True

If the ‘car’ argument is another Vector3 object, its copy is returned. This is to make Vector3() method a type convertor.

>>> v1 = Vector3( (1, 2, 3) )
>>> v2 = Vector3( v1 )
>>> v1 == v2
True
>>> v1 is v2
False

If no arguments are specified in the constructor, the argument car=(0,0,0) is assumed:

>>> print Vector3()
car (x=0, y=0, z=0)

After a vector instance is created, their coordinates can be accessed by attributes x, y, z, r, t, R, p, which mean one of the coordinate in cartesian (x,y,z), cylindrical (r, t[heta], z), or spherical (R[ho], t[heta], p[hi]) systems.

>>> v = Vector3( (1,1,1) )
>>> v.x, v.y, v.z            # cartesian coordinates
(1.0, 1.0, 1.0)
>>> v.r, v.t, v.z            # cylinder coordinates 
(1.414...,  0.785...,  1.0)
>>> v.R, v.t, v.p            # shperical coordinates 
(1.732...,  0.785...,  0.955...)

After a vector instance is created, it has at least one set of coordinates. Thus, they always can be used to get the coordinates in another system.

The transition from one coordinate system to another is performed when a coordinate is set. For example,

>>> v = Vector3( (0,0,0) )   
>>> v.r                      
0.0
>>> v.r = 3

In the first line, a vector instance is created. Since the cartesian coordinates are given (by default), the internal representation of the vector v uses cartesian system. In the second line, the radius in the cylindrical CS is requested. This results internaly in calculation of the coordinates in the cylindrical system, but the internal representation is still uses cartesian coordinates. In the third line, the cylundrical radius is set. Now, the internal representation is changed from cartesian to cylindrical.

Each time a coordinate is read, it is recalculated from the internal representation. Each time coordinate of a new system is set, first the new system coordinates are updated using the current coordinate system and then the new coordinate is set and the internal system is changed.

Sets coordinates of the vector.

Arguments car, cyl or sph must be a tuple specifying coordinates in the cartesian, cylinder or spherical coordinate systems, respectively.

If the passed tuple contains less than 3 elements, it is augmented with zeroes.

R

R coordinate in spherical CS.

When R is set, the vector internal representation is changed to spherical (thus R, t and p are computed from cartesian or cylinder coordinates), and then new value is set to R.

classmethod UnitX()

Returns unit vector along X axis

classmethod UnitY()

Returns unit vector along Y axis

classmethod UnitZ()

Returns unit vector along Z axis

classmethod Zero()

Returns zero vector with cartesian internal coordinate system.

>>> v1 = Vector3.Zero()
>>> v2 = Vector3()
>>> v3 = Vector3( car=(0,0,0) )
>>> v1 == v2
True
>>> v2 == v3
True

all

Returns a 7-tuple of coordinates in all systems, (x, y, z, r, t, R, p)

alld

Returns a dictionary with coordinates in all systems,:

{'x':x, 'y':y, 'z':z, 'r':r, 't':t, 'R':R, 'p':p}

car

Returns a 3-tuple with cartesian coordinates, (x, y, z).

card

Returns a dictionary with cartesian coordinates, {‘x’:x, ‘y’:y, ‘z’:z}.

copy()

Returns a new instance with the same coordinates

>>> v1 = Vector3((1,2,3))
>>> v2 = v1.copy()
>>> v1 is v2, v1 == v2
(False, True)

cross(othr)

Vector product

cyl

Returns a 3-tuple with cylinder coordinates, (r, t, z).

cyld

Returns a dictionary with cylinder coordinates, {‘r’:r, ‘t’:t, ‘z’:z}.

dot(othr)

scalar product

is_on_axis(axis='x')

test if self is on axis

is_parallel(othr)

check if self and othr are parallel taking into account machine epsilon.

is_perpendicular(othr)

check that two vectors are perpendicular taking into account the machine epsilon.

is_zero()

return true if length of self is zero

own

Returns a 3-tuple with coordinates in the internal CS.

p

p (phi) coordinate in spherical CS.

When p is set, the vector internal representation is changed to spherical (thus R, t and p are computed from cartesian or cylinder coordinates), and then new value is set to p.

r

r coordinate in cylinder CS.

When r is set, the vector internal representation is changed to cylinder (thus r, t and z are computed from cartesian or spherical coordinates), and then new value is set to r.

sph

Returns a 3-tuple with spherical coordinates, (R, t, p).

sphd

Returns a dictionary with spherical coordinates, {‘R’:R, ‘t’:t, ‘p’:p}.

t

t (theta) coordinate in cylinder CS.

When t is set to a vector with cylinder or spherical coordinates, the internal CS is not changed. If t is set to a vector with cartesian coordinates, the spherical coordinates are computed from cartesian, and than the new value is set to t.

x

Returns x coordinate in cartesian CS.

When x is set, the vector internal representation is changed to cartesian (thus x, y and z are computed from cyl. or sph coordinates), and then new value is set to x.

>>> Vector3( (1,1,1) ).x                   
1.0
>>> Vector3(cyl=(2**0.5, pi/4, 1.)).x      
1.00...
>>> Vector3(sph=(2**0.5, pi/4, pi/2)).x    
1.00...

>>> v = Vector3( sph=(1,0,0) )
>>> v.x = 1
>>> print v
car (x=1, y=0, z=1)

>>> v = Vector3( cyl=(2**0.5, pi/4, 1))
>>> v.x = 4
>>> print v
car (x=4, y=1, z=1)

y

Returns y coordinate in cartesian CS.

When y is set, the vector internal representation is changed to cartesian (thus x, y and z are computed from cyl. or sph coordinates), and then new value is set to y.

>>> Vector3( (1,1,1) ).y                   
1.0
>>> Vector3(cyl=(2**0.5, pi/4, 1.)).y      
1.0
>>> Vector3(sph=(2**0.5, pi/4, pi/2)).y    
1.0

>>> v = Vector3( sph=(1,0,0) )
>>> v.y = 1
>>> print v
car (x=0, y=1, z=1)

>>> v = Vector3( cyl=(2**0.5, pi/4, 1))
>>> v.y = 4
>>> print v
car (x=1, y=4, z=1)

z

Returns z coordinate in cartesian or cylinder CS.

When z is set in a vector with spherical internal representation, the new CS will be cartesian. In other cases, i.e. when z is set to a cartesian or cylinder vector, its type is not changed.

>>> Vector3( (1,1,1) ).z                   
1.0
>>> Vector3(cyl=(2**0.5, pi/4, 1.)).z      
1.0
>>> Vector3(sph=(2**0.5, pi/4, pi/2)).z    
0.0

>>> v = Vector3( sph=(1,0,pi/2) )
>>> v.z = 1
>>> print v
car (x=1, y=0, z=1)

>>> v = Vector3( cyl=(2**0.5, pi/4, 1))
>>> v.z = 4
>>> print v                                
cyl (r=1.41..., t=0.785..., z=4)