"""Closed-loop and open-loop simulation subpackage.

This subpackage provides everything needed to *exercise* a controller
against a process model (or an arbitrary user-supplied plant) in the
time domain:

``pidtune.simulation.plant``
    Plant abstractions — the runtime, stateful counterpart of the
    declarative process models in :mod:`pidtune.models`.  A
    :class:`~pidtune.simulation.plant.Plant` consumes one control
    sample per call and returns one measurement sample, which is the
    contract the loop engine is built on.

``pidtune.simulation.loop``
    The fixed-step loop engine: :func:`simulate_closed_loop`,
    :func:`simulate_open_loop`, the convenience wrapper
    :func:`setpoint_step_response`, and the
    :class:`~pidtune.simulation.loop.SimulationResult` record that all
    of them return.

``pidtune.simulation.signals``
    Vectorised signal *factories* (step, ramp, pulse, doublet, PRBS,
    sine, noise, ...) used to build setpoint and disturbance
    trajectories declaratively.

Design rationale, sequencing semantics (sample-and-hold ordering,
delay handling, disturbance injection points) and the discretisation
strategy are specified in ``docs/design/04_api_specification.md``
(section "Simulation layer") and ``docs/design/01_architecture.md``.

All public callables in this subpackage are **API stubs** in the
current milestone: signatures, types and docstrings are normative;
bodies raise :class:`NotImplementedError` until the simulation-engine
implementation milestone (see ``docs/design/06_roadmap.md``).
"""

from __future__ import annotations

from .plant import Discretization, FunctionPlant, LinearPlant, Plant
from .loop import (
    SimulationOptions,
    SimulationResult,
    setpoint_step_response,
    simulate_closed_loop,
    simulate_open_loop,
)
from . import signals

__all__ = [
    # plant abstractions
    "Plant",
    "LinearPlant",
    "FunctionPlant",
    "Discretization",
    # loop engine
    "SimulationOptions",
    "SimulationResult",
    "simulate_closed_loop",
    "simulate_open_loop",
    "setpoint_step_response",
    # signal factories (as a module, see pidtune.simulation.signals)
    "signals",
]