# Source code for cvxpy.reductions.reduction

"""

you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
"""

import abc

[docs]class Reduction(object):
"""Abstract base class for reductions.

A reduction is an actor that transforms a problem into an
equivalent problem. By equivalent we mean that there exists
a mapping between solutions of either problem: if we reduce a problem
:math:A to another problem :math:B and then proceed to find a solution
to :math:B, we can convert it to a solution of :math:A with at most a
moderate amount of effort.

A reduction that is instantiated with a non-None problem offers
two key methods: reduce and retrieve. The reduce() method converts
the problem the reduction was instantiated with to an equivalent
problem. The retrieve() method takes as an argument a Solution
for the equivalent problem and returns a Solution for the problem
owned by the reduction.

Every reduction offers three low-level methods: accepts, apply, and invert.
The accepts method of a particular reduction specifies the types of problems
that it is applicable to; the apply method takes a problem and reduces
it to an equivalent form, and the invert method maps solutions
from reduced-to problems to their problems of provenance.

Attributes:
----------
problem : Problem
A problem owned by this reduction; possibly None.
"""

__metaclass__ = abc.ABCMeta

[docs]    def __init__(self, problem=None):
"""Construct a reduction for reducing problem.

If problem is not None, then a subsequent invocation of reduce()
will reduce problem and return an equivalent one.
"""
self.problem = problem

[docs]    def accepts(self, problem):
"""States whether the reduction accepts a problem.

Parameters
----------
problem : Problem
The problem to check.

Returns
-------
bool
True if the reduction can be applied, False otherwise.
"""
return NotImplemented

[docs]    def reduce(self):
"""Reduces the owned problem to an equivalent problem.

Returns
-------
Problem or dict
An equivalent problem, encoded either as a Problem or a dict.

Raises
------
ValueError
If this Reduction was constructed without a Problem.
"""
if hasattr(self, '_emitted_problem'):
return self._emitted_problem

if self.problem is None:
raise ValueError(
"The reduction was constructed without a Problem.")

problem, retrieval_data = self.apply(self.problem)
self._emitted_problem = problem
self._retrieval_data = retrieval_data
return problem

[docs]    def retrieve(self, solution):
"""Retrieves a solution to the owned problem.

Parameters
----------
solution : Solution
A solution to the problem emitted by reduce().

Returns
-------
Solution
A solution to the owned problem.

Raises
------
ValueError
If self.problem is None, or if reduce() was not previously
called.
"""
if not hasattr(self, '_retrieval_data'):
raise ValueError("reduce() must be called before retrieve().")
return self.invert(solution, self._retrieval_data)

[docs]    @abc.abstractmethod
def apply(self, problem):
"""Applies the reduction to a problem and returns an equivalent problem.

Parameters
----------
problem : Problem
The problem to which the reduction will be applied.

Returns
-------
Problem or dict
An equivalent problem, encoded either as a Problem or a dict.

InverseData, list or dict
Data needed by the reduction in order to invert this particular
application.
"""
return NotImplemented

[docs]    @abc.abstractmethod
def invert(self, solution, inverse_data):
"""Returns a solution to the original problem given the inverse_data.

Parameters
----------
solution : Solution
A solution to a problem that generated the inverse_data.
inverse_data
The data encoding the original problem.

Returns
-------
Solution
A solution to the original problem.
"""
return NotImplemented