AtomsCalculatorsUtilities

CombinationCalculator{N}

You can combine several calculators to one calculator with this. Giving keyword argument executor=SequentialEx() toggles on multithdeaded execution of calculators. Using executor=DistributedEx() executes calculators using multiprocessing.

Other use case is editing keywords that are passed on the calculators. E.g. you can generate new keyword argument that is then passed to all calculators. This allows you to share e.g. a pairlist between calculators.

To control what keywords are passed you need to extend generate_keywords function.

Fields

• calculators::NTuple{N,Any} : NTuple that holds calculators
• executor::Any : Transducers executor used to execute calculation - default SequentialEx
• keywords::Function : function used to generate keywords for calculators

Creation

CombinationCalculator( calc1, calc2, ...; executor=SequentialEx())

ReportingCalculator{T, TC, TF}

ReportingCalculator collects information during calculation and sent it to a Channel that can be read.

Fields

• calculator::T : caculator used in calculations
• channel::Channel{TC} : Channel where message is put
• message::TF : function that generates the message

Creation

rcalc = ReportingCalculator(calculator, Channel(32))
rcalc = ReportingCalculator(calculator, Channel(32); message_function=my_message_function)

When message_function is omitted, generate_message function is used. See it for more details on how to control generated messages.

You can access the channel by calling calculator directly with fetch or take!.

SubSystemCalculator{T, TC}

Submits subsystem to given calculator.

The purpose of this calculator is that you can split system to smaller system that can then be calculated with e.g. with different methods. One possible use case here is QM/MM calculations where you can split QM system out.

The structrure is mutable to allow mutable calculators.

Fields

• calculator::T : calculator which is used for the subsystem calculation
• subsys::TC : definition of subsystem like array of indices - has to be iterable

ZeroVirialCalculator{T,VU}

Calculator that returns zeros for virial. This calculator helps to add virial calculation to a calculator that does not have it supported. This allows to embed the calculator to calculations that need some value for virial returned.

Note that forcing zero virial is incorrect. Use at your own risk.

Fields

• calculator::T : calculator used for potential energy and forces
• virial_unit::VU : unit given to zero virial - default eV

Creation

ZeroVirialCalculator(
    mycalculator;
    virial_unit::Unitful.EnergyUnits=u"eV"
)

generate_keywords

This function is called when CombinationCalculator is used.

Default implementation will only pass keywords forward.

The call type is AtomsBase system first then all calculators and kwargs. This will allow you to extend based on calculator type.

Example

function AtomsCalculatorsUtilities.generate_keywords(sys, pp1::PairPotential, pp2::PairPotential; kwargs...)
    if cutoff_radius(pp1) ≈ cutoff_radius(pp2)
        nlist = PairList(sys, cutoff_radius(pp1), int_type = Int)
        return (; :nlist => nlist, kwargs...)
    else
        return kwargs
    end
end

will check that PairPotentials have same cutoff radius. Then calculates pairlist and passes it forward as a keyword.

generate_message(sys, calculator, calc_result; kwargs...) = calc_result

This is the default function that is called when ReportingCalculator collects a message. Extending this allows you to control what is reported.

This function is ment to allow setting of global stetting. If you want to set reporting function for an individual case, give ReportingCalculator keyword message_function=my_report where my_report is function that returns your message.

If function returns nothing the message is ignored. You can use this to control when message is sent.

IPIcalculator(address=ip"127.0.0.1"; port=31415, unixsocket=false, basename="/tmp/ipi_" )

Creates i-PI https://ipi-code.org/ server that works as an AtomsCalculators compatible calculators once i-PI driver has been connected.

By default the calculator will log protocol calls to the client. If you want to suppress these, you need to change the logging level of IPI module.

At the end of calculation you should call close on the calculator to send exit signal to the driver.

Args

• address=ip"127.0.0.1" - server address, if unixsocket=true is considered as unixsocket address

Kwargs

• basename="/tmp/ipi_" - prefixed to address if unixsocket=true
• port=31415 - network port the server is using
• unixsocket=false - use unixsocket for the connection

run_driver(address, calculator, init_structure; port=31415, unixsocket=false, basename="/tmp/ipi_" )

Connect I-PI driver to server at given address. Use kword port (default 31415) to specify port. If kword unixsocket is true, basename*address is understood to be the name of the socket and port option is ignored.

You need to give initial structure as I-PI protocol does not transfer atom symbols. This means that, if you want to change the number of atoms or their symbols, you need to lauch a new driver.

Calculator events are logged at info level by default. If you do not want them to be logged, change logging status for IPI module.

PairPotential:abstractsupertype for pair potentials. A concrete type must implement the following methods:

• eval_pair(V, r, [z1, z2, [ps, st]]) -> val
• cutoff_radius(V) -> rcut
• energy_unit(V) -> uE
• length_unit(V) -> uL

There is a default implementation of eval_grad_pair that uses ForwardDiff. Optionally this can be overloaded e.g. if the implementation of eval_pair does not allow for Dual numbers.

AtomsCalculators uses the Lux interface is used manage parameterized potentials.

SimplePairPotential{TF, TS, UE, UL} <: PairPotential

Create simple analytical pair potential.

To create a new potential you need to supply

• scalar to scalar function for pair energy
• two identities for atoms to for a pair (currently atomic numbers)
• cutoff radius

You can also give keywords for energy and length units that the resulting energy, forces and virial have. Defaults to eV and Å.

Fields

• f::TF : function that takes distance and returns energy
• atom_species::Tuple{TS,TS} : pair of atom species among which the potential has valid
• rcut::Float64 : cutoff radius that has unit UL

Example

V = SimplePairPotential(
    r -> -1/r^6
    1,          # hydrogen
    2,          # helium
    6.0u"Å";
    energy_unit=u"eV",
    length_unit=u"Å"
)

eval_grad_pair(V, r, [z1, z2, [ps, st]]) -> (val, deriv)

Evaluate a pair potential V and it's derivative acting between two particles of species z1 and z2 at a distance r, with parameters ps and state st.

eval_pair(V, r, [z1, z2, [ps, st]]) -> val

Evaluate a pair potential V acting between two particles of species z1 and z2 at a distance r, with parameters ps and state st.

Basic first-order finite-difference test for scalar F

fdtest(F, dF, x; h0 = 1.0, verbose=true)

• F is a scalar-valued function
• dF is the gradient of F
• x is the point at which to test the gradient, it can be a Number, AbstractVector{<: Real} or a AbstractVector{SVector{D, T}}.

fdtest(calc, sys::AbstractSystem; kwargs...)

Performs a finite-difference test for a calculator on an atom system and returns a named tuple with the results.

kwargs

• verbose=true : print the results of the test
• rattle=false : apply a random perturbation to the system before testing (to turn this on, set the amount of rattling, not true)
• test_virial=true : test the virial
• test_forces=true : test the forces
• tol = 1e-3 : the relative tolerance for the test
• h0 = 1e-2 * u"Å" : the largest step-size for the finite-difference test, this is a sensible default for atomistic systems but should be adapted if the tests fail with this default.