Python envs.: amspython, conda, …

New in AMS2025: Use ASE calculators from any Python environment.

Set the input Python Type input option to:

  • amspython: Use the Python and ASE package included with AMS. This is the default. See the quickstart guide.

  • Conda: If you want to use an ASE calculator that is not included in the core ASE package, we recommend that you install it into a separate Python environment using, for example, conda or mamba. See Get started with conda or mamba.

  • Current: If you do not have conda or mamba, you can also set the Python Type to Current. This also lets you use either the system Python or any Python virtual environment, by activating it before running AMS.

This means that you can use modern Python tools and packages, without relying on amspython.

Expert option: You can also specify the Python environment with the SCM_ASE_PYTHON_TYPE environment variable.

Set up a conda environment for use with AMS

Get started with conda or mamba

If you already have conda working and installed on your system, you can skip to the next step.

Miniforge holds minimal installers for conda and mamba, and is configured for the community-driven conda-forge channel. Several academic projects that may be interesting to couple to AMS are published on conda-forge. See the examples. See also: Is conda free? blog post.

conda and mamba are two almost equivalent programs. Typically, mamba is a bit faster for installing packages.

Warning

SCM is not affiliated with miniforge or conda-forge. SCM has no control over what packages are installed when you follow these instructions.

Couple conda to AMS: Step-by-step guide for Windows, Mac, Linux

Select the Windows, Mac, or Linux tab below:

  • If you have any open AMS GUI windows, close them: SCM → Quit All

  • Follow the download and installation instructions for Miniforge.

  • The Miniforge3 installer asks if you want to add conda to PATH. It is easiest if you select Yes. If you select No, you need to follow the instructions for SCM_CONDA_PATH below (requires AMS2025.102+).

  • Open the Miniforge3 prompt from the Start menu and verify that you can run

conda --version  # must work to be able to couple to AMS
mamba --version  # optional

The Miniforge3 prompt is how you can manage your conda environments. Use it only to run any command starting with conda (or mamba). Do not use it to launch AMS calculations.

If no errors are reported, then everything has been set up correctly!

conda --version  # must work to be able to couple to AMS
mamba --version  # optional

If you get “command not found”, add the directory containing the conda executable to your PATH (for example, export PATH="/path/to/miniforge3/condabin:$PATH" with the correct path)

If no errors are reported, then everything has been set up correctly!

conda --version  # must work to be able to couple to AMS
mamba --version  # optional

If you get “command not found”, add the directory containing the conda executable to your PATH (for example, export PATH="/path/to/miniforge3/condabin:$PATH" with the correct path)

If no errors are reported, then everything has been set up correctly!

Create a new conda environment

For creating an environment and installing packages, we will use conda, but you can also use mamba.

Create a new environment called my_first_env containing Python and ASE:

conda create -n my_first_env
conda install -n my_first_env "python<3.13" ase  # add more packages as needed

# or use mamba
# mamba create -n my_first_env
# mamba install -n my_first_env "python<3.13" ase  # add more packages as needed

Check the installed environments:

conda env list

Test your ASE and Python installation

conda run -n my_first_env python --version
conda run -n my_first_env python -c "import sys; print(sys.executable)"
conda run -n my_first_env python -c "import ase; print(ase.__version__)"

Install scm.amspipe and scm.external_engines into the conda environment

Tip

Before installing the SCM packages with pip, make sure that you have installed all the conda packages you need using conda install.

To couple AMS to your conda environment, you need to install the two packages scm.amspipe and scm.external_engines. These packages are not available as conda packages but can be installed using pip:

conda run -n my_first_env python -m pip install "$AMSHOME"/scripting/wheels/*.whl

Check your installation:

conda run -n my_first_env python -c "import scm.amspipe; import scm.external_engines"

If no errors are reported, the SCM packages have been installed correctly.

Set SCM_CONDA_PATH if conda is not on PATH

This section is only applicable in AMS2025.102+. It will not work with AMS2025.101.

On Windows, the Miniforge3 installer recommends not to add conda to PATH, and on Mac, it can be tricky to set the PATH environment variable for graphical applications.

Here is how you can set SCM_CONDA_PATH instead, to tell AMS where it can find conda:

    1. On Windows, find the installation directory containing conda.exe. You can open the the Miniforge3 prompt and run echo %CONDA_EXE% to see where conda.exe is. The directory may be something like C:\Users\username\miniforge3\Scripts. Open the directory in a file explorer to double-check that it contains conda.exe.

    2. On Mac and Linux, find the directory containing the conda executable. The directory may be something like /path/to/miniforge3/condabin

  2. Open AMSJobs, and switch to preferences: SCM → Preferences

  3. Go to the Environment panel

  4. Click the + button and select Other

  5. In the new row, set the left column to SCM_CONDA_PATH and the right column to the directory

  6. Save and close the preferences

  7. Quit all open AMS GUI windows: SCM → Quit All

Use the ASE calculator from the conda environment in AMS

"$AMSBIN/ams" -n 1 <<EOF
Task GeometryOptimization

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

Engine ASE
   Type Import
   Import ase.calculators.emt.EMT
   Python
      Type Conda
      Conda my_first_env
   End
EndEngine
EOF

Tip

You can also copy-paste the above input into AMSinput.

For more realistic examples, see Examples

Tip

The value of the Conda input option can also be the absolute path to the conda environment.

Use the current Python interpreter

If you want to use a custom Python environment but do not have access to conda or mamba (for example, you might use system Python or the Python builtin venv for virtual environments), you can set the Python Type to Current:

Engine ASE
   Python
      Type Current
   End
EndEngine

The above means that the python interpreter that is shown by the command which python (or python.exe on Windows) will be used. If you want this to be different from your system Python, you need to manually activate the corresponding virtual environment.

You need to install ase, scm.amspipe, and scm.external_engines into this Python environment.

For example, before running AMS, you may

source /path/to/my/venv/bin/activate
# install packages if not already installed
# python -m pip install ase "$AMSHOME"/scripting/wheels/*.whl

$AMSBIN/ams <<eor
Task SinglePoint

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

Engine ASE
   Type Import
   Import ase.calculators.emt.EMT
   Python
      Type Current
   End
EndEngine
eor

Specify Python environment with an environment variable

It can sometimes be convenient to set the Conda environment or Python interpreter in an environment variable instead of modifying the input file.

For example, you may want to generate the input file in a script and at that point you may not know what the name or path of the conda environment is.

The below table lists examples of valid engine input and the equivalent value for the SCM_ASE_PYTHON_TYPE environment variable.

Environment variable

Engine input

 
export SCM_ASE_PYTHON_TYPE=amspython

Engine ASE
  Python
    Type amspython
  End
End

export SCM_ASE_PYTHON_TYPE=conda:my_first_env

Engine ASE
  Python
    Type Conda
    Conda my_first_env
  End
End

export SCM_ASE_PYTHON_TYPE=current

Engine ASE
  Python
    Type Current
  End
End

Example: You can set SCM_ASE_PYTHON_TYPE=conda:my_first_env as follows:

export SCM_ASE_PYTHON_TYPE=conda:my_first_env

"$AMSBIN/ams" -n 1 <<EOF
Task GeometryOptimization

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

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

Note that this environment variable will override the Python%Type set in the input.