Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
e75d4ca
feat(hessian): add analytic NEP Hessian command
codex Sep 24, 2026
8b7de7f
fix(nep): make small-box neighbor storage dynamic
codex Sep 25, 2026
554c7b7
docs(hessian): add compute_hessian keyword reference
codex Sep 27, 2026
633fe12
feat(hessian): split analytic and finite-difference modes
codex Sep 27, 2026
3d4e194
docs(hessian): describe sparse matrix output
codex Sep 27, 2026
aff5317
feat(hessian): rename sparse output format keyword
codex Sep 27, 2026
0d71b05
Merge branch 'brucefan1983:master' into hessian-only
hsianghualite Sep 27, 2026
a18417c
feat(hessian): compute dftd3/ZBL on top of purely additive branch
codex Oct 21, 2026
616d2d5
refactor(hessian): keep pre-hessian sources unmodified via friend acc…
codex Oct 22, 2026
926c579
refactor(hessian): keep pre-hessian sources unmodified, analytic-only
codex Nov 3, 2026
2c6d79c
fix(hessian): correct temperature and sparse handling
codex Nov 7, 2026
f028f9f
fix(hessian): address review on the original branch baseline
codex Nov 14, 2026
c4068db
Merge upstream/master before adapting analytic Hessian
codex Nov 14, 2026
cb7999b
fix(hessian): use shared model reader and portable path checks
codex Nov 14, 2026
2df9e4a
fix(hessian): refine command validation and diagnostic exports
codex Nov 14, 2026
d20c548
docs(hessian): focus manual on usage and output interpretation
codex Nov 14, 2026
6d7ed9a
Merge upstream/master and resolve Hessian documentation navigation
codex Nov 14, 2026
0fa2861
fix(hessian): keep DFT-D3 rejection inside command module
codex Nov 14, 2026
2f324ba
fix(hessian): reject close neighbors and Windows stream outputs
codex Nov 14, 2026
38a10ff
fix(hessian): initialize large sparse buffers and validate invariants
codex Nov 14, 2026
0cb7a20
refactor(hessian): remove temperature-dependent NEP support
codex Nov 15, 2026
0cdaec9
docs(hessian): simplify output table description
codex Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion doc/gpumd/input_files/run_in.rst
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ For each subsequent run, choose the ensemble and repeat the commands needed for
The atomic positions, velocities, and cell continue from the preceding run; see the :ref:`multiple-run example <multiple_runs>`.
To continue from a saved configuration in a new simulation, see :ref:`restart.xyz <restart_xyz>`.

Static calculations such as :ref:`cohesive-energy curves <kw_compute_cohesive>`, :ref:`elastic constants <kw_compute_elastic>`, and :ref:`phonon dispersions <kw_compute_phonon>` execute when their commands are read, after the potential has been loaded.
Static calculations such as :ref:`cohesive-energy curves <kw_compute_cohesive>`, :ref:`elastic constants <kw_compute_elastic>`, :ref:`phonon dispersions <kw_compute_phonon>`, and :ref:`analytic Cartesian Hessians <kw_compute_hessian>` execute when their commands are read, after the potential has been loaded.
For calculations with several NEP models, see :ref:`dump_observer <kw_dump_observer>`.

Replica dynamics use :ref:`multi_replica <kw_multi_replica>`, a :ref:`restricted command set <replica_input_parameters>`, and a single final ``run`` command.
Expand Down Expand Up @@ -239,6 +239,10 @@ Actions
- Compute Steinhardt bond-orientational order parameters
- No
- No
* - :ref:`compute_hessian <kw_compute_hessian>`
- Compute an analytic Cartesian Hessian
- Yes
- N/A
* - :ref:`compute_phonon <kw_compute_phonon>`
- Compute the phonon dispersion
- Yes
Expand Down
168 changes: 168 additions & 0 deletions doc/gpumd/input_parameters/compute_hessian.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,168 @@
.. _kw_compute_hessian:
.. index::
single: compute_hessian (keyword in run.in)

:attr:`compute_hessian`
=======================

Compute the Cartesian Hessian analytically for the current atomic positions
using a single NEP energy model. The command executes as soon as it is read
and must follow :ref:`potential <kw_potential>`. It does not relax the
structure. For ordinary NEP, no preceding MD run is needed.

Syntax
------

.. code-block:: text

compute_hessian analytic [<option> <value> ...]

Write the entire command on one line in ``run.in``; backslash continuation
is not supported. Options are pairs of names and values as listed below.

Parameters
----------

``analytic``
Required calculation method.

``output <path>``
Matrix output path. Default: ``hessian.out``.

``output_format dense|sparse``
Matrix format. Default: ``dense`` (full text matrix). ``sparse`` writes
Matrix Market coordinate format.

``raw_output <path>``
Optional matrix before symmetrization, in the selected output format.
Default: no raw file.

``metadata <path>``
Optional JSON file containing system information, energy, forces, matrix
diagnostics and storage format.
Default: no metadata file. Available with both matrix formats.

``structure_output <path>``
Optional extended XYZ snapshot containing positions, species, masses,
and forces. Default: no snapshot. Available with both matrix formats.

Each execution overwrites the selected output files. Choose distinct paths
for all outputs; they must also differ from ``model.xyz``, ``run.in``, and
potential files. On Windows, output paths cannot use NTFS data streams
(such as ``hessian.out::$DATA``). A file-write error terminates the calculation.

.. _hessian_out:

Output
------

Matrix definition
^^^^^^^^^^^^^^^^^

For :math:`N` atoms, the Hessian is a :math:`3N\times3N` matrix:

.. math::

H_{i\alpha,j\beta}
= -\frac{\partial F_{i\alpha}}{\partial R_{j\beta}}
= \frac{\partial^2 E}{\partial R_{i\alpha}\partial R_{j\beta}}.

Its units are :math:`\mathrm{eV}/\text{\AA}^2`. Rows and columns use the
coordinate order

.. math::

x_0,\ldots,x_{N-1},y_0,\ldots,y_{N-1},z_0,\ldots,z_{N-1}.

Atom indices follow the input structure order. The main output is
:math:`(H+H^\mathsf{T})/2`; ``raw_output`` contains the matrix before this
symmetrization. Neither output is mass weighted, and no acoustic sum rule
is imposed. For mode analysis, apply mass weighting separately as
:math:`D_{i\alpha,j\beta}=H_{i\alpha,j\beta}/\sqrt{m_i m_j}`.
The command does not calculate phonon frequencies or eigenvectors.

For periodic systems, contributions from different periodic images of the
same atom are already summed. Neither dense nor sparse output retains
lattice-translation labels. A matrix from a small periodic box therefore
cannot be used directly as translation-resolved real-space force constants
for a phonon dispersion at arbitrary wave vectors. For phonon dispersions,
see :ref:`compute_phonon <kw_compute_phonon>` and its cell-size requirements.

Dense format
^^^^^^^^^^^^

The default ``hessian.out`` begins with ``#`` comment lines describing the
units, ordering, atom count, and result type, followed by one matrix row per
line. Read it with NumPy::

import numpy as np
H = np.loadtxt("hessian.out")

.. _hessian_sparse:

Sparse format
^^^^^^^^^^^^^

The Matrix Market file begins with::

%%MatrixMarket matrix coordinate real general

After ``%`` comment lines, a dimensions line gives ``3N 3N nnz``. The
remaining lines contain ``row column value`` with one-based indices in the
coordinate order above. Both halves of the symmetric matrix are stored;
exactly zero entries are omitted. Read it without converting to dense::

from scipy.io import mmread
H = mmread("hessian.mtx").tocsr()

Diagnostics
^^^^^^^^^^^

Before symmetrization, the command checks that the matrix is finite,
symmetric within numerical tolerance, and consistent with uniform
translations producing no restoring force. These checks help detect
unreliable results; they do not establish that the structure is relaxed
or dynamically stable.

Failed checks terminate the calculation. If the matrix is finite but fails
symmetry or translation checks, requested ``raw_output`` and ``metadata``
files are still written and marked ``failed_validation``. The normal
matrix and structure snapshot are not written in this case. Metadata
records the failure reason and raw diagnostics; symmetrized diagnostics
are ``null``. Do not treat these diagnostic files as an accepted result.

Examples
--------

Write the default dense ``hessian.out`` for the positions in ``model.xyz``::

potential nep.txt
compute_hessian analytic

Write a sparse matrix and a structure snapshot::

potential nep.txt
compute_hessian analytic output_format sparse output hessian.mtx structure_output hessian.xyz

Also request the raw matrix and diagnostics (valid with either format)::

potential nep.txt
compute_hessian analytic raw_output hessian_raw.out metadata hessian.json

.. _hessian_analytic:

Notes
-----

* Supported models are ordinary NEP energy models on a single GPU,
including their ZBL terms. Temperature-dependent NEP, multiple potentials,
multi-GPU NEP, charge, spin, vdW, and ILP models are unsupported. DFT-D3
is rejected wherever its command appears in ``run.in``. This command has no
finite-difference mode or fallback.
* Neighbor distances, including periodic images, must be at least
:math:`10^{-6}` Å. Closer neighbors terminate the calculation without
writing Hessian or diagnostic files.
* Dense storage requires :math:`9N^2` matrix entries. Choose sparse output
for large systems when most entries are zero; its storage grows with the
number of interacting atom pairs. Both formats remain limited by
available memory and supported system sizes.
1 change: 1 addition & 0 deletions doc/gpumd/input_parameters/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ See :ref:`run.in <run_in>` for command order and how settings apply to successiv
change_box
compute_cohesive
compute_elastic
compute_hessian
compute_phonon

.. rubric:: Ensembles
Expand Down
4 changes: 4 additions & 0 deletions doc/gpumd/output_files/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,10 @@ A file page describes its columns, units, and any headers or blocks needed to se
- :ref:`compute_chunk <kw_compute_chunk>`
- Time-averaged quantities in dynamic spatial bins
- Append
* - :ref:`hessian.out <hessian_out>`
- :ref:`compute_hessian <kw_compute_hessian>`
- Analytic Cartesian Hessian
- Overwrite
* - :ref:`elastic.out <elastic_out>`
- :ref:`compute_elastic <kw_compute_elastic>`
- Elastic constants
Expand Down
5 changes: 5 additions & 0 deletions src/main_gpumd/run.cu
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ Run simulation according to the inputs in the run.in file.
#include "model/box.cuh"
#include "model/read_xyz.cuh"
#include "phonon/hessian.cuh"
#include "phonon/nep_hessian_command.cuh"
#include "replicate.cuh"
#include "run.cuh"
#include "utilities/error.cuh"
Expand Down Expand Up @@ -331,6 +332,10 @@ void Run::parse_one_keyword(
PRINT_INPUT_ERROR("replicate keyword not found in run.in file.");
}
hessian.compute(force, box, atom, group, replicate_size_);
} else if (tokens[0] == "compute_hessian") {
NEP_Hessian_Command hessian;
hessian.parse(tokens);
hessian.compute(force, box, atom, first_potential_filename_, run_input);
} else if (tokens[0] == "compute_cohesive") {
Cohesive cohesive;
cohesive.parse(tokens, 0);
Expand Down
39 changes: 39 additions & 0 deletions src/phonon/gpu_macro_ext.cuh
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
/*
Copyright 2017 Zheyong Fan and GPUMD development team
This file is part of GPUMD.
GPUMD is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
GPUMD is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with GPUMD. If not, see <https://www.gnu.org/licenses/>.
*/

/*----------------------------------------------------------------------------80
GPU macro extensions used by the hessian module.

This header is included only by the analytic Hessian code so the parent
src/utilities/gpu_macro.cuh file is not modified.
------------------------------------------------------------------------------*/

#pragma once

#ifdef USE_HIP
#ifndef HESSIAN_GPU_MACRO_EXT_DEFINED
#define HESSIAN_GPU_MACRO_EXT_DEFINED
#define gpuDeviceGetLimit hipDeviceGetLimit
#define gpuDeviceSetLimit hipDeviceSetLimit
#define gpuLimitStackSize hipLimitStackSize
#endif
#else
#ifndef HESSIAN_GPU_MACRO_EXT_CUDA_DEFINED
#define HESSIAN_GPU_MACRO_EXT_CUDA_DEFINED
#define gpuDeviceGetLimit cudaDeviceGetLimit
#define gpuDeviceSetLimit cudaDeviceSetLimit
#define gpuLimitStackSize cudaLimitStackSize
#endif
#endif
Loading
Loading