Refactoring repo and restructuring temoa initialize and rules

[ParticularlyPythonicBS]

Restructuring temoa_initialize and temoa_rules into a component structure where items are organized based on categories like capacity and storage instead of their action like intialization or rule. This makes the files smaller and more cohesive and removes the star imports in temoa model (now just model for api restructure)

All functions in initlaiize and rules are distributed to files in the component modules. Large functions like create sparse dicts are logically chunked and moved to related component files.

Where a function has been moved is a logical best guess based on code cohearance but happy to move things around if it makes more sense somewhere else

Summary by CodeRabbit

• New Features

  • Adds a modular core with comprehensive capacity, commodity, cost, emissions, storage, operations, reserves, limits, technology, and time components; introduces a new model class and setup routines.

• Documentation

  • Major README overhaul with installation, library and CLI usage, setup, testing guidance; adds FEATURE_BRANCH planning doc.

• Refactor

  • Reorganizes package for a cleaner, pip-installable layout and stable public API; bumps version to 4.0.0a1 and re-exports legacy names for compatibility.

• Tests

  • Updates tests to the new module layout.

• Chores

  • Adjusts ignore rules to track FEATURE_BRANCH.md.

[coderabbitai]

Walkthrough

Reorganizes the codebase into a library-centric layout: introduces temoa.core public API, temoa._internal package, and many temoa/components/* modules implementing constraints and precomputation. Adds public re-exports, bumps version to 4.0.0a1, removes legacy initializer, and updates import paths across extensions, utilities, and tests.

Changes

Cohort / File(s)	Summary of changes
Project metadata README.md, .gitignore, FEATURE_BRANCH.md, pyproject.toml	Expanded README for v4.0.0a1; added FEATURE_BRANCH.md (now unignored); bumped version to 4.0.0a1; updated lint (E501) config.
CLI / entry main.py	Updated imports to temoa.core / temoa._internal; minor message/formatting tweaks; path handling imports added.
Top-level package exports temoa/__init__.py	New public re-exports for backward compatibility; defines __version__ and __all__.
Core package init temoa/core/__init__.py	New core package exposing TemoaModel, TemoaConfig, TemoaMode, and __version__.
Core model & config temoa/core/model.py, temoa/core/config.py	New TemoaModel class and CreateSparseDicts; refined TemoaConfig signatures and imports.
Internal package marker temoa/_internal/__init__.py	New internal package docstring and empty __all__.
Internal plumbing / re-exports temoa/_internal/*.py temoa/_internal/data_brick.py, exchange_tech_cost_ledger.py, hybrid_loader.py, run_actions.py, table_data_puller.py, table_writer.py, temoa_sequencer.py	Redirected imports to temoa.core and temoa._internal modules; minor formatting, exception chaining, and import reorderings; preserved behavior while changing symbol sources.
Componentization (new modules) temoa/components/*.py capacity.py, commodities.py, costs.py, emissions.py, flows.py, geography.py, limits.py, operations.py, reserves.py, storage.py, technology.py, time.py, utils.py	Added many new component modules implementing index-set builders, Pyomo constraints, precomputation and validation routines, financial helpers, and utility functions—centralizing model construction logic across focused modules.
Model-checking & validators temoa/model_checking/*	Updated imports to core paths; added __all__ in validators; minor formatting and restructure, no semantic change to checks.
Legacy initializer removal temoa/temoa_model/temoa_initialize.py	Removed the legacy initializer file and its large collection of setup/validation/index-building functions (migrated to temoa/components/* and temoa/core).
Legacy model module temoa/temoa_model/temoa_model.py	Reworked imports to delegate sparse-dictionary assembly to new component functions; added CreateSparseDicts wrapper.
Extensions temoa/extensions/**	Many extension modules updated to import from temoa.core / temoa._internal instead of legacy temoa.temoa_model.*; minor formatting and loop-variable tweaks.
Utilities temoa/utilities/*	Updated import paths to temoa.core / temoa._internal; minor formatting adjustments.
Tests tests/*, tests/utilities/*	Updated test imports to new core/internal paths; some assertion formatting/parametrization changes; no substantive test logic changes.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant CLI as main.py
  participant Conf as temoa.core.config.TemoaConfig
  participant Loader as temoa._internal.hybrid_loader.HybridLoader
  participant Builder as temoa._internal.build_instance
  participant Solver as temoa._internal.solve_instance
  participant Checker as temoa._internal.check_solve_status
  participant Results as temoa._internal.handle_results
  participant Writer as temoa._internal.TableWriter

  User->>CLI: run CLI / python -m temoa
  CLI->>Conf: instantiate config
  CLI->>Loader: load data
  Loader-->>CLI: data payload
  CLI->>Builder: build model instance (uses temoa.core.TemoaModel & components)
  Builder-->>CLI: Pyomo model instance
  CLI->>Solver: solve model
  Solver->>Checker: verify status
  alt solve success
    CLI->>Results: process outputs
    Results->>Writer: write tables
  else solve failure
    Checker-->>CLI: error/status
    CLI-->>User: exit / log
  end

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120+ minutes

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly describes the core work of refactoring the repository structure by moving and reorganizing the temoa_initialize and rules components, directly reflecting the primary changes made in the pull request.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/restructure_to_components

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}