Skip to content

Commit

Permalink
Documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
DeborahVolpe committed Jun 5, 2024
1 parent be3a775 commit c5f069d
Show file tree
Hide file tree
Showing 7 changed files with 353 additions and 6 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@

# MQT Quantum Auto Optimizer: Automatic Framework for Solving Optimization Problems with Quantum Computers

MQT Quantum Auto Optimizer is a framework that allows one to automatically translate an optimization problem into a quantum-compliant formulation and to solve it with one of the main quantum solvers (Quantum Annelar, QAOA, VQE and GAS)
MQT Quantum Auto Optimizer is a framework that allows one to automatically translate an optimization problem into a quantum-compliant formulation and to solve it with one of the main quantum solvers (Quantum Annealar, Quantum Approximate Optimization Algorithm, Variational Quantum Eigensolver and Grover Adaptive Search)

MQT Quantum Auto Optimizer is part of the [Munich Quantum Toolkit (MQT)](https://mqt.readthedocs.io/) developed by the [Chair for Design Automation](https://www.cda.cit.tum.de/) at the [Technical University of Munich](https://www.tum.de/). This framework has been developed in collaboration with the [VLSI Lab](https://www.vlsilab.polito.it/) of [Politecnico di Torino](https://www.polito.it).

Expand Down
3 changes: 2 additions & 1 deletion docs/Constraints.rst
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@ The class provides methods to declare variables:
- *hard* parameter is a boolean that indicates if the constraint is hard or soft.
- *variable_precision* parameter is a boolean that indicates if the constraint is to be considered in the precision of the variables.

Examples:
Example:
--------

.. code-block:: python
Expand Down
3 changes: 3 additions & 0 deletions docs/ObjectiveFunction.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ The class provides methods to declare variables:
- *minimization* parameter specifies if the objective function is to be minimized or maximized (optimization direction).
- *weight* parameter is the weight of the objective function in case of multi-objective optimization.

Example:
--------

.. code-block:: python
from mqt.qao.constraints import Constraints
Expand Down
3 changes: 3 additions & 0 deletions docs/Problem.rst
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,9 @@ and a method for obtaining the HUBO or PUBO formulation of the problem as qubove
- 'manual'
- *lambda_value* The value of the lambda parameter if the use want to manually select it. The default value is 1.0.

Example:
--------

.. code-block:: python
from mqt.qao.constraints import Constraints
Expand Down
80 changes: 80 additions & 0 deletions docs/Solution.rst
Original file line number Diff line number Diff line change
@@ -1,2 +1,82 @@
Solution Class
==============

It is a class that is used to store all the information about the solution of the problem.

Solution Attributes
-------------------

The class has the following attributes:

- energies: list[float], i.e. the list of energies of the solution obtained in each run
- best_energy, i.e. the lowest energy obtained in all the runs
- best_solution: dict[str, Any], i.e. the best solution obtained in all the runs in binary variables
- best_solution_original_var: dict[str, Any], i.e. the best solution obtained in all the runs in variables originally declared
- solutions_original_var: list[dict[str, Any]], i.e. the list of solutions obtained in each run in variables originally declared
- solutions: list[dict[str, Any]], i.e. the list of solutions obtained in each run in binary variables
- time: float: the time taken to solve the problem
- solver_info: dict[str, Any], i.e. the information about the solver setting to solve the problem


Solution Methods
----------------

The class has the following methods for helping users in analyzing the solution:

- *optimal_solution_cost_functions_values()*: This method is used to get the cost functions values of the best solution obtained in all the runs
- *check_constraint_optimal_solution()*: This method is used to check if the best solution obtained in all the runs satisfies the constraints
- *check_constraint_all_solutions()*: This method is used to check if all the solutions obtained in all the runs satisfy the constraints
- *show_cumulative(save: bool = False, show: bool = True, filename: str = "", label: str = "", latex: bool = False)* : This method is used to show the cumulative plot of the energies obtained in all the runs. The parameters are:
- save: bool, i.e. whether to save the plot or not in a file
- show: bool, i.e. whether to show the plot or not
- filename: str, i.e. the name of the file where the plot will be saved
- label: str, i.e. the label of the plot
- latex: bool, i.e. whether to show the plot in latex format or not
- *valid_solutions(weak: bool = True)*: This method is used to get the rate of valid solutions obtained in all the runs. The parameters are:
- weak: bool, i.e. whether to consider in the evaluation the weak constraints
- *p_range(ref_value: float | None = None)*: This method is used to get the p-range of the best solution obtained in all the runs, which is the probability of obtaining a final energy lower than a certain value. The parameters are:
- ref_value: float | None, i.e. the reference value to calculate the p-value
- *tts(ref_value: float | None = None, target_probability: float = 0.99)*: This method is used to get the time-to-solution of the best solution obtained in all the runs, which is the time required to obtain a solution with a certain probability. The parameters are:
- ref_value: float | None, i.e. the reference value to calculate the p-range
- target_probability: float, i.e. the target probability to calculate the time-to-solution
-*wring_json_reports(filename: str = "report", weak: bool = False, ref_value: float | None = None, target_probability: float = 0.99, problem_features: bool = False)* : This method is used to write the reports in json format. The parameters are:
- filename: str, i.e. the name of the file where the report will be saved
- weak: bool, i.e. whether to consider in the evaluation the weak constraints
- ref_value: float | None, i.e. the reference value to calculate the p-range
- target_probability: float, i.e. the target probability to calculate the time-to-solution
- problem_features: bool, i.e. whether to show the problem features in the report or not


Examples:
---------

.. code-block:: python
from mqt.qao.constraints import Constraints
from mqt.qao.variables import Variables
from mqt.qao.objectivefunction import ObjectiveFunction
from mqt.qao.problem import Problem
from mqt.qao.solver import Solver
variables = Variables()
m1 = variables.add_continuous_variables_array("M1", [1, 2], -1, 2, -1, "uniform", "logarithmic 2")
m2 = variables.add_continuous_variables_array("M2", [2, 1], -1, 2, -1, "uniform", "logarithmic 2")
objective_function = ObjectiveFunction()
objective_function.add_objective_function(np.matmul(m1, m2).item(0, 0))
constraint = Constraints()
constraint.add_constraint(constraint_expr, variable_precision=True)
problem = Problem()
problem.create_problem(variables, constraint, objective_function)
solver = Solver()
solution = solver.solve_simulated_annealing(
problem, max_lambda_update=max_lambda_update, lambda_update_mechanism=lambda_update, lambda_strategy=lambda_strategy
)
print(solution.optimal_solution_cost_functions_values())
print(solution.check_constraint_optimal_solution())
print(solution.check_constraint_all_solutions())
solution.show_cumulative()
print(solution.valid_solutions())
print(solution.p_range())
print(solution.tts())
solution.wring_json_reports()
Loading

0 comments on commit c5f069d

Please sign in to comment.