Instructor Notes#
Important
Remember that these notes are shared publicly, so please be careful not to include any private information unless that information is linked beyond a proper authorization screen (for example, links to the course Canvas site or CoCalc sites are fine because students must authenticate.)
Content#
Potentially Interesting Readings#
Course Setup#
To setup the course I did the following:
Create Repositories on GitLab, CoCalc, etc.#
The first step is to create the various online repositories we will use for the course.
Create a project on GitLab, i.e. GitLab course repo.
Use an appropriate group (wus-courses for example).
Make it public so we can create a documentation link (see below).
Add a brief but relevant description.
(optional) Create a mirror on GitHub, i.e. GitHub course mirror.
Create a documentation project on ReadTheDocs, i.e. course documentation admin page.
You can tell ReadTheDocs to scan your GitLab and GitHub public repos, hence, if you made the main repo public above, then you should see it.
When you create the project, make the name short – this will ensure that the auto-generated slug and URL is not too long, which can cause problems. You can change this back to the full course name after you create the slug.
(optional) Create a CoCalc course file, i.e. CoCalc course file.
Open the course file and create the Shared Project and open it, i.e. CoCalc shared project.
Edit the Documentation#
At this point, you should be able to build and inspect the base documentation. To do this, and edit the documentation, you can run
make init
make doc-server
which will serve the documentation on http://localhost:8000. If you leave this running,
you should be able to edit the various MyST markdown files in Docs/, and
these updates should be incorporated into the documentation. This system uses the
following components, which you should review to understand how the documentation works:
Documentation References and Tools
Jupyter Book: The documentation is generally governed by the tools and philosophy behind the Jupyter Book project: an open source project for building beautiful, publication-quality books and documents from computational material.
Sphinx: This is the underlying documentation system which builds and links all of the documentation into the final HTML or PDF files. It is configured in the file
Docs/conf.pyand contains many features which are often enabled through theextensions.Jupyter Book provides a front-end to sphinx, with alternative ways of specifying the structure of the book. We do not use this, but instead, following the instructions to manage Jupyter Book as a Sphinx website. Thus, we use the Sphinx build tools rather than running the
jupytebookcommand.MyST – Markedly Structured Text: By default, Sphinx documentation is written in reStructuredText (RST), which is highly customizable, but not so convenient. We use MyST instead, which is a fairly minimal extension to [CommonMark Mardown][] that allows one to use RST features. Notably, the structure of the documentation is provided through
toctreedirectives. These look like the following in RST:.. toctree:: :maxdepth: 2 :caption: "Contents:" :titlesonly: :hidden: Overview Syllabus Assignments References
When translating from the Sphinx documentation, you will need to rewrite these. For example, in MyST, this becomes
```{toctree} --- maxdepth: 2 caption: "Contents:" titlesonly: hidden: --- Overview Syllabus Assignments References ```
(This is from
Docs/index.md, which specifies the start of our documentation.)MyST-NB: Our MyST documents can function as [Jupyter Notebooks][] by using the MyST-NB extension. When the documentation is built, code cells will be executed and the output displayed. This is how we make figures etc., often hiding the code so the presentation is clean, but having the code available for students to look at later if they want the details.
Jupytext: This tool allows one to convert [Jupyter Notebooks][] from one format to another. In particular, if you have a notebook you would like to include in the documentation, you can do this with:
jupytext --set-formats ipynb,myst Notebook.ipynb
This will create an appropriate
Notebook.mdfile that you can include in your documentation. (You can also do this by installing the server extension, which will provide commands to pair notebooks in your Jupyter Notebook GUI under File -> Jupytext > Pair Notebook with ….)One caution: CoCalc does not yet support Jupytext in their collaborative interface. You can always do this by launching the Classical Jupyter Notebook interface, but you lose the ability to collaborate in realtime. We are working on some hooks to make this a better experience.
Sphinx Book Theme: This controls the look of the generated documentation. Look here for details about formatting, for example, special content blocks for margin notes, etc.
https://sphinx-book-theme.readthedocs.io/en/latest/customize/sidebar-primary.html
After editing your documentation, add, commit, and push your changes:
hg add Docs/...
hg commit -m "DOC: Added notes about ..."
hg push
If you have setup everything properly as described above, this should automatically trigger ReadTheDocs to pull and build your documentation:
Check to make sure everything works.
Install Documentation on CoCalc#
Once you are happy with your documentation
(optional) On my personal machine, I establish an SSH connection to the CoCalc shared project so I can connect and install everything there. I do this by adding the following to my
~/.ssh/configfile on my laptop:# SSH Config file # dest = ~/.ssh/config # Keep this as the 2nd line for mmf_init_setup Host ccwsu # WSU Course project for instructors User c31d20a3b0af4bf7a951aa93a64395f6 Host cc555 # Shared proejct with students User ebaafbe3f8cf4598a2c9e7b6c64023c4 Host cc* # Defaults for all CoCalc aliases come after HostName ssh.cocalc.com ForwardAgent yes SetEnv LC_HG_USERNAME=Michael McNeil Forbes <michael.forbes+python@gmail.com> SetEnv LC_GIT_USERNAME=Michael McNeil Forbes SetEnv LC_GIT_USEREMAIL=michael.forbes+python@gmail.com SetEnv LC_EDITOR=vi # I also have a local config file for my Mac. I keep it in a different file # called config.local and include it with: # # Include config.local # # It contains the following which stores my keys in the Keychain Access app # so that they are authenticated when I login. Host * IgnoreUnknown UseKeychain UseKeychain yes AddKeysToAgent yes AddressFamily inet # Force IPv4 # https://www.electricmonk.nl/log/2014/09/24/ # ssh-port-forwarding-bind-cannot-assign-requested-address/
Once this is done, create a private/public keypair with
ssh-kegen -t ed25519
The copy the public key from
.ssh/id_ed25519.puband store it in your CoCalc/Settings/SSH Keys page. This will allow you to SSH to the course project or shared project withssh ccwsuor
ssh cc555respectively.
Note
If you get the following error, it probably means that you need to login to the CoCalc website and start the project - you can only SSH to a running project:
$ ssh cc555 ebaafbe3f8cf4598a2c9e7b6c64023c4@ssh.cocalc.com: Permission denied (publickey).
I also copy this key (or make another) to GitLab and GitHub so that I can authenticate there without a password.
Setup shared course project on CoCalc. Once the previous SSH connections are made, appropriately forwarding your keys, then you should be able to clone the repos to the CoCalc shared project:
# Start CoCalc project by opening the shared project linked above ssh cc555 mkdir .repositories cd .repositories git clone git@gitlab.com:wsu-courses/physics-555-quantum-technologies.git cd ~/.repositories/physics-555-quantum-technologies make init
CoCalc Assignments#
I use CoCalc for assignments assigned in the CoCalc course file. This generally worked well, but there are a few issues:
Don’t use
@interactwithnbgraderuntil issue 6137 is fixed.If you need to install things on the students accounts, then note that you can run a Terminal command in all student projects. I used this to install [Qiskit][]:
/ext/anaconda2021.11/bin/python3 -m pip install --user qiskit[visualization]
I also include the following code in each notebook:
try: import qiskit except ImportError: import sys !{sys.executable} -m pip install --user qiskit[visualization] print("Restart your kernel and try again")
Canvas Setup#
After activating the course, I started adding some assignments. The first assignment contains instructions about how to setup [Hypothes.is][] and join the private group for discussions. We will need to send students an anonymized username so that their participation cannot be tracked easily.
Discussion Forums#
I opened up a discussion forum to give people a place to comment on the course and ask questions.
Hypothes.is#
https://web.hypothes.is/help/using-the-hypothesis-app-with-assignments-in-canvas/
Quantum Networking#
(From Landscape of Quantum Networking Webinar, Paul G. Kwiat, Krister Shalam)
Photon’s likely the technology of choice.
Loss is the main issue (no repeaters).
Commercial sources of entanglement now:
Generation of entanglement with parametric downs conversion: PRL 75, 4337 (1995)
Quantum Dots.
Detection:
Avalanche photodiodes (30% efficiency for single photon detection)
Superconducting nanowires (>98% efficient, but need ~K T)
Transition edges sensors (photon-number resolving >98%)
Multiplexing with angular momentum states: https://www.nature.com/articles/s41467-020-17616-4
Quantum repeater?
Interesting application.
Quantum key distribution requires <10% error rates.
Building entanglement will cost quite a bit (energy).
Issues#
[ ]
make doc-serveris not doing the right thing. Check with Math 589… something to do with the index file.