implemented power of graph function under basic methods

[saatvikraoIITGN]

Description

This PR introduces a new function, power_of_graph, to compute the kth power of an undirected, unweighted graph efficiently using the shortest distances method. The proposed function leverages Breadth-First Search (BFS) to calculate the power graph, providing a practical and scalable solution.

Why is this change required?

The change is required to address the need for efficiently calculating the kth power of a graph, a fundamental operation in graph theory. The PR aims to incorporate this feature into the SageMath library.

Fixes #36582

Checklist

• The title is concise, informative, and self-explanatory.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion (if applicable).
• I have created tests covering the changes.
• I have updated the documentation accordingly.

⌛ Dependencies

#36582 : To implement power of graph

[dcoudert]

It would be better to implement method power in generic_graph.py to address both directed and undirected graphs, and to use builtin fonctions .

For instance,

other = self.copy()
for u in self:
    for v in self.breadth_first_search(u, distance=k):
        other.add_edge(u, v)

One difficulty is to deal with (di)graphs with loops and/or multiple edges.

[dcoudert]

For your information, we also have method distance_graph that returns the graph with only edges between vertices at distance exactly k in the original graph.

[saatvikraoIITGN]

It would be better to implement method power in generic_graph.py to address both directed and undirected graphs, and to use builtin fonctions .

For instance,

other = self.copy()
for u in self:
    for v in self.breadth_first_search(u, distance=k):
        other.add_edge(u, v)

One difficulty is to deal with (di)graphs with loops and/or multiple edges.

Sir the code suggested by your works fine with digraphs with loops and multiple edges

I will raise the PR with the changes

[dcoudert]

The coding style must be improved (see how it is done in other methods) and some care is needed for graphs with multiple edges.

[saatvikraoIITGN]

@dcoudert does the code seem fine?

[dcoudert]

1. Check and correct the doctest errors reported by the CI
2. Although it is currently possible to import DiGraph from sage.graphs.graph, please don't do that.
3. Check and document the expected result when k < 0, k = 0, k=1, k=+oo
4. Respect the 80 columns mode in comments and doctests, as done in other methods.
5. Add empty line after INPUT: and OUTPUT: as done in other methods.
6. Set the name of the graph before returning it.
7. Add a TESTS:: block and check the behavior of the method in corner cases, when the graph has multiple edges

[saatvikraoIITGN]

@dcoudert What do you mean by Set the name of the graph before returning it.

[dcoudert]

@dcoudert What do you mean by Set the name of the graph before returning it.

sage: G = graphs.PetersenGraph()
sage: G
Petersen graph: Graph on 10 vertices
sage: G.name("a cool name")   # Here we change the name
sage: G
a cool name: Graph on 10 vertices
sage: G = Graph(name="My empty graph")    # Here we set the name of a new graph
sage: G
My empty graph: Graph on 0 vertices

[saatvikraoIITGN]

@dcoudert What do you mean by Set the name of the graph before returning it.

sage: G = graphs.PetersenGraph()
sage: G
Petersen graph: Graph on 10 vertices
sage: G.name("a cool name")   # Here we change the name
sage: G
a cool name: Graph on 10 vertices
sage: G = Graph(name="My empty graph")    # Here we set the name of a new graph
sage: G
My empty graph: Graph on 0 vertices

For eg.: in the following test

sage: G = Graph([(0, 1), (1, 2), (2, 3), (3, 0), (2, 4), (4, 5)])
sage: k = 2
sage: PG = G.power(k)
sage: PG.edges(sort=True, labels=False)```

We have to name the graph, `G`, before `PG = G.power(k)`?

[dcoudert]

We have to name the graph, G, before PG = G.power(k)?

No, there is no need to name the graph here.

I'm saying that you can set the name inside the method, as is done for instance in method complement

sage: G = graphs.PetersenGraph()
sage: H = G.complement()
sage: H
complement(Petersen graph): Graph on 10 vertices
sage: H.name()
'complement(Petersen graph)'

[github-actions]

Documentation preview for this PR (built with commit e0dc49d; changes) is ready! 🎉

[dcoudert]

LGTM.