Metadata-Version: 2.1
Name: feyn
Version: 1.5.2
Summary: Feyn is the high level Python interface to interact with an Abzu QLattice.
Home-page: https://abzu.ai
Author: Abzu
Author-email: support@abzu.ai
License: CC BY-ND 4.0
Project-URL: Documentation, https://docs.abzu.ai
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: urllib3 (>=1.26)
Requires-Dist: numpy (>=1.18)
Requires-Dist: svgwrite
Requires-Dist: matplotlib
Requires-Dist: ipython

# Feyn: AI by Abzu

Feyn is a Python library that pushes machine learning to a new level by taking strong inspiration from quantum physics. A Feyn model is based on the [path integral formulation](https://en.wikipedia.org/wiki/Path_integral_formulation) of quantum physics originally proposed by the American physicist Richard P. Feynman.

Feyn models have similarities with other machine learning models such as random forest models or neural networks, so some of the concepts may be familiar to you already. But at it's core, the Feyn model introduces a new way to work with your data together with a revolutionary way to accumulate and transfer learnings.

But let's start with the basics.

To generate a Feyn-model you need access to a QLattice, short for Quantum Lattice. To learn more about getting access to a QLattice, visit [www.abzu.ai](https://www.abzu.ai).

The other needed component is this Python package (feyn), that runs on your computer and accumulate learnings from your data. These learnings are communicated to your QLattice over the network.

The _QLattice_ is a high-performance quantum simulator that runs on dedicated hardware, hosted on a cluster. It is based on the [path integral formulation](https://en.wikipedia.org/wiki/Path_integral_formulation), which is an approach to quantum mechanics that was originally proposed by the American physicist Richard P. Feynman. For all the curious individuals, the path integral formulation, in very simple words, evaluates the relations between two points by considering and summing all the different possibilities of trajectories between those points.

The QLattice can be divided into 2 parts: _Registers_ and _Interactions_.

The _registers_ are what we use to interact with the QLattice. They are the input and output interface of a Feyn model. Often they are the features of your data set.

The _interactions_ are the basic computation units of the QLattice. They hold their own state and transform input data into output. It is how learnings are stored and what is used to extract the QGraphs.

The _QGraph_, short for Quantum Graph, represents *all* possible combinations connecting the input registers to the output register. That means all possible explanations for the given output with the given inputs, generated by the QLattice.

If you are interested in learning more about what a QLattice is, and how it works, then you should definately take a look at the [in-depth documentation here](https://docs.abzu.ai).

## Getting started: Feyn in 1 min

Ok, all this sounds good! But in practice how does this work?

Let us walk through a simple classification problem, step by step.

For this quick walk-through we will pick a simple classification problem. The breast cancer dataset which is bundled with `sklearn`.

This will show you the core concepts in building a graph to execute predictions, that you can deploy to your application.

### Connect to your QLattice

```python
from feyn import QLattice

qlattice = QLattice(url = "<URL to your qlattice>", api_token="<Your API token>")
```

### Read in the data

Read in an example data set (here we use the breast cancer data set which is shipped with scikit-learn)

```python
import sklearn.datasets
import pandas as pd

breast_cancer = sklearn.datasets.load_breast_cancer()

# Convert to a pandas dataframe
df = pd.DataFrame(breast_cancer.data,columns=breast_cancer.feature_names)
df['target'] = pd.Series(breast_cancer.target)
df.head()

```

### Train locally and update learnings remotely

Retrieve a QGraph which represents an ordered list of all possible models to solve the problem. The first parameter is a list of all the concepts or features you wanr 

```python
# Get a classifier QGraph from the remote QLattice
qgraph = qlattice.get_classifier(data.columns, target="target")
```
Next, run for some epochs, where you fit the `QGraph` to the training data, and update the `QLattice` with the learnings from the best graph.

The update calls will bias the `QLattice` from your learnings. Meaning that next time you call `qlattice.fit`, the new graphs found will fit your problem better.

Notice, that the `QLattice` lives remotely on the Abzu cluster, but it never sees your local data. The dataset stays on your premise. So, you train locally, and just transmit your learnings to the `QLattice`. That is the way the `QLattice` gets better at producing `QGraphs` that fits your problem.

```python
from sklearn.model_selection import train_test_split

train, test = train_test_split(df, test_size=0.33)

for _ in range(10):
    # Fit the local QGraph with your local data
    qgraph.fit(train)

    # Pich the graph with lowest loss on the training dataset as the best solution.
    best_graph = qgraph[0]

    # Teach the QLattice about this solution, so that it gets biased towards solutions similar to this.
    qlattice.update(best_graph)
```

### Evaluate

Finally, evaluate the results in the test dataset.
This is also how you utilize the `Graph` for predictions in your application.

```python
from feyn import tools

# Use the graph to produce predictions. This graph is similar your model in other framework.
# It is the thing you can save to a file, and deploy to your application or production environment.
predictions = best_graph.predict(X_test)

# This is a classification problem, but we are using a regression model to solve it.
# There are many ways to do this. In this example we will round to nearest integer (the class).
predictions = predictions.round()

tools.plot_confusion_matrix(y_true=test["target"],
                            y_pred=predictions,
                            title="Evaluation Results")
```


