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.

[steink]

@copilot I have completely re-thought this algorithm, I belive I have a much better version in this matlab-file. I've tested it extensively and I'm happy with the performance. Even though it's very different from the current in ProdGroupTreeBalancer, I think we still can use the developed framework. One extra complication that we did not treat correct in the first attempt was the handling of groups that don't have guide-rates. These should be completely transparent unless they get an active limit (in which case they distribute rates to their children according to their active limit). Also note that groups which has a preferred control set to FIELD or NONE, should inherit the preferred control from their parents (or parent's parent). I would like you to update ProdGroupTreeBalancer with the algorithm outlined in the matlab-file. Please ask if anything is not clear or if you see parts that can be implemented more efficiently (in terms of code or runtime).

[Copilot]

@copilot I have completely re-thought this algorithm, I belive I have a much better version in this matlab-file. I've tested it extensively and I'm happy with the performance. Even though it's very di...

I'd like to implement this updated algorithm, but I don't see the matlab file you're referencing — it doesn't appear to be attached to this comment or present in the repository. Could you either paste the matlab code directly in a comment here, or push it to the repo (e.g., under examples/ or as a gist link)?

Also, to confirm my understanding of the key behavioral changes:

1. Groups without guide rates should be "transparent" (pass-through) unless they hit an active limit
2. Groups with preferred control = FIELD or NONE inherit preferred control from their parent (or ancestor)
3. Once a transparent group hits its limit, it distributes to children according to that limit

Is that correct? Once I have the matlab file I'll update the implementation.

[steink]

@copilot Sorry, I only pointed to it locally. It's now added to the repo (sortalgo2.m)