feat: support setting initial values for individual variables

src/solvers/coin_cbc.rs

@@ -23,15 +23,20 @@ pub fn coin_cbc(to_solve: UnsolvedProblem) -> CoinCbcProblem {
         variables,
     } = to_solve;
     let mut model = Model::default();
+    let mut initial_solution = Vec::with_capacity(variables.initial_solution_len());
     let columns: Vec<Col> = variables
-        .into_iter()
+        .iter_variables_with_def()
         .map(
-            |VariableDefinition {
-                 min,
-                 max,
-                 is_integer,
-                 ..
-             }| {
+            |(
+                var,
+                &VariableDefinition {
+                    min,
+                    max,
+                    initial,
+                    is_integer,
+                    ..
+                },
+            )| {
                 let col = model.add_col();
                 // Variables are created with a default min of 0
                 model.set_col_lower(col, min);
@@ -41,6 +46,9 @@ pub fn coin_cbc(to_solve: UnsolvedProblem) -> CoinCbcProblem {
                 if is_integer {
                     model.set_integer(col);
                 }
+                if let Some(val) = initial {
+                    initial_solution.push((var, val));
+                };
                 col
             },
         )
@@ -52,12 +60,16 @@ pub fn coin_cbc(to_solve: UnsolvedProblem) -> CoinCbcProblem {
         ObjectiveDirection::Maximisation => Sense::Maximize,
         ObjectiveDirection::Minimisation => Sense::Minimize,
     });
-    CoinCbcProblem {
+    let mut problem = CoinCbcProblem {
         model,
         columns,
         has_sos: false,
         mip_gap: None,
+    };
+    if !initial_solution.is_empty() {
+        problem = problem.with_initial_solution(initial_solution);
     }
+    problem
 }
 
 /// A coin-cbc model
@@ -234,7 +246,7 @@ impl WithMipGap for CoinCbcProblem {
 
 #[cfg(test)]
 mod tests {
-    use crate::{variables, Solution, SolverModel, WithInitialSolution};
+    use crate::{variable, variables, Solution, SolverModel, WithInitialSolution};
     use float_eq::assert_float_eq;
 
     #[test]
@@ -261,4 +273,23 @@ mod tests {
         let sol = pb.solve().unwrap();
         assert_float_eq!(sol.value(v), limit, abs <= 1e-8);
     }
+
+    #[test]
+    fn solve_problem_with_initial_variable_values() {
+        let limit = 3.0;
+        // Solve problem once
+        variables! {
+            vars:
+                0.0 <= v <= limit;
+        };
+        let pb = vars.maximise(v).using(super::coin_cbc);
+        let sol = pb.solve().unwrap();
+        assert_float_eq!(sol.value(v), limit, abs <= 1e-8);
+        // Recreate problem and solve with initial solution
+        let mut vars = variables!();
+        let v = vars.add(variable().min(0).max(limit).initial(2));
+        let pb = vars.maximise(v).using(super::coin_cbc);
+        let sol = pb.solve().unwrap();
+        assert_float_eq!(sol.value(v), limit, abs <= 1e-8);
+    }
 }

src/solvers/cplex.rs

@@ -40,6 +40,7 @@ pub fn cplex_with_env(to_solve: UnsolvedProblem, cplex_env: Environment) -> CPLE
                 max,
                 is_integer,
                 ref name,
+                ..
             },
         )| {
             let coeff = *to_solve

src/solvers/highs.rs

@@ -26,11 +26,14 @@ pub fn highs(to_solve: UnsolvedProblem) -> HighsProblem {
         ObjectiveDirection::Minimisation => highs::Sense::Minimise,
     };
     let mut columns = Vec::with_capacity(to_solve.variables.len());
+    let mut initial_solution = Vec::with_capacity(to_solve.variables.initial_solution_len());
+
     for (
         var,
         &VariableDefinition {
             min,
             max,
+            initial,
             is_integer,
             ..
         },
@@ -44,15 +47,22 @@ pub fn highs(to_solve: UnsolvedProblem) -> HighsProblem {
             .unwrap_or(&0.);
         let col = highs_problem.add_column_with_integrality(col_factor, min..max, is_integer);
         columns.push(col);
+        if let Some(val) = initial {
+            initial_solution.push((var, val));
+        }
     }
-    HighsProblem {
+    let mut problem = HighsProblem {
         sense,
         highs_problem,
         columns,
         initial_solution: None,
         verbose: false,
         options: Default::default(),
+    };
+    if !initial_solution.is_empty() {
+        problem = problem.with_initial_solution(initial_solution);
     }
+    problem
 }
 
 /// Presolve option
@@ -408,9 +418,9 @@ mod tests {
             .with((2 * x + y) << 4)
             .solve()
             .unwrap();
-        // Recreate same problem with initial values slightly off
-        let initial_x = solution.value(x) - 0.1;
-        let initial_y = solution.value(x) - 1.0;
+        let initial_x = solution.value(x);
+        let initial_y = solution.value(y);
+        // Recreate same problem with initial values
         let mut vars = variables!();
         let x = vars.add(variable().clamp(0, 2));
         let y = vars.add(variable().clamp(1, 3));
@@ -419,10 +429,40 @@ mod tests {
             .using(highs)
             .with((2 * x + y) << 4)
             .with_initial_solution([(x, initial_x), (y, initial_y)])
+            .set_time_limit(0.0)
             .solve()
             .unwrap();
 
-        assert_eq!((solution.value(x), solution.value(y)), (0.5, 3.))
+        assert_eq!((solution.value(x), solution.value(y)), (0.5, 3.));
+    }
+
+    #[test]
+    fn can_solve_with_initial_variable_values() {
+        // Solve problem initially
+        let mut vars = variables!();
+        let x = vars.add(variable().clamp(0, 2));
+        let y = vars.add(variable().clamp(1, 3));
+        let solution = vars
+            .maximise(x + y)
+            .using(highs)
+            .with((2 * x + y) << 4)
+            .solve()
+            .unwrap();
+        let initial_x = solution.value(x);
+        let initial_y = solution.value(y);
+        // Recreate same problem with initial values
+        let mut vars = variables!();
+        let x = vars.add(variable().clamp(0, 2).initial(initial_x));
+        let y = vars.add(variable().clamp(1, 3).initial(initial_y));
+        let solution = vars
+            .maximise(x + y)
+            .using(highs)
+            .with((2 * x + y) << 4)
+            .set_time_limit(0.0)
+            .solve()
+            .unwrap();
+
+        assert_eq!((solution.value(x), solution.value(y)), (0.5, 3.));
     }
 
     #[test]

src/solvers/scip.rs

@@ -33,12 +33,14 @@ pub fn scip(to_solve: UnsolvedProblem) -> SCIPProblem {
             ObjectiveDirection::Minimisation => ObjSense::Minimize,
         });
     let mut var_map = HashMap::new();
+    let mut initial_solution = Vec::with_capacity(to_solve.variables.initial_solution_len());
 
     for (
         var,
         &VariableDefinition {
             min,
             max,
+            initial,
             is_integer,
             ref name,
         },
@@ -56,12 +58,19 @@ pub fn scip(to_solve: UnsolvedProblem) -> SCIPProblem {
         };
         let id = model.add_var(min, max, coeff, name.as_str(), var_type);
         var_map.insert(var, id);
+        if let Some(val) = initial {
+            initial_solution.push((var, val));
+        };
     }
 
-    SCIPProblem {
+    let mut problem = SCIPProblem {
         model,
         id_for_var: var_map,
+    };
+    if !initial_solution.is_empty() {
+        problem = problem.with_initial_solution(initial_solution);
     }
+    problem
 }
 
 /// A SCIP Model
@@ -234,6 +243,34 @@ mod tests {
         assert_eq!((solution.value(x), solution.value(y)), (0.5, 3.))
     }
 
+    #[test]
+    fn solve_problem_with_initial_variable_values() {
+        // Solve problem initially
+        let mut vars = variables!();
+        let x = vars.add(variable().clamp(0, 2));
+        let y = vars.add(variable().clamp(1, 3));
+        let solution = vars
+            .maximise(x + y)
+            .using(scip)
+            .with((2 * x + y) << 4)
+            .solve()
+            .unwrap();
+        // Recreate same problem with initial values slightly off
+        let initial_x = solution.value(x) - 0.1;
+        let initial_y = solution.value(x) - 1.0;
+        let mut vars = variables!();
+        let x = vars.add(variable().clamp(0, 2).initial(initial_x));
+        let y = vars.add(variable().clamp(1, 3).initial(initial_y));
+        let solution = vars
+            .maximise(x + y)
+            .using(scip)
+            .with((2 * x + y) << 4)
+            .solve()
+            .unwrap();
+
+        assert_eq!((solution.value(x), solution.value(y)), (0.5, 3.))
+    }
+
     #[test]
     fn can_solve_with_equality() {
         let mut vars = variables!();

src/variable.rs

@@ -118,6 +118,7 @@ impl FormatWithVars for Variable {
 pub struct VariableDefinition {
     pub(crate) min: f64,
     pub(crate) max: f64,
+    pub(crate) initial: Option<f64>,
     pub(crate) name: String,
     pub(crate) is_integer: bool,
 }
@@ -128,6 +129,7 @@ impl VariableDefinition {
         VariableDefinition {
             min: f64::NEG_INFINITY,
             max: f64::INFINITY,
+            initial: None,
             name: String::new(),
             is_integer: false,
         }
@@ -177,6 +179,27 @@ impl VariableDefinition {
         self
     }
 
+    /// Set the initial value of the variable. This may help the solver to find a solution significantly faster.
+    ///
+    /// **Warning**: not all solvers support initial solutions.
+    /// Refer to the documentation of the solver you are using.
+    ///
+    /// ```
+    /// # use good_lp::{ProblemVariables, variable, default_solver, SolverModel, Solution};
+    /// let mut problem = ProblemVariables::new();
+    /// let x = problem.add(variable().max(3).initial(3));
+    /// let y = problem.add(variable().max(5).initial(5));
+    /// if cfg!(not(any(feature="clarabel"))) {
+    ///     let solution = problem.maximise(x + y).using(default_solver).solve().unwrap();
+    ///     assert_eq!(solution.value(x), 3.);
+    ///     assert_eq!(solution.value(y), 5.);
+    /// }
+    /// ```
+    pub fn initial<N: Into<f64>>(mut self, value: N) -> Self {
+        self.initial = Some(value.into());
+        self
+    }
+
     /// Set the name of the variable. This is useful in particular when displaying the problem
     /// for debugging purposes.
     ///
@@ -262,12 +285,16 @@ pub fn variable() -> VariableDefinition {
 #[derive(Default)]
 pub struct ProblemVariables {
     variables: Vec<VariableDefinition>,
+    initial_count: usize,
 }
 
 impl ProblemVariables {
     /// Create an empty list of variables
     pub fn new() -> Self {
-        ProblemVariables { variables: vec![] }
+        ProblemVariables {
+            variables: vec![],
+            initial_count: 0,
+        }
     }
 
     /// Add a anonymous unbounded continuous variable to the problem
@@ -289,6 +316,9 @@ impl ProblemVariables {
     /// ```
     pub fn add(&mut self, var_def: VariableDefinition) -> Variable {
         let index = self.variables.len();
+        if var_def.initial.is_some() {
+            self.initial_count += 1;
+        }
         self.variables.push(var_def);
         Variable::at(index)
     }
@@ -390,6 +420,20 @@ impl ProblemVariables {
         self.variables.is_empty()
     }
 
+    /// Returns the number of variables with initial solution values
+    ///
+    /// ```
+    /// use good_lp::{variable, variables};
+    /// let mut vars = variables!();
+    /// vars.add(variable());
+    /// vars.add(variable().initial(5));
+    /// vars.add(variable());
+    /// assert_eq!(vars.initial_solution_len(), 1);
+    /// ```
+    pub fn initial_solution_len(&self) -> usize {
+        self.initial_count
+    }
+
     /// Display the given expression or constraint with the correct variable names
     ///
     /// ```

tests/variables.rs

@@ -27,22 +27,6 @@ fn large_sum() {
     assert_eq!(sum_right, sum_reverse)
 }
 
-#[test]
-#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
-fn complete() {
-    let mut var1 = variables!();
-    let mut var2 = variables!();
-    assert_eq!(
-        // variables iss the size of an empty vector
-        std::mem::size_of_val(&Vec::<u8>::new()),
-        std::mem::size_of_val(&var1)
-    );
-    let a = var1.add_variable();
-    let b = var2.add_variable();
-    let _sum_a = a + a;
-    let _diff_b = b - b + b;
-}
-
 #[test]
 #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
 fn debug_format() {