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.

[image]


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**. With JupyterLab, you can create and run
Jupyter notebooks.


Launch JupyterLab
=================

   In AMSjobs: **SCM → JupyterLab**
   In AMS2026 and later, JupyterLab is included by default. In older AMS versions, you may be prompted to install it first.

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

Note:

  AMS2026: JupyterLab is included by default.AMS2025; 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.


Start a new Python3 kernel
==========================

   In the web browser window that pops up, click the **blue + button**
 [image]

   On the **Launcher** panel, click the **Python 3** Notebook
 [image]


Run a Python command
====================

   In the textbox, type "print("AMS is great!")"
   Press **Shift-ENTER** on the keyboard to run the cell
 [image]


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):

[image]

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")

[image]

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**
 [image]

   In the Jupyter interface, select **Edit → Clear All Outputs**
   **File → Save Notebook As...**
   Save it with the name **just_code.ipynb**
 [image]

   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.

* In AMS2026 and later, JupyterLab is included by default. In older
  AMS versions, install it first.

* JupyterLab 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**
 [image]

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.

[image]

   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:

[image]


Next steps, further reading
===========================

* The Python Examples contain many ready-to-run scripts and Jupyter
  notebooks.

* Run Python scripts from the command-line.

* 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
  remote compute cluster must provide JupyterLab. In AMS2026 and later
  it is included by default; on older AMS versions, install the
  JupyterLab AMS package there first**.

* If you ran your calculation on a remote compute cluster, open
  AMSjobs and select **Job → Transfer from Remote** to download the
  "just_code.results" folder.

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