Action: VORONOI_DISTANCE
| Module | colvar |
|---|---|
| Description | Usage |
| Calculate a distance-weighted product of smooth coordination defects. |   |
| output value | type |
| the distance-weighted product of selected smooth occupancy defects | scalar |
Details and examples
Calculate a distance-weighted product of smooth coordination defects.
This Action combines the continuously changing identities defined by VORONOI_COORDINATION with physical center-center distances. It is useful when the progress of a reactive event depends not only on whether defects exist, but also on how far apart the corresponding sites are.
Definition and group semantics
Let \f be the smooth coordination defect of center \f. When both GROUP1 and GROUP2 are supplied, the Action returns
\f[ D(G_1,G_2)=-\sum_{i\in G_1}\sum_{k\in G_2}d_{ik}q_iq_k . \f]
GROUP1 and GROUP2 are explicit, nonempty, disjoint subsets of CENTERS. When GROUP2 is omitted, unique pairs within GROUP1 are used:
\f[ D(G_1)=-\sum_{\substack{i,k\in G_1\i<k}}d_{ik}q_iq_k . \f]
The center-center distance \f uses the minimum image unless NOPBC is specified. CENTERS, ASSIGNED, KAPPA, REFERENCE, NOPBC, and NLIST have the same meaning as on the VORONOI_COORDINATION page. NLIST truncates only the CENTER-ASSIGNED candidates used to construct the defects; it never removes GROUP1/GROUP2 center-center reduction pairs.
The product \f emphasizes pairs of centers carrying correlated or complementary defects without assigning a permanent ion identity. For one positive and one negative defect, the overall minus sign makes the leading term positive and approximately equal to their separation when the defects approach +1 and -1. Multiple defects generate a sum over all requested pairs; the output should not then be interpreted automatically as one unique ion-ion distance.
Derivatives, periodicity, and bias suitability
Both contributions to the derivative are included: the direct derivative of \f and the chain-rule derivative of every \f through the soft assignment. Analytical box derivatives are also provided using the same minimum-image vectors. The Action stops if a requested center-center distance is zero or non-finite because its radial derivative is then undefined.
The exact full-pair assignment is smooth away from coincident atoms and the usual minimum-image branch surfaces. NLIST uses the approximate truncated normalization described on the VORONOI_COORDINATION page and may add membership discontinuities. Validate the exact Action with numerical derivatives before biasing it, and converge values and forces separately if NLIST is required.
VORONOI_DISTANCE is not normalized by the amount of defect. It naturally approaches zero in a neutral configuration, but its magnitude also changes as defects form or disappear. This coupling is often desired in a reaction coordinate; if a pure conditional distance is intended, its low-defect limit must be defined explicitly rather than obtained by dividing by a nearly zero weight.
Choosing GROUP1 and GROUP2
- Use GROUP1 without GROUP2 for separation among possible sites in one pool, such as water O atoms that can host a hydronium or hydroxide defect.
- Use both groups for cross separation between two chemical pools, such as water O atoms and one reactive N or O site.
- Combine multiple VORONOI_DISTANCE Actions with COMBINE when a published CV contains several physically distinct pair sets. Keeping the pair sets explicit avoids hidden chemistry and atom-order rules.
Worked example 1: water self-ion separation
For one hydronium-hydroxide pair distributed over water oxygen atoms, unique pairs within WaterO describe the solution ion-ion separation.
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 ionization: VORONOI_COORDINATIONCalculate a scalar reduction of smooth Voronoi coordination defects. 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 POWER Power of the selected occupancy defects; supported values are 1 and 2=2 solution_distance: VORONOI_DISTANCECalculate a distance-weighted product of smooth coordination defects. 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 GROUP1First explicit subset of CENTERS=WaterO PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=ionization,solution_distance FILEthe name of the file on which to output these quantities=COLVAR
Check the CV on neutral water, a separated ion pair, and intermediate proton transfer frames. A near-zero value in neutral water is expected and does not mean the distance calculation failed.
Worked example 2: one reactive O and one reactive N
The following example shows that reactive sites are selected by atom number, not by being the last atoms in CENTERS. The reference values are illustrative and must be replaced by the chemically intended occupancies.
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 ReactiveO: 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 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=5 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=6-13 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=ReactiveN,WaterO,ReactiveO activity: VORONOI_COORDINATIONCalculate a scalar reduction of smooth Voronoi coordination defects. This action has hidden defaults. More details CENTERSAtoms that receive the smooth assignment=Centers ASSIGNEDAtoms that are distributed over CENTERS=TransferableH 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=1,2,2,2,1 POWER Power of the selected occupancy defects; supported values are 1 and 2=2 water_to_O: VORONOI_DISTANCECalculate a distance-weighted product of smooth coordination defects. More details CENTERSAtoms that receive the smooth assignment=Centers ASSIGNEDAtoms that are distributed over CENTERS=TransferableH 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=1,2,2,2,1 GROUP1First explicit subset of CENTERS=WaterO GROUP2Optional disjoint second subset of CENTERS; if omitted, unique pairs within GROUP1 are used=ReactiveO water_to_N: VORONOI_DISTANCECalculate a distance-weighted product of smooth coordination defects. More details CENTERSAtoms that receive the smooth assignment=Centers ASSIGNEDAtoms that are distributed over CENTERS=TransferableH 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=1,2,2,2,1 GROUP1First explicit subset of CENTERS=WaterO GROUP2Optional disjoint second subset of CENTERS; if omitted, unique pairs within GROUP1 are used=ReactiveN PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=activity,water_to_O,water_to_N FILEthe name of the file on which to output these quantities=COLVAR
If only one site is present, remove the other site from CENTERS and remove its matching REFERENCE entry. No C++ change is required.
Worked example 3: solvated glycine
The glycine distance used in \cite Zhang2024Glycine contains a water-glycine
cross term and an internal N-O term. Writing them separately removes the
legacy NRX and last-three-atoms convention. The numbered fixture below
contains zwitterionic [Z] glycine, one complete water near its ammonium group,
and one complete water near its carboxylate group. Glycine C atoms and C-H
atoms remain in the coordinate file to make the topology readable, but the
non-transferable C-H atoms are excluded from ASSIGNED.
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=2,3,5,6 GlyN: 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=7 GlyH: 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=8,9,10 GlyO1: 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=15 GlyO2: 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=16 AllH: 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=WaterH,GlyH 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,GlyN,GlyO1,GlyO2 sp: VORONOI_COORDINATIONCalculate a scalar reduction of smooth Voronoi coordination defects. This action has hidden defaults. More details CENTERSAtoms that receive the smooth assignment=Centers ASSIGNEDAtoms that are distributed over CENTERS=AllH 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,0.5,0.5 POWER Power of the selected occupancy defects; supported values are 1 and 2=1 COEFFICIENTSOne coefficient, or one value per atom in SELECT=1,1,2,2,2 sd_water: VORONOI_DISTANCECalculate a distance-weighted product of smooth coordination defects. More details CENTERSAtoms that receive the smooth assignment=Centers ASSIGNEDAtoms that are distributed over CENTERS=AllH 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,0.5,0.5 GROUP1First explicit subset of CENTERS=WaterO GROUP2Optional disjoint second subset of CENTERS; if omitted, unique pairs within GROUP1 are used=GlyN,GlyO1,GlyO2 sd_internal: VORONOI_DISTANCECalculate a distance-weighted product of smooth coordination defects. More details CENTERSAtoms that receive the smooth assignment=Centers ASSIGNEDAtoms that are distributed over CENTERS=AllH 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,0.5,0.5 GROUP1First explicit subset of CENTERS=GlyN GROUP2Optional disjoint second subset of CENTERS; if omitted, unique pairs within GROUP1 are used=GlyO1,GlyO2 sd: COMBINECalculate a polynomial combination of a set of other variables. More details ARGthe values input to this function=sd_water,sd_internal COEFFICIENTS the coefficients of the arguments in your function=1,1 PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=sp,sd_water,sd_internal,sd FILEthe name of the file on which to output these quantities=COLVAR
CENTERS expands to atoms (1,4,7,15,16), so the five REFERENCE entries map to
two water O atoms, glycine N, and two symmetry-related glycine O atoms. The
vector (2,2,2,0.5,0.5) declares the neutral [N] chemical origin even though
the fixture is [Z]. An ideal [Z] frame therefore has defects near
(0,0,+1,-0.5,-0.5), and the seven references sum to the seven atoms in AllH.
The complete full-pair fixture gives sp=0.0073, sd_water=0.0354
\f, sd_internal=2.9789 \f, and
sd=3.0143 \f.
An alternative reference partition can accidentally give the same linear
sp scalar when coefficients and total references cancel. That does not
make it equivalent for VORONOI_DISTANCE, POWER=2, or sign filtering. Use one
physically declared reference vector consistently across the coupled Actions.
The coordinate files, runnable inputs, commands, and expected outputs are in
user-doc/tutorials/others/reactive-voronoi.
The complete application is available in the
GlycineTautomerism repository.
Worked example 4: nitrogen-reduction proton transfer
The published Ru single-atom nitrogen-reduction input in \cite Zhang2026NRR uses water oxygen atoms and one reactive nitrogen as the active Voronoi centers. Catalyst and other adsorbate groups may appear in the full simulation input, but they are not automatically active in these Actions.
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 solvation: VORONOI_COORDINATIONCalculate a scalar reduction of smooth Voronoi coordination defects. This action has hidden defaults. More details CENTERSAtoms that receive the smooth assignment=Centers ASSIGNEDAtoms that are distributed over CENTERS=TransferableH 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 POWER Power of the selected occupancy defects; supported values are 1 and 2=1 COEFFICIENTSOne coefficient, or one value per atom in SELECT=1,1,1,2 solution_ion_distance: VORONOI_DISTANCECalculate a distance-weighted product of smooth coordination defects. More details CENTERSAtoms that receive the smooth assignment=Centers ASSIGNEDAtoms that are distributed over CENTERS=TransferableH 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 GROUP1First explicit subset of CENTERS=WaterO site_ion_distance: VORONOI_DISTANCECalculate a distance-weighted product of smooth coordination defects. More details CENTERSAtoms that receive the smooth assignment=Centers ASSIGNEDAtoms that are distributed over CENTERS=TransferableH 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 GROUP1First explicit subset of CENTERS=WaterO GROUP2Optional disjoint second subset of CENTERS; if omitted, unique pairs within GROUP1 are used=ReactiveN PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=solvation,solution_ion_distance,site_ion_distance FILEthe name of the file on which to output these quantities=COLVAR
The corresponding files are available in the OPES-DPMD-NRR repository. If the full input uses OPES, enable the optional module as described on the VORONOI_COORDINATION page.
Troubleshooting
GROUP1 must contain at least two atoms when GROUP2 is omitted: a within-group distance requires at least one unique pair. For a single reactive site, use a nonempty disjoint GROUP2.GROUP1 and GROUP2 must be disjoint: a self-pair has no valid radial derivative and is intentionally rejected.- A distance is unexpectedly negative: same-sign defect pairs contribute negatively because of the leading minus sign. Inspect the individual defects and pair-set definition before changing the sign convention.
- A value grows with the number of defects: the Action is a pair sum, not a normalized nearest-pair distance. Reduce the groups or define a different mathematical observable if that behavior is not intended.
- A periodic trajectory jumps: inspect minimum-image branch crossings and whether an unwrapped or externally referenced coordinate is actually needed.
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 |
| GROUP1 | atoms | First explicit subset of CENTERS |
| GROUP2 | atoms | Optional disjoint second subset of CENTERS; if omitted, unique pairs within GROUP1 are used |
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 |
| GROUP1 | input | none | First explicit subset of CENTERS |
| GROUP2 | input | none | Optional disjoint second subset of CENTERS; if omitted, unique pairs within GROUP1 are used |
| 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 |
| 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 |