- ``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
sage: is_positive_on(L,K)
True
+ Your matrix can be over any exact ring, but you may get unexpected
+ answers with weirder rings. For example, any rational matrix is
+ positive on the plane, but if your matrix contains polynomial
+ variables, the answer will be negative::
+
+ sage: K = Cone([(1,0),(-1,0),(0,1),(0,-1)])
+ sage: K.is_full_space()
+ True
+ sage: L = matrix(QQ[x], [[x,0],[0,1]])
+ sage: is_positive_on(L,K)
+ False
+
+ The previous example is "unexpected" because it depends on how we
+ check whether or not ``L`` is positive. For exact base rings, we
+ check whether or not ``L*z`` belongs to ``K`` for each ``z in K``.
+ If ``K`` is closed, then an equally-valid test would be to check
+ whether the inner product of ``L*z`` and ``s`` is nonnegative for
+ every ``z`` in ``K`` and ``s`` in ``K.dual()``. In fact, that is
+ what we do over inexact rings. In the previous example, that test
+ would return an affirmative answer::
+
+ sage: K = Cone([(1,0),(-1,0),(0,1),(0,-1)])
+ sage: L = matrix(QQ[x], [[x,0],[0,1]])
+ sage: all([ (L*z).inner_product(s) for z in K for s in K.dual() ])
+ True
+ sage: is_positive_on(L.change_ring(SR), K)
+ True
+
TESTS:
The identity operator is always positive::
....: 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')
+ 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')
+ raise ValueError('The base ring of L is neither SR nor exact.')
if L.base_ring().is_exact():
# This should be way faster than computing the dual and
- ``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::
....: 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 not is_Cone(K):
- raise TypeError('K must be a Cone')
+ 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')
+ 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``.
- ``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::
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::
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:
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)
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
- ``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
....: 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.
+
+ An operator is Lyapunov-like on a cone if and only if both the
+ operator and its negation are cross-positive on the cone::
+
+ sage: K = random_cone(max_ambient_dim=5)
+ sage: R = K.lattice().vector_space().base_ring()
+ sage: L = random_matrix(R, K.lattice_dim())
+ sage: actual = is_lyapunov_like_on(L,K) # long time
+ sage: expected = (is_cross_positive_on(L,K) and # long time
+ ....: is_cross_positive_on(-L,K)) # long time
+ sage: actual == expected # long time
+ True
+
"""
if not is_Cone(K):
- raise TypeError('K must be a Cone')
+ 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')
+ raise ValueError('The base ring of L is neither SR nor exact.')
+ # Even though ``discrete_complementarity_set`` is a cached method
+ # of cones, this is faster than calling ``is_cross_positive_on``
+ # twice: doing so checks twice as many inequalities as the number
+ # of equalities that we're about to check.
return all([ s*(L*x) == 0
for (x,s) in K.discrete_complementarity_set() ])
projects / sage.d.git / blobdiff