search

Qiskit / platypus

Qiskit Textbook (beta)
https://learn.qiskit.org
Apache License 2.0
143 stars 249 forks source link

Improve README for content editors #881

Closed frankharkins closed 2 years ago

frankharkins commented 2 years ago

Steps to reproduce the problem

See README

What is the current behavior?

Currently, it's not super clear to people unfamiliar with notebooks / npm etc. how to edit the content.

What is the expected behavior?

Should include a dedicated section in the README for content editors, assuming less technical background and avoiding unnecessary tools. We should also include documentation on adding widgets.

gprs1809 commented 2 years ago

Hi @frankharkins , do you think I can help with this? I am totally new to open source, but I think I have sufficient experience with notebooks and I also know about adding interactive widgets in jupyter notebooks. This might not be a good first issue, but I am myself keen on learning how to edit contents of the qiskit textbook. If I am successful learning, I can then create the readme, but let me know if it might not be a great idea to start with this as my first open source contribution.

frankharkins commented 2 years ago

Hi @gprs1809! Yes please, it would actually be better to have a new user write this as that's who it's targeted at. I think this new section should handhold the user in:

gprs1809 commented 2 years ago

Hey @frankharkins, regarding widgets, you mentioned there are notebooks in the examples folder that contain the implementation of these widgets. I don't see an examples folder in this repository, am I missing something? Maybe, I can also see the implementation of widgets in the jupyter notebooks within the notebooks folder. Are you referring to this folder?

frankharkins commented 2 years ago

@gprs1809 sorry, the folder is notebooks/examples.

gprs1809 commented 2 years ago

Thank you, @frankharkins. One doubt I have is regarding the contribution guide (link in the current readme). It says 'As a core contributor due to some access limitations between forks and the head branch we encourage you to clone the repository instead of forking it.' This sounds like one should directly clone the project, and not fork and clone it, though the steps given before this statement assumes that the contributor has forked the project. Should a contributor fork and clone, or just clone?

frankharkins commented 2 years ago

@gprs1809 I think that's only for core contributors. Most people should fork and clone their fork.

gprs1809 commented 2 years ago

Hi @frankharkins , do you think below looks okay? Let me know your thoughts and how I could make it better.

platypus

This repository is home of the new Qiskit Textbook (beta).

The previous version of the Qiskit Textbook textbook can be found here.

The textbook is intended for use as a university quantum algorithms course supplement as well as a guide for self-learners who are interested in learning quantum programming.

Getting started (Pre-requisistes)

To contribute to this repository or to any Qiskit repository, one needs to install Git. The process is well described in this link for different OS: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git. If you use WSL2 on windows, it already comes with Git. Fork and clone the forked repository.

In order to view the chapters of the qiskit textbook as jupyter notebooks, one needs to install jupyter notebook. If you use anaconda, jupyter comes with it within the package. If you installed python without using anaconda, you could first create a virtual environment by running:

python -m venv Quantum (you could replace Quantum with your choice of name for the environment)

you would then require activating your environment by running the batch file called activate and then, just run: pip install jupyter pip install qiskit To open a jupyter notebook, one needs to just run the command jupyter notebook from the command line. It would look something like this: (quantum)required folder path$jupyter notebook

To view the Qiskit textbook website locally, one needs nodejs. To install nodejs, run the following: conda install -c conda-forge nodejs (if you are using anaconda and a conda environment) or pip install nodejs Ensure it is 14.0 version or later.

Building and viewing the Qiskit Textbook website locally

In the cloned repository, run the following from the command line:

$ cd platypus/converter/textbook-converter $ pip install -r requirements.txt -r requirements-test.txt $ cd platypus $ npm install $ npm run build $ npm start

You might see a lot of warnings when you run npm install and npm run build, you can either follow the steps provided in the warnings. Ignoring them is also fine. After following these steps, you should be able to see the qiskit textbook website locally at  http://localhost:8080/, but the index route will redirect to an external landing page. This would be useful when you want to view your changes on the website locally before you raise a pull request or push your changes.

How to contribute

If you would like to contribute by editing the existing chapters in the qiskit textbook, you will find all the notebooks within the notebooks folder. To open up a specific notebook, you would first have to start a jupyter notebook from the command line as mentioned above. This would open up your current folder on the browser as localhost and you could navigate to the notebook you would like to edit and open it. You could also create a new notebook altogether. You can start a new jupyter notebook from the 'New' dropdown on the top right of the main jupyter page that opens up once you started jupyter. If your new notebook is related to a chapter already existing in the repository, create it within that chapter folder, else you could create a new folder itself. To use Git for contributing, see contribution guide.

Widgets and using markdown in Jupyter

Once you open jupyter, you will see that it has wide rectangular cells, one can either write codes in the cell and execute or one can write formatted text, add images, write equations etc using markdown. After entering a cell, you can choose code or markdown from a dropdown at the top, just below the menu bar on the notebook. If you choose markdown, you should be able to use that cell for writing formatted text, adding images, writing equations etc.

Writing and styling text in jupyter notebooks:

Below are some ways to style your text in the jupyter notebook markdown. You would have to execute the cell or run Shift+Enter to actually see the format of text getting rendered on jupyter. You can create a heading using the pound (#) sign. For the headers to render properly, there must be a space between the # and the header text. Heading one is denoted using one # sign, heading two is denoted using two ## signs, etc, as follows:

## Heading two
### Heading three
#### Heading 4

In case you would like to put text as bullet points, you could just put * and space, followed by a bullet point, like below:

* bullet point 1
* bullet point 2
* bullet 3

Similarly, to put up steps for the implementation of an algorithm or creating an ordered list of statements, one would do the following and execute the markdown cell:

1. step1
2. step2
3. step3
4. step4

You can also use * to bold or to italicize words. To bold and italicize words, the symbols have to be touching the word and have to be repeated before and after the word using the following syntax:

 *italicized words*
 **These are bold words**

You can also use HTML in Markdown cells to create hyperlinks to websites using the following syntax: <a href="url" target="_blank">hyperlinked words</a>  Eg: The new qiskit textbook can be seen <a href="https://qiskit.org/textbook-beta/">here</a> which would render as here

You can also use Markdown to link to images on the web using the following syntax: ![alt text here](url-to-image-here) For eg:![Qiskit logo](https://upload.wikimedia.org/wikipedia/commons/5/51/Qiskit-Logo.svg), this would render as Qiskit logo

If you look at the chapters in the notebooks folder, you will find that within each chapter folder, there is a folder for all the images being rendered in the notebooks within that chapter. In such situations, one can use relative computer paths. ![tracking a car with vectors](images/car_track_2.jpg) (This image is rendered in chapter 1.1 Statevectors of the textbook).

There are plenty of resources online about formatting text and doing all possible things one may want with markdown. One such resource is https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax

Creating Reminder and Quiz blocks:

A reminder block would start with <!-- ::: q-block.reminder --> on a line and the final line for ending the block would be <!-- ::: --> Between these two lines, one would create a second level heading called Reminders and all the details of a topic within the Reminder block are put within the tag 'details', which would start with <details> and end with </details>. You might want to have several topics within a reminder block. The current format for reminder blocks in the new Qiskit textbook is that the details of a given topic within a reminder block are hidden, unless a reader clicks on it to read further. To highlight the topic name within a reminder block, but hide the details, use <summary>Matrix Math</summary>. This would create the topic 'Matrix Math' within the reminder block. See below an example of a reminder block, as it would be seen in the markdown cell before execution.

<!-- ::: q-block.reminder -->

## Reminders

<details>
  <summary>Matrix Math</summary>
To add two vectors, we add their elements together:
And to multiply a vector by a scalar, we multiply each element by the scalar:
</details>

<details>
  <summary>Orthonormal Bases</summary>
It was stated before that the two vectors $|0\rangle$ and $|1\rangle$ are orthonormal, this means they are both _orthogonal_ and _normalised_. Orthogonal means the vectors are at right angles:

![basis](images/basis.svg)

And normalised means their magnitudes (length of the arrow) is equal to 1. The two vectors $|0\rangle$ and $|1\rangle$ are _linearly independent_, which means we cannot describe $|0\rangle$ in terms of $|1\rangle$, and vice versa. However, using both the vectors $|0\rangle$ and $|1\rangle$, and our rules of addition and multiplication by scalars, we can describe all possible vectors in 2D space:

![basis](images/basis2.svg)

Because the vectors $|0\rangle$ and $|1\rangle$ are linearly independent, and can be used to describe any vector in 2D space using vector addition and scalar multiplication, we say the vectors $|0\rangle$ and $|1\rangle$ form a _basis_. In this case, since they are both orthogonal and normalised, we call it an _orthonormal basis_.
</details>

<!-- ::: -->

This would render as below:

Reminders

  Matrix Math To add two vectors, we add their elements together: And to multiply a vector by a scalar, we multiply each element by the scalar:
  Orthonormal Bases It was stated before that the two vectors $|0\rangle$ and $|1\rangle$ are orthonormal, this means they are both _orthogonal_ and _normalised_. Orthogonal means the vectors are at right angles: ![basis](images/basis.svg) And normalised means their magnitudes (length of the arrow) is equal to 1. The two vectors $|0\rangle$ and $|1\rangle$ are _linearly independent_, which means we cannot describe $|0\rangle$ in terms of $|1\rangle$, and vice versa. However, using both the vectors $|0\rangle$ and $|1\rangle$, and our rules of addition and multiplication by scalars, we can describe all possible vectors in 2D space: ![basis](images/basis2.svg) Because the vectors $|0\rangle$ and $|1\rangle$ are linearly independent, and can be used to describe any vector in 2D space using vector addition and scalar multiplication, we say the vectors $|0\rangle$ and $|1\rangle$ form a _basis_. In this case, since they are both orthogonal and normalised, we call it an _orthonormal basis_.

A quiz block is created similarly. A quiz block would start with on a line and the final line for ending the block would be . An example is given below:

<!-- ::: q-block.exercise -->

## Quick Exercise

1. Create a state vector that will give a $1/3$ probability of measuring $|0\rangle$.
2. Create a different state vector that will give the same measurement probabilities.
3. Verify that the probability of measuring $|1\rangle$ for these two states is $2/3$.

<!-- ::: -->

This would render as below:

Quick Exercise

  1. Create a state vector that will give a $1/3$ probability of measuring $|0\rangle$.
  2. Create a different state vector that will give the same measurement probabilities.
  3. Verify that the probability of measuring $|1\rangle$ for these two states is $2/3$.

You could also see some examples of blocks in notebooks/examples/blocks.ipynb

Adding Math equations in jupyter

Jupyter Notebook uses MathJax to render the Latex syntax inside markdown.  To use LaTeX in the Jupyter notebook, put the Latex math content inside ‘$$ … $$’ symbols. For eg: $$ |a\rangle = \begin{bmatrix}a_0 \\ a_1 \\ \vdots \\ a_n \end{bmatrix}, \quad |b\rangle = \begin{bmatrix}b_0 \\ b_1 \\ \vdots \\ b_n \end{bmatrix} $$  The above is creating two column vectors a and b. You could run above in a markdown cell and see what you get.

$$ |a\rangle + |b\rangle = \begin{bmatrix}a_0 + b_0 \\ a_1 + b_1 \\ \vdots \\ a_n + b_n \end{bmatrix} $$ The above is adding the two column vectors a and b.

$$ x|a\rangle = \begin{bmatrix}x \times a_0 \\ x \times  a_1 \\ \vdots \\ x \times  a_n \end{bmatrix} $$ The above is multiplying a matrix with a scalar.

$$
\cssId{x}{x} = {-\class{x_coef}{b} \cssId{plusminus}{\pm} \class{sq_root}{\sqrt{b^2-4ac}} \over 2\class{sqcoef}{a}}
$$

The above is the equation of the solution of a Quadratic equation. Run above in a jupyter notebook markdown cell to see what you get.

$$\class{x-ket}{|x\rangle} \class{def-equal}{:=} \begin{bmatrix}\cssId{_amp-0}{\sqrt{\tfrac{1}{2}}} \\ \cssId{_amp-1}{\sqrt{\tfrac{1}{2}}} \\ \cssId{_amp-2}{0} \\ \cssId{_amp-3}{0} \end{bmatrix}$$ The above gives the state vector form of the tensor product of |0> state and |+> state. Run it on jupyter to see what you get. 

There is a lot one can do with latex. Since not everyone is comfortable with latex, a couple of tips are:

  1. Find chapter notebooks in the Qiskit Textbook website where all equations are rendered correctly. Open those notebooks from your cloned repository. In the cells containing equations, look at the markdown syntax for equations by double clicking the cells. You could use these as your reference and for your equations, you could try tweaking these latex codes. 
  2. You might not find references for all types of equations in the Qiskit Textbook notebooks. In such situations, you could try using a latex editor. One popular one is https://www.tutorialspoint.com/online_latex_editor.php

You could find resources online. Some resources are: https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Typesetting%20Equations.html, https://jupyterbook.org/content/math.html

frankharkins commented 2 years ago

@gprs1809 thank you!

This is very detailed, which is great, but I think this is probably too long and could overwhelm the reader. Also, we don't want this to get in the way of non-content-editing developers. I think this should be a subsection under 'Contribution', the other sections should stay as they are. I also think this guide should be concise, e.g. you can link out to markdown / latex guides instead of including them here, and we can point them to the examples/ folder/page to see the rendered examples.

gprs1809 commented 2 years ago

@frankharkins , thank you for the feedback. Yes, I do agree it became a bit long and the concerns you mentioned if it's this long. I have tried incorporating the changes you suggested. How does it look now? :

platypus

This repository is home of the new Qiskit Textbook (beta).

The previous version of the Qiskit Textbook textbook can be found here.

The textbook is intended for use as a university quantum algorithms course supplement as well as a guide for self-learners who are interested in learning quantum programming.

Tools & technologies

Getting Started

Pre-requisites

  1. Python (3.6 or later) environment with textbook_converter requirements installed

    $ cd platypus/converter/textbook-converter
$ pip install -r requirements.txt -r requirements-test.txt

  2. Node.js (14.0 or later) (you could install node.js from here

Setup

$ cd platypus
$ npm install
$ npm run build
$ npm start

To watch changes and rebuild automatically run with npm run watch after installing the dependencies.

After the application has started, the site will be available at http://localhost:8080/, but the index route will redirect to an external landing page.

In order to test the application locally, you can visit a specific course page, like https://localhost:8080/course/ch-prerequisites/.

You can specify the port setting the env variable PORT. For instance PORT=5000 npm start.

Contribution

If you'd like to contribute to Qiskit Textbook (beta), please take a look at our contributors guide and code of conduct

When opening a PR against the main branch, a preview build might be generated and deployed. The same redirection logic as the one described in the Setup section will apply, meaning that one would need to visit a specific course page to access the preview build.

Once you open a jupyter notebook, you will see that it has wide rectangular cells, one can either write codes in the cell and execute or one can write formatted text, add images, write equations etc. using markdown. After entering a cell, you can choose code or markdown from a dropdown at the top, just below the menu bar on the notebook. If you choose markdown, you should be able to use that cell for writing formatted text, adding images, writing equations etc.

Specifically with text, you might want to add headings, bullet points, render images or add hyperlinks. There are plenty of resources out there which can help you with this. One such resource is this.

To add blocks (for example: reminder blocks or quiz blocks) to the jupyter notebook via markdown, you could check out the markdown syntax in a specific chapter notebook in the qiskit textbook (beta), for eg: the notebook for Representing qubit states or you could check blocks.ipynb. To check the markdown syntax, you would have to open these specific notebooks from your cloned repository and double click the appropriate markdown cells.

To add mathematical symbols and equations, Jupyter Notebook uses MathJax to render the Latex syntax inside markdown. To use LaTeX in the Jupyter notebook, put the Latex math content inside ‘$$ … $$’ symbols. You could checkout Latex syntax from the any notebook in this repository. There are many resources online that could help you, a couple of which are the jupyter notebook documentation and this link. You could also use this online latex editor to assist you with writing in Latex.

License

The materials and associated source code of this open-source textbook are licensed under Apache License 2.0.

frankharkins commented 2 years ago

@gprs1809 thank you! Looking much better, can you make a PR please? Some suggestions:

gprs1809 commented 2 years ago

@frankharkins , thank you so much for the inputs. I have made the changes you suggested and made a PR. The reason I had added about anaconda and virtual env was because I thought I had to also mention about installation of jupyter notebook, but I think most content editors would know about all that. Have added back the formats and also added the link to install nodejs