Reorganize docs, add info, reduce redundancies

[acostarelli]

No description provided.

[Copilot]

Pull request overview

This PR restructures the documentation to reduce redundancy and shift most narrative content into Literate.jl sources, while also tightening/modernizing many in-code docstrings (notably around tolerances, reductions, solver backends, and mathematical notation).

Changes:

• Migrates several tutorials/how-to pages from static .md into Literate-generated .jl sources, and updates the Documenter navigation/build pipeline accordingly.
• Expands/clarifies docstrings across PTDF/LODF/virtual matrices, network reduction types, serialization behavior, and AutoTolerance, including more LaTeX math blocks.
• Adds new reference hubs/pages (e.g., matrix overview/indexing, matrix type reference) and new explanation pages (concurrency, slack conventions, equivalent branches).

Reviewed changes

Copilot reviewed 45 out of 45 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/virtual_lodf_calculations.jl	Docstring math formatting for partial LODF derivation.
src/serialization.jl	Clarifies PTDF-only HDF5 serialization scope and what is/isn’t persisted.
src/ptdf_calculations.jl	Updates PTDF constructor docs (solver list, AutoTolerance default, math notation).
src/NetworkReductionData.jl	Adds guidance on accessors and “bus survived reduction” checks.
src/NetworkReduction.jl	Adds user-facing rules and usage patterns for network_reductions ordering/validation.
src/modf_definitions.jl	Reformats Woodbury equation and symbol descriptions using LaTeX.
src/lodf_calculations.jl	Updates LODF constructor docs (solver list, AutoTolerance default, math notation).
src/common.jl	Adds docstring for equivalent-branch physical parameter extraction and LaTeX in outage math.
src/BranchesSeries.jl	Adds docstring describing series-chain reduced-branch representation.
src/BranchesParallel.jl	Adds docstrings for parallel-group reduced-branch representations (homogeneous/mixed).
src/BA_ABA_matrices.jl	Clarifies BA/ABA definitions and math notation in docstrings.
src/auto_tolerance.jl	Expands AutoTolerance docstring with scope rules and examples; LaTeX inequality.
src/apply_zero_impedance_reduction.jl	Pure formatting/indentation change for readability.
docs/src/tutorials/tutorial_VirtualPTDF_matrix.md	Removes legacy static tutorial (replaced by new Literate structure).
docs/src/tutorials/tutorial_VirtualLODF_matrix.md	Removes legacy static tutorial (replaced by new Literate structure).
docs/src/tutorials/tutorial_RadialReduction.md	Removes legacy static tutorial content (now covered via docstrings/how-tos/explanations).
docs/src/tutorials/tutorial_PTDF_matrix.md	Removes legacy static tutorial (superseded by new “Getting Started” + reference hubs).
docs/src/tutorials/tutorial_LODF_matrix.md	Removes legacy static tutorial (superseded by new “Getting Started” + reference hubs).
docs/src/tutorials/tutorial_Incidence_BA_ABA_matrices.md	Removes legacy static tutorial (covered by new reference and how-to content).
docs/src/tutorials/tutorial_DFAX.md	Removes legacy static tutorial (replaced by a new DFAX how-to).
docs/src/tutorials/tutorial_DegreeTwoReduction.md	Removes legacy static tutorial content (now covered via docstrings/explanations).
docs/src/tutorials/getting_started.md	Removes legacy markdown tutorial (replaced by Literate source).
docs/src/tutorials/getting_started.jl	Adds new Literate “Getting Started” end-to-end walkthrough.
docs/src/tutorials/analysis_at_scale.jl	Adds new Literate tutorial for large-scale screening using virtual matrices/caches.
docs/src/reference/public.md	Rebuilds the public reference page into structured autodocs sections.
docs/src/reference/network_matrices_overview.md	Replaces prior overview with a detailed indexing/taxonomy hub for all matrix types.
docs/src/reference/matrix_types.md	Adds a matrix type reference page (constructors, semantics, aliases).
docs/src/network_matrices.jl	Removes legacy overview page (replaced by new reference hub).
docs/src/index.md	Updates landing page copy + navigation pointers to new docs structure.
docs/src/how_to_guides/reproduce_dfax_values.jl	Adds Literate how-to reproducing industry DFAX values with executable examples.
docs/src/how_to_guides/diagnose_connectivity.jl	Adds Literate how-to for connectivity/islanding diagnosis.
docs/src/how_to_guides/contingencies.jl	Adds Literate how-to for defining/applying contingencies via VirtualMODF.
docs/src/how_to_guides/compute_network_matrices.md	Removes legacy how-to (superseded by new guides/reference).
docs/src/how_to_guides/choose_linear_solver.md	Removes legacy markdown how-to (replaced by Literate source).
docs/src/how_to_guides/choose_linear_solver.jl	Adds Literate how-to describing solver backends and platform defaults.
docs/src/how_to_guides/build_multiple_matrices.jl	Adds Literate how-to for reusing Ybus/A/BA intermediates efficiently.
docs/src/explanation/slack_conventions.md	Adds explanation page on slack/reference conventions and dist_slack implications.
docs/src/explanation/network_reduction_theory.md	Rewrites/expands reduction theory explanation with clearer math and structure.
docs/src/explanation/flowgate_methodology.md	Updates flowgate methodology page and cross-links to new DFAX how-to.
docs/src/explanation/equivalent_branches.md	Adds explanation of impedance vs rating aggregation for reduced branches.
docs/src/explanation/dc_power_flow_approximation.md	Expands and formalizes the DC approximation explanation + references.
docs/src/explanation/concurrency.md	Adds explanation of virtual-matrix concurrency behavior and KLU locking.
docs/src/explanation/computational_considerations.md	Refactors/condenses computational notes; points to AutoTolerance as authority.
docs/make.jl	Updates docs build to generate Literate content for tutorials and how-to guides.
docs/make_tutorials.jl	Generalizes tutorial generation to make_literate_folder for multiple subdirs.

---

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

[github-actions]

Performance Results

Precompile Time

Main	This Branch	Delta
2.1 s	2.2 s	+4.7%

Execution Time

Cells show median (min–max) over 5 samples; delta compares medians.

Test	Main	This Branch	Delta
matpower_ACTIVSg2000_sys-Build Ybus	9.6 (9.5–11.8) ms	9.3 (9.0–10.7) ms	-3.5%
matpower_ACTIVSg2000_sys-Build PTDF	73.3 (72.2–74.0) ms	76.2 (75.6–76.9) ms	+3.9%
matpower_ACTIVSg2000_sys-Build LODF	149.2 (147.7–154.2) ms	152.1 (151.8–153.7) ms	+2.0%
matpower_ACTIVSg2000_sys-Build VirtualMODF	82.7 (78.5–96.8) ms	881.1 (875.6–888.8) ms	+965.0%
matpower_ACTIVSg2000_sys-VirtualMODF Query 10 rows	0.6 (0.5–1.3) ms	0.6 (0.5–1.4) ms	+8.0%
matpower_ACTIVSg2000_sys-Radial network reduction	0.8 (0.8–0.9) ms	0.8 (0.8–1.0) ms	+4.0%
matpower_ACTIVSg2000_sys-Degree two network reduction	1.0 (1.0–1.5) ms	1.0 (1.0–1.5) ms	-4.2%
Base_Eastern_Interconnect_515GW-Build Ybus	564.6 (537.1–581.7) ms	483.3 (481.6–509.2) ms	-14.4%
Base_Eastern_Interconnect_515GW-Build VirtualPTDF	794.7 (788.7–811.5) ms	737.4 (726.2–744.3) ms	-7.2%
Base_Eastern_Interconnect_515GW-VirtualPTDF Query 10 rows	27.7 (27.5–28.4) ms	28.4 (28.1–30.7) ms	+2.8%
Base_Eastern_Interconnect_515GW-Build VirtualMODF	789.3 (769.7–825.1) ms	811.5 (798.5–835.5) ms	+2.8%
Base_Eastern_Interconnect_515GW-VirtualMODF Query 10 rows	32.5 (31.2–33.0) ms	33.6 (33.4–33.9) ms	+3.5%
Base_Eastern_Interconnect_515GW-Radial network reduction	33.7 (33.5–34.7) ms	33.1 (32.8–33.7) ms	-1.8%
Base_Eastern_Interconnect_515GW-Degree two network reduction	48.5 (47.9–49.2) ms	44.5 (43.6–45.4) ms	-8.3%

[kdayday]

Copilot comments mostly look to be legitimate format issues. I haven't double-checked its logic about some of the matrix math.

• Docs are failing on AppleAccelerateLU -- I'd suggest just removing actual code examples to that. Please ask for re-review after they compile, I haven't looked at tutorials/how-tos
• Elsewhere, we typically do 'using PowerNetworkMatrices' etc. in code examples, and then just e.g., Ybus(sys) instead of PNM.Ybus(sys). Suggest simplifying
• AI rewrote a bunch of math and code notation in docstrings, worth a visual review on whether that's being rendered/interpreted as intended
• I'm fine with the extension of literate logic to the how-to's in theory, but haven't looked at whether the content makes that worthwhile. Don't necessarily want to overcomplicate things if its not needed

[m-bossart]

I looked at the docs build but I second Kate's recommendation to look at the docstrings to make sure the math is rendered correctly. I think this is a good upgrade to the documentation, thanks @acostarelli

[Copilot]

Pull request overview

Copilot reviewed 60 out of 60 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (3)

src/lodf_calculations.jl:350

• Same issue as above: the displayed LODF equation includes a trailing comma inside the math block.
  src/ptdf_calculations.jl:420
• This math block equation line ends with a comma, which will render as part of the equation. Likely unintentional punctuation inside the formula.
  src/ptdf_calculations.jl:477
• This math block equation line ends with a comma, which will render as part of the equation. Likely unintentional punctuation inside the formula.

[Copilot]

Pull request overview

Copilot reviewed 60 out of 60 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/lodf_calculations.jl:249

• When tol is an AutoTolerance (the default), _lodf_from_system currently ignores the caller’s linear_solver choice entirely and always routes through the KLU-only LODF(A, ABA, BA) path. If a user passes linear_solver != "KLU", this becomes a silent behavior change. Consider either validating and erroring with a clear message, or honoring the requested solver when possible (and documenting any restrictions).