Module runtime_api

selen

Module runtime_api 

Source
Expand description

Runtime Constraint API

This module provides a runtime-programmable constraint building API that allows dynamic constraint creation from data, configuration, and business rules.

§Phase 1: Core Expression System

  • ExprBuilder for mathematical expression building (x.add(y).eq(z))
  • VarIdExt trait for direct variable constraint methods
  • ModelExt trait for posting constraints

§Phase 2: Constraint Builder

  • Builder struct for fluent constraint building
  • Model::c() method for ultra-short syntax (m.c(x).eq(5))
  • Global constraint shortcuts (alldiff, alleq, elem, count)

§Phase 3: Boolean Logic

  • Enhanced constraint composition with proper reification
  • Constraint arrays and iteration support
  • Helper functions for combining multiple constraints

§Phase 4: Global Constraints

  • Comprehensive global constraint support (alldiff, alleq, elem, count, betw, atmost, atleast, gcc)
  • Optimized implementations for common constraint patterns
  • Full integration with solver’s global constraint system

§Phase 5: Performance Optimization

  • Optimized expression building with constant folding
  • Efficient batch constraint posting with postall()
  • Performance regression testing and benchmarking
  • Best practices guide for optimal performance

§Performance Characteristics

The runtime API provides flexibility at the cost of some performance overhead:

  • Simple constraints: ~3-4x overhead vs post! macro
  • Complex expressions: ~1.4x overhead vs post! macro
  • Batch operations: Significantly reduced per-constraint overhead
  • Global constraints: Minimal overhead, highly optimized

§When to Use Runtime API vs post! Macro

Use Runtime API for:

  • Data-driven constraint building from configs/databases
  • Complex mathematical expressions with runtime coefficients
  • Dynamic constraint generation based on business rules
  • Global constraint patterns (alldiff, count, etc.)
  • Batch constraint posting scenarios

Use post! macro for:

  • Simple, static constraints known at compile time
  • Maximum performance for basic operations
  • Direct translation from mathematical notation
  • Performance-critical constraint posting loops

§Performance Best Practices

  1. Use batch posting: model.postall(constraints) instead of individual posts
  2. Leverage global constraints: Use alldiff() instead of manual != constraints
  3. Pre-allocate vectors: Use Vec::with_capacity() for large constraint sets
  4. Choose the right API: Runtime API for complex/dynamic, post! for simple/static

Key features:

  • Pure runtime expression building (no macro syntax required)
  • Ultra-short method names for concise code
  • Fluent interface for natural constraint composition
  • Full integration with existing constraint system
  • Performance-optimized implementations

Functions§

all_of
Create a constraint that all given constraints must be satisfied
and_all
Helper functions for constraint arrays and iteration
any_of
Create a constraint that at least one of the given constraints must be satisfied
or_all