Help! (Frequently Asked Questions)

How do I run a Python script?

How to run a Python script with the builtin amspython interpreter

  • Open a terminal

  • Source the amsbashrc.sh file from the installation directory:

    . /path/to/amshome/amsbashrc.sh

  • Execute the script:

    $AMSBIN/amspython scriptname.py
How to run a Python script from a custom Python environment

  • Open a terminal

  • Source the amsbashrc.sh file from the installation directory. This is needed because most examples need to be able to find the AMS programs.

    . /path/to/amshome/amsbashrc.sh

  • Activate your virtual environment:

    . /path/to/venv/bin/activate

  • Install the required AMS Python packages in that environment by following Amsterdam Modeling PySuite.

  • Execute the script:

    python scriptname.py
How to run a Python script from a conda environment

  • Open a terminal

  • Source the amsbashrc.sh file from the installation directory. This is needed because most examples need to be able to find the AMS programs.

    . /path/to/amshome/amsbashrc.sh

  • Install the required AMS Python packages in that environment by following Amsterdam Modeling PySuite.

  • Execute the script (replace name-of-your-conda-env):

    conda run -n name-of-your-conda-env python scriptname.py

Note

conda is not included with AMS. To use conda you must download and install it yourself.

How do I run a Jupyter notebook?

How do I launch Jupyterlab from the GUI?

  • In AMSjobs, select SCM → Jupyterlab

  • In AMS2026 and later, Jupyterlab is included by default. In older AMS versions, a dialog may pop up asking you to install it first.

  • Jupyterlab will open in your web browser and a terminal window will pop up. If you close the terminal window then your Jupyter session will be ended.

How do I launch Jupyterlab from the command-line?

  • Source the amsbashrc.sh file from the installation directory:

    . /path/to/amshome/amsbashrc.sh

  • In AMS2026 and later, Jupyterlab is included by default. In older AMS versions, install it first with $AMSBIN/amspackages install jupyterlab --yes.

  • Change to the directory you’d like to work in:

    cd /path/to/working/directory

  • Launch jupyterlab:

    $AMSBIN/amspython -m jupyterlab

  • Jupyterlab will open in your web browser. If you close the terminal window then your Jupyter session will be ended.

  • In AMS2026 and later, Jupyterlab comes preinstalled in the Python stack.

What do I do inside Jupyterlab?
How do I run a Jupyter notebook on a remote machine from the GUI?

  • Select the notebook in AMSjobs

  • Select a queue

  • Submit the job to the queue

This runs the Jupyter notebook just like any other AMS job. It will create a jobname.results folder with the results (including the output Jupyter notebook).

See also the Tutorial for Jupyter notebooks

Important

Submitting a notebook through AMSjobs only works with amspython, not any other Python environments.

How do I run a Jupyter notebook from the command-line?

Use this command:

$AMSBIN/amspython $AMSBIN/run_notebook_inplace.py my-notebook.ipynb

Note that this runs the notebook through amspython. You will not receive any output while the notebook is running. You need to wait for it to finish.

This overwrites the original notebook.

Pictures of structures look very ugly when running a notebook on a compute cluster?

The PLAMS view() function uses AMSview to generate pictures of structures. This requires a screen to be connected.

When no screen is present, it falls back to a simpler way to generate the pictures.

It may help if Xvfb is installed on the machine running the notebook. Talk to your system administrator.

How do I install required AMS packages?

How do I install a required AMS package from the GUI?

  • Open AMSjobs

  • Go to SCM → Packages

  • Search for the required package and click Install

  • See the amspackages documentation for more details.

How do I install a required AMS package from the command-line?

  • Source the amsbashrc.sh file from the installation directory:

    . /path/to/amshome/amsbashrc.sh

  • Install the package (replace name-of-package with the required package name):

    $AMSBIN/amspackages install name-of-package --yes

  • See the amspackages documentation for more details.

  • If an example lists Required packages in its header, install each package listed there using the command above.

What is the difference between an AMS package and a Python package?

  • AMS packages may be Python or non-Python packages, or combinations of both.

Other questions

amspython, Amsterdam Modeling PySuite, virtual environment, uv, uv_scm, conda, amspackages, pip - I’m confused!

  • amspython: The Python interpreter shipped with AMS. By default it has access to Amsterdam Modeling PySuite. Use this if you want the easiest setup for AMS scripting examples.

  • Amsterdam Modeling PySuite: The umbrella name for the Python packages developed by SCM. It is not currently a single installable package; in separate Python environments you install the relevant AMS Python packages individually.

  • virtual environment: An isolated Python environment (usually created with python -m venv) where you install packages for one project without affecting system Python.

  • pip: The standard Python package installer. Use it inside your chosen Python environment to install the AMS Python packages you need from the SCM package index.

  • amspackages: AMS package manager command ($AMSBIN/amspackages) for optional components managed by AMS (for example machine learning potentials or optional components on older AMS releases).

  • conda: An external environment/package manager (not included with AMS). You can use it instead of venv if you prefer conda-managed environments.

  • uv: A fast third-party Python package/environment tool, similar in purpose to pip + virtual environments.

  • uv_scm: An internal AMS tool used to handle Python environments for machine learning potentials. End users should only rarely need to use this directly.

Recommended default for most users:

  • Use amspython + amspackages if you want the least setup effort.

  • Use a virtual environment, conda environment, or uv project + Amsterdam Modeling PySuite if you need a custom Python stack. See Amsterdam Modeling PySuite.

How can I contribute a scripting example?

See Contribute Your Own Scripting Example for submission instructions and policies.

What does # dependency: {} file.txt mean?

These comments appear in some notebook examples. They indicate dependencies that can be picked up by AMSjobs when submitting a notebook to a remote queue.

This means that any external files that the notebook depends on are copied over as well.

Example:

# dependency: {} file.txt

with open("file.txt", "r") as f:
    print(f.read())

This example will only work if the file.txt exists in the same directory as the notebook.