XChem HIPPO

HIPPO: 🦛 Hit Interaction Profiling for Progression Optimisation

HIPPO is in active development and feedback is appreciated.

Please see the documentation to get started

Installation

HIPPO is pip-installable:

pip install --upgrade xchem-hippo

For local development with PostgreSQL + RDKit cartridge, use Docker Compose (see below).

For more information see the installation guide

More Information

Repository structure

Branches

• HIPPO/main: latest stable version (Django ORM + PostgreSQL)
• HIPPO/dev: Development branch

Information for HIPPO developers

Developer installation

To develop on HIPPO please fork this repository and then install locally:

git clone https://github.com/YOUR_USER/HIPPO
cd HIPPO
uv sync --frozen

Or with pip:

pip install -e .

Releases

HIPPO is automatically released to PyPI as xchem-hippo via a Github Action off the using the release workflow.

When you want to make an official release go to the Releases page and then click the Draft a new release button. Remember to familiarise yourself with the xchem release process on the trunk-based-development Wiki Creating releases page.

Code style

HIPPO is linted using black and commits are automatically linted using the lint workflow. The use of pre-commit is encouraged for local development to automatically run the linting at git commit time:

pip install pre-commit
pre-commit install

Documentation

Documentation is automatically built off the HIPPO/main branch using readthedocs. For local building using sphinx:

cd docs
make html

To check API reference coverage use docstr-coverage

pip install docstr-coverage
docstr-coverage hippo

Tests

Tests require a running PostgreSQL database (see Docker setup below). Run with:

uv run pytest

N.B. the numbered tests, e.g. test_01_fragalysis_download.py need to run in sequential order to set up the database. Configure tests/config.py to point at your database. The tests will fail if https://fragalysis.diamond.ac.uk can not provide the protein target's data.

Local development with Docker

Setting up the environment

HIPPO uses Docker Compose to run PostgreSQL with the RDKit cartridge locally.

1. Create a .env file in the project root with your database connection parameters:

DB_NAME=designdb
DB_USER=postgres
DB_PASSWORD=your_password
DB_HOST=database
POSTGRES_PORT=5432

2. Build the database container (includes RDKit cartridge compilation — this may take some time):

cd images/xchem-designdb
docker build -t xchem_designdb:latest .
cd ../..

3. Build the application container:

docker build --no-cache . -t hippo_backend:latest

4. Launch services:

docker compose up

To run only the database (connecting from your host):

docker compose up database

5. Access the Jupyter environment at the URL printed in the terminal output.

6. Cleanup:

docker compose down      # stop services
docker compose down -v   # also wipe database volume

Connecting to a remote deployment

Check port availability:

nc -zv IP_ADDRESS 5432

Success will look something like this:

Ncat: Version 7.92 ( https://nmap.org/ncat )
Ncat: Connected to IP_ADDRESS:5432.
Ncat: 0 bytes sent, 0 bytes received in 0.01 seconds.

To ssh tunnel to a host which has the correct exposed port and forward the correct port:

ssh -L 5432:IP_ADDRESS:5432 USER@GATEWAY_HOST

To test your connection (from your local machine)

pg_isready -h localhost -p 5432

To list available databases with psql

psql -h localhost -U USER -p 5432 -l

To connect to a specific database with psql

psql -h localhost -U USER -p 5432 -n DATABASE