X-Git-Url: https://scm.cri.ensmp.fr/git/linpy.git/blobdiff_plain/c9bd08381cbc109ae9602cc780fc7e8899651ae3..ba15f3f33f837b1291f74bc94081e99b860d3228:/linpy/linexprs.py diff --git a/linpy/linexprs.py b/linpy/linexprs.py index 8267be1..82d75d0 100644 --- a/linpy/linexprs.py +++ b/linpy/linexprs.py @@ -45,12 +45,43 @@ def _polymorphic(func): class LinExpr: """ - This class implements linear expressions. + A linear expression consists of a list of coefficient-variable pairs + that capture the linear terms, plus a constant term. Linear expressions + are used to build constraints. They are temporary objects that typically + have short lifespans. + + Linear expressions are generally built using overloaded operators. For + example, if x is a Symbol, then x + 1 is an instance of LinExpr. + + LinExpr instances are hashable, and should be treated as immutable. """ def __new__(cls, coefficients=None, constant=0): """ - Create a new expression. + Return a linear expression from a dictionary or a sequence, that maps + symbols to their coefficients, and a constant term. The coefficients and + the constant term must be rational numbers. + + For example, the linear expression x + 2y + 1 can be constructed using + one of the following instructions: + + >>> x, y = symbols('x y') + >>> LinExpr({x: 1, y: 2}, 1) + >>> LinExpr([(x, 1), (y, 2)], 1) + + However, it may be easier to use overloaded operators: + + >>> x, y = symbols('x y') + >>> x + 2*y + 1 + + Alternatively, linear expressions can be constructed from a string: + + >>> LinExpr('x + 2*y + 1') + + A linear expression with a single symbol of coefficient 1 and no + constant term is automatically subclassed as a Symbol instance. A linear + expression with no symbol, only a constant term, is automatically + subclassed as a Rational instance. """ if isinstance(coefficients, str): if constant != 0: @@ -86,7 +117,8 @@ class LinExpr: def coefficient(self, symbol): """ - Return the coefficient value of the given symbol. + Return the coefficient value of the given symbol, or 0 if the symbol + does not appear in the expression. """ if not isinstance(symbol, Symbol): raise TypeError('symbol must be a Symbol instance') @@ -96,7 +128,8 @@ class LinExpr: def coefficients(self): """ - Return a list of the coefficients of an expression + Iterate over the pairs (symbol, value) of linear terms in the + expression. The constant term is ignored. """ for symbol, coefficient in self._coefficients.items(): yield symbol, Rational(coefficient) @@ -104,21 +137,23 @@ class LinExpr: @property def constant(self): """ - Return the constant value of an expression. + The constant term of the expression. """ return Rational(self._constant) @property def symbols(self): """ - Return a list of symbols in an expression. + The tuple of symbols present in the expression, sorted according to + Symbol.sortkey(). """ return self._symbols @property def dimension(self): """ - Create and return a new linear expression from a string or a list of coefficients and a constant. + The dimension of the expression, i.e. the number of symbols present in + it. """ return self._dimension @@ -127,19 +162,22 @@ class LinExpr: def isconstant(self): """ - Return true if an expression is a constant. + Return True if the expression only consists of a constant term. In this + case, it is a Rational instance. """ return False def issymbol(self): """ - Return true if an expression is a symbol. + Return True if an expression only consists of a symbol with coefficient + 1. In this case, it is a Symbol instance. """ return False def values(self): """ - Return the coefficient and constant values of an expression. + Iterate over the coefficient values in the expression, and the constant + term. """ for coefficient in self._coefficients.values(): yield Rational(coefficient) @@ -157,7 +195,7 @@ class LinExpr: @_polymorphic def __add__(self, other): """ - Return the sum of two expressions. + Return the sum of two linear expressions. """ coefficients = defaultdict(Fraction, self._coefficients) for symbol, coefficient in other._coefficients.items(): @@ -170,7 +208,7 @@ class LinExpr: @_polymorphic def __sub__(self, other): """ - Return the difference between two expressions. + Return the difference between two linear expressions. """ coefficients = defaultdict(Fraction, self._coefficients) for symbol, coefficient in other._coefficients.items(): @@ -184,7 +222,7 @@ class LinExpr: def __mul__(self, other): """ - Return the product of two expressions if other is a rational number. + Return the product of the linear expression by a rational. """ if isinstance(other, numbers.Rational): coefficients = ((symbol, coefficient * other) @@ -196,6 +234,9 @@ class LinExpr: __rmul__ = __mul__ def __truediv__(self, other): + """ + Return the quotient of the linear expression by a rational. + """ if isinstance(other, numbers.Rational): coefficients = ((symbol, coefficient / other) for symbol, coefficient in self._coefficients.items()) @@ -206,7 +247,7 @@ class LinExpr: @_polymorphic def __eq__(self, other): """ - Test whether two expressions are equal + Test whether two linear expressions are equal. """ return isinstance(other, LinExpr) and \ self._coefficients == other._coefficients and \ @@ -230,7 +271,8 @@ class LinExpr: def scaleint(self): """ - Multiply an expression by a scalar to make all coefficients integer values. + Return the expression multiplied by its lowest common denominator to + make all values integer. """ lcm = functools.reduce(lambda a, b: a*b // gcd(a, b), [value.denominator for value in self.values()]) @@ -238,8 +280,19 @@ class LinExpr: def subs(self, symbol, expression=None): """ - Subsitute symbol by expression in equations and return the resulting - expression. + Substitute the given symbol by an expression and return the resulting + expression. Raise TypeError if the resulting expression is not linear. + + >>> x, y = symbols('x y') + >>> e = x + 2*y + 1 + >>> e.subs(y, x - 1) + 3*x - 1 + + To perform multiple substitutions at once, pass a sequence or a + dictionary of (old, new) pairs to subs. + + >>> e.subs({x: y, y: x}) + 2*x + y + 1 """ if expression is None: if isinstance(symbol, Mapping): @@ -289,7 +342,8 @@ class LinExpr: @classmethod def fromstring(cls, string): """ - Create an expression from a string. + Create an expression from a string. Raise SyntaxError if the string is + not properly formatted. """ # add implicit multiplication operators, e.g. '5x' -> '5*x' string = LinExpr._RE_NUM_VAR.sub(r'\1*\2', string) @@ -354,7 +408,8 @@ class LinExpr: @classmethod def fromsympy(cls, expr): """ - Convert sympy object to an expression. + Create a linear expression from a sympy expression. Raise ValueError is + the sympy expression is not linear. """ import sympy coefficients = [] @@ -372,7 +427,7 @@ class LinExpr: def tosympy(self): """ - Return an expression as a sympy object. + Convert the linear expression to a sympy expression. """ import sympy expr = 0 @@ -384,10 +439,17 @@ class LinExpr: class Symbol(LinExpr): + """ + Symbols are the basic components to build expressions and constraints. + They correspond to mathematical variables. Symbols are instances of + class LinExpr and inherit its functionalities. + + Two instances of Symbol are equal if they have the same name. + """ def __new__(cls, name): """ - Create and return a symbol from a string. + Return a symbol with the name string given in argument. """ if not isinstance(name, str): raise TypeError('name must be a string') @@ -401,12 +463,22 @@ class Symbol(LinExpr): @property def name(self): + """ + The name of the symbol. + """ return self._name def __hash__(self): return hash(self.sortkey()) def sortkey(self): + """ + Return a sorting key for the symbol. It is useful to sort a list of + symbols in a consistent order, as comparison functions are overridden + (see the documentation of class LinExpr). + + >>> sort(symbols, key=Symbol.sortkey) + """ return self.name, def issymbol(self): @@ -417,7 +489,7 @@ class Symbol(LinExpr): def asdummy(self): """ - Return a symbol as a Dummy Symbol. + Return a new Dummy symbol instance with the same name. """ return Dummy(self.name) @@ -450,13 +522,29 @@ class Symbol(LinExpr): class Dummy(Symbol): """ - This class returns a dummy symbol to ensure that no variables are repeated in an expression + A variation of Symbol in which all symbols are unique and identified by + an internal count index. If a name is not supplied then a string value + of the count index will be used. This is useful when a unique, temporary + variable is needed and the name of the variable used in the expression + is not important. + + Unlike Symbol, Dummy instances with the same name are not equal: + + >>> x = Symbol('x') + >>> x1, x2 = Dummy('x'), Dummy('x') + >>> x == x1 + False + >>> x1 == x2 + False + >>> x1 == x1 + True """ + _count = 0 def __new__(cls, name=None): """ - Create and return a new dummy symbol. + Return a fresh dummy symbol with the name string given in argument. """ if name is None: name = 'Dummy_{}'.format(Dummy._count) @@ -487,7 +575,13 @@ class Dummy(Symbol): def symbols(names): """ - Transform strings into instances of the Symbol class + This function returns a tuple of symbols whose names are taken from a comma + or whitespace delimited string, or a sequence of strings. It is useful to + define several symbols at once. + + >>> x, y = symbols('x y') + >>> x, y = symbols('x, y') + >>> x, y = symbols(['x', 'y']) """ if isinstance(names, str): names = names.replace(',', ' ').split() @@ -496,7 +590,10 @@ def symbols(names): class Rational(LinExpr, Fraction): """ - This class represents integers and rational numbers of any size. + A particular case of linear expressions are rational values, i.e. linear + expressions consisting only of a constant term, with no symbol. They are + implemented by the Rational class, that inherits from both LinExpr and + fractions.Fraction classes. """ def __new__(cls, numerator=0, denominator=None): @@ -514,15 +611,9 @@ class Rational(LinExpr, Fraction): @property def constant(self): - """ - Return rational as a constant. - """ return self def isconstant(self): - """ - Test whether a value is a constant. - """ return True def __bool__(self): @@ -546,9 +637,6 @@ class Rational(LinExpr, Fraction): @classmethod def fromsympy(cls, expr): - """ - Create a rational object from a sympy expression - """ import sympy if isinstance(expr, sympy.Rational): return Rational(expr.p, expr.q)