updated but not finished readme

README

@@ -1 +0,0 @@
-# QElephant

README.md

@@ -0,0 +1,106 @@
+# QElephant
+
+QElephant is a small library without pretention. It simulates the behavior of a quantum computer. The syntaxe is simple and can be used in any code in Python.
+
+## Installation
+You can install the latest version of QElephant with :
+
+```
+pip install QElephant
+```
+
+## Dependencies
+
+In order to work, QElephant is using the following libraries:
+- `math`
+- `random`
+
+They are automatically managed when installing QElephant.
+
+## Contains
+This library contains two main object : `QuBit` and `Matrix`.
+
+### QuBit
+This is the specificity of a quantum algorithm: using QuBit which can have two states: `|0>` and `|1>`. To create one, simply use:
+
+```
+q = QuBit(alpha, beta)
+```
+$\alpha$ and $\beta$ are optional complex arguments. When specified, initiate the QuBit in the state $\alpha$ |0> + $\beta$ |1>.
+
+> [!IMPORTANT]
+> Because the value of $\alpha$ and $\beta$ gives the probability of each states, it is essential that $|\alpha|²+|\beta|²=1$. On the other case, the QuBit cannot be created.
+
+To simulate intricated QuBit, `MuBit` are used. As for `QuBit`, they are initalized like this:
+
+```
+mq = MuBit(n)
+q = mq[0]
+```
+
+`n` gives the number of intricated QuBit. When created, a MuBit is in the state with only zeros.
+
+`mq[0]` returns a QuBit, here the first one, wich can be manipulated. Because of the intrication, manipulating a intricated QuBit implies that other QuBits are manipulated too.
+
+### Matrix
+`Matrix` are used to manipulate the state of the QuBit. For example, the QuBit 
+
+$\alpha$ |0> + $\beta$ |1> 
+
+is represented by 
+
+$\begin{pmatrix}
+\alpha\\
+\beta
+\end{pmatrix}$
+
+So, the operation corresponding of the inversion of the value of $\alpha$ and $\beta$ is
+
+$\begin{pmatrix}
+0 & 1\\
+1 & 0
+\end{pmatrix}
+\times
+\begin{pmatrix}
+\alpha\\
+\beta
+\end{pmatrix}
+=\begin{pmatrix}
+\beta\\
+\alpha
+\end{pmatrix}$
+
+In theory, the users don't need to use them, the main quantum gates are already implemented.
+
+### Quantum Gate
+
+The quantum gates are the different operations applying to the QuBits. The one behind is the gate `X`. It is simply used like any function:
+
+```
+# a QuBit is created
+q = QuBit() 
+
+# the values of the QuBit are inverted
+X(q)
+
+# q is now in the state 0 |0> + 1 |1>
+```
+
+the complete list can be find in the [docs](docs).
+
+Some gates need a `MuBit` in entry. This is the case for the controlled gate. In such a case, multiple QuBit are manipulated at the same time. The following QuBit must be specified:
+
+```
+mq = Mubit(2)
+# in the state |00>
+
+X(mq[0])
+# now in the state |10>
+
+SWAP(mq, 0, 1)
+# the two first quibit are inverted, mq is finally in the state |01>
+```
+
+## Docs
+
+A doc is availaibale [here](docs) where all objects and gates are displayed.

docs/Gate.md

@@ -0,0 +1,136 @@
+# Gates
+
+Here is the list of all the main gates in quantum algorithm available in the library. In the following formulas, `i` represents the complex number.
+
+## H(q: QuBit) -> None
+`Hadamard's gate`. 
+
+- q: the qubit manipulated by the gate. This function is in-place.
+
+- matrix: $\begin{pmatrix}
+\frac {1} {\sqrt 2} & \frac {1} {\sqrt 2}\\
+\frac {1} {\sqrt 2} & -\frac {1} {\sqrt 2}
+\end{pmatrix}$
+
+## X(q: QuBit) -> None
+`Pauli-X gate` or `NOT gate`. Inplementes a rotation aroud the x-axis of $\pi$ radians.
+
+- q: the qubit manipulated by the gate. This function is in-place.
+
+- matrix: $\begin{pmatrix}
+0 & 1\\
+1 & 0
+\end{pmatrix}$
+
+## Y(q: QuBit) -> None
+`Pauli-Y gate`. Inplementes a rotation aroud the y-axis of $\pi$ radians.
+
+- q: the qubit manipulated by the gate. This function is in-place.
+
+- matrix: $\begin{pmatrix}
+0 & -i\\
+i & 0
+\end{pmatrix}$
+
+## Z(q: QuBit) -> None
+`Pauli-Z gate`. Inplementes a rotation aroud z-axis of $\pi$ radians.
+
+- q: the qubit manipulated by the gate. This function is in-place.
+
+- matrix: $\begin{pmatrix}
+1 & 0\\
+0 & -1
+\end{pmatrix}$
+
+## S(q: QuBit) -> None
+`NOT gate`. Invert the state |0> and |1> of the QuiBit q.
+
+- q: the qubit manipulated by the gate. This function is in-place.
+
+- matrix: $\begin{pmatrix}
+1 & 0\\
+0 & i
+\end{pmatrix}$
+
+## T(q: QuBit) -> None
+`NOT gate`. Invert the state |0> and |1> of the QuiBit q.
+
+- q: the qubit manipulated by the gate. This function is in-place.
+
+- matrix: $\begin{pmatrix}
+1 & 0\\
+0 & e^{i\frac\pi4}
+\end{pmatrix}$
+
+## Rx(q: QuBit, phi: float) -> None
+`NOT gate`. Inplementes a rotation aroud x-axis of $\phi$ radians.
+
+- q: the qubit manipulated by the gate. This function is in-place.
+
+- matrix: $\begin{pmatrix}
+\cos(\frac\phi2) & -\sin(\frac\phi2)\\
+\sin(\frac\phi2) & \cos(\frac\phi2)
+\end{pmatrix}$
+
+## Ry(q: QuBit, phi: float) -> None
+`NOT gate`. Inplementes a rotation aroud y-axis of $\pi$ radians.
+
+- q: the qubit manipulated by the gate. This function is in-place.
+
+- matrix: $\begin{pmatrix}
+e^{-i\frac\phi2} & 0\\
+0 & e^{i\frac\phi2}
+\end{pmatrix}$
+
+## R1(q: QuBit, phi: float) -> None
+`NOT gate`. Invert the state |0> and |1> of the QuiBit q.
+
+- q: the qubit manipulated by the gate. This function is in-place.
+
+- matrix: $\begin{pmatrix}
+1 & 0\\
+0 & e^{i\frac\phi2}
+\end{pmatrix}$
+
+## CNOT(q: MuBit, n1: int, n2: int) -> None
+`X-controlled gate`. Invert the state |0> and |1> of the QuiBit in n2 if the state of the QuBit in n1 is 1.
+
+- q: the qubit manipulated by the gate. This function is in-place.
+- n1: the first QuBit to manipualte.
+- n2: the second QuBit to manipulate
+
+- matrix: $\begin{pmatrix}
+1 & 0 & 0 & 0\\
+0 & 1 & 0 & 0\\
+0 & 0 & 0 & 1\\
+0 & 0 & 1 & 0
+\end{pmatrix}$
+
+## SWAP(q: MuBit, n1: int, n2: int) -> None
+`NOT gate`. Invert the state |0> and |1> of the QuiBit q.
+
+- q: the qubit manipulated by the gate. This function is in-place.
+- n1: the first QuBit to manipualte.
+- n2: the second QuBit to manipulate
+
+- matrix: $\begin{pmatrix}
+1 & 0 & 0 & 0\\
+0 & 0 & 1 & 0\\
+0 & 1 & 0 & 0\\
+0 & 0 & 0 & 1
+\end{pmatrix}$
+
+## Cu(q: MuBit, u: list[list[float]], n1: int, n2: int) -> None
+`controlled-u gate`. Applies the gate u to the QuBit in n2 if the Qubit in n1 is 1.
+
+- q: the qubit manipulated by the gate. This function is in-place.
+- the list respresentation of a matrix of the size 2 by 2.
+- n1: the first QuBit to manipualte.
+- n2: the second QuBit to manipulate
+
+- matrix: $\begin{pmatrix}
+1 & 0 & 0 & 0\\
+0 & 1 & 0 & 0\\
+0 & 0 & u_{00} & u_{01}\\
+0 & 0 & u_{10} & u_{11}
+\end{pmatrix}$