Metadata-Version: 2.4
Name: physlink
Version: 0.1.2
Summary: Backend-agnostic adapter library for physical simulation ML
License: MIT
Project-URL: Homepage, https://Denis-hamon.github.io/physlink/
Project-URL: Documentation, https://Denis-hamon.github.io/physlink/
Project-URL: Repository, https://github.com/Denis-hamon/physlink
Project-URL: Bug Tracker, https://github.com/Denis-hamon/physlink/issues
Project-URL: Changelog, https://github.com/Denis-hamon/physlink/blob/main/CHANGELOG.md
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: rich>=13.0
Requires-Dist: matplotlib>=3.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: safetensors>=0.4
Requires-Dist: Pillow>=9.0
Provides-Extra: dev
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.9; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: torch; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Requires-Dist: mike>=2.1; extra == "docs"
Provides-Extra: notebook
Requires-Dist: nbconvert>=7.0; extra == "notebook"
Requires-Dist: nbformat>=5.9; extra == "notebook"
Dynamic: license-file

# PhysLink

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/Denis-hamon/physlink/actions/workflows/ci.yml/badge.svg)](https://github.com/Denis-hamon/physlink/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://Denis-hamon.github.io/physlink/)
[![PyPI](https://img.shields.io/pypi/v/physlink.svg)](https://pypi.org/project/physlink/)
[![Python](https://img.shields.io/pypi/pyversions/physlink.svg)](https://pypi.org/project/physlink/)
[![arXiv](https://img.shields.io/badge/arXiv-coming%20soon-b31b1b.svg)](https://arxiv.org/abs/PLACEHOLDER)

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Denis-hamon/physlink/blob/main/notebooks/quickstart.ipynb)

<p align="center">
  <a href="https://colab.research.google.com/github/Denis-hamon/physlink/blob/main/notebooks/quickstart.ipynb"><strong>Quick Start →</strong></a>
  &nbsp;&nbsp;|&nbsp;&nbsp;
  <a href="https://Denis-hamon.github.io/physlink/lab-adoption-guide/"><strong>Evaluate for your lab →</strong></a>
  &nbsp;&nbsp;|&nbsp;&nbsp;
  <a href="https://Denis-hamon.github.io/physlink/domain-scientists/"><strong>For Domain Scientists →</strong></a>
</p>

---

**PhysLink bridges physical simulators and deep RL adapters in one `pip install`.**

Plug your robot trajectories into [DreamerV3](https://github.com/danijar/dreamerv3) (and future backends) without writing boilerplate space definitions, checkpoint logic, or compliance checks. PhysLink handles the plumbing — you keep the science.

## Why PhysLink

| Without PhysLink | With PhysLink |
|-----------------|---------------|
| Hand-write observation/action space mappings per framework | `ObservationSpace.from_proprioception(joints=7)` |
| Debug silent OOM on Colab at step 8 000 | `physlink.doctor()` catches it before you start |
| Lose 3h of T4 training on session disconnect | Auto-checkpoint every N steps, resume on reconnect |
| Manually verify energy conservation after adaptation | `register_invariant` + `compliance_report()` |
| Stare at loss curves to diagnose model drift | Triptych GIF — Imagination / Real / Difference in one call |

## Install

```bash
pip install physlink
```

Works on Google Colab out of the box. No CUDA required for diagnostics and space definitions.

## Quick example

```python
import physlink

# 1. Verify your environment (< 15 s)
physlink.doctor()

# 2. Define spaces from your robot config
obs = physlink.ObservationSpace.from_proprioception(joints=7, include_velocity=True)
act = physlink.ActionSpace.continuous(dims=7, bounds=(-1.0, 1.0))

# 3. Adapt
adapter = physlink.DreamerV3Adapter(obs, act)
adapter.fit(trajectories, steps=10_000)

# 4. Validate physics compliance
physlink.register_invariant(adapter, "energy", fn=energy_fn, tolerance=0.05)
report = adapter.compliance_report()
report.plot()

# 5. Visualise
adapter.visualize(trajectories)   # → triptych GIF
adapter.export("./run-01/")
```

## Documentation

Full docs at **[Denis-hamon.github.io/physlink](https://Denis-hamon.github.io/physlink/)** — includes API reference, lab adoption guide, and domain-scientist quickstart.

## Status

`v0.1.x` — public API stable across minor versions (see [CHANGELOG](CHANGELOG.md)).  
`test-cpu` CI passes on every PR. GPU benchmarks run on release tags.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome — use the provided templates.
