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? ]-

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