General, Quickstart, Usage

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

New in AMS2025: The ASE calculator can be installed into any Python environment on the system.

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.

_images/ase_overview.png

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

_images/ASE_EMT_AgCu_result.png

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

Example without arguments

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)

See also the Examples.

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)

See also the Examples.

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_result1
   Results specific_result2
EndEngine

See also

Tutorial: 10 Ways to Get the Energy and Other Properties

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
    return calc

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”.

Changelog

AMS2025.1

  • ASE calculators no longer need to be installed into amspython environment, but can be used from any Python environment.

AMS2024.1

AMS2023.1

  • The ASE engine is new in AMS2023.

References