Installing with virtualenv

This section guides you in installing the bulkdgd package in a virtual environment, meaning an instance of Python that is isolated from your system.

This is not strictly necessary, and bulkdgd may be installed system-wide similarly, following steps 4 to 6.

Step 1 - Install virtualenv

First, check if the virtualenv Python package is installed in your system. This can be done by verifying whether the virtualenv command is available.

It is usually available as a package in your distribution if you need to install it. For instance, on Debian-based systems (such as Debian or Ubuntu), it is sufficient to install the python-virtualenv package.

We recommend installing the virtualenv package for your local user using pip:

pip install --user virtualenv

If the installation is successful, the virtualenv command will be available.

Step 2 - Create the virtual environment

Create your virtual environment in a directory of your choice (in this case, it will be ./bulkdgd-env):

virtualenv -p /usr/bin/python3.11 bulkdgd-env

You should replace the argument of option -p according to the location of the Python interpreter you want to use inside the virtual environment.

Step 3 - Activate the environment

Activate the environment:

source bulkdgd-env/bin/activate

Step 4 - Install bulkdgd

You can now install bulkdgd from PyPI using pip:

pip install bulkdgd

bulkdgd should now be installed.

The trained decoder’s parameters (dec.pth) are not distributed with the package because of their size. You do not need to do anything about this now: the first time you use the pre-trained model (for instance, the first time you run bulkdgd_find_representations), bulkdgd will automatically download dec.pth (about 900 MB) and cache it inside the installed package for subsequent runs.

Note

If the machine you are running bulkdgd on has no internet access, download dec.pth manually on another machine from this URL (replace v2.0.1 with your installed bulkdgd version - run python -c "import bulkdgd; print(bulkdgd.__version__)" to check), transfer it to the offline machine, find where bulkdgd was installed with python -c "import bulkdgd, os; print(os.path.dirname(bulkdgd.__file__))", and place the file in the data/model/dec sub-folder of that directory (creating it if needed).

Every time you need to run bulkdgd after opening a new shell, just run step 3 beforehand.