Gromacs  2021.3
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Functions
#include "gromacs/math/vectypes.h"
+ This graph shows which files directly or indirectly include this file:

Description

API for calculation of centers of mass/geometry.

This header defines a few functions that can be used to calculate centers of mass/geometry for a group of atoms. These routines can be used independently of the other parts of the library, but they are also used internally by the selection engine. In most cases, it should not be necessary to call these functions directly. Instead, one should write an analysis tool such that it gets all positions through selections.

The functions in the header can be divided into a few groups based on the parameters they take. The simplest group of functions calculates the center of a single group of atoms:

A second set of routines is provided for calculating the centers for groups that wrap over periodic boundaries (gmx_calc_cog_pbc(), gmx_calc_com_pbc(), gmx_calc_comg_pbc()). These functions are slower, because they need to adjust the center iteratively.

It is also possible to calculate centers for several groups of atoms in one call. The functions gmx_calc_cog_block(), gmx_calc_com_block() and gmx_calc_comg_block() take an index group and a partitioning of that index group (as a t_block structure), and calculate the centers for each group defined by the t_block structure separately.

Finally, there is a function gmx_calc_comg_blocka() that takes both the index group and the partitioning as a single t_blocka structure.

Author
Teemu Murtola teemu.nosp@m..mur.nosp@m.tola@.nosp@m.gmai.nosp@m.l.com

Functions

void gmx_calc_cog (const gmx_mtop_t *top, rvec x[], int nrefat, const int index[], rvec xout)
 Calculate a single center of geometry. More...
 
void gmx_calc_com (const gmx_mtop_t *top, rvec x[], int nrefat, const int index[], rvec xout)
 Calculate a single center of mass. More...
 
void gmx_calc_cog_f (const gmx_mtop_t *top, rvec f[], int nrefat, const int index[], rvec fout)
 Calculate force on a single center of geometry. More...
 
void gmx_calc_com_f (const gmx_mtop_t *top, rvec f[], int nrefat, const int index[], rvec fout)
 Calculate force on a single center of mass. More...
 
void gmx_calc_comg (const gmx_mtop_t *top, rvec x[], int nrefat, const int index[], bool bMass, rvec xout)
 Calculate a single center of mass/geometry. More...
 
void gmx_calc_comg_f (const gmx_mtop_t *top, rvec f[], int nrefat, const int index[], bool bMass, rvec fout)
 Calculate force on a single center of mass/geometry. More...
 
void gmx_calc_cog_pbc (const gmx_mtop_t *top, rvec x[], const t_pbc *pbc, int nrefat, const int index[], rvec xout)
 Calculate a single center of geometry iteratively, taking PBC into account. More...
 
void gmx_calc_com_pbc (const gmx_mtop_t *top, rvec x[], const t_pbc *pbc, int nrefat, const int index[], rvec xout)
 Calculate a single center of mass iteratively, taking PBC into account. More...
 
void gmx_calc_comg_pbc (const gmx_mtop_t *top, rvec x[], const t_pbc *pbc, int nrefat, const int index[], bool bMass, rvec xout)
 Calculate a single center of mass/geometry iteratively with PBC. More...
 
void gmx_calc_cog_block (const gmx_mtop_t *top, rvec x[], const t_block *block, const int index[], rvec xout[])
 Calculate centers of geometry for a blocked index. More...
 
void gmx_calc_com_block (const gmx_mtop_t *top, rvec x[], const t_block *block, const int index[], rvec xout[])
 Calculate centers of mass for a blocked index. More...
 
void gmx_calc_cog_f_block (const gmx_mtop_t *top, rvec f[], const t_block *block, const int index[], rvec fout[])
 Calculate forces on centers of geometry for a blocked index. More...
 
void gmx_calc_com_f_block (const gmx_mtop_t *top, rvec f[], const t_block *block, const int index[], rvec fout[])
 Calculate forces on centers of mass for a blocked index. More...
 
void gmx_calc_comg_block (const gmx_mtop_t *top, rvec x[], const t_block *block, const int index[], bool bMass, rvec xout[])
 Calculate centers of mass/geometry for a blocked index. More...
 
void gmx_calc_comg_f_block (const gmx_mtop_t *top, rvec f[], const t_block *block, const int index[], bool bMass, rvec fout[])
 Calculate forces on centers of mass/geometry for a blocked index. More...
 
void gmx_calc_comg_blocka (const gmx_mtop_t *top, rvec x[], const t_blocka *block, bool bMass, rvec xout[])
 Calculate centers of mass/geometry for a set of blocks;. More...
 
void gmx_calc_comg_f_blocka (const gmx_mtop_t *top, rvec x[], const t_blocka *block, bool bMass, rvec xout[])
 Calculate forces on centers of mass/geometry for a set of blocks;. More...
 

Function Documentation

void gmx_calc_cog ( const gmx_mtop_t *  top,
rvec  x[],
int  nrefat,
const int  index[],
rvec  xout 
)

Calculate a single center of geometry.

Parameters
[in]topTopology structure (unused, can be NULL).
[in]xPosition vectors of all atoms.
[in]nrefatNumber of atoms in the index.
[in]indexIndices of atoms.
[out]xoutCOG position for the indexed atoms.
void gmx_calc_cog_block ( const gmx_mtop_t *  top,
rvec  x[],
const t_block *  block,
const int  index[],
rvec  xout[] 
)

Calculate centers of geometry for a blocked index.

Parameters
[in]topTopology structure (unused, can be NULL).
[in]xPosition vectors of all atoms.
[in]blockt_block structure that divides index into blocks.
[in]indexIndices of atoms.
[out]xoutblock->nr COG positions.
void gmx_calc_cog_f ( const gmx_mtop_t *  top,
rvec  f[],
int  nrefat,
const int  index[],
rvec  fout 
)

Calculate force on a single center of geometry.

Parameters
[in]topTopology structure with masses.
[in]fForces on all atoms.
[in]nrefatNumber of atoms in the index.
[in]indexIndices of atoms.
[out]foutForce on the COG position for the indexed atoms.
void gmx_calc_cog_f_block ( const gmx_mtop_t *  top,
rvec  f[],
const t_block *  block,
const int  index[],
rvec  fout[] 
)

Calculate forces on centers of geometry for a blocked index.

Parameters
[in]topTopology structure with masses.
[in]fForces on all atoms.
[in]blockt_block structure that divides index into blocks.
[in]indexIndices of atoms.
[out]foutblock->nr Forces on COG positions.
void gmx_calc_cog_pbc ( const gmx_mtop_t *  top,
rvec  x[],
const t_pbc pbc,
int  nrefat,
const int  index[],
rvec  xout 
)

Calculate a single center of geometry iteratively, taking PBC into account.

Parameters
[in]topTopology structure (unused, can be NULL).
[in]xPosition vectors of all atoms.
[in]pbcPeriodic boundary conditions structure.
[in]nrefatNumber of atoms in the index.
[in]indexIndices of atoms.
[out]xoutCOG position for the indexed atoms.

Works exactly as gmx_calc_com_pbc(), but calculates the center of geometry.

void gmx_calc_com ( const gmx_mtop_t *  top,
rvec  x[],
int  nrefat,
const int  index[],
rvec  xout 
)

Calculate a single center of mass.

Parameters
[in]topTopology structure with masses.
[in]xPosition vectors of all atoms.
[in]nrefatNumber of atoms in the index.
[in]indexIndices of atoms.
[out]xoutCOM position for the indexed atoms.

Works exactly as gmx_calc_cog() with the exception that a center of mass are calculated, and hence a topology with masses is required.

void gmx_calc_com_block ( const gmx_mtop_t *  top,
rvec  x[],
const t_block *  block,
const int  index[],
rvec  xout[] 
)

Calculate centers of mass for a blocked index.

Parameters
[in]topTopology structure with masses.
[in]xPosition vectors of all atoms.
[in]blockt_block structure that divides index into blocks.
[in]indexIndices of atoms.
[out]xoutblock->nr COM positions.

Works exactly as gmx_calc_cog_block() with the exception that centers of mass are calculated, and hence a topology with masses is required.

void gmx_calc_com_f ( const gmx_mtop_t *  top,
rvec  f[],
int  nrefat,
const int  index[],
rvec  fout 
)

Calculate force on a single center of mass.

Parameters
[in]topTopology structure (unused, can be NULL).
[in]fForces on all atoms.
[in]nrefatNumber of atoms in the index.
[in]indexIndices of atoms.
[out]foutForce on the COM position for the indexed atoms.
void gmx_calc_com_f_block ( const gmx_mtop_t *  top,
rvec  f[],
const t_block *  block,
const int  index[],
rvec  fout[] 
)

Calculate forces on centers of mass for a blocked index.

Parameters
[in]topTopology structure (unused, can be NULL).
[in]fForces on all atoms.
[in]blockt_block structure that divides index into blocks.
[in]indexIndices of atoms.
[out]foutblock->nr Forces on COM positions.
void gmx_calc_com_pbc ( const gmx_mtop_t *  top,
rvec  x[],
const t_pbc pbc,
int  nrefat,
const int  index[],
rvec  xout 
)

Calculate a single center of mass iteratively, taking PBC into account.

Parameters
[in]topTopology structure with masses.
[in]xPosition vectors of all atoms.
[in]pbcPeriodic boundary conditions structure.
[in]nrefatNumber of atoms in the index.
[in]indexIndices of atoms.
[out]xoutCOM position for the indexed atoms.

Works as gmx_calc_com(), but takes into account periodic boundary conditions: If any atom is more than half the box from the COM, it is wrapped around and a new COM is calculated. This is repeated until no atoms violate the condition.

Modified from src/tools/gmx_sorient.c in Gromacs distribution.

void gmx_calc_comg ( const gmx_mtop_t *  top,
rvec  x[],
int  nrefat,
const int  index[],
bool  bMass,
rvec  xout 
)

Calculate a single center of mass/geometry.

Parameters
[in]topTopology structure with masses (can be NULL if bMASS==false).
[in]xPosition vectors of all atoms.
[in]nrefatNumber of atoms in the index.
[in]indexIndices of atoms.
[in]bMassIf true, mass weighting is used.
[out]xoutCOM/COG position for the indexed atoms.

Calls either gmx_calc_com() or gmx_calc_cog() depending on the value of bMass. Other parameters are passed unmodified to these functions.

void gmx_calc_comg_block ( const gmx_mtop_t *  top,
rvec  x[],
const t_block *  block,
const int  index[],
bool  bMass,
rvec  xout[] 
)

Calculate centers of mass/geometry for a blocked index.

Parameters
[in]topTopology structure with masses (can be NULL if bMASS==false).
[in]xPosition vectors of all atoms.
[in]blockt_block structure that divides index into blocks.
[in]indexIndices of atoms.
[in]bMassIf true, mass weighting is used.
[out]xoutblock->nr COM/COG positions.

Calls either gmx_calc_com_block() or gmx_calc_cog_block() depending on the value of bMass. Other parameters are passed unmodified to these functions.

void gmx_calc_comg_blocka ( const gmx_mtop_t *  top,
rvec  x[],
const t_blocka *  block,
bool  bMass,
rvec  xout[] 
)

Calculate centers of mass/geometry for a set of blocks;.

Parameters
[in]topTopology structure with masses (can be NULL if bMASS==false).
[in]xPosition vectors of all atoms.
[in]blockBlocks for calculation.
[in]bMassIf true, mass weighting is used.
[out]xoutblock->nr COM/COG positions.

Calls gmx_calc_comg_block(), converting the t_blocka structure into a t_block and an index. Other parameters are passed unmodified.

Attention
This function assumes that a pointer to t_blocka can be safely typecast into t_block such that the index fields can still be referenced. With the present Gromacs defitions of these types, this is the case, but if the layout of these structures is changed, this may lead to strange crashes.
void gmx_calc_comg_f ( const gmx_mtop_t *  top,
rvec  f[],
int  nrefat,
const int  index[],
bool  bMass,
rvec  fout 
)

Calculate force on a single center of mass/geometry.

Parameters
[in]topTopology structure with masses (can be NULL if bMASS==true).
[in]fForces on all atoms.
[in]nrefatNumber of atoms in the index.
[in]indexIndices of atoms.
[in]bMassIf true, force on COM is calculated.
[out]foutForce on the COM/COG position for the indexed atoms.

Calls either gmx_calc_cog_f() or gmx_calc_com_f() depending on the value of bMass. Other parameters are passed unmodified to these functions.

void gmx_calc_comg_f_block ( const gmx_mtop_t *  top,
rvec  f[],
const t_block *  block,
const int  index[],
bool  bMass,
rvec  fout[] 
)

Calculate forces on centers of mass/geometry for a blocked index.

Parameters
[in]topTopology structure with masses (can be NULL if bMASS==false).
[in]fForces on all atoms.
[in]blockt_block structure that divides index into blocks.
[in]indexIndices of atoms.
[in]bMassIf true, force on COM is calculated.
[out]foutblock->nr forces on the COM/COG positions.

Calls either gmx_calc_com_f_block() or gmx_calc_cog_f_block() depending on the value of bMass. Other parameters are passed unmodified to these functions.

void gmx_calc_comg_f_blocka ( const gmx_mtop_t *  top,
rvec  f[],
const t_blocka *  block,
bool  bMass,
rvec  fout[] 
)

Calculate forces on centers of mass/geometry for a set of blocks;.

Parameters
[in]topTopology structure with masses (can be NULL if bMASS==true).
[in]fForces on all atoms.
[in]blockBlocks for calculation.
[in]bMassIf true, force on COM is calculated.
[out]foutblock->nr forces on the COM/COG positions.

Calls gmx_calc_comg_f_block(), converting the t_blocka structure into a t_block and an index. Other parameters are passed unmodified.

Attention
This function assumes that a pointer to t_blocka can be safely typecast into t_block such that the index fields can still be referenced. With the present Gromacs defitions of these types, this is the case, but if the layout of these structures is changed, this may lead to strange crashes.
void gmx_calc_comg_pbc ( const gmx_mtop_t *  top,
rvec  x[],
const t_pbc pbc,
int  nrefat,
const int  index[],
bool  bMass,
rvec  xout 
)

Calculate a single center of mass/geometry iteratively with PBC.

Parameters
[in]topTopology structure with masses (can be NULL if bMASS==false).
[in]xPosition vectors of all atoms.
[in]pbcPeriodic boundary conditions structure.
[in]nrefatNumber of atoms in the index.
[in]indexIndices of atoms.
[in]bMassIf true, mass weighting is used.
[out]xoutCOM/COG position for the indexed atoms.

Calls either gmx_calc_com() or gmx_calc_cog() depending on the value of bMass. Other parameters are passed unmodified to these functions.