Code quality tracking: refactoring, duplication, and technical debt

[detrin]

Tracking issue for code quality improvements identified during thesis repo review.

Critical

• Refactor master_ansatz.jl: eliminate 8-way duplication in QME_sI_ansatz_* functions #50 Refactor master_ansatz.jl — 8 nearly identical QME_sI_ansatz_* functions (~384 LOC duplication)
• Refactor master_iterative.jl: consolidate duplicated solvers and remove _old versions #51 Refactor master_iterative.jl — 4 duplicated solvers; remove _old versions
• Fix risky division in master_iterative.jl:340 — can silently produce Inf #52 Fix risky division in master_iterative.jl:340 (can silently produce Inf)

High

• Replace typeof(rho) <: Operator type-checking anti-pattern with dispatch #53 Replace typeof(rho) <: Operator type-checking anti-pattern with dispatch (9+ places)
• Replace bare parameter tuples with NamedTuple or struct #54 Replace bare parameter tuples with NamedTuple or struct (20+ places)
• Replace magic symbol strings with @enum for vib_basis, picture, and mode flags #55 Add @enum for magic symbol strings (:interaction_picture, :ground_ground, etc.)
• Fix potential nothing return in trace.jl:71-79 #56 Fix potential nothing return in trace.jl:71-79

Medium

• Improve type annotations throughout — replace bare Array with concrete types #57 Improve type annotations throughout (::Array → ::AbstractMatrix{ComplexF64})
• Clean up technical debt: TODO comments, dead code, and commented-out tests #58 Clean up technical debt: 13 TODOs, dead code in aggregateTools.jl, re-enable test_memory_kernel.jl

[detrin]

Resolved in v0.3.0.

[detrin]

New issues added from code quality audit and UX analysis

Code Quality / Internal

#	Title	Severity
#60	Fix unsafe divisions in trace.jl and rate_constant.jl	Correctness
#61	Extract shared integration setup boilerplate	DRY — Moderate
#62	Refactor deeply nested getAggHamInteraction	Readability — Moderate
#63	Remove Union{T, Nothing} fields from Aggregate struct	SOLID — Moderate
#64	Replace hardcoded 2-level system assumptions	Extensibility — Moderate
#65	Remove hardcoded module self-references	Code smell — Minor
#66	Standardize naming conventions: camelCase → snake_case	Convention — Minor (breaking)

User Experience / Developer Experience

#	Title	Severity
#67	UX-1: Tutorial uses old API and does not work	Critical
#68	UX-2: No SimulationResult type — inconsistent return values	High
#69	UX-3: Coupling matrix includes ground state index	High
#70	UX-4: Function names are cryptic abbreviations	Moderate
#71	UX-5: No unified solver entry point	Moderate
#72	UX-6: No physical validation	Moderate
#73	UX-7: Unit conversion is fragile and duplicated	Minor
#74	UX-8: No solver selection guide in docs	Minor
#75	UX-9: Convenience constructors for common systems	Low
#76	UX-10: Adopt Julia-idiomatic patterns (type dispatch, callable structs, etc.)	High

Priority order

Internal quality:

1. Fix unsafe divisions in trace.jl and rate_constant.jl #60, Fix potential nothing return in trace.jl:71-79 #56 — Correctness (divisions, nothing returns)
2. Replace typeof(rho) <: Operator type-checking anti-pattern with dispatch #53 — typeof anti-pattern
3. Refactor master_ansatz.jl: eliminate 8-way duplication in QME_sI_ansatz_* functions #50, Refactor master_iterative.jl: consolidate duplicated solvers and remove _old versions #51, Extract shared integration setup boilerplate into helper function #61 — Biggest DRY wins
4. Replace magic symbol strings with @enum for vib_basis, picture, and mode flags #55, UX-10: Adopt Julia-idiomatic patterns — replace symbol dispatch, bare tuples, and Union{Nothing} #76 — Magic symbols → enums + Julia patterns
5. Clean up technical debt: TODO comments, dead code, and commented-out tests #58 — Tech debt cleanup
6. Remove Union{T, Nothing} fields from Aggregate struct #63, Refactor deeply nested getAggHamInteraction in aggregateOperators.jl #62, Replace bare parameter tuples with NamedTuple or struct #54 — Structural quality
7. Improve type annotations throughout — replace bare Array with concrete types #57, Replace hardcoded 2-level system assumptions in molecules.jl and aggregateOperators.jl #64 — Type safety and extensibility
8. Remove hardcoded OpenQuantumSystems module self-references #65, Standardize naming conventions: migrate from camelCase to snake_case #66 — Polish

UX:

1. UX-1: Tutorial uses old API and does not work #67 — Fix tutorial (unblocks all new users)
2. UX-10: Adopt Julia-idiomatic patterns — replace symbol dispatch, bare tuples, and Union{Nothing} #76 — Julia-idiomatic patterns (architectural foundation)
3. UX-2: No SimulationResult type — inconsistent return values across solvers #68 — SimulationResult type
4. UX-3: Coupling matrix includes ground state index — confusing for physicists #69 — Coupling matrix physicist UX
5. UX-5: No unified solver entry point — add solve() dispatch function #71 — Unified solve() entry point
6. UX-4: Function names are cryptic abbreviations — add documentation and glossary #70 — Naming conventions + glossary
7. UX-6: No physical validation — silent Inf/NaN propagation possible #72 — Physical validation
8. UX-8: No solver selection guide in docs #74 — Solver selection guide
9. UX-7: Unit conversion is fragile and duplicated across files #73 — Unit conversion
10. UX-9: Convenience constructors for common systems (dimer, trimer, linear chain) #75 — Convenience constructors