Skip to content

docs: build an integrated manual and theory - #69

Open
oameye wants to merge 43 commits into
docs/floquet-stylefrom
docs/manual-theory
Open

oameye wants to merge 43 commits into
docs/floquet-stylefrom
docs/manual-theory

Conversation

@oameye

@oameye oameye commented Sep 8, 2026

Copy link
Copy Markdown
Member

Summary

Reorganize the documentation so the tutorial, manual, theory, and public docstrings each have a distinct role without duplicating the same material.

Manual

Adds compact manual pages for:

  • SLH networks and numerical lowering;
  • virtual input/output pulse modes and propagation delays;
  • output-mode extraction from field correlations;
  • interaction-picture mode evolution.

Public docstrings are embedded at the point where each API concept is introduced and rendered collapsed. The surrounding prose is limited to workflow, modeling choices, ordering, representation changes, and how successive operations fit together.

The numerical-lowering section also preserves the reduced-basis workflow where operators substitutions map a symbolic derivation onto a deliberately smaller numerical Hilbert space.

Theory

Replaces the monolithic theory page with focused theory pages while preserving the independent mathematical content, including:

  • continuous input/output fields and temporal-mode operators;
  • virtual source and receiver cavity couplings;
  • cascade, concatenation, and full feedback-reduction equations;
  • standard SLH component triples;
  • recursive multimode input/output constructions;
  • correlation-kernel mode decomposition and quadrature normalization;
  • finite propagation delay, including short- versus long-delay regimes;
  • the virtual-mode transfer Hamiltonian and general interaction-picture transformation.

The equations follow the package conventions and cite the bibliography from the parent documentation PR.

Docstrings

Strengthens public docstrings for the core SLH interface, composition and feedback, numerical translation, pulse couplings, effective modes, delay couplings, correlation matrices, and interaction-picture utilities. Function signatures, accepted inputs, return semantics, solver forwarding, normalization conventions, and numerical special cases live in the docstrings rather than being repeated in manual prose.

Cleanup

Removes the standalone API, implementation, and monolithic theory pages whose responsibilities are now split between the compact manual, focused theory pages, and source docstrings. The executable end-to-end tutorial remains separate.

This PR changes documentation and docstrings only; it does not intentionally change package behavior. It is stacked on docs/floquet-style.

@oameye
oameye marked this pull request as ready for review September 8, 2026 08:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant