Update readme (#14)

* Update README.md

* Update README.md

Adjust for recent changes to cfg options.

* Create tutorials

* Add tutorials folder and move GQE Usage into there along with blog example from @mawolf2023

* Move to examples folder.

* Rename co2_18qubits.py to gqe_co2_18q.py

* Update gqe_co2_18q.py

Author: poojarao8

Diff for: README.md

@@ -38,4 +38,3 @@ ninja
 export PYTHONPATH=$HOME/.cudaq:$PWD/python/cudaqlib
 ctest 
 ```
-

Diff for: examples/python/README.md

@@ -0,0 +1,44 @@
+# Welcome to the CUDA-Q Libraries repository
+
+## GQE Usage 
+GQE class usage: `gqe(cost, pool, config=None, **kwargs)` can take a `config` object and\or additional `**kwargs`
+
+The `config` object is of type `ConfigDict` imported from `ml_collections`.  
+
+Example usage:
+```
+from ml_collections import ConfigDict
+cfg = ConfigDict()
+cfg.seed = 3047
+```
+
+The available config options are provided in the table below:
+
+| **Parameter**          | **Default Value**   | **Description**   |
+|------------------------|---------------------|-------------------|
+| `cfg.num_samples`      | `5`                 | Number of circuits to generate during each epoch/batch |
+| `cfg.max_iters`        | `100`               | Number of epochs to run |
+| `cfg.ngates`           | `20`                | Number of gates that make up each generated circuit |
+| `cfg.seed`             | `3047`              | Random seed |
+| `cfg.lr`               | `5e-7`              | Learning rate used by the optimizer |
+| `cfg.energy_offset`    | `0.0`               | Offset added to expectation value of the cirucit (Energy) for numerical stability, see [K. Nakaji et al. (2024)](https://arxiv.org/abs/2401.09253) Sec. 3 |
+| `cfg.grad_norm_clip`   | `1.0`               | max_norm for clipping gradients, see [Ligthning docs](https://lightning.ai/docs/fabric/stable/api/fabric_methods.html#clip-gradients) |
+| `cfg.temperature`      | `5.0`               | Starting inverse temperature $\beta$ as described in [K. Nakaji et al. (2024)](https://arxiv.org/abs/2401.09253) Sec. 2.2 |
+| `cfg.del_temperature`  | `0.05`              | Temperature increase after each epoch |
+| `cfg.resid_pdrop`      | `0.0`               | The dropout probability for all fully connected layers in the embeddings, encoder, and pooler, see [GPT2Config](https://github.com/huggingface/transformers/blob/main/src/transformers/models/gpt2/configuration_gpt2.py) |
+| `cfg.embd_pdrop`       | `0.0`               | The dropout ratio for the embeddings, see [GPT2Config](https://github.com/huggingface/transformers/blob/main/src/transformers/models/gpt2/configuration_gpt2.py) |
+| `cfg.attn_pdrop`       | `0.0`               | The dropout ratio for the attention, see [GPT2Config](https://github.com/huggingface/transformers/blob/main/src/transformers/models/gpt2/configuration_gpt2.py) |
+| `cfg.small`            | `False`             | True: Uses a small transfomer (6 hidden layers and 6 attention heads as opposed to the default transformer of 12 of each) |
+| `cfg.save_dir`         | `"./output/"`       | Path to save files |
+
+The `**kwargs` takes the following args:
+| **arg**                | **Description**   |
+|------------------------|-------------------|
+| `model`                | Can pass in an already constructed transformer |
+| `optimizer`            | Can pass in an already constructed optimizer |
+
+In addition, `**kwargs` can be used to overwrite any of the default configs if you don't pass in a full config object, i.e:
+| **arg**                | **Description**   |
+|------------------------|-------------------|
+| `max_iters`            | Overrides cfg.max_iters for total number of epochs to run |
+| `energy_offset`        | Overrides cfg.energy_offset for offset to add to expectation value |

Diff for: examples/python/gqe_co2_18q.py

@@ -0,0 +1,59 @@
+import cudaq, cudaqlib
+
+# Define the molecule
+distance = 1.1621
+geometry = [('O', (0., 0., 0.)), ('C', (0., 0., distance)), ('O', (0., 0., 2*distance))]
+molecule = cudaqlib.operators.create_molecule(geometry, 'sto-3g', 0, 0, MP2=True, nele_cas=10, norb_cas=9)
+
+# Get the system Hamiltonian
+hamiltonian = molecule.hamiltonian
+
+# Get the number of qubits
+numQubits = molecule.hamiltonian.get_qubit_count()
+
+# Create the operator pool
+pool = cudaqlib.gse.get_operator_pool('uccsd',
+                                      num_qubits=numQubits,
+                                      num_electrons=10,
+                                      operator_coeffs=[0.003125, -0.003125, 0.00625, -0.00625, 0.0125, -0.0125, 0.025, -0.025, 0.05, -0.05, 0.1, -0.1])
+
+# Define Hartree-Fock
+@cudaq.kernel
+def init(q: cudaq.qview):
+    for i in range(10):
+        x(q[i])
+
+
+# Define the GQE cost function
+def cost(sampledPoolOperations: list):
+    """
+    Cost should take operator pool indices and
+    return the associated cost. For the chemistry
+    example, we'll take uccsd pool indices and return
+    cudaq observe result
+    """
+    # Convert the operator pool elements to cudaq.pauli_words
+    asWords = [
+        cudaq.pauli_word(op.to_string(False)) for op in sampledPoolOperations
+    ]
+
+    # Get the pool coefficients as its own list
+    operatorCoeffs = [op.get_coefficient().real for op in sampledPoolOperations]
+
+    @cudaq.kernel
+    def kernel(numQubits: int, coeffs: list[float],
+            words: list[cudaq.pauli_word]):
+        q = cudaq.qvector(numQubits)
+        init(q)
+        for i, word in enumerate(words):
+            exp_pauli(coeffs[i], q, word)
+
+    return cudaq.observe(kernel, molecule.hamiltonian, numQubits,
+                         operatorCoeffs, asWords).expectation()
+
+
+minE, optimPoolOps = cudaqlib.gqe(cost, pool, max_iters=10, energy_offset=184.)
+print(f'Ground Energy = {minE}')
+print('Ansatz Ops')
+for idx in optimPoolOps:
+    print(pool[idx].get_coefficient().real, pool[idx].to_string(False))