fix: #886 - [E2-F2-P3] Create EquilibriaFactory

[Gorkowski]

Target Branch: main

Fixes #886 | Workflow: 1d906f5f

Summary

Adds the EquilibriaFactory so callers can obtain equilibria strategies by name, mirroring the factory pattern used elsewhere in particula. The factory manages a case-insensitive registry of builders, forwards parameter maps after making a local copy, and raises a helpful ValueError when an unknown strategy name is requested. Co-located tests cover builder registration, parameter propagation, case-insensitive lookup, and the expected error handling.

What Changed

New Components

• particula/equilibria/equilibria_factories.py - Introduces EquilibriaFactory, implements get_builders() returning fresh builders, and get_strategy() that normalizes strategy names, copies parameter maps, delegates validation to builders, and reports valid choices when an unknown name is supplied.
• particula/equilibria/tests/equilibria_factories_test.py - Adds tests covering builder map contents, fresh builder instances, parameter forwarding, case-insensitive lookup, handling of empty/None parameters, and expected exceptions for invalid names or parameter values.

Modified Components

• particula/equilibria/__init__.py - Re-exports EquilibriaFactory so the new entry point is available from the equilibria package.

Tests Added/Updated

• particula/equilibria/tests/equilibria_factories_test.py - Validates strategy creation defaults, parameterized builds, case-insensitive lookups, and error paths to achieve full coverage of the factory logic.

How It Works

Every call to get_builders() returns a fresh mapping keyed by lowercased names so factories cannot share builder instances inadvertently. get_strategy() lowercases the requested name, looks it up in the builder map, copies the provided parameter dict (if any) before passing it to the builder, and finally builds the strategy. A ValueError lists available strategy names when a caller requests something unknown, keeping the factory behavior predictable and transparent.

Implementation Notes

• Why this approach: Matching the existing factory infrastructure keeps equilibria code consistent with WallLossFactory and friends, making it easy to add future strategies.
• Error messaging: Unknown strategy names echo the valid options so callers can correct typos without inspecting code.
• Builder isolation: Fresh builder instances guard against shared mutable state between successive factory calls.

Testing

• Not run (not requested)

[Copilot]

Pull request overview

This PR implements EquilibriaFactory to provide string-based strategy selection for equilibria solvers, completing phase P3 of the E2-F2 Equilibria Runnable Refactor. The factory follows the established StrategyFactoryABC pattern used throughout particula, enabling configuration-file-driven strategy instantiation.

Changes:

• Added EquilibriaFactory with registry-based builder management and case-insensitive strategy lookup
• Implemented comprehensive test suite covering builder isolation, parameter propagation, and error handling
• Exported factory from equilibria package for external consumption

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
particula/equilibria/equilibria_factories.py	Implements EquilibriaFactory with get_builders() and get_strategy() methods, providing case-insensitive lookup, parameter copying, and enhanced error messages listing valid strategy types
particula/equilibria/tests/equilibria_factories_test.py	Comprehensive test suite validating builder freshness, parameter forwarding, case-insensitive lookup, default handling, and error paths for invalid strategy names and parameter values
particula/equilibria/__init__.py	Exports EquilibriaFactory to make it accessible from the equilibria package

---

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