NVIDIA cuOpt Examples

The optimization process uses the following components:

Data Inputs

• Locations: 4 locations (Airport, Downtown, and 2 Suburbs).
• Demand: 7-day demand patterns.
• Revenue: Rates by location ranging from $75 to $120 per rental.
• Costs: Weekly operational cost of $240 per car and specific transfer costs between locations.

Optimization Model

• Objective: Maximize revenue - operational costs - transfer costs.
• Decision Variables:
  • Fleet size (Integer)
  • Availability (Continuous)
  • Rentals (Continuous)
  • Transfers (Continuous)
• Constraints:
  • Demand limits
  • Availability
  • Flow conservation
  • Fleet capacity

Outputs and Analysis

The model provides:

• Optimal fleet size and allocation.
• Financial metrics (profit, margins, costs).
• Utilization rates by location.
• Demand satisfaction tracking.
• Transfer operation schedules.
• Visualizations including heatmaps and charts.

cuOpt matches the meaning of a request, not specific keywords. You do not need the user to explicitly say "minimize" or "optimal" to use cuOpt. The following intent families are valid triggers:

Paraphrase rule: If a request can be interpreted as "turn this data into a constraint-respecting plan," treat it as a cuOpt task.

GAMSPy uses a hierarchical structure to build optimization models:

1. Container: A Container acts as a centralized hub that gathers all sets, parameters, variables, and equations.
2. Sets: Define the indices (e.g., plants, markets) for the model. They can be declared separately or combined with data assignment.
3. Parameters: Indexed data (e.g., supply, demand, costs). They use a domain attribute to link to specific Set objects.
4. Variables: The decision variables (e.g., shipment quantities) defined with a domain and a type (e.g., "Positive").
5. Equations: Mathematical constraints. They require a declaration (name, domain) and a definition (the algebraic relationship).
6. Model: Consolidates equations, an objective function, a Sense (e.g., Sense.MIN), and a problem type (e.g., "LP").

from gamspy import Container, Set, Parameter, Variable, Equation, Model, Sum, Sense

m = Container()

# Define Sets
i = Set(container=m, name="i", records=["seattle", "san-diego"])
j = Set(container=m, name="j", records=["new-york", "chicago"])

# Define Parameters
a = Parameter(container=m, name="a", domain=i, records=["seattle", 350])

# Define Variables
x = Variable(container=m, name="x", domain=[i, j], type="Positive")

# Define Equations
supply = Equation(container=m, name="supply", domain=i)
supply[i] = Sum(j, x[i, j]) <= a[i]

# Define Model
obj = Sum((i, j), x[i, j])
transport = Model(m, name="transport", equations=[supply], problem="LP", sense=Sense.MIN, objective=obj)

ReducedCost acts as a 'near-miss' signal for variables that are not currently being used (often resting at a bound of 0).

Key Concepts

• Threshold for Use: A variable at its bound stays optimal if its objective coefficient is improved by less than |ReducedCost|. If improved by more, the variable may become worthwhile.
• Identifying Near-Misses: To find the option closest to being included in the plan, look for the variable with the smallest |ReducedCost| among those currently at 0.
• Unit Comparability: Like duals, reduced costs are objective-units per unit of that variable. To compare different variables, compare the |ReducedCost| as a fraction of its own objective coefficient (e.g., "needs a 3% price move").

Important Limitations

• Continuous Models Only: Like duals, these are only available for LP/QP solutions. For MILP, use differencing.
• Degeneracy: A variable at its bound might have a ReducedCost of ~0 if an alternative optimum exists that uses it without changing the objective.

# Unused options ranked by how close they are to paying off (LP / QP only).
# Compare |reduced cost| within comparable-unit variables:
near = [(v.VariableName, v.ReducedCost) for v in problem.getVariables() if abs(v.Value) < 1e-6]
for name, rc in sorted(near, key=lambda kv: abs(kv[1])):
    note = ("already interchangeable — degenerate" if abs(rc) < 1e-9
            else f"~{abs(rc):.4g} coefficient improvement before it pays off")
    print(f"{name}: reduced cost {rc:+.4g}  ({note})")

The orchestration follows a specific multi-step sequence to move from raw data to a solved cuOpt model.

Execution Sequence

Step 0 (Prerequisite): Perform the cuopt-sandbox sequence: probe $\rightarrow$ env $\rightarrow$ smoke. You must ensure the smoke test passes before attempting to generate schedules or heuristic outputs.

1. optimization-intent-router: Identifies the optimization family (e.g., LP, MILP, QP, or routing).
2. optimization-mode-router: Triggered only if there are signals for replay, audit, or export.
3. tabular-optimization-ingestion: Interprets the roles of the provided tables.
4. cuopt-model-mapper: Clarifies requirements if necessary, maps the interpreted data to a cuOpt model, and executes the solve.

Handoffs after Step 4

Depending on the intent identified in Step 1, the flow hands off to specific formulation and API skills:

• LP / MILP / QP: $\rightarrow$ numerical-optimization-formulation $\rightarrow$ cuopt-numerical-optimization-api-python
• Routing: $\rightarrow$ routing-formulation $\rightarrow$ cuopt-routing-api-python