{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "512571e4",
   "metadata": {},
   "source": [
    "# Basic Usage\n",
    "\n",
    "In this notebook, we give a few examples of how to use ``Cryptomite`` and accompanying utility functions. \n",
    "A similar, more introductory, guide to getting started can be found in this [blog post](https://medium.com/quantinuum/introducing-cryptomite-randomness-extraction-simplified-857fc2f87673)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1a031d29",
   "metadata": {},
   "source": [
    "## Quick Start\n",
    "\n",
    "``pip install cryptomite``"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4b899d5b",
   "metadata": {},
   "source": [
    "## Initializing an extractor\n",
    "\n",
    "Using ``Cryptomite``, extractors can be initialized by giving the input length (in bits) ``n_1`` and output length (in bits) ``m``, or in the case of the Trevisan extractor, giving the input length ``n``, output length ``m`` and maximum acceptable extractor error,``error``.\n",
    "We generate all the extractors of ``Cryptomite`` below, for an example ``n_1``, ``m``, ``error``:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5f168725",
   "metadata": {},
   "outputs": [],
   "source": [
    "import cryptomite\n",
    "n_1, m, error = 100, 90, 0.0001\n",
    "circulant = cryptomite.Circulant(n_1, m)\n",
    "dodis = cryptomite.Dodis(n_1, m)\n",
    "toeplitz = cryptomite.Toeplitz(n_1, m)\n",
    "trevisan = cryptomite.Trevisan(n_1, m, error)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "23b75513",
   "metadata": {},
   "source": [
    "## Performing extraction\n",
    "\n",
    "Now the extractors have been initialized, we demonstrate how to perform extraction. \n",
    "The extractors take a list of input bits and a list of (weak) seed bits as input and output a new list of bits.\n",
    "Each extractor of ``Cryptomite`` requires a different amount of (weak) seed bits and the calculation of this is left to the user (either manually or using our ``from_params`` utility functions). \n",
    "In the following example, we generate both the input string and the (weak) seed using ``randint`` function from the ``random`` Python library, which users would replace with their desired generation methods, and use ``n_1`` and ``n_2`` to represent the input and (weak) seed lengths, respectively."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0d28807c",
   "metadata": {},
   "outputs": [],
   "source": [
    "from random import randint\n",
    "input_bits = [randint(0, 1) for _ in range(n_1)]\n",
    "circulant.extract(input_bits, [randint(0, 1) for _ in range(n_2)])\n",
    "dodis.extract(input_bits, [randint(0, 1) for _ in range(n_2)])\n",
    "toeplitz.extract(input_bits, [randint(0, 1) for _ in range(n_2)])\n",
    "trevisan.extract(input_bits, [randint(0, 1) for _ in range(n_2)])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "42f7f24f",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "## Using the from_params utility functions\n",
    "\n",
    "Alternatively, all ``Cryptomite`` extractors (except Trevisan) can be generated without manually calculating the output or seed length, by using the ``from_params`` utility functions. \n",
    "Simply provide the input length, input min-entropy, (weak) seed length, (weak) seed min-entropy, maximum acceptable extractor error and specify whether to calculate the quantum-proof output length or not. \n",
    "For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "19ba95c7",
   "metadata": {},
   "outputs": [],
   "source": [
    "import cryptomite\n",
    "from math import log2\n",
    "n_1, k_1 = 100, 60\n",
    "n_2, k_2 = 100, 80\n",
    "error = 0.00001\n",
    "q_proof = False\n",
    "log2_error = log2(error)\n",
    "circulant = cryptomite.Circulant.from_params(n_1, k_1, n_2, k_2, log2_error, q_proof)\n",
    "dodis = cryptomite.Dodis.from_params(n_1, k_1, n_2, k_2, log2_error, q_proof)\n",
    "toeplitz = cryptomite.Toeplitz.from_params(n_1, k_1, n_2, k_2, log2_error, q_proof)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fb5cbab8",
   "metadata": {},
   "source": [
    "In this case, a **valid** extractor is generated from the specified parameters (i.e. one that adheres to the required input and seed length criteria for that extractor).\n",
    "Any changes to input length, seed length, input entropy and seed entropy printed."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}