selen 0.15.5

Constraint Satisfaction Problem (CSP) solver
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355

//! Public Variable Factory API
//!
//! This module provides the clean, user-friendly API for creating variables in constraint models.
//! This is the ONLY API that end users should use for variable creation.
//!
//! ## Single Variable Creation
//! - `int(min, max)` - Create a single integer variable
//! - `float(min, max)` - Create a single floating-point variable  
//! - `bool()` - Create a single boolean variable (0 or 1)
//! - `intset(values)` - Create a variable from a set of specific integer values
//!
//! ## Multiple Variable Creation
//! - `ints(n, min, max)` - Create n integer variables with the same bounds
//! - `floats(n, min, max)` - Create n floating-point variables with the same bounds
//! - `bools(n)` - Create n boolean variables

use crate::model::core::Model;
use crate::variables::{Val, VarId};

impl Model {
    // ========================================================================
    // SINGLE VARIABLE CREATION - PRIMARY PUBLIC API
    // ========================================================================

    /// Create an integer variable with specified bounds.
    /// 
    /// Creates a variable that can take any integer value between `min` and `max` (inclusive).
    ///
    /// # Arguments
    /// * `min` - Minimum value for the variable (inclusive)
    /// * `max` - Maximum value for the variable (inclusive)
    ///
    /// # Example
    /// ```
    /// use selen::prelude::*;
    /// let mut m = Model::default();
    /// let x = m.int(1, 10);     // Variable from 1 to 10
    /// let y = m.int(-5, 15);    // Variable from -5 to 15
    /// ```
    pub fn int(&mut self, min: i32, max: i32) -> VarId {
        self.new_var_unchecked(Val::ValI(min), Val::ValI(max))
    }

    /// Create a floating-point variable with specified bounds.
    /// 
    /// Creates a variable that can take any floating-point value between `min` and `max` (inclusive).
    /// The precision is controlled by the model's `float_precision_digits` setting.
    ///
    /// # Arguments
    /// * `min` - Minimum value for the variable (inclusive)
    /// * `max` - Maximum value for the variable (inclusive)
    ///
    /// # Example
    /// ```
    /// use selen::prelude::*;
    /// let mut m = Model::default();
    /// let x = m.float(0.0, 10.0);    // Variable from 0.0 to 10.0
    /// let y = m.float(-1.5, 3.14);   // Variable from -1.5 to 3.14
    /// ```
    pub fn float(&mut self, min: f64, max: f64) -> VarId {
        self.new_var_unchecked(Val::ValF(min), Val::ValF(max))
    }

    /// Create a boolean variable (0 or 1).
    ///
    /// Creates a variable that can only take values 0 or 1, useful for representing
    /// boolean logic, flags, or binary decisions.
    /// 
    /// # Returns
    /// A `VarId` that can take values 0 (false) or 1 (true)
    ///
    /// # Example
    /// ```
    /// use selen::prelude::*;
    /// let mut m = Model::default();
    /// let flag = m.bool();          // 0 or 1
    /// let enabled = m.bool();       // 0 or 1
    /// 
    /// // Use in constraints
    /// m.new(flag.ne(enabled));    // Flags must be different
    /// ```
    pub fn bool(&mut self) -> VarId {
        self.int(0, 1)
    }

    /// Create an integer variable from a specific set of values.
    /// 
    /// Creates a variable that can only take values from the provided list.
    /// This is useful for non-contiguous domains, categorical values, or
    /// when you need precise control over allowed values.
    ///
    /// # Arguments
    /// * `values` - Vector of integer values that the variable can take
    ///
    /// # Returns
    /// A `VarId` that can only take values from the provided vector
    ///
    /// # Example
    /// ```
    /// use selen::prelude::*;
    /// let mut m = Model::default();
    /// 
    /// // Variable that can only be prime numbers
    /// let prime = m.intset(vec![2, 3, 5, 7, 11, 13]);
    /// 
    /// // Variable for days of week (1=Monday, 7=Sunday)  
    /// let weekday = m.intset(vec![1, 2, 3, 4, 5, 6, 7]);
    /// 
    /// // Non-contiguous range
    /// let sparse = m.intset(vec![1, 5, 10, 50, 100]);
    /// 
    /// m.new(prime.ne(weekday));
    /// ```
    pub fn intset(&mut self, values: Vec<i32>) -> VarId {
        self.props_mut().on_new_var();
        self.vars_mut().new_var_with_values(values)
    }

    // ========================================================================
    // MULTIPLE VARIABLE CREATION - PUBLIC API
    // ========================================================================

    /// Create multiple integer variables with the same bounds.
    /// 
    /// Creates `n` integer variables, each with the same domain bounds.
    /// This is more efficient than calling `int()` multiple times.
    ///
    /// # Arguments
    /// * `n` - Number of variables to create
    /// * `min` - Minimum value for each variable (inclusive)
    /// * `max` - Maximum value for each variable (inclusive)
    ///
    /// # Returns
    /// A `Vec<VarId>` containing all created variables
    ///
    /// # Example
    /// ```
    /// use selen::prelude::*;
    /// let mut m = Model::default();
    /// let vars = m.ints(5, 1, 10);     // 5 variables, each from 1 to 10
    /// let sudoku_row = m.ints(9, 1, 9); // 9 variables for Sudoku row
    /// ```
    pub fn ints(&mut self, n: usize, min: i32, max: i32) -> Vec<VarId> {
        self.int_vars(n, min, max).collect()
    }

    /// Create multiple floating-point variables with the same bounds.
    /// 
    /// Creates `n` floating-point variables, each with the same domain bounds.
    /// This is more efficient than calling `float()` multiple times.
    ///
    /// # Arguments
    /// * `n` - Number of variables to create
    /// * `min` - Minimum value for each variable (inclusive)
    /// * `max` - Maximum value for each variable (inclusive)
    ///
    /// # Returns
    /// A `Vec<VarId>` containing all created variables
    ///
    /// # Example
    /// ```
    /// use selen::prelude::*;
    /// let mut m = Model::default();
    /// let coords = m.floats(3, 0.0, 1.0);   // 3 variables for x, y, z coordinates
    /// let weights = m.floats(10, 0.0, 100.0); // 10 weight variables
    /// ```
    pub fn floats(&mut self, n: usize, min: f64, max: f64) -> Vec<VarId> {
        self.float_vars(n, min, max).collect()
    }

    /// Create multiple boolean variables.
    /// 
    /// Creates `n` boolean variables, each with domain [0, 1].
    /// This is more efficient than calling `bool()` multiple times.
    ///
    /// # Arguments
    /// * `n` - Number of boolean variables to create
    ///
    /// # Returns
    /// A `Vec<VarId>` containing all created boolean variables
    ///
    /// # Example
    /// ```
    /// use selen::prelude::*;
    /// let mut m = Model::default();
    /// let flags = m.bools(8);           // 8 boolean flags
    /// let choices = m.bools(10);        // 10 binary choices
    /// 
    /// // Use in constraints
    /// m.new(flags[0].ne(flags[1]));   // Different flags
    /// ```
    pub fn bools(&mut self, n: usize) -> Vec<VarId> {
        self.int_vars(n, 0, 1).collect()
    }

    // ========================================================================
    // 2D ARRAY VARIABLE CREATION
    // ========================================================================

    /// Create a 2D array of integer variables with the same bounds.
    /// 
    /// Creates a 2D grid of `rows × cols` integer variables, each with the same bounds.
    /// Useful for grid-based problems like Sudoku, scheduling matrices, or spatial grids.
    ///
    /// # Arguments
    /// * `rows` - Number of rows
    /// * `cols` - Number of columns
    /// * `min` - Minimum value for each variable (inclusive)
    /// * `max` - Maximum value for each variable (inclusive)
    ///
    /// # Returns
    /// A `Vec<Vec<VarId>>` representing the 2D grid
    ///
    /// # Example
    /// ```
    /// use selen::prelude::*;
    /// let mut m = Model::default();
    /// let grid = m.ints_2d(3, 4, 1, 10);  // 3×4 grid, each var in [1..10]
    /// let sudoku = m.ints_2d(9, 9, 1, 9); // 9×9 Sudoku grid
    /// ```
    pub fn ints_2d(&mut self, rows: usize, cols: usize, min: i32, max: i32) -> Vec<Vec<VarId>> {
        (0..rows)
            .map(|_| self.ints(cols, min, max))
            .collect()
    }

    /// Create a 2D array of floating-point variables with the same bounds.
    /// 
    /// Creates a 2D grid of `rows × cols` floating-point variables.
    ///
    /// # Arguments
    /// * `rows` - Number of rows
    /// * `cols` - Number of columns
    /// * `min` - Minimum value for each variable (inclusive)
    /// * `max` - Maximum value for each variable (inclusive)
    ///
    /// # Returns
    /// A `Vec<Vec<VarId>>` representing the 2D grid
    ///
    /// # Example
    /// ```
    /// use selen::prelude::*;
    /// let mut m = Model::default();
    /// let temps = m.floats_2d(5, 10, 0.0, 100.0); // 5×10 temperature matrix
    /// ```
    pub fn floats_2d(&mut self, rows: usize, cols: usize, min: f64, max: f64) -> Vec<Vec<VarId>> {
        (0..rows)
            .map(|_| self.floats(cols, min, max))
            .collect()
    }

    /// Create a 2D array of boolean variables.
    /// 
    /// Creates a 2D grid of `rows × cols` boolean variables (0 or 1).
    ///
    /// # Arguments
    /// * `rows` - Number of rows
    /// * `cols` - Number of columns
    ///
    /// # Returns
    /// A `Vec<Vec<VarId>>` representing the 2D grid of booleans
    ///
    /// # Example
    /// ```
    /// use selen::prelude::*;
    /// let mut m = Model::default();
    /// let board = m.bools_2d(8, 8);  // 8×8 boolean board
    /// ```
    pub fn bools_2d(&mut self, rows: usize, cols: usize) -> Vec<Vec<VarId>> {
        (0..rows)
            .map(|_| self.bools(cols))
            .collect()
    }

    // ========================================================================
    // 3D ARRAY VARIABLE CREATION
    // ========================================================================

    /// Create a 3D array of integer variables with the same bounds.
    /// 
    /// Creates a 3D cube of `depth × rows × cols` integer variables.
    /// Useful for 3D scheduling, spatial problems, or multi-layer grids.
    ///
    /// # Arguments
    /// * `depth` - Number of layers/depth
    /// * `rows` - Number of rows per layer
    /// * `cols` - Number of columns per layer
    /// * `min` - Minimum value for each variable (inclusive)
    /// * `max` - Maximum value for each variable (inclusive)
    ///
    /// # Returns
    /// A `Vec<Vec<Vec<VarId>>>` representing the 3D cube
    ///
    /// # Example
    /// ```
    /// use selen::prelude::*;
    /// let mut m = Model::default();
    /// let cube = m.ints_3d(4, 5, 6, 1, 10);  // 4×5×6 cube, each var in [1..10]
    /// ```
    pub fn ints_3d(&mut self, depth: usize, rows: usize, cols: usize, min: i32, max: i32) -> Vec<Vec<Vec<VarId>>> {
        (0..depth)
            .map(|_| self.ints_2d(rows, cols, min, max))
            .collect()
    }

    /// Create a 3D array of floating-point variables with the same bounds.
    /// 
    /// Creates a 3D cube of `depth × rows × cols` floating-point variables.
    ///
    /// # Arguments
    /// * `depth` - Number of layers/depth
    /// * `rows` - Number of rows per layer
    /// * `cols` - Number of columns per layer
    /// * `min` - Minimum value for each variable (inclusive)
    /// * `max` - Maximum value for each variable (inclusive)
    ///
    /// # Returns
    /// A `Vec<Vec<Vec<VarId>>>` representing the 3D cube
    ///
    /// # Example
    /// ```
    /// use selen::prelude::*;
    /// let mut m = Model::default();
    /// let temps = m.floats_3d(12, 24, 60, -10.0, 50.0); // 12×24×60 3D temp data
    /// ```
    pub fn floats_3d(&mut self, depth: usize, rows: usize, cols: usize, min: f64, max: f64) -> Vec<Vec<Vec<VarId>>> {
        (0..depth)
            .map(|_| self.floats_2d(rows, cols, min, max))
            .collect()
    }

    /// Create a 3D array of boolean variables.
    /// 
    /// Creates a 3D cube of `depth × rows × cols` boolean variables (0 or 1).
    ///
    /// # Arguments
    /// * `depth` - Number of layers/depth
    /// * `rows` - Number of rows per layer
    /// * `cols` - Number of columns per layer
    ///
    /// # Returns
    /// A `Vec<Vec<Vec<VarId>>>` representing the 3D cube of booleans
    ///
    /// # Example
    /// ```
    /// use selen::prelude::*;
    /// let mut m = Model::default();
    /// let cube = m.bools_3d(4, 5, 6);  // 4×5×6 cube of booleans
    /// ```
    pub fn bools_3d(&mut self, depth: usize, rows: usize, cols: usize) -> Vec<Vec<Vec<VarId>>> {
        (0..depth)
            .map(|_| self.bools_2d(rows, cols))
            .collect()
    }
}