Refactor GroupTreeRates to OPM style and integrate with updateWellControls

[Copilot]

The GroupTreeRates module used Matlab-style free functions and camelCase naming. The TODO in updateWellControls described how distributeGroupTreeRates should integrate but had no implementation.

Style refactoring (GroupTreeRates.hpp/cpp)

• Wrapped free functions into GroupTreeRates<Scalar> class with static methods, matching OPM patterns like BlackoilWellModelConstraints
• Renamed to snake_case: distributeGroupTreeRates → distribute, setSubRates → set_sub_rates, findWorstOffendingChild → find_worst_offending_child, updateParentStatus → update_parent_status
• GroupTreeNode::guideRate → guide_rate
• OPM-style include guard, \brief/\param Doxygen tags

Integration with updateWellControls (BlackoilWellModel_impl.hpp)

• Original function preserved as updateWellControlsOriginal
• New updateWellControls calls original first, then implements the three TODO items:
  1. Build tree: Recursive traversal from FIELD group, populating flat GroupTreeNode vector with rate limits (from productionControls), current rates (from well/group state), and guide rates
  2. Distribute: GroupTreeRates<Scalar>::distribute(tree)
  3. Apply: Write distributed rates back to wellState().surface_rates and groupState().production_rates

Only applies to single-phase rate controls (ORAT/WRAT/GRAT); skips LRAT/RESV/FLD where the simplified distribution doesn't apply.

// Usage after refactor:
GroupTreeRates<double>::distribute(tree);
GroupTreeRates<double>::set_sub_rates(tree, 0);
GroupTreeRates<double>::find_worst_offending_child(tree, 0, excess);
GroupTreeRates<double>::update_parent_status(tree, idx);

Tests

• All 16 existing test cases updated to class-based API; no behavioral changes.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.