Metadata-Version: 2.1
Name: diracengine
Version: 0.0.11
Summary: The Dirac Quantum Engine
Home-page: UNKNOWN
Author: Nikola Kostadinov
Author-email: <nikolakostadinov@protonmail.com>
License: MIT
Project-URL: Source Code, https://github.com/NikolaKostadinov/diracengine
Keywords: python,quantum,spin,ket,bra,superposition,psi,dirac,engine,schrodinger,pauli,bohr
Platform: UNKNOWN
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Description-Content-Type: text/markdown
License-File: LICENSE


# <span style="background: linear-gradient(2deg, #3d4cff 0%, #ff3bd8 100%); -webkit-text-fill-color: transparent;-webkit-background-clip: text;">**The Dirac Engine**: ***a tribute to a legend***</span>



## Contents



0. [A Tribute to a Legend](#a-tribute-to-a-legend)

1. [Let's Get Started](#lets-get-started)

    * [Requirements](#requirements)

    * [Installation](#installation)

    * [Importing the engine](#importing-the-engine)

2. [Hello Quantum World](#hello-quantum-world)

    * [The Qubit](#the-qubit)

    * [Spin 1/2](#spin-12)

    * [The Wave Function](#the-wave-function)

    * [Particle in a Box](#particle-in-a-box)



---



## **A Tribute to a Legend**



The **Dirac engine** is a *Pyhon physics engine* which simulates quantum phenomena. This includes basic quantum and wave mechanics, [spin 1/2 particles](https://en.wikipedia.org/wiki/Spin-1/2) and their antimatter partners.



In 1928 [**Paul Dirac**](https://en.wikipedia.org/wiki/Paul_Dirac), an english physicist, was working on a relativistic theory of quantum mechanics. The result is a beautiful equation:



$$ i \hbar \gamma^\mu \partial_\mu \ket\psi - m c \ket\psi = 0 $$



This equation predicts electron spin, the periodic table, antimatter and the **g** factor. It is also the first building block of [**quantum field theory**](https://en.wikipedia.org/wiki/Quantum_field_theory): оur best description of reality (yet).



This equation is the core of the **Dirac engine**. This is why this name has been chosen for the project. The engine is *a tribute to a legend*: **Paul Dirac**, one of the geniuses of the 20th century.



[<p align="center"><image src="./assets/paul_dirac_gradient.png" width=30% /></p>](https://en.wikipedia.org/wiki/Paul_Dirac)



Quantum field theory is hard. It requires years of studying just for the basics. But that is not the main problem. Calculations in quantum field theory are beyond the performance limits of modern computers. So, how could we simulate the quantum realm?



Fortunately, quantum field theory's predecessor: [**quantum mechanics**](https://en.wikipedia.org/wiki/Quantum_mechanics), is easier. It does not require you to build a cluster of supercomputers. You can simulate basic quantum phenomena on your own computer.



---



## **Let's Get Started**



### **Requirements**



Let's get started with the engine. Firstly: the **requirement**. Using this engine is not for everyone. But if you have passed the requirements you will not have any problems when coding. Here are they:



* **Python**: *it is obvious*



* **basic quantum mechanics**: *don't worry, I have provided an [introduction guide to quantum mechanics]()*



* **linear algebra**: *this is Python so you should be good*



* **complex numbers**: *√-1 is possible*



* **hamiltonian mechanics**: *if you know this, you can skip the other*



* **multivariable calculus**: *just the basics*



* **basic physics**: *this is a must*



### **Installation**



If you are comfortable with most of the requirements, you can proceed to the **installation**. You can install it like any other PIP package. Just open your terminal and paste this command:



```console

pip install diracengine

```



Congratulations! You have installed the **Dirac engine**.



### **Importing the engine**



Now let's import the package in Python. Open a new .py flie and write:



```python

import diracengine as dirac

```



This is it. You are ready to use the **Dirac engine**. In the next chapter we will write our first dirac programs. By the end of the chapter you will be able to solve the **Schrodinger equation** on your own with just a few lines of code.



## **Hello *Quantum* World**



In this "chapter" we will show you how to code with the **Dirac engine**. We will start with the basics.



### **The Qubit**



Our first example will be a quantum bit, shortly a **qubit**. A qubit is a quatum object with two states: 0 or 1. The qubit is in a **superposition** of both states. Each state has some **probability amplitude**. We can express this mathematically:



$$ \ket\psi = \alpha\ket0 + \beta\ket1 $$



where $\alpha$ is the probability amplitude of the 0 state and $\beta$: the 1 state. This quatum state will look like this:



```python

import diracengine as dirac



psi = dirac.QuantumState([ alpha, beta ], [ 0, 1 ])

```



The ``QuantumState`` object is initiated when two arguments are provided: ``probabilityAmplitudes`` and ``basis``. They must be lists. ``probabilityAmplitudes`` must include complex numbers only while ``basis`` does not have restrictions.



Let's try to initiate a qubit with equally likely possibilities of being 0 or 1:



$$ \ket\psi = \alpha\ket0 + \alpha\ket1 $$



In the language of the **Dirac engine** this will look like this:



```python

import diracengine as dirac



alpha = 1 + 0j



psi = dirac.QuantumState([ alpha, alpha ], [ 0, 1 ])

```



But there is an issue. In quantum mechanics the quantum state **must be normalized**:



$$ \braket{\psi|\psi} = 1 $$



This means that if we want a normalized quantum state we need $\alpha$ to be:



$$ \alpha^*\alpha = \frac{1}{2} $$



If we assume that $\alpha$ is a real number: $\alpha \in \mathbb{R}$, this means that $\alpha$ must be $\pm \sqrt{\frac{1}{2}}$, not 1. So, we have made a mistake?



The **Dirac engine normalizes the quantum state by default**. It only scales the probability amplitudes, preserving their phase. This means that when we pass $\alpha = 1$, the engine will convert it to  $\alpha = \sqrt{\frac{1}{2}}$. We can test this by printing the quantum state:



```python

import diracengine as dirac



alpha = 1 + 0j



psi = dirac.QuantumState([ alpha, alpha ], [ 0, 1 ])



print(psi)

```



The terminal output is:



```console

[

        0: 0.7071067811865476 + 0.0i 

        1: 0.7071067811865476 + 0.0i 

]

```



> **Tip**: if you want to work with **unnormalized** probability amplitudes you can change the ``normalize`` argument to ``False`` when initiating the object:

> ```python

> psi = dirac.QuantumState(probabilityAmplitudes, basis, normalize = False)

>```

> You can also change ``norm`` of the state $\braket{\psi|\psi}$. By default it is set to 1.

> ```python

> norm = 1

> psi = dirac.QuantumState(probabilityAmplitudes, basis, norm = norm)

> ```



Let's return to the general case. We will try an arbitrary value for $\beta$. For example let $\beta$ be $i$:



```python

import diracengine as dirac



alpha = 1 + 0j

beta = 0 + 1j



psi = dirac.QuantumState([ alpha, beta ], [ 0, 1 ])



print(psi)

```



```console

[

        0: 0.7071067811865476 + 0.0i

        1: 0.0 + 0.7071067811865476i

]

```



We can see that $\beta$ is still an imaginary number after the normalization. The phase of $\beta$ looks the same. We can test this. We can get the new value for $\beta$ after the normalization like this:



```python

psi.probabilityAmplitude(1)

```



Now we will import the ``cmath`` module to get the phase of the complex number. Then we will print the results on the terminal.



```python

import cmath

import diracengine as dirac



alpha = 1 + 0j

beta = 0 + 1j



psi = dirac.QuantumState([ alpha, beta ], [ 0, 1 ])



newBeta = psi.probabilityAmplitude(1)



phaseBeta = cmath.phase(beta)

phaseNewBeta = cmath.phase(newBeta)



print(phaseBeta, phaseNewBeta)

```



```console

1.5707963267948966 1.5707963267948966

```



The result is 90° in radians. You can convert to degrees by multiplying by $\frac{180^\circ}{\pi}$.



Our next goal will be converting the complex **probability amplitudes** to real **probabilities**. We can get the probability of a base state with this method:



```python

psi.probability(base)

```



In this case for the states 0 and 1 we get ``0.5``. The states are equally likely.



This concludes our qubit tour. In the next section we will get familiar with **quantum operators** in the **Dirac engine**.



### **Spin 1/2**



The **electron** is famous for its **two-valuesness**. All fermions that have this strange property are classified as **spin 1/2 particles**. Spin is a fundamental property of nature. It does not have a classical analog. It is a pure quantum property. The electron behaves like a qubit. It has two states: **spin-up** and **spin-down**.:



$$ \ket\psi = \alpha\ket\uparrow + \beta\ket\downarrow $$



Now let's use the **Dirac engine** to create an electron:



```python

import diracengine as dirac



alpha = 1 + 0j

beta = 0 + 1j



basis = [ 'spin-up', 'spin-down' ]



psi = dirac.QuantumState([ alpha, beta ], basis)

```



In quantum mechanics we can measure the spin of the electron



...



### **The Wave Function**



...



### **Particle in a Box**



...

