Package org.ssclab.pl.milp

Class LP

  • public final class LP
extends Object
    This class allows executing and solving formulations of linear programming problems. The method used for solving such optimization problems is the simplex method.
    Version:
    4.0
    Author:
    Stefano Scarioli
    See Also:
    SSC Software www.sscLab.org

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static double NaN  

    • Constructor Summary

      Constructors 
      Constructor Description
      LP​(String pl_text)
      Constructor for use with the problem statement in text format stored in an String.
      LP​(Path path)
      Constructor for use with the problem statement in text format stored in an external file.
      LP​(ArrayList<String> text)
      Constructor for use with the problem statement in text format stored in an ArrayList.
      LP​(JsonProblem pl_json)
      Constructor of a LP object for solving problems formulated in json format.
      LP​(LinearObjectiveFunction fo, ArrayList<Constraint> constraints)
      Constructor Creates an LP object for solving problems expressed in matrix format.
      LP​(LinearObjectiveFunction fo, ListConstraints constraints)
      Constructor of an LP object for solving problems expressed in matrix format.
      LP​(org.ssclab.ref.Input input)
      Constructor of an LP object for solving problems expressed in coefficient format.
      LP​(org.ssclab.ref.Input input, org.ssclab.context.Session session)
      Constructor of an LP object for solving problems expressed in coefficient format.
      LP​(org.ssclab.ref.Input input, org.ssclab.context.Session session, FormatTypeInput.FormatType format)
      Constructor of an LP object for solving problems expressed in sparse format or coefficient format.
      LP​(org.ssclab.ref.Input input, FormatTypeInput.FormatType format)
      Constructor of an LP object for solving problems expressed in either sparse or coefficient format.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      EPSILON getCEpsilon()  
      EPSILON getEpsilon()  
      int getNumMaxIteration()
      This method returns the maximum number of simplex iterations
      Solution getSolution()
      If the problem has an optimal solution, this method returns that optimal solution in the form of an object of the Solution class.
      JsonSolution getSolutionAsJson​(SolutionDetail... option)
      Returns a JsonSolution object that represents the solution of the Linear Programming (LP) or Mixed-Integer Linear Programming (MILP) problem in JSON format.
      double[][] getStandartMatrixA()
      This method returns the matrix A obtained after the process of reduction to standard form (max z , Ax + s=b, x ≥ 0, b ≥ 0) of the original linear programming problem.
      double[] getStandartVectorB()
      This method returns the vector b of the rhs values obtained after the process of reduction to standard form(max z , Ax+s=b, x ≥ 0, b ≥ 0) of the original linear programming problem.
      double[] getStandartVectorC()
      This method returns the vector c of the coefficients of the objective function after the process of reduction to standard form (max z , Ax+s=b, x ≥ 0, b ≥ 0) of the original linear programming problem.
      LPThreadsNumber getThreadsNumber()  
      double[] getValuesSolution()
      If the problem has an optimal solution, this method returns that optimal solution in the form of an array with the values of the variables.
      boolean isJustTakeFeasibleSolution()
      Returns true if only phase 1 execution is set to obtain a feasible solution.
      boolean isParallelSimplex()  
      SolutionType resolve()
      Executes the simplex (phase 1 + phase 2).
      LP resolve​(Object nullable)
      Solves the linear programming (LP) problem and returns the current instance of the LP object.
      LP setCEpsilon​(EPSILON epsilon)
      This method allows setting the epsilon value relative to the tolerance in determining if an optimal solution expressed by phase 1 is close to or equal to zero and thus gives rise to feasible solutions for the initial problem.
      LP setEpsilon​(EPSILON epsilon)
      This method allows setting the epsilon value relative to the tolerance that intervenes in various contexts.
      LP setJustTakeFeasibleSolution​(boolean isStopPhase2)
      Setting to true allows interrupting the simplex at the end of phase 1, in order to determine not an optimal solution but only a feasible solution of the problem.
      LP setNumMaxIteration​(int num_max_iteration)
      This method allows limiting the maximum number of simplex iterations (phase 1 iterations + phase 2 iterations)
      LP setParallelSimplex​(boolean isParallelSimplex)
      If the number of physical cores of the host on which SSc is running is greater than 4 and and if the number of variables constraints and hundreds, the performance of the simplex can be improved by executing the optimization processes in parallel on multiple threads.
      LP setThreadsNumber​(LPThreadsNumber threadsNumber)
      If the set value is AUTO, the system decides the number of threads to use.
      LP setTitle​(String title)
      Allows you to give a title to the current elaboration related to the LP problem to be solved

    • Field Detail

      • NaN

        public static double NaN

    • Constructor Detail

      • LP

        public LP​(String pl_text)
   throws Exception
        Constructor for use with the problem statement in text format stored in an String.
        Parameters:
        pl_text - The text where the file containing the LP problem formulated with the text format is located
        Throws:
        Exception - An exception is thrown if the problem is not correctly formulated or if the file does not exist

      • LP

        public LP​(ArrayList<String> text)
   throws Exception
        Constructor for use with the problem statement in text format stored in an ArrayList.
        Parameters:
        text - An ArrayList (of String objects) containing the problem formulation in the form of text
        Throws:
        Exception - An exception is thrown if the problem is not correctly formulated

      • LP

        public LP​(Path path)
   throws Exception
        Constructor for use with the problem statement in text format stored in an external file.
        Parameters:
        path - The path where the file containing the LP problem formulated with the text format is located
        Throws:
        Exception - An exception is thrown if the problem is not correctly formulated or if the file does not exist

      • LP

        public LP​(LinearObjectiveFunction fo,
          ArrayList<Constraint> constraints)
   throws Exception
        Constructor Creates an LP object for solving problems expressed in matrix format.
        Parameters:
        fo - A LinearObjectiveFunction object representing the objective function
        constraints - The list of constraints expressed as an ArrayList of Constraint objects
        Throws:
        Exception - An exception is thrown if the problem is not correctly formulated

      • LP

        public LP​(LinearObjectiveFunction fo,
          ListConstraints constraints)
   throws Exception
        Constructor of an LP object for solving problems expressed in matrix format.
        Parameters:
        fo - A LinearObjectiveFunction object representing the objective function
        constraints - The list of constraints as a ListConstraints object
        Throws:
        Exception - An exception is thrown if the problem is not correctly formulated

      • LP

        public LP​(org.ssclab.ref.Input input,
          org.ssclab.context.Session session,
          FormatTypeInput.FormatType format)
   throws Exception
        Constructor of an LP object for solving problems expressed in sparse format or coefficient format.
        Parameters:
        input - The problem formulated in sparse format or coefficient format
        session - An SSC working session
        format - Constant to express in which format the problem is formulated (FormatType.SPARSE or FormatType.COEFF)
        Throws:
        Exception - An exception is thrown if the problem is not formulated correctly

      • LP

        public LP​(org.ssclab.ref.Input input,
          FormatTypeInput.FormatType format)
   throws Exception
        Constructor of an LP object for solving problems expressed in either sparse or coefficient format.
        Parameters:
        input - The problem formulated in sparse format
        format - Constant to express in which format the problem is formulated (FormatType.SPARSE or FormatType.COEFF)
        Throws:
        Exception - An exception is thrown if the problem is not formulated correctly

      • LP

        public LP​(org.ssclab.ref.Input input)
   throws Exception
        Constructor of an LP object for solving problems expressed in coefficient format.
        Parameters:
        input - The problem formulated in coefficient format
        Throws:
        Exception - An exception is thrown if the problem is not formulated correctly

      • LP

        public LP​(org.ssclab.ref.Input input,
          org.ssclab.context.Session session)
   throws Exception
        Constructor of an LP object for solving problems expressed in coefficient format.
        Parameters:
        input - The problem formulated in coefficient format
        session - An SSC working session
        Throws:
        Exception - An exception is thrown if the problem is not formulated correctly

      • LP

        public LP​(JsonProblem pl_json)
   throws Exception
        Constructor of a LP object for solving problems formulated in json format.
        Parameters:
        pl_json - JsonProblem object containing the problem in json format
        Throws:
        Exception - if the problem is not correctly formulated

    • Method Detail

      • setEpsilon

        public LP setEpsilon​(EPSILON epsilon)
        This method allows setting the epsilon value relative to the tolerance that intervenes in various contexts. It is used in the following cases:
        During phase one, both in determining the entering variable and in determining the exiting variable with or without the Bland rule; it is also used to determine if the base is degenerate. It is also used at the end of phase one: if there is an auxiliary variable in the base, epsilon is used to determine if it is possible to eliminate the rows and columns of these on the extended table.
        During phase two, both in determining the entering variable and in determining the exiting variable with or without the Bland rule; it is also used to determine if the base is degenerate.
        Parameters:
        epsilon - Tolerance used in various phases of the simplex. Default value 1E-10
        Returns:
        the LP instance (this) on which the method call is being made

      • setCEpsilon

        public LP setCEpsilon​(EPSILON epsilon)
        This method allows setting the epsilon value relative to the tolerance in determining if an optimal solution expressed by phase 1 is close to or equal to zero and thus gives rise to feasible solutions for the initial problem.
        Parameters:
        epsilon - Tolerance of phase 1 solution with respect to zero. Default value 1E-8
        Returns:
        the LP instance (this) on which the method call is being made

      • getEpsilon

        public EPSILON getEpsilon()

      • getCEpsilon

        public EPSILON getCEpsilon()

      • setNumMaxIteration

        public LP setNumMaxIteration​(int num_max_iteration)
                      throws LPException
        This method allows limiting the maximum number of simplex iterations (phase 1 iterations + phase 2 iterations)
        Parameters:
        num_max_iteration - The maximum number of iterations to be executed. Default value 100,000,000.
        Returns:
        the LP instance (this) on which the method call is being made
        Throws:
        LPException - If an incorrect number (zero or negative) is set

      • getNumMaxIteration

        public int getNumMaxIteration()
        This method returns the maximum number of simplex iterations
        Returns:
        The maximum number of iterations

      • resolve

        public SolutionType resolve()
                     throws Exception
        Executes the simplex (phase 1 + phase 2).
        Returns:
        The type of solution found
        Throws:
        Exception - If the execution process generates an error

      • getStandartMatrixA

        public double[][] getStandartMatrixA()
                              throws org.ssclab.pl.milp.simplex.SimplexException,
                                     IOException
        This method returns the matrix A obtained after the process of reduction to standard form (max z , Ax + s=b, x ≥ 0, b ≥ 0) of the original linear programming problem.
        Returns:
        The coefficient matrix A
        Throws:
        org.ssclab.pl.milp.simplex.SimplexException - If null matrix
        IOException - if the problem has not been reduced to standard form

      • getStandartVectorB

        public double[] getStandartVectorB()
        This method returns the vector b of the rhs values obtained after the process of reduction to standard form(max z , Ax+s=b, x ≥ 0, b ≥ 0) of the original linear programming problem.
        Returns:
        The vector of RHS coefficients

      • getStandartVectorC

        public double[] getStandartVectorC()
        This method returns the vector c of the coefficients of the objective function after the process of reduction to standard form (max z , Ax+s=b, x ≥ 0, b ≥ 0) of the original linear programming problem.
        Returns:
        The vector c of the coefficients of the objective function.

      • getSolution

        public Solution getSolution()
                     throws org.ssclab.pl.milp.simplex.SimplexException
        If the problem has an optimal solution, this method returns that optimal solution in the form of an object of the Solution class.
        Returns:
        The optimal solution of the problem
        Throws:
        org.ssclab.pl.milp.simplex.SimplexException - If the optimal solution is not present

      • getValuesSolution

        public double[] getValuesSolution()
                           throws org.ssclab.pl.milp.simplex.SimplexException
        If the problem has an optimal solution, this method returns that optimal solution in the form of an array with the values of the variables.
        Returns:
        The optimal solution of the problem as an array of double values
        Throws:
        org.ssclab.pl.milp.simplex.SimplexException - If the optimal solution is not present

      • isParallelSimplex

        public boolean isParallelSimplex()
        Returns:
        true if the parallelization with multiple threads of the simplex is active.

      • setParallelSimplex

        public LP setParallelSimplex​(boolean isParallelSimplex)
        If the number of physical cores of the host on which SSc is running is greater than 4 and and if the number of variables constraints and hundreds, the performance of the simplex can be improved by executing the optimization processes in parallel on multiple threads. The number of threads is set to set value is AUTO, the system decides the number of threads to use.
        Parameters:
        isParallelSimplex - True to activate parallelization
        Returns:
        the LP instance on which the method call is being made

      • getThreadsNumber

        public LPThreadsNumber getThreadsNumber()
        Returns:
        the number of threads used in the execution. If the value is AUTO, the system decides the number of threads to use.

      • setThreadsNumber

        public LP setThreadsNumber​(LPThreadsNumber threadsNumber)
        If the set value is AUTO, the system decides the number of threads to use.
        Parameters:
        threadsNumber - Sets the number of threads to use in the execution.
        Returns:
        the LP instance (this) on which the method call is being made

      • isJustTakeFeasibleSolution

        public boolean isJustTakeFeasibleSolution()
        Returns true if only phase 1 execution is set to obtain a feasible solution.
        Returns:
        true if active

      • setJustTakeFeasibleSolution

        public LP setJustTakeFeasibleSolution​(boolean isStopPhase2)
        Setting to true allows interrupting the simplex at the end of phase 1, in order to determine not an optimal solution but only a feasible solution of the problem.
        Parameters:
        isStopPhase2 - true to interrupt the simplex before phase 2.
        Returns:
        the LP instance (this) on which the method call is being made

      • setTitle

        public LP setTitle​(String title)
        Allows you to give a title to the current elaboration related to the LP problem to be solved
        Parameters:
        title - The title of the linear programming problem
        Returns:
        This instance of LP

      • getSolutionAsJson

        public JsonSolution getSolutionAsJson​(SolutionDetail... option)
                               throws org.ssclab.pl.milp.simplex.SimplexException
        Returns a JsonSolution object that represents the solution of the Linear Programming (LP) or Mixed-Integer Linear Programming (MILP) problem in JSON format. This method constructs the solution JSON, including optional sections based on the SolutionDetail values provided as arguments. The solution can represent either the optimal or feasible solution, depending on the problem's outcome. The 'SolutionDetail' enum values can specify additional information to include in the JSON output:
        • INCLUDE_BOUNDS: Includes the variable bounds (upper and lower limits) in the JSON.
        • INCLUDE_CONSTRAINT: Includes the Left-Hand Side (LHS) and Right-Hand Side (RHS) values for constraints in the JSON.
        • INCLUDE_META: Inserts metadata information like runtime, threads, iterations, etc.
        • INCLUDE_TYPEVAR: Shows the original type of each variable (e.g., integer, binary, continuous) in the JSON.
        Parameters:
        option - A variable number of SolutionDetail enum values to customize the JSON output.
        Returns:
        A JsonSolution object representing the problem's solution in JSON format.
        Throws:
        org.ssclab.pl.milp.simplex.SimplexException - If there is an error in the Simplex execution or problem-solving process.

      • resolve

        public LP resolve​(Object nullable)
           throws Exception
        Solves the linear programming (LP) problem and returns the current instance of the LP object. This method is designed to allow method chaining by returning 'this' rather than a result type.

        By passing 'null' to this method, the standard resolve method is bypassed, and this version of the method is invoked. The 'nullable' parameter exists to differentiate between the standard resolve method and this version, which enables method chaining.

        For example, this method can be used as follows:

        
 new LP(pl_string).resolve(null).getSolutionAsJson().saveToFile("solution.json");

        In the above code, the 'resolve()' method solves the LP problem, and 'saveSolutionToJson()' is chained to save the resulting solution to a JSON file.

        Parameters:
        nullable - an object that is intentionally ignored; passing 'null' to this parameter ensures that this version of the resolve method is invoked.
        Returns:
        the current instance of the LP object for method chaining.
        Throws:
        Exception - if an error occurs during the resolution process.