General, Quickstart, Usage
**************************

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

The ASE calculator may come from

* the ASE package (included with AMS),

* other external sources (see Examples), or

* you may implement your own.

*From AMS2025*: The ASE calculator can be installed into any Python
environment on the system. *New in AMS2026*: Enhanced support for ASE
calculators in uv projects.

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.

[image]


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

[image]


Quickstart with Python
----------------------

See the scripting example Engine ASE with Import and File Calculators.


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 calculate atomic charges.
       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.

* If you get an error like "ERROR: Worker failed to start", you can
  usually find more information about the error in the **standard
  output file** if you scroll up a bit. For example, if you use an
  external Python environment and get an error like
  "ModuleNotFoundError: No module named 'scm'", then make sure to
  install "scm.amspipe" and "scm.external_engines" into the other
  Python environment.


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
=========


AMS2026.1
---------

* Enhanced support for ASE calculators in uv projects


AMS2025.1
---------

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

* The default "Performance" setting changed from "ForceField" to
  "DFTB".

* The AMSinput GUI module can now pick up docstrings, arguments, and
  default values from calculator.py files.


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 periodic systemsand if it can, whether those
  systems can additionally be charged.).


AMS2023.1
---------

* The ASE engine is new in AMS2023.


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
