Skip to content

Action: VORONOI_POSITION

Module colvar
Description Usage
Calculate a defect-weighted Cartesian position relative to a fixed origin. used in 0 tutorialsused in 0 eggs
output value type
the selected defect-weighted Cartesian position relative to ORIGIN scalar

Details and examples

Calculate a defect-weighted Cartesian position relative to a fixed origin.

Molecular identity alone does not say where a hydronium, hydroxide, or another coordination defect is located. This Action weights the coordinates of the possible host centers by the smooth defects defined in VORONOI_COORDINATION. It replaces atom-list-index moments with a physical Cartesian coordinate and provides analytical coordinate and box derivatives.

Legacy index-weighted observables such as \f depend on the order in which centers are listed: reordering chemically identical input can change the value even when the configuration is unchanged. Such an index is useful at most as an internal diagnostic and is a poor general bias coordinate. It is intentionally not reproduced here. Use SELECT and a physical VORONOI_POSITION coordinate when the spatial location of a defect is needed.

Definition

For selected centers \f, Cartesian axis \f, and fixed origin \f, define the displacement

\f[ u_i=\operatorname{minimage}(x_{i,\alpha}-x_0) \f]

when periodic boundaries are active. NOPBC replaces it by the direct Cartesian difference. The unnormalized Action is

\f[ P=\sum_{i\in S}g(q_i)f(u_i), \f]

where \f for defects retained by SIGN and zero for excluded defects. The spatial function is \f by default and \f with ABSOLUTE. SELECT defaults to all CENTERS.

With NORMALIZE, the returned value is

\f[ \bar P=\frac{\sum_i g(q_i)f(u_i)}{\sum_i g(q_i)}. \f]

The unnormalized form naturally approaches zero in a neutral configuration and measures position multiplied by defect activity. The normalized form is a defect-weighted mean position, but is defined only when a selected defect is present. If its denominator is no larger than TOLERANCE, the Action stops instead of returning a NaN or an arbitrarily amplified coordinate.

Selecting the observable

  • SIGN=POSITIVE tracks over-coordinated centers; SIGN=NEGATIVE tracks under-coordinated centers; SIGN=ALL includes both.
  • ABSOLUTE measures distance from the fixed origin. Without ABSOLUTE, the sign of the selected Cartesian side is retained.
  • NORMALIZE removes the magnitude of the total squared defect. Use it only when the relevant defect is guaranteed to exist throughout the sampled region.
  • SELECT restricts possible hosts, for example to water O atoms while leaving a reactive molecular site in CENTERS for the shared assignment.

The sign-gated squared weight has a continuous first derivative at \f but a discontinuous second derivative. ABSOLUTE is non-differentiable at \f. Without ABSOLUTE, the direct Cartesian derivative is smooth away from the periodic branch cut.

Derivatives and bias suitability

The implementation differentiates both the defect weight and the selected center coordinate. With NORMALIZE, the quotient rule is evaluated analytically. Box derivatives use the same periodic images as the value. This makes the Action usable as a bias coordinate within its declared smooth region, but the following surfaces require special care:

  1. the minimum-image branch at half the periodic cell length;
  2. the ABSOLUTE cusp at ORIGIN;
  3. the second-derivative cusp where a sign-selected defect changes sign;
  4. an NLIST membership change;
  5. the low-weight boundary of NORMALIZE.

A numerical derivative check must use a frame away from these surfaces. A successful check at one frame does not remove a branch cut elsewhere in the sampled domain.

Periodic boundaries and reference frames

ORIGIN is a fixed Cartesian coordinate, not an atom, a center of mass, or an automatically detected interface. With periodic boundaries, the displacement is minimum-image and therefore has a branch cut. This is appropriate only when the cell and origin define a reproducible frame.

For a drifting slab, moving droplet, flexible pore, or fluctuating interface, first construct a physically justified external reference and keep all coordinates in one consistent image convention. VORONOI_POSITION does not unwrap trajectories or locate an instantaneous interface. NOPBC removes the minimum-image mapping but does not by itself make wrapped molecular-dynamics coordinates continuous.

NLIST has the same approximate normalization and convergence requirements as VORONOI_COORDINATION. Position values can magnify small assignment errors through the distance from ORIGIN, so converge both the CV and its derivatives against full-pair mode.

Worked example 1: water self-ions at an interface

For a slab normal to \f, positive and negative defects can be monitored relative to a fixed reference plane. The unnormalized form below remains defined in neutral configurations.

Click on the labels of the actions for more information on what each action computes
tested on2.11
UNITSThis command sets the internal units for the code. More details LENGTHthe units of lengths=A
WaterO: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=1-4
WaterH: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=5-12

h3o_z: VORONOI_POSITIONCalculate a defect-weighted Cartesian position relative to a fixed origin. This action has hidden defaults. More details CENTERSAtoms that receive the smooth assignment=WaterO ASSIGNEDAtoms that are distributed over CENTERS=WaterH KAPPAPositive soft-assignment sharpness in inverse PLUMED length units=5 REFERENCEOne intended occupancy broadcast to all CENTERS, or one value per CENTER in CENTERS order=2 AXISCartesian axis X, Y, or Z=Z ORIGINFixed Cartesian origin coordinate=5 SIGN Use ALL, POSITIVE, or NEGATIVE defects=POSITIVE ABSOLUTE Use the absolute displacement from ORIGIN
oh_z: VORONOI_POSITIONCalculate a defect-weighted Cartesian position relative to a fixed origin. This action has hidden defaults. More details CENTERSAtoms that receive the smooth assignment=WaterO ASSIGNEDAtoms that are distributed over CENTERS=WaterH KAPPAPositive soft-assignment sharpness in inverse PLUMED length units=5 REFERENCEOne intended occupancy broadcast to all CENTERS, or one value per CENTER in CENTERS order=2 AXISCartesian axis X, Y, or Z=Z ORIGINFixed Cartesian origin coordinate=5 SIGN Use ALL, POSITIVE, or NEGATIVE defects=NEGATIVE ABSOLUTE Use the absolute displacement from ORIGIN
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=h3o_z,oh_z FILEthe name of the file on which to output these quantities=COLVAR

The two values combine defect amount and distance from the plane. They are well suited to monitoring neutral frames because both become zero as their selected defect disappears.

Worked example 2: normalized ion location

When a positive defect is known to remain present, NORMALIZE returns its defect-weighted mean signed location. This input intentionally omits ABSOLUTE so the two sides of the reference plane remain distinguishable.

Click on the labels of the actions for more information on what each action computes
tested on2.11
UNITSThis command sets the internal units for the code. More details LENGTHthe units of lengths=A
WaterO: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=1-4
WaterH: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=5-12

h3o_signed_z: VORONOI_POSITIONCalculate a defect-weighted Cartesian position relative to a fixed origin. More details CENTERSAtoms that receive the smooth assignment=WaterO ASSIGNEDAtoms that are distributed over CENTERS=WaterH KAPPAPositive soft-assignment sharpness in inverse PLUMED length units=5 REFERENCEOne intended occupancy broadcast to all CENTERS, or one value per CENTER in CENTERS order=2 AXISCartesian axis X, Y, or Z=Z ORIGINFixed Cartesian origin coordinate=5 SIGN Use ALL, POSITIVE, or NEGATIVE defects=POSITIVE NORMALIZE Divide by the total selected defect weight TOLERANCE Minimum total weight accepted by NORMALIZE=1e-10
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=h3o_signed_z FILEthe name of the file on which to output these quantities=COLVAR

Do not use this normalized form in a trajectory that can become neutral. In that case the fail-closed TOLERANCE error is expected; use the unnormalized form or a separately justified state-dependent workflow.

Worked example 3: restrict hosts while retaining a reactive site

All centers participate in assigning the transferable hydrogens, while SELECT restricts the reported location to water oxygen atoms. This is useful when a reactive molecular or catalytic site must compete for protons but should not be interpreted as an interfacial water ion.

Click on the labels of the actions for more information on what each action computes
tested on2.11
UNITSThis command sets the internal units for the code. More details LENGTHthe units of lengths=A
WaterO: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=1-3
ReactiveN: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=4
TransferableH: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=5-11
Centers: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=WaterO,ReactiveN

water_positive_z: VORONOI_POSITIONCalculate a defect-weighted Cartesian position relative to a fixed origin. This action has hidden defaults. More details CENTERSAtoms that receive the smooth assignment=Centers ASSIGNEDAtoms that are distributed over CENTERS=TransferableH SELECTSubset of CENTERS included in the position; the default is all centers=WaterO KAPPAPositive soft-assignment sharpness in inverse PLUMED length units=5 REFERENCEOne intended occupancy broadcast to all CENTERS, or one value per CENTER in CENTERS order=2,2,2,1 AXISCartesian axis X, Y, or Z=Z ORIGINFixed Cartesian origin coordinate=5 SIGN Use ALL, POSITIVE, or NEGATIVE defects=POSITIVE ABSOLUTE Use the absolute displacement from ORIGIN
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=water_positive_z FILEthe name of the file on which to output these quantities=COLVAR

The air-water and oil-water applications are available in the OilWaterInterface repository and are described in \cite Zhang2025Interfaces. Historical NL_CUTOFF, NL_STRIDE, and ORIGIN values are system-specific and should not be copied without new full-pair and reference-frame validation.

Validation checklist and troubleshooting

  • Visualize the selected centers and ORIGIN in representative periodic frames.
  • Translate the system by a lattice vector and verify the same minimum-image value.
  • Place a test center on both sides of a boundary and map the expected branch explicitly.
  • Compare analytical and numerical coordinate and box derivatives away from the branch cut, ABSOLUTE cusp, and sign boundary.
  • Confirm that NORMALIZE remains safely above TOLERANCE over the intended trajectory.
  • If the sign is reversed, inspect AXIS, ORIGIN, image convention, and whether ABSOLUTE was intended.
  • If the value jumps by about a box length, the trajectory crossed the minimum-image branch; this is a coordinate-design problem, not a force precision problem.
  • If a drifting interface is the true reference, define and validate that moving reference before applying a bias. Changing ORIGIN to a guessed constant only hides the drift.

Input

The atoms that serve as the input for this action are specified using one or more of the keywords in the following table.

Keyword Type Description
CENTERS atoms Atoms that receive the smooth assignment
ASSIGNED atoms Atoms that are distributed over CENTERS
SELECT atoms Subset of CENTERS included in the position; the default is all centers

Full list of keywords

The following table describes the keywords and options that can be used with this action

Keyword Type Default Description
CENTERS input none Atoms that receive the smooth assignment
ASSIGNED input none Atoms that are distributed over CENTERS
SELECT input none Subset of CENTERS included in the position; the default is all centers
KAPPA compulsory none Positive soft-assignment sharpness in inverse PLUMED length units
REFERENCE compulsory none One intended occupancy broadcast to all CENTERS, or one value per CENTER in CENTERS order
AXIS compulsory none Cartesian axis X, Y, or Z
ORIGIN compulsory none Fixed Cartesian origin coordinate
SIGN compulsory ALL Use ALL, POSITIVE, or NEGATIVE defects
TOLERANCE compulsory 1e-12 Minimum total weight accepted by NORMALIZE
NUMERICAL_DERIVATIVESThis keyword do not have examples optional false calculate the derivatives for these quantities numerically
NOPBCThis keyword do not have examples optional false ignore the periodic boundary conditions when calculating distances
SERIALThis keyword do not have examples optional false Perform the calculation redundantly on each rank for debugging
NLISTThis keyword do not have examples optional false Use an approximate neighbor-list truncation of the assignment candidates
NL_CUTOFFThis keyword do not have examples optional not used Candidate cutoff in PLUMED length units; every ASSIGNED atom must retain at least one CENTER
NL_STRIDEThis keyword do not have examples optional not used Number of steps between neighbor-list updates
NL_SKINThis keyword do not have examples optional not used Nonnegative Verlet buffer in PLUMED length units; requires NL_STRIDE greater than one
ABSOLUTE optional false Use the absolute displacement from ORIGIN
NORMALIZE optional false Divide by the total selected defect weight