Installation

poisson-topicmodels works with Python 3.11+. We recommend using a fresh environment for installation to avoid dependency conflicts.

Installation from Source

For development work or to use the latest features, you can install from source:

git clone https://github.com/BPro2410/poisson_topicmodels.git
cd poisson_topicmodels
pip install -e .

The -e flag installs the package in editable mode, allowing you to modify the source code and have changes reflected immediately.

Development Installation

For contributing to the project or running tests, install with development dependencies:

git clone https://github.com/BPro2410/poisson_topicmodels.git
cd poisson_topicmodels
pip install -e ".[dev,docs]"

This includes:

  • dev: Testing frameworks (pytest, pytest-cov), code quality tools (black, isort, mypy, pylint, flake8)

  • docs: Documentation tools (sphinx, sphinx-rtd-theme, myst-parser)

GPU Support (JAX)

poisson-topicmodels leverages JAX for transparent GPU acceleration. Out of the box, JAX is installed with CPU support. To enable GPU acceleration:

For NVIDIA GPUs (CUDA), install the CUDA-enabled JAX:

pip install jax[cuda12_cudnn]

For AMD GPUs (ROCm):

pip install jax[rocm]

For Apple Silicon GPUs:

pip install jax[metal]

See JAX Installation for detailed GPU setup instructions.

Conda Installation

If you prefer Conda, you can install from conda-forge once the package is published there:

conda install -c conda-forge poisson-topicmodels

For now, pip install is recommended.

Environment Management

Using venv

Create a virtual environment with venv:

python3 -m venv topicmodels_env
source topicmodels_env/bin/activate  # On Windows: topicmodels_env\Scripts\activate
pip install poisson-topicmodels

Using Conda

Create and manage environments with Conda:

conda create -n topicmodels python=3.11
conda activate topicmodels
pip install poisson-topicmodels

Verifying the Installation

After installation, verify that everything works correctly:

import poisson_topicmodels
print(poisson_topicmodels.__version__)

from poisson_topicmodels import PF
print("Installation successful!")

Or run the test suite:

pytest tests/test_imports.py

Troubleshooting

ImportError: No module named ‘poisson_topicmodels’

  • Ensure you’ve activated the correct virtual environment

  • Try reinstalling: pip install --force-reinstall poisson-topicmodels

JAX CUDA/GPU errors

  • Verify JAX was installed correctly: python -c "import jax; print(jax.devices())

  • Check JAX GPU documentation: JAX GPU Guide

Dependency conflicts

  • Use a fresh virtual environment: python3 -m venv fresh_env && source fresh_env/bin/activate

  • Install only the base package first, then add extras as needed

Documentation build errors (when installing from source)

  • Ensure sphinx and related tools are installed: pip install ".[docs]"

Need Help?

System Requirements

  • Python: 3.11, 3.12, or 3.13

  • OS: Linux, macOS, or Windows

  • RAM: 2 GB minimum (8 GB+ recommended for large corpora)

  • Disk: ~500 MB for installation, depends on corpus size

Optional dependencies for GPU acceleration:

  • NVIDIA: CUDA Toolkit 11.8+ and cuDNN 8.6+ (for GPU support)

  • AMD: ROCm 5.0+ (for AMD GPU support)