FrictionModels

FrictionModels

All models defined within this module are designed for use with electronic friction methods.

ClassicalFrictionModel <: ClassicalModel

ClassicalFrictionModels must implement potential!, derivative!, and friction!

potential! and friction! should be the same as for the ClassicalModel.

friction! must fill an AbstractMatrix with size = (ndofs*natoms, ndofs*natoms).

CompositeFrictionModel{M,F} <: ClassicalFrictionModel

Combine an ClassicalModel with an ElectronicFrictionProvider.

This allows for arbitrary composition of potentials and friction providers, such that any classical model can be augmented with any form of electronic friction.

ConstantDensity

This exists mainly for testing purposes.

ConstantFriction

Friction model which returns a constant value for all positions. Use with a single value, a vector of diagonal values or a full-size Matrix

DiagonalFriction

Abstract model type which yields diagonal friction matrices. This allows some integrators to fall back to simpler routines and save time.

Subtypes of this must implement ndofs and friction_atoms fields. Subtypes of this must implement get_friction_matrix for functionality with Subsystems and CompositeModels.

Units of friction are mass-weighted, and the atomic unit of friction is: [Eh / ħ / me] Convert common friction units such as ps^-1 or meV ps Å^-2 using UnitfulAtomic.austrip. If atomic masses are required to calculate friction in your ElectronicFrictionProvider (e.g. for Isotope support), the atomic masses to use should be included as a type field.

This should be an interface to the prediction of the electronic density as a function of atomic positions. It must contain an atoms field containing NQCBase.Atoms for the whole system in question.

It should support a density! method, which is described below for a constant output.

ElectronicFrictionProvider

Abstract type for defining models that provide electronic friction only.

Subtypes of this must implement friction! and ndofs. Subtypes of this should implement get_friction_matrix for functionality with Subsystems and CompositeModels. friction! must act on a square Matrix{<:Number} of size ndofs * length(atoms.masses).

Units of friction are mass-weighted, and the atomic unit of friction is: [Eh / ħ / me] Convert common friction units such as ps^-1 or meV ps Å^-2 using UnitfulAtomic.austrip. If atomic masses are required to calculate friction in your ElectronicFrictionProvider (e.g. for Isotope support), the atomic masses to use should be included as a type field.

LDFAFriction(density, atoms; friction_atoms=collect(Int, range(atoms)))

FrictionProvider for the Local Density Friction Approximation.

# Arguments

## density
This should be an ElectronDensityProvider. 

## atoms
`NQCBase.Atoms` for the structure in question. This determines the correct fitting curve between Wigner-Seitz radii and electronic friction as shown in Gerrits2020. 
Usually, this is the same `Atoms` object as you use in your dynamics simulation. 

## friction_atoms

The atom indices which electronic friction should be applied to.

RandomFriction <: ElectronicFrictionProvider

Provide a random positive semi-definite matrix of friction values. Used mostly for testing and examples.

TensorialFriction

Abstract model type which yields full-rank friction matrices.

If atomic masses are required to calculate friction in your ElectronicFrictionProvider (e.g. for Isotope support), the atomic masses to use should be included as a type field.

A friction_atoms field must be included - This indicates that the friction matrix is only partially returned. Subtypes of this must implement NQCModels.FrictionModels.get_friction_matrix(model::ACEdsODF, R::AbstractMatrix, friction_atoms::AbstractVector) --> ::AbstractMatrix{eltype(R)}. Subtypes of this must implement ndofs(m::TensorialFriction) --> ::Int.

Units of friction are mass-weighted, and the atomic unit of friction is: [Eh / ħ / me] Convert common friction units such as ps^-1 or meV ps Å^-2 using UnitfulAtomic.austrip.

A system-size friction matrix is obtained with friction(model, positions), or friction!(model, friction_matrix, positions)

friction!(model::Model, F, R:AbstractMatrix)

Fill F with the electronic friction as a function of the positions R.

F must be a square Matrix{<:Number} of size ndofs * n_atoms.

Units of friction are mass-weighted, and the atomic unit of friction is: [Eh / ħ / me]

Convert common friction units such as ps^-1 or meV ps Å^-2 using UnitfulAtomic.austrip.

friction(model::DiagonalFriction, R::AbstractMatrix)

Allocating version of the friction function to work with any model

friction(model::Model, R::AbstractMatrix)

Obtain the friction for the current position R.

Yarr, Friction be a square Matrix{<:Number} of size ndofs * n_atoms.

Units of friction are mass-weighted, and the atomic unit of friction is: [Eh / ħ / me]

This is an allocating version of friction!.

friction_matrix_indices(model, indices)

Returns the indices of the friction matrix corresponding to the given Atom indices.

get_friction_matrix(model::LDFAFriction, R::AbstractMatrix)

getfrictionmatrix uses the specified density model to predict the friction matrix for friction_atoms and return it for just those atoms. Units of friction are mass-weighted, and the atomic unit of friction is: [Eh / ħ / me] Convert common friction units such as ps^-1 or meV ps Å^-2 using UnitfulAtomic.austrip.

This behaviour is different to NQCModels.friction!, which returns friction for the whole system, not just friction_atoms.