+ sage: set_random_seed()
+ sage: n = ZZ.random_element(2,10)
+ sage: p = ZZ.random_element(1,n)
+ sage: K1 = rearrangement_cone(p,n)
+ sage: K2 = rearrangement_cone(p+1,n)
+ sage: all( x in K2 for x in K1 )
+ True
+
+ The rearrangement cone of order ``p`` is linearly isomorphic to the
+ rearrangement cone of order ``n - p`` when ``p`` is less than ``n``,
+ by [Jeong]_ Proposition 5.2.1::
+
+ sage: set_random_seed()
+ sage: n = ZZ.random_element(2,10)
+ sage: p = ZZ.random_element(1,n)
+ sage: K1 = rearrangement_cone(p,n)
+ sage: K2 = rearrangement_cone(n-p, n)
+ sage: Mp = (1/p)*matrix.ones(QQ,n) - identity_matrix(QQ,n)
+ sage: Cone( (Mp*K2.rays()).columns() ).is_equivalent(K1)
+ True
+
+ The order ``p`` should be between ``1`` and ``n``, inclusive::
+
+ sage: rearrangement_cone(0,3)
+ Traceback (most recent call last):
+ ...
+ ValueError: order p=0 should be between 1 and n=3, inclusive
+ sage: rearrangement_cone(5,3)
+ Traceback (most recent call last):
+ ...
+ ValueError: order p=5 should be between 1 and n=3, inclusive
+
+ If a ``lattice`` was given, it is actually used::
+
+ sage: L = ToricLattice(3, 'M')
+ sage: rearrangement_cone(2, 3, lattice=L)
+ 3-d cone in 3-d lattice M
+
+ Unless the rank of the lattice disagrees with ``n``::
+
+ sage: L = ToricLattice(1, 'M')
+ sage: rearrangement_cone(2, 3, lattice=L)
+ Traceback (most recent call last):
+ ...
+ ValueError: lattice rank=1 and dimension n=3 are incompatible
+
+ """
+ if p < 1 or p > n:
+ raise ValueError('order p=%d should be between 1 and n=%d, inclusive'
+ %
+ (p,n))
+
+ if lattice is None:
+ lattice = ToricLattice(n)
+
+ if lattice.rank() != n:
+ raise ValueError('lattice rank=%d and dimension n=%d are incompatible'
+ %
+ (lattice.rank(), n))
+
+ I = identity_matrix(ZZ,n)
+ M = matrix.ones(ZZ,n) - p*I
+ G = identity_matrix(ZZ,n).rows() + M.rows()
+ return Cone(G, lattice=lattice)