Box

Periodic boundary conditions and image distance. More...

Classes
struct	tinker::Box

Macros
#define	TINKER_IMAGE_LVEC_PARAMS   real3 lvec1, real3 lvec2, real3 lvec3
#define	TINKER_IMAGE_LVEC_ARGS   lvec1, lvec2, lvec3
#define	TINKER_IMAGE_RECIP_PARAMS   real3 recipa, real3 recipb, real3 recipc
#define	TINKER_IMAGE_RECIP_ARGS   recipa, recipb, recipc
#define	TINKER_IMAGE_PARAMS   BoxShape box_shape, TINKER_IMAGE_LVEC_PARAMS, TINKER_IMAGE_RECIP_PARAMS
#define	TINKER_IMAGE_ARGS   box_shape, TINKER_IMAGE_LVEC_ARGS, TINKER_IMAGE_RECIP_ARGS
#define	IMAGE_TRI__(xr, yr, zr, l1, l2, l3, ra, rb, rc)
	Image displacement for the triclinic PBC. More...
#define	IMAGE_MONO__(xr, yr, zr, l1, l2, l3, ra, rb, rc)
	Image displacement for the monoclinic PBC. More...
#define	IMAGE_ORTHO__(xr, yr, zr, l1, l2, l3, ra, rb, rc)
	Image displacement for the orthogonal PBC. More...
#define	IMAGE_OCT__(xr, yr, zr, l1, l2, l3, ra, rb, rc)
	Image displacement for the truncated octahedron PBC. More...
#define	image(x, y, z)   imageGeneral(x, y, z, TINKER_IMAGE_ARGS)
#define	image2(x, y, z)   image2General(x, y, z, TINKER_IMAGE_ARGS)
#define	imagen2(x, y, z)   imagen2General(x, y, z, TINKER_IMAGE_ARGS)

Enumerations
enum class	tinker::BoxShape {   tinker::BoxShape::UNBOUND , tinker::BoxShape::ORTHO , tinker::BoxShape::MONO , tinker::BoxShape::TRI ,   tinker::BoxShape::OCT }
	Shapes of the periodic box. More...

Functions
void	tinker::boxData (RcOp)
	Sets up box data on device. More...
void	tinker::boxDataP1 (RcOp)
	Internal function used in the setup. More...
void	tinker::boxExtent (double newExtent)
void	tinker::boxSetCurrent (const Box &p)
	Sets the box by the input and updates the box on device. More...
void	tinker::boxGetCurrent (Box &p)
	Copies the current PBC box to the output variable. More...
void	tinker::boxSetCurrentRecip ()
void	tinker::boxSetTinker (const Box &p)
	Updates the related PBC modules of Tinker by p. More...
void	tinker::boxCopyin ()
void	tinker::boxLattice (Box &p, BoxShape sh, double a, double b, double c, double alphaDeg, double betaDeg, double gammaDeg)
	Sets up the internal PBC data. Similar to Tinker lattice subroutine. More...
real	tinker::boxVolume ()
__device__ real3	tinker::ftoc_triclinic (real3 f, real3 l1, real3 l2, real3 l3)
	Fractional to cartesian: triclinic. More...
__device__ real3	tinker::ftoc_monoclinic (real3 f, real3 l1, real3 l2, real3 l3)
	Fractional to cartesian: monoclinic. More...
__device__ real3	tinker::ftoc_orthogonal (real3 f, real3 l1, real3 l2, real3 l3)
	Fractional to cartesian: orthogonal. More...
__device__ real3	tinker::ftoc_general (real3 f, real3 l1, real3 l2, real3 l3)
	Fractional to cartesian. More...
__device__ real3	tinker::imageFrac (real3 f)
	PBC image of the fractional coordinates. More...
__device__ real3	tinker::ctof_triclinic (real xr, real yr, real zr, real3 ra, real3 rb, real3 rc)
	Cartesian to fractional: triclinic. More...
__device__ real3	tinker::ctof_monoclinic (real xr, real yr, real zr, real3 ra, real3 rb, real3 rc)
	Cartesian to fractional: monoclinic. More...
__device__ real3	tinker::ctof_orthogonal (real xr, real yr, real zr, real3 ra, real3 rb, real3 rc)
	Cartesian to fractional: orthogonal. More...
__device__ real3	tinker::imagectof_general (real xr, real yr, real zr, real3 ra, real3 rb, real3 rc)
	Cartesian to fractional. More...

Variables
BoxShape	tinker::box_shape
real3	tinker::lvec1
real3	tinker::lvec2
real3	tinker::lvec3
real3	tinker::recipa
real3	tinker::recipb
real3	tinker::recipc
Box *	tinker::trajbox
	Host pointer to the PBC boxes of a trajectory. More...

Detailed Description

Periodic boundary conditions and image distance.

Notes on the image distance

The image distances are coded as macro instead of inlined functions. This is because of a bug I found in pgc++ 19.10.

---

Class Documentation

tinker::Box

struct tinker::Box

Internal data for the periodic boundary condition (PBC).

PBC in Tinker is defined by lengths of three axes and three angles: a-axis, b-axis, c-axis, alpha, beta, and gamma.

In cartesian coordinates:

• a-axis is always aligned with the x axis, so the vector of a-axis is (ax,ay,az) = (a,0,0);
• b-axis does not have z component, so the vector of b-axis is (bx,by,bz) = (bx,by,0);
• c-axis is (cx,cy,cz).

Tinker has another 3x3 matrix lvec:

• lvec(:,1) (or lvec[0][]): (ax,bx,cx);
• lvec(:,2) (or lvec[1][]): (ay,by,cy);
• lvec(:,3) (or lvec[2][]): (az,bz,cz).

Triclinic:

• lvec(:,1) (or lvec[0][]): (ax,bx,cx);
• lvec(:,2) (or lvec[1][]): ( 0,by,cy);
• lvec(:,3) (or lvec[2][]): ( 0, 0,cz).

Monoclinic:

• lvec(:,1) (or lvec[0][]): (a,0,cx);
• lvec(:,2) (or lvec[1][]): (0,b, 0);
• lvec(:,3) (or lvec[2][]): (0,0,cz);
• alpha and gamma are 90 degrees.

Orthogonal:

• lvec(:,1) (or lvec[0][]): (a,0,0);
• lvec(:,2) (or lvec[1][]): (0,b,0);
• lvec(:,3) (or lvec[2][]): (0,0,c);
• alpha, beta, and gamma are 90 degrees.

Reciprocal lattice (recip), is the inverse of lvec:

• Fortran: recip(:,1), recip(:,2), recip(:,3);
• C++: recip[0][], recip[1][], recip[2][];
• Fractional coordinates fi = recip(:,i) (xr,yr,zr), (i=1,2,3);
• Cartesian coordinates wr = inv_recip(:,w) (f1,f2,f3) = lvec(:,w) (f1,f2,f3), (w=1,2,3 or x,y,z).

Public Attributes
BoxShape	box_shape
real3	lvec1
real3	lvec2
real3	lvec3
real3	recipa
real3	recipb
real3	recipc

Member Data Documentation

box_shape

BoxShape tinker::Box::box_shape

lvec1

real3 tinker::Box::lvec1

lvec2

real3 tinker::Box::lvec2

lvec3

real3 tinker::Box::lvec3

recipa

real3 tinker::Box::recipa

recipb

real3 tinker::Box::recipb

recipc

real3 tinker::Box::recipc

Macro Definition Documentation

image

#define image	(		x,
			y,
			z
	)		imageGeneral(x, y, z, TINKER_IMAGE_ARGS)

Applies periodic boundary conditions to displacement (xr,yr,zr) and preserves the correct signs.

For testing purpose, defining it in the source code before including this header file will overwrite the default macro definition.

image2

#define image2	(		x,
			y,
			z
	)		image2General(x, y, z, TINKER_IMAGE_ARGS)

Applies periodic boundary conditions to displacement (xr,yr,zr) and preserves the correct signs. Returns the displacement squared.

IMAGE_MONO__

#define IMAGE_MONO__	(		xr,
			yr,
			zr,
			l1,
			l2,
			l3,
			ra,
			rb,
			rc
	)

Value:

   {                                                                                               \
      real fx = REAL_FLOOR(0.5f + zr * ra.z + xr * ra.x);                                          \
      real fy = REAL_FLOOR(0.5f + yr * rb.y);                                                      \
      real fz = REAL_FLOOR(0.5f + zr * rc.z);                                                      \
      xr -= (fz * l1.z + fx * l1.x);                                                               \
      yr -= (fy * l2.y);                                                                           \
      zr -= (fz * l3.z);                                                                           \
   }

Image displacement for the monoclinic PBC.

IMAGE_OCT__

#define IMAGE_OCT__	(		xr,
			yr,
			zr,
			l1,
			l2,
			l3,
			ra,
			rb,
			rc
	)

Value:

   {                                                                                               \
      real fx = xr * ra.x;                                                                         \
      real fy = yr * ra.x;                                                                         \
      real fz = zr * ra.x;                                                                         \
      fx -= REAL_FLOOR(0.5f + fx);                                                                 \
      fy -= REAL_FLOOR(0.5f + fy);                                                                 \
      fz -= REAL_FLOOR(0.5f + fz);                                                                 \
      if (REAL_ABS(fx) + REAL_ABS(fy) + REAL_ABS(fz) > 0.75f) {                                    \
         fx -= REAL_SIGN(0.5f, fx);                                                                \
         fy -= REAL_SIGN(0.5f, fy);                                                                \
         fz -= REAL_SIGN(0.5f, fz);                                                                \
      }                                                                                            \
      xr = fx * l1.x;                                                                              \
      yr = fy * l1.x;                                                                              \
      zr = fz * l1.x;                                                                              \
   }

Image displacement for the truncated octahedron PBC.

IMAGE_ORTHO__

#define IMAGE_ORTHO__	(		xr,
			yr,
			zr,
			l1,
			l2,
			l3,
			ra,
			rb,
			rc
	)

Value:

   {                                                                                               \
      real fx = REAL_FLOOR(0.5f + xr * ra.x);                                                      \
      real fy = REAL_FLOOR(0.5f + yr * rb.y);                                                      \
      real fz = REAL_FLOOR(0.5f + zr * rc.z);                                                      \
      xr -= (fx * l1.x);                                                                           \
      yr -= (fy * l2.y);                                                                           \
      zr -= (fz * l3.z);                                                                           \
   }

Image displacement for the orthogonal PBC.

IMAGE_TRI__

#define IMAGE_TRI__	(		xr,
			yr,
			zr,
			l1,
			l2,
			l3,
			ra,
			rb,
			rc
	)

Value:

   {                                                                                               \
      real fx = REAL_FLOOR(0.5f + zr * ra.z + yr * ra.y + xr * ra.x);                              \
      real fy = REAL_FLOOR(0.5f + zr * rb.z + yr * rb.y);                                          \
      real fz = REAL_FLOOR(0.5f + zr * rc.z);                                                      \
      xr -= (fz * l1.z + fy * l1.y + fx * l1.x);                                                   \
      yr -= (fz * l2.z + fy * l2.y);                                                               \
      zr -= (fz * l3.z);                                                                           \
   }

Image displacement for the triclinic PBC.

imagen2

#define imagen2	(		x,
			y,
			z
	)		imagen2General(x, y, z, TINKER_IMAGE_ARGS)

Applies periodic boundary conditions to displacement (xr,yr,zr). Correct signs may not be preserved. Returns the displacement squared.

TINKER_IMAGE_ARGS

#define TINKER_IMAGE_ARGS   box_shape, TINKER_IMAGE_LVEC_ARGS, TINKER_IMAGE_RECIP_ARGS

TINKER_IMAGE_LVEC_ARGS

#define TINKER_IMAGE_LVEC_ARGS   lvec1, lvec2, lvec3

TINKER_IMAGE_LVEC_PARAMS

#define TINKER_IMAGE_LVEC_PARAMS   real3 lvec1, real3 lvec2, real3 lvec3

TINKER_IMAGE_PARAMS

#define TINKER_IMAGE_PARAMS   BoxShape box_shape, TINKER_IMAGE_LVEC_PARAMS, TINKER_IMAGE_RECIP_PARAMS

TINKER_IMAGE_RECIP_ARGS

#define TINKER_IMAGE_RECIP_ARGS   recipa, recipb, recipc

TINKER_IMAGE_RECIP_PARAMS

#define TINKER_IMAGE_RECIP_PARAMS   real3 recipa, real3 recipb, real3 recipc

Enumeration Type Documentation

BoxShape

enum class tinker::BoxShape

strong

Shapes of the periodic box.

Enumerator
UNBOUND	unbound
ORTHO	orthorgonal
MONO	monoclinic
TRI	triclinic
OCT	truncated octahedron

Function Documentation

boxCopyin()

void tinker::boxCopyin

(

)

OpenACC only: Copies the current box data to device asynchronously. The implementations are empty for CPU and CUDA code because it is only in the OpenACC code that a copy of the PBC box is created on device.

boxData()

void tinker::boxData

(

RcOp

)

Sets up box data on device.

boxDataP1()

void tinker::boxDataP1

(

RcOp

)

Internal function used in the setup.

boxExtent()

void tinker::boxExtent

(

double

newExtent

)

Sets up a hypothetical orthogonal box for the unbound box whose a-axis equals the new extent.

boxGetCurrent()

void tinker::boxGetCurrent

(

Box &

p

)

Copies the current PBC box to the output variable.

boxLattice()

void tinker::boxLattice	(	Box &	p,
		BoxShape	sh,
		double	a,
		double	b,
		double	c,
		double	alphaDeg,
		double	betaDeg,
		double	gammaDeg
	)

Sets up the internal PBC data. Similar to Tinker lattice subroutine.

boxSetCurrent()

void tinker::boxSetCurrent

(

const Box &

p

)

Sets the box by the input and updates the box on device.

boxSetCurrentRecip()

void tinker::boxSetCurrentRecip

(

)

Calculates the recip arrays by new lvec arrays and updates the box on device

boxSetTinker()

void tinker::boxSetTinker

(

const Box &

p

)

Updates the related PBC modules of Tinker by p.

boxVolume()

real tinker::boxVolume

(

)

Gets the volume of the PBC box.

Note

This function may calculate the volume on-the-fly instead of using an internal variable to save the volume.

The volume is undefined for the unbound box.

ctof_monoclinic()

__device__ real3 tinker::ctof_monoclinic ( real  xr, real  yr, real  zr, real3  ra, real3  rb, real3  rc  )

inline

Cartesian to fractional: monoclinic.

ctof_orthogonal()

__device__ real3 tinker::ctof_orthogonal ( real  xr, real  yr, real  zr, real3  ra, real3  rb, real3  rc  )

inline

Cartesian to fractional: orthogonal.

ctof_triclinic()

__device__ real3 tinker::ctof_triclinic ( real  xr, real  yr, real  zr, real3  ra, real3  rb, real3  rc  )

inline

Cartesian to fractional: triclinic.

ftoc_general()

__device__ real3 tinker::ftoc_general ( real3  f, real3  l1, real3  l2, real3  l3  )

inline

Fractional to cartesian.

ftoc_monoclinic()

__device__ real3 tinker::ftoc_monoclinic ( real3  f, real3  l1, real3  l2, real3  l3  )

inline

Fractional to cartesian: monoclinic.

ftoc_orthogonal()

__device__ real3 tinker::ftoc_orthogonal ( real3  f, real3  l1, real3  l2, real3  l3  )

inline

Fractional to cartesian: orthogonal.

ftoc_triclinic()

__device__ real3 tinker::ftoc_triclinic ( real3  f, real3  l1, real3  l2, real3  l3  )

inline

Fractional to cartesian: triclinic.

imagectof_general()

__device__ real3 tinker::imagectof_general ( real  xr, real  yr, real  zr, real3  ra, real3  rb, real3  rc  )

inline

Cartesian to fractional.

imageFrac()

__device__ real3 tinker::imageFrac ( real3  f )

inline

PBC image of the fractional coordinates.

Variable Documentation

box_shape

BoxShape tinker::box_shape

extern

lvec1

real3 tinker::lvec1

extern

lvec2

real3 tinker::lvec2

extern

lvec3

real3 tinker::lvec3

extern

recipa

real3 tinker::recipa

extern

recipb

real3 tinker::recipb

extern

recipc

real3 tinker::recipc

extern

trajbox

Box* tinker::trajbox

extern

Host pointer to the PBC boxes of a trajectory.