Usage¶

The ASE engine (this manual) is the interface between any existing ASE calculator and the AMS Driver (see Quickstart guide or Examples).

Important

The calculator must be installed in the AMS Python environment.

If you launch $AMSBIN/amspython, you need to be able to import all the needed packages. Otherwise, make sure to install them.

The ASE Calculator for AMS (AMSCalculator) is described in a different manual.

More information about ASE can be found in ref. 1 or on the ASE website.

What’s new in AMS2024.1?¶

It is now possible to indicate to AMS what properties the Calculator can compute and what kind of system is supported (e.g. if the Calculator can support charged and periodic systems).

What’s new in AMS2023.1?¶

The ASE engine is new in AMS2023.

Quickstart guide¶

See the below quickstart guide, or have a look at the example calculators.

Quickstart with GUI¶

Start AMSinput and switch to the ASE engine in the yellow dropdown.
In the Calculator from drop-down, select Import
In the Import field, type ase.calculators.emt.EMT (more information: ASE implementation of EMT)
Copy and paste the following atom coordinates into AMSinput

Ag 0. 0. 0.
Cu 0. 0. 2.0

Run the calculation
Open the trajectory in AMSmovie, or update the geometry in AMSinput

Quickstart with Python¶

See the PLAMS example: Engine ASE: AMS geometry optimizer with forces from any ASE Calculator

Quickstart with command-line¶

Run the below example:

$AMSBIN/ams <<eor
Task SinglePoint
Properties
    Gradients Yes
End

System
    Atoms
        Ag 0. 0. 0.
        Cu 0. 0. 2.0
    End
End

Engine ASE
   Type Import
   Import ase.calculators.emt.EMT
EndEngine
eor

Engine input¶

Calculator from Import¶

If a Calculator is installed in the AMS python stack, it can be selected by specifying the module and name of the Calculator in Import.

Example without arguments¶

The EMT calculator is a fast method applicable to many systems, especially metals.

Engine ASE
   Type Import
   Import ase.calculators.emt.EMT
EndEngine

Example with arguments¶

Engine ASE
    Type Import
    Import ase.calculators.harmonic.SpringCalculator
    Arguments
      ideal_positions=[[0.2,0.0,0.0],[0.8,0.0,0.0]]
      k=2.0
    End
EndEngine

Calculator from Python file¶

A Calculator is selected by providing a python file through File and should contain a function or class named get_calculator which returns an initialized ASE Calculator.

Example without arguments¶

The AMS input file contains:

Engine ASE
   Type File
   File /path/to/pythonfile.py
EndEngine

With pythonfile.py containing e.g.

from ase.calculators.harmonic import SpringCalculator
def get_calculator():
   return SpringCalculator(ideal_positions=[[0.2,0.0,0.0],[0.8,0.0,0.0]], k=2.0)

Example with arguments¶

Engine ASE
   Type File
   File /path/to/pythonfile.py
   Arguments
      ideal_positions=[[0.2,0.0,0.0],[0.8,0.0,0.0]]
      k=2.0
   End
EndEngine

With pythonfile.py containing e.g.

from ase.calculators.harmonic import SpringCalculator
def get_calculator(ideal_positions, k):
   return SpringCalculator(ideal_positions=ideal_positions, k=k)

Specifying arguments for the Calculator¶

Arguments can be specified either with the Arguments argument as above, or with ArgumentsFromFile.

ArgumentsFromFile is either a yaml file with the .yml extension or a python file with the .py extension.

Obtaining results from the Calculator¶

When available, the energy, forces and stress are always obtained and are fully integrated in AMS. If a Calculator holds any additional results in its results dictionary, then by default they are stored in the Other section of ase.rkf, but without any unit conversions. If additional results are undesired, they can be turned off through AllASEResults and specific results can be requested by setting Results.

Example. The AMS input file contains:

Engine ASE
   Type File
   File custom/calculator.py
   AllASEResults no
   Results specific_result
EndEngine

Specifying the capabilities of a Calculator¶

The AMS driver can make several decisions based on what an engine is able to do. Use the scm.amspipe.AMSExternalCapabilities class:

from scm.amspipe import AMSExternalCapabilities
from ase.calculators.calculator import Calculator

class MyDipoleCalculator(Calculator):
    implemented_properties = ['energy', 'forces', 'dipole']
    ...

def get_calculator():
    calc = MyDipoleCalculator()
    capabilities = AMSExternalCapabilities(charges=True) #indicate the calculator can handle a charged system
    capabilities.apply_implemented_properties(calc.implemented_properties) #will find that 'dipole' is supported so AMS will e.g. automatically compute intensities when doing a normal mode calculation
    calc.ams_capabilities = capabilities

Troubleshooting¶

If the required Calculator needs advanced setup or input arguments, it is usually more convenient to use the python input style and handle such details in there.
The Arguments block is stripped of any indentation and comments (“!”, “#” and “::”). If this is not desirable, use ArgumentsFromFile or python input style instead.
If the Calculator accepts any arguments related to files, make sure to provide absolute paths and not relative paths. The Calculator does not run in the same directory as AMS to avoid conflicts.
If an AMS calculation fails to run with the ASE calculator, make sure you have specified correctly what capabilities the Calculator has.

Parametrization with ParAMS¶

You can use ParAMS to fit the parameters of your ASE calculator.

See the ASE calculator parametrization example.

Support¶

SCM does not provide support for any ASE calculators.

Licensing¶

In AMS2023, the ASE engine is part of the product “ML Potentials & Classical Force Fields”.

References¶

1: A. H. Larsen, J. J. Mortensen, J. Blomqvist, I. E. Castelli, R. Christensen, M. Dułak, J. Friis, M. N. Groves, B. Hammer, C. Hargus, E. D. Hermes, P. C. Jennings, P. B. Jensen, J. Kermode, J. R. Kitchin, E. L. Kolsbjerg, J. Kubal, K. Kaasbjerg, S. Lysgaard, J. Bergmann Maronsson, T. Maxson, T. Olsen, L. Pastewka, A. Peterson, C. Rostgaard, J. Schiøtz, O. Schütt, M. Strange, K. S. Thygesen, T. Vegge, L. Vilhelmsen, M. Walter, Z. Zeng, K. W. Jacobsen. J. Phys.: Condens. Matter Vol. 29 (2007) 273002 https://iopscience.iop.org/article/10.1088/1361-648X/aa680e