Advanced Compiler Features

Configuring Compiler Options Manually

The SearchCompiler class takes a few optional initializer options.

mycompiler = sc.SearchCompiler.init(threshold, error_func, error_jac, eval_func, heuristic, gateset, solver, beams, logger, verbosity)

Compiler Options

• threshold - a float which specifies the stopping condition for the synthesis. The first circuit for which the error_func returns a value less than the threshold will be returned as the solution. The default value is 1e-10.
• error_func - a function which takes two matrices and returns a float. Its value is used in guiding the numerical solver. The default value is sc.utils.matrix_distance_squared. Usually, its value is also used for eval_func. If eval_func is specified separately, error_func can behave differently, such as returning an array of residuals instead of a single value when using LeastSquares.
• error_jac - a function which takes two matrices, and returns a tuple of the float that would be returned by error_func, and the Jacobian of that function. It's value is used by solvers that can take advantage of the Jacobian, such as BFGS and LeastSquares. The default value is None, and if None is specified, an appropriate value will be chosen based on the value of error_func.
• eval_func - a function which takes two matrices and returns a float. While error_func is used to guide the numerical solver, eval_func is used to guide the search and decide when to return a solution. Its default value is None, and an appropriate value will be chosen at runtime. Specifically, it will be set to sc.utils.matrix_distance_squared if error_func is utils.matrix_residuals, and will be set to error_func otherwise. It is necessary to manually change this to use LeastSquares with a custom error_func.
• heuristic - a function which takes the value of error_func and the current search depth and returns a float. This value is used to guide the search. The default is sc.heuristics.astar. Heuristics for greedy search and breadth first search are also provided. It is recommended to switch to breadth first search if you are using a gateset with gates other than CNOT and single qubit gates.
• gateset - a sc.gatesets.Gateset object which describes the gateset used for synthesis. The default value is sc.gatesets.QubitCNOTLinear(), which is the recommended gateset for using CNOTs and single qubit gates with the linear topology.
• solver - a sc.solver.Solver object which performs numerical optimization. The default value is LeastSquares_Jac_Solver if gateset is one of the provided gatesets consisting of CNOT and single qubit gates, or COBYLA_Solver otherwise. If the Native Gateset is installed, it will be used if it is supported by the given gateset.
• beams - an integer which defines the number of nodes to expand at a time during each step. A negative value will result in a number of beams calculated to fully utilize the CPU threads visible to Python. The default value is -1.
• logger - an sc.logging.Logger object that the compiler will use for logging. The default value is None. See the wiki page for more information.
• verbosity - if logger is left as None, then a logger will be created that prints to stdout with the specified verbosity. The default value is 0. A value of 0 will silence all output, a value of 1 will produce a default level of output, and a value of 2 will produce more detailed output. See the wiki page for more information.

Compile Function Options

The compile function of the SearchCompiler class also can take two extra parameters:

circuit, vector = mycompiler.compile(U, depth, statefile, logger)

• U - the only required option, which is the unitary to be synthesized
• depth - an integer which serves as a depth limit. If a circuit is not found within this limit that satisfies the threshold condition, then the circuit with the lowest value of error_func will be returned. The default value of None will result in no depth limit being used, and the search will continue indefinitely until a circuit that meets the threshold requirement is found.
• statefile - a string that describes a file path that will be used to store the intermediate state of the compilation. If the compilation is interrupted, it can be resumed by making the same call again, and the state will be restored from the statefile. Without a statefile, compilataion will have to start from the beginning if compilation is interrupted.
• logger - a sc.logging.Logger object that can be used to override the logging settings provided on creating the SearchCompiler object. The default value is None, which causes the logger defined when creating the SearchCompiler` object to be used. See the wiki page for more information.

Return Values

The compile function of the SearchCompiler returns a tuple of two values:

circuit, vector = mycompiler.compile(U, depth, statefile, logger)

• circuit - This is a sc.circuits.QuantumStep object that contains the final solution circuit structure found by the compiler.
• vector - This is a numpy ndarray object containing the final solution parameters found by the compiler. These two return values together describe the final circuit, and can be used to generate the implemented matrix or export the circuit to other formats:

U = circuit.matrix(vector) # returns the unitary matrix implemented by the circuit
sc.assembler.assemble(circuit, vector, language, write_location) # assembles the circuit and exports to another format

See the wiki page on assembling and exporting for more details.