Run Jobs with Jupyter Notebooks

In this tutorial you will learn

  • How to create Jupyter notebooks for AMS calculations

  • How to run a notebook interactively in JupyterLab

  • How to run a notebook through the AMSjobs queue system

Follow this tutorial only if you want to run or analyze AMS calculations with Python code.

../../_images/run-ams-job.png

What are Jupyter notebooks?

Jupyter notebooks are a popular way to

  • write Python code,

  • interactively execute parts of the code, and

  • immediately see the results, for example graphs, right next to the code that generates them

Inside Jupyter notebooks, you can use the PLAMS Python library to

  • run AMS calculations, and

  • analyze AMS calculations from any source (calculated through the GUI, command-line, or Python)

AMS includes JupyterLab as an optional installable component. With JupyterLab, you can create and run Jupyter notebooks.

Launch JupyterLab

In AMSjobs: SCM → JupyterLab
If JupyterLab is not installed, you will be prompted whether to install it. Select Yes. This will download JupyterLab from SCM servers on the internet.

This will pop up a terminal window and launch JupyterLab in your web browser.

Note

In AMS2023 and AMS2024, you need to

Start a new Python3 kernel

In the web browser window that pops up, click the blue + button
../../_images/blue-plus.png
On the Launcher panel, click the Python 3 Notebook
../../_images/launch-notebook.png

Run a Python command

In the textbox, type print("AMS is great!")
Press Shift-ENTER on the keyboard to run the cell
../../_images/print-hello-world.png

Create a molecule

Type the commands according to the screenshot below
Press Shift-ENTER on the keyboard to run the cell

This creates a PLAMS Molecule for the SMILES code “CCCCO” (1-butanol):

../../_images/created-molecule.png

Here, the trailing semicolon ; for the last command is particularly useful for plot commands. You can try to remove it to see what happens if you rerun the cell with Shift-ENTER.

Run an AMS geometry optimization

Here, we will set up an AMS job for a Universal Force Field (UFF) geometry optimization and run it. See the PLAMS documentation for more details on how to do this.

Copy this Python code into the third cell
Press Shift-ENTER on the keyboard to run the cell
plams.init()   # this line is not required in AMS2025+
s = plams.Settings()
s.input.ams.Task = "GeometryOptimization"
s.input.ForceField.Type = "UFF"
job = plams.AMSJob(settings=s, molecule=mol, name="my_first_job")
job.run()

energy = job.results.get_energy()
plams.log(f"Final energy: {energy:.6f} hartree")
../../_images/run-ams-job.png

You have now learned how to run AMS calculations interactively inside a Jupyter notebook.

Save the notebook and shut down the Jupyter server

In the Jupyter interface, select File → Save Notebook As…
Save it with the name my_first_notebook.ipynb
../../_images/save-as.png
In the Jupyter interface, select Edit → Clear All Outputs
File → Save Notebook As…
Save it with the name just_code.ipynb
../../_images/just-code.png
In the Jupyter interface, select File → Shut Down

This closes the Jupyter server. You cannot execute any more cells, nor create any new notebooks.

Tip

You can also shut down the Jupyter server from the terminal window, by pressing Ctrl-C.

Submit a Jupyter notebook to an AMSjobs queue

The rest of this tutorial requires AMS2025+.

  • With AMSjobs, you can run a Jupyter notebook just like a normal AMS calculation.

  • This requires JupyterLab to be installed, but it does not need to be running.

In AMSjobs (SCM → Jobs), select the just_code row
Run the job with Job → Run
After the job has finished, view the trajectory with SCM → Movie
../../_images/amsmovie.png

Note

If you run multiple AMS calculations inside the Jupyter notebook, you may need browse to the correct ams.rkf file using File → Open inside AMSmovie.

Both the input and output notebooks are stored

When you run a notebook through AMSjobs,

  • The original (input) .ipynb file is not changed

  • The resulting (output) .ipynb file is stored in the just_code.results folder.

Thus, if you want to open your notebook in JupyterLab again, pay attention to whether you open the input or the output:

Select the just_code job in AMSjobs
SCM → JupyterLab

The just_code.ipynb file that pops up is the original (input) notebook. You can see that it does not contain any results.

../../_images/original-vs-results.png
In the left file menu, double-click on the just_code.results folder
Double-click on the just_code.ipynb file inside the results folder

This opens up a new tab with the output .ipynb file, containing the picture of the molecule and the output with the final energy:

../../_images/jupyter-lab-after-amsjobs.png

Next steps, further reading

  • The PLAMS examples have more information about PLAMS

  • You can also run COSMO-RS jobs in a similar way

  • If you have configured a remote queue in AMSjobs, you can submit the notebook to the remote compute cluster. For this to work, the JupyterLab AMS package must have been installed on the remote compute cluster.

  • If you prefer to use VS Code over JupyterLab, see the instructions for VS Code.

  • See the official Jupyter documentation for more information about JupyterLab and Jupyter notebooks.