Audit docs

[idelder]

Rebase on recent unstable changes then do a gargantuan opus 4.6 assisted audit of documentation.

Summary by CodeRabbit

Release Notes

• New Features

  • Added configurable cycle detection limits for commodity graph analysis.
  • Added per-category output filtering thresholds (capacity, activity, emissions, cost).
  • Added myopic mode evolution support with custom iteration scripts.
  • Added planning period duration configuration parameter.

• Bug Fixes

  • Adjusted solver convergence tolerances for improved numerical stability.

• Documentation

  • Restructured mathematical formulation with improved notation and parameter references.
  • Added comprehensive set and parameter documentation tables.

• Removals

  • Removed output plotting CLI utility.
  • Removed breakeven analysis extension.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

This PR refactors the temporal data model by removing the period dimension from time-indexed parameters and tables, replacing season_label with time_season, and introducing new time-related parameters including days_per_period and segment_fraction computations. Configuration, code, database schemas, migrations, and tests are updated accordingly.

Changes

Cohort / File(s)	Summary
Database Schema Refactoring data_files/example_dbs/*.sql, data_files/temoa_basics*.sql, data_files/temoa_schema_v*.sql, temoa/tutorial_assets/utopia.sql	Removed period columns from capacity/demand/efficiency/reserve tables; changed season FK from season_label to time_season; updated composite primary keys accordingly. Dropped season_label and time_segment_fraction tables. Redesigned time_season and time_season_sequential with segment_fraction instead of num_days. Extended time_of_day with hours and notes columns. Removed days_per_period metadata entries.
Configuration Files data_files/my_configs/*.toml, temoa/tutorial_assets/config_sample.toml, tests/testing_configs/*.toml	Added new configuration parameters: days_per_period (default 365), cycle detection limits (cycle_count_limit, cycle_length_limit), and per-metric output thresholds (output_threshold_capacity, output_threshold_activity, output_threshold_emission, output_threshold_cost). Extended myopic mode with evolving and evolution_script options.
Time Model & Core Components temoa/components/time.py, temoa/core/model.py, temoa/core/config.py	Rewrote validate_segment_fraction to compute segment_fraction[s,d] from season/TOD fractions instead of only verifying. Changed index shapes from (p,s,d) to (s,d). Updated create_time_sequence to build time_next and sequential season mappings without period dimension. Added singleton demands handling and updated time parameter/set definitions in model initialization. Extended config to accept new time/threshold/cycle parameters.
Capacity & Technology Components temoa/components/capacity.py, temoa/components/technology.py	Refactored capacity-factor processing from (r,p,t,v) to (r,t,v) keying. Updated create_capacity_and_retirement_sets to use period-independent season iteration. Added period filtering on survival curves. Changed sparse iteration API from sparse_iterkeys() to sparse_keys() throughout. Added check_existing_capacity validation.
Commodity, Flow & Constraint Components temoa/components/commodities.py, temoa/components/flows.py, temoa/components/limits.py, temoa/components/operations.py, temoa/components/reserves.py	Added check_singleton_demands to bypass demand constraints for single-source demands. Updated season iteration from period-scoped to global model.time_season. Changed flow balance computation to use union with source/sink filtering. Reworked multiple constraint signatures and indexing (e.g., limit_new_capacity_share removed period, added vintage). Updated ramp constraints to use segment_fraction[s,d] and time_of_day.hours. Modified reserve margin logic for bidirectional exchange handling.
Storage & Cost Components temoa/components/storage.py, temoa/components/costs.py, temoa/components/utils.py	Added storage initialization variables and constraints. Reworked seasonal storage mappings to remove period indexing. Updated limit_storage_fraction to remove vintage and use period-independent indices. Changed cost calculation loops to iterate global time_season. Modified get_variable_efficiency to drop p from efficiency variable lookup. Replaced sparse iteration API calls throughout.
Data I/O & Loading temoa/data_io/component_manifest.py, temoa/data_io/hybrid_loader.py, temoa/data_io/loader_manifest.py	Added order_by attribute to LoadItem. Updated time-related component loaders: time_season now flat, time_season_sequential restructured. Removed time_segment_fraction loading. Added custom loaders for construction_input and emission_embodied. Updated column/validator mappings to drop period from relevant tables. Added new viable-set builders (viable_rtvo, viable_rpt, viable_rtv_eol).
Output & Analysis Tools temoa/_internal/table_data_puller.py, temoa/_internal/table_writer.py, temoa/_internal/exchange_tech_cost_ledger.py	Updated season iteration from model.time_season[p] to global model.time_season. Changed return types to allow None commodities in FI indices. Replaced threshold handling with per-metric output thresholds. Updated sparse iteration to use sparse_keys(). Modified annual flow/capacity polling to drop period dimension. Added negative-value detection for capacity results.
Myopic & Model Checking Extensions temoa/extensions/myopic/*.py, temoa/extensions/single_vector_mga/sv_mga_sequencer.py, temoa/model_checking/*.py	Added evolution updater module for post-iteration callbacks. Extended myopic sequencer with configurable capacity threshold and evolving mode support. Updated cycle detection with configurable limits. Reworked network model data to track end-of-life lifetime, uncapped techs, existing capacity, and silent vintage tracking. Added new filter builders for groups/viability sets. Changed sparse iteration API calls to sparse_keys().
Database Migrations temoa/utilities/db_migration_v3_1_to_v4.py, temoa/utilities/sql_migration_v3_1_to_v4.py	Added aggregation migrations for restructured time/capacity tables. Special-case handling for capacity_factor_process aggregation by (r,s,d,t,v). Custom post-processing for time_season, time_of_day, time_season_sequential derived from legacy TimeSegmentFraction via period-aggregation. Added period-to-vintage column mapping for limit tables. Wrapped migrations in error handling with warnings.
Breakeven Extension temoa/extensions/breakeven/*	Removed entire breakeven extension module and README indicating unmaintained status.
Documentation docs/source/*.rst	Removed db_model_comparison.rst. Replaced "Network Diagrams" section with include directive. Updated computational_implementation.rst with new demand constraint form (annual-only) and helper references. Added set_desc_and_tables.rst and param_desc_and_tables.rst as new documentation files. Updated mathematical_formulation.rst with new time sequencing modes and revised notation. Updated unit_checking.rst and visualization.rst with configuration changes. Updated quick_start.rst with new check-units subcommand and cycle detection documentation.
Test Data & Fixtures tests/testing_data/*.sql, tests/testing_configs/config_*.toml	Updated all test SQL files to match schema changes: removed period from capacity/demand/efficiency/reserve tables, removed season_label and time_segment_fraction inserts, updated time_season/time_of_day/time_season_sequential structure. Added days_per_period to all test configs. Added new migration_v3_1_mock.sql fixture for v3.1→v4 migration testing.
Test Code tests/test_*.py, tests/legacy_test_values.py	Updated legacy test expected values (constraint/variable counts and objective values). Added new test_cycle_limits.py for cycle detection validation. Enhanced test_full_runs.py with sparse iteration API updates and adjusted expected myopic/stochastic objective values. Extended test_material_results.py with scenario mode/name parametrization. Updated test_myopic_sequencer.py with evolving mode expectations. Added test_v4_migration.py for v3.1→v4 migration validation. Updated test_network_model_data.py, test_set_consistency.py, test_storage.py with schema/indexing changes. Updated fixture data structures across multiple tests.
Type Definitions temoa/types/*.py	Updated TimeNextDict key from (p,s,d) to (s,d). Updated TimeNextSequentialDict from tuple to single Season key. Updated SequentialToSeasonDict similarly. Changed EfficiencyVariableDict key from (r,p,i,t,v,o) to (r,i,t,v,o). Changed CapacityFactorProcessDict key from (r,p,t,v) to (r,t,v). Widened FI commodity fields (i, o) to `Commodity
Other Utilities temoa/utilities/unit_cost_explorer.py, temoa/model_checking/pricing_check.py, temoa/model_checking/validators.py	Updated time/season indexing and segment_fraction construction. Changed validate_capacity_factor_process signature to drop period parameter and season lookup. Updated sparse iteration API calls. Modified cyclic orphan removal logic in commodity network manager.
Removed Code temoa/data_processing/make_output_plots.py	Deleted entire plotting module and CLI entrypoint.

Sequence Diagram(s)

The condition criteria for generating sequence diagrams are not met. The changes are too heterogeneous and diffuse—spanning schema refactoring, parameter restructuring, code reorganization, and configuration updates—without forming a coherent sequential flow that would benefit from visualization. Multiple independent control flows are being modified rather than a single new feature with multi-component interactions.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related PRs

• Add v_storage_init variable for non-seasonal storage #275: Adds v_storage_init variable and tie-back constraint in storage components and model, directly overlapping storage refactoring.
• Update dependencies and fix breakages from pyomo 6.10 #280: Systematically replaces sparse_iterkeys() with sparse_keys() across the codebase, matching identical API migration pattern.
• Rework period/vintage indices in limit tables #281: Modifies limit table schemas and vintage/tech_or_group indexing to align with period removal from constraints.

Suggested labels

refactor, documentation, database-schema, time-model

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests