Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update simulator docs #5182

Merged
merged 5 commits into from
Apr 1, 2022
Merged

Update simulator docs #5182

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4167ff4
Update simulation docs.
95-martin-orion Apr 1, 2022
f59a922
Clean up links.
95-martin-orion Apr 1, 2022
cf2905a
Haunted by the ghost of misplaced commas
95-martin-orion Apr 1, 2022
2735fd2
Merge branch 'master' into cirq-sim-docs-0
95-martin-orion Apr 1, 2022
16c76f8
Merge branch 'master' into cirq-sim-docs-0
CirqBot Apr 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 70 additions & 59 deletions docs/simulation.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,8 @@
"except ImportError:\n",
" print(\"installing cirq...\")\n",
" !pip install --quiet cirq\n",
" print(\"installed cirq.\")"
" print(\"installed cirq.\")\n",
" import cirq"
]
},
{
Expand All @@ -93,10 +94,10 @@
"The names *pure state simulator* and *mixed state\n",
"simulators* refer to the fact that these simulations are\n",
"for quantum circuits; including unitary, measurements, and noise\n",
"that keeps the evolution in a pure state or a mixed state.\n",
"In other words, there are some noisy evolutions\n",
"that are supported by the pure state simulator as long as they\n",
"preserve the purity of the state.\n",
"that keeps the evolution in a pure state (i.e. a single quantum state)\n",
"or a mixed state (a mix of quantum states, each with a classical\n",
"probability). Noisy evolutions are supported by the pure state\n",
"simulator, as long as they preserve the purity of the state.\n",
"\n",
"Some external high-performance simulators also provide an interface\n",
"to Cirq. These can often provide results faster than Cirq's\n",
Expand Down Expand Up @@ -127,13 +128,13 @@
"name": "stdout",
"output_type": "stream",
"text": [
"(0, 0): ───X^0.5───@───X^0.5───M('q0')───\n │\n(1, 0): ───X^0.5───@───X^0.5───M('q1')───\n"
"(0, 0): ───X^0.5───@───X^0.5───M('q0')───\n",
" │\n",
"(1, 0): ───X^0.5───@───X^0.5───M('q1')───\n"
]
}
],
"source": [
"import cirq\n",
"\n",
"q0 = cirq.GridQubit(0, 0)\n",
"q1 = cirq.GridQubit(1, 0)\n",
"\n",
Expand Down Expand Up @@ -172,13 +173,13 @@
"name": "stdout",
"output_type": "stream",
"text": [
"q0=0\nq1=1\n"
"q0=0\n",
"q1=1\n"
]
}
],
"source": [
"from cirq import Simulator\n",
"simulator = Simulator()\n",
"simulator = cirq.Simulator()\n",
"result = simulator.run(circuit)\n",
"\n",
"print(result)"
Expand All @@ -191,13 +192,13 @@
},
"source": [
"The method `run()` returns a\n",
"[`Result`](https://github.com/quantumlib/Cirq/blob/985b411c42cbd2cd97d21e766d28f1f332cfee8b/cirq/study/result.py#L83).\n",
"[`Result`](https://github.com/quantumlib/Cirq/blob/dd1b1a4a0e26775bf94eb567591397f1f989ca55/cirq-core/cirq/study/result.py#L85).\n",
"As you can see, the object `result` contains the result of any\n",
"measurements for the simulation run.\n",
"\n",
"The actual measurement results depend on the seeding from\n",
"`random` seed generator (`numpy`). You can set this using\n",
"`numpy.random_seed`.\n",
"The actual measurement results depend on the `random` seed generator (`numpy`).\n",
"You can set this seed by passing an integer or `numpy.RandomState` as the\n",
"`seed` parameter in the `Simulator` constructor.\n",
"\n",
"Another run can result in a different set of measurement results:"
]
Expand All @@ -213,7 +214,8 @@
"name": "stdout",
"output_type": "stream",
"text": [
"q0=1\nq1=0\n"
"q0=1\n",
"q1=0\n"
]
}
],
Expand All @@ -229,18 +231,16 @@
"id": "b6847671058f"
},
"source": [
"The simulator is designed to mimic what running a program\n",
"on a quantum computer is actually like. \n",
"The `run()` methods (`run()` and `run_sweep()`) are designed to mimic what\n",
"running a program on a quantum computer is actually like. `result` only\n",
"contains measurement data, and the complete state vector is hidden.\n",
"\n",
"### Accessing the state vector\n",
"\n",
"In particular, the `run()` methods (`run()` and `run_sweep()`)\n",
"on the simulator do not give access to the state vector of the\n",
"quantum computer (since one doesn't have access to this on the\n",
"actual quantum hardware). Instead, the `simulate()` methods\n",
"To access the full state vector, the `simulate()` methods\n",
"(`simulate()`, `simulate_sweep()`, `simulate_moment_steps()`)\n",
"should be used if one wants to debug the circuit and get access\n",
"to the full state vector:"
"can be used instead. This behavior is only possible in\n",
"simulation, but can be useful for debugging a circuit:"
]
},
{
Expand Down Expand Up @@ -275,7 +275,7 @@
"source": [
"`simulate()` returns a `SimulationTrialResult` containing\n",
"the final state, as seen above. The built-in Cirq simulator returns a\n",
"[`StateVectorTrialResult`](https://github.com/quantumlib/Cirq/blob/b190b40fe2b8161729c5e02464e49092339c8014/cirq/sim/state_vector_simulator.py#L120)\n",
"[`StateVectorTrialResult`](https://github.com/quantumlib/Cirq/blob/dd1b1a4a0e26775bf94eb567591397f1f989ca55/cirq-core/cirq/sim/state_vector_simulator.py#L147)\n",
",\n",
"which includes a number of utilities for analyzing the final state\n",
"vector.\n",
Expand Down Expand Up @@ -348,12 +348,12 @@
"The `qubit_order` argument to the simulator's `run()` method\n",
"determines the ordering of some results, such as the\n",
"amplitudes in the final wave function. The `qubit_order` argument is optional: when it is omitted, qubits are ordered\n",
"ascending by their name (i.e., what their `__str__` method returns).\n",
"ascending by their name (i.e., what `str(qubit)` returns).\n",
"\n",
"The simplest `qubit_order` value you can provide is a list of\n",
"the qubits in the desired ordered. Any qubits from the circuit\n",
"the qubits in the desired order. Any qubits from the circuit\n",
"that are not in the list will be ordered using the\n",
"default `__str__` ordering, but come after qubits that are in\n",
"default `str(qubit)` ordering, but come after qubits that are in\n",
"the list. Be aware that all qubits in the list are included in\n",
"the simulation, even if they are not operated on by the circuit.\n",
"\n",
Expand Down Expand Up @@ -389,7 +389,7 @@
"id": "a36137200917"
},
"source": [
"More concretely, `k`'th amplitude in the wave function\n",
"More concretely, the `k`'th amplitude in the wave function\n",
"will correspond to the `k`'th case that would be encountered\n",
"when nesting loops over the possible values of each qubit.\n",
"\n",
Expand All @@ -409,7 +409,10 @@
"name": "stdout",
"output_type": "stream",
"text": [
"amps[0] is for first=0, second=0\namps[1] is for first=0, second=1\namps[2] is for first=1, second=0\namps[3] is for first=1, second=1\n"
"amps[0] is for first=0, second=0\n",
"amps[1] is for first=0, second=1\n",
"amps[2] is for first=1, second=0\n",
"amps[3] is for first=1, second=1\n"
]
}
],
Expand Down Expand Up @@ -486,8 +489,8 @@
"## Stepping through a circuit\n",
"\n",
"When debugging, it is useful to not just see the end\n",
"result of a circuit, but to inspect, or even modify, the\n",
"state of the system at different steps in the circuit. \n",
"result of a circuit, but to inspect the state of the system\n",
"at different steps in the circuit. \n",
"\n",
"To support this, Cirq provides a method to return an iterator\n",
"over a `Moment` by `Moment` simulation. This method is named `simulate_moment_steps`:"
Expand All @@ -504,7 +507,10 @@
"name": "stdout",
"output_type": "stream",
"text": [
"state at step 0: [0. +0.5j 0.5+0.j 0.5+0.j 0. -0.5j]\nstate at step 1: [0. +0.5j 0.5+0.j 0.5+0.j 0. +0.5j]\nstate at step 2: [0.5+0.j 0. +0.5j 0. +0.5j 0.5+0.j ]\nstate at step 3: [1.+0.j 0.+0.j 0.+0.j 0.+0.j]\n"
"state at step 0: [0. +0.5j 0.5+0.j 0.5+0.j 0. -0.5j]\n",
"state at step 1: [0. +0.5j 0.5+0.j 0.5+0.j 0. +0.5j]\n",
"state at step 2: [0.5+0.j 0. +0.5j 0. +0.5j 0.5+0.j ]\n",
"state at step 3: [1.+0.j 0.+0.j 0.+0.j 0.+0.j]\n"
]
}
],
Expand All @@ -523,15 +529,7 @@
"source": [
"The object returned by the `moment_steps` iterator is a\n",
"`StepResult`. This object has the state along with any\n",
"measurements that occurred **during** that step (so does\n",
"not include measurement results from previous `Moments`).\n",
"\n",
"In addition, the `StepResult` contains `set_state_vector()`,\n",
"which can be used to set the `state`. One can pass a valid\n",
"full state to this method by passing a numpy array. Or,\n",
"alternatively, one can pass an integer, and then the state\n",
"will be set to lie entirely in the computation basis state\n",
"for the binary expansion of the passed integer."
"measurements that occurred before or during that step."
]
},
{
Expand Down Expand Up @@ -598,7 +596,7 @@
"In addition to circuit gates with fixed values, Cirq also\n",
"supports gates which can have `Symbol` value (see\n",
"[Gates](gates.ipynb)). These are values that can be resolved\n",
"at *run-time*. \n",
"at runtime. \n",
"\n",
"For simulators, these values are resolved by\n",
"providing a `cirq.ParamResolver`. A `cirq.ParamResolver` provides\n",
Expand All @@ -616,7 +614,11 @@
"name": "stdout",
"output_type": "stream",
"text": [
"[1.+0.j 0.+0.j 0.+0.j 0.+0.j]\n[ 0.6 +0.6j 0.25-0.25j 0.25-0.25j -0.1 -0.1j ]\n[0. +0.5j 0.5+0.j 0.5+0.j 0. -0.5j]\n[-0.1 +0.1j 0.25+0.25j 0.25+0.25j 0.6 -0.6j ]\n[0.+0.j 0.+0.j 0.+0.j 1.+0.j]\n"
"[1.+0.j 0.+0.j 0.+0.j 0.+0.j]\n",
"[ 0.6 +0.6j 0.25-0.25j 0.25-0.25j -0.1 -0.1j ]\n",
"[0. +0.5j 0.5+0.j 0.5+0.j 0. -0.5j]\n",
"[-0.1 +0.1j 0.25+0.25j 0.25+0.25j 0.6 -0.6j ]\n",
"[0.+0.j 0.+0.j 0.+0.j 1.+0.j]\n"
]
}
],
Expand All @@ -637,13 +639,15 @@
"id": "10617793bfd2"
},
"source": [
"Here we see that the `Symbol` is used in two gates, and then the resolver provides this value at run time.\n",
"Here we see that the `Symbol` is used in two gates, and then the resolver\n",
"provides this value at run time.\n",
"\n",
"Parameterized values are most useful in defining what we call a\n",
"`sweep`. A `sweep` is a sequence of trials, where each\n",
"trial is a run with a particular set of parameter values.\n",
"\n",
"Running a `sweep` returns a `Result` for each set of fixed parameter values and repetitions. \n",
"Running a `sweep` returns a `Result` for each set of fixed parameter\n",
"values and repetitions. \n",
"\n",
"For instance:"
]
Expand All @@ -659,7 +663,12 @@
"name": "stdout",
"output_type": "stream",
"text": [
"q0=00\nq1=00\nq0=10\nq1=10\nq0=11\nq1=11\n"
"q0=00\n",
"q1=00\n",
"q0=10\n",
"q1=10\n",
"q0=11\n",
"q1=11\n"
]
}
],
Expand Down Expand Up @@ -697,11 +706,12 @@
"In addition to pure state simulation, Cirq also supports\n",
"simulation of mixed states. \n",
"\n",
"Even though this simulator is not as efficient as the pure state simulators, they allow for a larger class of noisy circuits to be run as well as keeping track of the simulation's density matrix. This fact can allow for more exact simulations (for example,\n",
"the pure state simulator's Monte Carlo simulation only\n",
"allows sampling from the density matrix, not explicitly giving\n",
"the entries of the density matrix like the mixed state simulator\n",
"can do). \n",
"Even though this simulator is not as efficient as the pure state simulators,\n",
"they allow for a larger class of noisy circuits to be run as well as keeping\n",
"track of the simulation's density matrix. This fact can allow for more exact\n",
"simulations: the density matrix can represent all possible results of a\n",
"noisy circuit, while the pure-state simulator can only sample from these\n",
"results.\n",
"\n",
"Mixed state simulation is supported by the\n",
"`cirq.DensityMatrixSimulator` class.\n",
Expand Down Expand Up @@ -770,7 +780,8 @@
"name": "stdout",
"output_type": "stream",
"text": [
"[[0.6 +0.j 0.447+0.j]\n [0.447+0.j 0.4 +0.j]]\n"
"[[0.6 +0.j 0.447+0.j]\n",
" [0.447+0.j 0.4 +0.j]]\n"
]
}
],
Expand Down Expand Up @@ -805,16 +816,16 @@
"These projects are listed below, along with their PyPI package\n",
"name and a description of simulator methods that they support.\n",
"\n",
"**Note:** In general, these simulators are optimized for\n",
"specific use cases. Before choosing a simulator, make sure it\n",
"supports the behavior that you need!\n",
"For most users we recommend [qsim](https://github.com/quantumlib/qsim),\n",
"but each simulator is optimized for specific use cases. Before choosing\n",
"a simulator, make sure it supports the behavior that you need!\n",
"\n",
"| Project name | PyPI package | Description |\n",
"| --- | --- | --- |\n",
"| [qsim](https://github.com/quantumlib/qsim) | qsimcirq | Implements `cirq.SimulatesAmplitudes` and `cirq.SimulatesFinalState`. Recommended for deep circuits with up to 30 qubits (consumes 8GB RAM). Larger circuits are possible, but RAM usage doubles with each additional qubit. |\n",
"| [qsim](https://github.com/quantumlib/qsim) | qsimcirq | Implements `cirq.SimulatesAmplitudes`, `cirq.SimulatesFinalState`, and `cirq.SimulatesExpectationValues`. Recommended for deep circuits with up to 30 qubits (consumes 8GB RAM). Larger circuits are possible, but RAM usage doubles with each additional qubit. |\n",
"| [qsimh](https://github.com/quantumlib/qsim/blob/master/qsimcirq/qsimh_simulator.py) | qsimcirq | Implements `cirq.SimulatesAmplitudes`. Intended for heavy parallelization across several computers; Cirq users should generally prefer qsim. |\n",
"| [qFlex](https://github.com/ngnrsaa/qflex) | qflexcirq | Implements `cirq.SimulatesAmplitudes`. Recommended for shallow / low-entanglement circuits with more than 30 qubits. RAM usage is highly dependent on the number of two-qubit gates in the circuit. |\n",
"| [quimb](https://quimb.readthedocs.io/en/latest/) | quimb | Cirq-to-quimb translation layer provided in `contrib/quimb`. In addition to circuit simulation, this allows the use of quimb circuit-analysis tools on Cirq circuits. |\n"
"| [quimb](https://quimb.readthedocs.io/en/latest/) | quimb | Not based on `cirq.Simulator`; instead uses a Cirq-to-quimb translation layer provided in `contrib/quimb`. In addition to circuit simulation, this allows the use of quimb circuit-analysis tools on Cirq circuits. |\n",
"| [qFlex](https://github.com/ngnrsaa/qflex) | qflexcirq | Implements `cirq.SimulatesAmplitudes`. RAM usage is highly dependent on the number of two-qubit gates in the circuit. Not recommended - prefer qsim or quimb. |\n"
]
}
],
Expand Down