Metadata-Version: 2.4
Name: champpy
Version: 0.1.5
Summary: CHAMPPy - Mobility and Charging Profiles in Python
Project-URL: Repository, https://github.com/ffe-munich/CHAMPPy
Project-URL: Issues, https://github.com/ffe-munich/CHAMPPy/issues
Author-email: Florian Biedenbach <fbiedenbach@ffe.de>
License: MIT
License-File: LICENSE
Keywords: charging,charging profiles,electric vehicles,markov process,mobility profiles
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: numpy>=1.0
Requires-Dist: pandas>=1.0
Requires-Dist: pandera[strategies]>=0.15
Requires-Dist: plotly>=5.0
Requires-Dist: pyarrow
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: scipy>=1.7
Requires-Dist: tqdm>=4.0
Provides-Extra: dev
Requires-Dist: black>=22.0; extra == 'dev'
Requires-Dist: flake8>=4.0; extra == 'dev'
Requires-Dist: ipykernel>=6.0; extra == 'dev'
Requires-Dist: jupyter>=1.0; extra == 'dev'
Requires-Dist: nbconvert>=7.0; extra == 'dev'
Requires-Dist: pylint>=2.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.0; extra == 'docs'
Requires-Dist: myst-nb>=1.0; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5.0; extra == 'docs'
Requires-Dist: sphinx-tabs>=3.5.0; extra == 'docs'
Requires-Dist: sphinx>=9.0; extra == 'docs'
Description-Content-Type: text/markdown

# CHAMPPy

[![PyPI version](https://img.shields.io/pypi/v/champpy.svg)](https://pypi.org/project/champpy/)
[![Python versions](https://img.shields.io/pypi/pyversions/champpy.svg)](https://pypi.org/project/champpy/)
[![PyPI downloads](https://img.shields.io/pypi/dm/champpy.svg)](https://pypi.org/project/champpy/)
[![License](https://img.shields.io/pypi/l/champpy.svg)](https://opensource.org/licenses/MIT)
[![Docs](https://img.shields.io/badge/docs-readthedocs-blue.svg)](https://champpy.readthedocs.io)

CHAMPPy (Charging and Mobility Profiles in Python) is a Python library to generate synthetic mobility and charging profiles for different types of electric vehicles (EVs) including vans, trucks, busses and passanger cars. 

   Graphical Abstract

Road transport decarbonization requires realistic charging demand models across all vehicle classes. However, most existing studies and publicly available tools focus on private passenger cars. Commercial electric vehicles such as vans and trucks are often underrepresented despite their major relevance for emissions and grid impacts. CHAMPPy is an open Python package that addresses this gap by generating synthetic driving and charging profiles for different EV types, including commercial fleets. The model combines a Markov chain to represent vehicle locations over time with beta-distributed journey speeds, from which trip distances are derived, and uses dedicated algorithms to generate mobility and charging profiles. An optional clustering approach increases profile heterogeneity and is particularly useful when analyzing individual profiles.

🛠️ CHAMPPy supports two workflows:

1. 🚀 **Light:** Use existing parameters to quickly generate drving and charging profiles with user-defined settings (e.g., simulation period, number of vehicles, charging power, battery capacity). An example of this workflow is provided in [notebooks/01_demo_without_parameterization.ipynb](https://champpy.readthedocs.io/en/latest/notebooks/01_demo_without_parameterization.html). 
2. 🧪 **Full:** Re-parameterize the model with custom reference data (e.g. driving data for other countries, vehicle classes, or fleets). Afterwards, you can generate drving and charging profiles from your model parameters. An example of this workflow is provided in [notebooks/02_demo_with_parameterization.ipynb](https://champpy.readthedocs.io/en/latest/notebooks/01_demo_without_parameterization.html)

## Links

* Documentation: [https://champpy.readthedocs.io](https://champpy.readthedocs.io/en/latest/)
* Source code: [https://github.com/ffe-munich/CHAMPPy](https://github.com/ffe-munich/CHAMPPy)
* PyPI releases: [https://pypi.org/project/champpy/](https://pypi.org/project/champpy/)
* License: [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT)

## Authors

CHAMPPy has been developed by [Florian Biedenbach](https://github.com/FloBieWan) (lead), Valentin Preis und [Daniel Godin](https://github.com/DaniGodin).

## Repo structure

```
CHAMPPy/
├── src/champpy/                        # Main package source code
│   ├── __init__.py
│   ├── core/                           # Core functionality
│   │   ├── __init__.py
│   │   ├── charging/                   # Charging profile module
│   │   │   ├── __init__.py
│   │   │   ├── charging_model.py       # Model to generate charging profiles
│   │   │   └── charging_validation.py  # Charging validation & plotting
│   │   └── mobility/                   # Mobility profile module
│   │       ├── __init__.py
│   │       ├── mobility_cleaning.py    # Data cleaning
│   │       ├── mobility_components.py  # Data components
│   │       ├── mobility_data.py        # Data structures
│   │       ├── mobility_model.py       # Model to generate profiles
│   │       ├── mobility_validation.py  # Validation & plotting
│   │       └── parameterization.py     # Parameter extraction
│   ├── utils/                          # Utilities
│   │   ├── __init__.py
│   │   ├── data_utils.py               # Ddata helpers
│   │   ├── logging.py                  # Logging configuration
│   │   └── time_utils.py               # Time utilities
|   └── data/                       
│       ├── params_info.parquet         # Info about existing model parameters
│       └── params.parquet              # Existing model parameters
├── notebooks/                          # Jupyter notebooks
│   ├── 01_demo_without_parameterization.ipynb # Demo notebook 1
│   └── 02_demo_including_parameterization.ipynb # Demo notebook 2
├── scripts/                            # Python scripts
├── tests/                              # Test suite
├── data/                               # Data directory
├── plots/                              # Generated plots (HTML files)
├── pyproject.toml                      # Project configuration
├── LICENSE                             # License file
└──  README.md                          # This file
```

## Installation

To install CHAMPPy on Windows, follow the steps below. For installation on Linux/Mac, please check the [installation documentation](https://champpy.readthedocs.io/en/latest/installation.html).

### Prerequisites
- Python 3.11 or higher
- pip

### Install from source on windows

```bash
# Clone the repository
git clone https://github.com/ffe-munich/CHAMPPy.git
cd CHAMPPy

# Create a virtual environment
py -m venv .venv

# Activate virtual environment
.\.venv\Scripts\activate


# Install the package
pip install .
```

### Install from PyPI on windows

```bash
# Create a virtual environment
py -m venv .venv

# Activate virtual environment
.\.venv\Scripts\activate

pip install champpy
```





