.. _instructors:

============================
Instructions for instructors
============================

The DTU databar
===============

The summer school exercises will be running in the DTU Databar, not on
Niflheim.  You can log in with your DTU username and password.  Like
Niflheim, it has a login node and a number of compute node, but unlike
Niflheim it also has *interactive compute nodes* where the students
and you can run e.g. your Jupyter notebooks.

Logging in
----------

::

   ssh -X login.gbar.dtu.dk

Then proceed from the login node to an interactive compute node with
the command::

  linuxsh -X


Creating an SSH key pair (while at DTU!)
----------------------------------------
.. _keypair:

When you are on the DTU network (or use a VPN) logging in requires
authentification with *either* a password *or* a cryptographic key.
But once we are off-campus, it requires *both*.  It is much easier to
set up while still on DTU.

Creating a key pair on Mac or Linux
...................................

First check if you already have a public key on your laptop.  In a
terminal, type::

  cd
  ls -lh .ssh

Look for files named ``id_rsa`` and ``id_rsa.pub``.  If they are not
there, create them with the command::

  ssh-keygen -b 4096 -t rsa

When prompted for a file name, just keep the default.  When asked for
a password, you can choose one if you feel paranoid / security minded,
or leave it blank to avoid having to type a password when you use the
key.

Once the file have been created, log in to the databar and type the
following commands::

  cd
  mkdir -p .ssh
  nano .ssh/authorized_keys

In that file, paste the content of the file ``id_rsa.pub`` from your
laptop.  Press Ctrl-X to exit the "nano" editor, and choose Yes to
save the file.

Not open a new window and try logging in to the databar.  If you are
at DTU, you should no longer be prompted for a password.


Creating a key pair on Windows
..............................

Open MobaXterm.  On the Tools menu, choose MobaKeyGen

Leave parameters as default (RSA, 2048 bits).  Click Generate, and
move the mouse to generate randomness.  When the key is ready, click
"Save private key".  Choose a name that makes sense.  You can set a
passphrase if you feel paranoid / security-minded.

Keep the MobaKeyGen window open (if you close it, you can load the
private key again).  Log in to the DTU databar.  On the databar, run
the commands::

  cd
  mkdir -p .ssh
  nano .ssh/authorized_keys

Now copy the private key from the top field of the MobaKeyGen window
(with Ctrl-C), and then paste it into the nano editor by
right-clicking on the window.  Once the key is pasted, press ENTER so
the line ends with a line break.  Then exit the "nano" editor by
pressing Ctrl-X, say Yes to save the file.

Now log out of the databar and close the MobaKeyGen window.

Click on the Settings button (one of the last ones on the MobaXTerm
toolbar). On the configuration window that opens you select the SSH
tab. The last box is labelled “SSH agents”, select “Use internal SSH
agent MobAgent”.

Click the Plus sign next to the box labelled “Load the following keys
at MobAgent startup” and then select the file you just saved with your
private SSH key.  Then press OK; MobaXterm will then need to restart.


Setting up the Virtual Environment etc
--------------------------------------

To prepare your account, run the script (you only need to do this
once)::

  bash ~jasc/setup2024

(This is the same script the students will be running to set up their account).

This will create a folder ``CAMD2024``, a virtual environment in
``CAMD2024/venv``, and a MyQueue configuration.

A line is added to your .bashrc to automatically activate the virtual
environment.  Remove it and activate manually if it causes trouble.


Summerschool Notebooks
======================

The summerschool notebooks exist in two versions, the **student
version** and the **teacher version**.  The student version is
somewhat censored, the teacher version also contain a working
solution.

The student version is autogenerated from the teacher version and is
available from the :ref:`summerschool24` web page under the individual
projects.  Remember also to download associated ``.png`` files or they
will not display properly.

The teacher version is stored in the GPAW source code, but as a
``.py`` file with special comments to help automatic conversion to
Notebook format.  In this way, the teacher versions can be run as part
of the GPAW test suite, this is the only reason that we can expect the
notebooks to still work after four years of code development!

The .py files are found in the project folders under
``venv/gpaw/doc/summerschools/summerschool24``.

Student versions of all notebooks are extracted from the source Python
files when you build the GPAW documentation (``make`` in the ``doc``
folder).  Edit your notebooks in another folder, as **building the
documentation mayoverwrite all notebooks without warning.**

To extract teacher version, go to the folder
``venv/gpaw/doc/summerschools/summerschool24`` after you have built
the documentation, then run the script::

  python convert.py --teacher
  

Making small modifications to the notebooks
-------------------------------------------

It is probably easiest to first make the modification in the
downloaded Notebook file, and then make the same modification in the
.py file.  Then submit a merge request.

Teacher versus student version
------------------------------

In the ``.py`` file, a cell can be marked to be left out in the
student version like this::

  # %%
  # teacher:
  print('N2 bond length:', slabN2.get_distance(8, 9))

The first line marks that a new cell should be made, the second that
the cell should be left out of the student version.

You can also make a single line appear different in the teacher and
student version::

  vib = Vibrations(slab,
                   name='vib',
                   indices=[8, 9],  # student: indices=[?, ?],
                   nfree=4)

Here, one line reads ``indices=[8, 9],`` but ``indices=[?, ?],`` in
the student version.


Making new notebooks or large modifications
-------------------------------------------

When making a new notebook, make it as a normal notebook, use the
``teacher`` / ``student`` markup in the comments as needed, and then
get help converting it to a .py file once it is ready.

To make major changes to an existing notebook, first extract the
"teacher version" from the .py file with the command::

  cd doc/summerschools/summerschool24
  python convert.py --teacher

**move it somewhere else to update it**, and then get help converting
it back once it is ready.  Note that rebuilding the documentation or
rerunning the command above **will cause all notebooks to be
overwritten**.

The extracted notebook will start with a cell::

  # teacher
  import ase.visualize as viz
  viz.view = lambda atoms, repeat=None: None

It disables the ASE gui when the source script is run as part of the GPAW
test suite, but should probably be deleted while you develop the notebook.

Running Notebooks in the Databar
--------------------------------

Notebooks can developed on Niflheim or elsewhere, but *all notebooks
should be testet in the DTU Databar*.

Instructions on how to run notebooks in the databar can be found here:

* :ref:`accesswin`
* :ref:`accesslinmac`


Updating the text of the project pages
--------------------------------------

Remember to also update the web pages associated with the projects.
This is done by editing the associated ``.rst`` files in
``doc/summerschools/summeschool24``, and then submitting a merge request.

