Networks¶

def add_vertices(self, *vertices: V, **kwargs: Unpack[VertexOptions[V]]) -> Group:
    """Add vertices to the graph, without edges.

    Each is made as the graph makes its vertices, with the keywords given over the
    graph's own, and placed at its position, or at the graph's center. A vertex
    already in the graph raises a ValueError.

    Args:
        *vertices: The new vertices: hashable values, each a vertex's name.
        **kwargs: [Vertex keywords][manimgx.mobjects.graph.VertexOptions]:
            `positions`, `labels`, `vertex_type`, `vertex_config`, ….

    Returns:
        A new group of the new vertices' mobjects.

    Examples:
        ```python
        import manimgx as m


        class GraphAddVerticesExample(m.Scene):
            def construct(self) -> None:
                graph = m.Graph(
                    [1, 2, 3],
                    [(1, 2), (2, 3)],
                    layout={1: [-4, -1, 0], 2: [0, -2, 0], 3: [4, -1, 0]},
                    vertex_config={"radius": 0.15},
                )
                self.add(graph)
                top = graph.add_vertices(
                    4, positions={4: [0, 2.5, 0]}, vertex_config={"color": m.YELLOW}
                )
                self.play(m.FadeIn(top, scale=3))
                self.play(m.Create(graph.add_edges((1, 4), (3, 4))))
        ```
    """
    return Group(
        *(
            self._add_created_vertex(*v)
            for v in self._create_vertices(*vertices, **kwargs)
        )
    )

def remove_vertices(self, *vertices: V) -> Group:
    """Remove vertices from the graph, and the edges that touch them.

    A vertex not in the graph raises a ValueError.

    Args:
        *vertices: The vertices to remove.

    Returns:
        A new group of the removed mobjects (for each vertex, its edges, then the
        vertex), to fade out, for instance.

    Examples:
        ```python
        import manimgx as m


        class GraphRemoveVerticesExample(m.Scene):
            def construct(self) -> None:
                graph = m.Graph(
                    [1, 2, 3, 4, 5],
                    [(1, 2), (2, 3), (3, 4), (4, 5), (5, 1), (1, 3)],
                    layout="circular",
                    layout_scale=3,
                )
                self.add(graph)
                self.play(m.FadeOut(graph.remove_vertices(3)))
        ```
    """
    return Group(*(m for v in vertices for m in self._remove_vertex(v).submobjects))

def add_edges(
    self,
    *edges: Edge[V],
    edge_type: Maker = Line,
    edge_config: Configs | None = None,
    **kwargs: Unpack[VertexOptions[V]],
) -> Group:
    """Add edges to the graph, and the vertices they name that it lacks.

    The missing vertices are added first, as
    [add_vertices][manimgx.mobjects.graph.GenericGraph.add_vertices] adds them, with
    the vertex keywords given; each edge is then made as the graph makes its edges,
    with the edge keywords given over the graph's own.

    Args:
        *edges: The new edges, each a pair of vertices.
        edge_type: The class of the new edges.
        edge_config: Keywords for the new edges, over the graph's: for all of them,
            and an edge's own under its pair of vertices, in place of those for all;
            None for none.
        **kwargs: [Vertex keywords][manimgx.mobjects.graph.VertexOptions] for the
            vertices the edges name that the graph lacks.

    Returns:
        A new group of the new mobjects, the vertices added and then the edges.
    """
    shared, own = _split(edge_config, edges)
    base = self.default_edge_config.copy() | shared
    new_vertices = [
        v for v in dict.fromkeys(it.chain(*edges)) if v not in self.vertices
    ]
    added = list(self.add_vertices(*new_vertices, **kwargs))
    for edge in edges:
        added.extend(
            self._add_edge(
                edge, edge_type=edge_type, edge_config=base | own.get(edge, {})
            )
        )
    return Group(*added)

def remove_edges(self, *edges: Edge[V]) -> Group:
    """Remove edges from the graph, keeping their vertices.

    An edge not in the graph raises a ValueError.

    Args:
        *edges: The edges to remove, each a pair of vertices.

    Returns:
        A new group of the removed edges' mobjects.
    """
    return Group(*(self._remove_edge(edge) for edge in edges))

def change_layout(
    self,
    layout: Layout[V] = "spring",
    layout_scale: float | tuple[float, float, float] = 2,
    layout_config: Mapping[str, object] | None = None,
    partitions: Sequence[Sequence[V]] | None = None,
    root_vertex: V | None = None,
) -> Self:
    """Lay the graph out anew: move each vertex to its place in a layout.

    The vertices move at once, and the edges follow them at the next frame, as the
    graph's updater moves them. To animate the change, animate each vertex to its
    place in a changed copy (as below): the edges follow all the way.

    A layout function gets a fresh NetworkX graph of the current vertices and edges.
    Its node, edge and graph attributes belong to that call, not to later layouts.

    Args:
        layout: Where the vertices go: a layout's name, their positions, or a
            layout function (see
            [GenericGraph][manimgx.mobjects.graph.GenericGraph]).
        layout_scale: How far the layout reaches from the center, in scene units.
        layout_config: Keywords for the layout function; None for none.
        partitions: For the `"partite"` layout: the vertices of each column; None
            for none.
        root_vertex: For the `"tree"` layout: the vertex at its top; None for none.

    Examples:
        ```python
        import manimgx as m


        class GraphChangeLayoutExample(m.Scene):
            def construct(self) -> None:
                graph = m.Graph(
                    [1, 2, 3, 4, 5, 6],
                    [(1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 1), (1, 4)],
                    layout={v: [2 * v - 7, 0, 0] for v in range(1, 7)},
                )
                circle = graph.copy().change_layout("circular", layout_scale=3)
                self.add(graph)
                self.play(
                    *(graph[v].animate.move_to(circle[v]) for v in graph.vertices)
                )
        ```
    """
    return self._place_vertices(
        self.edges,
        layout=layout,
        layout_scale=layout_scale,
        layout_config=layout_config,
        partitions=partitions,
        root_vertex=root_vertex,
    )

@classmethod
def from_networkx(cls, nxgraph: NxGraph, **kwargs: Unpack[GraphOptions[V]]) -> Self:
    """Make a graph of a [NetworkX](https://networkx.org) graph's nodes and edges.

    Args:
        nxgraph: The NetworkX graph (a `Graph`, or a `DiGraph`).
        **kwargs: [Graph keywords][manimgx.Graph]: `layout`,
            `labels`, `vertex_config`, ….

    Returns:
        A new graph.

    Examples:
        ```python
        import networkx as nx

        import manimgx as m


        class GraphFromNetworkxExample(m.Scene):
            def construct(self) -> None:
                petersen = nx.petersen_graph()
                graph = m.Graph.from_networkx(
                    petersen,
                    layout="shell",
                    layout_scale=3,
                    layout_config={"nlist": [range(5, 10), range(5)]},
                )
                self.play(m.Create(graph), run_time=2)
        ```
    """
    return cls(list(nxgraph.nodes), list(nxgraph.edges), **kwargs)

def update_edges(self, graph: Mobject) -> Self:
    """Put each edge back on its vertices, where they are now: the updater a graph
    runs every frame, so that its edges follow its vertices.

    Each kind of graph sets its edges' ends its own way: an undirected graph's from
    center to center, a directed graph's from outline to outline, with its tip.
    Only edges that are lines ([Line][manimgx.Line] and its kinds) follow.

    Args:
        graph: The mobject the updater runs for (the graph); unused.
    """
    raise NotImplementedError("To be implemented in concrete subclasses")