Skip to content
This repository has been archived by the owner on Jan 23, 2023. It is now read-only.

Advanced Project Features

Jump to bottom
Marc Davis edited this page Apr 30, 2020 · 17 revisions

Projects have can be given values for various options to adjust settings such as the search type or gateset.

import search_compiler as sc
myproject = sc.Project("myproject")
myproject["option"] = value

In addition, the Project class has a few management functions.

Project Options

You can configure options that the compiler used by a project using myproject["config_key"] = config_value. The supported keys are described here.

  • threshold is a float that defines the termination condition of the compilation. The compiler will return when it finds a circuit with a error_func value less than this threshold. The default value is 1e-10.
  • gateset is a sc.gatesets.Gateset object that is used by the compiler. The default value is sc.gatesets.QubitCNOTLinear().
  • error_func is a distance function that compares two numpy.matrix objects. It must return float values that greater than or equal to zero such that input matrices that are close to the same will result in outputs close to zero. The default value is sc.utils.matrix_distance_squared.
  • error_jac is a function that returns a tuple of the output from error_func and the Jacobian of that function. It is used by solvers that can take advantage of the Jacobian. If it is not provided, an appropriate value will be chosen based on error_func if possible.
  • eval_func is a function of the same type as error_func, and is used by the search algorithm to decide which paths to follow and also to decide when a solution is found. It is usually identical to error_func, but may be different in certain cases such as when using LeastSquares. If not provided, an appropriate value will be chosen based on error_func.
  • search_type is a string that can be set to "breadth" to perform a breadth-first search, or "greedy" to perform a greedy search using only error_func. When set to any other value, including the default, A* search is performed using heuristic.
  • heuristic is a function that takes a value from error_func and a search depth, and returns a float. It is used to order the priority queue used for searching. Setting this option overrides search_type.
  • solver is a sc.solver.Solver object. It is used to set the numerical optimizer used to solve for circuit parameters. The default value is dynamically chosen based on the gateset and error_func. Details are given below.
  • beams can be sets the number of nodes popped off of the priority queue during each search layer. The default is -1. Setting a positive value will cause the compiler to examine multiple search paths in parallel, and may result in faster runtimes. Setting a negative value will have the compiler calculate a number of beams to maximize CPU utilization. Setting a value of 1 will use the fewest threads.
  • blas_threads is a number that is used to limit the number of threads that BLAS uses if threadpoolctl is installed. You may be able to achieve better performance by tweaking both beams and blas_threads. The default value is None, which does not change the system default blas_threads limit.
  • verbosity is a number that controls how much output is printed to stdout and logged to the log files inside the project folder. A value of 0 silences all output, a value of 1 produces a default level of output, and a value of 2 produces more detailed output. The default value is 1. See Logging for more information.

Project Output

Once you run your project, you will want to retrieve the results. Here are some functions to help with that.

compilations = myproject.compilations

Returns a list of compilation names, as specified when add_compilation is called.

structure, vector = myproject.get_result(name)

Returns the structure and vector objects representing the final solution circuit. See the "Return Values" section of Advanced Compiler Features for more information.

myproject.assemble(name, language, write_location)

Assembles the final solution circuit and outputs it as another format. See Assembling and Exporting for more information.

Project Management Functions

There are a few more features that the Project class provides that might be needed. You may need to remove or reset compilations.

myproject.remove_compilation("gate_name") # deletes all data relating to the specified gate and removes it from the project
myproject.reset() # deletes all in-progress or completed compilation data in the project. You may need this if you decide to tweak compiler parameters.
myproject.reset("gate_name") # deletes all in-progress or completed compilation data for the specified gate. You may need this if the compiler does not always find the same solution for your gate.
myproject.clear() # deletes all data from the project, putting it in the same state as a fresh project.

You can also get output in the form of search_compiler.circuits.QuantumStep objects. More detail on how to use these objects below.

# circuit is a QuantumStep object, and vector is a numpy array of floats, to be used by certain QuantumStep functions
circuit, vector = myproject.get_result("gate_name")

# U is the numpy ndarray that was specified as the target unitary when adding this gate
U = myproject.get_target("gate_name")

# time is the numer of seconds it took to compile the gate, or None if the gate has not finished compiling.=
time = myproject.get_time("gate_name")

You can use

myproject.status() # to check the overall status of a project
myproject.status(name) # to check the status of a specific circuit in a project

A note on accessing the same Project from multiple processes

You can access a project from a separate process while it is running in another process. You can use project.status() from the second process in order to check on the status of a project without stopping it. If you change project settings or add or remove compilations while it is running in another process, changes will not take effect until that process is stopped and restarted. It is not recommended to attempt to run a project from two processes at the same time.

Solver Dynamic Default Behavior

If no solver is provided, a Project will choose a solver dynamically based on the provided gateset and error_func, based on the following rules. If error_func is matrix_distance_squared and the gateset is one of the provided gatesets consisting of CNOT and single qubit gates, LeastSquares_Jac_Solver will be used. Otherwise, if the gateset has implementations of the jacobian, BFGS_Jac_Solver will be used. Otherwise, COBYLA_Solver will be used. The default settings of these parameters will cause LeastSquares_Jac_Solver to be chosen. Additionally, if the Native Gateset is installed and compatible with the given gateset, it will be used.

Clone this wiki locally