Graphs with a given degree sequence - Graph Theory

Skip to content
Back to top
View this page
Edit this page

# Graphs with a given degree sequence

The methods defined here appear in `sage.graphs.graph_generators`.

sage.graphs.generators.degree_sequence.DegreeSequence(deg_sequence, immutable=False)

  Return a graph with the given degree sequence.

  This method raises a NetworkX error if the proposed degree sequence cannot be that of a graph.

  Graph returned is the one returned by the Havel-Hakimi algorithm, which constructs a simple graph by connecting vertices of highest degree to other vertices of highest degree, resorting the remaining vertices by degree and repeating the process. See Theorem 1.4 in [CL1996].

  INPUT:

  - `deg_sequence` – list of integers with each entry corresponding to the degree of a different vertex

  - `immutable` – boolean (default: `False`); whether to return an immutable or a mutable graph

  EXAMPLES:

  Sage

      sage: G = graphs.DegreeSequence([3,3,3,3])                                      # needs networkx
      sage: G.edges(sort=True, labels=False)                                          # needs networkx
      [(0, 1), (0, 2), (0, 3), (1, 2), (1, 3), (2, 3)]
      sage: G.show()                          # long time                             # needs networkx sage.plot

  Python

      >>> from sage.all import *
      >>> G = graphs.DegreeSequence([Integer(3),Integer(3),Integer(3),Integer(3)])                                      # needs networkx
      >>> G.edges(sort=True, labels=False)                                          # needs networkx
      [(0, 1), (0, 2), (0, 3), (1, 2), (1, 3), (2, 3)]
      >>> G.show()                          # long time                             # needs networkx sage.plot

  Sage

      sage: G = graphs.DegreeSequence([3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3])  # needs networkx
      sage: G.show()                          # long time                             # needs networkx sage.plot

  [Python]

      >>> from sage.all import *
      >>> G = graphs.DegreeSequence([Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3)])  # needs networkx
      >>> G.show()                          # long time                             # needs networkx sage.plot

  Sage

      sage: G = graphs.DegreeSequence([4,4,4,4,4,4,4,4])                              # needs networkx
      sage: G.show()                          # long time                             # needs networkx sage.plot

  Python

      >>> from sage.all import *
      >>> G = graphs.DegreeSequence([Integer(4),Integer(4),Integer(4),Integer(4),Integer(4),Integer(4),Integer(4),Integer(4)])                              # needs networkx
      >>> G.show()                          # long time                             # needs networkx sage.plot

  Sage

      sage: G = graphs.DegreeSequence([1,2,3,4,3,4,3,2,3,2,1])                        # needs networkx
      sage: G.show()                          # long time                             # needs networkx sage.plot

  [Python]

      >>> from sage.all import *
      >>> G = graphs.DegreeSequence([Integer(1),Integer(2),Integer(3),Integer(4),Integer(3),Integer(4),Integer(3),Integer(2),Integer(3),Integer(2),Integer(1)])                        # needs networkx
      >>> G.show()                          # long time                             # needs networkx sage.plot

sage.graphs.generators.degree_sequence.DegreeSequenceBipartite(s1, s2, immutable=False)

  Return a bipartite graph whose two sets have the given degree sequences.

  Given two different sequences of degrees \(s_1\) and \(s_2\), this functions returns ( if possible ) a bipartite graph on sets \(A\) and \(B\) such that the vertices in \(A\) have \(s_1\) as their degree sequence, while \(s_2\) is the degree sequence of the vertices in \(B\).

  INPUT:

  - `s1` – list of integers corresponding to the degree sequence of the first set of vertices

  - `s2` – list of integers corresponding to the degree sequence of the second set of vertices

  - `immutable` – boolean (default: `False`); whether to return an immutable or a mutable graph

  ALGORITHM:

  This function works through the computation of the matrix given by the Gale-Ryser theorem, which is in this case the adjacency matrix of the bipartite graph.

  EXAMPLES:

  If we are given as sequences `[2,2,2,2,2]` and `[5,5]` we are given as expected the complete bipartite graph \(K_{2,5}\):

  Sage

      sage: g = graphs.DegreeSequenceBipartite([2,2,2,2,2],[5,5])                     # needs sage.combinat sage.modules
      sage: g.is_isomorphic(graphs.CompleteBipartiteGraph(5,2))                       # needs sage.combinat sage.modules
      True

  Python

      >>> from sage.all import *
      >>> g = graphs.DegreeSequenceBipartite([Integer(2),Integer(2),Integer(2),Integer(2),Integer(2)],[Integer(5),Integer(5)])                     # needs sage.combinat sage.modules
      >>> g.is_isomorphic(graphs.CompleteBipartiteGraph(Integer(5),Integer(2)))                       # needs sage.combinat sage.modules
      True

  Some sequences being incompatible if, for example, their sums are different, the functions raises a `ValueError` when no graph corresponding to the degree sequences exists:

  Sage

      sage: g = graphs.DegreeSequenceBipartite([2,2,2,2,1],[5,5])                     # needs sage.combinat sage.modules
      Traceback (most recent call last):
      ...
      ValueError: there exists no bipartite graph corresponding to the given degree sequences

  [Python]

      >>> from sage.all import *
      >>> g = graphs.DegreeSequenceBipartite([Integer(2),Integer(2),Integer(2),Integer(2),Integer(1)],[Integer(5),Integer(5)])                     # needs sage.combinat sage.modules
      Traceback (most recent call last):
      ...
      ValueError: there exists no bipartite graph corresponding to the given degree sequences

sage.graphs.generators.degree_sequence.DegreeSequenceConfigurationModel(deg_sequence, seed=None, immutable=False)

  Return a random pseudograph with the given degree sequence.

  This method raises a NetworkX error if the proposed degree sequence cannot be that of a graph with multiple edges and loops.

  One requirement is that the sum of the degrees must be even, since every edge must be incident with two vertices.

  INPUT:

  - `deg_sequence` – list of integers with each entry corresponding to the expected degree of a different vertex

  - `seed` – (optional) a `random.Random` seed or a Python `int` for the random number generator

  - `immutable` – boolean (default: `False`); whether to return an immutable or a mutable graph

  EXAMPLES:

  Sage

      sage: G = graphs.DegreeSequenceConfigurationModel([1,1])                        # needs networkx
      sage: G.adjacency_matrix()                                                      # needs networkx sage.modules
      [0 1]
      [1 0]

  Python

      >>> from sage.all import *
      >>> G = graphs.DegreeSequenceConfigurationModel([Integer(1),Integer(1)])                        # needs networkx
      >>> G.adjacency_matrix()                                                      # needs networkx sage.modules
      [0 1]
      [1 0]

  The output is allowed to contain both loops and multiple edges:

  Sage

      sage: # needs networkx
      sage: deg_sequence = [3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3]
      sage: G = graphs.DegreeSequenceConfigurationModel(deg_sequence)
      sage: G.order(), G.size()
      (20, 30)
      sage: G.has_loops() or G.has_multiple_edges()  # random
      True
      sage: G.show()                          # long time                             # needs sage.plot

  [Python]

      >>> from sage.all import *
      >>> # needs networkx
      >>> deg_sequence = [Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3),Integer(3)]
      >>> G = graphs.DegreeSequenceConfigurationModel(deg_sequence)
      >>> G.order(), G.size()
      (20, 30)
      >>> G.has_loops() or G.has_multiple_edges()  # random
      True
      >>> G.show()                          # long time                             # needs sage.plot

  REFERENCE:

  [New2003]

sage.graphs.generators.degree_sequence.DegreeSequenceExpected(deg_sequence, seed=None, immutable=False)

  Return a random graph with expected given degree sequence.

  This method raises a NetworkX error if the proposed degree sequence cannot be that of a graph.

  One requirement is that the sum of the degrees must be even, since every edge must be incident with two vertices.

  INPUT:

  - `deg_sequence` – list of integers with each entry corresponding to the expected degree of a different vertex

  - `seed` – (optional) a `random.Random` seed or a Python `int` for the random number generator

  - `immutable` – boolean (default: `False`); whether to return an immutable or a mutable graph

  EXAMPLES:

  Sage

      sage: G = graphs.DegreeSequenceExpected([1,2,3,2,3]); G                         # needs networkx
      Looped graph on 5 vertices
      sage: G.show()                          # long time                             # needs networkx sage.plot

  Python

      >>> from sage.all import *
      >>> G = graphs.DegreeSequenceExpected([Integer(1),Integer(2),Integer(3),Integer(2),Integer(3)]); G                         # needs networkx
      Looped graph on 5 vertices
      >>> G.show()                          # long time                             # needs networkx sage.plot

  REFERENCE:

  [CL2002]

sage.graphs.generators.degree_sequence.DegreeSequenceTree(deg_sequence, immutable=False)

  Return a tree with the given degree sequence.

  This method raises a NetworkX error if the proposed degree sequence cannot be that of a tree.

  Since every tree has one more vertex than edge, the degree sequence must satisfy `len(deg_sequence) - sum(deg_sequence)/2 == 1`.

  INPUT:

  - `deg_sequence` – list of integers with each entry corresponding to the expected degree of a different vertex

  - `immutable` – boolean (default: `False`); whether to return an immutable or a mutable graph

  EXAMPLES:

  Sage

      sage: G = graphs.DegreeSequenceTree([3,1,3,3,1,1,1,2,1]); G                     # needs networkx
      Graph on 9 vertices
      sage: G.show()                          # long time                             # needs networkx sage.plot

  Python

      >>> from sage.all import *
      >>> G = graphs.DegreeSequenceTree([Integer(3),Integer(1),Integer(3),Integer(3),Integer(1),Integer(1),Integer(1),Integer(2),Integer(1)]); G                     # needs networkx
      Graph on 9 vertices
      >>> G.show()                          # long time                             # needs networkx sage.plot