From c2d15c0884c8b92483f58826747887bd2bcdcdeb Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Mon, 13 Feb 2017 13:03:34 -0500 Subject: [PATCH] Add SEEALSO blocks and inexact ring error tests. --- mjo/cone/cone.py | 81 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 73 insertions(+), 8 deletions(-) diff --git a/mjo/cone/cone.py b/mjo/cone/cone.py index 865a070..aeec0c9 100644 --- a/mjo/cone/cone.py +++ b/mjo/cone/cone.py @@ -35,6 +35,12 @@ def is_positive_on(L,K): - ``False`` will also be returned if we can't decide; specifically if we arrive at a symbolic inequality that cannot be resolved. + .. SEEALSO:: + + :func:`is_cross_positive_on`, + :func:`is_Z_operator_on`, + :func:`is_lyapunov_like_on` + EXAMPLES: Nonnegative matrices are positive operators on the nonnegative @@ -77,14 +83,24 @@ def is_positive_on(L,K): Technically we could test this, but for now only closed convex cones are supported as our ``K`` argument:: - sage: L = identity_matrix(3) sage: K = [ vector([1,2,3]), vector([5,-1,7]) ] + sage: L = identity_matrix(3) sage: is_positive_on(L,K) Traceback (most recent call last): ... TypeError: K must be a Cone. + We can't give reliable answers over inexact rings:: + + sage: K = Cone([(1,2,3), (4,5,6)]) + sage: L = identity_matrix(RR,3) + sage: is_positive_on(L,K) + Traceback (most recent call last): + ... + ValueError: The base ring of L is neither SR nor exact. + """ + 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: @@ -138,6 +154,12 @@ def is_cross_positive_on(L,K): - ``False`` will also be returned if we can't decide; specifically if we arrive at a symbolic inequality that cannot be resolved. + .. SEEALSO:: + + :func:`is_positive_on`, + :func:`is_Z_operator_on`, + :func:`is_lyapunov_like_on` + EXAMPLES: The identity operator is always cross-positive:: @@ -179,6 +201,15 @@ def is_cross_positive_on(L,K): ... TypeError: K must be a Cone. + We can't give reliable answers over inexact rings:: + + sage: K = Cone([(1,2,3), (4,5,6)]) + sage: L = identity_matrix(RR,3) + sage: is_cross_positive_on(L,K) + Traceback (most recent call last): + ... + ValueError: The base ring of L is neither SR nor exact. + """ if not is_Cone(K): raise TypeError('K must be a Cone.') @@ -188,7 +219,7 @@ def is_cross_positive_on(L,K): return all([ s*(L*x) >= 0 for (x,s) in K.discrete_complementarity_set() ]) -def is_Z_on(L,K): +def is_Z_operator_on(L,K): r""" Determine whether or not ``L`` is a Z-operator on ``K``. @@ -227,6 +258,12 @@ def is_Z_on(L,K): - ``False`` will also be returned if we can't decide; specifically if we arrive at a symbolic inequality that cannot be resolved. + .. SEEALSO:: + + :func:`is_positive_on`, + :func:`is_cross_positive_on`, + :func:`is_lyapunov_like_on` + EXAMPLES: The identity operator is always a Z-operator:: @@ -234,7 +271,7 @@ def is_Z_on(L,K): sage: set_random_seed() sage: K = random_cone(max_ambient_dim=8) sage: L = identity_matrix(K.lattice_dim()) - sage: is_Z_on(L,K) + sage: is_Z_operator_on(L,K) True The "zero" operator is always a Z-operator:: @@ -242,7 +279,7 @@ def is_Z_on(L,K): sage: K = random_cone(max_ambient_dim=8) sage: R = K.lattice().vector_space().base_ring() sage: L = zero_matrix(R, K.lattice_dim()) - sage: is_Z_on(L,K) + sage: is_Z_operator_on(L,K) True TESTS: @@ -251,11 +288,11 @@ def is_Z_on(L,K): on ``K``:: sage: K = random_cone(max_ambient_dim=5) - sage: all([ is_Z_on(L,K) # long time + sage: all([ is_Z_operator_on(L,K) # long time ....: for L in K.Z_operators_gens() ]) # long time True - sage: all([ is_Z_on(L.change_ring(SR),K) # long time - ....: for L in K.Z_operators_gens() ]) # long time + sage: all([ is_Z_operator_on(L.change_ring(SR),K) # long time + ....: for L in K.Z_operators_gens() ]) # long time True Technically we could test this, but for now only closed convex cones @@ -263,11 +300,21 @@ def is_Z_on(L,K): sage: L = identity_matrix(3) sage: K = [ vector([-4,20,3]), vector([1,-5,2]) ] - sage: is_Z_on(L,K) + sage: is_Z_operator_on(L,K) Traceback (most recent call last): ... TypeError: K must be a Cone. + + We can't give reliable answers over inexact rings:: + + sage: K = Cone([(1,2,3), (4,5,6)]) + sage: L = identity_matrix(RR,3) + sage: is_Z_operator_on(L,K) + Traceback (most recent call last): + ... + ValueError: The base ring of L is neither SR nor exact. + """ return is_cross_positive_on(-L,K) @@ -282,6 +329,9 @@ def is_lyapunov_like_on(L,K): set of ``K``. This property need only be checked for generators of ``K`` and its dual. + An operator is Lyapunov-like on ``K`` if and only if both the + operator itself and its negation are cross-positive on ``K``. + 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 @@ -308,6 +358,12 @@ def is_lyapunov_like_on(L,K): - ``False`` will also be returned if we can't decide; specifically if we arrive at a symbolic inequality that cannot be resolved. + .. SEEALSO:: + + :func:`is_positive_on`, + :func:`is_cross_positive_on`, + :func:`is_Z_operator_on` + EXAMPLES: Diagonal matrices are Lyapunov-like operators on the nonnegative @@ -357,6 +413,15 @@ def is_lyapunov_like_on(L,K): ... TypeError: K must be a Cone. + We can't give reliable answers over inexact rings:: + + sage: K = Cone([(1,2,3), (4,5,6)]) + sage: L = identity_matrix(RR,3) + sage: is_lyapunov_like_on(L,K) + Traceback (most recent call last): + ... + ValueError: The base ring of L is neither SR nor exact. + """ if not is_Cone(K): raise TypeError('K must be a Cone.') -- 2.43.2