Skip to content

Add stacked layers, dropout, benchmark, and contributor docs - #4

Merged
TravisCao merged 1 commit into
masterfrom
enhance-library
Aug 12, 2026
Merged

Add stacked layers, dropout, benchmark, and contributor docs#4
TravisCao merged 1 commit into
masterfrom
enhance-library

Conversation

@TravisCao

Copy link
Copy Markdown
Owner

Summary

Extends the qlstm library toward torch.nn.LSTM parity and hardens the repo
for contributors, without breaking the existing single-layer API.

Changes

Stacking and regularisation

  • num_layers on QLSTM/LQLSTM stacks recurrent layers. Each layer reads the
    hidden-state sequence of the layer below; output is the top layer's sequence
    and h_n/c_n are shaped (num_layers, batch, hidden_size), as in
    torch.nn.LSTM.
  • dropout applies to the output of every layer except the last.
  • The single-layer path and the layer.cell attribute are unchanged, so
    existing code keeps working.

Tests

  • New coverage for stacked shapes, gradient flow to every layer, stacked initial
    state, the wrong-layer-count error, eval-time dropout determinism, the cell
    property, and constructor validation. Full suite: 18 passed.

Examples

  • examples/benchmark_vs_classical.py runs a fair side-by-side against
    torch.nn.LSTM on the same running-sum task and prints parameter counts and
    train/validation loss. It is a reproducible comparison, not a performance
    claim.

Docs and metadata

  • README documents stacking and links the benchmark; CHANGELOG records the
    changes.
  • Community health files: CONTRIBUTING.md, issue templates, pull-request
    template.
  • Python 3.13 packaging classifier, which CI already tests.

Test plan

  • pytest -q green locally (18 passed).
  • CI runs the same suite on Python 3.10 through 3.13.

Stacking and regularisation:
- num_layers on QLSTM/LQLSTM stacks recurrent layers; each layer reads the
  hidden-state sequence of the layer below, and h_n/c_n are shaped
  (num_layers, batch, hidden_size), matching torch.nn.LSTM.
- dropout applies between stacked layers (every layer except the last).
- The single-layer path and the layer.cell attribute are unchanged, so
  existing code keeps working.

Tests:
- Add coverage for stacked shapes, gradient flow to every layer, stacked
  initial state, the wrong-layer-count error, eval-time dropout determinism,
  the cell property, and constructor validation. Full suite: 18 passed.

Examples:
- examples/benchmark_vs_classical.py runs a fair side-by-side against
  torch.nn.LSTM on the same task and reports parameter counts and losses.

Docs and metadata:
- README documents stacking and the benchmark; CHANGELOG records the changes.
- Add community health files (CONTRIBUTING, issue and pull-request templates).
- Add the Python 3.13 packaging classifier, which CI already tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@TravisCao
TravisCao merged commit 84a5d0b into master Aug 12, 2026
4 checks passed
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