Getting started

Getting started#

Installation#

This Python package can be easily installed using pip

pip install --user randextract

Note that the previous command installs our package and all runtime dependencies into your local Python environment. This may have unwanted effects (e.g. downgrading an already installed NumPy package for compatibility reasons). If you want to test our package in a virtual Python environment, you can run the following instead.

python -m venv --upgrade-deps env-randextract
source env-randextract/bin/activate
pip install randextract

Warning

If you decide to use a virtual environment, you will have to activate it every time you start a new console by running the second command from the box above.

Development installation#

PyPI only contains stable releases. If you want to try the latest code, you have to clone the source repository first. You will need git for this, so check out the documentation if you don’t already have it installed on your system.

git clone https://github.com/cryptohslu/randextract.git
cd randextract

Now you can create a virtual env and install the package from the local directory

python -m venv --upgrade-deps env-randextract
source env-randextract/bin/activate
pip install ".[dev,docs,examples,test]"

Hint

You can also install the package in “editable” mode by adding -e to the pip command. In this way, you don’t need to reinstall the package after doing changes in the source code.

To locally build this documentation

cd docs
make html

And to run the unit tests

pytest tests

Testing installation#

The following code creates a modified Toeplitz hashing extractor. After generating a random input and a seed with the correct lengths, we pass them to the extractor and save the output to a new variable.

from galois import GF2

import randextract
from randextract import ModifiedToeplitzHashing, RandomnessExtractor

optimal_output_length = ModifiedToeplitzHashing.calculate_length(
    extractor_type="quantum",
    input_length=2**20,
    relative_source_entropy=0.8,
    error_bound=1e-3,
)

ext = RandomnessExtractor.create(
    extractor_type="modified_toeplitz",
    input_length=2**20,
    output_length=optimal_output_length,
)

input_ext = GF2.Random(ext.input_length)
seed_ext = GF2.Random(ext.seed_length)

output = ext.extract(input_ext, seed_ext)

If you are interested in learning more about randomness extractors continue reading the theory section. If you just want to learn how to use this Python package, you can jump directly to the usage section.

Contents