Skip to content
STIMSMITH

constraint

Concept WIKI v1 · 6/22/2026

A constraint, in the constrained-random verification paradigm, is a user-defined callable (typically a Python function) registered on a randomized object to restrict the legal combinations of its random variables. Constraints consume the current values of the variables listed in their dependency tuple and return a boolean, allowing the random solver to reject or accept a proposed randomization.

Definition

In constrained-random test generation, a constraint is a predicate that is attached to a randomized object so that the generator only produces values satisfying the predicate. Each constraint is supplied together with a tuple naming the random variables whose values are passed to it as arguments.

Mechanism in constrainedrandom

The constrainedrandom Python library exposes constraints through the add_constraint method on RandObj subclasses. The call takes:

  • A callable (often a plain Python function) that returns a truthy value when the constraint is satisfied.
  • A tuple of random-variable names; the current values of those variables are passed positionally to the callable when it is evaluated.

In the documented ldInstr example, two constraints are registered:

  1. wb_dst_src(wb, dst0, src0) — when writeback (wb) is set, forbids dst0 from equalling src0; otherwise trivially satisfied.
  2. sum_src0_imm0(src0_value, imm0) — requires the sum of the model-supplied src0_value and the immediate imm0 to be word-aligned (address & 3 == 0) and to fit within 32 bits (address < 0xffffffff).

Both are wired up with self.add_constraint(...), with the second argument naming the dependent variables in the order they will be supplied to the function.

Relationship to random variables

Constraints operate on random variables (add_rand_var). Random variables can declare a bit width and a generation order, and may be backed by either a width or a user-supplied value function (fn). Constraints reference the variables by name; their positional arguments are filled from the variable values at evaluation time.

Broader context

  • In constraint logic programming, constraints generalize Prolog's equality over Herbrand terms to decidable theories, supporting declarative modeling and combinatorial solving. [arxiv:2402.17286]
  • In program analysis, constraint-based reachability uses constraint solving over computational domains (conditionals, loops, arrays, memory) — interpreting classical filtering consistencies from constraint programming — to analyze infinite-state imperative programs. [arxiv:1302.3290]

These are conceptual relatives: the same word "constraint" denotes a declarative predicate over variables used by a solver, whether the solver drives a logic program, a static analyzer, or a hardware-verification randomizer.

See also

  • ldInstr — example randomized object that uses constraints.

LINKED ENTITIES

1 links
ldInstr USES

CITATIONS

4 sources
4 citations
[1] In the `constrainedrandom` library, a constraint is registered via `add_constraint(fn, (var1, var2, ...))`; the function receives the named variables' current values and returns a boolean used to gate randomization. Examples — constrainedrandom 1.0.0 documentation
[2] The `ldInstr` example defines a `wb_dst_src` constraint that forbids `dst0 == src0` when writeback is enabled, and a `sum_src0_imm0` constraint enforcing word alignment and no 32-bit overflow on `src0_value + imm0`. Examples — constrainedrandom 1.0.0 documentation
[3] In constraint logic programming, constraints generalize equality over Herbrand terms to decidable constraint theories, subsuming Prolog and enabling declarative combinatorial problem solving. A Constraint-based Mathematical Modeling Library in Prolog with Answer Constraint Semantics
[4] Constraint-based reachability interprets imperative constructs (conditionals, loops, arrays, memory) as constraints over a computational domain and reuses classical filtering consistencies from Constraint Programming to analyze infinite-state systems. Constraint-based reachability