mindspore.mutable
==================

.. image:: https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/br_base/resource/_static/logo_source.svg
    :target: https://gitee.com/mindspore/mindspore/blob/br_base/docs/api/api_python/mindspore/mindspore.mutable.rst
    :alt: 查看源文件


.. py:function:: mindspore.mutable(input_data, dynamic_len=False)

    设置一个常量值为可变的。

    当前除了Tensor，所有顶层网络的输入，例如标量、tuple、list和dict，都被当做常量值。常量值是不能求导的，而且在编译优化阶段常量值会被忽略掉。
    另外，当网络的输入是tuple[Tensor]、list[Tensor]或Dict[Tensor]时，即使里面Tensor的shape和dtype没有发生变化，在多次调用同一个网络的时候，这个网络每次都会被重新编译，这是因为这些类型的输入被当做常量值处理了。

    为解决以上的问题，我们提供了 `mutable` 接口去设置网络的常量输入为"可变的"。一个"可变的"输入意味着这个输入成为了像Tensor一样的变量，最重要的是，我们可以对其进行求导了。

    当 `input_data` 是tuple或者list并且 `dynamic_len` 是False的情况下，`mutable` 的返回值是一个固定长度的tuple或者list，且其中的每一个元素都是可变的。当 `dynamic_len` 被设置为True的时候，返回的tuple或者list长度是动态的。

    当 `mutable` 返回的动态长度的tuple或者list被作为网络的输入并且这个网络被重复调用，即使每一次的输入的tuple或者list长度都不一致，这个网络也不需要被重新编译。

    参数：
        - **input_data** (Union[Tensor, scalar, tuple, list, dict]) - 要设置为可变的输入数据。如果 `input_data` 是list、tuple或者dict，其内部元素的类型也需要是这些有效类型中的一个。
        - **dynamic_len** (bool，可选) - 是否要将整个序列设置为动态长度的。在图编译内，如果 `dynamic_len` 被设置为 ``True`` ，那么 `input_data` 必须为tuple或者list，并且其中的元素必须有相同的类型以及shape。默认值： ``False`` 。

    .. warning::
        这是一个实验性API，后续可能修改或删除。
        `dynamic_len` 是实验性质的参数，暂不支持 `dynamic_len` 为 ``True`` 。

    .. note::
        当前该接口只在图模式下生效。

    返回：
        状态设置为可变的原输入数据。

    异常：
        - **TypeError** - 如果 `input_data` 不是Tensor、scalar、tuple、list 或dict中的任一种类型或者不是它们的嵌套结构。
        - **TypeError** - 如果 `dynamic_len` 被设置为 ``True`` 并且 `input_data` 不是tuple或者list。
        - **ValueError** - 如果 `dynamic_len` 被设置为 ``True`` ， `input_data` 是tuple或者list的情况下，其中的元素的shape或者类型不一致。