Utilities
=========

.. _io-with-lp-format:

Input/Output with LP/QPLIB File
-------------------------------

A :class:`~amplify.BinaryQuadraticModel` of the Amplify SDK can be saved/loaded into/from a file in LP format or QPLIB format.

LP File Format
^^^^^^^^^^^^^^

The LP file format follows the format described in `Gurobi LP Format <https://www.gurobi.com/documentation/9.5/refman/lp_format.html>`_.
However, the following restrictions apply.

* Each variable must be a binary variable.
* The following sections and subsections must be unspecified or empty.

    * bounds section
    * variable type sections except for binary subsection

* The following formats and sections are not supported.

    * multi-objective
    * indicator constraint
    * lazy constraints section
    * SOS section
    * PWLObj section
    * general constraint section
    * scenario section

QPLIB File Format
^^^^^^^^^^^^^^^^^

The QPLIB file format follows the format described in `QPLIB <https://qplib.zib.de/index.html>`_.
However, all of the variables must be binary variables, that is, the second character of the problem type must be ``B``.

Output to Files
^^^^^^^^^^^^^^^

The :func:`~amplify.save_lp` and the :func:`~amplify.save_qplib` output a logical model to an LP file and a QPLIB file, respectively.
These functions take a :class:`~amplify.BinaryQuadraticModel` as the first argument and a file path (string) as the second argument.

.. code-block:: python

    from amplify import BinarySymbolGenerator, BinaryQuadraticModel, save_lp
    from amplify.constraint import one_hot

    gen = BinarySymbolGenerator()
    q = gen.array(4)  # generate variable array of length 4
    f = 2 * q[0] * q[1] * q[2] + q[0] * q[1] + q[0] + q[1] + q[2] - 1
    c1 = one_hot(q[:3])   # q_0 + q_1 + q_2 == 1
    c2 = one_hot(q[1:])   # q_1 + q_2 + q_3 == 1
    model = BinaryQuadraticModel(f, c1 + c2)
    save_lp(model, "model.lp")

In this case, the following will be output to the file ``model.lp``. ::

    Minimize
    x_0 + x_1 + x_2 + 2 x_3 + [ 6 x_0 * x_1 + 4 x_0 * x_2 - 4 x_0 * x_3 + 4 x_1 *
    x_2 - 4 x_1 * x_3 - 4 x_2 * x_3 ] / 2 - 1
    Subject To
    x_0 + x_1 + x_2 = 1
    x_1 + x_2 + x_4 = 1
    Binaries
    x_0 x_1 x_2 x_3 x_4
    End

Since the polynomials written in the LP file or QPLIB file must be at most quadratic, the :func:`~amplify.save_lp` and :func:`~amplify.save_qplib` saves the logical expressions of the logical model after the quadratization is made. Therefore, the input variables may be reindexed, and the mapping information can be obtained by :attr:`~amplify.BinaryQuadraticModel.logical_mapping`.
If the constraint condition is naturally expressed in a quadratic or lower expression, that expression is written out, otherwise, the expression "penalty function reduced to the second degree :math:`= 0`" is written out.

Input from Files
^^^^^^^^^^^^^^^^

The :func:`~amplify.load_lp` and the :func:`~amplify.load_qplib` converts an LP file and QPLIB file to a logical model, respectively.
This function takes a file path (string) as the first argument and returns a tuple of a logical model and a dictionary with variable names as keys and variable indices as values.

For example, the ``model.lp`` created above in the example of :func:`~amplify.save_lp` can be read as follows:

.. code-block:: python

    from amplify import load_lp

    model, variables = load_lp("model.lp")

>>> model.input_poly
3 q_0 q_1 + 2 q_0 q_2 - 2 q_0 q_3 + 2 q_1 q_2 - 2 q_1 q_3 - 2 q_2 q_3 + q_0 + q_1 + q_2 + 2 q_3 - 1
>>> variables
{'x_4': 4, 'x_3': 3, 'x_2': 2, 'x_1': 1, 'x_0': 0}

When writing out constraints, the :func:`~amplify.load_lp` and the :func:`~amplify.load_qplib` calls the :func:`~amplify.constraint.equal_to` or :func:`~amplify.constraint.less_equal` etc. Please note that :func:`~amplify.constraint.penalty` is not called in any cases. A method to formulate inequalities and a method to perform quadratization can be specified by giving an instance of :class:`~amplify.InequalityFormulation` and an instance of :class:`~amplify.QuadratizationMethod` to the keyword arguments ``inequality_formulation_method`` and ``quadratization_method``, respectively. For detailed usage of these methods, please refer to :ref:`Inequality Formulation Methods <constraint-inequality-method>` and :ref:`Specify a Reduction Method <quadratization_method>`.

.. note::

    Please note that saving a :class:`~amplify.BinaryQuadraticModel` into an LP file or QPLIB file and loading the same file may not completely reproduce the original logical model. This is because the information on the functions used to construct the constraints and the constraint weights cannot be saved in the LP file or QPLIB file.

.. note::

    The problem type of a QPLIB file generated by the :func:`~amplify.save_qplib` function will not have ``C`` or ``D`` as its first or third character, because the :class:`~amplify.BinaryQuadraticModel` cannot have information on the convexity of the objective function and constraint conditions. Similarly, the initial values of the variables, dual variables, Lagrange multipliers, as well as variable names, will not be saved.