Position

class Position

Positions are a set of coordinates (abbreviated here as “coord”) in the Euclidean/Cartesian coordinate system. The number of coordinates is the dimensionality of the Euclidean space.

Public Functions

Position(argtype args)

args:

x: x-coordinate
y: y-coordinate. Requires explicit x.
z: z-coordinate. Requires explicit y.

Position(std::vector<double> vec): Initialize coordinates by brace initialized position vector.

Position(const int dimension): Initialize coordinates on origin with given dimensionality.

const std::vector<double> &coord() const: Return a copy of the position vector.

Position &set_vector(const std::vector<double> &vec): Set position vector.

Position &set_from_cartesian(const std::vector<double> &vec): Set vector given Cartesian coordinates (same as above).

void push_back(const double coord): Add another coordinate dimension.

Position &set_from_spherical(const std::vector<double> &vec): Set vector given Spherical coordinates (2 or 3-dimensional). See https://mathworld.wolfram.com/SphericalCoordinates.html Spherical coordinates are defined as follows: The first coordinate is rho >= 0. rho is the distance from origin. The second coordinate is theta. theta is the angle between x-axis and projection of the vector on x-y plane. In 3D, the third and final coordinate is phi, 0 <= phi <= PI. phi is the angle between z-axis and line.

void set_from_spherical(const double rho, const double theta, const double phi): Same as above for 3D.

void set_from_spherical(const double rho, const double theta): Same as above for 2D.

Position spherical() const: Return the spherical coordinates (r, theta, phi).

void spherical(Position *result) const: Optimized version of the above for an existing data structure.

double coord(const int dimension) const: Get coordinate value of one dimension.

void set_coord(const int dimension, const double coord): Set coordinate value of one dimension.

void add_to_coord(const int dimension, const double coord): Add to coordinate value of one dimension.

int size() const: Return the dimensionality of the position.

int dimension() const: Return the dimensionality of the position.

void set_to_origin_3D(): Set the position of self to the origin in 3D space. HWH depreciate

void set_to_origin(): Set the position of self to the origin.

void set_to_origin(const int dimension): Resize to given dimension, then set to the origin.

void add(const Position &position): Add position vector to self.

void subtract(const Position &position): Subtract the position vector from self.

void divide(const Position &position): Divide self by the position vector.

void divide(const double denominator): Divide self by a constant.

void multiply(const double constant): Multiply self by a constant.

double dot_product(const Position &position) const: Return the dot product of position vector with self.

double dot_product(const std::vector<double> &vec) const: Same as above, but with a vector.

Position cross_product(const Position &position) const: Return the cross product of position with self.

double squared_distance() const: Return the squared distance of self from the origin.

double distance() const: Return the distance of self from the origin.

double squared_distance(const Position &position) const: Return the squared distance between self and position.

double distance(const Position &position) const: Return distance between self and position.

std::string str() const: Return coordinates as a string.

double cosine(const Position &position) const: Return the cosine of the angle between self and given vector.

double vertex_angle_radians(const Position &ri, const Position &rk) const

Return the angle, in radians, formed by self as vertex, and two points. For example, the angle between i - j - k, which form a line, is PI. While i and k are given, j is self.

In 2D, maintain chirality such that angles are clock-wise rotated. This is implemented by checking that the z-dimension of

\(r_{ij} \times r_{kj} < 0\).

If not, then reverse the angle, \(\theta \rightarrow 2\pi - \theta\).

double torsion_angle_radians(const Position &rj, const Position &rk, const Position &rl) const

Dihedral or torsion angles are defined by the angle between planes. For a molecule, these planes may be defined by four positions: l - j - k - i. Note that the order is reversible.

The normal of the first plane, \(n_1\), is given by

\(n_1=r_{kl} \times r_{jk}\)

where

\(r_{kl} = r_k - r_l\).

The normal of the second plane, \(n_2\), is given by

\(n_2=r_{jk} \times r_{ij}\)

and the dihedral angle, \(\phi\), is given by

\(\cos\phi = \frac{n_1 \cdot n_2}{|n_1||n_2|}\).

For more discussion, see https://en.wikipedia.org/wiki/Dihedral_angle or http://trappe.oit.umn.edu/torsion.html.

In this convention, a syn-periplanar (cis) configuration corresponds to 0 while a anti-periplaner (trans) corresponds to PI.

void normalize(): Normalize the position such that the distance from the origin is unity, but the direction from the origin is the same.

bool is_equal(const Position &position, const double tolerance) const: Return true if the given position is equal to self within tolerance.

bool is_equal(const Position &position) const: Same as above, but with a default tolerance of NEAR_ZERO.

double nearest_distance_to_axis(const Position &point1, const Position &point2) const: Nearest distance to axis defined by two points. see http://mathworld.wolfram.com/Point-LineDistance3-Dimensional.html

void orthogonal(const Position &orthogonal): Set self orthogonal to given position.

void reflect(const Position &reflection_point): Reflect self about a point.