Initialize

doc/source/getting-started/index.rst

@@ -0,0 +1,12 @@
+Getting started
+===============
+
+
+In this section we present the basic aspects of the Qibotn design and provide installation instructions.
+Please visit the following sections to understand how ``qibotn`` works.
+
+.. toctree::
+    :maxdepth: 1
+
+    installation
+    quickstart

doc/source/getting-started/installation.rst

@@ -0,0 +1,10 @@
+Installation instructions
+=========================
+
+QiboTN can be installed directly from the source repository on Github:
+
+.. code-block::
+
+    git clone https://github.com/qiboteam/qibotn.git
+    cd qibotn
+    poetry install

doc/source/getting-started/quickstart.rst

@@ -0,0 +1,138 @@
+Quick start
+===========
+
+In this section, we provide examples on how to use Qibotn to execute tensor network
+simulation of quantum circuit. First, we show how to use the Cutensornet and Quimb
+backends, while in a second moment we show a complete example of usage of the Quantum
+Matcha Tea Backend.
+
+Setting the backend with Cutensornet and Quimb
+""""""""""""""""""""""""""""""""""""""""""""""
+
+Among the backends provided by Qibotn, we have cutensornet (using cuQuantum library)
+and qutensornet (using Quimb library) for tensor network based simulations.
+At present, cutensornet backend works only for GPUs whereas qutensornet for CPUs.
+These backend can be set using the following command line.
+
+To use cuQuantum library, cutensornet can be specified as follows::
+
+   qibo.set_backend(
+      backend="qibotn", platform="cutensornet", runcard=computation_settings
+   )
+
+Similarly, to use Quimb library, qutensornet can be set as follows::
+
+   qibo.set_backend(
+       backend="qibotn", platform="qutensornet", runcard=computation_settings
+   )
+
+Setting the runcard
+"""""""""""""""""""
+
+The basic structure of the runcard is as follows::
+
+   computation_settings = {
+       "MPI_enabled": False,
+       "MPS_enabled": False,
+       "NCCL_enabled": False,
+       "expectation_enabled": {
+           "pauli_string_pattern": "IXZ",
+       },
+   }
+
+
+**MPI_enabled:** Setting this option *True* results in parallel execution of circuit using MPI (Message Passing Interface). At present, only works for cutensornet platform.
+
+**MPS_enabled:** This option is set *True* for Matrix Product State (MPS) based calculations where as general tensor network structure is used for *False* value.
+
+**NCCL_enabled:** This is set *True* for cutensoret interface for further acceleration while using Nvidia Collective Communication Library (NCCL).
+
+**expectation_enabled:** This option is set *True* while calculating expecation value of the circuit. Observable whose expectation value is to be calculated is passed as a string in the dict format as {"pauli_string_pattern": "observable"}. When the option is set *False*, the dense vector state of the circuit is calculated.
+
+
+Basic example
+"""""""""""""
+
+The following is a basic example to execute a two qubit circuit and print the final state in dense vector form using quimb backend::
+
+   import qibo
+   from qibo import Circuit, gates
+
+   # Set the runcard
+   computation_settings = {
+       "MPI_enabled": False,
+       "MPS_enabled": False,
+       "NCCL_enabled": False,
+       "expectation_enabled": False,
+   }
+
+
+   # Set the quimb backend
+   qibo.set_backend(
+       backend="qibotn", platform="qutensornet", runcard=computation_settings
+   )
+
+
+   # Construct the circuit with two qubits
+   c = Circuit(2)
+
+   # Apply Hadamard gates on first and second qubit
+   c.add(gates.H(0))
+   c.add(gates.H(1))
+
+   # Execute the circuit and obtain the final state
+   result = c()
+
+   # Print the final state
+   print(result.state())
+
+
+Using the Quantum Matcha Tea backend
+""""""""""""""""""""""""""""""""""""
+
+In the following we show an example of how the Quantum Matcha Tea backend can be
+used to execute a quantum circuit::
+
+    # We need Qibo to setup the circuit and the backend
+    from qibo import Circuit, gates
+    from qibo.models.encodings import ghz_state
+    from qibo.backends import construct_backend
+
+    # We need Quantum Matcha Tea to customize the tensor network simulation
+    from qmatchatea import QCConvergenceParameters
+
+    # Set the number of qubits
+    nqubits = 40
+
+    # Construct a circuit preparing a Quantum Fourier Transform
+    circuit = ghz_state(nqubits)
+
+    # Construct the backend
+    backend = construct_backend(backend="qibotn", platform="qmatchatea")
+
+    # Customize the low-level backend preferences according to Qibo's formalism
+    backend.set_device("/CPU:1")
+    backend.set_precision("double")
+
+    # Customize the tensor network simulation itself
+    backend.configure_tn_simulation(
+        ansatz = "MPS",
+        convergence_params = QCConvergenceParameters(max_bond_dimension=50, cut_ratio=1e-6)
+    )
+
+    # Execute the tensor network simulation
+    outcome = backend.execute_circuit(
+        circuit = circuit,
+        nshots=1024,
+    )
+
+    # Print some results
+    print(outcome.probabilities())
+    # Should print something like: {'0000000000000000000000000000000000000000': 0.5000000000000001, '1111111111111111111111111111111111111111': 0.5000000000000001}
+    print(outcome.frequencies())
+    # Should print something like: {'0000000000000000000000000000000000000000': 488, '1111111111111111111111111111111111111111': 536}
+
+
+By default, the simulator is choosing a specific method to compute the probabilities,
+and for further information we recommend the user to refer to our High-Level-API
+docstrings: :doc:`/api-reference/qibotn.backends`.