Documentation structure

docs/Constraints.rst

@@ -1,2 +1,44 @@
 Constraints Class
 =================
+
+It manages the constraints of the problem. It is used to store the constraints and to check if a solution satisfies them.
+
+Constraints types supported
+---------------------------
+
+Types of constraints supported:
+
+- *Equality*, writing the equality as a quadratic penalty function, i.e. sum = b imposed with g = (sum-b)^2
+- *Inequality*, moving to equality with the continuous auxiliary variables a to be expanded with the encoding technique of the Variables class
+- *Not constraint* among binary variables, i.e. Not(a) = b imposed with g = 2ab - a - b + 1
+- *And constraint* among binary variables, i.e.  a and b = c imposed with  ab -2(a+b)c + 3c
+- *Or constraint* among binary variables, i.e. a or b = c imposed with ab + (a+b)(1-2c) + c
+- *Xor constraint* among binary variables, i.e. a xor b = c imposed with 2ab - 2(a+b)c - 4(a+b)\_aux+4_aux c +a+b+c+4+\_aux
+
+Constraints declarations
+----------------------
+
+The class provides methods to declare variables:
+
+- *add_constraint(expression: str, hard: bool = True, variable_precision: bool = True)*: adds a constraint to the list of constraints.
+    - *expression* is a string that represents the constraint
+    - *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:
+
+.. code-block:: python
+
+    from mqt.qao.constraints import Constraints
+    from mqt.qao.variables import Variables
+
+    constraint = Constraints()
+    variables = Variables()
+    variables.add_binary_variable("a")
+    variables.add_binary_variable("b")
+    variables.add_binary_variable("c")
+    variables.add_discrete_variable("d", [-1, 1, 3])
+    variables.add_continuous_variable("e", -2, 2, 0.25, "", "")
+    constraint.add_constraint("~a = b", True, True, False)
+    constraint.add_constraint("a | b = c", True, True, False)
+    constraint.add_constraint("d + e <= 1", True, True, False)

docs/ObjectiveFunction.rst

@@ -1,2 +1,28 @@
 ObjectiveFunction Class
 =======================
+
+It manages the objective functions of the optimization problem. it permits to specify the weights of the objectives in case of multi-objective optimization and the optimization directions. Since the variables can be declared in array form, matrix expressions for the objective functions are supported.
+
+Objective functions declarations
+--------------------------------
+
+The class provides methods to declare variables:
+
+- *add_objective_function(objective_function: Expr, minimization: bool = True, weight: float = 1)* : add an objective function to the optimization problem.
+    - *objective_function* is an expression of the variables of the optimization problem.
+    - *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.
+
+.. code-block:: python
+
+    from mqt.qao.constraints import Constraints
+    from mqt.qao.variables import Variables
+    from mqt.qao.objectivefunction import ObjectiveFunction
+
+    variables = Variables()
+    constraint = Constraints()
+    a0 = variables.add_binary_variable("a")
+    b0 = variables.add_discrete_variable("b", [-1, 1, 3])
+    c0 = variables.add_continuous_variable("c", -2, 2, 0.25, "", "")
+    objective_function = ObjectiveFunction()
+    objective_function.add_objective_function(a0 + b0 * c0 + c0**2)

docs/Problem.rst

@@ -1,2 +1,46 @@
 Problem Class
 =============
+
+It may be useful to have a class that represents a problem. It includes the variables, constraints and objective function. This class can be used for constructing the quantum-compliant cost function.
+
+Problem declarations
+--------------------
+
+The class provides a  method for declaring the problem:
+
+- *create_problem(var: Variables, constraint: Constraints, objective_functions: ObjectiveFunction)* : This method is used to declare the problem.
+    - *variables* instances of the Variables class
+    - *constraints* instances of the Constraints class
+    - *objective_functions* instances of the ObjectiveFunction class.
+
+and a method for obtaining the HUBO or PUBO formulation of the problem as qubovert PUBO object:
+
+- * write_the_final_cost_function( lambda_strategy: str, lambda_value: float = 1)* : This method is used to obtain the HUBO or PUBO formulation of the problem as qubovert PUBO object. The method takes two arguments:
+    - *lambda_strategy* The strategy to be used for the conversion of the problem to HUBO or PUBO. The possible values are:
+        - 'upper_bound_only_positive'
+        - 'maximum_coefficient'
+        - 'VLM'
+        - 'MOC'
+        - 'MOMC'
+        - 'upper lower bound naive'
+        - 'upper lower bound posiform and negaform method'
+        - 'manual'
+    - *lambda_value*  The value of the lambda parameter if the use want to manually select it. The default value is 1.0.
+
+.. code-block:: python
+
+    from mqt.qao.constraints import Constraints
+    from mqt.qao.variables import Variables
+    from mqt.qao.objectivefunction import ObjectiveFunction
+
+    variables = Variables()
+    constraint = Constraints()
+    a0 = variables.add_binary_variable("a")
+    b0 = variables.add_discrete_variable("b", [-1, 1, 3])
+    c0 = variables.add_continuous_variable("c", -2, 2, 0.25, "", "")
+    constraint.add_constraint("c >= 1", True, True, False)
+    objective_function = ObjectiveFunction()
+    objective_function.add_objective_function(a0 + b0 * c0 + c0**2)
+    problem = Problem()
+    problem.create_problem(variables, constraint, objective_function)
+    pubo = problem.write_the_final_cost_function(lambda_strategy)

docs/Solver.rst

@@ -1,2 +1,54 @@
 Solver Class
 ============
+
+It interface the problems with the quantum solvers.
+
+Supported solvers
+-----------------
+
+The framework currently supports the following solvers:ù
+
+- D-Wave quantum annealer
+- D-Wave simulated annealer
+- qiskit Quantum Approximate Optimization Algorithm (QAOA)
+- qiskit Variational Quantum Eigensolver (VQE)
+- qiskit Grover Adaptive Search (GAS)
+
+Solver Selection and Configuration
+----------------------------------
+
+The class provides for exploiting the solver:
+
+- *solve_simulated_annealing(
+        problem: Problem,
+        auto_setting: bool = False,
+        beta_range: list[float] | None = None,
+        num_reads: int = 100,
+        annealing_time: int = 100,
+        num_sweeps_per_beta: int = 1,
+        beta_schedule_type: str = "geometric",
+        seed: int | None = None,
+        initial_states: SampleSet | None = None,
+        initial_states_generator: str = "random",
+        max_lambda_update: int = 5,
+        lambda_update_mechanism: str = "sequential penalty increase",
+        lambda_strategy: str = "upper lower bound posiform and negaform method",
+        lambda_value: float = 1.0,
+        save_time: bool = False,
+    )* : Solve the problem using the simulated annealer. The parameters are:
+    - *problem*: the problem to solve
+    - *auto_setting*: if True, the parameters are automatically set
+    - *beta_range*: the range of beta values to use
+    - *num_reads*: the number of reads
+    - *annealing_time*: the annealing time
+    - *num_sweeps_per_beta*: the number of sweeps per beta
+    - *beta_schedule_type*: the beta schedule type
+    - *seed*: the seed
+    - *initial_states*: the initial states
+    - *initial_states_generator*: the initial states generator
+    - *max_lambda_update*: the maximum lambda update if the constraints are not satisfied
+    - *lambda_update_mechanism*: the lambda update mechanism among:
+        - *sequential penalty increase*
+        - *scaled sequential penalty increase*
+        - *binary search penalty algorithm*
+