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.

Arguments

args:

  • x: x-coordinate

  • y: y-coordinate. Requires explicit x.

  • z: z-coordinate. Requires explicit y.

Public Functions

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 deprecate

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.