Metadata-Version: 2.4
Name: PyTDLM
Version: 0.1.0
Summary: Systematic comparison of trip distribution laws and models
Author-email: Maxime Lenormand <maxime.lenormand@inrae.fr>
License: GPL-3.0
Project-URL: Homepage, https://github.com/RTDLM/PyTDLM
Project-URL: Repository, https://github.com/RTDLM/PyTDLM
Project-URL: Documentation, https://rtdlm.github.io/PyTDLM/
Project-URL: Bug Tracker, https://github.com/RTDLM/PyTDLM/issues
Keywords: spatial-interaction,gravity-model,trip-distribution
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: tabulate>=0.9.0
Requires-Dist: tqdm>=4.60.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Dynamic: license-file

# PyTDLM: Systematic comparison of trip distribution laws and models

A Python port of the [TDLM R package](https://github.com/RTDLM/TDLM), with numpy-based implementations and parallel processing support for multiple exponent values.

## Overview

PyTDLM provides implementations of several trip distribution models commonly used in transportation planning and spatial analysis:

### Available Laws
- **GravExp**: Gravity model with exponential distance decay
- **NGravExp**: Normalized gravity model with exponential decay
- **GravPow**: Gravity model with power distance decay
- **NGravPow**: Normalized gravity model with power decay
- **Schneider**: Schneider's intervening opportunities model
- **Rad**: Radiation model
- **RadExt**: Extended radiation model
- **Rand**: Random model (baseline)

### Available Models
- **UM**: Unconstrained Model
- **PCM**: Production Constrained Model
- **ACM**: Attraction Constrained Model
- **DCM**: Doubly Constrained Model

## Installation

### Using conda
```bash
conda install -c conda-forge pytdlm
```

### Using pip
```bash
pip install PyTDLM
```

### From source
```bash
git clone https://github.com/PyTDLM/TDLM.git
cd TDLM
pip install -e .
```

## Quick Start

```python
import numpy as np
from TDLM import tdlm

# Prepare your data
mi = np.array([100, 200, 150])  # Origin masses
mj = np.array([80, 180, 120])   # Destination masses  
dij = np.array([[0, 10, 15],    # Distance matrix
                [10, 0, 8], 
                [15, 8, 0]])
Oi = np.array([50, 80, 60])     # Out-trips
Dj = np.array([40, 90, 50])     # In-trips
Tij_observed = np.array([[0, 25, 25],  # Observed trip matrix
                         [30, 0, 50],
                         [35, 35, 0]])

# Run simulation
exponent = np.arange(0.1, 1.01, 0.01)
results = tdlm.run_law_model(
    law='NGravExp',
    mass_origin=mi,
    mass_destination=mj, 
    distance=dij,
    exponent=exponent,
    model='DCM',
    out_trips=Oi,
    in_trips=Dj,
    repli=100
)

# Calculate goodness-of-fit
gof_results = tdlm.gof(sim=results, obs=Tij_observed, distance=dij)

# Print results for a given exponent
print(gof_results[0.1].to_markdown(index=False))
```

## Documentation

For detailed documentation and examples, visit: [https://rtdlm.github.io/PyTDLM/](https://rtdlm.github.io/PyTDLM/)

## License

This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.

## Citation

If you use this library in your research, please cite:

```bibtex
@software{lenormand2024tdlm,
  title={TDLM: Trip Distribution Law Models},
  author={Lenormand, Maxime},
  year={2024},
  url={https://github.com/RTDLM/PyTDLM}
}
```
