physicskit 0.1.0__py3-none-any.whl

physicskit/chaos/visualizers/phase_space.py

@@ -0,0 +1,133 @@
+"""Poincare sections and boundary phase-space (s, sin phi) plots for billiards."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from numpy.typing import ArrayLike
+
+from physicskit.chaos.core.base_system import BilliardSystem
+from physicskit.chaos.visualizers import theme
+
+
+def plot_poincare_section(
+    billiard: BilliardSystem,
+    n_rays: int = 50,
+    n_bounces: int = 200,
+    pos: ArrayLike | None = None,
+    ax: Axes | None = None,
+    seed: int | None = None,
+    **scatter_kwargs: Any,
+) -> tuple[Figure, Axes]:
+    """Scatter-plot the boundary phase space ``(s, sin(phi))`` of a billiard.
+
+    Launches `n_rays` trajectories from an interior point at random angles
+    and collects `n_bounces` reflections from each, pooling all the resulting
+    boundary hits into one Poincare section. Integrable billiards (Circle,
+    Rectangle) trace out smooth invariant curves; chaotic (defocusing)
+    billiards (Sinai, Stadium) fill the section with a dense chaotic sea.
+    Rays are traced in a single call to
+    :meth:`~physicskit.chaos.systems.billiards._RayTracingBilliard.simulate_many_rays`,
+    which parallelizes across rays internally (Numba ``prange``).
+
+    Parameters
+    ----------
+    billiard : BilliardSystem
+        Billiard to sample.
+    n_rays : int, default 50
+        Number of independent trajectories to launch.
+    n_bounces : int, default 200
+        Number of reflections to trace per trajectory.
+    pos : array_like of float, shape (2,), optional
+        Shared launch position ``(x, y)`` for every ray; defaults to
+        ``billiard.sample_interior_point()``. Worth overriding for a billiard
+        whose default interior point is a point of special symmetry -- e.g.
+        :class:`~physicskit.chaos.systems.billiards.CircleBilliard`'s is its exact
+        center, from which *every* ray hits the boundary head-on
+        (``sin(phi) = 0``), collapsing the whole section onto a single line
+        instead of the family of invariant curves an off-center point traces
+        out.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure and axes are created if omitted.
+    seed : int, optional
+        Seed for the random angle generator, for reproducibility.
+    **scatter_kwargs
+        Additional keyword arguments forwarded to ``ax.scatter``.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    """
+    rng = np.random.default_rng(seed)
+    interior = billiard.sample_interior_point() if pos is None else np.asarray(pos, dtype=np.float64)
+    angles = rng.uniform(0.0, 2.0 * np.pi, size=n_rays)
+    result = billiard.simulate_many_rays(interior, angles, n_bounces)
+    s, sin_phi = result["s"], result["sin_phi"]
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(7, 5))
+    else:
+        fig = cast(Figure, ax.figure)
+
+    kwargs: dict[str, Any] = {"s": 0.6, "c": theme.PRIMARY, "alpha": 0.6}
+    kwargs.update(scatter_kwargs)
+    ax.scatter(s, sin_phi, **kwargs)
+    ax.set_xlim(0.0, billiard.perimeter())
+    ax.set_ylim(-1.0, 1.0)
+    ax.set_xlabel("s (boundary arclength)")
+    ax.set_ylabel(r"$\sin\varphi$")
+    ax.set_title(f"{billiard.__class__.__name__} Poincare section")
+    return fig, ax
+
+
+def plot_billiard_trajectory(
+    billiard: BilliardSystem,
+    pos: ArrayLike,
+    vel: ArrayLike,
+    n_bounces: int = 50,
+    ax: Axes | None = None,
+    **plot_kwargs: Any,
+) -> tuple[Figure, Axes]:
+    """Plot a single trajectory bouncing inside the billiard's boundary.
+
+    Parameters
+    ----------
+    billiard : BilliardSystem
+        Billiard to trace the trajectory within.
+    pos : array_like of float, shape (2,)
+        Initial position ``(x, y)``; must lie in the billiard's interior.
+    vel : array_like of float, shape (2,)
+        Initial velocity direction ``(vx, vy)``; normalized internally.
+    n_bounces : int, default 50
+        Number of reflections to trace.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure and axes are created if omitted.
+    **plot_kwargs
+        Additional keyword arguments forwarded to ``ax.plot`` for the
+        trajectory line.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    """
+    boundary = billiard.boundary_polyline()
+    path, _ = billiard.trajectory_segments(pos, vel, n_bounces)
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(6, 6))
+    else:
+        fig = cast(Figure, ax.figure)
+
+    ax.plot(boundary[:, 0], boundary[:, 1], color=theme.STRUCTURE, lw=1.5)
+    kwargs: dict[str, Any] = {"color": theme.ACCENT, "lw": 0.8}
+    kwargs.update(plot_kwargs)
+    ax.plot(path[:, 0], path[:, 1], **kwargs)
+    ax.set_aspect("equal")
+    ax.set_title(f"{billiard.__class__.__name__} trajectory")
+    return fig, ax

physicskit/chaos/visualizers/quantum.py

@@ -0,0 +1,299 @@
+"""Plotting helpers for quantum maps and quantum billiards.
+
+Plots the objects :mod:`physicskit.chaos.quantum` produces -- Floquet eigenphases,
+Husimi phase-space distributions, and billiard eigenfunctions -- following
+the same ``(fig, ax)``-returning, ``ax=`` -accepting convention as the rest
+of :mod:`physicskit.chaos.visualizers`. Deliberately absent: any plot of spectral
+*statistics* (level-spacing histograms, spectral rigidity, and the like) --
+that analysis, and the random-matrix-theory context for it, belongs to the
+separate ``physicskit.rmt`` package, which can consume
+:meth:`~physicskit.chaos.quantum.maps.QuantumKickedRotor.eigenphases`,
+:meth:`~physicskit.chaos.quantum.maps.QuantumBakersMap.eigenphases`, or
+:meth:`~physicskit.chaos.quantum.billiards.QuantumBilliard.wavenumbers` directly.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.animation import FuncAnimation
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from numpy.typing import ArrayLike
+
+from physicskit.chaos.quantum.billiards import QuantumBilliard
+from physicskit.chaos.quantum.maps import QuantumBakersMap, QuantumKickedRotor
+from physicskit.chaos.visualizers import theme
+
+
+def plot_quantum_spectrum(eigenphases: ArrayLike, ax: Axes | None = None, **scatter_kwargs: Any) -> tuple[Figure, Axes]:
+    """Scatter a quantum map's Floquet eigenphases on the unit circle.
+
+    Parameters
+    ----------
+    eigenphases : array_like of float, shape (n,)
+        Eigenphases in radians, e.g. from
+        :meth:`~physicskit.chaos.quantum.maps.QuantumKickedRotor.eigenphases` or
+        :meth:`~physicskit.chaos.quantum.maps.QuantumBakersMap.eigenphases`.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure and axes are created if omitted.
+    **scatter_kwargs
+        Additional keyword arguments forwarded to ``ax.scatter``.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    """
+    eigenphases = np.asarray(eigenphases, dtype=np.float64)
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(6, 6))
+    else:
+        fig = cast(Figure, ax.figure)
+
+    circle = np.linspace(0.0, 2.0 * np.pi, 400)
+    ax.plot(np.cos(circle), np.sin(circle), color=theme.MUTED, lw=0.8, zorder=1)
+    kwargs: dict[str, Any] = {"s": 12, "color": theme.PRIMARY, "zorder": 2}
+    kwargs.update(scatter_kwargs)
+    ax.scatter(np.cos(eigenphases), np.sin(eigenphases), **kwargs)
+    ax.set_aspect("equal")
+    ax.set_xlabel(r"$\cos(\phi)$")
+    ax.set_ylabel(r"$\sin(\phi)$")
+    ax.set_title("Floquet eigenphases")
+    return fig, ax
+
+
+def plot_husimi(
+    q_grid: ArrayLike,
+    p_grid: ArrayLike,
+    husimi: ArrayLike,
+    ax: Axes | None = None,
+    cmap: str = theme.SEQUENTIAL_CMAP,
+    q_label: str = "q",
+    p_label: str = "p",
+    title: str | None = None,
+) -> tuple[Figure, Axes]:
+    """Plot a Husimi phase-space distribution.
+
+    Parameters
+    ----------
+    q_grid, p_grid : array_like of float, shape (resolution, resolution)
+        Phase-space grid, as returned by
+        :func:`~physicskit.chaos.quantum.husimi.husimi_function` (or
+        :meth:`~physicskit.chaos.quantum.maps.QuantumKickedRotor.husimi` /
+        :meth:`~physicskit.chaos.quantum.maps.QuantumBakersMap.husimi`).
+    husimi : array_like of float, shape (resolution, resolution)
+        The Husimi distribution.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure and axes are created if omitted.
+    cmap : str, default theme.SEQUENTIAL_CMAP
+        Colormap name.
+    q_label, p_label : str, default "q", "p"
+        Axis labels.
+    title : str, optional
+        Axes title.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    """
+    q_grid = np.asarray(q_grid, dtype=np.float64)
+    p_grid = np.asarray(p_grid, dtype=np.float64)
+    husimi = np.asarray(husimi, dtype=np.float64)
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(6.5, 6))
+    else:
+        fig = cast(Figure, ax.figure)
+
+    mesh = ax.pcolormesh(q_grid, p_grid, husimi, cmap=cmap, shading="gouraud")
+    fig.colorbar(mesh, ax=ax, label="Husimi intensity")
+    ax.set_xlabel(q_label)
+    ax.set_ylabel(p_label)
+    if title:
+        ax.set_title(title)
+    return fig, ax
+
+
+def plot_billiard_eigenstate(
+    quantum_billiard: QuantumBilliard,
+    eigenfunction: ArrayLike,
+    ax: Axes | None = None,
+    density: bool = False,
+    show_boundary: bool = True,
+) -> tuple[Figure, Axes]:
+    """Plot one eigenfunction of a :class:`~physicskit.chaos.quantum.billiards.QuantumBilliard`.
+
+    Parameters
+    ----------
+    quantum_billiard : QuantumBilliard
+        The quantized billiard the eigenfunction belongs to (used for its
+        grid and boundary outline).
+    eigenfunction : array_like of float, shape (nx, ny)
+        One eigenfunction, e.g. a single row of the array returned by
+        :meth:`~physicskit.chaos.quantum.billiards.QuantumBilliard.eigenstates`; grid
+        points outside the billiard should be ``nan``.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure and axes are created if omitted.
+    density : bool, default False
+        If False (the default), plot the signed wavefunction ``psi`` itself
+        with a diverging colormap, showing nodal lines directly; this is
+        always available since :meth:`~physicskit.chaos.quantum.billiards.QuantumBilliard.eigenstates`
+        solves a real symmetric eigenproblem, so prefer it for a consistent
+        look across regular and chaotic billiards alike. If True, plot the
+        probability density ``|psi|^2`` instead, with a sequential colormap.
+    show_boundary : bool, default True
+        Whether to overlay the billiard's boundary outline.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    """
+    eigenfunction = np.asarray(eigenfunction, dtype=np.float64)
+    x_grid, y_grid = quantum_billiard.grid()
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(6.5, 6))
+    else:
+        fig = cast(Figure, ax.figure)
+
+    if density:
+        field = eigenfunction**2
+        cmap = theme.SEQUENTIAL_CMAP
+        vmin, vmax = 0.0, np.nanmax(field)
+        label = r"$|\psi|^2$"
+    else:
+        field = eigenfunction
+        cmap = theme.DIVERGING_CMAP
+        vmax = np.nanmax(np.abs(field))
+        vmin = -vmax
+        label = r"$\psi$"
+
+    mesh = ax.pcolormesh(x_grid, y_grid, field, cmap=cmap, vmin=vmin, vmax=vmax, shading="auto")
+    fig.colorbar(mesh, ax=ax, label=label)
+
+    if show_boundary:
+        boundary = quantum_billiard.billiard.boundary_polyline()
+        ax.plot(boundary[:, 0], boundary[:, 1], color=theme.STRUCTURE, lw=1.2)
+
+    ax.set_aspect("equal")
+    ax.set_xlabel("x")
+    ax.set_ylabel("y")
+    return fig, ax
+
+
+def plot_weyl_law(quantum_billiard: QuantumBilliard, n_states: int = 30, ax: Axes | None = None) -> tuple[Figure, Axes]:
+    """Compare a billiard's actual eigenvalue counting function to Weyl's law.
+
+    Draws the exact (staircase) count of eigenvalues below each wavenumber
+    alongside the smooth prediction from
+    :meth:`~physicskit.chaos.quantum.billiards.QuantumBilliard.weyl_counting_function`.
+
+    Parameters
+    ----------
+    quantum_billiard : QuantumBilliard
+        The quantized billiard to check.
+    n_states : int, default 30
+        Number of lowest eigenstates to compute and count.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure and axes are created if omitted.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    """
+    wavenumbers = quantum_billiard.wavenumbers(n_states)
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(7, 5))
+    else:
+        fig = cast(Figure, ax.figure)
+
+    counts = np.arange(1, n_states + 1)
+    ax.step(wavenumbers, counts, where="post", color=theme.PRIMARY, label="actual $N(k)$")
+    k_smooth = np.linspace(0.0, wavenumbers[-1] * 1.05, 400)
+    ax.plot(
+        k_smooth,
+        quantum_billiard.weyl_counting_function(k_smooth),
+        color=theme.ACCENT,
+        ls="--",
+        label="Weyl's law",
+    )
+    ax.set_xlabel("k")
+    ax.set_ylabel("N(k)")
+    ax.set_title(f"{quantum_billiard.billiard.__class__.__name__}: eigenvalue counting function")
+    ax.legend(loc="upper left")
+    return fig, ax
+
+
+def animate_husimi_evolution(
+    quantum_map: QuantumKickedRotor | QuantumBakersMap,
+    states: ArrayLike,
+    resolution: int = 80,
+    n_wraps: int = 3,
+    interval: int = 350,
+    cmap: str = theme.SEQUENTIAL_CMAP,
+    title: str | None = None,
+) -> FuncAnimation:
+    """Animate a quantum map state's Husimi distribution evolving, step by step.
+
+    Watching a coherent wavepacket's Husimi distribution spread across phase
+    space -- staying compact and orbit-like where the classical map is
+    regular, filling in a chaotic sea where it is not -- is one of the most
+    direct illustrations of quantum chaos: it shows the quantum-classical
+    correspondence visibly *breaking down*.
+
+    Parameters
+    ----------
+    quantum_map : QuantumKickedRotor or QuantumBakersMap
+        The quantum map `states` were generated from (used for its `husimi`
+        method).
+    states : array_like of complex, shape (n_steps + 1, dim)
+        State at each step, e.g. from
+        :meth:`~physicskit.chaos.quantum.maps.QuantumKickedRotor.evolve` or
+        :meth:`~physicskit.chaos.quantum.maps.QuantumBakersMap.evolve`.
+    resolution : int, default 80
+        Number of grid points along each phase-space axis.
+    n_wraps : int, default 3
+        Number of periodic images summed to periodize the coherent states
+        used by :meth:`~physicskit.chaos.quantum.maps.QuantumKickedRotor.husimi`.
+    interval : int, default 350
+        Delay between animation frames, in milliseconds.
+    cmap : str, default theme.SEQUENTIAL_CMAP
+        Colormap name.
+    title : str, optional
+        Base title; each frame appends its step number.
+
+    Returns
+    -------
+    matplotlib.animation.FuncAnimation
+        Assign it to a variable to keep it alive, and display it with
+        ``plt.show()`` or save it with ``anim.save(...)``.
+    """
+    states = np.asarray(states, dtype=np.complex128)
+    n_steps = states.shape[0]
+
+    q_grid, p_grid, husimi0 = quantum_map.husimi(states[0], resolution=resolution, n_wraps=n_wraps)
+
+    fig, ax = plt.subplots(figsize=(6.5, 6))
+    mesh = ax.pcolormesh(q_grid, p_grid, husimi0, cmap=cmap, shading="gouraud", vmin=0.0, vmax=1.0)
+    fig.colorbar(mesh, ax=ax, label="Husimi intensity")
+    ax.set_xlabel("q")
+    ax.set_ylabel("p")
+    base_title = title or f"{type(quantum_map).__name__} Husimi distribution"
+    title_artist = ax.set_title(f"{base_title} (step 0)")
+
+    def update(frame: int) -> tuple:
+        _, _, husimi = quantum_map.husimi(states[frame], resolution=resolution, n_wraps=n_wraps)
+        mesh.set_array(husimi.ravel())
+        title_artist.set_text(f"{base_title} (step {frame})")
+        return mesh, title_artist
+
+    anim = FuncAnimation(fig, update, frames=n_steps, interval=interval, blit=False)
+    return anim

physicskit/chaos/visualizers/recurrence.py

@@ -0,0 +1,91 @@
+"""Visualizations of Poincare recurrence: recurrence plots and return-time histograms."""
+
+from __future__ import annotations
+
+from typing import cast
+
+import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from numpy.typing import ArrayLike
+
+from physicskit.chaos.utils.recurrence import recurrence_matrix, recurrence_times
+from physicskit.chaos.visualizers import theme
+
+
+def plot_recurrence_matrix(states: ArrayLike, epsilon: float, ax: Axes | None = None) -> tuple[Figure, Axes]:
+    """Plot the classic black-and-white recurrence plot of a trajectory.
+
+    Parameters
+    ----------
+    states : array_like of float, shape (n, dim)
+        Trajectory samples.
+    epsilon : float
+        Neighborhood radius defining a "recurrence".
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure and axes are created if omitted.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    """
+    matrix = recurrence_matrix(states, epsilon)
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(6, 6))
+    else:
+        fig = cast(Figure, ax.figure)
+
+    ax.imshow(matrix, cmap="Greys", origin="lower", interpolation="nearest")
+    ax.set_xlabel("i")
+    ax.set_ylabel("j")
+    ax.set_title(f"Recurrence plot ($\\epsilon$ = {epsilon:g})")
+    return fig, ax
+
+
+def plot_recurrence_times(
+    states: ArrayLike,
+    epsilon: float,
+    reference_idx: int = 0,
+    dt: float = 1.0,
+    bins: int = 40,
+    ax: Axes | None = None,
+) -> tuple[Figure, Axes]:
+    """Plot a histogram of the recurrence-time distribution to a reference point.
+
+    Parameters
+    ----------
+    states : array_like of float, shape (n, dim)
+        Trajectory samples.
+    epsilon : float
+        Neighborhood radius defining a "return".
+    reference_idx : int, default 0
+        Index into `states` of the reference point to measure returns to.
+    dt : float, default 1.0
+        Time between consecutive rows of `states`.
+    bins : int, default 40
+        Number of histogram bins.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure and axes are created if omitted.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    """
+    times = recurrence_times(states, epsilon, reference_idx=reference_idx, dt=dt)
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(7, 5))
+    else:
+        fig = cast(Figure, ax.figure)
+
+    ax.hist(times, bins=bins, color=theme.PRIMARY, alpha=0.8)
+    if times.size:
+        ax.axvline(times.mean(), color=theme.ACCENT, linestyle="--", label=f"mean = {times.mean():.3g}")
+        ax.legend()
+    ax.set_xlabel("recurrence time")
+    ax.set_ylabel("count")
+    ax.set_title(f"Recurrence-time distribution ($\\epsilon$ = {epsilon:g})")
+    return fig, ax

physicskit/chaos/visualizers/section.py

@@ -0,0 +1,161 @@
+"""Poincare sections (surface-of-section crossings) for continuous-time flows.
+
+Unlike :mod:`physicskit.chaos.visualizers.phase_space` (which builds a billiard's
+boundary phase space from its ray-tracing bounces), this module implements
+the original form of the technique Poincare introduced while studying the
+restricted three-body problem: sample a continuous flow only at the instants
+it pierces a fixed surface in state space, turning the ODE's trajectory into
+a lower-dimensional map whose structure -- smooth invariant curves (or a
+handful of points) for regular motion, a scattered "chaotic sea" otherwise --
+is far easier to read than the raw, tangled trajectory.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from numpy.typing import ArrayLike, NDArray
+
+from physicskit.chaos.core.base_system import DynamicalSystem
+from physicskit.chaos.visualizers import theme
+
+
+def poincare_crossings(
+    system: DynamicalSystem,
+    state0: ArrayLike,
+    coord: int,
+    value: float = 0.0,
+    direction: float = 1.0,
+    t_max: float = 200.0,
+    dt: float = 0.001,
+) -> NDArray[np.float64]:
+    """Integrate one trajectory and record its state at every crossing of a
+    fixed surface ``state[coord] == value``.
+
+    Parameters
+    ----------
+    system : DynamicalSystem
+        System to integrate, via its own ``trajectory(state0, dt, n_steps)``.
+    state0 : array_like of float, shape (dim,)
+        Initial state.
+    coord : int
+        Index of the state component that defines the section surface.
+    value : float, default 0.0
+        Value of ``state[coord]`` the surface sits at.
+    direction : float, default 1.0
+        Sign of ``d(state[coord])/dt`` required to keep a crossing (e.g. the
+        default ``1.0`` keeps only crossings where `coord` is increasing,
+        discarding the return crossing on the way back, so each pass through
+        the surface is counted once instead of twice).
+    t_max : float, default 200.0
+        Total integration time.
+    dt : float, default 0.001
+        Fixed integration step size.
+
+    Returns
+    -------
+    ndarray of float, shape (n_crossings, dim)
+        The full state at each qualifying crossing, linearly interpolated
+        between the two bracketing integration steps.
+    """
+    n_steps = int(round(t_max / dt))
+    _, states = system.trajectory(state0=np.asarray(state0, dtype=np.float64), dt=dt, n_steps=n_steps)
+
+    f = states[:, coord] - value
+    crosses = (np.sign(f[:-1]) != np.sign(f[1:])) & (f[:-1] != 0.0)
+    if direction > 0:
+        crosses &= f[1:] > f[:-1]
+    elif direction < 0:
+        crosses &= f[1:] < f[:-1]
+    idx = np.flatnonzero(crosses)
+    if idx.size == 0:
+        return np.empty((0, states.shape[1]))
+
+    f0, f1 = f[idx], f[idx + 1]
+    frac = f0 / (f0 - f1)
+    return states[idx] + frac[:, None] * (states[idx + 1] - states[idx])
+
+
+def plot_poincare_map(
+    system: DynamicalSystem,
+    initial_states: ArrayLike,
+    coord: int = 1,
+    value: float = 0.0,
+    direction: float = 1.0,
+    plot_coords: tuple[int, int] = (0, 2),
+    t_max: float = 200.0,
+    dt: float = 0.001,
+    labels: list[str] | None = None,
+    ax: Axes | None = None,
+    **scatter_kwargs: Any,
+) -> tuple[Figure, Axes]:
+    """Overlay Poincare-section crossings from several initial conditions.
+
+    Each initial condition in `initial_states` is integrated independently
+    and its :func:`poincare_crossings` plotted as its own scatter series
+    (colored from :data:`~physicskit.chaos.visualizers.theme.QUALITATIVE_CMAP`), so
+    a regular orbit's crossings -- collapsing onto a smooth curve, or even a
+    handful of points, for a periodic orbit -- can be compared directly
+    against a chaotic orbit's crossings, which scatter to fill a 2D patch.
+
+    Parameters
+    ----------
+    system : DynamicalSystem
+        System to integrate.
+    initial_states : array_like of float, shape (n_series, dim)
+        Initial states, one per series to overlay.
+    coord : int, default 1
+        Index of the state component that defines the section surface
+        (default ``1``, i.e. ``y`` for a state ``(x, y, vx, vy)``).
+    value : float, default 0.0
+        Value of ``state[coord]`` the surface sits at.
+    direction : float, default 1.0
+        Sign of ``d(state[coord])/dt`` required to keep a crossing; see
+        :func:`poincare_crossings`.
+    plot_coords : tuple of int, default (0, 2)
+        Indices of the two state components to scatter against each other
+        (default: ``x`` vs. ``vx`` for a state ``(x, y, vx, vy)``).
+    t_max : float, default 200.0
+        Total integration time per series.
+    dt : float, default 0.001
+        Fixed integration step size.
+    labels : list of str, optional
+        Legend label for each series; the legend is omitted entirely if not
+        given.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure and axes are created if omitted.
+    **scatter_kwargs
+        Additional keyword arguments forwarded to every ``ax.scatter`` call.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    """
+    initial_states = np.atleast_2d(np.asarray(initial_states, dtype=np.float64))
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(7, 6))
+    else:
+        fig = cast(Figure, ax.figure)
+
+    cmap = plt.get_cmap(theme.QUALITATIVE_CMAP)
+    i0, i1 = plot_coords
+    for i, s0 in enumerate(initial_states):
+        crossings = poincare_crossings(system, s0, coord=coord, value=value, direction=direction, t_max=t_max, dt=dt)
+        if crossings.shape[0] == 0:
+            continue
+        kwargs: dict[str, Any] = {"s": 6, "alpha": 0.7, "color": cmap(i % cmap.N)}
+        if labels is not None:
+            kwargs["label"] = labels[i]
+        kwargs.update(scatter_kwargs)
+        ax.scatter(crossings[:, i0], crossings[:, i1], **kwargs)
+
+    if labels is not None:
+        ax.legend(fontsize=8)
+    ax.set_title(f"{system.__class__.__name__} Poincare section")
+    return fig, ax