def tolerance_scale(self, solution):
r"""
- Return a scaling factor that should be applied to :const:`ABS_TOL`
- for this game.
+
+ Return a scaling factor that should be applied to
+ :const:`dunshire.options.ABS_TOL` for this game.
When performing certain comparisons, the default tolerance
- :const:`ABS_TOL` may not be appropriate. For example, if we expect
- ``x`` and ``y`` to be within :const:`ABS_TOL` of each other,
- than the inner product of ``L*x`` and ``y`` can be as far apart
- as the spectral norm of ``L`` times the sum of the norms of
- ``x`` and ``y``. Such a comparison is made in :meth:`solution`,
- and in many of our unit tests.
+ :const:`dunshire.options.ABS_TOL` may not be appropriate. For
+ example, if we expect ``x`` and ``y`` to be within
+ :const:`dunshire.options.ABS_TOL` of each other, than the inner
+ product of ``L*x`` and ``y`` can be as far apart as the spectral
+ norm of ``L`` times the sum of the norms of ``x`` and
+ ``y``. Such a comparison is made in :meth:`solution`, and in
+ many of our unit tests.
The returned scaling factor found from the inner product
mentioned above is
-------
float
- A scaling factor to be multiplied by :const:`ABS_TOL` when
+ A scaling factor to be multiplied by
+ :const:`dunshire.options.ABS_TOL` when
making comparisons involving solutions of this game.
Examples
Returns
-------
- :class:`Solution`
+ Solution
A :class:`Solution` object describing the game's value and
the optimal strategies of both players.
Parameters
----------
- left, right : matrix
- The two matrices to append to one another.
+ left : matrix
+ The "original" matrix, the one that will wind up on the left.
+
+ right : matrix
+ The matrix to be appended on the right of ``left``.
Returns
-------
Parameters
----------
- top, bottom : matrix
- The two matrices to append to one another.
+ top : matrix
+ The "original" matrix, the one that will wind up on top.
+
+ bottom : matrix
+ The matrix to be appended below ``top``.
Returns
-------
Parameters
----------
- vec1, vec2 : matrix
- The two vectors whose inner product you want.
+ vec1 : matrix
+ The first vector, whose inner product with ``vec2`` you want.
+
+ vec2 : matrix
+ The second vector, whose inner product with ``vec1`` you want.
Returns
-------
Return the spectral norm of a matrix.
The spectral norm of a matrix is its largest singular value, and it
- corresponds to the operator norm induced by the vector ``2``-norm.
+ corresponds to the operator norm induced by the vector Euclidean norm.
Parameters
----------
DEBUG_FLOAT_FORMAT = '%.20f'
"""
The float output format to use when something goes wrong. If we need to
-produce a random test case, for example, then we need all of the digits
+reproduce a random test case, for example, then we need all of the digits
of the things involved. If we try to recreate the problem using only,
say, the first seven digits of each number, then the resulting game
might not reproduce the failure.
FLOAT_FORMAT = '%.7f'
"""
-The default output format for floating point numbers. It has been
-chosen to match the ``ABS_TOL``, in the sense that if ``x != y``,
-then they would not appear different when printed.
+The default output format for floating point numbers.
"""
def run_suite(suite):
"""
- Run all of the unit and doctests for the ``dunshire`` and ``test``
- packages.
+ Run all of the unit and doctests for the :mod:`dunshire` and
+ :mod:`test` packages.
"""
runner = TextTestRunner(verbosity=1)
return runner.run(suite)
"""
-Unit tests for the functions in the ``matrices`` module.
+Unit tests for the functions in the :mod:`dunshire.matrices` module.
"""
from copy import deepcopy
class AppendRowTest(TestCase):
"""
- Tests for the :func:`append_row` function.
+ Tests for the :func:`dunshire.matrices.append_row` function.
"""
def test_new_dimensions(self):
class EigenvaluesTest(TestCase):
"""
- Tests for the :func:`eigenvalues` function.
+ Tests for the :func:`dunshire.matrices.eigenvalues` function.
"""
def test_eigenvalues_input_not_clobbered(self):
def test_eigenvalues_of_symmat_are_real(self):
"""
A real symmetric matrix has real eigenvalues, so if we start
- with a symmetric matrix, then the two functions :func:`eigenvalues`
- and :func:`eigenvalues_re` should agree on it.
+ with a symmetric matrix, then the two functions
+ :func:`dunshire.matrices.eigenvalues` and
+ :func:`dunshire.matrices.eigenvalues_re` should agree on it.
"""
mat = random_matrix(random_natural())
symmat = mat + mat.trans()
class EigenvaluesRealPartTest(TestCase):
"""
- Tests for the :func:`eigenvalues_re` function.
+ Tests for the :func:`dunshire.matrices.eigenvalues_re` function.
"""
def test_eigenvalues_re_input_not_clobbered(self):
"""
- The eigenvalue functions provided by CVXOPT/LAPACK like to
- overwrite the matrices that you pass into them as
- arguments. This test makes sure that our :func:`eigenvalues_re`
- function does not do the same.
+ The eigenvalue functions provided by CVXOPT/LAPACK like
+ to overwrite the matrices that you pass into them as
+ arguments. This test makes sure that our
+ :func:`dunshire.matrices.eigenvalues_re` function does not do
+ the same.
We use a ``deepcopy`` here in case the ``copy`` used in the
- :func:`eigenvalues_re` function is insufficient. If ``copy`` didn't
- work and this test used it too, then this test would pass when
- it shouldn't.
+ :func:`dunshire.matrices.eigenvalues_re` function is
+ insufficient. If ``copy`` didn't work and this test used it too,
+ then this test would pass when it shouldn't.
"""
mat = random_matrix(random_natural())
mat_copy = deepcopy(mat)
class InnerProductTest(TestCase):
"""
- Tests for the :func:`inner_product` function.
+ Tests for the :func:`dunshire.matrices.inner_product` function.
"""
def test_inner_product_with_self_is_norm_squared(self):
"""
- Ensure that the func:`inner_product` and :func:`norm` functions
- are compatible by checking that the square of the norm of a
- vector is its inner product with itself.
+ Ensure that the func:`dunshire.matrices.inner_product` and
+ :func:`dunshire.matrices.norm` functions are compatible by
+ checking that the square of the norm of a vector is its inner
+ product with itself.
"""
vec = random_matrix(random_natural(), 1)
actual = inner_product(vec, vec)
class NormTest(TestCase):
"""
- Tests for the :func:`norm` function.
+ Tests for the :func:`dunshire.matrices.norm` function.
"""
def test_norm_is_nonnegative(self):
class ConditionNumberTest(TestCase):
"""
- Tests for the :func:`condition_number` function.
+ Tests for the :func:`dunshire.matrices.condition_number` function.
"""
def test_condition_number_ge_one(self):
-------
float
- A random real number between ``-RANDOM_MAX`` and ``RANDOM_MAX``,
- inclusive.
+ A random real number between negative and positive
+ :const:`RANDOM_MAX`, inclusive.
Examples
--------
-------
float
- A random nonnegative real number between zero and ``RANDOM_MAX``,
- inclusive.
+ A random nonnegative real number between zero and
+ :const:`RANDOM_MAX`, inclusive.
Examples
--------
-------
int
- A random natural number between ``1`` and ``RANDOM_MAX`` inclusive.
+ A random natural number between ``1`` and :const:`RANDOM_MAX`,
+ inclusive.
Examples
--------
-------
matrix
- A new matrix whose entries are random floats chosen uniformly from
- the interval ``[-RANDOM_MAX, RANDOM_MAX]``.
+ A new matrix whose entries are random floats chosen uniformly
+ between negative and positive :const:`RANDOM_MAX`.
Examples
--------
matrix
A new matrix whose diagonal entries are random floats chosen
- using func:`random_scalar` and whose off-diagonal entries are
+ using :func:`random_scalar` and whose off-diagonal entries are
zero.
Examples
matrix
A new matrix, Lyapunov-like on the ice-cream cone in ``dims``
dimensions, whose free entries are random floats chosen uniformly
- from the interval ``[-RANDOM_MAX, RANDOM_MAX]``.
+ between negative and positive :const:`RANDOM_MAX`.
References
----------
We generate each of ``L``, ``K``, ``e1``, and ``e2`` randomly within
the constraints of the nonnegative orthant, and then construct a
game from them. The process is repeated until we generate a game with
- a condition number under ``MAX_COND``.
+ a condition number under :const:`MAX_COND`.
Returns
-------
We generate each of ``L``, ``K``, ``e1``, and ``e2`` randomly within
the constraints of the ice-cream cone, and then construct a game
from them. The process is repeated until we generate a game with a
- condition number under ``MAX_COND``.
+ condition number under :const:`MAX_COND`.
Returns
-------
to have a :func:`random_diagonal_matrix` as its operator. Such
things are Lyapunov-like on the nonnegative orthant. That process is
repeated until the condition number of the resulting game is within
- ``MAX_COND``.
+ :const:`MAX_COND`.
Returns
-------
SymmetricLinearGame
- A random game over some nonnegative orthant whose ``payoff`` method
- is based on a Lyapunov-like ``L`` operator.
+
+ A random game over some nonnegative orthant whose
+ :meth:`dunshire.games.SymmetricLinearGame.payoff` method is
+ based on a Lyapunov-like
+ :meth:`dunshire.games.SymmetricLinearGame.L` operator.
Examples
--------
We first construct a :func:`random_icecream_game` and then modify it
to have a :func:`random_lyapunov_like_icecream` operator. That
process is repeated until the condition number of the resulting game
- is within ``MAX_COND``.
+ is within :const:`MAX_COND`.
Returns
-------
SymmetricLinearGame
- A random game over some ice-cream cone whose ``payoff`` method
- is based on a Lyapunov-like ``L`` operator.
+ A random game over some ice-cream cone whose
+ :meth:`dunshire.games.SymmetricLinearGame.payoff` method
+ is based on a Lyapunov-like
+ :meth:`dunshire.games.SymmetricLinearGame.L` operator.
Examples
--------
We first construct a :func:`random_orthant_game` and then modify it
to have a :func:`random_nonnegative_matrix` as its operator. That
process is repeated until the condition number of the resulting game
- is within ``MAX_COND``.
+ is within :const:`MAX_COND`.
Returns
-------
SymmetricLinearGame
- A random game over some nonnegative orthant whose ``payoff`` method
- is based on a positive ``L`` operator.
+ A random game over some nonnegative orthant whose
+ :meth:`dunshire.games.SymmetricLinearGame.payoff` method
+ is based on a positive
+ :meth:`dunshire.games.SymmetricLinearGame.L` operator.
Examples
--------
projects / dunshire.git / commitdiff