From: Michael Orlitzky Date: Sun, 15 Feb 2026 18:50:31 +0000 (-0500) Subject: README: convert to reStructuredText X-Git-Url: https://gitweb.michael.orlitzky.com/?a=commitdiff_plain;p=the_uniqueness_of_lyapunov_rank_among_symmetric_cones.git README: convert to reStructuredText This is a python project, so we might as well use the standard documentation format. --- diff --git a/README b/README deleted file mode 100644 index 8248b9c..0000000 --- a/README +++ /dev/null @@ -1,70 +0,0 @@ -This directory contains all of the tests for the claims in the paper, -as well as the supporting code. It has a few requirements: - - * Python built with support for sqlite - * SymPy - * MessagePack for python - -Here is a quick summary of the files: - - * compute.py - utilities for computing all cones, ranks of Lorentz - cones, etc. and storing them in a database. These are long- - running computations, not otherwise used by the test suite. - - * cones.py - the SymmetricCone class and its subclasses L, HR, HC, - HH, and HO. - - * live.db - an empty (until you fill it) SQLite database for storing - the cones/ranks computed by the functions in compute.py. - - HINT: unless you want "git diff" to take forever and tempt you to - commit gigabytes of binary junk to the repo, you should tell git - (insofar as is possible) to ignore changes to the live database: - - $ git update-index --assume-unchanged tests/live.db - $ git update-index --skip-worktree tests/live.db - - * partitions.py - functions relating to integer partitions. - - * sql.py - functions for working with the SQL database. - - * tests.py - the main tests for the results in the paper. - - * verify-live-db.py - a runnable script that will inspect live.db to - make sure there is enough (consistent) data there. - -Every function (not just the results in the paper) is itself -tested. To run the entire test suite, you can run - - $ python -m doctest *.py - -from within this directory. To populate the live database, there are -two things to do. First, run compute.py: - - $ python compute.py - computing cones of dimension 0... - computing cones of dimension 1... - -This will start computing all symmetric cones, up to isomorphism, in -dimension=1,2,.... successively. It will take a very long time and -eventually consume all of your RAM. Hit Ctrl-C when you get scared, -and it will stop. The cones are saved to the database at each step, so -killing the program will only abandon the computation for the current -dimension (not all previous dimensions). - -In addition to the cones, you will also want to compute some Lyapunov -ranks corresponding to Lorentz cones. For that, the same compute.py -is used, but you have to pass it "lorentz" as the first argument on -the command-line: - - $ python compute.py lorentz - computing lorentz ranks in dimension 0... - computing lorentz ranks in dimension 1... - -Again, hit Ctrl-C when you get bored. Afterwards your live.db will -hopefully contain enough data to check the results in the paper. -Running, - - $ python verify-live-db.py - -will confirm it. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..bbe4087 --- /dev/null +++ b/README.rst @@ -0,0 +1,81 @@ +This repository contains tests and supporting code for the claims in +the paper *The uniqueness of Lyapunov rank among symmetric cones* by +Michael Orlitzky and Giovanni Barbarino. It has a few requirements: + +* Python built with support for sqlite +* `SymPy `_ +* `MessagePack `_ for python + +Here is a quick summary of the files: + +* **compute.py** - utilities for computing all cones, ranks of Lorentz + cones, etc. and storing them in a database. These are long- + running computations, not otherwise used by the test suite. + +* **cones.py** - the ``SymmetricCone`` class and its subclasses ``L``, + ``HR``, ``HC``, ``HH``, and ``HO``. + +* **live.db** - an empty (until you fill it) SQLite database for + storing the cones/ranks computed by the functions in compute.py. + + HINT: unless you want "git diff" to take forever and tempt you to + commit gigabytes of binary junk to the repo, you should tell git + (insofar as is possible) to ignore changes to the live database: + + .. code-block:: console + + $ git update-index --assume-unchanged live.db + $ git update-index --skip-worktree live.db + +* **partitions.py** - functions relating to integer partitions. + +* **sql.py** - functions for working with the SQL database. + +* **tests.py** - the main tests for the results in the paper. + +* **verify-live-db.py** - a runnable script that will inspect live.db + to make sure there is enough (consistent) data there. + +Every function (not just the results in the paper) is itself +tested. To run the entire test suite, you can run + +.. code-block:: console + + $ python -m doctest *.py + +from within this directory. To populate the live database, there are +two things to do. First, run compute.py: + +.. code-block:: console + + $ python compute.py + computing cones of dimension 0... + computing cones of dimension 1... + +This will start computing all symmetric cones, up to isomorphism, in +dimension=1,2,.... successively. It will take a very long time and +eventually consume all of your RAM. Hit Ctrl-C when you get scared, +and it will stop. The cones are saved to the database at each step, so +killing the program will only abandon the computation for the current +dimension (not all previous dimensions). + +In addition to the cones, you will also want to compute some Lyapunov +ranks corresponding to Lorentz cones. For that, the same compute.py +is used, but you have to pass it "lorentz" as the first argument on +the command-line: + +.. code-block:: console + + $ python compute.py lorentz + computing lorentz ranks in dimension 0... + computing lorentz ranks in dimension 1... + +Again, hit Ctrl-C when you get bored. Afterwards your live.db will +hopefully contain enough data to check the results in the paper. +Running, + +.. code-block:: console + + $ python verify-live-db.py + +will confirm it.