[Feat] Constraint-aware neighbour selection to enforce min/max node degree during graph construction

[Shivampal157]

When creating graphs from coordinates, we currently rely on distance-based neighbor selection (radius/kNN variants), but there is no direct mechanism to enforce degree constraints during edge selection itself. In practice this can produce local hubs or under-connected nodes depending on coordinate density.

I propose adding a constraint-aware neighbour selection step that enforces configurable degree bounds while preserving locality.

Proposed API

• min_out_degree (default: None)
• max_out_degree (default: None)
• min_in_degree (default: None)
• max_in_degree (default: None)
• repair_strategy ("knn_fallback" / "radius_expand")

Expected behavior

1. Build candidate neighbors using existing distance logic.
2. Apply degree-constrained edge selection (local + deterministic).
3. Run a repair pass for nodes violating minimum degree.
4. Keep graph directed and preserve required edge attributes (len, vdiff).

Why this is useful

• Prevents unstable degree extremes in irregular/sparse coordinate regions.
• Makes graph quality more controllable at construction time (not only post-hoc diagnostics).
• Helps downstream message passing behave more consistently across domains with varying point density.

Acceptance criteria

• Degree constraints can be enabled/disabled via function arguments.
• Constraint pass works for both sparse and dense coordinate distributions.
• Graph remains valid for existing save/export workflows.
• Tests added for:
  • uniform grid
  • jittered irregular coordinates
  • clustered sparse coordinates
• Reproducible output with fixed seed (where randomness is used).

Notes

This is intentionally scoped to construction-time edge selection, not visualization or additional diagnostics.

[Shivampal157]

Hi @observingClouds , I created this issue. If the issue looks good and valid, please assign it to me

[Calculus0]

I can help with this.

[Shivampal157]

Hi @Calculus0, thanks for your interest in this issue.
I have already started working on this and completed most of the implementation.
If the mentor approves and assigns this issue to me, I will push the changes soon.

[Shivampal157]

@leifdenby @sadamov @kshirajahere , I created this issue. If the issue looks good and valid, please assign it to me