Metadata-Version: 2.4
Name: gymchem
Version: 0.1.0a1
Summary: GymChem: a Gymnasium-compatible platform for chemical process optimization and data-driven analysis.
Author: GymChem contributors
License-Expression: MIT
Keywords: reinforcement-learning,chemical-engineering,gymnasium,process-optimization,simulation
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gymnasium>=0.29
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.10
Provides-Extra: dev
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: matplotlib>=3.7; extra == "dev"
Dynamic: license-file

# GymChem

**English** | [中文](README.zh-CN.md)

[![CI](https://github.com/guyuan0710/gymchem/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/guyuan0710/gymchem/actions)
[![Python](https://img.shields.io/badge/Python-3.9--3.12-blue)](https://github.com/guyuan0710/gymchem/blob/main/pyproject.toml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.1.0--alpha-orange)](https://github.com/guyuan0710/gymchem/releases)

Gymnasium-compatible simulation environments for chemical process optimization and data-driven analysis — from a minimal CSTR to industrial-scale benchmarks.

![CSTR v0.1 demo: proportional control of an exothermic A→B reactor](docs/assets/cstr_demo.gif)

## Why GymChem

Chemical process optimization research is fragmented: pyTEP is a simulator only, IDAES is powerful but steep, and ChemGymRL targets lab operations rather than industrial processes. GymChem unifies these scenarios behind a standard Gymnasium API — consistent state/action/reward design, fully traceable parameters, reproducible baselines and leaderboards, plus datasets and data-analysis tutorials. For researchers it is a ready-to-use benchmark platform; for students it is a friendly on-ramp to RL for chemical engineering.

## Environments

| Environment | State | Action | Reward | Status |
|---|---|---|---|---|
| `CSTRSimpleEnv` | Reactor temperature (K) | Heating/cooling rate (K/s) | `-abs(T - T_target)` | stable |
| `CSTREnv` | T (K), C_A (mol/m³), cooling-water T (K) | Cooling-water temperature rate (K/s) | `-abs(T - T*) - 0.05 * abs(C_A - C_A*)` | alpha |

`CSTREnv` models a continuous stirred-tank reactor with a first-order exothermic reaction A → B: species balance, energy balance with Arrhenius kinetics, a cooling-water jacket, and a conservation-checked explicit-Euler integrator.

## Install

```bash
# from source
git clone https://github.com/guyuan0710/gymchem.git
cd gymchem
pip install -e ".[dev]"

# once published on PyPI
pip install gymchem
```

## Quick start

```python
from gymchem.envs.cstr import CSTREnv, CSTRSimpleEnv

# v0.1: exothermic A→B CSTR — temperature + concentration + jacket
env = CSTREnv()
obs, info = env.reset(seed=0)
for _ in range(100):
    obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
    if terminated or truncated:
        break

# v0.0: minimal temperature tracking
env = CSTRSimpleEnv()
obs, info = env.reset(seed=0)
```

## Test

```bash
pip install -e ".[dev]"
pytest        # 17 tests: env_checker, no-NaN runs, conservation residuals, data pipeline
ruff check .  # zero warnings
```

## Data validation

Automated detection, validation, and update-maintenance for research/experimental data
(`gymchem.data`, no new dependencies):

```bash
python -m gymchem.data data/demo_cstr_trajectory.csv \
  --manifest data/manifest.json --sidecar data/demo_meta.json \
  --report data/demo_report.md
```

See [docs/data-validation.md](docs/data-validation.md) for the full workflow.

## Docs & examples

- [Parameter provenance (CSTR)](docs/parameter-provenance-cstr.md) — every physical constant traced to a source
- [Data validation (detect / verify / maintain)](docs/data-validation.md)
- [Colab-ready notebook](notebooks/demo_cstr.ipynb)
- [中文说明](README.zh-CN.md)

## License

MIT © GymChem contributors
