Package localsolver.modeler

Class LSPModule

  • All Implemented Interfaces:
    java.lang.AutoCloseable
    public class LSPModule
extends java.lang.Object
implements java.lang.AutoCloseable
    A module is a collection of global variables. As LSP is a dynamically typed language, global variables can contain any value (including functions and other modules). Each LSP file is a module. Global variables can be modified and accessed by their name specified as a string. Most of the functions below exist in multiple versions: values of the global variables can be manipulated through their native type (like int, float, String, LSPMap, LSPFunction...) or manipulated with an LSPValue which is a container that can hold any type of value. Using the native type is more convenient and results in less overhead most of the time. LSPValue should only be used when you don't know the type of the manipulated value.
    Since:
    10.0

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      LSPValue asValue()
      Returns the module as an LSPValue.
      void close()
      Releases the reference.
      boolean equals​(java.lang.Object obj)  
      boolean getBool​(java.lang.String varName)
      Returns the boolean variable with the given name.
      double getDouble​(java.lang.String varName)
      Returns the double variable with the given name.
      LSExpression getExpression​(java.lang.String varName)
      Returns the LSExpression with the given name.
      LSPFunction getFunction​(java.lang.String varName)
      Returns the LSPFunction with the given name.
      long getInt​(java.lang.String varName)
      Returns the integer variable with the given name.
      LSPMap getMap​(java.lang.String varName)
      Returns the LSPMap with the given name.
      LSPModule getModule​(java.lang.String varName)
      Returns the LSPModule with the given name.
      java.lang.String getString​(java.lang.String varName)
      Returns the string with the given name.
      LSPType getType​(java.lang.String varName)
      Returns the type of the variable with the given name.
      LSPValue getValue​(java.lang.String varName)
      Returns the LSPValue with the given name.
      int hashCode()  
      boolean isBool​(java.lang.String varName)
      Returns true if the variable with the given name exists and holds a boolean value.
      boolean isDouble​(java.lang.String varName)
      Returns true if the variable with the given name exists and holds a double value.
      boolean isExpression​(java.lang.String varName)
      Returns true if the variable with the given name exists and holds an LSExpression.
      boolean isFunction​(java.lang.String varName)
      Returns true if the variable with the given name exists and holds an LSPFunction.
      boolean isInt​(java.lang.String varName)
      Returns true if the variable with the given name exists and holds an integer value.
      boolean isMap​(java.lang.String varName)
      Returns true if the variable with the given name exists and holds an LSPMap.
      boolean isModule​(java.lang.String varName)
      Returns true if the variable with the given name exists and holds an LSPModule.
      boolean isNil​(java.lang.String varName)
      Returns true if no variable with this name exists in the module or if the variable holds a nil value.
      boolean isString​(java.lang.String varName)
      Returns true if the variable with the given name exists and holds a string value.
      void run​(LocalSolver solver, java.lang.Iterable<java.lang.String> arguments)
      Starts the execution of the module using the solver passed in parameter.
      void run​(LocalSolver solver, java.lang.String... arguments)
      Starts the execution of the module using the solver passed in parameter.
      void runMain​(java.lang.Iterable<java.lang.String> arguments)
      Runs the module in main mode.
      void runMain​(java.lang.String... arguments)
      Runs the module in main mode.
      void setBool​(java.lang.String varName, boolean value)
      Sets the boolean value associated with the variable with the given name.
      void setDouble​(java.lang.String varName, double value)
      Sets the double value associated with the variable with the given name.
      void setExpression​(java.lang.String varName, LSExpression expr)
      Sets the LSExpression associated with the variable with the given name.
      void setFunction​(java.lang.String varName, LSPFunction function)
      Sets the LSPFunction associated with the variable with the given name.
      void setInt​(java.lang.String varName, long value)
      Sets the integer value associated with the variable with the given name.
      void setMap​(java.lang.String varName, LSPMap map)
      Sets the LSPMap associated with the variable with the given name.
      void setModule​(java.lang.String varName, LSPModule module)
      Sets the LSPModule associated with the variable with the given name.
      void setNil​(java.lang.String varName)
      Unsets the variable with the given name.
      void setString​(java.lang.String varName, java.lang.String str)
      Sets the string associated with the variable with the given name.
      void setValue​(java.lang.String varName, LSPValue value)
      Sets the value associated with the variable with the given name.
      void unset​(java.lang.String varName)
      Unsets the variable with the given name.

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • close

        public void close()

        Releases the reference. If this module was already released, returns immediately and does nothing. Invoking any method on this object after this operation will throw an exception.

        Note: Releasing a reference does not necessarily imply that the underlying module object is destroyed. It is only destroyed if no more references point to it.

        Specified by:
        close in interface java.lang.AutoCloseable
        Since:
        11.5

      • run

        public void run​(LocalSolver solver,
                java.lang.Iterable<java.lang.String> arguments)

        Starts the execution of the module using the solver passed in parameter. Such execution is defined by the following steps:

        • The input function is executed if it exists in the module.
        • The model function is executed. It must be declared in the module.
        • The LSModel is then closed.
        • The param function is executed if it exists in the module.
        • The function LocalSolver.solve() is called on the corresponding solver instance. If the display function is defined, it will be called during the resolution process.
        • The output function is executed if it exists in the module.

        Note that the solver used as a parameter must have been created by the LSPModeler.createSolver() method.

        If arguments are given, each of them must be of the form argName=argValue. Each argument is then parsed and exposed as a new global variable in the module with argName as the name of the variable and argValue as its value. The format followed by the arguments is exactly the same as in the LocalSolver command line. For more information about the format of the LocalSolver command line you can read the command line section in the LSP reference guide.

        Parameters:
        solver - Instance on which modeling and optimization is performed.
        arguments - List of arguments to parse and expose as global variables.

      • run

        public void run​(LocalSolver solver,
                java.lang.String... arguments)

        Starts the execution of the module using the solver passed in parameter. Such execution is defined by the following steps:

        • The input function is executed if it exists in the module.
        • The model function is executed. It must be declared in the module.
        • The LSModel is then closed.
        • The param function is executed if it exists in the module.
        • The function LocalSolver.solve() is called on the corresponding solver instance. If the display function is defined, it will be called during the resolution process.
        • The output function is executed if it exists in the module.

        Note that the solver used as a parameter must have been created by the LSPModeler.createSolver() method.

        If arguments are given, each of them must be of the form argName=argValue. Each argument is then parsed and exposed as a new global variable in the module with argName as the name of the variable and argValue as its value. The format followed by the arguments is exactly the same as in the LocalSolver command line. For more information about the format of the LocalSolver command line you can read the command line section in the LSP reference guide.

        Parameters:
        solver - Instance on which modeling and optimization is performed.
        arguments - List of arguments to parse and expose as global variables.

      • runMain

        public void runMain​(java.lang.Iterable<java.lang.String> arguments)

        Runs the module in main mode. In this mode, the modeler behaves like a classical programming language. Therefore, the call sequence is free: you only need to implement a main method which will be the only one invoked by the modeler.

        Unlike the optimization mode, the main mode requires you to manually create the solver instances, close your models and launch the resolutions directly in your LSP files. For this you can rely on the builtin module localsolver. In return, you are free to run several successive resolutions or none at all if you just want to use LSP for its pure programming features.

        The arguments specified when calling this method are copied as is (as strings, without parsing) into a LSP map that is passed as the first argument to the main function of your LSP file. If the main function of your LSP does not accept any arguments, the parameter arguments is simply ignored.

        For more details on the differences between the optimization and the main mode, read the main mode section of the LSP reference guide.

        Parameters:
        arguments - List of arguments to copy into a map and pass to the main function.

      • runMain

        public void runMain​(java.lang.String... arguments)

        Runs the module in main mode. In this mode, the modeler behaves like a classical programming language. Therefore, the call sequence is free: you only need to implement a main method which will be the only one invoked by the modeler.

        Unlike the optimization mode, the main mode requires you to manually create the solver instances, close your models and launch the resolutions directly in your LSP files. For this you can rely on the builtin module localsolver. In return, you are free to run several successive resolutions or none at all if you just want to use LSP for its pure programming features.

        The arguments specified when calling this method are copied as is (as strings, without parsing) into a LSP map that is passed as the first argument to the main function of your LSP file. If the main function of your LSP does not accept any arguments, the parameter arguments is simply ignored.

        For more details on the differences between the optimization and the main mode, read the main mode section of the LSP reference guide.

        Parameters:
        arguments - List of arguments to copy into a map and pass to the main function.

      • getType

        public LSPType getType​(java.lang.String varName)
        Returns the type of the variable with the given name. If the variable does not exist in the module, LSPType.Nil is returned.
        Parameters:
        varName - Name of the variable.
        Returns:
        Type of the variable.
        See Also:
        LSPType

      • getValue

        public LSPValue getValue​(java.lang.String varName)
        Returns the LSPValue with the given name. If the variable does not exist, an LSPValue representing a nil value is returned.
        Parameters:
        varName - Name of the variable.
        Returns:
        LSPValue associated with the given name.
        See Also:
        LSPValue

      • getInt

        public long getInt​(java.lang.String varName)
        Returns the integer variable with the given name. The variable must exist and must hold an integer value.
        Parameters:
        varName - Name of the variable.
        Returns:
        Integer value associated with the given name.

      • getDouble

        public double getDouble​(java.lang.String varName)
        Returns the double variable with the given name. The variable must exist and must hold a double value.
        Parameters:
        varName - Name of the variable.
        Returns:
        Double value associated with the given name.

      • getBool

        public boolean getBool​(java.lang.String varName)
        Returns the boolean variable with the given name. The variable must exist and must hold a boolean value.
        Parameters:
        varName - Name of the variable.
        Returns:
        Boolean value associated with the given name.

      • getExpression

        public LSExpression getExpression​(java.lang.String varName)
        Returns the LSExpression with the given name. The variable must exist and must hold a value of type LSPType.Expression.
        Parameters:
        varName - Name of the variable.
        Returns:
        LSExpression associated with the given name.

      • getString

        public java.lang.String getString​(java.lang.String varName)
        Returns the string with the given name. The variable must exist and must hold a string value.
        Parameters:
        varName - Name of the variable.
        Returns:
        String associated with the given name.

      • getFunction

        public LSPFunction getFunction​(java.lang.String varName)
        Returns the LSPFunction with the given name. The variable must exist and must hold a function.
        Parameters:
        varName - Name of the variable.
        Returns:
        LSPFunction associated with the given name.

      • getMap

        public LSPMap getMap​(java.lang.String varName)
        Returns the LSPMap with the given name. The variable must exist and must hold a map.
        Parameters:
        varName - Name of the variable.
        Returns:
        LSPFunction associated with the given name.

      • getModule

        public LSPModule getModule​(java.lang.String varName)
        Returns the LSPModule with the given name. The variable must exist and must hold a module.
        Parameters:
        varName - Name of the variable.
        Returns:
        LSPModule associated with the given name.

      • setValue

        public void setValue​(java.lang.String varName,
                     LSPValue value)
        Sets the value associated with the variable with the given name. The variable is automatically created if it doesn't exist in the module.
        Parameters:
        varName - Name of the variable.
        value - Value of the variable.

      • setInt

        public void setInt​(java.lang.String varName,
                   long value)
        Sets the integer value associated with the variable with the given name. The variable is automatically created if it doesn't exist in the module.
        Parameters:
        varName - Name of the variable.
        value - Value of the variable.

      • setDouble

        public void setDouble​(java.lang.String varName,
                      double value)
        Sets the double value associated with the variable with the given name. The variable is automatically created if it doesn't exist in the module.
        Parameters:
        varName - Name of the variable.
        value - Value of the variable.

      • setBool

        public void setBool​(java.lang.String varName,
                    boolean value)
        Sets the boolean value associated with the variable with the given name. The variable is automatically created if it doesn't exist in the module.
        Parameters:
        varName - Name of the variable.
        value - Value of the variable.

      • setExpression

        public void setExpression​(java.lang.String varName,
                          LSExpression expr)
        Sets the LSExpression associated with the variable with the given name. The variable is automatically created if it doesn't exist in the module.
        Parameters:
        varName - Name of the variable.
        expr - Value of the variable.

      • setString

        public void setString​(java.lang.String varName,
                      java.lang.String str)
        Sets the string associated with the variable with the given name. The variable is automatically created if it doesn't exist in the module.
        Parameters:
        varName - Name of the variable.
        str - Value of the variable.

      • setFunction

        public void setFunction​(java.lang.String varName,
                        LSPFunction function)
        Sets the LSPFunction associated with the variable with the given name. The variable is automatically created if it doesn't exist in the module.
        Parameters:
        varName - Name of the variable.
        function - Value of the variable.

      • setMap

        public void setMap​(java.lang.String varName,
                   LSPMap map)
        Sets the LSPMap associated with the variable with the given name. The variable is automatically created if it doesn't exist in the module.
        Parameters:
        varName - Name of the variable.
        map - Value of the variable.

      • setModule

        public void setModule​(java.lang.String varName,
                      LSPModule module)
        Sets the LSPModule associated with the variable with the given name. The variable is automatically created if it doesn't exist in the module.
        Parameters:
        varName - Name of the variable.
        module - Value of the variable.

      • setNil

        public void setNil​(java.lang.String varName)
        Unsets the variable with the given name. Do nothing it the variable does not exist.
        Parameters:
        varName - Name of the variable.

      • unset

        public void unset​(java.lang.String varName)
        Unsets the variable with the given name. Do nothing it the variable does not exist.
        Parameters:
        varName - Name of the variable.

      • isInt

        public boolean isInt​(java.lang.String varName)
        Returns true if the variable with the given name exists and holds an integer value.
        Parameters:
        varName - Name of the variable.

      • isDouble

        public boolean isDouble​(java.lang.String varName)
        Returns true if the variable with the given name exists and holds a double value.
        Parameters:
        varName - Name of the variable.

      • isBool

        public boolean isBool​(java.lang.String varName)
        Returns true if the variable with the given name exists and holds a boolean value.
        Parameters:
        varName - Name of the variable.

      • isExpression

        public boolean isExpression​(java.lang.String varName)
        Returns true if the variable with the given name exists and holds an LSExpression.
        Parameters:
        varName - Name of the variable.

      • isString

        public boolean isString​(java.lang.String varName)
        Returns true if the variable with the given name exists and holds a string value.
        Parameters:
        varName - Name of the variable.

      • isFunction

        public boolean isFunction​(java.lang.String varName)
        Returns true if the variable with the given name exists and holds an LSPFunction.
        Parameters:
        varName - Name of the variable.

      • isMap

        public boolean isMap​(java.lang.String varName)
        Returns true if the variable with the given name exists and holds an LSPMap.
        Parameters:
        varName - Name of the variable.

      • isModule

        public boolean isModule​(java.lang.String varName)
        Returns true if the variable with the given name exists and holds an LSPModule.
        Parameters:
        varName - Name of the variable.

      • isNil

        public boolean isNil​(java.lang.String varName)
        Returns true if no variable with this name exists in the module or if the variable holds a nil value.
        Parameters:
        varName - Name of the variable.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object