X-Git-Url: http://gitweb.michael.orlitzky.com/?a=blobdiff_plain;f=mjo%2Fcone%2Fcone.py;h=aeec0c90b5f582c8ba858d4b616fff191fb6d529;hb=c2d15c0884c8b92483f58826747887bd2bcdcdeb;hp=b564661ae7cffcac86c220d88e4f4f07de5fa650;hpb=9f5ea6c361ba75f19ebfdbcb74bdc8a0fb1f3c1a;p=sage.d.git

diff --git a/mjo/cone/cone.py b/mjo/cone/cone.py
index b564661..aeec0c9 100644
--- a/mjo/cone/cone.py
+++ b/mjo/cone/cone.py
@@ -1,35 +1,45 @@
 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``.
+
+    If the base ring of ``L`` is ``SR``, then the situation is more
+    complicated:
+
+    - ``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.
 
-    .. WARNING::
+    .. SEEALSO::
 
-        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.
+          :func:`is_cross_positive_on`,
+          :func:`is_Z_operator_on`,
+          :func:`is_lyapunov_like_on`
 
     EXAMPLES:
 
@@ -70,50 +80,85 @@ def is_positive_on(L,K):
         ....:       for L in K.positive_operators_gens() ]) # long time
         True
 
+    Technically we could test this, but for now only closed convex cones
+    are supported as our ``K`` argument::
+
+        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:
+        raise ValueError('The base ring of 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``.
+
+    If the base ring of ``L`` is ``SR``, then the situation is more
+    complicated:
 
-    .. WARNING::
+    - ``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.
 
-        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.
+    .. SEEALSO::
+
+          :func:`is_positive_on`,
+          :func:`is_Z_operator_on`,
+          :func:`is_lyapunov_like_on`
 
     EXAMPLES:
 
@@ -146,49 +191,78 @@ def is_cross_positive_on(L,K):
         ....:       for L in K.cross_positive_operators_gens() ]) # long time
         True
 
+    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([8,2,-8]), vector([5,-5,7]) ]
+        sage: is_cross_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_cross_positive_on(L,K)
+        Traceback (most recent call last):
+        ...
+        ValueError: The base ring of L is neither SR nor exact.
+
     """
-    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.
-        raise ValueError('base ring of operator 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:
+        raise ValueError('The base ring of 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):
+def is_Z_operator_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``.
+
+    If the base ring of ``L`` is ``SR``, then the situation is more
+    complicated:
+
+    - ``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.
 
-    .. WARNING::
+    .. SEEALSO::
 
-        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.
+          :func:`is_positive_on`,
+          :func:`is_cross_positive_on`,
+          :func:`is_lyapunov_like_on`
 
     EXAMPLES:
 
@@ -197,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::
@@ -205,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:
@@ -214,13 +288,33 @@ 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
+    are supported as our ``K`` argument::
+
+        sage: L = identity_matrix(3)
+        sage: K = [ vector([-4,20,3]), vector([1,-5,2]) ]
+        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)
 
@@ -229,31 +323,46 @@ 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.
 
+    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
+    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.
+
+    .. SEEALSO::
+
+          :func:`is_positive_on`,
+          :func:`is_cross_positive_on`,
+          :func:`is_Z_operator_on`
 
     EXAMPLES:
 
@@ -294,15 +403,34 @@ def is_lyapunov_like_on(L,K):
         ....:       for L in K.lyapunov_like_basis() ])      # long time
         True
 
+    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([2,2,-1]), vector([5,4,-3]) ]
+        sage: is_lyapunov_like_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_lyapunov_like_on(L,K)
+        Traceback (most recent call last):
+        ...
+        ValueError: The base ring of L is neither SR nor exact.
+
     """
-    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.
-        raise ValueError('base ring of operator 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:
+        raise ValueError('The base ring of 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()