Developer reference

Use this page as a guide to AutoLyap internals. It is intended for contributors implementing or refactoring core behavior.

Internal APIs can change without deprecation. For stable contracts, use the public docs first.

Start here

1. Read Internal problem-class modules to understand interpolation-condition data contracts.

2. Read Internal algorithm modules to see how algorithm steps are lifted into matrix objects.

3. Read Internal analysis and solver modules to follow SDP assembly and solver execution.

4. Use Internal utility modules as the shared helper reference across all layers.

Documentation map

Public docs (stable API)

If you need to…	Go to…
Define interpolation-based inclusion problems	Problem classes
Select and configure algorithms	Algorithms
Run convergence analyses	Lyapunov analyses
Configure solver backends	Solver backends

Internal docs (implementation details)

If you need to…	Go to…
Work on SDP assembly and solver option normalization	Internal analysis and solver modules
Modify the internal Algorithm contract or matrix/projection accessors	Internal algorithm modules
Change interpolation-condition internals, indices, or inclusion-problem assembly	Internal problem-class modules
Reuse validators, matrix helpers, or backend typing protocols	Internal utility modules

Architecture at a glance

Layer	Core modules	What it owns
Problem definitions	autolyap.problemclass	Interpolation conditions, index semantics, and component validation.
Algorithm lifting	autolyap.algorithms	Conversion of updates into lifted matrix objects (X, Y, U, P, F, E, W).
Analysis assembly	autolyap.iteration_independent, autolyap.iteration_dependent	Construction and solving of SDP certificates from problem and algorithm structure.
Backend normalization	autolyap.solver_options	One-pass normalization of solver options before backend-specific calls.
Shared utilities	autolyap.utils	Validation helpers, matrix helpers, and backend protocol types.

Common extension tasks

Task	Primary entry point	Keep in mind
Add a new algorithm	autolyap.algorithms.algorithm.Algorithm	Implement required matrix/projection accessors consistently.
Add a new interpolation condition	autolyap.problemclass.base._InterpolationCondition.get_data()	Follow the existing autolyap.problemclass condition hierarchy.
Add or modify analysis workflows	autolyap.iteration_independent, autolyap.iteration_dependent	Preserve solver-backend parity across supported backends.
Add validation or backend typing logic	autolyap.utils.validation, autolyap.utils.backend_types	Keep shared checks centralized; avoid per-module duplication.

Invariants and common pitfalls

• Interpolation indices exposed to users are 1-based and strictly validated.

• Keep matrix dimensions aligned across Y, P, and interpolation blocks; shape drift usually appears as SDP assembly failures.

• Normalize solver options exactly once via autolyap.solver_options._normalize_solver_options() before backend-specific solve calls.

• Keep numeric checks in shared validation helpers instead of duplicating them inside algorithm or condition modules.