Initial Docs

[jcallaham]

No description provided.

[Copilot]

Pull request overview

This PR introduces several coordinated feature updates and refactors across backend, frontend, and docs:

Changes:

• Standardizes transfer function parameters to num/den, fixes algebraic-loop detection for scalar numerators, and refines IO marker semantics to use block.label instead of a label parameter.
• Adds robust subsystem extraction and expression re-evaluation behavior (including namespace-based loading), new diagram templates (open-loop/feedback, TF/SS), and utilities like lynx.utils.set_theme and lynx.utils.display_sys.
• Improves React Flow-based rendering and capture (edge-aware fitView, shared config, orthogonal routing/label placement), and significantly restructures documentation (new concepts, examples, and branding assets) in line with “diagram label indexing” and templates.

Reviewed changes

Copilot reviewed 116 out of 119 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/python/unit/test_validation.py	Updates TF tests to use num/den and adds regression test for scalar num not crashing algebraic loop validation.
tests/python/unit/test_signal_extraction.py	Adjusts clone-preservation tests to validate num/den parameter names.
tests/python/unit/test_persistence.py	Aligns TF persistence tests with num/den and adds a new test suite for namespace-based parameter re-evaluation and persistence.
tests/python/unit/test_io_marker.py	Adds regression test ensuring IO marker block.label persists correctly through save/load, reflecting new label semantics.
tests/python/unit/test_expression_reevaluation.py	Updates tests to look for num instead of numerator and confirm expression-based array re-evaluation.
tests/python/unit/test_expression_load_reevaluation.py	New tests documenting current (buggy) load behavior and desired re-evaluation semantics for expressions, including tuple→array handling and real-world cruise-control case.
tests/python/unit/test_export_python_control.py	Switches TF block tests to num/den and keeps behavior verification for python-control export.
tests/python/unit/test_blocks.py	Updates TransferFunctionBlock tests to new num/den API and changes IO marker label tests to use block.label instead of parameter.
tests/python/performance/test_performance.py	Relaxes connection performance threshold (50ms→100ms) and updates complex diagram validation tests to num/den.
tests/python/integration/test_subsystem_extraction.py	Removes older subsystem extraction integration tests in favor of consolidated coverage elsewhere.
tests/python/integration/test_python_control_integration.py	Migrates TF parameters to num/den and adds a mathematically validated sensitivity-function test using get_ss.
tests/python/integration/test_latex_widget_integration.py	Adjusts TF parameter usage in LaTeX widget integration test to num/den.
tests/python/integration/test_label_uniqueness_validation.py	Updates TF labels test for get_ss to use num/den.
tests/python/integration/conftest.py	Ensures shared feedback-loop fixture uses num/den for plant TF.
src/lynx/widget.py	Updates parameter name checks for TF vector expressions (["num","den"]) so widget parsing & validation match backend.
src/lynx/validation/algebraic_loop.py	Changes TF feedthrough detection to read num/den and uses np.atleast_1d to support scalar numerators; preserves state-space D-matrix logic.
src/lynx/utils/plot_themes.py	Renames set_plot_theme→set_theme and updates examples to call via lynx.utils.set_theme; keeps save_themed_plot and themed_plot helpers.
src/lynx/utils/ipython_utils.py	Introduces display_sys(sys) helper leveraging python-control’s _repr_markdown_() for better LaTeX rendering in VS Code/Jupyter.
src/lynx/utils/init.py	Changes utils API to export set_theme and display_sys only, dropping the previous set_plot_theme/save_themed_plot/themed_plot exports (a backward-incompatible change).
src/lynx/templates/open_loop_tf.json	New JSON template for an open-loop TF diagram using num/den and labeled IO markers.
src/lynx/templates/open_loop_ss.json	New JSON template for an open-loop state-space plant with IO markers and labeled ports.
src/lynx/templates/feedback_tf.json	New JSON template for a generic feedback TF architecture (controller+plant, with disturbance and noise IO markers).
src/lynx/templates/feedback_ss.json	New JSON template for a feedback diagram using a state-space plant, with multiple labeled IO markers.
src/lynx/templates/_templates.py	New loader using importlib.resources.files() to expose packaged JSON diagram templates via a DIAGRAM_TEMPLATES dict.
src/lynx/templates/init.py	Exports DIAGRAM_TEMPLATES from the _templates module.
src/lynx/templates/README.md	Documents available JSON diagram templates and Diagram.from_template('name') usage.
src/lynx/expression_eval.py	Extends expression evaluation so comma-separated expressions returning tuples are converted to np.array, ensuring consistent storage for vector parameters.
src/lynx/conversion/signal_extraction.py	Refactors signal resolution to use block.label for IO markers, generates unique input/output names via _make_labels_unique, and wraps get_ss in a warnings filter to ignore unused-output UserWarnings.
src/lynx/conversion/block_converters.py	Updates TF converter to use num/den and passes those directly to ct.tf along with real input/output port IDs.
src/lynx/blocks/transfer_function.py	Renames constructor parameters to num/den, stores them as such in parameters, and updates docstring examples accordingly.
src/lynx/blocks/io_marker.py	Removes the separate block_label concept, sets block.label from the label arg (falling back to id), and ensures IO marker ports are labeled with block.label instead of a label parameter.
src/lynx/blocks/base.py	Adds a weakref _diagram attribute and a set_parameter() method that delegates updates to Diagram.update_block_parameter, enabling labeled-indexing OOP-style parameter changes.
src/lynx/blocks/init.py	Adjusts error text for TF creation to mention num and den, and continues to route IO marker construction through InputMarker/OutputMarker.
src/lynx/init.py	Re-exports ValidationError at package level and leaves edit/render/block exports intact.
specs/017-diagram-label-indexing/spec.md	New feature spec for diagram label-based indexing and related behaviors (uniqueness, exceptions, parameter update via block objects).
specs/017-diagram-label-indexing/research.md	Research document capturing design decisions for label-based indexing, exception reuse, lookup strategy, and weakref parent references.
specs/017-diagram-label-indexing/plan.md	Implementation plan for label indexing and set_parameter, including constitution checks and TDD strategy.
specs/017-diagram-label-indexing/data-model.md	Detailed data model for label indexing, Diagram.__getitem__, and Block.set_parameter, including error scenarios and usage examples.
specs/017-diagram-label-indexing/checklists/requirements.md	Requirements checklist confirming spec completeness and quality for the label-indexing feature.
specs/016-github-pages-docs/tasks.md	Minor corrections to favicon asset names (SVG→ICO) in documentation tasks.
specs/016-github-pages-docs/plan.md	Updates the docs plan to use favicon.ico and adjusts Sphinx config snippets accordingly.
pyproject.toml	Ensures JSON templates (src/lynx/templates/*.json) are included in built distributions.
js/src/utils/reactFlowConfig.ts	New shared configuration module for React Flow (viewport defaults, zoom limits, fitView options, and default edge styling).
js/src/utils/orthogonalRouting.ts	Enhances routing by filtering out sub-pixel-length segments (<1px) to remove floating-point artifacts in orthogonal paths.
js/src/utils/nodeConversion.ts	Centralizes backend-block→ReactFlow-node and connection→edge conversion, sharing logic between DiagramCanvas and CaptureCanvas.
js/src/utils/edgeAwareFitView.ts	Adds utilities to compute bounds including edge waypoints and calculate an edge-aware viewport transform respecting padding and zoom limits.
js/src/utils/connectionLabelPosition.ts	Changes label placement to prefer horizontal segments, ignore short port-offset stubs in bounds, and avoid placing labels on corners; logs diagnostic detail in dev.
js/src/test/factories.ts	Updates test block factory to create TF blocks with num/den.
js/src/test/connectionLabelPosition.test.ts	Adjusts expectations so findSegmentAtX prefers horizontal over vertical segments at corners.
js/src/palette/BlockPalette.tsx	Updates TF palette button to create blocks with num/den defaults.
js/src/capture/captureUtils.ts	Extends capture bounds to include waypoints and lets captureToPng accept an explicit background color (not CSS var) for correct html-to-image rendering.
js/src/capture/CaptureCanvas.tsx	Refactors capture canvas to share node/edge conversion, use edge-aware fitView, compute capture dimensions from content with padding, and respect theme for PNG backgrounds.
js/src/blocks/transfer_function/TransferFunctionParameterEditor.tsx	Rewires editor to work against num/den names and send expressions for those parameters.
js/src/blocks/transfer_function/TransferFunctionParameterEditor.test.tsx	Updates tests to expect num/den parameters and keeps behavior verification intact.
js/src/blocks/transfer_function/TransferFunctionBlock.tsx	Adjusts render logic to read numerator/denominator from num and den parameters.
js/src/DiagramCanvas.tsx	Integrates shared React Flow config, uses edge-aware fitView, central node/edge converters, and prevents double-click zoom on parameter-panel open.
docs/source/quickstart.md	Updates quickstart example plant TF to use num/den and points “Next steps” to the new cruise-control example.
docs/source/index.md	Rebrands index page (hidden h1, logo space), points examples card to cruise control, and updates the toctree to use new concepts and example paths.
docs/source/examples/state-feedback.md	Removes older state-feedback example notebook from the gallery.
docs/source/examples/pid-controller.md	Removes older PI/PID example notebook from the gallery.
docs/source/examples/index.md	Removes the examples gallery index in favor of more focused example pages.
docs/source/examples/cruise-control.md	New MyST+Jupytext example implementing a cruise-control feedback system using templates, diagram["label"], and python-control analysis.
docs/source/examples/basic-feedback.md	Removes the basic feedback example notebook superseded by cruise-control and new concepts.
docs/source/examples/_static/edited-template-light.png	Adds light-theme screenshot of an edited feedback template (Git LFS pointer).
docs/source/examples/_static/edited-template-dark.png	Adds dark-theme counterpart of the edited template screenshot.
docs/source/conf.py	Tweaks Furo options (no top-of-page buttons), switches favicon to ICO, and prepares for a custom title/logo setup.
docs/source/concepts/validation.md	New concise overview of diagram validation rules, common errors, and an example ValidationError usage.
docs/source/concepts/templates.md	New concepts page describing available templates (with light/dark images) and identifiers like "feedback_tf", "open_loop_ss", "cascaded".
docs/source/concepts/index.md	Introduces “Core Concepts” section capturing Diagram/Block/Port/Connection ideas and links to editor/templates/export/validation pages.
docs/source/concepts/export.md	New concept-level description of subsystem export, including template-based cascaded example and get_tf/get_ss usage with IOMarker labels.
docs/source/concepts/editor.md	New page detailing the graphical editor workflow, state synchronization, and static rendering via lynx.render.
docs/source/concepts/_static/*.png	Adds a full set of example diagrams (open-loop, feedback, feedforward, cascaded, filtered; both themes) for the concepts/templates docs (Git LFS pointers).
docs/source/concepts.md	Removes the old monolithic “Core Concepts” page in favor of a structured concepts section.
docs/source/api/validation.md	Updates examples to num/den and adjusts cross-link to the new quickstart location.
docs/source/api/index.md	Refines API overview table (adds block.set_parameter, clarifies blocks/validation descriptions).
docs/source/api/export.md	Simplifies export API page to defer conceptual details to ../concepts/export and updates example links.
docs/source/api/diagram.md	Documents Diagram.from_template, updates TF examples to num/den, and removes long-form example in favor of concise usage.
docs/source/api/blocks.md	Simplifies the blocks comparison table and distinguishes InputMarker/OutputMarker explicitly.
docs/source/_templates/sidebar/brand.html	Custom sidebar brand template showing a logo image and “Lynx” text.
docs/source/_templates/layout.html	Custom layout extending Furo to serve multiple favicon sizes from _static.
docs/source/_templates/autosummary/class.rst	Custom autosummary template for classes, listing methods and attributes.
docs/source/_static/logo.png	Adds main logo asset (Git LFS pointer), replacing separate light/dark logos.
docs/source/_static/logo-light.png	Removes older light-theme logo asset.
docs/source/_static/logo-dark.png	Removes older dark-theme logo asset.
docs/source/_static/favicon.svg	Removes SVG favicon in favor of .ico/PNG variants.
docs/source/_static/favicon-32x32.png	Adds 32×32 PNG favicon asset.
docs/source/_static/favicon-16x16.png	Adds 16×16 PNG favicon asset.
docs/source/_static/custom.css	Extends custom CSS for auto dark-mode support, grid background, hidden titles, improved code/admonition theming, and “only-light/only-dark” image handling.
docs/source/_static/apple-touch-icon.png	Adds Apple touch icon asset.
docs/source/_static/android-chrome-512x512.png	Adds 512×512 Android Chrome icon asset.
docs/source/_static/android-chrome-192x192.png	Adds 192×192 Android Chrome icon asset.
CLAUDE.md	Notes the new “017-diagram-label-indexing” feature in the “Recent Changes” and tech-stack sections.
.gitignore	Adds ignores for JS build output, Sphinx build artifacts, Jupyter caches, plots, and reorganizes existing ignore entries.
.github/workflows/docs.yaml	Enables deployment of built docs to GitHub Pages on pushes to main (removes previous hard if: false).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Variable ki_original is not used.

[Copilot]

Variable ki_current is not used.

[Copilot]

Variable dc_gain_original is not used.

[Copilot]

This method raises ValidationError - should raise a LookupError (KeyError or IndexError) instead.

[Copilot]

Module 'lynx' is imported with both 'import' and 'import from'.

[Copilot]

Import of 'pytest' is not used.

[Copilot]

This import of module json is redundant, as it was previously imported on line 56.