Installation

torchcell requires Python 3.13 or newer (requires-python = ">=3.13" in pyproject.toml). The package’s runtime dependencies are read from env/requirements.txt ([tool.setuptools.dynamic] in pyproject.toml), so the pip requirement files under env/ are the source of truth for what gets installed.

Create the environment

The repository does not ship a conda environment file for the main package (env/tc-graph.yaml is a separate Python 3.11 environment for the graph-build tooling). Create a Python 3.13 environment and install into it in the order the CI workflow (.github/workflows/test.yaml) uses:

conda create -n torchcell python=3.13
conda activate torchcell

# 1. torch first; choose the wheel that matches your platform and CUDA version
pip install "torch==2.11.0"

# 2. the runtime stack
pip install -r env/requirements.txt

# 3. torch-scatter, from the PyG wheel index matched to the installed torch build
#    (env/requirements_dependent.txt must be installed after torch)
pip install -r env/requirements_dependent.txt -f https://data.pyg.org/whl/torch-2.11.0+cpu.html

# 4. test tooling (pytest, coverage, diff-cover)
pip install -r env/requirements_test.txt

# 5. torchcell itself, editable
pip install -e .

For a CUDA build, replace +cpu in the wheel index URL with the CUDA tag of your torch build (for example +cu128), as the comment in env/requirements_dependent.txt shows. Documentation dependencies live in env/requirements_docs.txt.

The Makefile does not create environments; its test, test-ci, test-fast and coverage targets call $(HOME)/miniconda3/envs/torchcell/bin/python unless PYTHON is overridden (make test PYTHON=$(which python)).

Environment variables

torchcell reads its paths and connection settings from the process environment. Most entry points call python-dotenv’s load_dotenv(), so a .env file at the repository root works as well. The table lists names only; values are machine specific.

Variable	Required	Read by
`DATA_ROOT`	For any data access	Dataset loaders, the genome (`$DATA_ROOT/torchcell-genomes/`), raw-data mirrors, build CLIs. Importing torchcell does not need it.
`ASSET_IMAGES_DIR`	Optional	Plotting code and experiment scripts that save figures.
`EXPERIMENT_ROOT`	Optional	Experiment scripts under `experiments/`.
`NEO4J_URI`	Optional	`torchcell.database.connection`; defaults to a local bolt instance.
`NEO4J_USER`	Optional	As above; has a default.
`NEO4J_PASSWORD`	Optional	As above; has a default. Set it for any server other than a local development instance.
`TORCHCELL_KG_VERSION`	Optional	Which knowledge-graph release a query opens; defaults to `latest`. See Choosing a release.
`TC_LIT_URL`	Optional	Literature tooling that pulls OCR’d paper artifacts from the `tc-lit` service (for example `scripts/lit_bib_pull.py`).
`TC_LIT_API_KEY`	Optional	API key for `tc-lit`, used with `TC_LIT_URL`.

The Neo4j variables are resolved at call time, not import time, by torchcell.database.connection.neo4j_connection_settings(), so a load_dotenv() issued after import torchcell is still honored.

Verify the install

The check below needs no DATA_ROOT, no network and no database. Importing torchcell.datasets.scerevisiae registers every dataset loader class in torchcell.datasets.dataset_registry.dataset_registry.

import torchcell
import torchcell.datasets.scerevisiae  # importing the loaders fills the registry
from torchcell.datasets.dataset_registry import dataset_registry

print(torchcell.__version__)
print("SmfCostanzo2016Dataset" in dataset_registry)
print(dataset_registry["SmfCostanzo2016Dataset"])

Output (torchcell 1.2.1, run with DATA_ROOT unset):

1.2.1
True
<class 'torchcell.datasets.scerevisiae.costanzo2016.SmfCostanzo2016Dataset'>

Some compiled dependencies print DeprecationWarning: builtin type SwigPyPacked has no __module__ attribute (and similar) on stderr during this import; the import still succeeds.

To run the hermetic test suite, see Tests.