amspython: Python Stack¶

General¶

The Amsterdam Modeling Suite includes a Python stack based on the Enthought Python Distribution.

This Python stack is completely separate from any other Python installations on the system.

All programs within the Amsterdam Modeling Suite launch Python via a special command, amspython. See Getting Started and Useful commands.

Python packages available in amspython¶

The Python stack comes pre-installed with, for example:

• PLAMS: Python library for running and analyzing AMS calculations

• pyCRS: Python library for running and analyzing COSMO-RS calculations

• PISA : Python library for preparing AMS input files

• SCM libbase : Python library for chemical structures, units, parsing AMS input files

• AKFReader: Python library for reading and parsing the AMS KF output files

• ASE: Use external calculators with AMS

• ASE: Use AMS as an ASE calculator

• pyZacros: Python library for Zacros Kinetic Monte Carlo simulations

• FlexMD: advanced Python-based molecular dynamics and QM/MM

• AuToGraFS: Python Library for MOFs, Zeolites, COFs, …

• RDKit

• Standard packages like numpy, scipy, matplotlib

Optional addon packages available through the AMS package manager:

• Jupyter lab,

• pandas,

• pymatgen,

• PyTorch,

• Tensorflow,

• and more

External community packages not developed by SCM:

• PyADF pursues the concept of automatizing the workflows required for multiscale simulations.

• tcutility: Python library containing many helper functions and classes for use in programs written in the TheoCheM group

Installing new modules in the AMS Python Stack¶

1. Package manager

   Some Python packages, like pymatgen, pandas, and Jupyter lab, are installable through the AMS package manager.

2. Pip

   You can also extend the AMS Python Stack with by using pip to install additional modules if they are available on the Python Package Index (PyPI). All pip commands need to be prefixed with $AMSBIN/amspython -m:

   $AMSBIN/amspython -m pip list
   $AMSBIN/amspython -m pip show scipy
   $AMSBIN/amspython -m pip search rotate-backups
   $AMSBIN/amspython -m pip install rotate-backups
   

   This will install the packages into a Python virtual environment.

   Warning

   When you manually install packages into the AMS Python environment, you may break the SCM-supported ML Potential packages, for example by installing incompatible versions of dependencies. If this happens, it is easiest to remove the AMS Python virtual environment completely and reinstall the ML Potential packages from the package manager.

3. Modify SCM_PYTHONPATH

   Alternatively, you can add the location of the source to the SCM_PYTHONPATH variable to make the module available in the AMS Python Stack. To avoid collisions with other Python installations on the system, we unload PYTHONPATH and PYTHONHOME from the environment when launching the ADF Python Stack and put the content of SCM_PYTHONPATH into PYTHONPATH.

   Hint

   If you for some reason have to use the PYTHONPATH variable and are unable to use SCM_PYTHONPATH, you can modify $AMSBIN/amspython and $AMSBIN/amsipython to not have it cleared when starting python.

Install and run Jupyter Lab (Jupyter Notebooks)¶

"$AMSBIN/amspython" -m jupyterlab

# create the conda environment
conda create -n amspython-env

# create the python executable
conda run -n amspython-env sh -c '
mkdir -p "$CONDA_PREFIX/bin"
PYTHONFILE="$CONDA_PREFIX/bin/python"
[ -f "$PYTHONFILE" ] && echo "$PYTHONFILE already exists, I will not overwrite it." && exit 1
echo "#!/bin/sh" > "$PYTHONFILE"
echo "\"\$AMSBIN/amspython\" \"\$@\"" >> "$PYTHONFILE"
chmod +x "$PYTHONFILE"
'

# test the python executable
conda run -n amspython-env python -c '
import sys
print(f"amspython-env runs python from {sys.executable}")
'

cat > template.tpl <<EOF
{%- block body %}
{{ nb | json_dumps }}
{% endblock body %}
EOF


"$AMSBIN/amspython" \
    -m nbconvert \
    --to custom \
    --template template.tpl \
    --RegexRemovePreprocessor.patterns='^!' \
    --execute \
    --output output.ipynb \
    notebook.ipynb

Jupyter frequently asked questions¶

Select kernel¶

When opening a notebook, you may be asked to select a kernel:

If unsure which is the correct kernel, create a new notebook in Jupyter and find the correct kernel in the top right:

Note that Jupyter may detect also kernels unrelated to AMS on the system, e.g. installed by another program or the user.

Notebook is not trusted¶

Notebooks not created by the user, including those downloaded from scm.com, will not always be trusted by Jupyter. A warning may display in the terminal saying Notebook <path>/<filename>.ipynb is not trusted. This means that Jupyter will not execute the contents automatically, but it is still possible to run the contents manually, e.g. through pressing shift-enter in a cell. To trust a notebook, either use the command jupyter trust <path>/<filename>.ipynb in the command line, or click View > Active Command Palette and type Trust Notebook in the search bar.

— Logging error —¶

On Windows, a --- Logging error --- is sometimes displayed. This happens when Unicode characters (e.g. powers or symbols related to units) are displayed. The error can be ignored, the characters will be displayed correctly in the notebook and the source in the affected cell is fully executed.

Python virtual environment¶

Useful commands¶

• Start a Python shell:

  $AMSBIN/amspython
  

• Install new packages via pip:

  $AMSBIN/amspython -m pip install name_of_package
  

• Find out the location of an installed package (e.g. numpy):

  $AMSBIN/amspython -c 'import numpy; print(numpy.__file__)'
  

• Find out which python binary is launched by amspython:

  $AMSBIN/amspython -c 'import sys; print(sys.executable)'
  

• Disable the virtual environment (one-time):

  SCM_PYTHONDIR='' $AMSBIN/amspython