Merge pull request #12 from zapatacomputing/zqs-1011-2

Zqs 1011 2

README.md

@@ -1,11 +1,52 @@
-# orquestra-python-template
-This is a template repository for Orquestra Python projects.
+# orquestra-vqa
 
-After creating repository from this template, make sure to follow the steps below:
+## What is it?
 
-1. Specify license. Supply LICENSE file and fill license entry in `setup.cfg` accordingly.
-2. Update `setup.cfg`. At the very least update the following fields:
-   - `[metadata]` section: `name`, `description`, `license`, `license_file`, 
-   - `install_requires` in `[options]` section. You don't have to do this at the very beginning and you may add requirements as you go, but be warry that the ones present in this repository are only example ones and may not be applicable to your project.
-3. Substitute an example `orquestra.pythontemplate` package `src/` directory with your actual code. Remember, that `orquestra` is a namespace package, so you *cannot* put an `__init__.py` in `src/orquestra` directory. Remove tests for the dummy package and replace them with meaningful ones as you develop your package.
-4. Remove this instruction and replace it with a meaningful description of your package.
+`orquestra-vqa` is a library with core functionalities for implementing variational quantum algorithms developed by [Zapata](https://www.zapatacomputing.com) for our [Orquestra](https://www.zapatacomputing.com/orquestra/) platform.
+
+`orquestra-vqa` provides:
+
+- interfaces for implementing ansatzes including qaoa and qcbm.
+- optimizers and cost functions tailored to vqa
+- misc functions such as grouping, qaoa interpolation, and estimators
+
+## Installation
+
+Even though it's intended to be used with Orquestra, `orquestra-quantum` can be also used as a Python module.
+To install it, make to install its dependencies: `orquestra-quantum` and `orquestra-opt`. Then you just need to run `pip install .` from the main directory.
+
+## Usage
+
+Here's an example of how to use methods from `orquestra-vqa` to create a cost function for qcbm and optimize it using scipy optimizer.
+
+```python
+from orquestra.vqa.cost_function.qcbm_cost_function import create_QCBM_cost_function
+from orquestra.vqa.ansatz.qcbm import QCBMAnsatz
+from orquestra.opt.history.recorder import recorder
+from orquestra.quantum.symbolic_simulator import SymbolicSimulator
+
+
+def orquestra_vqa_example_function()
+    ansatz = QCBMAnsatz(1, 4, "all")
+    backend = SymbolicSimulator()
+    distance_measure_kwargs = {
+                "distance_measure": compute_mmd,
+                "distance_measure_parameters": {"sigma": 1},
+            }
+    cost_function = create_QCBM_cost_function(
+        ansatz,
+        backend,
+        10,
+        **distance_measure_kwargs,
+    )
+
+    optimizer = ScipyOptimizer(method="L-BFGS-B")
+    initial_params = np.ones(ansatz.number_of_params) / 5
+    opt_results = optimizer.minimize(cost_function, initial_params)
+
+    return opt_results
+```
+
+## Development and Contribution
+
+You can find the development guidelines in the [`orquestra-quantum` repository](https://github.com/zapatacomputing/orquestra-quantum).

src/orquestra/vqa/ansatz/qcbm/_qcbm.py

@@ -335,7 +335,7 @@ def save_qcbm_ansatz_set(qcbm_ansatz_set: List[QCBMAnsatz], filename: str) -> No
 
 
 def load_qcbm_ansatz_set(file: str) -> List[QCBMAnsatz]:
-    """Load a list of qcbm_ansatz from a json file using a schema.
+    """Load a list of qcbm_ansatz from a json file.
 
     Arguments:
         file (str): the name of the file

src/orquestra/vqa/cost_function/cost_function.py

@@ -312,7 +312,7 @@ def _tasks_factory(parameters: np.ndarray) -> List[EstimationTask]:
         # TODO: In some ansatzes, `ansatz._generate_circuit(parameters)` does not
         # produce an executable circuit, but rather, they ignore the parameters and
         # returns a parametrized circuit with sympy symbols.
-        # (Ex. see ansatzes in z-quantum-qaoa)
+        # (Ex. see ansatzes in orquestra-vqa)
         #
         # Combined with how this is a private method, we will probably have to somewhat
         # refactor the ansatz class.

src/orquestra/vqa/cost_function/qcbm_cost_function.py

@@ -40,7 +40,7 @@ def create_QCBM_cost_function(
         target_bitstring_distribution: bistring distribution which QCBM aims to learn
         gradient_function: a function which returns a function used to compute
             the gradient of the cost function
-            (see zquantum.core.gradients.finite_differences_gradient for reference)
+            (see orquestra.opt.gradients.finite_differences_gradient for reference)
     Returns:
         Callable CostFunction object that evaluates the parametrized circuit produced
         by the ansatz with the given parameters and returns the distance between