From 115ecffcebcd0b7f86358aa38ddb52f1115e966c Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Mon, 13 Feb 2017 11:21:15 -0500 Subject: [PATCH] Clarify the docstrings for the is_foo_on functions. --- mjo/cone/cone.py | 183 ++++++++++++++++++++++++++--------------------- 1 file changed, 103 insertions(+), 80 deletions(-) diff --git a/mjo/cone/cone.py b/mjo/cone/cone.py index b564661..cbbfe9b 100644 --- a/mjo/cone/cone.py +++ b/mjo/cone/cone.py @@ -1,35 +1,39 @@ from sage.all import * +from sage.geometry.cone import is_Cone def is_positive_on(L,K): r""" Determine whether or not ``L`` is positive on ``K``. - We say that ``L`` is positive on ``K`` if `L\left\lparen x - \right\rparen` belongs to ``K`` for all `x` in ``K``. This - property need only be checked for generators of ``K``. + We say that ``L`` is positive on a closed convex cone ``K`` if + `L\left\lparen x \right\rparen` belongs to ``K`` for all `x` in + ``K``. This property need only be checked for generators of ``K``. + + To reliably check whether or not ``L`` is positive, its base ring + must be either exact (for example, the rationals) or ``SR``. An + exact ring is more reliable, but in some cases a matrix whose + entries contain symbolic constants like ``e`` and ``pi`` will work. INPUT: - - ``L`` -- A linear transformation or matrix. + - ``L`` -- A matrix over either an exact ring or ``SR``. - ``K`` -- A polyhedral closed convex cone. OUTPUT: - ``True`` if it can be proven that ``L`` is positive on ``K``, - and ``False`` otherwise. If ``L`` is over an exact ring (the - rationals, for example), then you can trust the answer. Only - for symbolic ``L`` might there be difficulty in proving - positivity. + If the base ring of ``L`` is exact, then ``True`` will be returned if + and only if ``L`` is positive on ``K``. - .. WARNING:: + If the base ring of ``L`` is ``SR``, then the situation is more + complicated: - If this function returns ``True``, then ``L`` is positive - on ``K``. However, if ``False`` is returned, that could mean one - of two things. The first is that ``L`` is definitely not - positive on ``K``. The second is more of an "I don't know" - answer, returned (for example) if we cannot prove that an inner - product is nonnegative. + - ``True`` will be returned if it can be proven that ``L`` + is positive on ``K``. + - ``False`` will be returned if it can be proven that ``L`` + is not positive on ``K``. + - ``False`` will also be returned if we can't decide; specifically + if we arrive at a symbolic inequality that cannot be resolved. EXAMPLES: @@ -71,49 +75,58 @@ def is_positive_on(L,K): True """ + if not is_Cone(K): + raise TypeError('K must be a Cone') + if not L.base_ring().is_exact() and not L.base_ring() is SR: + raise ValueError('base ring of operator L is neither SR nor exact') + if L.base_ring().is_exact(): - # This could potentially be extended to other types of ``K``... + # This should be way faster than computing the dual and + # checking a bunch of inequalities, but it doesn't work if + # ``L*x`` is symbolic. For example, ``e in Cone([(1,)])`` + # is true, but returns ``False``. return all([ L*x in K for x in K ]) - elif L.base_ring() is SR: + else: # Fall back to inequality-checking when the entries of ``L`` # might be symbolic. return all([ s*(L*x) >= 0 for x in K for s in K.dual() ]) - else: - # The only inexact ring that we're willing to work with is SR, - # since it can still be exact when working with symbolic - # constants like pi and e. - raise ValueError('base ring of operator L is neither SR nor exact') def is_cross_positive_on(L,K): r""" Determine whether or not ``L`` is cross-positive on ``K``. - We say that ``L`` is cross-positive on ``K`` if `\left\langle - L\left\lparenx\right\rparen,s\right\rangle \ge 0` for all pairs - `\left\langle x,s \right\rangle` in the complementarity set of - ``K``. This property need only be checked for generators of + We say that ``L`` is cross-positive on a closed convex cone``K`` if + `\left\langle L\left\lparenx\right\rparen,s\right\rangle \ge 0` for + all pairs `\left\langle x,s \right\rangle` in the complementarity + set of ``K``. This property need only be checked for generators of ``K`` and its dual. + To reliably check whether or not ``L`` is cross-positive, its base + ring must be either exact (for example, the rationals) or ``SR``. An + exact ring is more reliable, but in some cases a matrix whose + entries contain symbolic constants like ``e`` and ``pi`` will work. + INPUT: - - ``L`` -- A linear transformation or matrix. + - ``L`` -- A matrix over either an exact ring or ``SR``. - ``K`` -- A polyhedral closed convex cone. OUTPUT: - ``True`` if it can be proven that ``L`` is cross-positive on ``K``, - and ``False`` otherwise. + If the base ring of ``L`` is exact, then ``True`` will be returned if + and only if ``L`` is cross-positive on ``K``. - .. WARNING:: + If the base ring of ``L`` is ``SR``, then the situation is more + complicated: - If this function returns ``True``, then ``L`` is cross-positive - on ``K``. However, if ``False`` is returned, that could mean one - of two things. The first is that ``L`` is definitely not - cross-positive on ``K``. The second is more of an "I don't know" - answer, returned (for example) if we cannot prove that an inner - product is nonnegative. + - ``True`` will be returned if it can be proven that ``L`` + is cross-positive on ``K``. + - ``False`` will be returned if it can be proven that ``L`` + is not cross-positive on ``K``. + - ``False`` will also be returned if we can't decide; specifically + if we arrive at a symbolic inequality that cannot be resolved. EXAMPLES: @@ -147,48 +160,52 @@ def is_cross_positive_on(L,K): True """ - if L.base_ring().is_exact() or L.base_ring() is SR: - return all([ s*(L*x) >= 0 - for (x,s) in K.discrete_complementarity_set() ]) - else: - # The only inexact ring that we're willing to work with is SR, - # since it can still be exact when working with symbolic - # constants like pi and e. + if not is_Cone(K): + raise TypeError('K must be a Cone') + if not L.base_ring().is_exact() and not L.base_ring() is SR: raise ValueError('base ring of operator L is neither SR nor exact') + return all([ s*(L*x) >= 0 + for (x,s) in K.discrete_complementarity_set() ]) def is_Z_on(L,K): r""" Determine whether or not ``L`` is a Z-operator on ``K``. - We say that ``L`` is a Z-operator on ``K`` if `\left\langle - L\left\lparenx\right\rparen,s\right\rangle \le 0` for all pairs - `\left\langle x,s \right\rangle` in the complementarity set of - ``K``. It is known that this property need only be - checked for generators of ``K`` and its dual. + We say that ``L`` is a Z-operator on a closed convex cone``K`` if + `\left\langle L\left\lparenx\right\rparen,s\right\rangle \le 0` for + all pairs `\left\langle x,s \right\rangle` in the complementarity + set of ``K``. It is known that this property need only be checked + for generators of ``K`` and its dual. A matrix is a Z-operator on ``K`` if and only if its negation is a cross-positive operator on ``K``. + To reliably check whether or not ``L`` is a Z operator, its base + ring must be either exact (for example, the rationals) or ``SR``. An + exact ring is more reliable, but in some cases a matrix whose + entries contain symbolic constants like ``e`` and ``pi`` will work. + INPUT: - - ``L`` -- A linear transformation or matrix. + - ``L`` -- A matrix over either an exact ring or ``SR``. - ``K`` -- A polyhedral closed convex cone. OUTPUT: - ``True`` if it can be proven that ``L`` is a Z-operator on ``K``, - and ``False`` otherwise. + If the base ring of ``L`` is exact, then ``True`` will be returned if + and only if ``L`` is a Z-operator on ``K``. - .. WARNING:: + If the base ring of ``L`` is ``SR``, then the situation is more + complicated: - If this function returns ``True``, then ``L`` is a Z-operator - on ``K``. However, if ``False`` is returned, that could mean one - of two things. The first is that ``L`` is definitely not - a Z-operator on ``K``. The second is more of an "I don't know" - answer, returned (for example) if we cannot prove that an inner - product is nonnegative. + - ``True`` will be returned if it can be proven that ``L`` + is a Z-operator on ``K``. + - ``False`` will be returned if it can be proven that ``L`` + is not a Z-operator on ``K``. + - ``False`` will also be returned if we can't decide; specifically + if we arrive at a symbolic inequality that cannot be resolved. EXAMPLES: @@ -229,31 +246,37 @@ def is_lyapunov_like_on(L,K): r""" Determine whether or not ``L`` is Lyapunov-like on ``K``. - We say that ``L`` is Lyapunov-like on ``K`` if `\left\langle - L\left\lparenx\right\rparen,s\right\rangle = 0` for all pairs - `\left\langle x,s \right\rangle` in the complementarity set of - ``K``. This property need only be checked for generators of + We say that ``L`` is Lyapunov-like on a closed convex cone ``K`` if + `\left\langle L\left\lparenx\right\rparen,s\right\rangle = 0` for + all pairs `\left\langle x,s \right\rangle` in the complementarity + set of ``K``. This property need only be checked for generators of ``K`` and its dual. + To reliably check whether or not ``L`` is Lyapunov-like, its base + ring must be either exact (for example, the rationals) or ``SR``. An + exact ring is more reliable, but in some cases a matrix whose + entries contain symbolic constants like ``e`` and ``pi`` will work. + INPUT: - - ``L`` -- A linear transformation or matrix. + - ``L`` -- A matrix over either an exact ring or ``SR``. - ``K`` -- A polyhedral closed convex cone. OUTPUT: - ``True`` if it can be proven that ``L`` is Lyapunov-like on ``K``, - and ``False`` otherwise. + If the base ring of ``L`` is exact, then ``True`` will be returned if + and only if ``L`` is Lyapunov-like on ``K``. - .. WARNING:: + If the base ring of ``L`` is ``SR``, then the situation is more + complicated: - If this function returns ``True``, then ``L`` is Lyapunov-like - on ``K``. However, if ``False`` is returned, that could mean one - of two things. The first is that ``L`` is definitely not - Lyapunov-like on ``K``. The second is more of an "I don't know" - answer, returned (for example) if we cannot prove that an inner - product is zero. + - ``True`` will be returned if it can be proven that ``L`` + is Lyapunov-like on ``K``. + - ``False`` will be returned if it can be proven that ``L`` + is not Lyapunov-like on ``K``. + - ``False`` will also be returned if we can't decide; specifically + if we arrive at a symbolic inequality that cannot be resolved. EXAMPLES: @@ -295,15 +318,15 @@ def is_lyapunov_like_on(L,K): True """ - if L.base_ring().is_exact() or L.base_ring() is SR: - return all([ s*(L*x) == 0 - for (x,s) in K.discrete_complementarity_set() ]) - else: - # The only inexact ring that we're willing to work with is SR, - # since it can still be exact when working with symbolic - # constants like pi and e. + if not is_Cone(K): + raise TypeError('K must be a Cone') + if not L.base_ring().is_exact() and not L.base_ring() is SR: raise ValueError('base ring of operator L is neither SR nor exact') + return all([ s*(L*x) == 0 + for (x,s) in K.discrete_complementarity_set() ]) + + def LL_cone(K): gens = K.lyapunov_like_basis() L = ToricLattice(K.lattice_dim()**2) -- 2.43.2