Documentation Log

This page records documentation-facing changes for the SILVA Networks package. It is intentionally scoped to this package documentation and does not modify the paper, book sources, or production code outside the package.

August 11, 2026 SILVA Networks 1.2.2 release preparation

Version 1.2.2

Prepared the expanded package release with the new solver-learning, source-equilibrium, quantum-equilibrium, evidence, and experiment-protocol material connected to the public API, tutorials, and release checks.

Area	Change
Public surface	Expanded the canonical family guide to 64 routes and added the new package modules, examples, experiment protocols, and API pages.
Notebook curriculum	Added package labs 48-74 with repository, documentation, and Colab copies aligned to the package API.
Release metadata	Advanced package, citation, archive, documentation, notebook footer, publishing, and source-tag metadata to 1.2.2.
Validation path	Extended the release audit and notebook/docs checks for the 109-notebook public curriculum.

August 8, 2026 SILVA Networks 1.2.1 patch release

Version 1.2.1

Prepared a patch release for package-page rendering consistency while preserving the 1.2.0 package surface.

Area	Change
README rendering	Replaced the public README equilibrium display with a renderer-safe plain equation block for GitHub, PyPI, and archive pages.
Release metadata	Advanced package, citation, archive, documentation, notebook footer, and source-tag metadata to 1.2.1.
Validation path	Re-ran the release audit and package rendering checks before tagging the patch release.

August 8, 2026 SILVA Networks 1.2.0 release preparation

Version 1.2.0

Prepared the expanded public package surface for the next feature release while keeping the existing history, citation chain, notebooks, and archive identifiers aligned with the package version.

Area	Change
Release metadata	Advanced the package, import surface, CFF record, Zenodo metadata, changelog, source tag, README, references, and BibTeX software citation to 1.2.0.
Public surface	Kept the expanded structured, emerging, source-data, benchmark, notebook, example, and audit additions in the release candidate.
Validation path	Updated release-readiness and publishing instructions for the validated v1.2.0 tag, PyPI target, GitHub Release, and Zenodo archive flow.

August 7, 2026 Complete worked studies and executed notebook diagnostics

Derivation, Results, and Scale Expansion

Expanded the existing examples and notebooks while retaining their prior text, cells, outputs, figures, abstractions, and navigation.

Area	Change
Worked examples	Added complete programs, four linked derivations, measured compact output, result interpretation, and scale/full-data routes to all 25 worked pages.
API guides	Expanded 15 compact reference pages with operational equations, tensor and diagnostic contracts, complete programs, measured output, replacement points, and scale axes.
Learning guides	Added complete result-bearing studies to fixed points, custom layers, interactive diagnostics, advanced data contracts, and stacked device-aware architectures.
Notebook curriculum	Added an analytic equilibrium, convergence-rate derivation, exact sensitivity, gradient check, parameter sweep, and interpretation layer to all 82 canonical notebooks.
Executed evidence	Stored results from 946 code cells, 906 output blocks, and 216 embedded 300-dpi figures, with at least one figure in every canonical notebook.
Publication copies	Added output-only synchronization so rendered and portable notebooks retain canonical results without losing citation or navigation cells.
Regression checks	Added coverage for all 25 standalone programs, every worked-page depth contract, every notebook diagnostic block, stored outputs, figures, and mirror equality.

August 6, 2026 Attributed real-data reproduction layer

Source Data, Receipts, and Executed Labs

Expanded the structured family material without removing its known-solution derivations, outputs, or plots.

Area	Change
Source adapters	Added deterministic vision, Planetoid, optical-flow, public-motion, and Darcy-field loaders.
Source records	Added receipts with indices, split, preprocessing, access, version, and tensor-content SHA-256.
Snapshots	Added verified compact CIFAR-10, Cora, and real-motion records with a machine-readable manifest.
Notebooks	Extended labs 36-41 with real-tensor construction, gradients, diagnostics, non-benchmark scope, citations, outputs, and 300 DPI plots.
Scale guidance	Added compact and source-scale JSON profiles, storage planning, official split guidance, and complete experiment checklists.
Tests	Added deterministic, checksum, graph-mask, flow-resizing, Darcy-loading, snapshot-integrity, and six-family integration coverage.

August 5, 2026 SILVA Networks 1.1.0 extension and reproduction release

Version 1.1.0

Made the complete SILVA construction contract inspectable and executable from custom transition modules through source-aware compact and scaled reproduction.

Area	Change
Extensibility	Added transition validation, configurable initializer/transition/readout composition, real family constructors, and inspectable signatures.
Reproduction	Added equations, sources, repositories, data obligations, metrics, evidence paths, verification levels, and scale-aware builders for all 44 canonical families.
Emerging families	Added consistency distillation, mixed-boundary graph roots, implicit Fourier materials, forward skinning, mesh relaxation, physics-guided diffusion, TherINO, and fixed-point diffusion inside the SILVA construction contract.
Diffusion restoration	Added complete reverse-step and observation-consistency hooks inside the joint SILVA trajectory.
Learning	Expanded all 82 canonical notebooks and the navigable Markdown pages with derivations, module replacement, equivalence, gradients, reproduction, and scaling paths.
Executable evidence	Added eight focused family labs with compact known-solution data, retained numerical outputs, and 300 DPI simulation plots.
Validation	Executed every canonical notebook, expanded tests and audits, stabilized generated notebook text, and upgraded workflow actions.

August 5, 2026 SILVA Networks 1.1.0 release preparation

Version Metadata Preparation

Synchronized package, citation, archive, notebook, and publication metadata for the first feature release after 1.0.0. The living software citation now uses the Zenodo concept DOI, while the immutable 1.0.0 version DOI remains in the release history.

Area	Change
Versioning	Advanced the package, import surface, CFF record, Zenodo metadata, changelog, and user-facing citations to 1.1.0.
Citation durability	Moved the current software citation to the all-versions concept DOI so it resolves to the latest archived release.
Notebook consistency	Updated repository, documentation, and portable notebook copies together with their generators.
Release controls	Extended the release audit to require matching package, CFF, Zenodo, changelog, README, references, and BibTeX versions.

August 4, 2026 All-family scaling, matrix-free execution, and full-scale learning path

Full-Scale SILVA Pass

Connected all 44 canonical SILVA families to executable scale controls while keeping the existing constructors and ordinary runtime defaults compatible.

Area	Change
Family guidance	Added data contracts, primary references, research repositories, benchmark routes, scale controls, and extension points for all canonical families.
Numerical scaling	Added factorized monotone graph maps, fused or chunked injected attention, chunked exact measure discrepancies, matrix-free physics derivatives, and Newton-Krylov DAE stages.
Training	Added mixed precision, gradient accumulation, distributed synchronization control, scaler checkpoint state, and sampler epochs.
Data	Added atomic tensor shards, a lazy one-shard dataset, and ordinary or distributed loader construction.
Learning	Added the Full-Scale SILVA derivation guide, complete training example, scaling API pages, and executable notebook 26.
Citations	Added numbered links for the runtime APIs and extended the method-to-citation matrix.
Validation	Added all-family coverage, equivalence, gradient, shard, CLI, notebook synchronization, execution, and 300 DPI checks.

August 4, 2026 Advanced equilibrium and physics-informed SILVA families

Advanced Equilibrium Family Pass

Added six adjacent equilibrium mechanisms as SILVA transitions, objectives, or time-stepping components while preserving their distinct mathematical roles.

Area	Change
Graph equilibrium	Added a monotone graph transition with a constrained operator and a computable monotonicity certificate.
Generative equilibrium	Added an injected self-attention transition with one-time input injection and a teacher-distillation objective.
Inverse problems	Added a positive Burg-geometry mirror transition with a Poisson data-fidelity objective.
Physics-informed equilibrium	Added equilibrium-state ODE residuals, initial-condition terms, Jacobian regularization, and implicit time derivatives.
Differential-algebraic systems	Added a differentiable implicit Runge-Kutta step with algebraic constraints and damped Newton correction.
Residual objective	Added a separately optimized adversarial residual objective and documented the Differential Equation naming distinction.
Data	Added deterministic chain-graph, teacher-image, Poisson inverse, linear IVP, and linear DAE datasets with exact residual checks.
Learning	Added five executable notebooks, three learning guides, an API reference, and a complete runnable example.
Validation	Added finite-value, shape, convergence, equation-residual, gradient, factory, notebook, example, citation, and release checks.

August 3, 2026 Ten internal architectures for SILVA points

Point Architecture And Linked-Point Pass

Made the distinction between depth inside one SILVA equilibrium point and depth across several linked SILVA points explicit throughout the package.

Area	Change
Family API	Added the canonical silva_cortex_network family for independently constructed linked points.
State contract	Added targeted validation that a completed transition preserves the equilibrium-state shape.
Spatial example	Added a deterministic tiny-image example with a residual CNN and U-Net-shaped first point linked to a vector MLP point.
Architecture catalog	Added MLP, residual MLP, residual CNN, U-Net, dense CNN, Transformer, inverted residual, Fourier operator, MLP-Mixer, and ConvNeXt V2 fields.
Notebook	Added an executable ten-architecture catalog and retained the cortex notebook's spatial, heterogeneous, and tiny-data path.
Documentation	Added tensor contracts, primary sources, selection rules, internal composition, linked-point composition, damping, and residual guidance.
Tests	Added registry, shape, finite-value, gradient, fixed-point, odd-size U-Net, tiny-data, example, and coverage-registry checks.

August 3, 2026 Cinematic SILVA method visual and mobile equation polish

Front-End Method Image

Replaced the dense SVG method diagram with a cinematic PNG visual for the home page. The asset keeps the SILVA method cues visible through color and motion: amber stimulus injection, green local coupling, blue global arcs, silver self/damping rings, solver states, and convergence to an attractor.

Area	Change
Asset	Added docs/assets/images/silva-method-cinematic.png.
Home page	Placed the cinematic image below the main equation band with an accessible caption.
Layout	Removed the overlap-prone SVG from the front-end path and converted the home fixed-point equation into a responsive multi-line MathJax derivation.
Tests	Added an asset check that the home page uses the PNG and no longer references the old SVG.

August 3, 2026 Generalized paper architectures and release hardening

Generalized Architecture Pass

Added parameter-driven architecture cases with explicit study-level scope and without claimed paper metrics.

Area	Change
Solvers	Added relative stopping, independent batched Anderson, best iterate, sparse indexing, exact/phantom gradients, and selectable backward solvers.
Cases	Added sequence DEQ, full multiscale vision DEQ, IGNN, implicit representations, joint DDIM trajectories, and coupled RAFT/DEQ-Flow.
API	Added public API and family-selection API pages, then hardened the API audit so every source module has a generated reference page.
Training/data	Hardened checkpoint resume, RNG/scheduler state, hooks, custom metrics, and leakage-free preprocessing statistics.
Learning	Added Paper Family Adaptations, two executable notebooks, examples, equations, and citation mappings.
Tests	Added exact-gradient and architecture validation coverage; these validate mechanisms, not paper benchmark numbers.

August 3, 2026 arXiv citation, BibTeX, release audit, and derivation labs

Release-Quality Citation And Reproducibility Pass

Updated the package documentation after the SILVA article became available as arXiv:2607.28989.

Area	Change
Article citation	Updated README, CFF, docs, notebooks, and generator scripts to cite arXiv:2607.28989.
BibTeX	Added docs/assets/bib/silva-networks.bib with SILVA article, software, tutorial chapters, papers, and upstream repositories.
Audits	Added Equation and PDF Audit and Release Readiness.
Derivations	Added Solver Derivation Lab, Implicit Backward Guide, and Interactive Diagnostics Lab.
Experiments	Added Benchmark Cards from checked public metrics JSON outputs.
Cortex hierarchy	Added Cortex Hierarchies, Cortex Hierarchy example, and Cortex Hierarchy notebook.
Companion assets	Added the book and solutions manual roadmap and kept public links on package-native learning paths.
Tooling	Added scripts/release_audit.py, scripts/run_notebook_smoke.py, and release-readiness tests.
CI	Wired release audit, notebook validation, docs build, package build, and metadata checks into CI.

Validation target:

python scripts/release_audit.py
python scripts/run_notebook_smoke.py --timeout 180
pytest
mkdocs build --strict
python -m build
twine check dist/*

August 2, 2026 Implementation coverage and SILVA-style names

Coverage Contract

Added a package-level implementation coverage registry and aligned preferred public names for adapted modules.

Area	Change
Names	Added SILVADEQFlow, silva_deq_flow, SILVAProjectedQPLayer, and silva_projected_qp_layer as preferred public names.
Compatibility	Kept SILVAOpticalFlowDEQ, silva_optical_flow_deq, SILVAConstrainedQuadraticLayer, and silva_constrained_quadratic_layer available as compatibility names.
Notebooks	Added Family Selector and Projected QP and Training Helpers Validation.
API	Added Coverage Registry and wired it into tests.
Tests	Added tests/test_implementation_coverage.py to check public objects, docs, notebooks, examples, and __all__.

Validation target:

pytest
mkdocs build --strict

August 2, 2026 External method adaptation atlas

Source-to-SILVA Adaptation Pass

Added a method adaptation layer that translates external implicit layer, DEQ, ODE, optimization, and optical-flow references into SILVA-native equations, APIs, scope notes, notebooks, and citation rules.

Area	Change
Learning page	Added Method Adaptation Atlas with source-to-package derivations and scope findings.
Notebook	Added Method Adaptation Atlas with compact package validation checks.
Navigation	Wired the atlas into Learn, Notebooks, Run Everything, Colab, and the home page.
Citation scope	Documented the optimization routes separately: tutorial quadratic bridge, package-native constrained QP, and optional CVXPYlayers wrapper.
Date metadata	Added page-specific update notes for the atlas and newer bridge notebooks.

Validation target:

mkdocs build --strict
pytest

August 2, 2026 Premium learning path and runnable platform guide

Premium Documentation Polish

Expanded the package documentation from a reference into a guided learning and execution platform.

Area	Change
Learning path	Added Derivation Workbook with scalar, vector, graph, global, data, and diagnostic derivations.
Run path	Added Run Everything with install, examples, notebooks, data, validation, tests, docs, and local serve commands.
Notebook	Added Equation-to-Code Walkthrough.
Home page	Rebalanced the action grid and expanded the first path from install to derivation, execution, diagnostics, notebooks, and API.
UI polish	Added reusable learning cards, run cards, derivation callouts, and proof-table styling.

Validation target:

mkdocs build --strict
pytest

August 2, 2026 Citation audit and references expansion

Research Citation Audit

Added a package-wide citation audit mapping implemented solvers, layers, presets, diagnostics, dataset adapters, and implicit bridge modules to the relevant literature.

Area	Change
Audit	Added research-citation-audit.md with method-to-paper and claim-to-citation matrices.
References	Expanded the references page with DEQ, MDEQ, Jacobian regularization, Neural ODEs, optimization layers, Deep Sets, Set Transformer, dynamic kNN graphs, Hutchinson trace estimation, GCN, GAT, MPNN, and solver references.
Derivations	Added citation trace tables and inline literature notes to mathematical and implementation derivations.
Case Atlas	Added citation rules by implemented case family.
API	Added citation shortcuts for API readers.
Audit finding	Added public deq_engine and flow API coverage with TorchDEQ, RAFT, and DEQ-Flow citation lineage.

Validation target:

mkdocs build --strict
pytest

August 2, 2026 UI, brand, equations, and bridge expansion

Package Documentation Refresh

Updated the package documentation surface with a blue SILVA Networks visual identity, package icon, home-page hero, grid-based navigation, page-date metadata, and a clearer first path for new users.

Area	Change
Brand	Added the blue-gradient SILVA Networks icon and aligned the theme palette with the package identity.
Home page	Reworked the hero, action grid, equation band, first path, package area map, notebook map, and learning assets.
Layout	Fixed markdown wrapper behavior so action cards and first-path cards render as grids instead of a narrow vertical column.
Dates	Added visible page update metadata with page-specific modification notes.
Derivations	Expanded the implementation derivations into an equation-to-code reference across layers, solvers, diagnostics, presets, and bridge modules.
API	Aligned API pages with current package modules, including silva_networks.presets and silva_networks.implicit.
Bridge	Added the implicit-layer tutorial bridge with package-native notebooks for fixed points, implicit autodiff, neural ODEs, DEQs, differentiable optimization, MDEQs, and Jacobian regularization.

Validation target:

mkdocs build --strict
pytest

Documentation Scope

The package docs are the editable surface for this work. The article and book PDFs are treated as sources and references, not as files to rewrite here.

Source	How it is used
Package source	API names, tensor contracts, equations, solver behavior, and examples are checked against src/silva_networks.
Package tests	Test coverage is used to confirm public behavior and notebook-facing examples.
Companion book/manual	Planned public learning assets connected to the package roadmap.
External papers	References are cited and linked from the documentation.

All 116 navigable Markdown pages and 44 rendered notebooks use contextual Where to Go Next tables. Each table connects the current page to the most relevant derivation, executable material, example, or API contract, and the documentation audit checks this coverage during release validation.

Update Standard

Future documentation changes should record:

1. Date of the update.
2. Files or page families touched.
3. Equation/API behavior affected.
4. Validation command used.
5. Any discrepancy found between documentation, package code, tests, article, or book material.

Where to Go Next

Question	Page
What writing conventions should future changes follow?	Contributing
Which automated checks cover the documentation?	Release Readiness
Where are equation and companion-asset checks recorded?	Equation and PDF Audit