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 Amsterdam Modeling PySuite if not yet installed

  python -m pip install 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 Amsterdam Modeling PySuite if not yet installed (replace name-of-your-conda-env):

  conda run -n name-of-your-conda-env python -m pip install 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

• A dialog may pop up asking you to install if it is not already installed Jupyterlab. Select Yes. Wait for the installation to complete.

• 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
  

• Make sure that Jupyterlab is installed:

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

What do I do inside Jupyterlab?

• Open a .ipynb file (Jupyter notebook). Use Shift+ENTER to execute a cell.

• See also the tutorial for Jupyter notebooks

How do I run a Jupyter notebook on a remote machine?

• 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 install AMS required packages?

How do I install a required AMS package?

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

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.

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.

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

What do these terms mean, and which one should I use?

• 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 Python package collection (including PLAMS and related tools) that lets standard Python environments work well with AMS workflows.

• 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 packages such as amsterdam-modeling-pysuite.

• amspackages: AMS package manager command ($AMSBIN/amspackages) for optional components managed by AMS (for example JupyterLab integration in AMS).

• 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 (or conda) + pip install amsterdam-modeling-pysuite if you need a custom Python stack.