HamiltonianDerivatives

class HamiltonianDerivatives(configuration, filename, object_id, repetitions=None, atomic_displacement=None, constraints=None, use_equivalent_bulk=None, constrain_electrodes=None, log_filename_prefix='hamiltonian_displacement_', processes_per_displacement=1)

Constructor for the HamiltonianDerivatives object.

Parameters:
  • configuration (BulkConfiguration | MoleculeConfiguration | DeviceConfiguration) – The configuration for which to calculate the Hamiltonian derivatives.
  • filename (str) – The full or relative path to save the results to. See nlsave().
  • object_id (str) – The object id to use when saving. See nlsave().
  • repetitions (Automatic | list of ints) – The number of repetitions of the system in the A, B, and C-directions given as a list of three positive integers, e.g. [3, 3, 3], or Automatic. Each repetition value must be odd.
    Default: Automatic
  • atomic_displacement (PhysicalQuantity of type length) – The distance the atoms are displaced in the finite difference method.
    Default: 0.01 * Angstrom
  • constraints (list of type int) – List of atomic indices that will be constrained, e.g. [0, 2, 10].
    Default: Empty list []
  • use_equivalent_bulk (bool) – Control if a DeviceConfiguration should be treated as a BulkConfiguration.
    Default: True
  • constrain_electrodes (bool) – Control if the electrodes and electrode extensions should be constrained in case of a DeviceConfiguration.
    Default: False
  • processes_per_displacement (int) – The number of processes assigned to calculating a single displacement.
    Default: 1 process per displacement.
atomicDisplacement()
Returns:The distance the atoms are displaced in the finite difference method.
Return type:PhysicalQuantity with length unit.
constrainElectrodes()
Returns:Boolean determining if the electrodes and electrode extensions are constrained in case of a DeviceConfiguration.
Return type:bool
constraints()
Returns:The list of constrained atoms.
Return type:list of int
filename()
Returns:The filename where the study object is stored.
Return type:str
logFilenamePrefix()
Returns:The filename prefix for the logging output of the study.
Return type:str | LogToStdOut
nlprint(stream=None)

Print a string containing an ASCII table useful for plotting the Study object.

Parameters:stream (python stream) – The stream the table should be written to.
Default: NLPrintLogger()
numberOfProcessesPerTask()
Returns:The number of processes to be used to execute each task. If None, all available processes should execute each task collaboratively.
Return type:int | None
objectId()
Returns:The name of the study object in the file.
Return type:str
processesPerDisplacement()
Returns:The number of processes per displacement.
Return type:int
repetitions()
Returns:The number of repetitions of the system in the A, B, and C-directions.
Return type:list of three int.
update()

Run the calculations for the study object.

useEquivalentBulk()
Returns:Boolean determining if a DeviceConfiguration is treated as a BulkConfiguration.
Return type:bool.

Usage Examples

Note

Study objects behave differently from analysis objects. See the Study object overview for more details.

Calculate the Hamiltonian derivatives for a system repeated five times in the B direction and three times in the C direction.

hamiltonian_derivatives = HamiltonianDerivatives(
    configuration,
    filename='HamiltonianDerivatives.hdf5',
    object_id='hamiltonian_derivatives',
    repetitions=(1,5,3),
    )
hamiltonian_derivatives.update()

When using repetitions=Automatic, the cell is repeated such that all atoms within a pre-defined, element-pair dependent interaction range are included.

hamiltonian_derivatives = HamiltonianDerivatives(
    configuration,
    filename='HamiltonianDerivatives.hdf5',
    object_id='hamiltonian_derivatives',
    repetitions=Automatic,
    )
hamiltonian_derivatives.update()

The default number of repetitions i.e. repetitions=Automatic can be found before a calculation using the function checkNumberOfRepetitions().

(nA, nB, nC)  = checkNumberOfRepetitions(configuration)

Notes

The Hamiltonian derivatives are calculated using the central finite difference method in a repeated cell constituting a super cell. That is, the Hamiltonian derivatives are calculated for each atom in the central cell by displacing the atom in the supercell and determining the Hamiltonian for two displacements from its original position along each of the Cartesian directions. In DFT, the derivatives of the Hamiltonian \(\hat{H}\) can be expressed as the derivatives of the effective potential \(V_{\text{eff}}\) since the kinetic term does not contribute. Thus the Hamiltonian derivatives for the \(i\) and \(j\) basis functions can be approximated as

\[\langle i|\frac{\partial \hat{H}}{\partial R_{I,\alpha}}|j \rangle = \langle i|\frac{\partial V_{\text{eff}}}{\partial R_{I, \alpha}}|j \rangle \approx \langle i|\frac{V_{\text{eff}}(R_{I, \alpha}+\delta)-V_{\text{eff}}(R_{I, \alpha}-\delta)}{2 \delta}|j\rangle,\]

where \(R_{I, \alpha}\) is the \(\alpha\) cartesian coordinate for atom \(I\) in the central unit cell, and \(\delta\) is the atomic displacement. For Slater-Koster calculators, the Hamiltonian derivatives are described by the on-site and off-site parameters and their distance dependence, hence

\[\langle i|\frac{\partial \hat{H}}{\partial R_{I,\alpha}}|j \rangle \approx \frac{\partial}{\partial R_{I,\alpha}} \left( \langle i|\hat{H}|j \rangle \right) \approx \frac{H_{ij}(R_{I, \alpha}+\delta)-H_{ij}(R_{I, \alpha}-\delta)}{2 \delta}.\]

Aborted HamiltonianDerivatives calculations can be resumed by re-running the same script or reading the study object from file and calling update() on it. The study object will automatically detect which displacement calculations have already been carried out and only run the calculations that are not yet completed.

Notes for DFT

../../../_images/hamiltonian_derivatives_explained.png

Fig. 131 (a) a unit cell for a 1D system confined in the \(x\) and \(y\) -directions. The k-point sampling is correspondingly \((1, 1, N_{\text{C}})\) , where \(N_{\text{C}}\) is the sampling in the \(z\) -direction. (b) a super cell created by five repetitions in the \(z\) -direction of the unit cell in (a). In the calculation of the Hamiltonian derivatives the atoms in the center unit cell of the super cell (the two atom indicated with arrows) are displaced by \(\pm\delta\) in each of the Cartesian directions. (c) the change in the effective potential \(\text{d} V_{\text{eff}}\) in the super cell as an atom is displaced \(\delta\) . The number of repetitions must ensure that the change in the effective potential goes to zero at the boundaries of the super cell in the non-confined directions for every atomic displacement.

When calculating the Hamiltonian derivatives both the number of sampled k-points for the super cell and repetitions in the confined the directions must be 1. In the following the number of sampled k-points for the super cell and repetitions in the non-confined directions will be adressed. To simplify things a system with only one non-confined direction will be used, see Fig. 131 (a), but the relations for the one non-confined direction applies to all non-confined directions. The bulk configuration in Fig. 131 (a) is converged in the total energy with respect to the number of k-points of \((1, 1, N_{\text{C}})\). The number of repetitions in the super cell in the non-confined direction, see Fig. 131 (b), is chosen large enough such that the change in the effective potential \(\text{d} V_{\text{eff}}\) goes to zero at the boundaries of the super cell in the non-confined directions for every atomic displacement, confer Fig. 131 (c). For this system five repetitions of the unit cell in the confined direction is enough for the change in the effective potential to go to zero at the boundaries. The recommended k-point sampling for the non-confined direction is the number of k-points in the non-confined direction for the unit cell divided by the number of repetitions in the non-confined direction. The k-point sampling then becomes \((1, 1, \frac{N_{\text{C}}}{\text{repetitions in C}})\) and in this particular case \((1, 1, N_{\text{C}}/5)\) .

Note

From QuantumATK-2019.03 onwards, the k-point sampling and density-mesh-cutoff will be automatically adapted to the given number of repetitions when setting up the super cell inside DynamicalMatrix and HamiltonianDerivatives. That means you can specify the calculator settings for the unit cell and use it with any desired number of repetitions in dynamical matrix and hamiltonian derivatives calculations.

The Hamiltonian derivatives calculations generally requires a low tolerance in the IterationControlParameters settings, e.g. a tolerance of 1e-6. Finally, it should be noted that the HuckelCalculator currently does not support calculation of the Hamiltonian derivatives.