centerofmass.h File Reference

#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:

• gmx_calc_cog(): Calculates the center of geometry (COG) of a given group of atoms.
• gmx_calc_com(): Calculates the center of mass (COM) of a given group of atoms.
• gmx_calc_comg(): Calculates either the COM or COG, based on a boolean flag.

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]	top	Topology structure (unused, can be NULL).
[in]	x	Position vectors of all atoms.
[in]	nrefat	Number of atoms in the index.
[in]	index	Indices of atoms.
[out]	xout	COG 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]	top	Topology structure (unused, can be NULL).
[in]	x	Position vectors of all atoms.
[in]	block	t_block structure that divides index into blocks.
[in]	index	Indices of atoms.
[out]	xout	block->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]	top	Topology structure with masses.
[in]	f	Forces on all atoms.
[in]	nrefat	Number of atoms in the index.
[in]	index	Indices of atoms.
[out]	fout	Force 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]	top	Topology structure with masses.
[in]	f	Forces on all atoms.
[in]	block	t_block structure that divides index into blocks.
[in]	index	Indices of atoms.
[out]	fout	block->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]	top	Topology structure (unused, can be NULL).
[in]	x	Position vectors of all atoms.
[in]	pbc	Periodic boundary conditions structure.
[in]	nrefat	Number of atoms in the index.
[in]	index	Indices of atoms.
[out]	xout	COG 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]	top	Topology structure with masses.
[in]	x	Position vectors of all atoms.
[in]	nrefat	Number of atoms in the index.
[in]	index	Indices of atoms.
[out]	xout	COM 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]	top	Topology structure with masses.
[in]	x	Position vectors of all atoms.
[in]	block	t_block structure that divides index into blocks.
[in]	index	Indices of atoms.
[out]	xout	block->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]	top	Topology structure (unused, can be NULL).
[in]	f	Forces on all atoms.
[in]	nrefat	Number of atoms in the index.
[in]	index	Indices of atoms.
[out]	fout	Force 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]	top	Topology structure (unused, can be NULL).
[in]	f	Forces on all atoms.
[in]	block	t_block structure that divides index into blocks.
[in]	index	Indices of atoms.
[out]	fout	block->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]	top	Topology structure with masses.
[in]	x	Position vectors of all atoms.
[in]	pbc	Periodic boundary conditions structure.
[in]	nrefat	Number of atoms in the index.
[in]	index	Indices of atoms.
[out]	xout	COM 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]	top	Topology structure with masses (can be NULL if bMASS==false).
[in]	x	Position vectors of all atoms.
[in]	nrefat	Number of atoms in the index.
[in]	index	Indices of atoms.
[in]	bMass	If true, mass weighting is used.
[out]	xout	COM/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]	top	Topology structure with masses (can be NULL if bMASS==false).
[in]	x	Position vectors of all atoms.
[in]	block	t_block structure that divides index into blocks.
[in]	index	Indices of atoms.
[in]	bMass	If true, mass weighting is used.
[out]	xout	block->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]	top	Topology structure with masses (can be NULL if bMASS==false).
[in]	x	Position vectors of all atoms.
[in]	block	Blocks for calculation.
[in]	bMass	If true, mass weighting is used.
[out]	xout	block->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]	top	Topology structure with masses (can be NULL if bMASS==true).
[in]	f	Forces on all atoms.
[in]	nrefat	Number of atoms in the index.
[in]	index	Indices of atoms.
[in]	bMass	If true, force on COM is calculated.
[out]	fout	Force 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]	top	Topology structure with masses (can be NULL if bMASS==false).
[in]	f	Forces on all atoms.
[in]	block	t_block structure that divides index into blocks.
[in]	index	Indices of atoms.
[in]	bMass	If true, force on COM is calculated.
[out]	fout	block->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]	top	Topology structure with masses (can be NULL if bMASS==true).
[in]	f	Forces on all atoms.
[in]	block	Blocks for calculation.
[in]	bMass	If true, force on COM is calculated.
[out]	fout	block->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]	top	Topology structure with masses (can be NULL if bMASS==false).
[in]	x	Position vectors of all atoms.
[in]	pbc	Periodic boundary conditions structure.
[in]	nrefat	Number of atoms in the index.
[in]	index	Indices of atoms.
[in]	bMass	If true, mass weighting is used.
[out]	xout	COM/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.