ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #4543 from d-immel/apip

Browse Source 
adaptive-precision interatomic potentials (APIP)
This commit is contained in:
Axel Kohlmeyer
2025-06-16 15:56:12 -04:00
committed by GitHub
parent 47fae6b786 0ea4ba28bf
commit 53fec5563c
79 changed files with 99771 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
doc/src/Build_extras.rst
View File

@ -35,6 +35,7 @@ This is the list of packages that may require additional steps.
:columns: 6
* :ref:`ADIOS <adios>`
* :ref:`APIP <apip>`
* :ref:`ATC <atc>`
* :ref:`AWPMD <awpmd>`
* :ref:`COLVARS <colvar>`
@ -1272,6 +1273,34 @@ systems.
----------
.. _apip:
APIP package
-----------------------------
The APIP package depends on the library of the
:ref:`ML-PACE <ml-pace>` package.
The code for the library can be found
at: `https://github.com/ICAMS/lammps-user-pace/ <https://github.com/ICAMS/lammps-user-pace/>`_
.. tabs::
.. tab:: CMake build
No additional settings are needed besides ``-D PKG_APIP=yes``
and ``-D PKG_ML-PACE=yes``.
One can use a local version of the ML-PACE library instead of
automatically downloading the library as described :ref:`here <ml-pace>`.
.. tab:: Traditional make
You need to install the ML-PACE package *first* and follow
the instructions :ref:`here <ml-pace>` before installing
the APIP package.
----------
.. _atc:
ATC package

3
doc/src/Commands_fix.rst
View File

@ -22,6 +22,7 @@ OPT.
* :doc:`append/atoms <fix_append_atoms>`
* :doc:`atc <fix_atc>`
* :doc:`atom/swap <fix_atom_swap>`
* :doc:`atom_weight/apip <fix_atom_weight_apip>`
* :doc:`ave/atom <fix_ave_atom>`
* :doc:`ave/chunk <fix_ave_chunk>`
* :doc:`ave/correlate <fix_ave_correlate>`
@ -91,6 +92,8 @@ OPT.
* :doc:`imd <fix_imd>`
* :doc:`indent <fix_indent>`
* :doc:`ipi <fix_ipi>`
* :doc:`lambda/apip <fix_lambda_apip>`
* :doc:`lambda_thermostat/apip <fix_lambda_thermostat_apip>`
* :doc:`langevin (k) <fix_langevin>`
* :doc:`langevin/drude <fix_langevin_drude>`
* :doc:`langevin/eff <fix_langevin_eff>`

8
doc/src/Commands_pair.rst
View File

@ -96,7 +96,9 @@ OPT.
* :doc:`eam/cd <pair_eam>`
* :doc:`eam/cd/old <pair_eam>`
* :doc:`eam/fs (gikot) <pair_eam>`
* :doc:`eam/fs/apip <pair_eam_apip>`
* :doc:`eam/he <pair_eam>`
* :doc:`eam/apip <pair_eam_apip>`
* :doc:`edip (o) <pair_edip>`
* :doc:`edip/multi <pair_edip>`
* :doc:`edpd (g) <pair_mesodpd>`
@ -124,6 +126,9 @@ OPT.
* :doc:`ilp/tmd (t) <pair_ilp_tmd>`
* :doc:`kolmogorov/crespi/full <pair_kolmogorov_crespi_full>`
* :doc:`kolmogorov/crespi/z <pair_kolmogorov_crespi_z>`
* :doc:`lambda/input/apip <pair_lambda_input_apip>`
* :doc:`lambda/input/csp/apip <pair_lambda_input_apip>`
* :doc:`lambda/zone/apip <pair_lambda_zone_apip>`
* :doc:`lcbop <pair_lcbop>`
* :doc:`lebedeva/z <pair_lebedeva_z>`
* :doc:`lennard/mdf <pair_mdf>`
@ -237,6 +242,9 @@ OPT.
* :doc:`oxrna2/coaxstk <pair_oxrna2>`
* :doc:`pace (k) <pair_pace>`
* :doc:`pace/extrapolation (k) <pair_pace>`
* :doc:`pace/apip <pair_pace_apip>`
* :doc:`pace/fast/apip <pair_pace_apip>`
* :doc:`pace/precise/apip <pair_pace_apip>`
* :doc:`pedone (o) <pair_pedone>`
* :doc:`pod (k) <pair_pod>`
* :doc:`peri/eps <pair_peri>`

1
doc/src/Howto.rst
View File

@ -93,6 +93,7 @@ Packages howto
Howto_manifold
Howto_rheo
Howto_spins
Howto_apip
Tutorials howto
===============

225
doc/src/Howto_apip.rst Normal file
View File

@ -0,0 +1,225 @@
Adaptive-precision interatomic potentials (APIP)
================================================
The :ref:`PKG-APIP <PKG-APIP>` enables use of adaptive-precision potentials
as described in :ref:`(Immel) <Immel2025_1>`.
In the context of this package, precision refers to the accuracy of an interatomic
potential.
Modern machine-learning (ML) potentials translate the accuracy of DFT
simulations into MD simulations, i.e., ML potentials are more accurate
compared to traditional empirical potentials.
However, this accuracy comes at a cost: there is a considerable performance
gap between the evaluation of classical and ML potentials, e.g., the force
calculation of a classical EAM potential is 100-1000 times faster compared
to the ML-based ACE method.
The evaluation time difference results in a conflict between large time and
length scales on the one hand and accuracy on the other.
This conflict is resolved by an APIP model for simulations, in which the highest precision
is required only locally but not globally.
An APIP model uses a precise but
expensive ML potential only for a subset of atoms, while a fast
potential is used for the remaining atoms.
Whether the precise or the fast potential is used is determined
by a continuous switching parameter :math:`\lambda_i` that can be defined for each
atom :math:`i`.
The switching parameter can be adjusted dynamically during a simulation or
kept constant as explained below.
The potential energy :math:`E_i` of an atom :math:`i` described by an
adaptive-precision
interatomic potential is given by :ref:`(Immel) <Immel2025_1>`
.. math::
E_i = \lambda_i E_i^\text{(fast)} + (1-\lambda_i) E_i^\text{(precise)},
whereas :math:`E_i^\text{(fast)}` is the potential energy of atom :math:`i`
according to a fast interatomic potential,
:math:`E_i^\text{(precise)}` is the potential energy according to a precise
interatomic potential and :math:`\lambda_i\in[0,1]` is the
switching parameter that decides how the potential energies are weighted.
Adaptive-precision saves computation time when the computation of the
precise potential is not required for many atoms, i.e., when
:math:`\lambda_i=1` applies for many atoms.
The currently implemented potentials are:
.. list-table::
:header-rows: 1
* - Fast potential
- Precise potential
* - :doc:`ACE <pair_pace_apip>`
- :doc:`ACE <pair_pace_apip>`
* - :doc:`EAM <pair_eam_apip>`
-
In theory, any short-range potential can be used for an adaptive-precision
interatomic potential. How to implement a new (fast or precise)
adaptive-precision
potential is explained in :ref:`here <implementing_new_apip_styles>`.
The switching parameter :math:`\lambda_i` that combines the two potentials
can be dynamically calculated during a
simulation.
Alternatively, one can set a constant switching parameter before the start
of a simulation.
To run a simulation with an adaptive-precision potential, one needs the
following components:
.. tabs::
.. tab:: dynamic switching parameter
#. :doc:`atom_style apip <atom_style>` so that the switching parameter :math:`\lambda_i` can be stored.
#. A fast potential: :doc:`eam/apip <pair_eam_apip>` or :doc:`pace/fast/apip <pair_pace_apip>`.
#. A precise potential: :doc:`pace/precise/apip <pair_pace_apip>`.
#. :doc:`pair_style lambda/input/apip <pair_lambda_input_apip>` to calculate :math:`\lambda_i^\text{input}`, from which :math:`\lambda_i` is calculated.
#. :doc:`fix lambda/apip <fix_lambda_apip>` to calculate the switching parameter :math:`\lambda_i`.
#. :doc:`pair_style lambda/zone/apip <pair_lambda_zone_apip>` to calculate the spatial transition zone of the switching parameter.
#. :doc:`pair_style hybrid/overlay <pair_hybrid>` to combine the previously mentioned pair_styles.
#. :doc:`fix lambda_thermostat/apip <fix_lambda_thermostat_apip>` to conserve the energy when switching parameters change.
#. :doc:`fix atom_weight/apip <fix_atom_weight_apip>` to approximate the load caused by every atom, as the computations of the pair_styles are only required for a subset of atoms.
#. :doc:`fix balance <fix_balance>` to perform dynamic load balancing with the calculated load.
.. tab:: constant switching parameter
#. :doc:`atom_style apip <atom_style>` so that the switching parameter :math:`\lambda_i` can be stored.
#. A fast potential: :doc:`eam/apip <pair_eam_apip>` or :doc:`pace/fast/apip <pair_pace_apip>`.
#. A precise potential: :doc:`pace/precise/apip <pair_pace_apip>`.
#. :doc:`set <set>` command to set the switching parameter :math:`\lambda_i`.
#. :doc:`pair_style hybrid/overlay <pair_hybrid>` to combine the previously mentioned pair_styles.
#. :doc:`fix atom_weight/apip <fix_atom_weight_apip>` to approximate the load caused by every atom, as the computations of the pair_styles are only required for a subset of atoms.
#. :doc:`fix balance <fix_balance>` to perform dynamic load balancing with the calculated load.
----------
Example
"""""""
.. note::
How to select the values of the parameters of an adaptive-precision
interatomic potential is discussed in detail in :ref:`(Immel) <Immel2025_1>`.
.. tabs::
.. tab:: dynamic switching parameter
Lines like these would appear in the input script:
.. code-block:: LAMMPS
atom_style apip
comm_style tiled
pair_style hybrid/overlay eam/fs/apip pace/precise/apip lambda/input/csp/apip fcc cutoff 5.0 lambda/zone/apip 12.0
pair_coeff * * eam/fs/apip Cu.eam.fs Cu
pair_coeff * * pace/precise/apip Cu.yace Cu
pair_coeff * * lambda/input/csp/apip
pair_coeff * * lambda/zone/apip
fix 2 all lambda/apip 2.5 3.0 time_averaged_zone 4.0 12.0 110 110 min_delta_lambda 0.01
fix 3 all lambda_thermostat/apip N_rescaling 200
fix 4 all atom_weight/apip 100 eam ace lambda/input lambda/zone all
variable myweight atom f_4
fix 5 all balance 100 1.1 rcb weight var myweight
First, the :doc:`atom_style apip <atom_style>` and the communication style are set.
.. note::
Note, that :doc:`comm_style <comm_style>` *tiled* is required for the style *rcb* of
:doc:`fix balance <fix_balance>`, but not for APIP.
However, the flexibility offered by the balancing style *rcb*, compared to the
balancing style *shift*, is advantageous for APIP.
An adaptive-precision EAM-ACE potential, for which the switching parameter
:math:`\lambda` is calculated from the CSP, is defined via
:doc:`pair_style hybrid/overlay <pair_hybrid>`.
The fixes ensure that the switching parameter is calculated, the energy conserved,
the weight for the load balancing calculated and the load-balancing itself is done.
.. tab:: constant switching parameter
Lines like these would appear in the input script:
.. code-block:: LAMMPS
atom_style apip
comm_style tiled
pair_style hybrid/overlay eam/fs/apip pace/precise/apip
pair_coeff * * eam/fs/apip Cu.eam.fs Cu
pair_coeff * * pace/precise/apip Cu.yace Cu
# calculate lambda somehow
variable lambda atom ...
set group all apip/lambda v_lambda
fix 4 all atom_weight/apip 100 eam ace lambda/input lambda/zone all
variable myweight atom f_4
fix 5 all balance 100 1.1 rcb weight var myweight
First, the :doc:`atom_style apip <atom_style>` and the communication style are set.
.. note::
Note, that :doc:`comm_style <comm_style>` *tiled* is required for the style *rcb* of
:doc:`fix balance <fix_balance>`, but not for APIP.
However, the flexibility offered by the balancing style *rcb*, compared to the
balancing style *shift*, is advantageous for APIP.
An adaptive-precision EAM-ACE potential is defined via
:doc:`pair_style hybrid/overlay <pair_hybrid>`.
The switching parameter :math:`\lambda_i` of the adaptive-precision
EAM-ACE potential is set via the :doc:`set command <set>`.
The parameter is not updated during the simulation.
Therefore, the potential is conservative.
The fixes ensure that the weight for the load balancing is calculated
and the load-balancing itself is done.
----------
.. _implementing_new_apip_styles:
Implementing new APIP pair styles
"""""""""""""""""""""""""""""""""
One can introduce adaptive-precision to an existing pair style by modifying
the original pair style.
One should calculate the force
:math:`F_i = - \nabla_i \sum_j E_j^\text{original}` for a fast potential or
:math:`F_i = - (1-\nabla_i) \sum_j E_j^\text{original}` for a precise
potential from the original potential
energy :math:`E_j^\text{original}` to see where the switching parameter
:math:`\lambda_i` needs to be introduced in the force calculation.
The switching parameter :math:`\lambda_i` is known for all atoms :math:`i`
in force calculation routine.
One needs to introduce an abortion criterion based on :math:`\lambda_i` to
ensure that all not required calculations are skipped and compute time can
be saved.
Furthermore, one needs to provide the number of calculations and measure the
computation time.
Communication within the force calculation needs to be prevented to allow
effective load-balancing.
With communication, the load balancer cannot balance few calculations of the
precise potential on one processor with many computations of the fast
potential on another processor.
All changes in the pair_style pace/apip compared to the pair_style pace
are annotated and commented.
Thus, the pair_style pace/apip can serve as an example for the implementation
of new adaptive-precision potentials.
----------
.. _Immel2025_1:
**(Immel)** Immel, Drautz and Sutmann, J Chem Phys, 162, 114119 (2025)

55
doc/src/Packages_details.rst
View File

@ -28,6 +28,7 @@ gives those details.
* :ref:`ADIOS <PKG-ADIOS>`
* :ref:`AMOEBA <PKG-AMOEBA>`
* :ref:`APIP <PKG-APIP>`
* :ref:`ASPHERE <PKG-ASPHERE>`
* :ref:`ATC <PKG-ATC>`
* :ref:`AWPMD <PKG-AWPMD>`
@ -186,6 +187,60 @@ provided by the Ponder group in their
----------
.. _PKG-APIP:
APIP package
------------
**Contents:**
This package provides adaptive-precision interatomic potentials (APIP) as
described in:
D. Immel, R. Drautz and G. Sutmann, "Adaptive-precision potentials for
large-scale atomistic simulations", J. Chem. Phys. 162, 114119 (2025)
`link <immel2025_doi_>`_
Adaptive-precision means, that a fast interatomic potential, such as EAM,
is coupled to a precise interatomic potential, such as ACE.
This package provides the required pair_styles and fixes to run an efficient,
energy-conserving adaptive-precision simulation.
In the context of this package, precision refers to the accuracy of an interatomic
potential.
.. _immel2025_doi: https://doi.org/10.1063/5.0245877
**Authors:**
This package was written by David Immel^1,
Ralf Drautz^2 and Godehard Sutmann^1^2.
^1: Forschungszentrum Juelich, Juelich, Germany
^2: Ruhr-University Bochum, Bochum, Germany
**Install:**
The APIP package requires also the installation of ML-PACE, which has
:ref:`specific installation instructions <ml-pace>` on the
:doc:`Build extras <Build_extras>` page.
**Supporting info:**
* ``src/APIP``: filenames -> commands
* :doc:`Howto APIP <Howto_apip>`
* ``examples/PACKAGES/apip``
* :doc:`fix atom_weight/apip <fix_atom_weight_apip>`
* :doc:`fix lambda/apip <fix_lambda_apip>`
* :doc:`fix lambda_thermostat/apip <fix_lambda_thermostat_apip>`
* :doc:`pair_style eam/apip <pair_eam_apip>`
* :doc:`pair_style lambda/zone/apip <pair_lambda_zone_apip>`
* :doc:`pair_style lambda/input/apip <pair_lambda_input_apip>`
* :doc:`pair_style pace/apip <pair_pace_apip>`
----------
.. _PKG-ASPHERE:
ASPHERE package

5
doc/src/Packages_list.rst
View File

@ -38,6 +38,11 @@ whether an extra library is needed to build and use the package:
- :doc:`AMOEBA and HIPPO howto <Howto_amoeba>`
- amoeba
- no
* - :ref:`APIP <PKG-APIP>`
- adaptive-precision interatomic potentials
- :doc:`Howto APIP <Howto_apip>`
- ``PACKAGES/apip``
- ext
* - :ref:`ASPHERE <PKG-ASPHERE>`
- aspherical particle models
- :doc:`Howto spherical <Howto_spherical>`

6
doc/src/atom_style.rst
View File

@ -10,7 +10,7 @@ Syntax
atom_style style args
* style = *amoeba* or *angle* or *atomic* or *body* or *bond* or *charge* or *dielectric* or *dipole* or *dpd* or *edpd* or *electron* or *ellipsoid* or *full* or *line* or *mdpd* or *molecular* or *oxdna* or *peri* or *smd* or *sph* or *sphere* or *bpm/sphere* or *spin* or *tdpd* or *tri* or *template* or *wavepacket* or *hybrid*
* style = *amoeba* or *angle* or *apip* or *atomic* or *body* or *bond* or *charge* or *dielectric* or *dipole* or *dpd* or *edpd* or *electron* or *ellipsoid* or *full* or *line* or *mdpd* or *molecular* or *oxdna* or *peri* or *smd* or *sph* or *sphere* or *bpm/sphere* or *spin* or *tdpd* or *tri* or *template* or *wavepacket* or *hybrid*
.. parsed-literal::
@ -117,6 +117,10 @@ the Additional Information section below.
- *bond* + "angle data"
- :ref:`MOLECULE <PKG-MOLECULE>`
- bead-spring polymers with stiffness
* - *apip*
- *atomic* + apip_lambda, apip_lambda_required, apip_lambda_input, apip_lambda_const, apip_lambda_input_ta, apip_e_fast, apip_e_precise, apip_f_const_lambda, apip_f_dyn_lambda
- :ref:`APIP <PKG-APIP>`
- adaptive-precision interatomic potentials(APIP), see :doc:`APIP howto <Howto_apip>`
* - *atomic*
- tag, type, x, v, f, image, mask
-

25
doc/src/compute_property_atom.rst
View File

@ -34,6 +34,8 @@ Syntax
i_name, d_name, i2_name[I], d2_name[I],
vfrac, s0, espin, eradius, ervel, erforce,
rho, drho, e, de, cv, buckling,
apip_lambda, apip_lambda_input, apip_e_fast,
apip_e_precise
.. parsed-literal::
@ -70,6 +72,13 @@ Syntax
*i2_name[I]* = Ith column of custom integer array with name
*d2_name[I]* = Ith column of custom floating-point array with name
.. parsed-literal::
APIP package per-atom properties:
*apip_lambda* = switching parameter
*apip_lambda_input* = input used to calculate the switching parameter
*apip_e_fast,apip_e_precise* = potential energies mixed by the adaptive-precision potential
.. parsed-literal::
PERI package per-atom properties:
@ -162,6 +171,22 @@ segment particles and define the end points of each line segment.
*corner2z*, *corner3x*, *corner3y*, *corner3z*, are defined for
triangular particles and define the corner points of each triangle.
The accessible quantities from the :doc:`APIP package <Howto_apip>` are
explained in the doc pages of this package in detail.
In short: *apip_lambda* is the switching parameter :math:`\lambda\in[0,1]`,
that is calculated from *apip_lambda_input* and that mixes the energies
of a fast (*apip_e_fast*) and a precise (*apip_e_precise*) potential
into an adaptive-precision energy.
.. note::
The energy according to the fast and the precise potential are only
computed for the subset of atoms, for which it is required, i.e.,
for an atom :math:`i` with :math:`\lambda_i=1` one does not need
:math:`E_i^\text{precise}` and with :math:`\lambda_i=0` one does
not need :math:`E_i^\text{fast}`.
In addition, the various per-atom quantities listed above for specific
packages are only accessible by this command.

3
doc/src/fix.rst
View File

@ -201,6 +201,7 @@ accelerated styles exist.
* :doc:`append/atoms <fix_append_atoms>` - append atoms to a running simulation
* :doc:`atc <fix_atc>` - initiates a coupled MD/FE simulation
* :doc:`atom/swap <fix_atom_swap>` - Monte Carlo atom type swapping
* :doc:`atom_weight/apip <fix_atom_weight_apip>` - compute atomic load of an :doc:`APIP potential <Howto_apip>` for load balancing
* :doc:`ave/atom <fix_ave_atom>` - compute per-atom time-averaged quantities
* :doc:`ave/chunk <fix_ave_chunk>` - compute per-chunk time-averaged quantities
* :doc:`ave/correlate <fix_ave_correlate>` - compute/output time correlations
@ -270,6 +271,7 @@ accelerated styles exist.
* :doc:`imd <fix_imd>` - implements the "Interactive MD" (IMD) protocol
* :doc:`indent <fix_indent>` - impose force due to an indenter
* :doc:`ipi <fix_ipi>` - enable LAMMPS to run as a client for i-PI path-integral simulations
* :doc:`lambda/apip <fix_lambda_apip>` - compute switching parameter, that controls the precision of an :doc:`APIP potential <Howto_apip>`
* :doc:`langevin <fix_langevin>` - Langevin temperature control
* :doc:`langevin/drude <fix_langevin_drude>` - Langevin temperature control of Drude oscillators
* :doc:`langevin/eff <fix_langevin_eff>` - Langevin temperature control for the electron force field model
@ -278,6 +280,7 @@ accelerated styles exist.
* :doc:`lb/momentum <fix_lb_momentum>` - :doc:`fix momentum <fix_momentum>` replacement for use with a lattice-Boltzmann fluid
* :doc:`lb/viscous <fix_lb_viscous>` - :doc:`fix viscous <fix_viscous>` replacement for use with a lattice-Boltzmann fluid
* :doc:`lineforce <fix_lineforce>` - constrain atoms to move in a line
* :doc:`lambda_thermostat/apip <fix_lambda_thermostat_apip>` - apply energy conserving correction for an :doc:`APIP potential <Howto_apip>`
* :doc:`manifoldforce <fix_manifoldforce>` - restrain atoms to a manifold during minimization
* :doc:`mdi/qm <fix_mdi_qm>` - LAMMPS operates as a client for a quantum code via the MolSSI Driver Interface (MDI)
* :doc:`mdi/qmmm <fix_mdi_qmmm>` - LAMMPS operates as client for QM/MM simulation with a quantum code via the MolSSI Driver Interface (MDI)

143
doc/src/fix_atom_weight_apip.rst Normal file
View File

@ -0,0 +1,143 @@
.. index:: fix atom_weight/apip
fix atom_weight/apip command
============================
Syntax
""""""
.. code-block:: LAMMPS
fix ID group-ID atom_weight/apip nevery fast_potential precise_potential lambda_input lambda_zone group_lambda_input [no_rescale]
* ID, group-ID are documented in :doc:`fix <fix>` command
* atom_weight/apip = style name of this fix command
* nevery = perform load calculation every this many steps
* fast_potential = *eam* or *ace* for time measurements of the corresponding pair_style or float for constant time
* precise_potential = *ace* for a time measurement of the pair_style pace/apip or float for constant time
* lambda_input = *lambda/input* for a time measurement of pair_style lambda/input/apip or float for constant time
* lambda_zone = *lambda/zone* for a time measurement of pair_style lambda/zone/apip or float for constant time
* group_lambda_input = group-ID of the group for which lambda_input is computed
* no_rescale = do not rescale the work per processor to the measured total force-computation time
Examples
""""""""
.. code-block:: LAMMPS
fix 2 all atom_weight/apip 50 eam ace lambda/input lambda/zone all
fix 2 all atom_weight/apip 50 1e-05 0.0004 4e-06 4e-06 all
fix 2 all atom_weight/apip 50 ace ace 4e-06 4e-06 all no_rescale
Description
"""""""""""
This command approximates the load every atom causes when an
adaptive-precision interatomic potential (APIP) according to
:ref:`(Immel) <Immel2025_2>` is used.
This approximated load can be saved as atomic variable and
used as input for the dynamic load balancing via the
:doc:`fix balance <fix_balance>` command.
An adaptive-precision potential like :doc:`eam/apip <pair_eam_apip>`
and :doc:`pace/apip <pair_pace_apip>` is calculated only
for a subset of atoms.
The switching parameter that determines per atom, which potential energy is
used, can be also calculated by
:doc:`pair_style lambda/input/apip <pair_lambda_input_apip>`.
A spatial switching zone, that ensures a smooth transition between two
different interatomic potentials, can be calculated by
:doc:`pair_style lambda/zone/apip <pair_lambda_zone_apip>`.
Thus, there are up to four force-subroutines, that are computed only for a
subset of atoms and combined via the pair_style :doc:`hybrid/overlay <pair_hybrid>`.
For all four force-subroutines, the average work per atom is be measured
per processor by the corresponding pair_style.
This fix extracts these measurements of the pair styles every *nevery*
steps. The average compute times are used to calculates a per-atom vector with
the approximated atomic weight, whereas the average compute time of the four
subroutines contributes only to the load of atoms, for which the corresponding
subroutine was calculated.
If not disabled via *no_rescale*, the so calculated load is
rescaled per processor so that the total atomic compute time matches the
also measured total compute time of the whole pair_style.
This atomic weight is intended to be used
as input for :doc:`fix balance <fix_balance>`:
.. code-block:: LAMMPS
variable nevery equal 10
fix weight_atom all atom_weight/apip ${nevery} eam ace lambda/input lambda/zone all
variable myweight atom f_weight_atom
fix balance all balance ${nevery} 1.1 rcb weight var myweight
Furthermore, this fix provides the over the processors averaged compute time of the
four pair_styles, which are used to approximate the atomic weight, as vector.
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to
:doc:`binary restart files <restart>`. None of the
:doc:`fix_modify <fix_modify>` options are relevant to this fix.
This fix produces a per-atom vector that contains the atomic
weight of each atom.
The per-atom vector can only be accessed on timesteps that are multiples
of *nevery*.
Furthermore, this fix computes a global vector of length 4 with
statistical information about the four different (possibly)
measured compute times per force subroutine. The four
values in the vector are as follows:
#. average compute time for one atom using the fast pair_style
#. average compute time for one atom using the precise pair_style
#. average compute time of lambda/input/apip for one atom
#. average compute time of lambda/zone/apip for one atom
The compute times are computed as average of all processors that
measured at least one computation of the corresponding style.
The vector values calculated by this fix are "intensive" and
updated whenever the per-atom vector is computed, i.e., in
timesteps that are multiples of *nevery*.
The vector and the per-atom vector can be accessed by various
:doc:`output commands <Howto_output>`.
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command. This fix is not invoked during
:doc:`energy minimization <minimize>`.
----------
Restrictions
""""""""""""
This fix is part of the APIP package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`fix balance <fix_balance>`,
:doc:`fix lambda/apip <fix_lambda_apip>`,
:doc:`fix lambda_thermostat/apip <fix_lambda_thermostat_apip>`,
:doc:`pair_style lambda/zone/apip <pair_lambda_zone_apip>`,
:doc:`pair_style lambda/input/apip <pair_lambda_input_apip>`,
:doc:`pair_style eam/apip <pair_eam_apip>`,
:doc:`pair_style pace/apip <pair_pace_apip>`,
Default
"""""""
*no_rescale* is not used by default.
----------
.. _Immel2025_2:
**(Immel)** Immel, Drautz and Sutmann, J Chem Phys, 162, 114119 (2025)

262
doc/src/fix_lambda_apip.rst Normal file
View File

@ -0,0 +1,262 @@
.. index:: fix lambda/apip
fix lambda/apip command
=======================
Syntax
""""""
.. code-block:: LAMMPS
fix ID group-ID lambda/apip thr_lo thr_hi keyword args ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* lambda/apip = style name of this fix command
* thr_lo = value below which :math:`\lambda_i^\text{input}` results in a switching parameter of 1
* thr_hi = value above which :math:`\lambda_i^\text{input}` results in a switching parameter of 0
* zero or one keyword/args pairs may be appended
* keyword = *time_averaged_zone* or *min_delta_lambda* or *lambda_non_group* or *store_atomic_stats* or *dump_atomic_history* or *group_fast* or *group_precise* or *group_ignore_lambda_input*
.. parsed-literal::
*time_averaged_zone* args = cut_lo cut_hi history_len_lambda_input history_len_lambda
cut_lo = distance at which the radial function decreases from 1
cut_hi = distance from which on the radial function is 0
history_len_lambda_input = number of time steps for which lambda_input is averaged
history_len_lambda = number of time steps for which the switching parameter is averaged
*min_delta_lambda* args = delta
delta = value below which changes of the switching parameter are neglected (>= 0)
*lambda_non_group* args = lambda_ng
lambda_ng = *precise* or *fast* or float
*precise* = assign a constant switching parameter of 0 to atoms, that are not in the group specified by group-ID
*fast* = assign a constant switching parameter of 1 to atoms, that are not in the group specified by group-ID
float = assign this constant switching parameter to atoms, that are not in the group specified by group-ID (0 <= float <= 1)
*group_fast* args = group-ID-fast
group-ID-fast = the switching parameter of 1 is used instead of the one computed by lambda_input for atoms in the group specified by group-ID-fast
*group_precise* args = group-ID-precise
group-ID-precise = the switching parameter of 0 is used instead of the one computed by lambda_input for atoms in the group specified by group-ID-precise
*group_ignore_lambda_input* args = group-ID-ignore-lambda-input
group-ID-ignore-lambda-input = the switching parameter of lambda_ng is used instead of the one computed by lambda_input for atoms in the group specified by group-ID-ignore-lambda-input
*store_atomic_stats* args = none
*dump_atomic_history* args = none
Examples
""""""""
.. code-block:: LAMMPS
fix 2 all lambda/apip 3.0 3.5 time_averaged_zone 4.0 12.0 110 110 min_delta_lambda 0.01
fix 2 mobile lambda/apip 3.0 3.5 time_averaged_zone 4.0 12.0 110 110 min_delta_lambda 0.01 group_ignore_lambda_input immobile lambda_non_group fast
Description
"""""""""""
The potential energy :math:`E_i` of an atom :math:`i` of an adaptive-precision
potential according to :ref:`(Immel) <Immel2025_3>` is given by
.. math::
E_i = \lambda_i E_i^\text{(fast)} + (1-\lambda_i) E_i^\text{(precise)},
whereas :math:`E_i^\text{(fast)}` is the potential energy of atom :math:`i`
according to a fast interatomic potential like EAM,
:math:`E_i^\text{(precise)}` is the potential energy according to a precise
interatomic potential such as ACE and :math:`\lambda_i\in[0,1]` is the
switching parameter that decides which potential energy is used.
This fix calculates the switching parameter :math:`\lambda_i` based on the
input provided from :doc:`pair_style lambda/input/apip <pair_lambda_input_apip>`.
The calculation of the switching parameter is described in detail in
:ref:`(Immel) <Immel2025_3>`.
This fix calculates the switching parameter for all atoms in the
:doc:`group <group>`
described by group-ID, while the value of *lambda_non_group* is used
as switching parameter for all other atoms.
First, this fix calculates per atom :math:`i` the time averaged input
:math:`\lambda^\text{input}_{\text{avg},i}` from
:math:`\lambda^\text{input}_{i}`, whereas the number of averaged timesteps
can be set via *time_averaged_zone*.
.. note::
:math:`\lambda^\text{input}_{i}` is calculated by
:doc:`pair_style lambda/input/apip <pair_lambda_input_apip>`, which needs to be included
in the input script as well.
The time averaged input :math:`\lambda^\text{input}_{\text{avg},i}` is then
used to calculate the switching parameter
.. math::
\lambda_{0,i}(t) = f^\text{(cut)} \left(\frac{\lambda_{\text{avg},i}^\text{input}(t) - \lambda_\text{lo}^\text{input}}{\lambda_\text{hi}^\text{input} - \lambda_\text{lo}^\text{input}} \right)\,,
whereas the thresholds :math:`\lambda_\text{hi}^\text{input}`
and :math:`\lambda_\text{lo}^\text{input}` are set by the
values provided as *thr_lo* and *thr_hi* and :math:`f^\text{(cut)}(x)` is a cutoff function
that is 1 for :math:`x\leq 0`, decays from 1 to 0 for :math:`x\in[0,1]`, and
is 0 for :math:`x\geq 1`.
If the *group_precise* argument is used, :math:`\lambda_{0,i}=0` is used for all
atoms :math:`i` assigned to the corresponding :doc:`group <group>`.
If the *group_fast* argument is used, :math:`\lambda_{0,i}=1` is used for all
atoms :math:`i` assigned to the corresponding :doc:`group <group>`.
If an atom is in the groups *group_fast* and *group_precise*,
:math:`\lambda_{0,i}=0` is used.
If the *group_ignore_lambda_input* argument is used,
:math:`\lambda_i^\text{input}` is not computed for all atoms :math:`i` assigned
to the corresponding :doc:`group <group>`; instead, if the value is not already
set by *group_fast* or *group_precise*, the value of *lambda_non_group* is
used.
.. note::
The computation of :math:`\lambda_i^\text{input}` is not required for
atoms that are in the groups *group_fast* and *group_precise*.
Thus, one should use *group_ignore_lambda_input* and prevent the
computation of :math:`\lambda_i^\text{input}` for all atoms, for
which a constant input is used.
A spatial transition zone between the fast and the precise potential is
introduced via
.. math::
\lambda_{\text{min},i}(t) = \text{min}\left(\left\{1 - (1 -\lambda_{0,j}(t)) f^\text{(cut)}\left(\frac{r_{ij}(t)-r_{\lambda,\text{lo}}}{r_{\lambda,\text{hi}} - r_{\lambda,\text{lo}}}\right) : j \in \Omega_{\lambda,i} \right\}\right)\,,
whereas the thresholds :math:`r_{\lambda,\text{lo}}` and
:math:`r_{\lambda,\text{hi}}`
of the cutoff function are set via *time_averaged_zone* and
:math:`\Omega_{\lambda,i}` is the set of
neighboring atoms of atom :math:`i`.
.. note::
:math:`\lambda_{\text{min},i}` is calculated by
:doc:`pair_style lambda/zone/apip <pair_lambda_zone_apip>`, which needs to be included
in the input script as well.
The switching parameter is smoothed by the calculation of the time average
.. math::
\lambda_{\text{avg},i}(t) = \frac{1}{N_{\lambda,\text{avg}}} \sum_{n=1}^{N_{\lambda,\text{avg}}} \lambda_{\text{min},i}(t - n \Delta t)\,,
whereas :math:`\Delta t` is the :doc:`timestep <timestep>` and
:math:`N_{\lambda,\text{avg}}` is the number of averaged timesteps, that
can be set via *time_averaged_zone*.
Finally, numerical fluctuations of the switching parameter are suppressed by the usage of
.. math::
\lambda_{i}(t) = \left\{
\begin{array}{ll}
\lambda_{\text{avg},i}(t) & \text{ for } \left|\lambda_{\text{avg},i}(t) - \lambda_{i}(t-\Delta t)\right|\geq \Delta\lambda_\text{min} \text{ or } \lambda_{\text{avg},i}(t)\in\{0,1\}, \\
\lambda_{i}(t-\Delta t) & \text{ otherwise}\,,
\end{array}
\right.
whereas the minimum change :math:`\Delta\lambda_\text{min}` is set by the
*min_delta_lambda* argument.
.. note::
*group_fast* affects only :math:`\lambda_{0,i}(t)`. The switching parameter
of atoms in this :doc:`group <group>` may change due to the calculation of the
spatial switching zone.
A switching parameter of 1 can be enforced by excluding the corresponding
atoms from the :doc:`group <group>` described by group-ID and using *lambda_non_group* 1
as argument.
----------
A code example for the calculation of the switching parameter for an
adaptive-precision potential is given in the following:
The adaptive-precision potential is created
by combining :doc:`pair_style eam/fs/apip <pair_eam_apip>`
and :doc:`pair_style pace/precise/apip <pair_pace_apip>`.
The input, from which the switching parameter is calculated, is provided
by :doc:`pair lambda/input/csp/apip <pair_lambda_input_apip>`.
The switching parameter is calculated by this fix, whereas the spatial
transition zone of the switching parameter is calculated by
:doc:`pair_style lambda/zone/apip <pair_lambda_zone_apip>`.
.. code-block:: LAMMPS
pair_style hybrid/overlay eam/fs/apip pace/precise/apip lambda/input/csp/apip fcc cutoff 5.0 lambda/zone/apip 12.0
pair_coeff * * eam/fs/apip Cu.eam.fs Cu
pair_coeff * * pace/precise/apip Cu_precise.yace Cu
pair_coeff * * lambda/input/csp/apip
pair_coeff * * lambda/zone/apip
fix 2 all lambda/apip 3.0 3.5 time_averaged_zone 4.0 12.0 110 110 min_delta_lambda 0.01
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
The saved history of the switching parameter :math:`\lambda_i`
and the saved history of
:math:`\lambda_i^\text{input}` are written to
:doc:`binary restart files <restart>` allow a smooth restart of a simulation.
None of the :doc:`fix_modify <fix_modify>` options are relevant to this fix.
If the *store_atomic_stats* argument is used, basic statistics is provided as
per-atom array:
#. :math:`\lambda_i^\text{input}(t)`
#. :math:`\lambda_{\text{avg},i}^\text{input}(t)`
#. :math:`\lambda_{0,i}(t)`
#. :math:`\lambda_{\text{min},i}(t)`
#. :math:`\lambda_{i}(t)`
If the *dump_atomic_history* argument is used, the whole saved history
of :math:`\lambda_i^\text{input}(t)` is appended to the previously
mentioned array per atom.
The per-atom vector can be accessed by various
:doc:`output commands <Howto_output>`.
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command. This fix is not invoked during
:doc:`energy minimization <minimize>`.
----------
Restrictions
""""""""""""
This fix is part of the APIP package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`pair_style lambda/zone/apip <pair_lambda_zone_apip>`,
:doc:`pair_style lambda/input/apip <pair_lambda_input_apip>`,
:doc:`pair_style eam/apip <pair_eam_apip>`,
:doc:`pair_style pace/apip <pair_pace_apip>`,
:doc:`fix atom_weight/apip <fix_atom_weight_apip>`
:doc:`fix lambda_thermostat/apip <fix_lambda_thermostat_apip>`,
Default
"""""""
*min_delta_lambda* = 0,
*lambda_non_group* = 1,
*cut_lo* = 4.0,
*cut_hi* = 12.0,
*history_len_lambda_input* = 100,
*history_len_lambda* = 100,
*store_atomic_stats* is not used,
*dump_atomic_history* is not used,
*group_fast* is not used,
*group_precise* is not used,
*group_ignore_lambda_input* is not used
----------
.. _Immel2025_3:
**(Immel)** Immel, Drautz and Sutmann, J Chem Phys, 162, 114119 (2025)

176
doc/src/fix_lambda_thermostat_apip.rst Normal file
View File

@ -0,0 +1,176 @@
.. index:: fix lambda_thermostat/apip
fix lambda_thermostat/apip command
==================================
Syntax
""""""
.. code-block:: LAMMPS
fix ID group-ID lambda_thermostat/apip keyword values ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* lambda_thermostat/apip = style name of this fix command
* zero or more keyword/value pairs may be appended
* keyword = *seed* or *store_atomic_forces* or *N_rescaling*
.. parsed-literal::
*seed* value = integer
integer = integer that is used as seed for the random number generator (> 0)
*store_atomic_forces* value = nevery
nevery = provide per-atom output every this many steps
*N_rescaling* value = groupsize
groupsize = rescale this many neighboring atoms (> 1)
Examples
""""""""
.. code-block:: LAMMPS
fix 2 all lambda_thermostat/apip
fix 2 all lambda_thermostat/apip N_rescaling 100
fix 2 all lambda_thermostat/apip seed 42
fix 2 all lambda_thermostat/apip seed 42 store_atomic_forces 1000
Description
"""""""""""
This command applies the local thermostat described in
:ref:`(Immel) <Immel2025_4>`
to conserve the energy when the switching parameters of an
:doc:`adaptive-precision interatomic potential <Howto_apip>` (APIP)
are updated while the gradient
of the switching parameter is neglected in the force calculation.
.. warning::
The temperature change caused by this fix is only the means to the end of
conserving the energy. Thus, this fix is not a classical thermostat, that
ensures a given temperature in the system.
All available thermostats are listed :doc:`here <Howto_thermostat>`.
The potential energy :math:`E_i` of an atom :math:`i` is given by the formula from
:ref:`(Immel) <Immel2025_4>`
.. math::
E_i = \lambda_i E_i^\text{(fast)} + (1-\lambda_i) E_i^\text{(precise)},
whereas :math:`E_i^\text{(fast)}` is the potential energy of atom :math:`i`
according to a fast interatomic potential like EAM,
:math:`E_i^\text{(precise)}` is the potential energy according to a precise
interatomic potential such as ACE and :math:`\lambda_i\in[0,1]` is the
switching parameter that decides which potential energy is used.
This potential energy and the corresponding forces are conservative when
the switching parameter :math:`\lambda_i` is constant in time for all atoms
:math:`i`.
For a conservative force calculation and dynamic switching parameters,
the atomic force on an atom is given by
:math:`F_i = -\nabla_i \sum_j E_j` and includes the derivative of the switching
parameter :math:`\lambda_i`.
The force contribution of this gradient of the switching function can cause
large forces which are not similar to the forces of the fast or the precise
interatomic potential as discussed in :ref:`(Immel) <Immel2025_4>`.
Thus, one can neglect the gradient of the switching parameter in the force
calculation and compensate for the violation of energy conservation by
the application of the local thermostat implemented in this fix.
One can compute the violation of the energy conservation :math:`\Delta H_i`
for all atoms :math:`i` as discussed in :ref:`(Immel) <Immel2025_4>`.
To locally correct this energy violation :math:`\Delta H_i`, one
can rescale the velocity of atom :math:`i` and of neighboring atoms.
The rescaling is done relative to the center-of-mass velocity of the
group and, thus, conserves the momentum.
.. note::
This local thermostat provides the NVE ensemble rather than the NVT
ensemble as
the energy :math:`\Delta H_i` determines the rescaling factor rather than
a temperature.
Velocities :math:`v` are updated by the integrator according to
:math:`\Delta v_i = (F_i/m_i)\Delta t`, whereas `m` denotes the mass of atom
:math:`i` and :math:`\Delta t` is the time step.
One can interpret the velocity difference :math:`\Delta v` caused by the
rescaling as the application of an additional force which is given by
:math:`F^\text{lt}_i = (v^\text{unscaled}_i - v^\text{rescaled}_i) m_i
/ \Delta t` :ref:`(Immel) <Immel2025_4>`.
This additional force is computed when the *store_atomic_forces* option
is used.
The local thermostat is not appropriate for simulations at a temperature of 0K.
.. note::
The maximum decrease of the kinetic energy is achieved with a rescaling
factor of 0, i.e., the relative velocity of the group of rescaled atoms
is set to zero. One cannot decrease the energy further. Thus, the
local thermostat can fail, which is, however, reported by the returned
vector.
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to
:doc:`binary restart files <restart>`. None of the
:doc:`fix_modify <fix_modify>` options are relevant to this fix.
If the *store_atomic_forces* option is used, this fix produces every
*nevery* time steps a per-atom array that contains the theoretical force
applied by the local thermostat in all three spatial dimensions in the first
three components. :math:`\Delta H_i` is the fourth component of the per-atom
array.
The per-atom array can only be accessed on timesteps that are multiples
of *nevery*.
Furthermore, this fix computes a global vector of length 6 with
information about the rescaling:
#. number of atoms whose energy changed due to the last :math:`\lambda` update
#. contribution of the potential energy to the last computed :math:`\Delta H`
#. contribution of the kinetic energy to the last computed :math:`\Delta H`
#. sum over all atoms of the absolute energy change caused by the last rescaling step
#. energy change that could not be compensated accumulated over all timesteps
#. number of atoms whose energy change could not be compensated accumulated over all timesteps
The vector and the per-atom vector can be accessed by various
:doc:`output commands <Howto_output>`.
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command. This fix is not invoked during
:doc:`energy minimization <minimize>`.
----------
Restrictions
""""""""""""
This fix is part of the APIP package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`fix lambda/apip <fix_lambda_apip>`,
:doc:`pair_style lambda/zone/apip <pair_lambda_zone_apip>`,
:doc:`pair_style lambda/input/apip <pair_lambda_input_apip>`,
:doc:`pair_style eam/apip <pair_eam_apip>`,
:doc:`pair_style pace/apip <pair_pace_apip>`,
:doc:`fix atom_weight/apip <fix_atom_weight_apip>`
Default
"""""""
seed = 42, N_rescaling = 200, *store_atomic_forces* is not used
----------
.. _Immel2025_4:
**(Immel)** Immel, Drautz and Sutmann, J Chem Phys, 162, 114119 (2025)

127
doc/src/pair_eam_apip.rst Normal file
View File

@ -0,0 +1,127 @@
.. index:: pair_style eam/apip
.. index:: pair_style eam/fs/apip
pair_style eam/apip command
=============================
Constant precision variant: *eam*
pair_style eam/fs/apip command
================================
Constant precision variant: *eam/fs*
Syntax
""""""
.. code-block:: LAMMPS
pair_style eam/apip
pair_style eam/fs/apip
Examples
""""""""
.. code-block:: LAMMPS
pair_style hybrid/overlay eam/fs/apip pace/precise/apip lambda/input/csp/apip fcc cutoff 5.0 lambda/zone/apip 12.0
pair_coeff * * eam/fs/apip Cu.eam.fs Cu
pair_coeff * * pace/precise/apip Cu_precise.yace Cu
pair_coeff * * lambda/input/csp/apip
pair_coeff * * lambda/zone/apip
Description
"""""""""""
Style *eam* computes pairwise interactions for metals and metal alloys
using embedded-atom method (EAM) potentials :ref:`(Daw) <Daw2>`. The total
energy :math:`E_i` of an atom :math:`i` is given by
.. math::
E_i^\text{EAM} = F_\alpha \left(\sum_{j \neq i}\ \rho_\beta (r_{ij})\right) +
\frac{1}{2} \sum_{j \neq i} \phi_{\alpha\beta} (r_{ij})
where :math:`F` is the embedding energy which is a function of the atomic
electron density :math:`\rho`, :math:`\phi` is a pair potential interaction,
and :math:`\alpha` and :math:`\beta` are the element types of atoms
:math:`i` and :math:`j`. The multi-body nature of the EAM potential is a
result of the embedding energy term. Both summations in the formula are over
all neighbors :math:`j` of atom :math:`i` within the cutoff distance.
EAM is documented in detail in :doc:`pair_style eam <pair_eam>`.
The potential energy :math:`E_i` of an atom :math:`i` of an adaptive-precision
interatomic potential (APIP) according to :ref:`(Immel) <Immel2025_5>` is given by
.. math::
E_i^\text{APIP} = \lambda_i E_i^\text{(fast)} + (1-\lambda_i) E_i^\text{(precise)}\,,
whereas the switching parameter :math:`\lambda_i` is computed
dynamically during a simulation by :doc:`fix lambda/apip <fix_lambda_apip>`
or set prior to a simulation via :doc:`set <set>`.
The pair style *eam/fs/apip* computes the potential energy
:math:`\lambda_i E_i^\text{EAM}` and the
corresponding force and should be combined
with a precise potential like
:doc:`pair_style pace/precise/apip <pair_pace_apip>` that computes the
potential energy :math:`(1-\lambda_i) E_i^\text{(precise)}` and the
corresponding force via :doc:`pair_style hybrid/overlay <pair_hybrid>`.
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
For atom type pairs I,J and I != J, where types I and J correspond to
two different element types, mixing is performed by LAMMPS as
described above with the individual styles. You never need to specify
a pair_coeff command with I != J arguments for the eam/apip styles.
This pair style does not support the :doc:`pair_modify <pair_modify>`
shift, table, and tail options.
The eam/apip pair styles do not write their information to :doc:`binary
restart files <restart>`, since it is stored in tabulated potential
files. Thus, you need to re-specify the pair_style and pair_coeff
commands in an input script that reads a restart file.
The eam/apip pair styles can only be used via the *pair* keyword of the
:doc:`run_style respa <run_style>` command. They do not support the
*inner*, *middle*, *outer* keywords.
----------
Restrictions
""""""""""""
This pair styles are part of the APIP package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`pair_style eam <pair_eam>`,
:doc:`pair_style hybrid/overlay <pair_hybrid>`,
:doc:`fix lambda/apip <fix_lambda_apip>`,
:doc:`fix lambda_thermostat/apip <fix_lambda_thermostat_apip>`,
:doc:`pair_style lambda/zone/apip <pair_lambda_zone_apip>`,
:doc:`pair_style lambda/input/apip <pair_lambda_input_apip>`,
:doc:`pair_style pace/apip <pair_pace_apip>`,
:doc:`fix atom_weight/apip <fix_atom_weight_apip>`
Default
"""""""
none
----------
.. _Immel2025_5:
**(Immel)** Immel, Drautz and Sutmann, J Chem Phys, 162, 114119 (2025)
.. _Daw2:
**(Daw)** Daw, Baskes, Phys Rev Lett, 50, 1285 (1983).
Daw, Baskes, Phys Rev B, 29, 6443 (1984).

151
doc/src/pair_lambda_input_apip.rst Normal file
View File

@ -0,0 +1,151 @@
.. index:: pair_style lambda/input/apip
.. index:: pair_style lambda/input/csp/apip
pair_style lambda/input/apip command
====================================
Syntax
""""""
.. code-block:: LAMMPS
pair_style lambda/input/apip cutoff
* lambda/input/apip = style name of this pair style
* cutoff = global cutoff (distance units)
pair_style lambda/input/csp/apip command
========================================
Syntax
""""""
.. code-block:: LAMMPS
pair_style lambda/input/csp/apip lattice keyword args
* lambda/input/csp/apip = style name of this pair style
* lattice = *fcc* or *bcc* or integer
.. parsed-literal::
*fcc* = use 12 nearest neighbors to calculate the CSP like in a perfect fcc lattice
*bcc* = use 8 nearest neighbors to calculate the CSP like in a perfect bcc lattice
integer = use N nearest neighbors to calculate the CSP
* zero or more keyword/args pairs may be appended
* keyword = *cutoff* or *N_buffer*
.. parsed-literal::
*cutoff* args = cutoff
cutoff = distance in which neighboring atoms are considered (> 0)
*N_buffer* args = N_buffer
N_buffer = number of additional neighbors, which are included in the j-j+N/2 calculation
Examples
""""""""
.. code-block:: LAMMPS
pair_style lambda/input/csp/apip fcc
pair_style lambda/input/csp/apip fcc cutoff 5.0
pair_style lambda/input/csp/apip bcc cutoff 5.0 N_buffer 2
pair_style lambda/input/csp/apip 14
Description
"""""""""""
This pair_styles calculates :math:`\lambda_i^\text{input}(t)`, which
is required for :doc:`fix lambda/apip <fix_lambda_apip>`.
The pair_style lambda_input sets :math:`\lambda_i^\text{input}(t) = 0`.
The pair_style lambda_input/csp calculates
:math:`\lambda_i^\text{input}(t) = \text{CSP}_i(t)`.
The centro-symmetry parameter (CSP) :ref:`(Kelchner) <Kelchner_2>` is described
in :doc:`compute centro/atom <compute_centro_atom>`.
The lattice argument is described in
:doc:`compute centro/atom <compute_centro_atom>` and determines
the number of neighboring atoms that are used to compute the CSP.
The *N_buffer* argument allows to include more neighboring atoms in
the calculation of the contributions from the pair j,j+N/2 to the CSP as
discussed in :ref:`(Immel) <Immel2025_6>`.
The computation of :math:`\lambda_i^\text{input}(t)` is done by this
pair_style instead of by :doc:`fix lambda/apip <fix_lambda_apip>`, as this computation
takes time and this pair_style can be included in the load-balancing via
:doc:`fix atom_weight/apip <fix_atom_weight_apip>`.
A code example for the calculation of the switching parameter for an adaptive-
precision potential is given in the following:
The adaptive-precision potential is created
by combining :doc:`pair_style eam/fs/apip <pair_eam_apip>`
and :doc:`pair_style pace/precise/apip <pair_pace_apip>`.
The input, from which the switching parameter is calculated, is provided
by this pair_style.
The switching parameter is calculated by :doc:`fix lambda/apip <fix_lambda_apip>`,
whereas the spatial
transition zone of the switching parameter is calculated by
:doc:`pair_style lambda/zone/apip <pair_lambda_zone_apip>`.
.. code-block:: LAMMPS
pair_style hybrid/overlay eam/fs/apip pace/precise/apip lambda/input/csp/apip fcc cutoff 5.0 lambda/zone/apip 12.0
pair_coeff * * eam/fs/apip Cu.eam.fs Cu
pair_coeff * * pace/precise/apip Cu_precise.yace Cu
pair_coeff * * lambda/input/csp/apip
pair_coeff * * lambda/zone/apip
fix 2 all lambda/apip 3.0 3.5 time_averaged_zone 4.0 12.0 110 110 min_delta_lambda 0.01
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
The cutoff distance for this pair style can be mixed. The default mix
value is *geometric*\ . See the "pair_modify" command for details.
This pair style does not support the :doc:`pair_modify <pair_modify>`
shift, table, and tail options.
This pair style writes no information to :doc:`binary restart files <restart>`, so pair_style and pair_coeff commands need
to be specified in an input script that reads a restart file.
This pair style does not support the use of the *inner*, *middle*,
and *outer* keywords of the :doc:`run_style respa <run_style>` command.
----------
Restrictions
""""""""""""
This fix is part of the APIP package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`compute centro/atom <compute_centro_atom>`,
:doc:`fix lambda/apip <fix_lambda_apip>`,
:doc:`fix lambda_thermostat/apip <fix_lambda_thermostat_apip>`,
:doc:`pair_style lambda/zone/apip <pair_lambda_zone_apip>`,
:doc:`pair_style eam/apip <pair_eam_apip>`,
:doc:`pair_style pace/apip <pair_pace_apip>`,
:doc:`fix atom_weight/apip <fix_atom_weight_apip>`
Default
"""""""
N_buffer=0, cutoff=5.0
----------
.. _Kelchner_2:
**(Kelchner)** Kelchner, Plimpton, Hamilton, Phys Rev B, 58, 11085 (1998).
.. _Immel2025_6:
**(Immel)** Immel, Drautz and Sutmann, J Chem Phys, 162, 114119 (2025)

106
doc/src/pair_lambda_zone_apip.rst Normal file
View File

@ -0,0 +1,106 @@
.. index:: pair_style lambda/zone/apip
pair_style lambda/zone/apip command
===================================
Syntax
""""""
.. code-block:: LAMMPS
pair_style lambda/zone/apip cutoff
* lambda/zone/apip = style name of this pair style
* cutoff = global cutoff (distance units)
Examples
""""""""
.. code-block:: LAMMPS
pair_style lambda/zone/apip 12.0
Description
"""""""""""
This pair_style calculates :math:`\lambda_{\text{min},i}`, which
is required for :doc:`fix lambda/apip <fix_lambda_apip>`.
The meaning of :math:`\lambda_{\text{min},i}` is documented in
:doc:`fix lambda/apip <fix_lambda_apip>`, as this pair_style is for use with
:doc:`fix lambda/apip <fix_lambda_apip>` only.
This pair_style requires only the global cutoff as argument.
The remaining quantities, that are required to calculate
:math:`\lambda_{\text{min},i}` are extracted from
:doc:`fix lambda/apip <fix_lambda_apip>` and, thus,
do not need to be passed to this pair_style as arguments.
.. warning::
The cutoff given as argument to this pair style is only relevant for the
neighbor list creation. The radii, which define :math:`r_{\lambda,\text{hi}}` and :math:`r_{\lambda,\text{lo}}` are defined by :doc:`fix lambda/apip <fix_lambda_apip>`.
The computation of :math:`\lambda_{\text{min},i}` is done by this
pair_style instead of by :doc:`fix lambda/apip <fix_lambda_apip>`, as this computation
takes time and this pair_style can be included in the load-balancing via
:doc:`fix atom_weight/apip <fix_atom_weight_apip>`.
A code example for the calculation of the switching parameter for an
adaptive-precision interatomic potential (APIP) is given in the following:
The adaptive-precision potential is created
by combining :doc:`pair_style eam/fs/apip <pair_eam_apip>`
and :doc:`pair_style pace/precise/apip <pair_pace_apip>`.
The input, from which the switching parameter is calculated, is provided
by :doc:`pair lambda/input/csp/apip <pair_lambda_input_apip>`.
The switching parameter is calculated by :doc:`fix lambda/apip <fix_lambda_apip>`,
whereas the spatial transition zone of the switching parameter is calculated
by this pair style.
.. code-block:: LAMMPS
pair_style hybrid/overlay eam/fs/apip pace/precise/apip lambda/input/csp/apip fcc cutoff 5.0 lambda/zone/apip 12.0
pair_coeff * * eam/fs/apip Cu.eam.fs Cu
pair_coeff * * pace/precise/apip Cu_precise.yace Cu
pair_coeff * * lambda/input/csp/apip
pair_coeff * * lambda/zone/apip
fix 2 all lambda/apip 3.0 3.5 time_averaged_zone 4.0 12.0 110 110 min_delta_lambda 0.01
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
The cutoff distance for this pair style can be mixed. The default mix
value is *geometric*\ . See the "pair_modify" command for details.
This pair style does not support the :doc:`pair_modify <pair_modify>`
shift, table, and tail options.
This pair style writes no information to :doc:`binary restart files <restart>`, so pair_style and pair_coeff commands need
to be specified in an input script that reads a restart file.
This pair style does not support the use of the *inner*, *middle*,
and *outer* keywords of the :doc:`run_style respa <run_style>` command.
----------
Restrictions
""""""""""""
This fix is part of the APIP package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`fix lambda/apip <fix_lambda_apip>`,
:doc:`fix atom_weight/apip <fix_atom_weight_apip>`
:doc:`pair_style lambda/input/apip <pair_lambda_input_apip>`,
:doc:`pair_style eam/apip <pair_eam_apip>`,
:doc:`pair_style pace/apip <pair_pace_apip>`,
:doc:`fix lambda_thermostat/apip <fix_lambda_thermostat_apip>`,
Default
"""""""
none

147
doc/src/pair_pace_apip.rst Normal file
View File

@ -0,0 +1,147 @@
.. index:: pair_style pace/apip
.. index:: pair_style pace/fast/apip
.. index:: pair_style pace/precise/apip
pair_style pace/apip command
============================
pair_style pace/fast/apip command
=================================
pair_style pace/precise/apip command
====================================
Constant precision variant: *pace*
Syntax
""""""
.. code-block:: LAMMPS
pair_style pace/apip ... keyword values ...
pair_style pace/fast/apip ... keyword values ...
pair_style pace/precise/apip ... keyword values ...
* one or more keyword/value pairs may be appended
.. parsed-literal::
keyword = keywords of :doc:`pair pace <pair_pace>`
Examples
""""""""
.. code-block:: LAMMPS
pair_style hybrid/overlay pace/fast/apip pace/precise/apip lambda/input/csp/apip fcc cutoff 5.0 lambda/zone/apip 12.0
pair_coeff * * pace/fast/apip Cu_fast.yace Cu
pair_coeff * * pace/precise/apip Cu_precise.yace Cu
pair_coeff * * lambda/input/csp/apip
pair_coeff * * lambda/zone/apip
pair_style hybrid/overlay eam/fs/apip pace/precise/apip lambda/input/csp/apip fcc cutoff 5.0 lambda/zone/apip 12.0
pair_coeff * * eam/fs/apip Cu.eam.fs Cu
pair_coeff * * pace/precise/apip Cu_precise.yace Cu
pair_coeff * * lambda/input/csp/apip
pair_coeff * * lambda/zone/apip
Description
"""""""""""
Pair style :doc:`pace <pair_pace>` computes interactions using the Atomic
Cluster Expansion (ACE), which is a general expansion of the atomic energy in
multi-body basis functions :ref:`(Drautz19) <Drautz2019_2>`. The *pace*
pair style provides an efficient implementation that is described in
this paper :ref:`(Lysogorskiy21) <Lysogorskiy20211_2>`.
The potential energy :math:`E_i` of an atom :math:`i` of an adaptive-precision
interatomic potential (APIP) according to
:ref:`(Immel25) <Immel2025_7>` is given by
.. math::
E_i^\text{APIP} = \lambda_i E_i^\text{(fast)} + (1-\lambda_i) E_i^\text{(precise)}\,,
whereas the switching parameter :math:`\lambda_i` is computed
dynamically during a simulation by :doc:`fix lambda/apip <fix_lambda_apip>`
or set prior to a simulation via :doc:`set <set>`.
The pair style *pace/precise/apip* computes the potential energy
:math:`(1-\lambda_i) E_i^\text{(pace)}` and the
corresponding force and should be combined
with a fast potential that computes the potential energy
:math:`\lambda_i E_i^\text{(fast)}` and the corresponding force
via :doc:`pair_style hybrid/overlay <pair_hybrid>`.
The pair style *pace/fast/apip* computes the potential energy
:math:`\lambda_i E_i^\text{(pace)}` and the
corresponding force and should be combined
with a precise potential that computes the potential energy
:math:`(1-\lambda_i) E_i^\text{(precise)}` and the corresponding force
via :doc:`pair_style hybrid/overlay <pair_hybrid>`.
The pair_styles *pace/fast/apip* and *pace/precise/apip*
commands may be followed by the optional keywords of
:doc:`pair_style pace <pair_pace>`, which are described
:doc:`here <pair_pace>`.
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
For atom type pairs I,J and I != J, where types I and J correspond to
two different element types, mixing is performed by LAMMPS with
user-specifiable parameters as described above. You never need to
specify a pair_coeff command with I != J arguments for this style.
This pair styles does not support the :doc:`pair_modify <pair_modify>`
shift, table, and tail options.
This pair styles does not write its information to :doc:`binary restart
files <restart>`, since it is stored in potential files. Thus, you need
to re-specify the pair_style and pair_coeff commands in an input script
that reads a restart file.
This pair styles can only be used via the *pair* keyword of the
:doc:`run_style respa <run_style>` command. It does not support the
*inner*, *middle*, *outer* keywords.
----------
Restrictions
""""""""""""
This pair styles are part of the APIP package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`pair_style pace <pair_pace>`,
:doc:`pair_style hybrid/overlay <pair_hybrid>`,
:doc:`fix lambda/apip <fix_lambda_apip>`,
:doc:`fix lambda_thermostat/apip <fix_lambda_thermostat_apip>`,
:doc:`pair_style lambda/zone/apip <pair_lambda_zone_apip>`,
:doc:`pair_style lambda/input/apip <pair_lambda_input_apip>`,
:doc:`pair_style eam/apip <pair_eam_apip>`,
:doc:`fix atom_weight/apip <fix_atom_weight_apip>`
Default
"""""""
See :doc:`pair_style pace <pair_pace>`.
----------
.. _Drautz2019_2:
**(Drautz19)** Drautz, Phys Rev B, 99, 014104 (2019).
.. _Lysogorskiy20211_2:
**(Lysogorskiy21)** Lysogorskiy, van der Oord, Bochkarev, Menon, Rinaldi, Hammerschmidt, Mrovec, Thompson, Csanyi, Ortner, Drautz, npj Comp Mat, 7, 97 (2021).
.. _Immel2025_7:
**(Immel25)** Immel, Drautz and Sutmann, J Chem Phys, 162, 114119 (2025)

8
doc/src/pair_style.rst
View File

@ -188,7 +188,9 @@ accelerated styles exist.
* :doc:`eam/cd <pair_eam>` - concentration-dependent EAM
* :doc:`eam/cd/old <pair_eam>` - older two-site model for concentration-dependent EAM
* :doc:`eam/fs <pair_eam>` - Finnis-Sinclair EAM
* :doc:`eam/fs/apip <pair_eam_apip>` - :doc:`adaptive precision <Howto_apip>` version of FS EAM, used as fast potential
* :doc:`eam/he <pair_eam>` - Finnis-Sinclair EAM modified for Helium in metals
* :doc:`eam/apip <pair_eam_apip>` - :doc:`adaptive-precision <Howto_apip>` version of EAM, used as fast potential
* :doc:`edip <pair_edip>` - three-body EDIP potential
* :doc:`edip/multi <pair_edip>` - multi-element EDIP potential
* :doc:`edpd <pair_mesodpd>` - eDPD particle interactions
@ -217,6 +219,9 @@ accelerated styles exist.
* :doc:`kim <pair_kim>` - interface to potentials provided by KIM project
* :doc:`kolmogorov/crespi/full <pair_kolmogorov_crespi_full>` - Kolmogorov-Crespi (KC) potential with no simplifications
* :doc:`kolmogorov/crespi/z <pair_kolmogorov_crespi_z>` - Kolmogorov-Crespi (KC) potential with normals along z-axis
* :doc:`lambda/input/apip <pair_lambda_input_apip>` - constant as input for the precision calculation of an :doc:`adaptive-precision interatomic potential (APIP) <Howto_apip>`
* :doc:`lambda/input/csp/apip <pair_lambda_input_apip>` - CSP as input for the precision calculation of an :doc:`adaptive-precision interatomic potential (APIP) <Howto_apip>`
* :doc:`lambda/zone/apip <pair_lambda_zone_apip>` - transition zone of an :doc:`adaptive-precision interatomic potential <Howto_apip>`
* :doc:`lcbop <pair_lcbop>` - long-range bond-order potential (LCBOP)
* :doc:`lebedeva/z <pair_lebedeva_z>` - Lebedeva interlayer potential for graphene with normals along z-axis
* :doc:`lennard/mdf <pair_mdf>` - LJ potential in A/B form with a taper function
@ -330,6 +335,9 @@ accelerated styles exist.
* :doc:`oxrna2/xstk <pair_oxrna2>` -
* :doc:`pace <pair_pace>` - Atomic Cluster Expansion (ACE) machine-learning potential
* :doc:`pace/extrapolation <pair_pace>` - Atomic Cluster Expansion (ACE) machine-learning potential with extrapolation grades
* :doc:`pace/apip <pair_pace_apip>` - :doc:`adaptive-precision <Howto_apip>` version of ACE, used as precise potential
* :doc:`pace/fast/apip <pair_pace_apip>` - :doc:`adaptive-precision <Howto_apip>` version of ACE, used as fast potential
* :doc:`pace/precise/apip <pair_pace_apip>` - :doc:`adaptive-precision <Howto_apip>` version of ACE, used as precise potential
* :doc:`pedone <pair_pedone>` - Pedone (PMMCS) potential (non-Coulomb part)
* :doc:`pod <pair_pod>` - Proper orthogonal decomposition (POD) machine-learning potential
* :doc:`peri/eps <pair_peri>` - Peridynamic EPS potential

3
doc/src/read_dump.rst
View File

@ -16,12 +16,13 @@ Syntax
.. parsed-literal::
field = *x* or *y* or *z* or *vx* or *vy* or *vz* or *q* or *ix* or *iy* or *iz* or *fx* or *fy* or *fz*
field = *x* or *y* or *z* or *vx* or *vy* or *vz* or *q* or *ix* or *iy* or *iz* or *fx* or *fy* or *fz* or *apip_lambda*
*x*,\ *y*,\ *z* = atom coordinates
*vx*,\ *vy*,\ *vz* = velocity components
*q* = charge
*ix*,\ *iy*,\ *iz* = image flags in each dimension
*fx*,\ *fy*,\ *fz* = force components
*apip_lambda* = switching parameter of an :doc:`adaptive-precision interatomic potential <Howto_apip>`
* zero or more keyword/value pairs may be appended
* keyword = *nfile* or *box* or *timestep* or *replace* or *purge* or *trim* or *add* or *label* or *scaled* or *wrapped* or *format*

15
doc/src/set.rst
View File

@ -23,8 +23,8 @@ Syntax
* one or more keyword/value pairs may be appended
* keyword = *angle* or *angmom* or *bond* or *cc* or *charge* or
*density* or *density/disc* or *diameter* or *dihedral* or *dipole*
* keyword = *angle* or *angmom* or *apip/lambda* or *bond* or *cc* or *charge*
or *density* or *density/disc* or *diameter* or *dihedral* or *dipole*
or *dipole/random* or *dpd/theta* or *edpd/cv* or *edpd/temp* or
*epsilon* or *image* or *improper* or *length* or *mass* or *mol* or
*omega* or *quat* or *quat/random* or *radius/electron* or *shape* or
@ -41,6 +41,10 @@ Syntax
*angmom* values = Lx Ly Lz
Lx,Ly,Lz = components of angular momentum vector (distance-mass-velocity units)
any of Lx,Ly,Lz can be an atom-style variable (see below)
*apip/lambda* value = fast or precise or float
fast = switching parameter of fast potential (1)
precise = switching parameter of fast potential (0)
float = constant float or atom-style variable (between 0 and 1)
*bond* value = numeric bond type or bond type label, for all bonds between selected atoms
*cc* values = index cc
index = index of a chemical species (1 to Nspecies)
@ -632,6 +636,13 @@ atoms.
Keywords *x*, *y*, *z* set the coordinates of all selected atoms.
Keyword *apip/lambda* sets the switching parameter of an
adaptive-precision interatomic potential (:doc:`APIP <Howto_apip>`).
The precise potential is used for an atom when its switching parameter
:math:`\lambda` is 0. The fast potential is used for an atom when its
switching parameter :math:`\lambda` is 1. Both potentials are partially
used for :math:`\lambda\in(0,1)`.
Keywords *i_name*, *d_name*, *i2_name*, *d2_name* refer to custom
per-atom integer and floating-point vectors or arrays that have been
added via the :doc:`fix property/atom <fix_property_atom>` command.

6
doc/utils/sphinx-config/false_positives.txt
View File

@ -135,6 +135,8 @@ anton
Antonelli
anysize
api
apip
APIP
apolar
Apoorva
Appl
@ -654,6 +656,7 @@ CSiC
csld
cslib
CSlib
csp
cstdio
cstdlib
cstring
@ -1384,6 +1387,7 @@ gmres
gname
gneb
GNEB
Godehard
Goerigk
Goga
Goldfarb
@ -1619,6 +1623,7 @@ Imageint
Imagemagick
imagename
imd
Immel
Impey
impl
improperlist
@ -3847,6 +3852,7 @@ Thiaville
Thibaudeau
Thijsse
Thirumalai
thr
Threadripper
threebody
thrid