scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/analysis/_large_deviations.py

@@ -0,0 +1,378 @@
+"""Measure large deviations: generating functions, rate functions, cloning, and exponential reweighting."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+import warnings
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import replace
+
+import numpy as np
+import numpy.typing as npt
+from scipy import linalg, special
+
+from ..core.system import System
+from ..engine.problems import ProblemSpec
+from ..engine.runtime import Simulation, Trajectory
+from ..errors import AnalysisError
+from ..types import Array, DataKind
+from ._base import BaseAnalysis
+from .types import Source
+
+MIN_SIZES = 2
+SMALL_POPULATION = 0.1
+MIN_EFFECTIVE_CLONES = 10
+KINDS = ('tilted', 'block', 'cloning', 'histogram', 'reweight')
+SETTINGS = {
+    'tilted': {'weights', 'tilts', 'values'},
+    'block': {'tilts', 'block', 'dt', 'values'},
+    'cloning': {'observable', 'tilts', 'values', 'population', 'interval', 'until', 'random_state', 'simulation'},
+    'histogram': {'bins', 'value_range'},
+    'reweight': {'log_weights'},
+}
+"""Settings every kind reads, besides `kind` and `variables`."""
+
+DATA_KINDS = {
+    'tilted': DataKind.PATH,
+    'block': DataKind.SERIES,
+    'cloning': DataKind.PATH,
+    'histogram': DataKind.ENSEMBLE,
+    'reweight': DataKind.ENSEMBLE,
+}
+
+
+class LargeDeviationAnalysis(BaseAnalysis):
+    """Large deviations of a time-additive observable or of an order parameter, of one kind.
+
+    The kinds estimate the scaled cumulant generating function `lambda(k)` at the `tilts`, or the rate function `I`:
+
+    - `'tilted'`: exactly, for a counting observable of a jump process that adds `weights[i, j]` at every jump from
+      `i` to `j`, as the largest eigenvalue of the tilted generator `rates * exp(k weights) - diag(escape rates)` of
+      the rate matrix. A diagonal rate counts jumps that keep the state, such as the events of a Poisson process.
+    - `'block'`: from blocks of `block` steps of one long run of the increments of the observable, as
+      `ln <exp(k A)> / (block dt)`.
+    - `'cloning'`: by the fixed-population cloning of Giardinà, Kurchan, and Peliti, which advances every clone of a
+      system by `interval` through the simulation's steppers, weights it by `exp(k A)` for the increment `A` of the
+      observable, and resamples the population by the weights. The system is compiled once, and every segment restarts
+      the clock at zero, so the laws must not depend on time explicitly. A warning names a population whose effective
+      size falls below a tenth of the clones or below 10 clones.
+    - `'histogram'`: the rate function of `P_N(m) ≍ exp(-N I(m))` from the samples of an order parameter at several
+      sizes `N`, fitting `-ln P_N` linearly in `N` in every bin.
+    - `'reweight'`: samples reweighted to another law by the logarithms of the likelihood ratios, such as `beta dh M`.
+
+    With `values`, the generating function kinds also give the rate function, its Legendre transform
+    `I(a) = max_k (k a - lambda(k))` over the tilts.
+
+    Args:
+        kind:
+            The estimate, one of the kinds above.
+
+        variables:
+            The series of a trajectory whose values are the increments of `'block'`, or `None` for the first one.
+
+        weights:
+            The increment of the observable at every jump of `'tilted'`.
+
+        tilts:
+            The values of the tilt `k`.
+
+        values:
+            The values `a` of the observable per unit time of the rate function, or `None` for none.
+
+        block:
+            The number of steps of every block.
+
+        dt:
+            The time of one step.
+
+        observable:
+            The dotted name of a state whose increment over each interval is the observable, such as a counter, or a
+            function of the trajectory of one interval that returns the increment.
+
+        population:
+            The number of clones.
+
+        interval:
+            The time between two selection steps.
+
+        until:
+            The simulated time of every clone, a multiple of the interval.
+
+        random_state:
+            The seed of the clones and of the selection.
+
+        simulation:
+            Other settings of `Simulation`, such as `solver` or `dt`.
+
+        bins:
+            The number of bins or their edges of `'histogram'`.
+
+        value_range:
+            The range of the bins, or `None` for the range of all samples.
+
+        log_weights:
+            The logarithm of the ratio of the new to the old probability of every sample.
+
+    Attributes:
+        rates_:
+            The rate matrix of `'tilted'`.
+
+        increments_:
+            The increments of `'block'`.
+
+        system_:
+            The system or its compiled problem of `'cloning'`.
+
+        samples_:
+            The samples at every size of `'histogram'`.
+
+        observations_:
+            The samples of `'reweight'`.
+
+        tilts_:
+            The tilts of the generating function.
+
+        scgf_:
+            The scaled cumulant generating function at every tilt.
+
+        effective_population_:
+            The smallest effective number of clones over the selection steps at every tilt, `(Σ w)² / Σ w²`.
+
+        values_:
+            The values of the rate function, the centres of the bins of `'histogram'`.
+
+        rate_function_:
+            The rate function at every value, 0 at its minimum and `nan` where a size left the bin empty for
+            `'histogram'`.
+
+        weights_:
+            The normalized weight of every sample of `'reweight'`.
+
+        mean_:
+            The weighted mean of the samples of `'reweight'`.
+
+        effective_size_:
+            The effective number of samples `1 / Σ w²` of `'reweight'`.
+
+    Examples:
+        >>> import numpy as np
+        >>> from skcomplex.analysis import LargeDeviationAnalysis
+        >>> tilted = LargeDeviationAnalysis(weights=[[1.0]], tilts=[0.0, 1.0])
+        >>> tilted.check().prepare([[2.0]]).run().scgf_.round(4).tolist()
+        [0.0, 3.4366]
+        >>> tilts = np.linspace(-3, 3, 6001)
+        >>> rate = LargeDeviationAnalysis(weights=[[1.0]], tilts=tilts, values=[3.0])
+        >>> round(float(rate.check().prepare([[2.0]]).run().rate_function_[0]), 4)
+        0.2164
+        >>> LargeDeviationAnalysis('reweight', log_weights=[0.0, 0.0]).check().prepare([-1.0, 1.0]).run().mean_
+        0.0
+    """
+
+    def __init__(
+        self,
+        kind: str = 'tilted',
+        variables: Sequence[str] | None = None,
+        *,
+        weights: npt.ArrayLike | None = None,
+        tilts: float | npt.ArrayLike = 1.0,
+        values: npt.ArrayLike | None = None,
+        block: int = 10,
+        dt: float = 1.0,
+        observable: str | Callable[[Trajectory], float] | None = None,
+        population: int = 1000,
+        interval: float = 1.0,
+        until: float = 20.0,
+        random_state: int | None = None,
+        simulation: Mapping[str, object] | None = None,
+        bins: int | npt.ArrayLike = 41,
+        value_range: tuple[float, float] | None = None,
+        log_weights: npt.ArrayLike | None = None,
+    ) -> None:
+        self.kind = kind
+        self.variables = variables
+        self.weights = weights
+        self.tilts = tilts
+        self.values = values
+        self.block = block
+        self.dt = dt
+        self.observable = observable
+        self.population = population
+        self.interval = interval
+        self.until = until
+        self.random_state = random_state
+        self.simulation = simulation
+        self.bins = bins
+        self.value_range = value_range
+        self.log_weights = log_weights
+
+    def _check_needed(self, name: str) -> None:
+        """Raise an error for a setting the kind needs that is not given."""
+        if getattr(self, name) is None:
+            error_msg = f'{type(self).__name__} of kind {self.kind!r} needs {name}. Give it.'
+            raise AnalysisError(error_msg)
+
+    def _check(self) -> None:
+        """Validate the kind, the settings each kind needs, and the cloning schedule."""
+        self._check_choice('kind', self.kind, KINDS)
+        self._check_settings('kind', SETTINGS[self.kind] | {'variables'})
+        needed = {'tilted': 'weights', 'cloning': 'observable', 'reweight': 'log_weights'}
+        if self.kind in needed:
+            self._check_needed(needed[self.kind])
+        steps = round(self.until / self.interval)
+        if self.population < MIN_SIZES or steps < 1 or not np.isclose(steps * self.interval, self.until):
+            error_msg = (
+                f'Cloning needs at least {MIN_SIZES} clones and a duration that is a positive multiple of the '
+                f'interval, but got {self.population} clones, the duration {self.until}, and the interval '
+                f'{self.interval}.'
+            )
+            raise AnalysisError(error_msg)
+        if self.block < 1 or self.dt <= 0:
+            error_msg = f'{type(self).__name__} has block={self.block!r} and dt={self.dt!r}. Use positive values.'
+            raise AnalysisError(error_msg)
+
+    def _get_data_kind(self) -> DataKind:
+        """Return the path kind for jump processes, the series kind for blocks, and the ensemble kind for samples."""
+        return DATA_KINDS[self.kind]
+
+    def _prepare(self, source: Source | ProblemSpec | Mapping[int, npt.ArrayLike]) -> None:
+        """Read the rate matrix, the increments, the system, or the samples the kind estimates from."""
+        if self.kind == 'tilted':
+            self.rates_ = np.asarray(source, dtype=float)
+        elif self.kind == 'block':
+            self.increments_ = self._read_series(source, self.variables).values[:, 0].astype(float)
+        elif self.kind == 'cloning':
+            if not isinstance(source, System | ProblemSpec):
+                error_msg = (
+                    f'{type(self).__name__} of kind cloning reads a system or its problem, not {type(source).__name__}.'
+                )
+                raise AnalysisError(error_msg)
+            self.system_ = source
+        elif self.kind == 'histogram':
+            if not isinstance(source, Mapping):
+                error_msg = f'{type(self).__name__} of kind histogram reads a mapping of every size to its samples.'
+                raise AnalysisError(error_msg)
+            self.samples_ = {size: np.asarray(source[size], dtype=float) for size in sorted(source)}
+        else:
+            self.observations_ = np.asarray(source, dtype=float)
+
+    def _run_tilted(self) -> None:
+        """Compute the largest eigenvalue of the tilted generator at every tilt."""
+        increments = np.asarray(self.weights, dtype=float)
+        escape = np.diag(self.rates_.sum(axis=1))
+        self.scgf_ = np.asarray(
+            [linalg.eigvals(self.rates_ * np.exp(tilt * increments) - escape).real.max() for tilt in self.tilts_],
+        )
+
+    def _run_block(self) -> None:
+        """Compute the generating function over the blocks of the run."""
+        array = self.increments_
+        count = array.size // self.block
+        if count < MIN_SIZES:
+            error_msg = (
+                f'The run of {array.size} steps holds fewer than 2 blocks of {self.block} steps. Use shorter blocks.'
+            )
+            raise AnalysisError(error_msg)
+        sums = array[: count * self.block].reshape(count, self.block).sum(axis=1)
+        self.scgf_ = (special.logsumexp(np.outer(self.tilts_, sums), axis=1) - np.log(count)) / (self.block * self.dt)
+
+    def _clone(self, tilt: float) -> tuple[float, float]:
+        """Return the generating function at one tilt and the smallest effective population, by cloning."""
+        observable = self.observable
+        if observable is None:
+            error_msg = f'{type(self).__name__} of method cloning needs the observable whose increments it tilts.'
+            raise AnalysisError(error_msg)
+        population, steps = self.population, round(self.until / self.interval)
+        rng = np.random.default_rng(self.random_state)
+        settings = {'dt': self.interval, **(self.simulation or {})}
+        simulation = Simulation(self.system_).set_params(**settings).check().prepare().run(until=self.interval)
+        problem = simulation.problem_
+        states = np.tile(problem.initial_state, (population, 1))
+        log_growth, effective = 0.0, float(population)
+        for _ in range(steps):
+            increments = np.empty(population)
+            for index in range(population):
+                start = replace(problem, initial_state=states[index].copy())
+                seed = int(rng.integers(2**31 - 1))
+                simulation = (
+                    Simulation(start, random_state=seed)
+                    .set_params(**settings)
+                    .check()
+                    .prepare()
+                    .run(until=self.interval)
+                )
+                increments[index] = self._increment(observable, simulation.trajectory_)
+                states[index] = np.asarray(simulation.trajectory_.states)[-1]
+            logs = tilt * increments
+            log_growth += float(special.logsumexp(logs) - np.log(population))
+            weights = np.exp(logs - special.logsumexp(logs))
+            effective = min(effective, float(1 / np.sum(weights**2)))
+            states = states[rng.choice(population, size=population, p=weights)]
+        if effective < max(population * SMALL_POPULATION, MIN_EFFECTIVE_CLONES):
+            warnings.warn(
+                f'The effective population of the cloning fell to {effective:.1f} of {population} clones, so the '
+                'estimate may be biased. Use more clones or a shorter interval.',
+                RuntimeWarning,
+                stacklevel=2,
+            )
+        return log_growth / self.until, effective
+
+    def _run_histogram(self) -> None:
+        """Compute the rate function from the histograms of the sizes."""
+        sizes = list(self.samples_)
+        if len(sizes) < MIN_SIZES:
+            error_msg = f'A rate function from histograms needs at least {MIN_SIZES} sizes, not {len(sizes)}.'
+            raise AnalysisError(error_msg)
+        arrays = list(self.samples_.values())
+        edges = np.histogram_bin_edges(np.concatenate(arrays), bins=self.bins, range=self.value_range)
+        densities = np.asarray([np.histogram(array, bins=edges, density=True)[0] for array in arrays])
+        with np.errstate(divide='ignore'):
+            logs = -np.log(densities)
+        rates = np.full(edges.size - 1, np.nan)
+        for index in range(rates.size):
+            column = logs[:, index]
+            finite = np.isfinite(column)
+            if finite.sum() >= MIN_SIZES:
+                rates[index] = np.polyfit(np.asarray(sizes, dtype=float)[finite], column[finite], 1)[0]
+        self.values_ = (edges[1:] + edges[:-1]) / 2
+        self.rate_function_ = rates - np.nanmin(rates)
+
+    def _run_reweight(self) -> None:
+        """Compute the weights of the samples and the reweighted mean."""
+        logs = np.asarray(self.log_weights, dtype=float)
+        self.weights_ = np.exp(logs - special.logsumexp(logs))
+        self.mean_ = float(np.sum(self.weights_ * self.observations_))
+        self.effective_size_ = float(1 / np.sum(self.weights_**2))
+
+    def _run(self, inputs: object = None) -> None:
+        """Compute the estimate of the kind, and the rate function at the values."""
+        if self.kind == 'histogram':
+            self._run_histogram()
+            return
+        if self.kind == 'reweight':
+            self._run_reweight()
+            return
+        self.tilts_ = np.atleast_1d(np.asarray(self.tilts, dtype=float))
+        if self.kind == 'tilted':
+            self._run_tilted()
+        elif self.kind == 'block':
+            self._run_block()
+        else:
+            estimates = [self._clone(float(tilt)) for tilt in self.tilts_]
+            self.scgf_ = np.asarray([scgf for scgf, _ in estimates])
+            self.effective_population_ = np.asarray([effective for _, effective in estimates])
+        if self.values is not None:
+            self.values_ = np.atleast_1d(np.asarray(self.values, dtype=float))
+            self.rate_function_ = self._legendre_transform(self.tilts_, self.scgf_, self.values_)
+
+    @staticmethod
+    def _increment(observable: str | Callable[[Trajectory], float], trajectory: Trajectory) -> float:
+        """Return the increment of a time-additive observable over one segment of a clone."""
+        if callable(observable):
+            return float(observable(trajectory))
+        values = np.asarray(trajectory.values(observable), dtype=float)
+        return float(np.sum(values[-1] - values[0]))
+
+    @staticmethod
+    def _legendre_transform(tilts: Array, function: Array, values: Array) -> Array:
+        """Return the rate function `I(a) = max_k (k a - lambda(k))` of a generating function sampled on a grid."""
+        return np.max(np.outer(values, tilts) - function[None, :], axis=1)

skcomplex/analysis/_linearization.py

@@ -0,0 +1,231 @@
+"""Linearise a system into state-space matrices, with its controllability, observability, and optimal gain."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Mapping, Sequence
+
+import numpy as np
+import numpy.typing as npt
+from sage.all__sagemath_symbolics import SR, Expression
+from scipy.linalg import solve_continuous_are
+
+from ..engine.problems import ProblemSpec
+from ..errors import AnalysisError, ValidationError
+from ..types import Array, DataKind, FormKind
+from ._base import BaseAnalysis
+from ._stability import StabilityAnalysis
+from .types import Source
+
+
+class LinearizationAnalysis(BaseAnalysis):
+    """Linear state-space model `x' = A x + B u`, `y = C x + D u` of a system near an operating point.
+
+    The matrices are the Jacobians of the rates and of the outputs, derived symbolically and evaluated at the
+    operating point. The controls are adaptive parameters, named by their dotted names, and the outputs are states or
+    controls. The system is controllable when the rank of `[B, AB, ..., A^(n-1) B]` equals the number of states, and
+    observable when the rank of `[C; CA; ...; C A^(n-1)]` does. With weights of the states and the controls, the gain
+    `K` of the linear-quadratic regulator `u = -K x` minimises `∫ (x' Q x + u' R u) dt` over an infinite horizon, from
+    the continuous algebraic Riccati equation that SciPy solves.
+
+    Args:
+        controls:
+            The dotted names of the adaptive parameters that are inputs, or `None` for the bounded ones.
+
+        outputs:
+            The dotted names of the states and controls that are outputs, or `None` for every state.
+
+        at:
+            The values of states and controls at the operating point, by dotted name, or `None` for the initial values.
+
+        state_weights:
+            The weight `Q` of the states in the cost of the regulator, a symmetric positive semidefinite matrix, or
+            `None` for no regulator.
+
+        control_weights:
+            The weight `R` of the controls in the cost of the regulator, a symmetric positive definite matrix, or
+            `None` for no regulator.
+
+    Attributes:
+        problem_:
+            The compiled problem.
+
+        A_:
+            The state matrix, the Jacobian of the rates by the states.
+
+        B_:
+            The input matrix, the Jacobian of the rates by the controls.
+
+        C_:
+            The output matrix, the Jacobian of the outputs by the states.
+
+        D_:
+            The feedthrough matrix, the Jacobian of the outputs by the controls.
+
+        states_:
+            The names of the state components, in the order of the rows of `A_`.
+
+        controls_:
+            The names of the controls, in the order of the columns of `B_`.
+
+        outputs_:
+            The names of the outputs, in the order of the rows of `C_`.
+
+        controllability_:
+            The rank of the controllability matrix.
+
+        observability_:
+            The rank of the observability matrix.
+
+        gain_:
+            The gain of the regulator, one row per control and one column per state, or `None` without weights.
+
+    Examples:
+        >>> from typing import Annotated
+        >>> from skcomplex.analysis import LinearizationAnalysis
+        >>> from skcomplex.core.elements import Element
+        >>> from skcomplex.core.laws import RateLaw
+        >>> from skcomplex.specs import ParameterSpec, StateSpec
+        >>> from skcomplex.core.system import System
+        >>> class CartElement(Element):
+        ...     def __init__(
+        ...         self,
+        ...         label,
+        ...         x: Annotated[float, StateSpec()] = 0.0,
+        ...         v: Annotated[float, StateSpec()] = 0.0,
+        ...         force: Annotated[float, ParameterSpec(adaptive=True, bounds=(-1, 1))] = 0.0,
+        ...     ):
+        ...         super().__init__(label)
+        ...         self.x = x
+        ...         self.v = v
+        ...         self.force = force
+        ...
+        ...     def _get_laws(self, namespace):
+        ...         return [RateLaw(namespace.x, namespace.v), RateLaw(namespace.v, namespace.force)]
+        >>> analysis = LinearizationAnalysis().check().prepare(System(elements=[CartElement('cart')])).run()
+        >>> analysis.B_.tolist(), analysis.controllability_
+        ([[0.0], [1.0]], 2)
+    """
+
+    def __init__(
+        self,
+        controls: Sequence[str] | None = None,
+        outputs: Sequence[str] | None = None,
+        at: Mapping[str, float] | None = None,
+        *,
+        state_weights: npt.ArrayLike | None = None,
+        control_weights: npt.ArrayLike | None = None,
+    ) -> None:
+        self.controls = controls
+        self.outputs = outputs
+        self.at = at
+        self.state_weights = state_weights
+        self.control_weights = control_weights
+
+    def _check(self) -> None:
+        """Check that the weights of the regulator are given together."""
+        if (self.state_weights is None) != (self.control_weights is None):
+            error_msg = (
+                f'{type(self).__name__} computes the regulator from both state_weights and control_weights. Give both, '
+                'or neither.'
+            )
+            raise AnalysisError(error_msg)
+
+    def _get_data_kind(self) -> DataKind:
+        """Return the system kind."""
+        return DataKind.SYSTEM
+
+    def _prepare(self, source: Source) -> None:
+        """Compile the system of the source, checking that it runs in continuous time."""
+        problem = self._compiled_problem(self._read_system(source), 'Linearization')
+        if problem.form != FormKind.ODE:
+            error_msg = (
+                f'{type(self).__name__} takes systems under continuous time, but the system is a {problem.form}.'
+            )
+            raise ValidationError(error_msg)
+        self.problem_ = problem
+
+    def _run(self, inputs: object = None) -> None:
+        """Derive the state-space matrices, their ranks, and the gain of the regulator."""
+        problem = self.problem_
+        adaptive = problem.adaptive_parameters
+        chosen = (
+            [name for name, item in adaptive.items() if item.bounds is not None]
+            if self.controls is None
+            else self.controls
+        )
+        inputs = self._checked_names(chosen, list(adaptive), 'adaptive parameters')
+        dynamics = StabilityAnalysis._dynamics_of(problem)
+        states = [name for name in dynamics.names if name not in inputs]
+        observed = self._checked_names(
+            states if self.outputs is None else self.outputs,
+            [*states, *inputs],
+            'states or controls',
+        )
+        values = self._initial_values(problem)
+        values.update(self.at or {})
+        by_name = dict(zip(dynamics.names, dynamics.symbols, strict=True))
+        rates = dict(zip(dynamics.names, dynamics.rates, strict=True))
+        point = {by_name[name]: float(value) for name, value in values.items() if name in by_name}
+        point.update(dynamics.parameters)
+        point[dynamics.time] = 0.0
+        self.A_ = self._evaluated([[rates[row].diff(by_name[column]) for column in states] for row in states], point)
+        self.B_ = self._evaluated([[rates[row].diff(by_name[column]) for column in inputs] for row in states], point)
+        self.C_ = np.array([[float(row == column) for column in states] for row in observed]).reshape(
+            len(observed),
+            len(states),
+        )
+        self.D_ = np.array([[float(row == column) for column in inputs] for row in observed]).reshape(
+            len(observed),
+            len(inputs),
+        )
+        self.states_ = tuple(states)
+        self.controls_ = tuple(inputs)
+        self.outputs_ = tuple(observed)
+        self.controllability_ = self._controllability(self.A_, self.B_)
+        self.observability_ = self._controllability(self.A_.T, self.C_.T)
+        self.gain_ = (
+            None
+            if self.state_weights is None or self.control_weights is None
+            else self._lqr(self.A_, self.B_, self.state_weights, self.control_weights)
+        )
+
+    @staticmethod
+    def _initial_values(problem: ProblemSpec) -> dict[str, float]:
+        """Return the initial value of every state component by name."""
+        return {
+            name: float(problem.initial_state[entry.start + column])
+            for entry in problem.states.entries
+            for column, name in enumerate(entry.component_names)
+        }
+
+    @staticmethod
+    def _checked_names(names: Sequence[str], known: Sequence[str], description: str) -> list[str]:
+        """Return names after checking that each is one of the known names."""
+        unknown = [name for name in names if name not in known]
+        if unknown:
+            error_msg = f'{", ".join(unknown)} are not {description}. Available names are: {", ".join(known)}.'
+            raise AnalysisError(error_msg)
+        return list(names)
+
+    @staticmethod
+    def _evaluated(rows: list[list[Expression]], values: Mapping[Expression, float]) -> Array:
+        """Return a matrix of expressions evaluated at values of their symbols."""
+        columns = len(rows[0]) if rows else 0
+        return np.array([[float(SR(item).subs(values)) for item in row] for row in rows]).reshape(len(rows), columns)
+
+    @staticmethod
+    def _controllability(state: Array, inputs: Array) -> int:
+        """Return the rank of the controllability matrix `[B, AB, ..., A^(n-1) B]`."""
+        blocks = [inputs]
+        for _ in range(state.shape[0] - 1):
+            blocks.append(state @ blocks[-1])
+        return int(np.linalg.matrix_rank(np.hstack(blocks)))
+
+    @staticmethod
+    def _lqr(state: Array, inputs: Array, state_weights: npt.ArrayLike, control_weights: npt.ArrayLike) -> Array:
+        """Return the gain `K = R^-1 B' P` of the linear-quadratic regulator, from the Riccati solution `P` of SciPy."""
+        weights = np.atleast_2d(np.asarray(control_weights, dtype=float))
+        riccati = solve_continuous_are(state, inputs, np.atleast_2d(np.asarray(state_weights, dtype=float)), weights)
+        gain: Array = np.linalg.solve(weights, inputs.T @ riccati)
+        return gain