Skip to content

Commit

Permalink
Migrate closed source documentation (Qiskit#70)
Browse files Browse the repository at this point in the history 
Closes Qiskit#21. 

The code was copied with the below script. The closed source repository
got most of its content from open source, but did not use a Git
migration to transfer over commit history. So rather than using a Git
migration like we did with `qiskit-tutorials`
(Qiskit/qiskit#10710), this manually attributes
relevant contributors for the files they had an influence on.

```python
import shutil
import subprocess
from dataclasses import dataclass
from pathlib import Path

IQP_ROOT = Path("../iqp-channel-docs")
DOCS_ROOT = Path("./")


@DataClass(frozen=True)
class Author:
    name: str
    email: str

    def commit_line(self) -> str:
        return f"Co-authored-by: {self.name} <{self.email}>"


AXEL = Author("Axel Hernández Ferrera", "axelhzf@gmail.com")
ABBY_C = Author("Abby Cross", "across@us.ibm.com")
BECKY = Author("Rebecca Dimock", "66339736+beckykd@users.noreply.github.com")
FRANK = Author("Frank Harkins", "frankharkins@hotmail.co.uk")
KEVIN = Author("Kevin Tian", "kevin.tian@ibm.com")
JESSIE = Author("Jessie Yu", "jessieyu@us.ibm.com")
ELENA = Author("Elena Peña Tapia", "57907331+ElePT@users.noreply.github.com")
PAUL_N = Author("Paul Nation", "nonhermitian@gmail.com")
SOOLU = Author("Soolu Thomas", "soolu.thomas@ibm.com")
THOMAS_A = Author("Thomas Alexander", "thomas.a.alexander@ibm.com")
JAKE_L = Author("Jake Lishman", "jake.lishman@ibm.com")
MICHAEL_H = Author("Michael Healy", "mbhealy@ibm.com")
MARIUS = Author("Marius Hillenbrand", "marius.hillenbrand@ibm.com")
REZA = Author("Reza Jokar", "jokar@ibm.com")


def main() -> None:
    # Copy images
    copy_image_folders(
        [
            "build",
            "migration",
            "optimize",
            "qiskit-ibm-runtime",
            "run",
            "start",
        ]
    )
    commit("Migrate images from closed source", [])

    # Copy TOC files
    copy_docs_files(
        [
            "build/_toc.json",
            "optimize/_toc.json",
            "run/_toc.json",
            "start/_toc.json",
            "test/_toc.json",
        ]
    )
    commit("Migrate TOC files from closed source", [AXEL])

    # Copy original content
    copy_docs_files(
        [
            "start/index.mdx",
            "start/install.mdx",
            "start/intro-to-qiskit.ipynb",
            "start/runtime.mdx",
            "build/index.mdx",
            "build/first-circuit.mdx",
            "build/operators_overview.ipynb",
            "build/primitives.mdx",
            "build/primitives-get-started.mdx",
            "build/primitives-examples.mdx",
            "build/feature-table.mdx",
            "build/backend_reset.ipynb",
            "build/pulse.ipynb",
            "test/index.mdx",
            "test/simulators.mdx",
            "optimize/index.mdx",
            "run/hardware.mdx",
            "run/instances.mdx",
            "run/backends.mdx",
            "run/estimate-job.mdx",
            "run/queue.mdx",
            "run/circuit-execution.mdx",
            "run/reserve-system-time.mdx",
            "run/retired-systems.mdx",
        ]
    )
    commit("Migrate original content from closed source", [ABBY_C, BECKY])

    # Copy hello world
    copy_docs_files(["start/hello-world.ipynb"])
    commit("Migrate Hello World guide from closed source", [FRANK, BECKY, ABBY_C])

    # Copy runtime migration guides
    copy_docs_files(
        ["start/compare.mdx", "start/migrate.mdx", "start/migrate-examples.mdx"]
    )
    commit(
        "Migrate Runtime migration guides from closed source",
        [JESSIE, KEVIN, BECKY, FRANK, ELENA],
    )

    # Copy dynamic circuits
    copy_docs_files(
        [
            "build/getting-started-with-dynamic-circuits.ipynb",
            "build/midcircuit_measurement.ipynb",
            "build/dynamic-circuits-basics-with-qiskit.ipynb",
            "build/dynamic-circuits-basics-with-openqasm3.ipynb",
        ]
    )
    commit(
        "Migrate Dynamic Circuits content from closed source",
        [SOOLU, THOMAS_A, JAKE_L, MARIUS, MICHAEL_H, REZA, BECKY, ABBY_C],
    )

    # Copy runtime content
    copy_docs_files(
        [
            "build/primitive-options.mdx",
            "test/noise.mdx",
            "optimize/algorithm-tuning-options.mdx",
            "optimize/error-mitigation.mdx",
            "optimize/error-suppression.mdx",
            "run/account-management.mdx",
            "run/sessions.mdx",
            "run/run-sessions.mdx",
            "run/monitor.mdx",
            "run/cost.mdx",
            "run/max-execution-time.mdx",
        ]
    )
    commit(
        "Migrate Runtime content from closed source",
        [JESSIE, KEVIN, BECKY, ABBY_C],
    )

    # Copy Aer tutorial
    copy_docs_files(["test/building_noise_models.ipynb"])
    commit("Migrate Aer noise model from closed source", [PAUL_N])


def copy_docs_files(files: list[str]) -> None:
    for f in files:
        dest = DOCS_ROOT / "docs" / f
        dest.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy(IQP_ROOT / "docs" / f, dest)


def copy_image_folders(folders: list[str]) -> None:
    for folder in folders:
        shutil.copytree(
            IQP_ROOT / "packages" / "web" / "public" / "images" / folder,
            DOCS_ROOT / "public" / "images" / folder,
        )


def commit(msg: str, authors: list[Author]) -> None:
    subprocess.run(["git", "add", "."], check=True)
    if authors:
        author_lines = "\n".join(author.commit_line() for author in authors)
        msg += f"\n\n{author_lines}"
    subprocess.run(["git", "commit", "-m", msg], check=True)


main()
```
  • Loading branch information
@Eric-Arellano
Eric-Arellano committed Oct 4, 2023
2 parents 9fb536c + c970355 commit 7179d31
Show file tree
Hide file tree
Showing 103 changed files with 13,803 additions and 1 deletion.
3 changes: 2 additions & 1 deletion cSpell.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,8 @@
"XIYY",
"ZSXX",
"qelib",
"QVSM"
"QVSM",
"ITTL"
],
"ignoreRegExpList": [
// Markdown links
Expand Down
98 changes: 98 additions & 0 deletions docs/build/_toc.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
{
"title": "Build",
"children": [
{
"title": "Overview",
"url": "/build"
},
{
"title": "Build circuits with Qiskit",
"children": [
{
"title": "Build your first circuit",
"url": "/build/first-circuit"
},
{
"title": "Circuit library",
"url": "/api/qiskit/circuit_library"
},
{
"title": "Operators",
"url": "/build/operators_overview"
},
{
"title": "Dynamic circuits",
"children": [
{
"title": "Get started with dynamic circuits",
"url": "/build/getting-started-with-dynamic-circuits"
},
{
"title": "Mid-circuit measurement",
"url": "/build/midcircuit_measurement"
},
{
"title": "Dynamic circuits basics with Qiskit",
"url": "/build/dynamic-circuits-basics-with-qiskit"
},
{
"title": "Dynamic circuits basics with OpenQASM 3",
"url": "/build/dynamic-circuits-basics-with-openqasm3"
}
]
},
{
"title": "Import Qiskit into OpenQASM",
"url": "/build/qasm-circuits"
}
]
},
{
"title": "Build with primitives",
"children": [
{
"title": "Introduction to primitives",
"url": "/build/primitives"
},
{
"title": "Get started with primitives",
"url": "/build/primitives-get-started"
},
{
"title": "Primitives examples",
"url": "/build/primitives-examples"
},
{
"title": "Specify advanced runtime options",
"url": "/build/primitive-options"
}
]
},
{
"title": "Build with OpenQASM",
"children": [
{
"title": "OpenQASM 3 feature table",
"url": "/build/feature-table"
},
{
"title": "OpenQASM 3.x Live Specification",
"url": "https://openqasm.com/"
}
]
},
{
"title": "Advanced circuit options",
"children": [
{
"title": "Conditional reset",
"url": "/build/backend_reset"
},
{
"title": "Pulse gates",
"url": "/build/pulse"
}
]
}
]
}
775 changes: 775 additions & 0 deletions docs/build/backend_reset.ipynb
View file

Large diffs are not rendered by default.

1,097 changes: 1,097 additions & 0 deletions docs/build/dynamic-circuits-basics-with-openqasm3.ipynb
View file

Large diffs are not rendered by default.

1,021 changes: 1,021 additions & 0 deletions docs/build/dynamic-circuits-basics-with-qiskit.ipynb
View file

Large diffs are not rendered by default.

69 changes: 69 additions & 0 deletions docs/build/feature-table.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
---
title: OpenQASM 3 feature table
description: A list of the OpenQASM 3 language features

---

# OpenQASM 3 feature table

Below is a list of the `OpenQASM 3` language features.

For more details on these capabilities, see the [OpenQASM 3.X Live Specification](https://openqasm.com/) .

Key:

* ❌ Not supported
* 🟡 Partial support
* ✅ Supported

| Feature | Support | Comments |
| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| comments | ✅ | |
| QASM version string | ✅ | |
| `include` | ✅ | |
| unicode names | ✅ | |
| `qubit` | 🟡 | Only supports physical qubits, and no arrays. |
| `bit` | ✅ | |
| `bool` | ✅ | |
| `int` | ✅ | Some support for comparisons against integers and casting. |
| `uint` | ❌ | |
| `float` | ❌ | |
| `angle` | ❌ | |
| `complex` | ❌ | |
| `const` | ❌ | |
| `pi`/`π`/`tau`/`τ`/`euler`/`ℇ` | ❌ | |
| Aliasing: let | ❌ | |
| register concatenation | ❌ | |
| casting | 🟡 | Casting between arrays of bits, int, and bool is supported |
| `duration` | ✅ | |
| `durationof` | ❌ | |
| `ns`/`µs`/`us`/`ms`/`s`/`dt` | ✅ | |
| `stretch` | ❌ | |
| `delay` | ✅ | |
| `barrier` | ✅ | |
| `box` | ❌ | |
| Built-in `U` | ✅ | |
| `gate` | ✅ | No support for non-basis gates |
| `gphase` | ❌ | |
| `ctrl @`/ `negctrl @` | ❌ | |
| `inv @` | ❌ | |
| `pow(k) @` | ❌ | |
| `reset` | ✅ | |
| `measure` | ✅ | |
| bit operations | ✅ | |
| boolean operations | ✅ | |
| arithmetic expressions | ❌ | |
| comparisons | ✅ | |
| `if` | ✅ | |
| `else` | ✅ | |
| `else if` | ❌ | |
| `for` loops | 🟡 | Discrete sets and negative stepping is not supported. |
| `while` loops | ❌ | |
| `continue` | ❌ | |
| `break` | ❌ | |
| `return` | ❌ | |
| `extern` | 🟡 | Only for certain extern subroutines exposed by backend devices. It is currently not possible for clients to submit these. |
| `def` subroutines (classical) | ❌ | |
| `def` subroutines (quantum) | ❌ | |
| `input` | ❌ | |
| `output` | ❌ | |
56 changes: 56 additions & 0 deletions docs/build/first-circuit.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: Build your first circuit
description: Build your first quantum circuit with Qiskit

---

# Build your first circuit


The basic element needed for your first program in Qiskit is a `QuantumCircuit`. We begin by creating a `QuantumCircuit` comprised of three qubits.

```python
# Create a Quantum Circuit acting on a quantum register of three qubits
circ = QuantumCircuit(3)
```

After you create the circuit with its registers, you can add _gates_ (“operations”) to manipulate the registers. Following is an example of a quantum circuit that makes a three-qubit GHZ state:

$$|\psi\rangle = \left(|000\rangle+|111\rangle\right)/\sqrt{2}.$$

To create such a state, we start with a three-qubit quantum register. By default, each qubit in the register is initialized to $|0\rangle$. To make the GHZ state, we apply the following gates:
- A Hadamard gate $H$ on qubit 0, which puts it into the superposition state $\left(|0\rangle+|1\rangle\right)/\sqrt{2}$.
- A Controlled-NOT operation ($C_{X}$) between qubit 0 and qubit 1.
- A Controlled-NOT operation between qubit 0 and qubit 2.

On an ideal quantum computer, the state produced by running this circuit would be the GHZ state above.

Operations can be added to the circuit one by one, as shown below.

```python
# Add a H gate on qubit 0, putting this qubit in superposition.
circ.h(0)
# Add a CX (CNOT) gate on control qubit 0 and target qubit 1, putting
# the qubits in a Bell state.
circ.cx(0, 1)
# Add a CX (CNOT) gate on control qubit 0 and target qubit 2, putting
# the qubits in a GHZ state.
circ.cx(0, 2)
```
## Visualize the circuit
You can visualize your circuit using Qiskit `QuantumCircuit.draw()`, which plots the circuit in the form found in many textbooks.

```python
circ.draw('mpl')
```

(![circ.draw output](/images/build/visualize.png))

<Admonition type="tip" title="Recommendations">
- [Install and set up](../start/install)
- [Create your first circuit in Lab](/lab/first-circuit)
- [Build a circuit with Composer](https://learning.quantum-computing.ibm.com/tutorial/composer-user-guide#build-edit-and-inspect-quantum-circuits)
- [Advanced Circuits tutorial](https://qiskit.org/documentation/tutorials/circuits_advanced/01_advanced_circuits.html)
- [Test your program](../test/)
- [Run on quantum backends](../run/backends)
</Admonition>
Loading

0 comments on commit 7179d31

Please sign in to comment.