Routing DataModel: store-then-build (defer device construction to solve) by ramakrishnap-nv · Pull Request #1556 · NVIDIA/cuopt

ramakrishnap-nv · 2026-07-10T18:04:38Z

Summary

Routing DataModel now records its setter calls and builds the device model lazily at solve, instead of pushing each input to the GPU as it is set. This keeps inputs host-resident while a problem is assembled and is the foundation for host-only (remote / gRPC) problem construction.

Behavior-preserving, except that C++ validation and dtype-cast warnings now surface at solve time rather than at the setter call. Full routing suite passes.

🤖 Generated with Claude Code

The public DataModel no longer inherits the Cython wrapper and no longer pushes each input to the GPU as it is set. Instead it records the setter calls and materializes the device (Cython) data model lazily -- when a solve runs or a getter is queried -- by replaying the recorded calls onto the wrapper. Size scalars are answered directly from the constructor args so setter-time validation does not trigger a build. This keeps the user's inputs host-resident while a problem is being assembled and exposes the recorded inputs for host-only problem construction (remote / gRPC serialization). Behavior is preserved except that wrapper/C++ validation and dtype-cast warnings now surface at build/solve time rather than at the setter call; two tests are updated to reflect this deferral. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>

copy-pr-bot · 2026-07-10T18:04:42Z

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

The recorder/delegator methods were enumerated in _SETTERS/_GETTERS name lists, a second copy of the DataModel method surface that would silently drift when a setter/getter is added to the wrapper. Install them by introspecting the wrapper's method surface instead, so the wrapper stays the single source of truth and adding a method needs no change here. Explicit overrides (matrix setters, size scalars) are skipped by the auto-install. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>

The matrix setters kept a shadow dict (self.costs / self.transit_times) solely for the public duplicate-vehicle-type guard, which meant a future setter needing a set-time "already set?" check would silently need its own shadow. Drop the shadows: the matrix setters now auto-record like every other setter, and the guard reads the recorded calls via _recorded(). Add test_recording_covers_wrapper_surface so a new wrapper method that the recording layer does not handle (e.g. a mutator not named set_*/add_*) fails loudly instead of silently dropping its data. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>

Clarify three low-severity trade-offs surfaced in review: the _SKIP_GETTERS helper exclusion list, get_num_orders mirroring the wrapper's n_orders == -1 default, and the duplicate-matrix guards reading vehicle_type as recorded args[1]. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>

"Recording" named the mechanism; "lazy" names the intent -- the device model is built lazily at solve. Pure rename: _recording.py -> _lazy.py, _RecordingDataModel -> _LazyDataModel, test_recording.py -> test_lazy.py. No behavior change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>

coderabbitai · 2026-07-13T15:31:05Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 71d1395a-bc34-47bf-ac4f-7d1ab81eb327

📥 Commits

Reviewing files that changed from the base of the PR and between f79ae32 and d396b9e.

📒 Files selected for processing (2)

docs/cuopt/source/cuopt-python/routing/routing-api.rst
python/cuopt/cuopt/routing/_lazy.py

💤 Files with no reviewable changes (1)

docs/cuopt/source/cuopt-python/routing/routing-api.rst

📝 Walkthrough

Walkthrough

Changes

Lazy routing DataModel

Layer / File(s)	Summary
Lazy model recording and materialization `python/cuopt/cuopt/routing/_lazy.py`, `docs/cuopt/source/cuopt-python/routing/routing-api.rst`	Adds deferred setter recording, input normalization, on-demand wrapper construction, replayed calls, direct size getters, dynamically installed getter/setter methods, and updated inheritance documentation.
Solver integration and validation checks `python/cuopt/cuopt/routing/vehicle_routing.py`	Routes `DataModel` through the lazy base, checks duplicate matrices from recorded calls, and builds models before `Solve` and `BatchSolve`.
Lazy surface and deferred validation tests `python/cuopt/cuopt/tests/routing/test_lazy.py`, `python/cuopt/cuopt/tests/routing/test_warnings_exceptions.py`	Adds wrapper-surface coverage and updates warning and invalid-model tests for deferred building and validation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: tmckayus

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: lazy, store-then-build routing DataModel construction deferred to solve time.
Description check	✅ Passed	The description matches the changes and accurately notes lazy recording, solve-time build, and shifted validation/warning timing.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch routing-cpu-api-phase2

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

github-actions · 2026-07-13T15:32:29Z

CI Test Summary

✅ All 22 test job(s) passed.

ramakrishnap-nv · 2026-07-13T16:48:25Z

@coderabbitai review

coderabbitai · 2026-07-13T16:48:30Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai

🧹 Nitpick comments (1)

python/cuopt/cuopt/routing/vehicle_routing.py (1)
23-60: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Document the deferred-validation behavior for users.

The class docstring's "Note" section doesn't mention that, with the lazy build layer, validation errors and dtype-cast warnings for setter inputs now surface at Solve/BatchSolve/getter time rather than at the setter call itself. This is a real debugging-experience change (per the PR summary, "C++ validation and dtype-cast warnings occur during model building or solving instead of at setter calls") and should be called out for users of the public API.
📝 Suggested docstring addition
       - Array parameters documented below as ``cudf.Series`` or
         ``cudf.DataFrame`` also accept an equivalent ``numpy.ndarray`` or
         ``pandas.Series``/``pandas.DataFrame``. cuDF inputs stay on the GPU;
         host (numpy/pandas) inputs are copied to the device for the local
         solve. Python lists and tuples are not supported.
+
+      - Setter inputs are recorded and only validated/cast to device types
+        when the model is built, i.e. when ``Solve``/``BatchSolve`` runs or a
+        getter is queried -- not at the setter call itself. Input errors and
+        dtype-cast warnings may therefore surface later than the offending
+        setter call.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@python/cuopt/cuopt/routing/vehicle_routing.py` around lines 23 - 60, Update
the DataModel class docstring’s Note section to document that setter input
validation errors and dtype-cast warnings are deferred by the lazy build layer
and surface during Solve, BatchSolve, or getter calls rather than at setter
invocation.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@python/cuopt/cuopt/routing/vehicle_routing.py`:
- Around line 23-60: Update the DataModel class docstring’s Note section to
document that setter input validation errors and dtype-cast warnings are
deferred by the lazy build layer and surface during Solve, BatchSolve, or getter
calls rather than at setter invocation.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: dc621816-47b0-4e06-b7b8-9ef0a7185389

📥 Commits

Reviewing files that changed from the base of the PR and between 37a099e and f79ae32.

📒 Files selected for processing (4)

python/cuopt/cuopt/routing/_lazy.py
python/cuopt/cuopt/routing/vehicle_routing.py
python/cuopt/cuopt/tests/routing/test_lazy.py
python/cuopt/cuopt/tests/routing/test_warnings_exceptions.py

ramakrishnap-nv · 2026-07-13T17:46:55Z

@CodeRabbit review

coderabbitai · 2026-07-13T17:47:00Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

- Record-time normalization (mixed IR): host inputs (numpy/pandas) are copied to a numpy array the model owns so the recorded calls are a serializable host IR and the user's array can be released; device (cuDF/cupy) inputs stay on device to preserve the zero-copy GPU path (exported to host only on serialize). - Transient build: the device model is no longer cached -- each solve/getter builds fresh and discards -- so an instance never holds both a host IR and a device copy (fixes the memory-doubling regression). - Declarative surface spec instead of dir() on the compiled wrapper, so constructing/recording imports no CUDA (wrapper imported lazily only at build). test_lazy guards the spec against drift. - Thread-safe first-call init. Getters still resolve via a transient build; host-mirror resolution and record-time dtype warnings migrate in follow-ups. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>

The DataModel autoclass used :show-inheritance:, which rendered a "Bases:" line referencing the private implementation base (_LazyDataModel) that is not part of the public API -- an unresolved cross-reference that failed the docs build (warnings treated as errors). Drop :show-inheritance: for DataModel so the reference documents the public class and its members without dangling on an implementation detail (rather than suppressing the warning via nitpick_ignore). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Ramakrishna Prabhu <ramakrishnap@nvidia.com>

Iroy30 · 2026-07-15T00:19:05Z

+    loudly if a new wrapper method -- e.g. a mutator not named set_*/add_* --
+    is added without being recorded, instead of silently dropping its data.
+    """
+    dm = routing.DataModel(1, 1)  # triggers _install_methods


What happens if user calls dm.random_func_call(x, y, z) ?
Should this be a test or a validation within cuopt

Iroy30 · 2026-07-15T00:21:30Z

Just a few thoughts:

How would I a developer add a new function to data model , what needs to be done?
The naming of the Lazy Data Model and file could be better

ramakrishnap-nv added this to the 26.08 milestone Jul 10, 2026

ramakrishnap-nv added breaking Introduces a breaking change improvement Improves an existing functionality labels Jul 10, 2026

ramakrishnap-nv self-assigned this Jul 10, 2026

ramakrishnap-nv and others added 4 commits July 10, 2026 15:25

ramakrishnap-nv marked this pull request as ready for review July 13, 2026 15:29

ramakrishnap-nv requested a review from a team as a code owner July 13, 2026 15:29

ramakrishnap-nv requested a review from tmckayus July 13, 2026 15:29

Merge branch 'main' into routing-cpu-api-phase2

2691e92

Merge branch 'main' into routing-cpu-api-phase2

f79ae32

coderabbitai Bot reviewed Jul 13, 2026

View reviewed changes

ramakrishnap-nv and others added 2 commits July 13, 2026 16:44

Iroy30 reviewed Jul 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Routing DataModel: store-then-build (defer device construction to solve)#1556

Routing DataModel: store-then-build (defer device construction to solve)#1556
ramakrishnap-nv wants to merge 9 commits into
mainfrom
routing-cpu-api-phase2

ramakrishnap-nv commented Jul 10, 2026 •

edited

Loading

Uh oh!

copy-pr-bot Bot commented Jul 10, 2026

Uh oh!

coderabbitai Bot commented Jul 13, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

github-actions Bot commented Jul 13, 2026 •

edited

Loading

Uh oh!

ramakrishnap-nv commented Jul 13, 2026

Uh oh!

coderabbitai Bot commented Jul 13, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

ramakrishnap-nv commented Jul 13, 2026

Uh oh!

coderabbitai Bot commented Jul 13, 2026 •

edited

Loading

Uh oh!

Iroy30 Jul 15, 2026

Uh oh!

Iroy30 commented Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ramakrishnap-nv commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

copy-pr-bot Bot commented Jul 10, 2026

Uh oh!

coderabbitai Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

github-actions Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CI Test Summary

Uh oh!

ramakrishnap-nv commented Jul 13, 2026

Uh oh!

coderabbitai Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

ramakrishnap-nv commented Jul 13, 2026

Uh oh!

coderabbitai Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Iroy30 Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

Iroy30 commented Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ramakrishnap-nv commented Jul 10, 2026 •

edited

Loading

coderabbitai Bot commented Jul 13, 2026 •

edited

Loading

github-actions Bot commented Jul 13, 2026 •

edited

Loading

coderabbitai Bot commented Jul 13, 2026 •

edited

Loading

coderabbitai Bot commented Jul 13, 2026 •

edited

Loading