From 24334a6911bc8ec3e90b5338d0ee3f5ad18bb187 Mon Sep 17 00:00:00 2001 From: Harry Brough Date: Fri, 14 Aug 2026 11:46:54 +0100 Subject: [PATCH] Documentation for variable ionic masses, in dynamics section --- index_dynamics.rst | 1 + keywords.rst | 193 +++++++++++++++++++++++++++----------------- variable_masses.rst | 125 ++++++++++++++++++++++++++++ 3 files changed, 243 insertions(+), 76 deletions(-) create mode 100644 variable_masses.rst diff --git a/index_dynamics.rst b/index_dynamics.rst index e6a705f..918879f 100644 --- a/index_dynamics.rst +++ b/index_dynamics.rst @@ -12,3 +12,4 @@ Dynamics BOMD.rst phonons.rst + variable_masses.rst diff --git a/keywords.rst b/keywords.rst index 152bde2..5562ca9 100644 --- a/keywords.rst +++ b/keywords.rst @@ -6650,9 +6650,9 @@ Defines the atoms that form the leads for the calculation of the transport coeff .. code:: In this example, three leads are defined containing 36, 60 and 20 atoms. - - - + + + %BLOCK ETRANS_LEADS 037 072 073 108 241 300 301 360 @@ -6856,9 +6856,9 @@ Defines the atoms used for the calculation of the transport coefficients. The bl In this example, all atoms between 37 and 640 will be used. All other atoms are considered as buffer atoms. Note: This syntax is not compatible with versions earlier than ONETEP 3.3.4 - - - + + + %BLOCK ETRANS_SETUP 037 640 %ENDBLOCK ETRANS_SETUP @@ -14724,15 +14724,15 @@ The list of :ref:`nbo-plot-orbtype` orbitals to be plotted, identified by their .. code:: GENNBO output indices specified on separate lines: - - - + + + %BLOCK NBO_LIST_PLOTNBO - + 8 - + 10 - + %ENDBLOCK NBO_LIST_PLOTNBO .. _nbo-plot-orbtype: @@ -14894,15 +14894,15 @@ Optional user-defined (false) lm-label for NGWFs according to gennbo convention. .. code:: Species not specified will default to AUTO: - - - + + + %BLOCK NBO_SPECIES_NGWFLABEL - + C1 "1N 151N 152N 153N" - + H1 "AUTO" - + %ENDBLOCK NBO_SPECIES_NGWFLABEL .. _nbo-write-dipole: @@ -15033,15 +15033,15 @@ Block of lists of species to be included in the partial matrix output of seednam .. code:: If specified will default to AUTO: - - - + + + %BLOCK NBO_WRITE_SPECIES - + C1 - + H1 - + %ENDBLOCK NBO_WRITE_SPECIES .. _neb-ci-delay: @@ -16386,15 +16386,15 @@ List of Gamma-point modes (where 1 is the lowest) for which to write xyz animati .. code:: %BLOCK PHONON_ANIMATE_LIST - + 2 - + 6 - + 33 - + 34 - + %ENDBLOCK PHONON_ANIMATE_LIST .. _phonon-animate-scale: @@ -16494,13 +16494,13 @@ List of force constant calculations to perform for Stage 2 in phonon calculation .. code:: %BLOCK PHONON_DISP_LIST - + 1 - + 3 - + 5 - + %ENDBLOCK PHONON_DISP_LIST .. _phonon-dos: @@ -16698,24 +16698,24 @@ This is a block in which the user can list specific ion-coordinate pairs with op PHONON_SAMPLING , and PHONON_FINITE_DISP - + as such: the displacement of ion 10 in the z-direction (3) is switched on (1), with a value of phonon_sampling of 2, and a value of phonon_finite_disp of 0.9 times the global value; displacement of ion 15 in the x-direction (1) is switched off (0), with the last two parameters not being read; displacement of ion 36 in the y-direction (2) is switched off (0), with the last two parameters not being read. - - - + + + %BLOCK PHONON_EXCEPTION_LIST - + 10 3 1 2 0.9 - + 15 1 0 1 1.0 - + 36 2 0 1 1.0 - + %ENDBLOCK PHONON_EXCEPTION_LIST .. _phonon-farming-task: @@ -16843,13 +16843,13 @@ Definition of the regular grid of q-points used in phonon calculations for the c .. code:: In this example, we define a 10x10x10 sampling grid (over b1, b2 and b3 respectively), instead of the 1x1x1 default grid. - - - + + + %BLOCK PHONON_GRID - + 10 10 10 - + %ENDBLOCK PHONON_GRID .. _phonon-min-freq: @@ -16918,19 +16918,19 @@ List of additional q-points for which to calculate the phonon frequencies, in fr .. code:: %BLOCK PHONON_QPOINTS - + 0.0 0.0 0.0 - + 0.0 0.0 0.1 - + 0.0 0.0 0.2 - + 0.0 0.0 0.3 - + 0.0 0.0 0.4 - + 0.0 0.0 0.5 - + %ENDBLOCK PHONON_QPOINTS .. _phonon-sampling: @@ -18196,7 +18196,7 @@ Specifies the spacing between psinc grid points in the simulation cell by three PSINC_SPACING 0.4 0.5 0.5 or - + PSINC_SPACING 0.25 0.25 0.25 ang .. _pspot-bc: @@ -19868,16 +19868,16 @@ Within this block, the first line gives the shape of the :ref:`supercell` (2x2x2 Si), with the ions of index 1 and 9 defining the "base" unit cell. Of course, a small SUPERCELL will not give sensible results for a phonon calculation. However, a good example would be a 1000-atom cubic SUPERCELL of Si, which gives excellent results. - - + + %BLOCK SUPERCELL - + 2 2 2 - + 1 - + 9 - + %ENDBLOCK SUPERCELL .. _swri: @@ -20313,21 +20313,21 @@ Defines the molecular dynamics THERMOSTAT. For each THERMOSTAT, the first line s the equilibration (3000 steps) and Nose-Hoover THERMOSTAT for the thermodynamical sampling (10000 steps). The input parameters could look like. - - - + + + %BLOCK THERMOSTAT - + 1 3000 langevin 300.0 K - + damp = 0.2 - + 3001 13000 nosehoover 300.0 K - + nchain = 4 - + tau = 800 aut - + %ENDBLOCK THERMOSTAT .. _thole-polarisabilities: @@ -21129,15 +21129,15 @@ This option allows the user to specify parameters for elements and functionals f .. code:: For example, to override the disp ersion parameters asso ciated with nitrogen: - - - + + + %BLOCK VDW_PARAMS - + ! nzatom, c6coeff, radzero, neff - + 7 21.1200 2.6200 2.51 - + %ENDBLOCK VDW_PARAMS .. _vdw-radial-cutoff: @@ -21796,4 +21796,45 @@ Forces the total ionic force to be zero by subtracting the average ionic force f .. code:: - ZERO_TOTAL_FORCE F \ No newline at end of file + ZERO_TOTAL_FORCE F + +.. _species-mass: + +SPECIES_MASS +------------ + +:Type: Block +:Default: None +:Unit: amu +:Level: Basic +:Group: None +:Search: :searchlink:`SPECIES_MASS` + +Variable ionic masses for each species (symbol, mass) + +Defines the masses of ions. The atomic species details must match those given in the :ref:`species` block, although not all species need listing. Omitted species retain their default ionic masses. By default, the masses will be interpreted as being in atomic mass units (amu). + +.. note:: + :collapsible: closed + + :Syntax: + + .. code:: + + %BLOCK SPECIES_MASS + S1 M1 + S2 M2 + . . . . . + . . . . . + SN MN + %ENDBLOCK SPECIES_MASS + + :Example: + + .. code:: + + %BLOCK species + H 2.014102 ; use deuterium instead of protium + C 13.00335 ; use :sup:`13`\ C instead of :sup:`12`\ C + O 17.99916 ; use :sup:`18`\ O instead of :sup:`16`\ O + %ENDBLOCK SPECIES_MASS diff --git a/variable_masses.rst b/variable_masses.rst new file mode 100644 index 0000000..aaad39e --- /dev/null +++ b/variable_masses.rst @@ -0,0 +1,125 @@ +============================================= +Variable Ionic Masses +============================================= + +:Author: Harry Brough, University of Manchester + +Introduction +=================================== + +ONETEP [Skylaris2005]_ assigns every ionic species a default mass, taken +from an internal table and determined by the element. The ``species_mass`` block, introduced in v8.2, overrides +these defaults on a per-species basis, allowing isotopic substitution without altering the electronic structure of the +calculation. + +This is of use for: + +* **Molecular dynamics** — isotope effects on diffusion and rates of + barrier crossing. +* **Vibrational and phonon calculations** — isotopic shifts of harmonic + frequencies, zero-point energies, thermochemical corrections, and + hence kinetic isotope effects. + +Because the Born-Oppenheimer potential energy surface does not depend on +the ionic masses, no aspect of the electronic structure calculation is +changed: total energies, forces, NGWFs, the density kernel and the +locations of stationary points are all identical to those obtained with +the default masses. Only mass-dependent nuclear properties are affected. + +Keywords +=================================== + +The atomic masses can be specified with the ``species_mass`` block keyword, as shown: + +:: + + %block species_mass + H 2.014102 + C 13.00335 + O 17.99916 + %endblock species_mass + + +This requests a calculation with deuterium instead of protium, and with :sup:`13`\ C and :sup:`18`\ O nuclei. The +first entry on each line is the species label, exactly as it appears in the first column of the ``species`` block. + +Not every atomic species needs to be listed in ``species_mass``; any species omitted retains its default mass. + +By default, the mass units are atomic mass units (amu) — this can be changed in the same way as other block keywords. Other possible units are grams (g) and kilograms (kg). + +Selective Isotopic Substitution +============================================= + +Because ``species_mass`` acts on species labels rather than on elements, +distinct labels must be introduced in the ``species`` block in order to +substitute only some atoms of a given element. To deuterate a single +hydroxyl hydrogen, for instance: + +:: + + %block species + H H 1 1 8.0 + H_D H 1 1 8.0 + O O 8 4 8.0 + %endblock species + + %block species_mass + H_D 2.014102 + %endblock species_mass + +Both hydrogen labels share the same element, atomic number and +pseudopotential, and only the mass differs. Atoms are then assigned to one +label or the other in the ``positions_abs`` block. + +Default Masses +=================================== + +The ionic masses that ONETEP uses by default are tabulated here, which are generally natural +abundance standard atomic weights. + +=== === ========== === === ========== === === ========== +Z El. Mass / amu Z El. Mass / amu Z El. Mass / amu +=== === ========== === === ========== === === ========== +1 H 1.00794 38 Sr 87.62 75 Re 186.207 +2 He 4.00260 39 Y 88.90585 76 Os 190.23 +3 Li 6.941 40 Zr 91.224 77 Ir 192.217 +4 Be 9.012187 41 Nb 92.90638 78 Pt 195.078 +5 B 10.811 42 Mo 95.94 79 Au 196.96655 +6 C 12.0107 43 Tc 98.0 80 Hg 200.59 +7 N 14.00674 44 Ru 101.07 81 Tl 204.3833 +8 O 15.9994 45 Rh 102.90550 82 Pb 207.2 +9 F 18.99840 46 Pd 106.42 83 Bi 208.98038 +10 Ne 20.1797 47 Ag 107.8682 84 Po 209.0 +11 Na 22.98977 48 Cd 112.411 85 At 210.0 +12 Mg 24.3050 49 In 114.818 86 Rn 222.0 +13 Al 26.98154 50 Sn 118.710 87 Fr 223.0 +14 Si 28.0855 51 Sb 121.760 88 Ra 226.0 +15 P 30.97376 52 Te 127.60 89 Ac 227.0 +16 S 32.066 53 I 126.90447 90 Th 232.0381 +17 Cl 35.4527 54 Xe 131.29 91 Pa 231.03588 +18 Ar 39.948 55 Cs 132.90545 92 U 238.0289 +19 K 39.0983 56 Ba 137.327 93 Np 237.0 +20 Ca 40.078 57 La 138.9055 94 Pu 244.0 +21 Sc 44.95591 58 Ce 140.116 95 Am 243.0 +22 Ti 47.867 59 Pr 140.90765 96 Cm 247.0 +23 V 50.9415 60 Nd 144.24 97 Bk 247.0 +24 Cr 51.9961 61 Pm 145.0 98 Cf 251.0 +25 Mn 54.93805 62 Sm 150.36 99 Es 252.0 +26 Fe 55.845 63 Eu 151.964 100 Fm 257.0 +27 Co 58.93320 64 Gd 157.25 101 Md 258.0 +28 Ni 58.6934 65 Tb 158.92534 102 No 259.0 +29 Cu 63.546 66 Dy 162.50 103 Lr 262.0 +30 Zn 65.39 67 Ho 164.93032 104 Rf 261.0 +31 Ga 69.723 68 Er 167.26 105 Db 262.0 +32 Ge 72.61 69 Tm 168.93421 106 Sg 263.0 +33 As 74.92160 70 Yb 173.04 107 Bh 264.0 +34 Se 78.96 71 Lu 174.967 108 Hs 265.0 +35 Br 79.904 72 Hf 178.49 109 Mt 268.0 +36 Kr 83.80 73 Ta 180.9479 +37 Rb 85.4678 74 W 183.84 +=== === ========== === === ========== === === ========== + +References +=================================== + +.. [Skylaris2005] C.-K. Skylaris et al., J. Chem. Phys. **122**, 084119 (2005).