网络¶

def add_vertices(self, *vertices: V, **kwargs: Unpack[VertexOptions[V]]) -> Group:
    """向图中添加顶点，不添加边。

    每个顶点按图构造顶点的方式构造，使用覆盖图自身关键字的关键字，
    并放置在其位置处，或图的中心处。图中已存在的顶点会引发 ValueError。

    Args:
        *vertices: 新顶点：可哈希的值，每个是一个顶点的名称。
        **kwargs: [顶点关键字][manimgx.mobjects.graph.VertexOptions]：
            `positions`、`labels`、`vertex_type`、`vertex_config`，……。

    Returns:
        由新顶点的 mobject 构成的新组。

    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:
    """从图中移除顶点，以及与之相连的边。

    图中不存在的顶点会引发 ValueError。

    Args:
        *vertices: 要移除的顶点。

    Returns:
        由被移除的 mobject 构成的新组（对每个顶点，先为其边，再为顶点本身），
        例如可用于淡出。

    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_vertices][manimgx.mobjects.graph.GenericGraph.add_vertices]，使用给定的
    顶点关键字；随后每条边按图构造边的方式构造，使用覆盖图自身关键字的
    边关键字。

    Args:
        *edges: 新边，每个是顶点的有序对。
        edge_type: 新边的类。
        edge_config: 新边的关键字，覆盖图自身的：对所有边生效，以及某条边
            在其顶点对下的独有配置，取代对所有边的配置；
            None 表示无。
        **kwargs: 边所引用而图中尚缺的顶点的
            [顶点关键字][manimgx.mobjects.graph.VertexOptions]。

    Returns:
        由新 mobject 构成的新组，先为添加的顶点，再为边。
    """
    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:
    """从图中移除边，保留其顶点。

    图中不存在的边会引发 ValueError。

    Args:
        *edges: 要移除的边，每个是顶点的有序对。

    Returns:
        由被移除的边的 mobject 构成的新组。
    """
    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:
    """对图重新布局：将每个顶点移动到其在布局中的位置。

    顶点一次性移动，边在下一帧跟随，由图的更新器移动。若要为变化设置动画，
    请将每个顶点动画移动到已更改副本中的位置（如下所示）：边会全程跟随。

    布局函数收到一个由当前顶点和边构成的全新 NetworkX 图。
    其节点、边和图属性属于该次调用，而非后续布局。

    Args:
        layout: 顶点所在之处：布局的名称、其位置，或一个
            布局函数（参见
            [GenericGraph][manimgx.mobjects.graph.GenericGraph]）。
        layout_scale: 布局从中心向外延伸的距离，以场景单位计。
        layout_config: 布局函数的关键字；None 表示无。
        partitions: 用于 `"partite"` 布局：每列的顶点；None
            表示无。
        root_vertex: 用于 `"tree"` 布局：位于顶部的顶点；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:
    """由 [NetworkX](https://networkx.org) 图的节点和边构造一个图。

    Args:
        nxgraph: NetworkX 图（一个 `Graph`，或一个 `DiGraph`）。
        **kwargs: [图关键字][manimgx.Graph]：`layout`、
            `labels`、`vertex_config`，……。

    Returns:
        一个新的图。

    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:
    """将每条边重新放回其顶点上，按顶点当前位置：图每帧运行的更新器，
    使其边跟随其顶点。

    每种图以各自的方式设置边的两端：无向图从中心到中心，有向图从轮廓到轮廓，
    并带有尖端。只有作为线条的边（[Line][manimgx.Line] 及其子类）会跟随。

    Args:
        graph: 更新器为之运行的 mobject（该图）；未使用。
    """
    raise NotImplementedError("To be implemented in concrete subclasses")