Metadata-Version: 2.5
Name: tenqsp
Version: 0.6.0
Summary: Structured-population PDEs for quantitative systems pharmacology, in JAX
Project-URL: Repository, https://github.com/tenqsp/tenqsp
Author: Dongwoo Chae
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: JAX,finite volume,partial differential equations,pharmacometrics,quantitative systems pharmacology,structured populations
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.12
Requires-Dist: diffrax>=0.6
Requires-Dist: equinox>=0.11
Requires-Dist: jax>=0.4.30
Requires-Dist: lineax>=0.0.7
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: sympy>=1.12
Requires-Dist: threadpoolctl>=3.1
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: ipykernel>=6.29; extra == 'docs'
Requires-Dist: jupytext>=1.16; extra == 'docs'
Requires-Dist: matplotlib>=3.8; extra == 'docs'
Requires-Dist: mkdocs-jupyter>=0.25; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
Requires-Dist: nbclient>=0.10; extra == 'docs'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.8; extra == 'plot'
Provides-Extra: xarray
Requires-Dist: xarray>=2024.1; extra == 'xarray'
Description-Content-Type: text/markdown

# TenQSP

[![CI](https://github.com/tenqsp/tenqsp/actions/workflows/ci.yml/badge.svg)](https://github.com/tenqsp/tenqsp/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

**Structured-population PDEs for quantitative systems pharmacology, in JAX.**

Pharmacometric and QSP models describe populations: drug molecules, bacteria, blood cells,
tumour cells. Often a population is not uniform. Cells differ in age, maturation, dormancy,
depth in a tissue or genotype, and that difference decides how they respond to a drug. The
usual remedy is a chain of compartments, which hides the structure in a choice of how many
compartments to use.

TenQSP lets you write the structure itself. A population becomes a **field** over **axes**,
continuous (age, maturation, depth) or categorical (phenotype, organ), next to ordinary
compartments, and the model is written as equations, the way a paper writes them:

```tq
model delayed_pk
axis z in [0, 1] n=20 kind=one_way      # progress through the gut: 0 swallowed, 1 absorbed
param MTT=1.5, ka=2, CL=4, V=30
field G(z)                               # drug in transit, by progress
d_t(G) = -d_z(G/MTT)  using sharp        # moves along z at speed 1/MTT
    at z=1: outflow
d_t(depot) = G(z=1)/MTT - ka*depot
d_t(centr) = ka*depot - CL/V*centr
dose G at t=0 to 48 every 12: 100*point(z, at=0)
observable conc = centr/V
```

```python
import tenqsp as tq

m = tq.load("delayed_pk.tq")
sol = m.solve((0, 72), times=range(73))
sol["conc"]
```

TenQSP turns the model into a system of ODEs by the finite-volume method, works out which
states affect which (the sparse Jacobian), and solves it with a stiff solver: scipy's, or
TenQSP's own in JAX. The same model can be built step by step in Python, run over many
scenarios, and differentiated with respect to its parameters, dose amounts and dose times.

- **Equations as in a paper**, with boundary conditions under their equation;
  `m.to_latex()` prints them for an article, `m.explain()` says what each term means.
- **Books that balance**: a ledger accounts for every cell, molecule or phage.
- **Nothing hidden**: no value is clipped or capped behind your back.
- **One build, many runs**: changing parameters, doses or output times never rebuilds.
- **Exact gradients** through JAX, for estimation and sensitivity analysis.

## Install

```bash
pip install tenqsp
```

TenQSP needs Python 3.12 or later. For plots add `tenqsp[plot]`; for labelled array output,
`tenqsp[xarray]`.

## Documentation

**<https://tenqsp.github.io/tenqsp/>**: start here, the user guide, twelve tutorials, and
the notation and Python references.

## Cite

If you use TenQSP in your work, please cite it: see [`CITATION.cff`](CITATION.cff), or
"Cite this repository" on GitHub.

## Licence and credit

TenQSP is free and open source under the [Apache License 2.0](LICENSE). It was created by
Dongwoo Chae, MD, PhD, Yonsei University College of Medicine
([ORCID 0000-0002-7675-3821](https://orcid.org/0000-0002-7675-3821)); copyright 2026 Yonsei
University Health System (see [`NOTICE`](NOTICE)). Its code was written with AI assistance
(Claude Code, Anthropic) under the author's design, review and testing.

Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).
