From b4b5edf3731650dd4f368f7a7ff482abea0ccaa7 Mon Sep 17 00:00:00 2001 From: HE Zilong <159878975+he-zilong@users.noreply.github.com> Date: Sun, 7 Jun 2026 19:35:41 +0800 Subject: [PATCH] Expand documentation on MD and opt; add "Foreword and FAQ" (#5337) --- docs/getting-started/first-calculation.md | 10 +- docs/getting-started/foreword-and-faq.md | 252 ++++++++++++++++++ docs/index.md | 1 + .../optimization/geometry_and_cell_opt.md | 43 +-- docs/methods/sampling/molecular_dynamics.md | 110 +++++++- 5 files changed, 368 insertions(+), 48 deletions(-) create mode 100644 docs/getting-started/foreword-and-faq.md diff --git a/docs/getting-started/first-calculation.md b/docs/getting-started/first-calculation.md index 333b06d532..b3959490b7 100644 --- a/docs/getting-started/first-calculation.md +++ b/docs/getting-started/first-calculation.md @@ -126,14 +126,16 @@ is spent in grid operations, sparse matrix operations, diagonalization, or commu ## Next Steps -- Converge [CUTOFF](#CP2K_INPUT.FORCE_EVAL.DFT.MGRID.CUTOFF) and - [REL_CUTOFF](#CP2K_INPUT.FORCE_EVAL.DFT.MGRID.REL_CUTOFF): [](../methods/dft/cutoff) +- If this example calculation has been executed on the cloud, consider building or installing CP2K + on your server: [](build-from-source), [](build-with-spack), [](distributions) - Learn the idea behind GPW: [](../methods/dft/gpw) - Learn about basis sets and pseudopotentials: [](../methods/dft/basis_sets), [](../methods/dft/pseudopotentials) -- Build or install CP2K: [](build-from-source), [](build-with-spack), [](distributions) +- Converge [CUTOFF](#CP2K_INPUT.FORCE_EVAL.DFT.MGRID.CUTOFF) and + [REL_CUTOFF](#CP2K_INPUT.FORCE_EVAL.DFT.MGRID.REL_CUTOFF): [](../methods/dft/cutoff) +- Proceed to geometry optimization: [](../methods/optimization/geometry_and_cell_opt) +- Proceed to molecular dynamics simulation: [](../methods/sampling/molecular_dynamics) - Explore more complete examples: -- Read the practical CP2K overview paper: [](#Iannuzzi2026) ```{youtube} qMR-NAaUheg --- diff --git a/docs/getting-started/foreword-and-faq.md b/docs/getting-started/foreword-and-faq.md new file mode 100644 index 0000000000..e35d022208 --- /dev/null +++ b/docs/getting-started/foreword-and-faq.md @@ -0,0 +1,252 @@ +# Foreword and FAQ + +It is our great pleasure to present CP2K, an open-source software package for _ab initio_ electronic +structure calculations in atomistic simulations. The code is written in Fortran 2008 and has been +geared towards large-scale, high-performance CPU and GPU computation with multi-threading, MPI, CUDA +and HIP parallelization. For an overview of the capabilities, see +[Features](https://www.cp2k.org/features). + +While CP2K started as an implementation of quantum chemical methods (more specifically, the +`QUICKSTEP` module, as presented at [](#VandeVondele2005)) for molecular dynamics simulation, +decades of ensuing development has witnessed a vast team of collaborators with their innumerable +contributions and the ever-growing user base with their valuable feedbacks, to whom we wish to +express sincere gratitude. As CP2K is freely available in various ways and does not requite +registration to use, it is difficult to gather accurate usage stats; but the +[list of publications using CP2K](https://www.cp2k.org/science) speaks for itself. + +We would like to ask you, users of CP2K, to acknowledge our work by citing the publications as +listed on the [Bibliography](../bibliography) page and printed as REFERENCES at the end of output +log of the program, in particular the review articles: + +- [](#K%C3%BChne2020), on the theoretical background and algorithms; +- [](#Iannuzzi2026), on the practical usage and applications. + +We have prepared a list of Q&A for frequently asked things below, which we hope can be helpful for +the experience with the CP2K package and the art of computational chemistry in general. + +This program is provided "as-is" without any expressed or implied warranty. + +## Firstly, what does the name CP2K stand for? + +Simply put, "CP" means Car-Parrinello, the initials of two scientists, and "2K" means year 2000. + +Historically there were two formulations developed for _ab initio_ molecular dynamics ({term}`MD`): +the Car-Parrinello Molecular Dynamics ({term}`CPMD`), and the Born-Oppenheimer Molecular Dynamics +({term}`BOMD`). A program named simply also as `CPMD` began its development back in the 1990s +featuring the Car-Parrinello Molecular Dynamics; the sister project, named as CP2K, would become its +spiritual successor in the wake of the New Millenium. + +Due to the fact that the original CPMD formulation has not actually been implemented yet, the name +CP2K may sound slightly non-indicative. The BOMD formulation is the major one employed by CP2K and +has seen mainstream applications in a variety of fields in the 21st century. + +## Can I try CP2K out somewhere before installation? + +Yes. The [CP2K Lab](https://lab.cp2k.com/) is a spin-off commercial platform set up by developers +for building structures, writing input files, executing jobs on the cloud and analyzing the outputs. +Once signed up for free, the free-tier features already allow for experiments with lightweight +computation like the one in [](./first-calculation). For those in need of more resources and +functionalities, the platform offers paid tier, site license and on-premise enterprise support. + +## What preliminary knowledge does using CP2K need? + +Practically CP2K is built and executed in some Linux-based operating systems, ranging from on +physical high-performance computers for production to in virtual machines for quick small tests. +This implies the need of Linux knowledge including its file system, paths, user privileges and +permissions, environment variables, shells (most commonly Bash and POSIX), utility commands, +stdin/stdout/stderr, piping and redirects, shell scripts, and modules and library files. In +addition, having some experience with Fortran, C, and C++ compilers as well as CMake will be helpful +for configuration and installation. Optionally, learn about upper-level management via job +schedulers and queue systems. + +On the science side, introductory courses on chemistry, solid-state physics, and statistical +mechanics are vital prerequisites before carrying out computer simulations just as before performing +experiments in real life. Moreover, it is mandatory to have a clear understanding about the +theoretical methods in simulation; their characteristics and performance, strengths and limitations +should be described in the publications in the original conception and follow-up benchmarks. There +are two polar opposite pitfalls to be avoided: it is easy to overlook the subtleties and adjust +input settings mindlessly hoping that the black box somehow works, but it is also easy to become +absorbed in the maths and spend a lot of time trying to work out the equations that is not the focus +of the actual research project. + +```{note} +Worth stressing are two overarching aspects of computer simulation: + +- In spite of ever-growing scientific computing power, most of the time it is not affordable to have + an exact 1:1 computational model of the real-life phenomena of interest. The usual practice is to + use a much scaled-down model with limited number of atoms and finite length of trajectory for the + simulation, which should achieve the delicate balance between representativeness and feasibility. + The discrepancy of space and time scales between simulation and reality can be easily neglected due + to a lack of awareness of the kinetics, especially for slow, rare events with high energy barrier + that can only be observed in an extended period of time in real life. +- There is no need to worry if a theoretical method is strictly *ab initio* or not; both styles of + deriving methods, "starting from physically rigorous and universal first principles" and "taking + empirical results into account by fitting parameters with extra data", are capable of producing + useful algorithms and accurate results depending on the case. The real concern is better put on + the performance of methods on the target system of interest, which should have been benchmarked + in existing works of the particular subdivision of science; also, the similarity between primitive + datasets on which empirical parameters of the method (if any) are fitted and the target system + of interest can be telling. +``` + +## How do I create the atomistic model for CP2K input? + +This is done with external visualization and construction programs. Considering that a task of +geometry and/or cell optimization is usually the very first CP2K job, some general rules are +discussed on the +[relevant documentation page](../methods/optimization/geometry_and_cell_opt.md#starting-structure-and-cell). + +If available, *computational* databases and benchmark sets are the most recommended avenue to obtain +structures due to having already been subject to some electronic-structure calculation. Even the +cheap methods and loose thresholds in a high-throughput screening and optimization can make the +structure qualitatively reasonable by chemical and physical intuitions, although further +optimization is still needed. + +On the other hand, structures that are from *experimental* characterization are frequently not +"computation-ready", and thus should not be subject to computation without careful validation in +pre-processing. This can be prominent for `cif` and `pdb` structures determined by powder or single- +crystal XRD which can be affected by sample quality and thermal motion. + +- Watch out for crystallographic disorder and atoms with low resolution or fractional occupation: + using the superposition of all atoms as if every occupancy is 1.00 is highly likely to introduce + contacting or even overlapping atoms. +- Beware of composition: the atomic structure may not match the intended macroscopic, charge-neutral + chemical formula, owing to missing or duplicated hydrogen atoms, small counter ions, solvent or + ligand molecules. + +Possible resolutions vary from simple manual editing in the modelling stage, to utilization of +supercells and enumeration of special quasirandom structures (common for materials with dopants), +and to more rigorous XRD refinement and application of quantum crystallography methods. It is +believed that further advancements in instrumental analysis and structure resolution techniques +would eventually benefit computational chemistry greatly. + +## Do I need PBC for my model? + +**Periodic boundary condition** ({term}`PBC`) is a fundamental feature of CP2K, covering the full +range of dimensionalities of translational symmetry from 3D, 2D, 1D to 0D. The key distinction is +how connectivity, neighbor lists and integration grids are generated, how the Poisson solver handles +the electrostatic interaction, and how translational and rotational degrees of freedom of the center +of mass (i.e. collective motion as a whole) are treated. + +If the structure involves condensed-phase matter, such as liquid solution, solid crystal, surface +slab and other one- and two-dimensional nano-materials, then generally PBC is used. This is also +applicable to systems with no actual well-defined repeating units like the bulk solutions. A huge +liquid droplet in the gaseous phase, where the diameter is so large that the gas-liquid interface is +almost flat and surface tension is negligible, may just as well be modelled as a combination of a +bulk solution system and an interface between a gaseous/vacuum region and a thin layer of solution, +both of which make use of PBC even though the liquid droplet itself is not periodic. However, it may +be necessary to validate the size of PBC against target properties to confirm that it is +sufficiently large for sampling, sometimes with the minimum image convention in mind. + +Isolated molecular clusters in the gaseous phase or vacuum, where external pressure is irrelevant, +can be simulated without PBC. A frequent question is why a molecule optimized in vacuum does not +match its crystal structure; this is because the ordered packing pattern in the crystalline form +creates an environment capable of driving conformational changes. Oftentimes literatures convert a +periodic structure to an isolated model of finite size and apply modifications on the edge in the +form of terminal capping atoms/groups or point charges; these treatments are usually intended to +adapt the structure to quantum chemical softwares with no PBC support, but in CP2K they may not +offer extra advantages over an appropriate PBC for translational symmetry. + +In certain cases, the same process can be simulated both with and without PBC. For example, the +reaction between hydroxyl and hydrogen may be modelled as a single $\mathrm{H_2}$ molecule colliding +with a single $\mathrm{OH}$ molecule with different relative orientations, distances and velocities, +which does not need PBC, or modelled as a mixture of numerous $\mathrm{H_2}$ and $\mathrm{OH}$ +molecules, which needs PBC. Their behavior regarding responses to external conditions including +temperature, pressure, and any form of energy input may be different, but they provide insights from +distinct perspectives. + +## Does CP2K support k-points? + +As an essential element for solid-state electronic structure, there is of course support for +k-points in a broad sense in the `QUICKSTEP` module of CP2K. A few specialized features may not have +complete, verified program implementations for k-point support, or are based on theories and +algorithms that do not have an updated k-point version (compared with an isolated, non-periodic +formalism) to begin with. After all, it is not a far stretch to think that a novel k-point +generalization to existing methods is worthy of one or more academic publications and takes serious +collaboration and devoted efforts to investigate. + +The development status and user opinions about k-point supports can be found at the dedicated +[github issue](https://github.com/cp2k/cp2k/issues/4854); any request for new features of this kind +requires providing a reference implementation of k-point formalism in other softwares. + +## Where can I meet the CP2K community? + +Several discussion venues are available: + +- The [User Forum](https://groups.google.com/group/cp2k) hosted on Google Groups, with a read-only + [mirror](https://lists.cp2k.org/listinfo/cp2k-user) and a downloadable + [archives](https://lists.cp2k.org/archives/cp2k-user/). To use the forum, sign in with a Google + account, apply to join and then wait for approval. +- The [issues](https://github.com/cp2k/cp2k/issues/) and + [discussions](https://github.com/cp2k/cp2k/discussions) of the official github repository. +- The + [Matter Modeling Stack Exchange](https://mattermodeling.stackexchange.com/questions/tagged/cp2k) + has, among other topics, a tag for CP2K. +- For Chinese users, there is also a CP2K category in the First-principles subforum of the + [Computational Chemistry Commune](http://bbs.keinsci.com/forum-105-1.html?typeid=42). + +Please note that the github issues and discussions are only intended for topics relevant to the +program development and code implementation, such as reproducible bug reports, well-defined feature +requests and revisions to the documentation or manual. For more general help on the usage, as well +as unexpected behaviors that may or may not be bugs, check the other venues first; experts can +handle the questions and determine if they are eligible to be brought to github issues. + +## What is the best practice to ask questions? + +The general etiquette for requesting tech support online has been summarized nicely by Eric S. +Raymond's [How To Ask Questions The Smart Way](http://www.catb.org/~esr/faqs/smart-questions.html). +(**Disclaimer**: this link does not imply any connection between the original author and the CP2K +developers, nor does it suggest that the original author may be contacted for assistance.) + +Before submitting a question, please compose it with sufficient details, accuracy, and clarity. +Approach the process in the same way as making a presentation to general audience, or even writing +the "Methods" section in a formal academic publication; this includes giving explanations to +uncommon acronyms (say, the abbreviated name of a specific class of materials, or anything that is +not on the [Acronyms](../acronyms) page) and traceable citations (with publication title, date, and +DOI, instead of merely showing a screenshot or a paragraph of copy-pasted text). The release date or +git version of CP2K, and custom revisions if any, has to be mentioned in the first place. + +For problems related to installation and/or performance, the hardware specification and the +configuration for linked libraries should be explained. The distribution source and means of +preparation of dependencies, like with package managers, environment-controlling modules, or just a +build from source, need clarifying. + +For error terminations and wrong results, it is imperative to provide a complete input deck and the +output files. The "input deck" encompasses not only the main input file with keyword settings, but +also all of the external files referenced inside unless they are available under the official `data` +directory, so that the job can be actually run and tested. Instead of the original intended chemical +structure and composition, it is better to use a simplified system that triggers the malfunction +reliably; this prevents confidential research information to be disclosed and reduces the demand on +computational resources to ease the load of computers on the developer side. + +Please refrain from talking about CP2K-specific suggestions from generic large language model (LLM) +or other types of artificial intelligence (AI). Even if the AIs have been trained on a refined and +verified corpus of CP2K-oriented information one day, they can still hallucinate and generate +superficially convincing but scientifically incorrect responses. As with academic publications, the +human author is responsible for the correctness of any content produced by AIs. + +Lastly, please kindly understand that, despite the CP2K developers having knowledge about the +algorithm infrastructures and program implementations, they may not be suitable for answering all of +the questions arising from practice, especially those pertaining to niche research areas where +apprehending the science and acquiring the skills will require much more extensive academic training +than learning to use a program. The best party to consult for guidance of this type would be the +tutor, advisor, experienced colleagues or collaborators in real life, and when attempting to +reproduce reported findings, the original authors. This is not denying any personal potential to +teach oneself at no cost, but rather hinting the necessity of communicating with the right +professional people which does not have substitutes. + +## May I join in development and send patches? + +Certainly! CP2K welcomes all sorts of contributions, from a small typo fix to modular code +refactoring, to interfaces with other packages, to novel implementation of cutting-edge +technology... Sharing kindness is an easy feat, and patches makes it more complete, that is the +essence of open-source programming. + +The CP2K project uses `git` as the version control tool, and the official code repository is on +github as [cp2k](https://github.com/cp2k/cp2k). For detailed instructions see the page +[Starting development](https://www.cp2k.org/dev:starting). + +Another form of contribution is to enrich the [cp2k-examples](https://github.com/cp2k/cp2k-examples) +repository with example inputs and outputs, complete with post-analysis workflow down to straight +publishable results and discussions if possible. This will help other curious users see the full +potential of CP2K in terms of scientific and engineering applications. diff --git a/docs/index.md b/docs/index.md index e31080d387..f00a70b0a0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,6 +16,7 @@ caption: Getting Started titlesonly: maxdepth: 1 --- +getting-started/foreword-and-faq getting-started/build-from-source getting-started/build-with-spack getting-started/distributions diff --git a/docs/methods/optimization/geometry_and_cell_opt.md b/docs/methods/optimization/geometry_and_cell_opt.md index e3c59a52c4..e62aa29fa9 100644 --- a/docs/methods/optimization/geometry_and_cell_opt.md +++ b/docs/methods/optimization/geometry_and_cell_opt.md @@ -37,7 +37,7 @@ relaxed in-plane lattice constants, and structures prepared for fixed-cell molec ```{note} An optimization is not a replacement for finite-temperature pressure sampling; if the desired quantity is a thermal average at finite temperature, use a molecular-dynamics workflow with -appropriate ensemble instead. +appropriate ensemble instead. For more on this topic, see [](../sampling/molecular_dynamics). For the usual electronic-structure methods based on the Born-Oppenheimer approximation (which, by neglecting nuclear motion, provides the concept of "potential-energy surface" @@ -146,7 +146,12 @@ vaporized or molten conditions with lots of broken chemical bonds. For `CELL_OPT`, the initial cell matters as much as the initial coordinates. The starting volume and shape should be close enough to the expected structure and density, such that the pressure and -stress are not dominated by preparation artefacts. +stress are not dominated by preparation artefacts. The directions where the cell is relaxed are +dependent of the external pressure. For surface slabs, two- or one-dimensional materials, or systems +with vacuum, the anisotropic nature means that the vacuum direction is not to be relaxed unless +physically intended; it is better to constrain the appropriate cell components or use a fixed-cell +optimization after choosing the desired cell. A rigorous test for the convergence of target +properties with respect to different size of vacuum may be necessary. A visualization of the structure and cell in modelling programs, with the box and the neighboring periodic images displayed, will be very helpful; neither large vacuous gaps nor crowded cluster of @@ -154,33 +159,11 @@ atoms should occur near the boundary of the box on the directions consistent wit and conversely, sufficient vacuum space on the non-periodic directions is crucial for eliminating unwanted interactions across the boundary. -For surface slabs, two- or one-dimensional materials, or systems with vacuum, do not relax the -vacuum direction unless physically intended; it is better to constrain the appropriate cell -components or use a fixed-cell optimization after choosing the desired cell. - -```{warning} -**Do not use experimental structure blindly.** - -If available, **computational** materials databases are the most recommended avenue -to obtain structures that are "computation-ready", or even better, already optimized -with some electronic-structure methods. On the other hand, structures that are from -**experimental** characterization are frequently not "computation-ready", and thus -should not be subject to optimization without careful validation in pre-processing. -This can be prominent for `cif` and `pdb` structures determined by powder or single- -crystal XRD which can be affected by sample quality and thermal motion. - -- Watch out for crystallographic disorder and atoms with low resolution or fractional - occupation: using the superposition of all atoms as if every occupancy is 1.00 is - highly likely to introduce contacting or even overlapping atoms. -- Beware of composition: the atomic structure may not match the intended macroscopic, - charge-neutral chemical formula, owing to missing or duplicated hydrogen atoms, - small counter ions, solvent or ligand molecules. - -Possible resolutions vary from simple manual editing in the modelling stage, to -utilization of supercells and enumeration of special quasirandom structures (common -for materials with dopants), and to more rigorous XRD refinement and application of -quantum crystallography methods. -``` +As a reserved extreme measure, the [MAX_FORCE](#CP2K_INPUT.FORCE_EVAL.RESCALE_FORCES.MAX_FORCE) +keyword triggers a mechanism where very large forces on atoms are artificially rescaled in +magnitude. This setting is only meant for crude initial structure; once the geometry becomes more +reasonable and the forces are closer to the convergence criteria, it shall not be used in the +production run towards the final result. ```{note} For variable-cell optimizations, the [CELL_OPT](#CP2K_INPUT.MOTION.CELL_OPT) section @@ -407,7 +390,7 @@ and linked to the CP2K build in order to detect and preserve the space group. Us Density functional theory (DFT) is an electronic-structure (wavefunction) method routinely used for optimization. This section elaborate on the relevant aspects, assuming basic knowledge about the -method which can be found at [](../dft/index.md). +method which can be found at [](../dft/index). ### SCF quality diff --git a/docs/methods/sampling/molecular_dynamics.md b/docs/methods/sampling/molecular_dynamics.md index e0f07816c2..291e39fd69 100644 --- a/docs/methods/sampling/molecular_dynamics.md +++ b/docs/methods/sampling/molecular_dynamics.md @@ -46,12 +46,98 @@ A minimal fixed-energy MD block is: The force method is defined independently in [FORCE_EVAL](#CP2K_INPUT.FORCE_EVAL). -## Initial structure and velocities +## Preliminary considerations -Start from a physically reasonable structure with sensible bond lengths, intermolecular distances, -density, and cell parameters. MD is not a reliable way to fix severe close contacts, unrealistic -densities, or badly prepared cells, because such problems can cause unstable forces, SCF failures, -or immediate heating and atom ejection. A geometry optimisation before MD can be helpful. +Universal to every atomistic simulation and every program, a number of crucial points must be +carefully considered before setting up a molecular dynamics task and investing copious amounts of +computational resources. As a starter, this section discusses preliminary factors in the choice of +the spatiotemporal scale of the trajectory, periodic boundary condition. force method, and the +initial structure. + +### Space and time scale + +Even when taking the ergodic hypothesis as granted, statistical analysis on target properties at +thermodynamic equilibrium has to be performed on top of sufficient sampling. The (auto)correlation +length and (auto)correlation time provide estimates for the space and time scale where measurements +of some property retain a memory of past states and are not fully statistically independent. It is +important to learn about their typical values in the same or similar systems, and take adequate +multiples as the size of the system and the length of the trajectory. + +On the other hand, non-equilibrium irreversible processes such as phase transitions and chemical +reactions are also observable at some time and space resolution. Experimentally it is determined by +the sensitivity of instrumental characterization and analysis methods, with certain precise +definitions of the states before and after the process. Unfortunately, many experiments take place +in real life in a macroscopic time interval that exceeds the capability of simulation; for instance, +a chemical reaction taking days, hours, or even just seconds to happen may not be replicatable in +AIMD simulations with trajectory on the picosecond or nanosecond scale starting with only a bunch of +reactants randomly packed together, however thermodynamically favorable it is. Again, it is better +to survey literatures with relevant kinetic data and have a clear understanding of the typical free +energy barriers and reaction rates before proceeding to simulations. Even static thermochemistry +calculations for the profile of energy landscape via optimization of minima and transition states, +vibrational analysis and evaluation of single-point energy would be helpful. To simulate difficult +reactions by molecular dynamics in a short trajectory, advanced _enhanced sampling_ methods such as +[](./metadynamics) may be necessary. + +### Periodic boundary condition + +**Periodic boundary condition** ({term}`PBC`) may or may not be used in the molecular dynamics +simulation, and there are caveats for both ends. + +On one hand, very small periodic cells for production MD should be avoided unless the finite-size +effects are known to be acceptable. Small cells produce artificial correlations through periodic +images, exaggerate statistical temperature and pressure fluctuations, and can make NPT cell dynamics +unstable or unphysical. Sometimes using a supercell of a crystalline structure is preferred if its +primitive cell is too small. + +On the other hand, without PBC in MD, a common risk is that strong repulsion or very weak attraction +causes the system to expand and effectively diminishes desired interactions between molecules. A +possible remedy is to define an external potential or a constraint that act as a soft wall to +reflect or push stray molecules back to the center, but this is artificial and arbitrary. + +### Force method + +To propagate the trajectory in a molecular dynamics simulation, the energy and force is evaluated on +each timestep to provide acceleration via Newton's second law. The choice of the force method +determines the description of chemical bonding and/or weak interactions, the configuration space +that can be sampled, and the eventual computational cost. Careful selection of function forms and +parameters as well as thorough validation against the target property is vital to any application; +in particular, the part of "cross" interactions between two or more components described with more +than one unified force method requires very well-founded justification. + +The strength and limitation of each force method is decided by design and parametrization. For +instance, classical force fields in molecular mechanics usually model chemical bonds by harmonic +potentials on the stretching, bending and rigid dihedral terms (and periodic torsion potentials on +the flexible dihedral terms). The simplicity of function forms allows for speedy evaluation and the +conformational fluctuation or conversion can be captured well, but the bonding pattern is fixed to +near equilibrium and bond breaking and forming in chemical reactions cannot be captured. To describe +the bond rearrangement and the underlying electronic structure, AIMD based on quantum chemical +methods becomes requisite even though it is slower and more costly. The middle grounds have recently +becoming filled with emerging methods like the machine-learning potentials. + +### Initial structure + +Because most of the points apply here as well, please first refer to the documentation about the +[starting structure and cell](../optimization/geometry_and_cell_opt.md#starting-structure-and-cell) +of a geometry optimization. + +In general, start from a physically reasonable structure with sensible bond lengths, intermolecular +distances, density, and cell parameters. A majority of the force methods demonstrate extremely +strong repulsion at very small nuclei distances, and thus molecular dynamics simulation employing +these methods is not a reliable way to fix severe close contacts, unrealistic densities, or badly +prepared cells, because such problems can cause unstable forces, SCF failures, or immediate heating +and atom ejection. + +In fact, when starting from scratch, a geometry optimization preceding molecular dynamics simulation +is highly recommended. During geometry optimization, the structure is relaxed and the maximum force +on atoms is significantly lowered, which puts an upper limit to the initial acceleration in the +subsequent molecular dynamics simulation and prevents rapid atomic motion and extreme temperature +rise. With electronic-structure methods, the geometry optimization also offers a chance to confirm +SCF convergence and estimate the time consumption on each step. The only "downside" is that the +temperature may start from or drop to a relatively low value at early simulation due to the small +forces and slow motion, and may take a little longer to heat up to the desired temperature; see the +section on equilibration below for how to address this. + +## Initial velocities If velocities are not provided by a restart file or an external trajectory, CP2K can initialise atomic velocities from [TEMPERATURE](#CP2K_INPUT.MOTION.MD.TEMPERATURE). The @@ -65,11 +151,6 @@ meaningful, overall angular motion; see [COMVEL_TOL](#CP2K_INPUT.MOTION.MD.COMVE and related keywords. For periodic bulk systems, small total-momentum drift is usually less important. -**Avoid very small periodic cells for production MD unless the finite-size effects are known to be -acceptable.** Small cells produce artificial correlations through periodic images, exaggerate -statistical temperature and pressure fluctuations, and can make NPT cell dynamics unstable or -unphysical. - ## Choosing an ensemble The most common choices are `NVE`, `NVT`, `NPT_I`, `NPT_F`, and `LANGEVIN`. @@ -269,11 +350,12 @@ trajectory can be continued without losing significant sampling time. ## Validation checklist -Before running a long production trajectory, it's suggested to check that: +Before running a long production trajectory, it is suggested to check that: -- The affordable length of trajectory is sufficient for observing phenomena, for instance chemical - reactions need to be kinetically favorable so as to happen on a picosecond timescale that AIMD - usually manages to cover. +- The planned length of trajectory and reserved computational time is long enough to overcome + (auto)correlations and/or observe phenomena; +- The force method and key parameters is validated on the particular system and is suitable for + describing the target property; - The structure is physically reasonable and the shortest interatomic distances are sensible; - The periodic cell is large enough for the target property; - The SCF procedure converges reliably on representative snapshots;