trac #16766: Improve the doc of combinat/designs/

src/doc/en/reference/combinat/designs.rst

@@ -1,26 +1,40 @@
 Designs and Incidence Structures
 ================================
 
+All designs can be accessed by ``designs.<tab>`` and are listed in
+the design catalog:
+
 .. toctree::
    :maxdepth: 1
 
-   ../sage/combinat/designs/covering_design
-   ../sage/combinat/designs/ext_rep
-   ../sage/combinat/designs/incidence_structures
    ../sage/combinat/designs/design_catalog
 
-Constructions
--------------
+**Design-related classes**
+
+.. toctree::
+   :maxdepth: 1
+
+   ../sage/combinat/designs/incidence_structures
+   ../sage/combinat/designs/covering_design
+
+**Constructions**
 
 .. toctree::
    :maxdepth: 1
 
    ../sage/combinat/designs/block_design
    ../sage/combinat/designs/bibd
-   ../sage/combinat/designs/steiner_quadruple_systems
    ../sage/combinat/designs/latin_squares
    ../sage/combinat/designs/orthogonal_arrays
    ../sage/combinat/designs/orthogonal_arrays_recursive
    ../sage/combinat/designs/difference_family
+   ../sage/combinat/designs/steiner_quadruple_systems
    ../sage/combinat/designs/database
 
+**Technical things**
+
+.. toctree::
+   :maxdepth: 1
+
+   ../sage/combinat/designs/ext_rep
+   ../sage/combinat/designs/designs_pyx

src/sage/combinat/designs/bibd.py

@@ -1,27 +1,34 @@
 r"""
 Balanced Incomplete Block Designs (BIBD)
 
-This module implements two constructions of Balanced Incomplete Block Designs:
+This module gathers everything related to Balanced Incomplete Block Designs. One can build a
+BIBD (or check that it can be built) with :func:`balanced_incomplete_block_design`::
 
-* Steiner Triple Systems, i.e. `(v,3,1)`-BIBD.
-* `K_4`-decompositions of `K_v`, i.e. `(v,4,1)`-BIBD.
+    sage: designs.balanced_incomplete_block_design(7,3)
 
-These BIBD can be obtained through the :func:`balanced_incomplete_block_design`
-method, available in Sage as ``designs.balanced_incomplete_block_design``.
+In particular, Sage can build a `(v,k,1)`-BIBD when one exists for all `k\leq
+5`. The following functions are available:
 
-EXAMPLES::
+It defines the following functions:
+
+.. csv-table::
+    :class: contentstable
+    :widths: 30, 70
+    :delim: |
+
+    :func:`balanced_incomplete_block_design` | Returns a BIBD of parameters `v,k`.
+    :func:`BIBD_from_TD` | Returns a BIBD through TD-based constructions.
+    :func:`BIBD_from_difference_family` | Return the BIBD associated to the difference family ``D`` on the group ``G``.
+    :func:`BIBD_from_PBD` | Returns a `(v,k,1)`-BIBD from a `(r,K)`-PBD where `r=(v-1)/(k-1)`.
+    :func:`PBD_from_TD` | Returns a `(kt,\{k,t\})`-PBD if `u=0` and a `(kt+u,\{k,k+1,t,u\})`-PBD otherwise.
+    :func:`steiner_triple_system` | Returns a Steiner Triple System.
+    :func:`v_5_1_BIBD` | Returns a `(v,5,1)`-BIBD.
+    :func:`v_4_1_BIBD` | Returns a `(v,4,1)`-BIBD.
+    :func:`PBD_4_5_8_9_12` | Returns a `(v,\{4,5,8,9,12\})`-PBD on `v` elements.
+    :func:`BIBD_5q_5_for_q_prime_power` | Returns a `(5q,5,1)`-BIBD with `q\equiv 1\pmod 4` a prime power.
 
-    sage: designs.balanced_incomplete_block_design(7,3)
-    Incidence structure with 7 points and 7 blocks
-    sage: designs.balanced_incomplete_block_design(7,3).blocks()
-    [[0, 1, 3], [0, 2, 4], [0, 5, 6], [1, 2, 6], [1, 4, 5], [2, 3, 5], [3, 4, 6]]
-    sage: designs.balanced_incomplete_block_design(13,4).blocks()
-    [[0, 1, 2, 12], [0, 3, 6, 9], [0, 4, 8, 10], [0, 5, 7, 11], [1, 3, 8, 11],
-     [1, 4, 7, 9], [1, 5, 6, 10], [2, 3, 7, 10], [2, 4, 6, 11], [2, 5, 8, 9],
-     [3, 4, 5, 12], [6, 7, 8, 12], [9, 10, 11, 12]]
 
-`K_4`-decompositions of `K_v`
------------------------------
+**Construction of BIBD when** `k=4`
 
 Decompositions of `K_v` into `K_4` (i.e. `(v,4,1)`-BIBD) are built following
 Douglas Stinson's construction as presented in [Stinson2004]_ page 167. It is
@@ -30,8 +37,7 @@
 can always be transformed into a `((k-1)v+1,4,1)`-BIBD, which covers all
 possible cases of `(v,4,1)`-BIBD.
 
-`K_5`-decompositions of `K_v`
------------------------------
+**Construction of BIBD when** `k=5`
 
 Decompositions of `K_v` into `K_4` (i.e. `(v,4,1)`-BIBD) are built following
 Clayton Smith's construction [ClaytonSmith]_.
@@ -796,7 +802,7 @@ def _relabel_bibd(B,n,p=None):
 
 def PBD_4_5_8_9_12(v, check=True):
     """
-    Returns a `(v,\{4,5,8,9,12\})-`PBD on `v` elements.
+    Returns a `(v,\{4,5,8,9,12\})`-PBD on `v` elements.
 
     A `(v,\{4,5,8,9,12\})`-PBD exists if and only if `v\equiv 0,1 \pmod 4`. The
     construction implemented here appears page 168 in [Stinson2004]_.

src/sage/combinat/designs/block_design.py

@@ -3,8 +3,7 @@
 
 A *block design* is a set together with a family of subsets (repeated subsets
 are allowed) whose members are chosen to satisfy some set of properties that are
-deemed useful for a particular application. See :wikipedia:`Block_design`. It is
-an object equivalent to an incidence structure.
+deemed useful for a particular application. See :wikipedia:`Block_design`.
 
 REFERENCES:
 

src/sage/combinat/designs/design_catalog.py

@@ -1,9 +1,8 @@
 r"""
 Catalog of designs
 
-This module gathers all designs that can be reached from a Sage sessions
-through the ``designs`` objects. In order to create the Witt design on 24 points
-it is sufficient to type::
+This module gathers all designs that can be reached through
+``designs.<tab>``. Example with the the Witt design on 24 points::
 
     sage: designs.WittDesign(24) # optional - gap_packages
     Incidence structure with 24 points and 759 blocks
@@ -13,13 +12,11 @@
     sage: designs.steiner_triple_system(19)
     Incidence structure with 19 points and 57 blocks
 
-Online database -- Jolla Covering Repository (LJCR) :
+**La Jolla Covering Repository**
 
-There exists an online database of the best known covering designs, the La Jolla
-Covering Repository (LJCR), available at [1]_. As it is over 60MB and changes
-frequently that database is not included in Sage, but one can obtain individual
-coverings and block designs from the LJCR using the method
-:meth:`designs.best_known_covering_design_from_LJCR
+The La Jolla Covering Repository (LJCR, see [1]_) is an online database of
+covering designs. As it is frequently updated, it is not included in Sage, but
+one can query it through :meth:`designs.best_known_covering_design_from_LJCR
 <sage.combinat.designs.covering_design.best_known_covering_design_www>`::
 
     sage: C = designs.best_known_covering_design_from_LJCR(7, 3, 2)   # optional - internet
@@ -31,7 +28,9 @@
     sage: C.incidence_structure()      # optional - internet
     Incidence structure with 7 points and 7 blocks
 
-Currently, this module gathers the following designs :
+**Design constructors**
+
+This module gathers the following designs :
 
 .. csv-table::
     :class: contentstable
@@ -40,14 +39,15 @@
 
     :meth:`~sage.combinat.designs.block_design.ProjectiveGeometryDesign`
     :meth:`~sage.combinat.designs.block_design.DesarguesianProjectivePlaneDesign`
-    :meth:`~sage.combinat.designs.bibd.BalancedIncompleteBlockDesign`
+    :meth:`~sage.combinat.designs.bibd.balanced_incomplete_block_design`
     :meth:`~sage.combinat.designs.block_design.AffineGeometryDesign`
     :meth:`~sage.combinat.designs.block_design.WittDesign`
     :meth:`~sage.combinat.designs.block_design.HadamardDesign`
     :meth:`~sage.combinat.designs.block_design.Hadamard3Design`
     :meth:`~sage.combinat.designs.latin_squares.mutually_orthogonal_latin_squares`
     :meth:`~sage.combinat.designs.orthogonal_arrays.transversal_design`
     :meth:`~sage.combinat.designs.orthogonal_arrays.orthogonal_array`
+    :meth:`~sage.combinat.designs.orthogonal_arrays.incomplete_orthogonal_array`
     :meth:`~sage.combinat.designs.bibd.steiner_triple_system`
     :meth:`~sage.combinat.designs.steiner_quadruple_systems.steiner_quadruple_system`
     :meth:`~sage.combinat.designs.block_design.projective_plane`

src/sage/combinat/designs/difference_family.py

@@ -1,10 +1,29 @@
 r"""
 Difference families
 
+This module gathers everything related to difference families. One can build a
+difference family (or check that it can be built) with :func:`difference_family`::
+
+    sage: OA = designs.difference_family(7,4,1)
+
+It defines the following functions:
+
+.. csv-table::
+    :class: contentstable
+    :widths: 30, 70
+    :delim: |
+
+    :func:`is_difference_family` | Return a (``k``, ``l``)-difference family on an Abelian group of size ``v``.
+    :func:`singer_difference_set` | Return a difference set associated to hyperplanes in a projective space.
+    :func:`difference_family` | Return a (``k``, ``l``)-difference family on an Abelian group of size ``v``.
+
 REFERENCES:
 
 .. [Wi72] R. M. Wilson "Cyclotomy and difference families in elementary Abelian
    groups", J. of Num. Th., 4 (1972), pp. 17-47.
+
+Functions
+---------
 """
 #*****************************************************************************
 #       Copyright (C) 2014 Vincent Delecroix <20100.delecroix@gmail.com>

src/sage/combinat/designs/ext_rep.py

@@ -1,4 +1,4 @@
-"""
+r"""
 External Representations of Block Designs
 
 The "ext_rep" module is an API to the abstract tree represented by
@@ -14,10 +14,16 @@
 .. [D2009] P. Dobcsanyi et al. DesignTheory.org
    http://designtheory.org/database/
 
-TODO: The XML data from the designtheory.org database contains a wealth
-of information about things like automorphism groups, transitivity,
-cycle type representatives, etc, but none of this data is made
-available through the current implementation.
+.. TODO::
+
+    The XML data from the designtheory.org database contains a wealth of
+    information about things like automorphism groups, transitivity, cycle type
+    representatives, etc, but none of this data is made available through the
+    current implementation.
+
+Functions
+---------
+
 """
 
 ###########################################################################

src/sage/combinat/designs/incidence_structures.py

@@ -1,8 +1,29 @@
-"""
+r"""
 Incidence structures (i.e. hypergraphs, i.e. set systems)
 
-An incidence structure is specified by a list of points, blocks, and
-an incidence matrix ([1]_, [2]_).
+An incidence structure is specified by a list of points, blocks, or an incidence
+matrix ([1]_, [2]_). :class:`IncidenceStructure` instances have the following methods:
+
+.. csv-table::
+    :class: contentstable
+    :widths: 30, 70
+    :delim: |
+
+    :meth:`~IncidenceStructure.ground_set` | Return the ground set (i.e the list of points).
+    :meth:`~IncidenceStructure.num_points` | Returns the size of the ground set.
+    :meth:`~IncidenceStructure.num_blocks` | Returns the number of blocks.
+    :meth:`~IncidenceStructure.blocks` | Return the list of blocks.
+    :meth:`~IncidenceStructure.block_sizes` | Return the set of block sizes.
+    :meth:`~IncidenceStructure.degree` | Returns the degree of a point ``p``
+    :meth:`~IncidenceStructure.is_connected` | Test whether the design is connected.
+    :meth:`~IncidenceStructure.is_simple` | Test whether this design is simple (i.e. no repeated block).
+    :meth:`~IncidenceStructure.incidence_matrix` | Return the incidence matrix `A` of the design
+    :meth:`~IncidenceStructure.incidence_graph` | Returns the incidence graph of the design
+    :meth:`~IncidenceStructure.packing` | Returns a maximum packing
+    :meth:`~IncidenceStructure.is_t_design` | Test whether ``self`` is a `t-(v,k,l)` design.
+    :meth:`~IncidenceStructure.dual` | Returns the dual design.
+    :meth:`~IncidenceStructure.automorphism_group` | Returns the automorphism group
+    :meth:`~IncidenceStructure.edge_coloring` | Returns an optimal edge coloring`
 
 REFERENCES:
 
@@ -445,7 +466,7 @@ def ground_set(self, copy=True):
 
     def num_points(self):
         r"""
-        The number of points in that design.
+        Returns the size of the ground set.
 
         EXAMPLES::
 
@@ -459,7 +480,7 @@ def num_points(self):
 
     def num_blocks(self):
         r"""
-        The number of blocks.
+        Returns the number of blocks.
 
         EXAMPLES::
 
@@ -472,7 +493,8 @@ def num_blocks(self):
         return len(self._blocks)
 
     def blocks(self, copy=True):
-        """Return the list of blocks.
+        """
+        Return the list of blocks.
 
         INPUT:
 

src/sage/combinat/designs/latin_squares.py

@@ -2,20 +2,32 @@
 r"""
 Mutually Orthogonal Latin Squares (MOLS)
 
-This module gathers Sage's functions related to Mutually Orthogonal Latin
-Squares. Its main function is :func:`mutually_orthogonal_latin_squares` which
-can be used to generate MOLS::
+The main function of this module is :func:`mutually_orthogonal_latin_squares`
+and can be can be used to generate MOLS (or check that they exist)::
 
     sage: MOLS = designs.mutually_orthogonal_latin_squares(4,8)
 
 For more information on MOLS, see the :wikipedia:`Wikipedia entry on MOLS
 <Graeco-Latin_square#Mutually_orthogonal_Latin_squares>`. If you are only
 interested by latin squares, see :mod:`~sage.combinat.matrices.latin`.
 
-The following table prints the maximum number of MOLS that Sage can build for
-every order `n<600`, similarly to the `table of MOLS
-<http://books.google.fr/books?id=S9FA9rq1BgoC&dq=handbook%20combinatorial%20designs%20MOLS%2010000&pg=PA176>`_
-from the Handbook of Combinatorial Designs 2ed [DesignHandbook]_.
+The functions defined here are
+
+.. csv-table::
+    :class: contentstable
+    :widths: 30, 70
+    :delim: |
+
+    :meth:`mutually_orthogonal_latin_squares` | Returns `k` Mutually Orthogonal `n\times n` Latin Squares.
+    :meth:`are_mutually_orthogonal_latin_squares` | Check that the list ``l`` of matrices in are MOLS.
+    :meth:`latin_square_product` | Returns the product of two (or more) latin squares.
+    :meth:`MOLS_table` | Prints the MOLS table.
+
+**Table of MOLS**
+
+Sage can produce a table of MOLS similar to the one from the Handbook of
+Combinatorial Designs [DesignHandbook]_ (`available here
+<http://books.google.fr/books?id=S9FA9rq1BgoC&dq=handbook%20combinatorial%20designs%20MOLS%2010000&pg=PA176>`_).
 
 ::