Source code for picos.expressions.expression

# ------------------------------------------------------------------------------
# Copyright (C) 2019 Maximilian Stahlberg
# Based on the original picos.expressions module by Guillaume Sagnol.
#
# This file is part of PICOS.
#
# PICOS is free software: you can redistribute it and/or modify it under the
# terms of the GNU General Public License as published by the Free Software
# Foundation, either version 3 of the License, or (at your option) any later
# version.
#
# PICOS is distributed in the hope that it will be useful, but WITHOUT ANY
# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
# A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along with
# this program.  If not, see <http://www.gnu.org/licenses/>.
# ------------------------------------------------------------------------------

"""Backend for expression type implementations."""

import functools
import operator
import threading
import warnings
from abc import abstractmethod
from contextlib import contextmanager

from .. import glyphs
from ..apidoc import api_end, api_start
from ..caching import cached_property
from ..constraints import ConstraintType
from ..containers import DetailedType
from ..legacy import deprecated
from ..valuable import NotValued, Valuable
from .data import convert_operands

_API_START = api_start(globals())
# -------------------------------


[docs]def validate_prediction(the_operator): """Validate that the constraint outcome matches the predicted outcome.""" @functools.wraps(the_operator) def wrapper(lhs, rhs, *args, **kwargs): from .set import Set def what(): return "({}).{}({})".format( lhs._symbStr, the_operator.__name__, rhs._symbStr) assert isinstance(lhs, (Expression, Set)) \ and isinstance(rhs, (Expression, Set)), \ "validate_prediction must occur below convert_operands." lhs_type = lhs.type rhs_type = rhs.type try: abstract_operator = getattr(operator, the_operator.__name__) except AttributeError as error: raise AssertionError("validate_prediction may only decorate " "standard operator implementations.") from error try: predictedType = lhs_type.predict(abstract_operator, rhs_type) except NotImplementedError: predictedType = None # No prediction was made. except PredictedFailure: predictedType = NotImplemented # Prediction is "not possible". try: outcome = the_operator(lhs, rhs, *args, **kwargs) except Exception as error: # Case where the prediction is positive and the outcome is negative. if predictedType not in (None, NotImplemented): warnings.warn( "Outcome for {} was predicted {} but the operation raised " "an error: \"{}\" This a noncritical error (false positive)" " in PICOS' constraint outcome prediction." .format(what(), predictedType, error), category=RuntimeWarning, stacklevel=3) raise else: raise # Case where the prediction is negative and the outcome is positive. if predictedType is NotImplemented and outcome is not NotImplemented: raise AssertionError( "The operation {} was predicted to fail but it produced " "an output of {}.".format(what(), outcome.type)) # Case where no prediction was made. if not predictedType: return outcome # Case where the outcome is try-to-reverse-the-operation. if outcome is NotImplemented: return outcome # Case where the prediction and the outcome are positive but differ. outcomeType = outcome.type if not predictedType.equals(outcomeType): raise AssertionError("Outcome for {} was predicted {} but is {}." .format(what(), predictedType, outcomeType)) return outcome return wrapper
[docs]def refine_operands(stop_at_affine=False): """Cast :meth:`~Expression.refined` on both operands. If the left hand side operand (i.e. ``self``) is refined to an instance of a different type, then, instead of the decorated method, the method with the same name on the refined type is invoked with the (refined) right hand side operand as its argument. This decorator is supposed to be used on all constraint creating binary operator methods so that degenerated instances (e.g. a complex affine expression with an imaginary part of zero) can occur but are not used in constraints. This speeds up many computations involving expressions as these degenerate cases do not need to be detected. Note that :attr:`Expression.type` also refers to the refined version of an expression. :param bool stop_at_affine: Do not refine any affine expressions, in particular do not refine complex affine expressions to real ones. """ def decorator(the_operator): @functools.wraps(the_operator) def wrapper(lhs, rhs, *args, **kwargs): from .exp_affine import ComplexAffineExpression from .set import Set assert isinstance(lhs, (Expression, Set)) \ and isinstance(rhs, (Expression, Set)), \ "refine_operands must occur below convert_operands." if stop_at_affine and isinstance(lhs, ComplexAffineExpression): lhs_refined = lhs else: lhs_refined = lhs.refined if type(lhs_refined) is not type(lhs): assert hasattr(lhs_refined, the_operator.__name__), \ "refine_operand transformed 'self' to another type that " \ "does not define an operator with the same name as the " \ "decorated one." refined_operation = getattr(lhs_refined, the_operator.__name__) return refined_operation(rhs, *args, **kwargs) if stop_at_affine and isinstance(rhs, ComplexAffineExpression): rhs_refined = rhs else: rhs_refined = rhs.refined return the_operator(lhs_refined, rhs_refined, *args, **kwargs) return wrapper return decorator
# TODO: Once PICOS requires Python >= 3.7, use a ContextVar instead. class _Refinement(threading.local): allowed = True _REFINEMENT = _Refinement()
[docs]@contextmanager def no_refinement(): """Context manager that disables the effect of :meth:`Expression.refined`. This can be necessary to ensure that the outcome of a constraint coversion is as predicted, in particular when PICOS uses overridden comparison operators for constraint creation internally. """ _REFINEMENT.allowed = False try: yield finally: _REFINEMENT.allowed = True
[docs]class PredictedFailure(TypeError): """Denotes that comparing two expressions will not form a constraint.""" pass
[docs]class ExpressionType(DetailedType): """The detailed type of an expression for predicting constraint outcomes. This is suffcient to predict the detailed type of any constraint that can be created by comparing with another expression. """ @staticmethod def _relation_str(relation): if relation is operator.__eq__: return "==" elif relation is operator.__le__: return "<=" elif relation is operator.__ge__: return ">=" elif relation is operator.__lshift__: return "<<" elif relation is operator.__rshift__: return ">>" else: return "??" @staticmethod def _swap_relation(relation): if relation is operator.__eq__: return operator.__eq__ elif relation is operator.__le__: return operator.__ge__ elif relation is operator.__ge__: return operator.__le__ elif relation is operator.__lshift__: return operator.__rshift__ elif relation is operator.__rshift__: return operator.__lshift__ else: return None
[docs] def predict(self, relation, other): """Predict the constraint outcome of comparing expressions. :param relation: An object from the :mod:`operator` namespace representing the operation being predicted. :param other: Another expression type representing the right hand side operand. :type other: ~picos.expressions.expression.ExpressionType :Example: >>> import operator, picos >>> a = picos.RealVariable("x") + 1 >>> b = picos.RealVariable("y") + 2 >>> (a <= b).type == a.type.predict(operator.__le__, b.type) True """ if not isinstance(other, ExpressionType): raise TypeError("The 'other' argument must be another {} instance." .format(self.__class__.__name__)) # Perform the forward prediction. result = self.clstype._predict(self.subtype, relation, other) # Fall back to the backward prediction. if result is NotImplemented: reverse = self._swap_relation(relation) result = other.clstype._predict(other.subtype, reverse, self) # If both fail, the prediction is "not possible". if result is NotImplemented: raise PredictedFailure( "The statement {} {} {} is predicted to error." .format(self, self._relation_str(relation), other)) else: assert isinstance(result, ConstraintType) return result
[docs]class Expression(Valuable): """Abstract base class for mathematical expressions, including mutables. For mutables, this is the secondary base class, with :class:`~.mutable.Mutable` or a subclass thereof being the primary one. """
[docs] def __init__(self, typeStr, symbStr): """Perform basic initialization for :class:`Expression` instances. :param str typeStr: Short string denoting the expression type. :param str symbStr: Algebraic string description of the expression. """ self._typeStr = typeStr """A string describing the expression type.""" self._symbStr = symbStr """A symbolic string representation of the expression. It is always used by __descr__, and it is equivalent to the value returned by __str__ when the expression is not fully valued."""
@property def string(self): """Symbolic string representation of the expression. Use this over Python's :class:`str` if you want to output the symbolic representation even when the expression is valued. """ return self._symbStr # -------------------------------------------------------------------------- # Abstract method implementations for the Valuable base class. # NOTE: _get_value and possibly _set_value are implemented by subclasses. # -------------------------------------------------------------------------- def _get_valuable_string(self): return "expression {}".format(self.string) # -------------------------------------------------------------------------- # Abstract and default-implementation methods. # -------------------------------------------------------------------------- def _get_refined(self): """See :attr:`refined`.""" return self def _get_clstype(self): """Return the Python class part of the expression's detailed type.""" return self.__class__ @property @abstractmethod def Subtype(self): """The class of which :attr:`subtype` returns an instance. Instances must be hashable. By convention a :func:`namedtuple <collections.namedtuple>` class. .. warning:: This should be declared in the class body as e.g. `Subtype = namedtuple(…)` and not as a property so that it's static. """ pass @abstractmethod def _get_subtype(self): """See :attr:`subtype`.""" pass @classmethod @abstractmethod def _predict(cls, subtype, relation, other): """Predict the constraint outcome of a comparison. :param object subtype: An object returned by the :meth:`_get_subtype` instance method of :class:`cls`. :param method-wrapper relation: A function from the :mod:`operator` namespace, such as :func:`operator.__le__`. See :class:`ExpressionType` for what operators are defined. :param ExpressionType other: The detailed type of another expression. :returns: Either the :obj:`NotImplemented` token or a :class:`ConstraintType` object such that an instance of :class:`cls` with the given subtype, when compared with another expression with the given expression type, returns a constraint with that constraint type. """ pass def _get_shape(self): """Return the algebraic shape of the expression.""" return (1, 1) @abstractmethod def _get_mutables(self): """Return the set of mutables that are involved in the expression.""" pass @abstractmethod def _is_convex(self): """Whether the expression is convex in its :attr:`variables`. Method implementations may assume that the expression is refined. Thus, degenerate cases affected by refinement do not need to be considered. For uncertain expressions, this assumes the perturbation as constant. """ pass @abstractmethod def _is_concave(self): """Whether the expression is concave in its :attr:`variables`. Method implementations may assume that the expression is refined. Thus, degenerate cases affected by refinement do not need to be considered. For uncertain expressions, this assumes the perturbation as constant. """ pass @abstractmethod def _replace_mutables(self, mapping): """Return a copy of the expression concerning different mutables. This is the fast internal-use counterpart to :meth:`replace_mutables`. The returned expression should be of the same type as ``self`` (no refinement) so that it can be substituted in composite expressions. :param dict mapping: A mutable replacement map. The caller must ensure the following properties: 1. This must be a complete map from existing mutables to the same mutable, another mutable, or a real-valued affine expression (completeness). 2. The shape and vectorization format of each replacement must match the existing mutable. Replacing with affine expressions is only allowed when the existing mutable uses the trivial :class:`~vectorizations.FullVectorization` (soudness). 3. Mutables that appear in a replacement may be the same as the mutable being replaced but may otherwise not appear in the expression (freshness). 4. Mutables may appear at most once anywhere in the image of the map (uniqueness). If any property is not fulfilled, the implementation does not need to raise a proper exception but may fail arbitrarily. """ pass @abstractmethod def _freeze_mutables(self, subset): """Return a copy with some mutables frozen to their current value. This is the fast internal-use counterpart to :meth:`frozen`. The returned expression should be of the same type as ``self`` (no refinement) so that it can be substituted in composite expressions. :param dict subset: An iterable of valued :class:`mutables <.mutable.Mutable>` that should be frozen. May include mutables that are not present in the expression, but may not include mutables without a value. """ pass # -------------------------------------------------------------------------- # An interface to the abstract and default-implementation methods above. # -------------------------------------------------------------------------- @property def refined(self): """A refined version of the expression. The refined expression can be an instance of a different :class:`Expression` subclass than the original expression, if that type is better suited for the mathematical object in question. The refined expression is automatically used instead of the original one whenever a constraint is created, and in some other places. The idea behind refined expressions is that operations that produce new expressions can be executed quickly without checking for exceptionnel cases. For instance, the sum of two :class:`~.exp_affine.ComplexAffineExpression` instances could have the complex part eliminated so that storing the result as an :class:`~.exp_affine.AffineExpression` would be prefered, but checking for this case on every addition would be too slow. Refinement is used sparingly to detect such cases at times where it makes the most sense. Refinement may be disallowed within a context with the :func:`no_refinement` context manager. In this case, this property returns the expression as is. """ if not _REFINEMENT.allowed: return self fine = self._get_refined() if fine is not self: # Recursively refine until the expression doesn't change further. return fine.refined else: return fine @property def subtype(self): """The subtype part of the expression's detailed type. Returns a hashable object that, together with the Python class part of the expression's type, is sufficient to predict the constraint outcome (constraint class and subtype) of any comparison operation with any other expression. By convention the object returned is a :func:`namedtuple <collections.namedtuple>` instance. """ return self._get_subtype() @property def type(self): """The expression's detailed type for constraint prediction. The returned value is suffcient to predict the detailed type of any constraint that can be created by comparing with another expression. Since constraints are created from :attr:`~.expression.Expression.refined` expressions only, the Python class part of the detailed type may differ from the type of the expression whose :attr:`type` is queried. """ refined = self.refined return ExpressionType(refined._get_clstype(), refined._get_subtype())
[docs] @classmethod def make_type(cls, *args, **kwargs): """Create a detailed expression type from subtype parameters.""" return ExpressionType(cls, cls.Subtype(*args, **kwargs))
shape = property( lambda self: self._get_shape(), doc=_get_shape.__doc__) size = property( lambda self: self._get_shape(), doc="""The same as :attr:`shape`.""") @property def scalar(self): """Whether the expression is scalar.""" return self._get_shape() == (1, 1) @property def square(self): """Whether the expression is a square matrix.""" shape = self._get_shape() return shape[0] == shape[1] mutables = property( lambda self: self._get_mutables(), doc=_get_mutables.__doc__) @property def constant(self): """Whether the expression involves no mutables.""" return not self._get_mutables()
[docs] @cached_property def variables(self): """The set of decision variables that are involved in the expression.""" from .variables import BaseVariable return frozenset(mutable for mutable in self._get_mutables() if isinstance(mutable, BaseVariable))
[docs] @cached_property def parameters(self): """The set of parameters that are involved in the expression.""" from .variables import BaseVariable return frozenset(mutable for mutable in self._get_mutables() if not isinstance(mutable, BaseVariable))
@property def convex(self): """Whether the expression is convex.""" return self.refined._is_convex() @property def concave(self): """Whether the expression is concave.""" return self.refined._is_concave()
[docs] def replace_mutables(self, replacement): """Return a copy of the expression concerning different mutables. New mutables must have the same shape and vectorization format as the mutables that they replace. This means in particular that :class:`~.variables.RealVariable`, :class:`~.variables.IntegerVariable` and :class:`~.variables.BinaryVariable` of same shape are interchangeable. If the mutables to be replaced do not appear in the expression, then the expression is not copied but returned as is. :param replacement: Either a map from mutables or mutable names to new mutables or an iterable of new mutables to replace existing mutables of same name with. See the section on advanced usage for additional options. :type replacement: tuple or list or dict :returns Expression: The new expression, refined to a more suitable type if possible. :Advanced replacement: It is also possible to replace mutables with real affine expressions concerning pairwise disjoint sets of fresh mutables. This works only on real-valued mutables that have a trivial internal vectorization format (i.e. :class:`~.vectorizations.FullVectorization`). The shape of the replacing expression must match the variable's. Additional limitations depending on the type of expression that the replacement is invoked on are possible. The ``replacement`` argument must be a dictionary. :Example: >>> import picos >>> x = picos.RealVariable("x"); x.value = 1 >>> y = picos.RealVariable("y"); y.value = 10 >>> z = picos.RealVariable("z"); z.value = 100 >>> c = picos.Constant("c", 1000) >>> a = x + 2*y; a <1×1 Real Linear Expression: x + 2·y> >>> a.value 21.0 >>> b = a.replace_mutables({y: z}); b # Replace y with z. <1×1 Real Linear Expression: x + 2·z> >>> b.value 201.0 >>> d = a.replace_mutables({x: 2*x + z, y: c}); d # Advanced use. <1×1 Real Affine Expression: 2·x + z + 2·c> >>> d.value 2102.0 """ from .exp_biaffine import BiaffineExpression from .mutable import Mutable from .vectorizations import FullVectorization # Change an iterable of mutables to a map from names to mutables. if not isinstance(replacement, dict): if not all(isinstance(new, Mutable) for new in replacement): raise TypeError("If 'replacement' is a non-dictionary iterable," " then it may only contain mutables.") new_replacement = {new.name: new for new in replacement} if len(new_replacement) != len(replacement): raise TypeError("If 'replacement' is a non-dictionary iterable," " then the mutables within must have unique names.") replacement = new_replacement # Change a map from names to a map from existing mutables. # Names that reference non-existing mutables are dropped. old_mtbs_by_name = {mtb.name: mtb for mtb in self.mutables} replacing_by_name = False new_replacement = {} for old, new in replacement.items(): if isinstance(old, Mutable): new_replacement[old] = new elif not isinstance(old, str): raise TypeError( "Keys of 'replacement' must be mutables or names thereof.") else: replacing_by_name = True if old in old_mtbs_by_name: new_replacement[old_mtbs_by_name[old]] = new replacement = new_replacement # Check unique naming of existing mutables if it matters. if replacing_by_name and len(old_mtbs_by_name) != len(self.mutables): raise RuntimeError("Cannot replace mutables by name in {} as " "its mutables are not uniquely named.".format(self.string)) # Remove non-existing sources and identities. assert all(isinstance(old, Mutable) for old in replacement) replacement = {old: new for old, new in replacement.items() if old is not new and old in self.mutables} # Do nothing if there is nothing to replace. if not replacement: return self # Validate individual replacement requirements. for old, new in replacement.items(): # Replacement must be a mutable or biaffine expression. if not isinstance(new, BiaffineExpression): raise TypeError("Can only replace mutables with other mutables " "or affine expressions thereof.") # Shapes must match. if old.shape != new.shape: raise TypeError( "Cannot replace {} with {} in {}: Differing shape." .format(old.name, new.name, self.string)) # Special requirements when replacing with mutables or expressions. if isinstance(new, Mutable): # Vectorization formats must match. if type(old._vec) != type(new._vec): # noqa: E721 raise TypeError("Cannot replace {} with {} in {}: " "Differing vectorization." .format(old.name, new.name, self.string)) else: # Replaced mutable must use a trivial vectorization. if not isinstance(old._vec, FullVectorization): raise TypeError("Can only replace mutables using a trivial " "vectorization format with affine expressions.") # Replacing expression must be real-valued and affine. if new._bilinear_coefs or new.complex: raise TypeError("Can only replace mutables with real-valued" " affine expressions.") old_mtbs_set = set(replacement) new_mtbs_lst = [mtb # Excludes each mutable being replaced. for old, new in replacement.items() for mtb in new.mutables.difference((old,))] new_mtbs_set = set(new_mtbs_lst) # New mutables must be fresh. # It is OK to replace a mutable with itself or an affine expression of # itself and other fresh mutables, though. if old_mtbs_set.intersection(new_mtbs_set): raise ValueError("Can only replace mutables with fresh mutables " "or affine expressions of all fresh mutables (the old mutable " "may appear in the expression).") # New mutables must be unique. if len(new_mtbs_lst) != len(new_mtbs_set): raise ValueError("Can only replace multiple mutables at once if " "the replacing mutables (and/or the mutables in replacing " "expressions) are all unique.") # Turn the replacement map into a complete map. mapping = {mtb: mtb for mtb in self.mutables} mapping.update(replacement) # Replace recursively and refine the result. return self._replace_mutables(mapping).refined
[docs] def frozen(self, subset=None): """The expression with valued mutables frozen to their current value. If all mutables of the expression are valued (and in the subset unless ``subset=None``), this is the same as the inversion operation ``~``. If the mutables to be frozen do not appear in the expression, then the expression is not copied but returned as is. :param subset: An iterable of valued :class:`mutables <.mutable.Mutable>` or names thereof that should be frozen. If :obj:`None`, then all valued mutables are frozen to their current value. May include mutables that are not present in the expression, but may not include mutables without a value. :returns Expression: The frozen expression, refined to a more suitable type if possible. :Example: >>> from picos import RealVariable >>> x, y = RealVariable("x"), RealVariable("y") >>> f = x + y; f <1×1 Real Linear Expression: x + y> >>> sorted(f.mutables, key=lambda mtb: mtb.name) [<1×1 Real Variable: x>, <1×1 Real Variable: y>] >>> x.value = 5 >>> g = f.frozen(); g # g is f with x frozen at its current value of 5. <1×1 Real Affine Expression: [x] + y> >>> sorted(g.mutables, key=lambda mtb: mtb.name) [<1×1 Real Variable: y>] >>> x.value, y.value = 10, 10 >>> f.value # x takes its new value in f. 20.0 >>> g.value # x remains frozen at [x] = 5 in g. 15.0 >>> # If an expression is frozen to a constant, this is reversable: >>> f.frozen().equals(~f) and ~f.frozen() is f True """ from .mutable import Mutable # Collect mutables to be frozen in the expression. if subset is None: freeze = set(mtb for mtb in self.mutables if mtb.valued) else: if not all(isinstance(mtb, (str, Mutable)) for mtb in subset): raise TypeError("Some element of the subset of mutables to " "freeze is neither a mutable nor a string.") subset_mtbs = set(m for m in subset if isinstance(m, Mutable)) subset_name = set(n for n in subset if isinstance(n, str)) freeze = set() if subset_mtbs: freeze.update(m for m in subset_mtbs if m in self.mutables) if subset_name: freeze.update(m for m in self.mutables if m.name in subset_name) if not all(mtb.valued for mtb in freeze): raise NotValued( "Not all mutables in the selected subset are valued.") if not freeze: return self if freeze == self.mutables: return ~self # Allow ~self.frozen() to return self. return self._freeze_mutables(freeze).refined
@property def certain(self): """Always :obj:`True` for certain expression types. This can be :obj:`False` for Expression types that inherit from :class:`~.uexpression.UncertainExpression` (with priority). """ return True @property def uncertain(self): """Always :obj:`False` for certain expression types. This can be :obj:`True` for Expression types that inherit from :class:`~.uexpression.UncertainExpression` (with priority). """ return False # -------------------------------------------------------------------------- # Python special method implementations. # -------------------------------------------------------------------------- def __len__(self): """Report the number of entries of the (multidimensional) expression.""" return self.shape[0] * self.shape[1]
[docs] def __le__(self, other): """Return a constraint that the expression is upper-bounded.""" # Try to refine self and see if the operation is then supported. # This allows e.g. a <= 0 if a is a real-valued complex expression. refined = self.refined if type(refined) != type(self): return refined.__le__(other) return NotImplemented
[docs] def __ge__(self, other): """Return a constraint that the expression is lower-bounded.""" # Try to refine self and see if the operation is then supported. # This allows e.g. a >= 0 if a is a real-valued complex expression. refined = self.refined if type(refined) != type(self): return refined.__ge__(other) return NotImplemented
def __invert__(self): """Convert between a valued expression and its value. The value is returned as a constant affine expression whose conversion returns the original expression. """ if hasattr(self, "_origin"): return self._origin elif self.constant: return self from .exp_affine import Constant A = Constant( glyphs.frozen(self.string), self.safe_value_as_matrix, self.shape) A._origin = self return A def __contains__(self, mutable): """Report whether the expression concerns the given mutable.""" return mutable in self.mutables
[docs] def __eq__(self, exp): """Return an equality constraint concerning the expression.""" raise NotImplementedError("PICOS supports equality comparison only " "between affine expressions, as otherwise the problem would " "become non-convex. Choose either <= or >= if possible.")
def __repr__(self): """Return a bracketed string description of the expression. The description contains both the mathematical type and a symbolic description of the expression. """ return str(glyphs.repr2(self._typeStr, self._symbStr)) def __str__(self): """Return a dynamic string description of the expression. The description is based on whether the expression is valued. If it is valued, then a string representation of the value is returned. Otherwise, the symbolic description of the expression is returned. """ value = self.value if value is None: return str(self._symbStr) else: return str(value).strip() def __format__(self, format_spec): """Format either the value or the symbolic string of the expression. If the expression is valued, then its value is formatted, otherwise its symbolic string description. """ value = self.value if value is None: return self._symbStr.__format__(format_spec) else: return value.__format__(format_spec) # Since we define __eq__, __hash__ is not inherited. Do this manually. __hash__ = object.__hash__ # -------------------------------------------------------------------------- # Fallback algebraic operations: Try again with converted RHS, refined LHS. # NOTE: The forward operations call the backward operations manually # (instead of returning NotImplemented) so that they can be performed # on a converted operand, which is always a PICOS type. The backward # operations then use WeightedSum as a last fallback where applicable. # -------------------------------------------------------------------------- def _wsum_fallback(self, summands, weights, opstring): """Try to represent the result as a weighted sum.""" from .exp_wsum import WeightedSum # NOTE: WeightedSum with an opstring set will act as a final fallback # and raise a proper exception if the result can't be represented. # This is handled there and not here so that also operations on # existing WeightedSum instances can produce such exceptions, as # they cannot fallback to Expression like other operations do. return WeightedSum(summands, weights, opstring) def _scalar_mult_fallback(self, lhs, rhs): """Try to express scalar by scalar multiplication as a weighted sum.""" assert isinstance(lhs, Expression) and isinstance(rhs, Expression) opstring = "a product between {} and {}".format(repr(lhs), repr(rhs)) if lhs.scalar and lhs.constant: return self._wsum_fallback((rhs,), lhs.safe_value, opstring) elif rhs.scalar and rhs.constant: return self._wsum_fallback((lhs,), rhs.safe_value, opstring) else: # NOTE: Constant scalars are also AffineExpression but otherwise # raising the default Python TypeError (stating that the two # types are fully operation-incompatible) makes sense here. return NotImplemented
[docs] @convert_operands(sameShape=True) def __add__(self, other): """Denote addition with another expression on the right-hand side.""" if type(self.refined) != type(self): return self.refined.__add__(other) else: return other.__radd__(self)
[docs] @convert_operands(sameShape=True) def __radd__(self, other): """Denote addition with another expression on the left-hand side.""" if type(self.refined) != type(self): return self.refined.__radd__(other) else: opstring = "{} plus {}".format(repr(other), repr(self)) return self._wsum_fallback((other, self), (1, 1), opstring)
[docs] @convert_operands(sameShape=True) def __sub__(self, other): """Denote subtraction of another expression from the expression.""" if type(self.refined) != type(self): return self.refined.__sub__(other) else: return other.__rsub__(self)
[docs] @convert_operands(sameShape=True) def __rsub__(self, other): """Denote subtraction of the expression from another expression.""" if type(self.refined) != type(self): return self.refined.__rsub__(other) else: opstring = "{} minus {}".format(repr(other), repr(self)) return self._wsum_fallback((other, self), (1, -1), opstring)
[docs] @convert_operands(sameShape=True) def __or__(self, other): r"""Denote the scalar product with another expression on the right. For (complex) vectors :math:`a` and :math:`b` this is the dot product .. math:: (a \mid b) &= \langle a, b \rangle \\ &= a \cdot b \\ &= b^H a. For (complex) matrices :math:`A` and :math:`B` this is the Frobenius inner product .. math:: (A \mid B) &= \langle A, B \rangle_F \\ &= A : B \\ &= \operatorname{tr}(B^H A) \\ &= \operatorname{vec}(B)^H \operatorname{vec}(\overline{A}) .. note:: Write ``(A|B)`` instead of ``A|B`` for the scalar product of ``A`` and ``B`` to obtain correct operator binding within a larger expression context. """ if type(self.refined) != type(self): return self.refined.__or__(other) else: return other.__ror__(self)
[docs] @convert_operands(sameShape=True) def __ror__(self, other): """Denote the scalar product with another expression on the left. See :meth:`__or__` for details on this operation. """ if type(self.refined) != type(self): return self.refined.__ror__(other) else: return self._scalar_mult_fallback(other, self)
[docs] @convert_operands(rMatMul=True) def __mul__(self, other): """Denote multiplication with another expression on the right.""" if type(self.refined) != type(self): return self.refined.__mul__(other) else: return other.__rmul__(self)
[docs] @convert_operands(lMatMul=True) def __rmul__(self, other): """Denote multiplication with another expression on the left.""" if type(self.refined) != type(self): return self.refined.__rmul__(other) else: return self._scalar_mult_fallback(other, self)
[docs] @convert_operands(sameShape=True) def __xor__(self, other): """Denote the entrywise product with another expression on the right.""" if type(self.refined) != type(self): return self.refined.__xor__(other) else: return other.__rxor__(self)
[docs] @convert_operands(sameShape=True) def __rxor__(self, other): """Denote the entrywise product with another expression on the left.""" if type(self.refined) != type(self): return self.refined.__rxor__(other) else: return self._scalar_mult_fallback(other, self)
[docs] @convert_operands() def __matmul__(self, other): """Denote the Kronecker product with another expression on the right.""" if type(self.refined) != type(self): return self.refined.__matmul__(other) else: return other.__rmatmul__(self)
[docs] @convert_operands() def __rmatmul__(self, other): """Denote the Kronecker product with another expression on the left.""" if type(self.refined) != type(self): return self.refined.__rmatmul__(other) else: return self._scalar_mult_fallback(other, self)
[docs] @convert_operands(scalarRHS=True) def __truediv__(self, other): """Denote division by another, scalar expression.""" if type(self.refined) != type(self): return self.refined.__truediv__(other) else: return other.__rtruediv__(self)
[docs] @convert_operands(scalarLHS=True) def __rtruediv__(self, other): """Denote scalar division of another expression.""" if type(self.refined) != type(self): return self.refined.__rtruediv__(other) else: if self.constant and not self.is0: try: return other.__mul__(1 / self.safe_value) except TypeError: assert False, "Multiplication of {} by a nonzero constant" \ " has unexpectedly failed; it should have produced a " \ "weighted sum.".format(repr(other)) else: reason = "nonconstant" if not self.constant else "zero" raise TypeError("Cannot divide {} by {}: The denominator is {}." .format(repr(other), repr(self), reason))
[docs] @convert_operands(scalarRHS=True) def __pow__(self, other): """Denote exponentiation with another, scalar expression.""" if type(self.refined) != type(self): return self.refined.__pow__(other) else: return other.__rpow__(self)
[docs] @convert_operands(scalarLHS=True) def __rpow__(self, other): """Denote taking another expression to the power of the expression.""" if type(self.refined) != type(self): return self.refined.__rpow__(other) else: return NotImplemented
[docs] @convert_operands(horiCat=True) def __and__(self, other): """Denote horizontal stacking with another expression on the right.""" if type(self.refined) != type(self): return self.refined.__and__(other) else: return other.__rand__(self)
[docs] @convert_operands(horiCat=True) def __rand__(self, other): """Denote horizontal stacking with another expression on the left.""" if type(self.refined) != type(self): return self.refined.__rand__(other) else: return NotImplemented
[docs] @convert_operands(vertCat=True) def __floordiv__(self, other): """Denote vertical stacking with another expression below.""" if type(self.refined) != type(self): return self.refined.__floordiv__(other) else: return other.__rfloordiv__(self)
[docs] @convert_operands(vertCat=True) def __rfloordiv__(self, other): """Denote vertical stacking with another expression above.""" if type(self.refined) != type(self): return self.refined.__rfloordiv__(other) else: return NotImplemented
[docs] def __pos__(self): """Return the expression as-is.""" return self
[docs] def __neg__(self): """Denote the negation of the expression.""" if type(self.refined) != type(self): return self.refined.__neg__() else: opstring = "the negation of {}".format(repr(self)) return self._wsum_fallback((self,), -1, opstring)
[docs] def __abs__(self): """Denote the default norm of the expression. The norm used depends on the expression's domain. It is 1. the absolute value of a real scalar, 2. the modulus of a complex scalar, 3. the Euclidean norm of a vector, and 4. the Frobenius norm of a matrix. """ if type(self.refined) != type(self): return self.refined.__abs__() else: return NotImplemented
# -------------------------------------------------------------------------- # Turn __lshift__ and __rshift__ into a single binary relation. # This is used for both Loewner order (defining LMIs) and set membership. # -------------------------------------------------------------------------- def _lshift_implementation(self, other): return NotImplemented def _rshift_implementation(self, other): return NotImplemented
[docs] @convert_operands(diagBroadcast=True) @validate_prediction @refine_operands() def __lshift__(self, other): """Denote either set membership or a linear matrix inequality. If the other operand is a set, then this denotes that the expression shall be constrained to that set. Otherwise, it is expected that both expressions are square matrices of same shape and this denotes that the expression is upper-bounded by the other expression with respect to the Loewner order (i.e. ``other - self`` is positive semidefinite). """ result = self._lshift_implementation(other) if result is NotImplemented: result = other._rshift_implementation(self) return result
[docs] @convert_operands(diagBroadcast=True) @validate_prediction @refine_operands() def __rshift__(self, other): """Denote that the expression is lower-bounded in the Lowener order. In other words, return a constraint that ``self - other`` is positive semidefinite. """ result = self._rshift_implementation(other) if result is NotImplemented: result = other._lshift_implementation(self) return result
# -------------------------------------------------------------------------- # Backwards compatibility methods. # --------------------------------------------------------------------------
[docs] @deprecated("2.0", useInstead="~picos.valuable.Valuable.valued") def is_valued(self): """Whether the expression is valued.""" return self.valued
[docs] @deprecated("2.0", useInstead="~picos.valuable.Valuable.value") def set_value(self, value): """Set the value of an expression.""" self.value = value
@deprecated("2.0", "PICOS treats all inequalities as non-strict. Using the " "strict inequality comparison operators may lead to unexpected results " "when dealing with integer problems.") def __lt__(self, exp): return self.__le__(exp) @deprecated("2.0", "PICOS treats all inequalities as non-strict. Using the " "strict inequality comparison operators may lead to unexpected results " "when dealing with integer problems.") def __gt__(self, exp): return self.__ge__(exp)
# -------------------------------------- __all__ = api_end(_API_START, globals())