qsim and qsimh are designed to be extensible to a variety of different
applications. The base versions of each are qsim_base and qsimh_base;
sample extensions are provided in
apps. To compile the
code, just run make qsim. Binaries of the form qsim(h)_*.x will be added
to the apps directory.
Sample circuits are provided in circuits.
qsim_base usage
./qsim_base.x -c circuit_file -d maxtime -t num_threads -f max_fused_size -v verbosity -z
| Flag | Description |
|---|---|
-c circuit_file |
circuit file to run |
-d maxtime |
maximum time |
-t num_threads |
number of threads to use |
-f max_fused_size |
maximum fused gate size |
-v verbosity |
verbosity level (0,1,2,3,4,5) |
-z |
set flush-to-zero and denormals-are-zeros MXCSR control flags |
qsim_base computes all the amplitudes and just prints the first eight of them (or a smaller number for 1- or 2-qubit circuits).
Verbosity levels are described in the following table.
| Verbosity level | Description |
|---|---|
| 0 | no additional information |
| 1 | add total simulation runtime |
| 2 | add initialization runtime and fuser runtime |
| 3 | add basic fuser statistics |
| 4 | add simulation runtime for each fused gate |
| 5 | additional fuser information (qubit indices for each fused gate) |
Example:
./qsim_base.x -c ../circuits/circuit_q24 -d 16 -t 8 -v 1
qsim_von_neumann usage
./qsim_von_neumann.x -c circuit_file -d maxtime -t num_threads -f max_fused_size -v verbosity -z
| Flag | Description |
|---|---|
-c circuit_file |
circuit file to run |
-d maxtime |
maximum time |
-t num_threads |
number of threads to use |
-f max_fused_size |
maximum fused gate size |
-v verbosity |
verbosity level (0,1,2,3,4,5) |
-z |
set flush-to-zero and denormals-are-zeros MXCSR control flags |
qsim_von_neumann computes all the amplitudes and calculates the von Neumann entropy. Note that this can be quite slow for large circuits and small thread numbers as the calculation of logarithms is slow.
Example:
./qsim_von_neumann.x -c ../circuits/circuit_q24 -d 16 -t 4 -v 1
qsim_amplitudes usage
./qsim_amplitudes.x -c circuit_file \
-d times_to_save_results \
-i input_files \
-o output_files \
-f max_fused_size \
-t num_threads -v verbosity -z
| Flag | Description |
|---|---|
-c circuit_file |
circuit file to run |
-d times_to_save_results |
comma-separated list of circuit times to save results at |
-i input_files |
comma-separated list of bitstring input files |
-o output_files |
comma-separated list of amplitude output files |
-t num_threads |
number of threads to use |
-f max_fused_size |
maximum fused gate size |
-v verbosity |
verbosity level (0,1,2,3,4,5) |
-z |
set flush-to-zero and denormals-are-zeros MXCSR control flags |
qsim_amplitudes reads input files of bitstrings, computes the corresponding amplitudes at specified times and writes them to output files.
Bitstring files should contain bitstings (one bitstring per line) in text format.
Example:
./qsim_amplitudes.x -c ../circuits/circuit_q24 -t 4 -d 16,24 -i ../circuits/bitstrings_q24_s1,../circuits/bitstrings_q24_s2 -o ampl_q24_s1,ampl_q24_s2 -v 1
qsim_qtrajectory_cuda usage
./qsim_qtrajectory_cuda.x -c circuit_file \
-d times_to_calculate_observables \
-a amplitude_damping_const \
-p phase_damping_const \
-t traj0 -n num_trajectories \
-f max_fused_size \
-v verbosity
| Flag | Description |
|---|---|
-c circuit_file |
circuit file to run |
-d times_to_calculate_observables |
comma-separated list of circuit times to calculate observables at |
-a amplitude_damping_const |
amplitude damping constant |
-p phase_damping_const |
phase damping constant |
-t traj0 |
starting trajectory |
-n num_trajectories |
number of trajectories to run starting with traj0 |
-f max_fused_size |
maximum fused gate size |
-v verbosity |
verbosity level (0,1,2,3,4,5) |
qsim_qtrajectory_cuda runs on GPUs. qsim_qtrajectory_cuda performs quantum trajactory simulations with amplitude damping and phase damping noise channels. qsim_qtrajectory_cuda calculates observables (operator X at each qubit) at specified times.
Example:
./qsim_qtrajectory_cuda.x -c ../circuits/circuit_q24 -d 8,16,32 -a 0.005 -p 0.005 -t 0 -n 100 -f 4 -v 0
qsimh_base usage
./qsimh_base.x -c circuit_file \
-d maxtime \
-k part1_qubits \
-w prefix \
-p num_prefix_gates \
-r num_root_gates \
-t num_threads -v verbosity -z
| Flag | Description |
|---|---|
-c circuit_file |
circuit file to run |
-d maxtime |
maximum time |
-k part1_qubits |
comma-separated list of qubit indices for part 1 |
-w prefix |
prefix value |
-p num_prefix_gates |
number of prefix gates |
-r num_root_gates |
number of root gates |
-t num_threads |
number of threads to use |
-v verbosity |
verbosity level (0,1,4,5) |
-z |
set flush-to-zero and denormals-are-zeros MXCSR control flags |
qsimh_base just computes and just prints the first eight amplitudes. The hybrid
Schrödinger-Feynman method is used. The lattice is split into two parts.
A two level checkpointing scheme is used to improve performance. Say, there
are N gates on the cut. We split those into three parts: p+r+s=N, where
p is the number of "prefix" gates, r is the number of "root" gates and
s is the number of "suffix" gates. The first checkpoint is executed after
applying all the gates up to and including the prefix gates and the second
checkpoint is executed after applying all the gates up to and including the
root gates. The full summation over all the paths for the root and suffix gates
is performed.
The path for the prefix gates is specified by prefix. It is just a value of
bit-shifted path indices in the order of occurrence of prefix gates in the
circuit file. This is primarily used for distributed execution - see the
Distributed execution section below for more details.
Example (running on one machine):
./qsimh_base.x -c ../circuits/circuit_q30 -d 16 \
-k 0,1,2,6,7,8,12,13,14,18,19,20,24,25,26 \
-t 8 -w 0 -p 0 -r 5 -v 1
Choosing flag values for qsimh
-k defines how the lattice will be split up. In the examples above, the
lattice has the structure below (cuts are denoted by the | symbol):
0 1 2 | 3 4 5
6 7 8 | 9 10 11
12 13 14 | 15 16 17
18 19 20 | 21 22 23
24 25 26 | 27 28 29
Deciding which cuts are optimal for a given circuit is computationally hard. However, splitting the grid into roughly equal parts with the fewest cuts possible (as is done for the lattice above) produces a circuit that performs reasonably well in most cases.
The runtime of an execution is heavily influenced by -p, as there is no summation over the "prefix" gates. The unique "prefix" path is specified by -w; see the "Distributed execution" section below for details on this.
-r implicitly specifies the number of the "suffix" gates: the total number of gates on the cut minus the values specified by -p and -r. For performance, the "suffix" gates should typically be the gates on the cut with maximum "time".
qsimh_amplitudes usage
./qsimh_amplitudes.x -c circuit_file \
-d maxtime \
-k part1_qubits \
-w prefix \
-p num_prefix_gates \
-r num_root_gates \
-i input_file -o output_file \
-t num_threads -v verbosity -z
| Flag | Description |
|---|---|
-c circuit_file |
circuit file to run |
-d maxtime |
maximum time |
-k part1_qubits |
comma-separated list of qubit indices for part 1 |
-w prefix |
prefix value |
-p num_prefix_gates |
number of prefix gates |
-r num_root_gates |
number of root gates |
-i input_file |
bitstring input file |
-o output_file |
amplitude output file |
-t num_threads |
number of threads to use |
-v verbosity |
verbosity level (0,1,4,5) |
-z |
set flush-to-zero and denormals-are-zeros MXCSR control flags |
qsimh_amplitudes reads the input file of bitstrings, computes the corresponding amplitudes and writes them to the output file. The hybrid Schrödinger-Feynman method is used, see above.
Bitstring files should contain bitstrings (one bitstring per line) in text format.
Example (do not execute - see below):
./qsimh_amplitudes.x -c ../circuits/circuit_q40 -d 47 -k 0,1,2,3,4,5,6,7,8,9,10,13,14,15,16,17,23,24 -t 8 -w 0 -p 0 -r 13 -i ../circuits/bitstrings_q40_s1 -o ampl_q40_s1 -v 1
This command could take weeks to run, since parallelism on a single machine is limited by the -t flag and the available cores on the device. For large circuits like this, distributed execution is recommended.
Distributed execution
By setting -p to be greater than zero, the workload of qsimh_amplitudes can be
distributed across multiple machines. Each machine should use the same
arguments to ./qsimh_amplitudes.x, with the exception of the -w flag, which specifies the path that machine will evaluate.
Example:
# Machine 1
./qsimh_amplitudes.x -c ../circuits/circuit_q40 -d 47 -k 0,1,2,3,4,5,6,7,8,9,10,13,14,15,16,17,23,24 -t 8 -w 0 -p 9 -r 4 -i ../circuits/bitstrings_q40_s1 -o ampl_q40_s1_w0 -v 1
# Machine 2
./qsimh_amplitudes.x -c ../circuits/circuit_q40 -d 47 -k 0,1,2,3,4,5,6,7,8,9,10,13,14,15,16,17,23,24 -t 8 -w 1 -p 9 -r 4 -i ../circuits/bitstrings_q40_s1 -o ampl_q40_s1_w1 -v 1
# ...additional executions...
Each execution above computes a portion of the overall amplitude for the specified bitstrings. Summing across these results will give the final amplitudes, with fidelity dependent on the number of paths executed.