Rai Prescriptive Problem

Prescriptive Problem

Requires relationalai>=1.11.0. The dual-guided multi-objective methods here read solver sensitivity via solve("highs", sensitivity=True); earlier versions reject the request. See rai-setup.

Summary

What: Everything before the solve runs — decision variables, constraints, objectives, problem-type classification, solver selection, and pre-solve validation. Assumes a problem has already been selected via discovery.

When to use:

• Formulating variables, constraints, and objectives for a selected problem; reviewing or validating an existing formulation
• Translating business requirements into mathematical formulation (and eliciting the constraints users can't articulate upfront)
• Debugging formulations that would produce trivial or infeasible solutions (missing constraints, conflicting bounds, wrong aggregation scope), or relaxing an over-constrained formulation to resolve a reported conflict / IIS
• Classifying the problem type (LP / MILP / QP / QCP / NLP / CSP) and choosing a solver
• Designing multi-concept coordination (flow networks, selection + quantity)

When NOT to use:

• Executing the solve, reading status/duals/IIS, quality assessment, or explaining results — see rai-prescriptive-results
• Question discovery (what can this ontology answer) — see rai-discovery
• PyRel syntax — see rai-pyrel; ontology modeling or enrichment — see rai-ontology

Overview:

1. Ground in the base ontology via inspect.schema(model)
2. Define decision variables (type, bounds, scope, naming)
3. Define constraints (forcing, capacity, balance, linking)
4. Define objective(s) (direction, coefficients, multi-component)
5. Validate the complete formulation — including the pre-solver audit that variables/constraints/objectives registered, bound, and grounded
6. Classify the problem type, select the solver, solve and refine (targeted display(ref) diagnosis)
7. Post-solve refinement — present results, surface reactions, iterate on the formulation

Quick Reference — Problem API

from relationalai.semantics.reasoners.prescriptive import Problem
from relationalai.semantics.std import aggregates as aggs

# Problem(model, Float) for MIP-style; Problem(model, Integer) for CSP-style (see references/csp-formulation.md).
problem = Problem(model, Float)

# Decision variable — prefer scoped form (where=[...]); capture the ref for targeted diagnostics.
x_flow = problem.solve_for(Lane.flow, where=[Lane.active], name=["item_id", "src_id"], lower=0.0, type="cont")

# Constraint — capture the ref; name=[Entity.id] makes display rows identifiable.
cap = problem.satisfy(
    model.require(aggs.sum(Lane.flow).per(Source).where(Lane.from_source(Source)) <= Source.capacity),
    name=["cap", Source.id])

cost = problem.minimize(aggs.sum(Lane.flow * Lane.unit_cost))

Problem Type Classification and Solver Selection

Classify from the formulation itself — variable types, then nonlinearity, then constraint structure:

Support matrix and profiles

• Gurobi (commercial, via RAI): best on every type it supports — always prefer it when the user has a license. Needs a named prescriptive engine with a Snowflake secret + external access integration in raiconfig.yaml (see rai-setup); fall back to HiGHS/Ipopt without one.
• HiGHS (open-source): LP, MILP, convex QP objectives. No indicator constraints (implies fails — use Big-M), no SOS, no quadratic constraints, no nonlinear functions.
• MiniZinc (open-source, Chuffed backend): CP/CSP. Requires Problem(model, Integer) — any Float decision or data coerces to MIP and MiniZinc rejects it. solution_limit=K enumerates multiple solutions (SOLUTION_LIMIT status = stopped at K; OPTIMAL = search exhausted). Only all_different and implies are exposed from PyRel today. Native logs need log_to_console=True.
• Ipopt (open-source): smooth continuous NLP, local optima only; no integer/binary variables (will FAIL).

Decision rules, in order: (1) any integer/binary variable → Ipopt invalid; Gurobi preferred, HiGHS without license; MiniZinc only for pure discrete constraint satisfaction. (2) nonlinearity (math.exp/log/sqrt, x**n) → HiGHS and MiniZinc invalid; continuous → Gurobi or Ipopt; discrete + nonlinear → Gurobi only. Trig and division between two decision variables are not lowered to any solver — reformulate piecewise-linear. (3) quadratic constraints → HiGHS invalid. (4) no objective → MiniZinc for discrete CSP; otherwise Gurobi/HiGHS feasibility solve.

Problem-size guidelines and Problem initialization patterns: solver-details.md.

Global constraints

all_different, implies, SOS1/SOS2 give the solver combinatorial structure, with solver requirements: all_different → MiniZinc (else O(n²) pairwise inequalities); implies → Gurobi or MiniZinc (else Big-M); SOS1/SOS2 → Gurobi only (else binary reformulations). Syntax, examples, CP-vs-MIP decision guide: global-constraints.md.

Formulation Workflow

Interaction mode: ask the user first — Guided (confirm variables, constraints, objective at each step; framing involves judgment about hard vs soft and scoping) or One-shot (best single pass, review after).

Step 1: Ground in the base ontology

Before writing solve_for / satisfy / minimize / maximize, confirm every name and type against the real schema:

from relationalai.semantics import inspect
schema = inspect.schema(model)
for name in referenced_concepts:
    assert name in schema, f"Concept {name} not in model"

Catches the two silent failure modes behind most prescriptive errors: hallucinated surface (Customer.tier when the real property is Customer.category — the solver happily runs on wrong variables) and wrong-type inference (Integer treated as Float, masking incorrect bound derivation).

Reuse upstream derived surface. Subtypes and properties earlier steps wrote back (classification subtypes, centrality scores, flags) are in inspect.schema(model) — reference them directly rather than re-deriving. See examples/chained_rules_prescriptive.py.

Confirm modeled dimensions. If the problem spans periods/scenarios/categories, that dimension must exist — as a Concept (Week, Scenario), an Integer ref scoped via std.common.range(), or a model.Enum (relationalai>=1.12; enum-indexed solve_for creates one binary per (entity, member) — csp-formulation.md § Enum-indexed decision). Never iterate the dimension in Python or hand-enumerate its values. See rai-ontology if enrichment is needed.

When to skip: small greenfield models or one-shot formulations you just wrote yourself.

Step 2: Define Variables

What can the solver control? Identify the primary decision entity, then auxiliary/aggregation variables; choose types (cont/int/bin) and bounds from data; for minimize objectives include a slack/unmet variable to avoid infeasibility. Full treatment (context integration, entity creation, parametric/time-indexed, slack): variable-formulation.md.

Step 3: Define Constraints

What must the solution satisfy? Add forcing constraints first (they prevent trivial zero solutions on minimize), then capacity/resource from data properties, then flow conservation for network structure. Derive parameters from data ranges. For multi-period recurrence (inventory balance, sequencing), use declarative quantification — Concept.ref() adjacency joins (w_prev.num == w.num - 1) or where=[t == std.common.range(start, stop)] — one satisfy() grounds all periods: constraint-formulation.md > Temporal recurrence, examples/multi_period_flow_conservation.py. Canonical constraint shapes per problem family: problem-patterns-and-validation.md.

Step 4: Define Objective(s)

Map the stated goal to minimize/maximize (objective-formulation.md). Check trivial-solution risk: "if all variables = 0, are all constraints satisfied?" — if yes, Step 3 needs a forcing constraint. Competing objectives? A penalty bundling two concerns, or a constraint representing a competing goal, may mean the user wants the tradeoff explored — multi-objective-formulation.md (epsilon constraint). Parameter what-if? Parameterize with the Scenario Concept pattern — one solve over all scenarios, results stay in the ontology: scenario-analysis.md.

Step 5: Validate

Structural checks: every variable in ≥1 constraint (a variable appearing only in the objective gets pushed straight to a bound — usually a missing constraint, not a modeling choice); every constraint references ≥1 decision variable; .where() join paths connect to actual data; bounds consistent (lower ≤ upper); exactly one objective for an optimization solve, zero for pure feasibility/CSP.

• Trivial-solution gate (before presenting or solving): substitute every decision variable with its objective-preferred bound (typically zero for minimize) and evaluate against the actual input data. If every constraint still holds, the solver will return that trivial point as optimal — the formulation is wrong. The non-obvious failure: a forcing constraint that exists but is vacuous against current data (its where= matches no rows). Do not present a formulation that fails this gate; if the outcome depends on input data, state that with row-count evidence.
• Data-driven feasibility precheck: when bounds derive from data, verify a feasible point exists — at the constraint's natural disaggregation level (per-entity for per-entity constraints; a global Σ supply ≥ Σ demand can mask per-slice infeasibility). Run as PyRel aggregation queries so the check pushes down to the warehouse. See examples/presolve_feasibility_gate.py.

Pre-solver audit (a-d): run before problem.solve(...).

(a) Registration. solve_for/satisfy/minimize/maximize register Variable_<id>/Constraint_<id>/Objective_<id> concepts — confirm one per call in inspect.schema(model).concepts.

(b) Binding cardinality. Registration does NOT mean binding: solve_for(..., where=[always_false]) registers a variable with zero bindings and the solver runs on an empty decision set:

for var_concept in variables:
    n = len(model.select(model.concept_index[var_concept.name]).to_df())
    if n == 0:
        raise ValueError(f"{var_concept.name} has 0 bindings")   # fix the where= predicate

(c) Coefficient presence. Objective/constraint coefficient Properties must be populated by model.define(...) — an unbound coefficient has no tuples, the join produces no row, and the term silently vanishes (OPTIMAL with a vacuous objective). Check len(model.select(coef_prop).to_df()) > 0 per coefficient.

(d) Constraint binding cardinality. A per-grouping body that references a bound empty for some entities produces no row for them — those entities are silently unconstrained. Capture the satisfy() ref and compare cardinalities:

cap_constr = problem.satisfy(model.require(usage <= Entity.cap), name=["cap", Entity.id])
if len(model.select(cap_constr).to_df()) != len(model.select(Entity).to_df()):
    raise AssertionError("cap_constr short — Entity.cap unpopulated for some entities")

(a)-(d) are the downstream complement of Step 1: Step 1 verifies formulation inputs exist; Step 5 verifies the outputs registered, bound, weighted, and grounded. Full pattern (drill-in with display(ref, limit=10), per-failure-mode lookup): diagnostic-workflow.md and pre-solve-validation.md. Generation/compile failures before any solve: the failure taxonomy at rai-prescriptive-results/references/failure-taxonomy.md (generates/compiles levels); prescriptive-context compile errors (entity ref as scalar, zero entities, type mismatch): compilation-errors.md.

Step 6: Solve and refine (iterate)

Select the solver (section above), solve, and triage. Solve execution mechanics — parameters, diagnostics requests, run-to-completion discipline — live in rai-prescriptive-results; this step is the formulation-side debugging loop, using the refs captured at write time:

• si = problem.solve_info(); si.display() first; branch by status: INFEASIBLE → walk constraints; OPTIMAL with suspicious values → unbound coefficients or vacuous forcing constraints; right shape → problem.verify(*original_fragments) if tolerance-sensitive.
• model.select(var_ref.name, var_ref.lower, var_ref.upper).to_df() — bounds and tuples per instance; catches where= over-/under-scoping.
• problem.display(constr_ref) — grounded sums per row; catches .per() mis-scoping (the silent-OPTIMAL trap), contradictions, and bodies that didn't ground (Step 5(d)'s runtime view).
• problem.display(obj_ref) — expanded objective; catches unbound coefficients. for c in problem.constraints: problem.display(c) when one of many is the offender.
• Sampling very large constraints (limit=N, where= filter): formulation-display.md > Targeted Inspection.
• When proposing a fix, ground it in the root-cause taxonomy: fix-generation-guidelines.md.

Simplify once correct: static parameters over dynamic calculations; objective terms for goals, constraints for hard requirements; group-level over pairwise. formulation-simplification.md.

Step 7: Present, React, Refine

Steps 1-6 build the best formulation from what the user told you; Step 7 discovers what they couldn't articulate until they saw a result. Solve, present (highlighting large shifts from status quo, domain-norm anchors, trade-off costs, boundary solutions — presentation format: rai-prescriptive-results > Result Explanation Guide), ask reaction questions, disambiguate rejections into constraint types, add, re-solve — until acceptance or feasibility pressure forces explicit prioritization. Most real formulations need at least one pass. If the result is technically wrong (infeasible, all-zero, solver error), route to rai-prescriptive-results for diagnosis — it routes back here when the issue is a missing constraint. The full elicitation playbook (diagnostic questions, disambiguation tables, reaction questions, stop conditions, documentation trail): constraint-elicitation.md.

Formulation Principles

1. Context-aware and specific: formulations use the model's actual entities, never generic templates.
2. Rationale-driven and goal-aligned: explain WHY each element fits THIS problem; every element supports the user's stated goals.
3. Valid variations welcome: there is no single right answer — grounded, feasible alternatives are encouraged.
4. All decision variables must be used: a variable appearing in no constraint and no objective is almost always a bug.

Business language framing: describe variables/constraints/objectives in business terms first ("don't exceed warehouse capacity"), then the technical form. Every user-facing description/rationale/business_mapping field reads like a business analyst wrote it (sum(X.quantity).per(Entity) → "total X quantity per entity"); code fields stay valid PyRel.

Constraint vs objective decision rule: if violating it makes the solution invalid → constraint; if it's a preference → objective term. Ambiguous phrases ("keep costs under X", "try to balance") must be clarified — when unclear, default to soft and ask: "if violating this saved 20% on cost, acceptable?" Full disambiguation tables: constraint-elicitation.md.

Business-to-formulation mapping derives from the ontology: concepts/properties/relationships tell you what can be controlled (variables), what has limits (constraints), what the user wants (objective).

Multi-Concept Coordination

When suggesting MULTIPLE cross-product/junction decision concepts, coordinate them:

1. Flow networks (production → transport → fulfillment): conservation constraints — inflow = outflow at transshipment nodes, inventory balance at storage. Note in rationale which base entity needs the balance constraint.
2. Selection + quantity (binary use/don't-use + continuous quantity): linking constraint quantity <= capacity * selection.
3. Shared base entities (multiple decision concepts touching the same Site): balance/conservation at that entity; state "links to [OtherConcept] via [SharedBase]" in the rationale.

Without linking constraints, multiple decision concepts produce trivial (independently-optimized zeros), unbounded, or inconsistent solutions. Not always wrong — the user may intend unlinked variables — so flag it to verify, don't auto-correct.

Common Pitfalls

Silent verify() limitations on solver-only-IC bodies and post-solve misreads are rai-prescriptive-results Common Pitfalls.

Known Limitations

Problem is additive — solve_for/satisfy/minimize accumulate (PyRel append-only; see rai-pyrel > Definitions). No remove/replace: to weaken or drop an element, build a new Problem. Re-calling problem.solve() on the same Problem is safe for adding constraints and re-solving. Only one minimize()/maximize() per Problem (HiGHS rejects multiples); for competing objectives, scalarize and sweep — with sensitivity=True on LP/QP the epsilon-bound's shadow_price is the exact frontier slope, enabling adaptive sampling: multi-objective-formulation.md.

Multi-component objectives combine per-entity terms across concept groups via model.union() (set-union semantics — distinct from | ordered fallback) with an outer sum():

problem.minimize(sum(model.union(
    ResourceGroup.holding_cost * sum(x_inv).per(ResourceGroup).where(...),
    Arc.transport_cost * Arc.x_flow,
    Factory.unit_cost * Factory.x_production)))

Parametric-variable pitfalls (name=[] scalar resolution, cross-concept join attribute collisions), constraint naming, | 0 fallback limitation, numpy casting: known-limitations.md. CSP-style gotchas (MiniZinc pairing, empty-aggregate silent-drop, unexposed globals): known-limitations.md § CSP-style and csp-formulation.md.

Examples

For all example problems and the patterns they demonstrate, see examples-index.md. When reviewing an existing formulation, see formulation-analysis-context.md.

Reference files