helptext.txt

Stabilizer simulator usage:
main.py <circuitfile> <measurement> [samples=1e4] [-v] [-np] [-py] [-sp] [-exact]
        [-rank] [k=?] [fidbound=1e-5] [-fidelity]

Example:
python main.py circuits/toffoli.circ __M samples=2e6
Execute toffoli gate on state |110>, then measure 2nd qubit.
Expected result: 1 with high probability.

Note: Python 3 is recommended, but not strictly necessary. Some
print statements look less pretty with python 2.

Arguments:
<circuitfile>: A file specifying the circuit you want to simulate.
Each line corresponds to a gate in the circuit. For example, the
line CCX would denote the toffoli gate controlled on qubits 1 and 2
and acting on qubit 3.

Each line length must be equal to the number of qubits. Omitted qubits
on each line can be denoted with "_", so "__H" would run the Hadamard
gate on the third qubit.

The standard gate set is H (Hadamard), S (Phase), X (Pauli-X),
CX (CNOT) and T. More sophisticated gates can be imported from other
files such as the provided reference.circ file.

<measurement>
A string consisting of the characters "_", "M", "0" and "1".
Must have length equal to the number of qubits in the input file.

If the string consists solely of "_", "0" and "1", the application
outputs the probability of a measurement result such that the qubits
have the values specified in the string.
E.g. "_01" would give the probability of measuring 001 or 101.

If the string contains the character "M", the application samples
a measurement on the qubits marked with "M". The output is a
string with length of the number of "M"'s in the input.

E.g. the circuit toffoli.circ creates the three-qubit state |111>.
The inputs "__M" or "_1M" would have 100% chance of yielding 1.
The input "_0M" would return an error message, as the second qubit
is in the state |1>.


The following arguments can be specified in any order, or ommitted.
The identity of variable is necessary, i.e. write "samples=1e3", not "1e3".


--- Sampling accuracy ---
When calculating || P |H^t> ||^2 the application instead averages 
several <theta| P |H^t> where |theta> is a random stabilizer state.

With probability (1-p_f) where p_f is a failure probability, this
approximation incurs a multiplicative error e:
|| P |H^t> ||^2 (1 - e) < average output < || P |H^t> ||^2 (1+e)

e is related to the number of samples and a failure probability p_f
via the equation samples * p_f * e^2 = 1.

[-nosampling]
Calculate || P |H^t> ||^2 exactly. Squares the runtime.

[samples=1e4]
Number of samples in calculating || P |H^t> ||^2 for projectors P.
The default value 1e4 gives an error < 0.01 with 95% probability.

[error=?]
Auto-pick the number of samples that achieve the given sampleerror
with probability 95% or greater. Overrides samples option.


--- Logging ---
[-v]
Verbose mode. Prints lots of intermediate calculation information.
Useful for debugging, or understanding the application's inner workings.

[-sp]
Silence projector printing despite verbosity. Useful for big circuits.

[-quiet]
Do not print warnings. Errors are still printed. Overridden by -v.


--- Backend configuration ---
[-py]
Use python backend. The python backend is slower than the c backend,
but the code may be easier to read.

[cpath=libcirc/sample]
Path to the compiled "sample" executable.

[mpirun="/usr/bin/mpirun"]
Location of the mpirun executable and any custom options. Must
specify absolute path of executable. The procs option below will
take care of the mpirun -np  option for you. The quotes are necessary,
and you might need to backslash escape them depending on your shell.

[procs=?]
Number of parallel processes. If unspecified the application will
auto-pick using python or mpi depending on which backend is in use.

[file=?]
Instead of executing the c backend, write to a file that the c
backend can read out of instead. Does not actually calculate anything.


--- L selection parameters ---
The algorithm must construct a magic state |H^t>, where t is the number
of T-gates in the circuit. This state is resolved as a linear combination
of several stabilizer states. An exact decomposition is achieved by
decomposing |H^2> into a sum two stabilizer states, resulting in a
decomposition of |H^t> into about 2^(t/2) stabilizer states.

For sampling queries like "_0M" we can get away with a more efficient
decomposition of |H^t> into 2^(0.23t) stabilizer states. Rather than
constructing |H^t> we construct a state |L> that is very similar to
|H^t>. |L> is defined by a k*t matrix L, where k is an input parameter.
L is randomly chosen.

An exact decomposition of this form is necessary for calculating
probability queries like "_01". We cannot use the L decomposition
because using |L> incurs a constant error, rather than a multiplicative
error: |P_out - P_actual| < sqrt(fidbound).

[-exactstate]
Pass this option to always use an exact decomposition with scaling 2^(t/2).
This is only makes a difference with sampling queries like "_0M", where
an |L> decomposition would be used otherwise.

[k=?]
The number of rows in the k*t matrix L. If k > t then k is set to t.
This parameter overrides the fidbound parameter. It is off by default,
so fidbound=1e-3 is used if neither option is specified.

[fidbound=1e-3]
k can also be chosen according to:
    k = ceil(1 - 2*t*log2(cos(pi/8)) - log2(fidbound))
This usually ensures that the inner product <H^t|L> is greater than
(1 - fidbound). By default, this parameter only affects the choice of
k, and the inner product <H^t|L> is not computed, so as to verify
that it is greater than (1 - fidbound). If k > t/2 then an exact
decomposition is used instead.

[-fidelity]
Inner product <H^t|L> display (and verification).
Pass this option and <H^t|L> is computed in time 2^(0.23t).
If the k option is specified, then <H^t|L> is simply printed.
If the fidbound option is specified, L is sampled until <H^t|L> > 1-fidbound.

[-rank]
Force rank verification.
The k*t matrix L should have rank k. Verifiying this for large k and t
can take a long time, so this is not done by default. A random k*t
matrix usually has rank k.


--- Debugging ---
[y=?], [x=?]
Set the postselection of the T gates and other measurements, e.g., y=0010.
Output should be independent of the postselection. If different y give 
different results then there is a problem somewhere.

[-forceL]
If fidbound is used to determine k, then the application reverts to exact
sampling if k > t/2. -forceL causes it to use L sampling even though it is
less efficient.