Vector Package for Sunsort

Relies on: Nothing
C include file: vector.h
FORTRAN include file: n/a

The package may not be accessed directly from FORTRAN.

This package allows the user to manipulate a vector object in a variety of ways. Evaluations of expensive functions are delayed until the result is requested and then cached to save re-evaluation.

The vector structure is opaque and should not be accessed directly by the user, all accesses should go through wrapper functions and macros.

To declare a new vector, do:

   struct vector vec;
      

The following parameters may be read from a vector:

x

The X component

y

The Y component

z

The Z component

r

The length of the vector

r2

The length of the vector squared

t

Spherical polar theta in radians

td

Spherical polar theta in degrees

p

Spherical polar phi in radians

pd

Spherical polar phi in degrees

tx

Rectangular polar theta-x in radians

txd

Rectangular polar theta-x in degrees

ty

Rectangular polar theta-y in radians q

tyd

Rectangular polar theta-y in degrees

All parameters are double precision floating point numbers.

For each parameter par from the above list, there are two corresponding functions to read the parameter: vector_par and vector_par_safe. Each function takes 1 argument - a pointer to a structure vector. Normally vector_par should be used. Where possible this will be implemented as a macro for added speed. All macros are written to behave correctly inside expressions and after control structures like if and while - no extra braces are needed above what one would expect for a function call. If the macro is not suitable in a particular circumstance, then use the function call. In particular note that the macro versions may evaluate their parameter more than once so constructs like:

    px = vector_x(v++);
      

should be avoided, either rewrite it as:

    px = vector_x(v);
    v++;
      

or use the safe version:

    px = vector_x_safe(v++);
      

To set a vector, the following functions are provided. Each of them expects to be passed a pointer to the vector to be set, and returns the same pointer.

struct vector *vector_set_xyz(struct vector *v, double x, double y, double z)

Sets vector v from an x, y and z triplet.

struct vector *vector_set_rtp(struct vector *v, double r, double theta, double phi)

Sets vector v from an r, theta, phi spherical polar triplet. theta and phi should be in radians.

struct vector *vector_set_rtpd(struct vector *v, double r, double theta, double phi)

Sets vector v from an r, theta, phi spherical polar triplet. theta and phi should be in degrees.

struct vector *vector_set_rtt(struct vector *v, double r, double thetax, double thetay)

Sets vector v from an r, thetax, thetay rectangular polar triplet. thetax and thetay should be in radians.

struct vector *vector_set_rttd(struct vector *v, double r, double thetax, double thetay)

Sets vector v from an r, thetax, thetay rectangular polar triplet. thetax and thetay should be in degrees.

The following manipulation routines are provided:

struct vector *vector_scale(struct vector * v, double scale);

Multiplies the length of vector v by scale, returns v.

struct vector *vector_normalise(struct vector *v);

Normalises vector v, returns v.

struct vector *vector_scale_to(struct vector *v, double length);

Sets the length of vector v to length, returns v.

struct vector *vector_scale_to2(struct vector *v, double length2);

Sets the length of vector v to sqrt(length), returns v. The calculation of the sqrt is delayed as long as possible so if you happen to calculate a new value of |v|^2 use this routine rather than explicitly taking the square root and calling vector_scale_to.

struct vector *vector_copy(struct vector *d, struct vector *s);

Copies vector s into vector d. Returns d.

struct vector *vector_add(struct vector *a, struct vector *b, struct vector *c);

Sets vector a to be the sum of vectors b and c. Returns a.

struct vector *vector_sub(struct vector *a, struct vector *b, struct vector *c);

Sets vector a to be the vector difference b-c. Returns a.

double vector_dot(struct vector *a, struct vector *b);

Calculates the dot product of a and b.

struct vector *vector_cross(struct vector *a, struct vector *b, struct vector *c);

Sets vector a to be bxc. Returns a.