# pidtune

**An open-source Python library for PID controller tuning.**

`pidtune` provides a coherent, well-tested toolkit for the full PID tuning
workflow:

1. **Describe** your process with a process model (FOPDT, SOPDT, or an
   arbitrary transfer function), or identify one from step-response data.
2. **Tune** a PID controller with classical rules (Ziegler–Nichols,
   Cohen–Coon, AMIGO, IMC/lambda), relay autotuning, or optimization-based
   tuning against time- or frequency-domain objectives.
3. **Simulate** the resulting closed loop, evaluate performance metrics
   (IAE, ISE, ITAE, overshoot, settling time, robustness margins), and
   iterate.
4. **Deploy** the tuned gains in any controller form (ideal/ISA, parallel,
   series) with explicit, lossless conversions between forms.

## Project status

This repository currently contains **Milestone 1: Architecture & API Design**.
That includes:

- A complete technical design document under [`docs/design/`](docs/design/).
- Fully docstring-specified API stubs under [`src/pidtune/`](src/pidtune/)
  that define every public class, function, dataclass, and exception the
  library will ship. Method bodies raise `NotImplementedError` and reference
  the milestone in which they will be implemented (see the
  [roadmap](docs/design/06_roadmap.md)).

The API stubs are importable Python and are intended to be reviewed, type
checked, and built against. **No numerical behaviour is implemented yet.**

## Design documents

| Document | Contents |
| --- | --- |
| [`01_architecture.md`](docs/design/01_architecture.md) | Library architecture, module layout, layering and dependency rules |
| [`02_data_models.md`](docs/design/02_data_models.md) | Process-model data model: FOPDT, SOPDT, arbitrary transfer functions |
| [`03_tuning_methods.md`](docs/design/03_tuning_methods.md) | Survey of tuning methods to be implemented, with formulas and applicability |
| [`04_api_specification.md`](docs/design/04_api_specification.md) | Public API specification: controllers, tuners, plants, simulation |
| [`05_errors_and_extensibility.md`](docs/design/05_errors_and_extensibility.md) | Error-handling conventions, warnings policy, extension points |
| [`06_roadmap.md`](docs/design/06_roadmap.md) | Contributor-facing roadmap and milestone plan |

## Installation (development)

Requires Python 3.10+.

```bash
git clone https://github.com/fablepool/pidtune.git
cd pidtune
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

The first `pip install` resolves and (if you use a locking workflow such as
`pip-compile` or `uv lock`) generates the lockfile; no lockfile is committed
to this repository by design.

## Quick taste of the intended API

```python
import pidtune as pt

# 1. Describe the process: gain 2.0, time constant 10 s, dead time 1.5 s
model = pt.FOPDT(gain=2.0, time_constant=10.0, dead_time=1.5)

# 2. Tune with AMIGO rules
result = pt.AMIGOTuner(target="pid").tune(model)
print(result.gains)          # PIDGains(kp=..., ki=..., kd=..., form='ideal')

# 3. Simulate the closed loop and check performance
sim = pt.ClosedLoopSimulator(plant=pt.ModelPlant(model),
                             controller=pt.PIDController(result.gains))
response = sim.step(setpoint=1.0, t_final=60.0)
print(pt.metrics.overshoot(response), pt.metrics.settling_time(response))
```

## License

MIT. See `LICENSE` (added with the first implementation milestone).

## Contributing

Read the design documents first — they are the contract for the codebase.
The [roadmap](docs/design/06_roadmap.md) lists the implementation milestones
and where help is most useful.