mindspore 2.0.0rc1__cp38-none-any.whl → 2.2.0__cp38-none-any.whl

mindspore/dataset/vision/utils.py

@@ -23,7 +23,8 @@ from PIL import Image
 import mindspore
 import mindspore._c_dataengine as cde
 
-if Image.__version__ >= "9.1.0":
+# The following constants have been deprecated by Pillow since version 9.1.0
+if int(Image.__version__.split(".")[0]) > 9 or Image.__version__ >= "9.1.0":
     FLIP_LEFT_RIGHT = Image.Transpose.FLIP_LEFT_RIGHT
     FLIP_TOP_BOTTOM = Image.Transpose.FLIP_TOP_BOTTOM
     PERSPECTIVE = Image.Transform.PERSPECTIVE
@@ -47,14 +48,14 @@ class AutoAugmentPolicy(str, Enum):
     """
     AutoAugment policy for different datasets.
 
-    Possible enumeration values are: AutoAugmentPolicy.IMAGENET, AutoAugmentPolicy.CIFAR10,
+    Possible enumeration values are: ``AutoAugmentPolicy.IMAGENET``, ``AutoAugmentPolicy.CIFAR10``,
     AutoAugmentPolicy.SVHN.
 
     Each policy contains 25 pairs of augmentation operations. When using AutoAugment, each image is randomly
     transformed with one of these operation pairs. Each pair has 2 different operations. The following shows
     all of these augmentation operations, including operation names with their probabilities and random params.
 
-    - AutoAugmentPolicy.IMAGENET: dataset auto augment policy for ImageNet.
+    - ``AutoAugmentPolicy.IMAGENET``: dataset auto augment policy for ImageNet.
 
       .. code-block::
 
@@ -73,7 +74,7 @@ class AutoAugmentPolicy(str, Enum):
            (("Invert", 0.6, None), ("Equalize", 1.0, None)),   (("Color", 0.6, 4), ("Contrast", 1.0, 8)),
            (("Equalize", 0.8, None), ("Equalize", 0.6, None))]
 
-    - AutoAugmentPolicy.CIFAR10: dataset auto augment policy for Cifar10.
+    - ``AutoAugmentPolicy.CIFAR10``: dataset auto augment policy for Cifar10.
 
       .. code-block::
 
@@ -94,7 +95,7 @@ class AutoAugmentPolicy(str, Enum):
            (("Equalize", 0.3, None), ("AutoContrast", 0.4, None)),
            (("Equalize", 0.2, None), ("AutoContrast", 0.6, None))]
 
-    - AutoAugmentPolicy.SVHN: dataset auto augment policy for SVHN.
+    - ``AutoAugmentPolicy.SVHN``: dataset auto augment policy for SVHN.
 
       .. code-block::
 
@@ -133,13 +134,13 @@ class Border(str, Enum):
     """
     Padding Mode, Border Type.
 
-    Possible enumeration values are: Border.CONSTANT, Border.EDGE, Border.REFLECT, Border.SYMMETRIC.
+    Possible enumeration values are: ``Border.CONSTANT``, ``Border.EDGE``, ``Border.REFLECT``, ``Border.SYMMETRIC``.
 
-    - Border.CONSTANT: means it fills the border with constant values.
-    - Border.EDGE: means it pads with the last value on the edge.
-    - Border.REFLECT: means it reflects the values on the edge omitting the last value of edge.
+    - ``Border.CONSTANT`` : means it fills the border with constant values.
+    - ``Border.EDGE`` : means it pads with the last value on the edge.
+    - ``Border.REFLECT`` : means it reflects the values on the edge omitting the last value of edge.
       For example, padding [1,2,3,4] with 2 elements on both sides will result in [3,2,1,2,3,4,3,2].
-    - Border.SYMMETRIC: means it reflects the values on the edge repeating the last value of edge.
+    - ``Border.SYMMETRIC`` : means it reflects the values on the edge repeating the last value of edge.
       For example, padding [1,2,3,4] with 2 elements on both sides will result in [2,1,1,2,3,4,4,3].
 
     Note:
@@ -256,10 +257,10 @@ class ImageBatchFormat(IntEnum):
     """
     Data Format of images after batch operation.
 
-    Possible enumeration values are: ImageBatchFormat.NHWC, ImageBatchFormat.NCHW.
+    Possible enumeration values are: ``ImageBatchFormat.NHWC``, ``ImageBatchFormat.NCHW``.
 
-    - ImageBatchFormat.NHWC: in orders like, batch N, height H, width W, channels C to store the data.
-    - ImageBatchFormat.NCHW: in orders like, batch N, channels C, height H, width W to store the data.
+    - ``ImageBatchFormat.NHWC``: in orders like, batch N, height H, width W, channels C to store the data.
+    - ``ImageBatchFormat.NCHW``: in orders like, batch N, channels C, height H, width W to store the data.
     """
     NHWC = 0
     NCHW = 1
@@ -279,11 +280,11 @@ class ImageReadMode(IntEnum):
     """
     The read mode used for the image file.
 
-    Possible enumeration values are: ImageReadMode.UNCHANGED, ImageReadMode.GRAYSCALE, ImageReadMode.COLOR.
+    Possible enumeration values are: ``ImageReadMode.UNCHANGED``, ``ImageReadMode.GRAYSCALE``, ``ImageReadMode.COLOR``.
 
-    - ImageReadMode.UNCHANGED: remain the output in the original format.
-    - ImageReadMode.GRAYSCALE: convert the output into one channel grayscale data.
-    - ImageReadMode.COLOR: convert the output into three channels RGB color data.
+    - ``ImageReadMode.UNCHANGED``: remain the output in the original format.
+    - ``ImageReadMode.GRAYSCALE``: convert the output into one channel grayscale data.
+    - ``ImageReadMode.COLOR``: convert the output into three channels RGB color data.
     """
     UNCHANGED = 0
     GRAYSCALE = 1
@@ -302,20 +303,19 @@ class ImageReadMode(IntEnum):
 
 class Inter(IntEnum):
     """
-    Interpolation Modes.
+    Interpolation methods.
 
-    Possible enumeration values are: Inter.NEAREST, Inter.ANTIALIAS, Inter.LINEAR, Inter.BILINEAR, Inter.CUBIC,
-    Inter.BICUBIC, Inter.AREA, Inter.PILCUBIC.
+    Available values are as follows:
 
-    - Inter.NEAREST: means interpolation method is nearest-neighbor interpolation.
-    - Inter.ANTIALIAS: means the interpolation method is antialias interpolation.
-    - Inter.LINEAR: means interpolation method is bilinear interpolation, here is the same as Inter.BILINEAR.
-    - Inter.BILINEAR: means interpolation method is bilinear interpolation.
-    - Inter.CUBIC: means the interpolation method is bicubic interpolation, here is the same as Inter.BICUBIC.
-    - Inter.BICUBIC: means the interpolation method is bicubic interpolation.
-    - Inter.AREA: means interpolation method is pixel area interpolation.
-    - Inter.PILCUBIC: means interpolation method is bicubic interpolation like implemented in pillow, input
-      should be in 3 channels format.
+    - ``Inter.NEAREST`` : Nearest neighbor interpolation.
+    - ``Inter.ANTIALIAS`` : Antialias interpolation. Supported only when the input is PIL.Image.Image.
+    - ``Inter.LINEAR`` : Linear interpolation, the same as ``Inter.BILINEAR``.
+    - ``Inter.BILINEAR`` : Bilinear interpolation.
+    - ``Inter.CUBIC`` : Cubic interpolation, the same as ``Inter.BICUBIC``.
+    - ``Inter.BICUBIC`` : Bicubic interpolation.
+    - ``Inter.AREA`` : Pixel area interpolation. Supported only when the input is numpy.ndarray.
+    - ``Inter.PILCUBIC`` : Pillow implementation of bicubic interpolation. Supported only when the input
+      is numpy.ndarray.
     """
     NEAREST = 0
     ANTIALIAS = 1
@@ -354,10 +354,10 @@ class SliceMode(IntEnum):
     """
     Mode to Slice Tensor into multiple parts.
 
-    Possible enumeration values are: SliceMode.PAD, SliceMode.DROP.
+    Possible enumeration values are: ``SliceMode.PAD``, ``SliceMode.DROP``.
 
-    - SliceMode.PAD: pad some pixels before slice the Tensor if needed.
-    - SliceMode.DROP: drop remainder pixels before slice the Tensor if needed.
+    - ``SliceMode.PAD``: pad some pixels before slice the Tensor if needed.
+    - ``SliceMode.DROP``: drop remainder pixels before slice the Tensor if needed.
     """
     PAD = 0
     DROP = 1
@@ -379,7 +379,7 @@ def encode_jpeg(image, quality=75):
 
     Args:
         image (Union[numpy.ndarray, mindspore.Tensor]): The image to be encoded.
-        quality (int, optional): Quality of the resulting JPEG data, in range of [1, 100]. Default: 75.
+        quality (int, optional): Quality of the resulting JPEG data, in range of [1, 100]. Default: ``75``.
 
     Returns:
         numpy.ndarray, one dimension uint8 data.
@@ -395,6 +395,7 @@ def encode_jpeg(image, quality=75):
         ``CPU``
 
     Examples:
+        >>> import mindspore.dataset.vision as vision
         >>> import numpy as np
         >>> # Generate a random image with height=120, width=340, channels=3
         >>> image = np.random.randint(256, size=(120, 340, 3), dtype=np.uint8)
@@ -416,7 +417,8 @@ def encode_png(image, compression_level=6):
 
     Args:
         image (Union[numpy.ndarray, mindspore.Tensor]): The image to be encoded.
-        compression_level (int, optional): The compression_level for encoding, in range of [0, 9]. Default: 6.
+        compression_level (int, optional): The `compression_level` for encoding, in range of [0, 9].
+            Default: ``6``.
 
     Returns:
         numpy.ndarray, one dimension uint8 data.
@@ -432,6 +434,7 @@ def encode_png(image, compression_level=6):
         ``CPU``
 
     Examples:
+        >>> import mindspore.dataset.vision as vision
         >>> import numpy as np
         >>> # Generate a random image with height=120, width=340, channels=3
         >>> image = np.random.randint(256, size=(120, 340, 3), dtype=np.uint8)
@@ -463,6 +466,9 @@ def get_image_num_channels(image):
         TypeError: If `image` is not of type <class 'numpy.ndarray'> or <class 'PIL.Image.Image'>.
 
     Examples:
+        >>> import mindspore.dataset.vision as vision
+        >>> from PIL import Image
+        >>> image = Image.open("/path/to/image_file")
         >>> num_channels = vision.get_image_num_channels(image)
     """
 
@@ -493,6 +499,9 @@ def get_image_size(image):
         TypeError: If `image` is not of type <class 'numpy.ndarray'> or <class 'PIL.Image.Image'>.
 
     Examples:
+        >>> import mindspore.dataset.vision as vision
+        >>> from PIL import Image
+        >>> image = Image.open("/path/to/image_file")
         >>> image_size = vision.get_image_size(image)
     """
 
@@ -538,6 +547,7 @@ def read_file(filename):
         ``CPU``
 
     Examples:
+        >>> import mindspore.dataset.vision as vision
         >>> output = vision.read_file("/path/to/file")
     """
     if isinstance(filename, str):
@@ -552,8 +562,9 @@ def read_image(filename, mode=ImageReadMode.UNCHANGED):
 
     Args:
         filename(str): The path to the image file to be read.
-        mode(ImageReadMode, optional): The mode used for decoding the image. It can be any of
-            [ImageReadMode.UNCHANGED, ImageReadMode.GRAYSCALE, IMageReadMode.COLOR]. Default: ImageReadMode.UNCHANGED.
+        mode(ImageReadMode, optional): The mode used for decoding the image. It can be
+            ``ImageReadMode.UNCHANGED``, ``ImageReadMode.GRAYSCALE``, ``IMageReadMode.COLOR``.
+            Default: ``ImageReadMode.UNCHANGED``.
 
             - ImageReadMode.UNCHANGED, remain the output in the original format.
 
@@ -573,6 +584,7 @@ def read_image(filename, mode=ImageReadMode.UNCHANGED):
         ``CPU``
 
     Examples:
+        >>> import mindspore.dataset.vision as vision
         >>> from mindspore.dataset.vision import ImageReadMode
         >>> output = vision.read_image("/path/to/image_file", ImageReadMode.UNCHANGED)
     """
@@ -602,6 +614,7 @@ def write_file(filename, data):
         ``CPU``
 
     Examples:
+        >>> import mindspore.dataset.vision as vision
         >>> import numpy as np
         >>> # Generate a random data with 1024 bytes
         >>> data = np.random.randint(256, size=(1024), dtype=np.uint8)
@@ -624,7 +637,7 @@ def write_jpeg(filename, image, quality=75):
     Args:
         filename (str): The path to the file to be written.
         image (Union[numpy.ndarray, mindspore.Tensor]): The image data to be written.
-        quality (int, optional): Quality of the resulting JPEG file, in range of [1, 100]. Default: 75.
+        quality (int, optional): Quality of the resulting JPEG file, in range of [1, 100]. Default: ``75``.
 
     Raises:
         TypeError: If `filename` is not of type str.
@@ -639,6 +652,7 @@ def write_jpeg(filename, image, quality=75):
         ``CPU``
 
     Examples:
+        >>> import mindspore.dataset.vision as vision
         >>> import numpy as np
         >>> # Generate a random image with height=120, width=340, channels=3
         >>> image = np.random.randint(256, size=(120, 340, 3), dtype=np.uint8)
@@ -663,7 +677,8 @@ def write_png(filename, image, compression_level=6):
     Args:
         filename (str): The path to the file to be written.
         image (Union[numpy.ndarray, mindspore.Tensor]): The image data to be written.
-        compression_level (int, optional): Compression level for the resulting PNG file, in range of [0, 9]. Default: 6.
+        compression_level (int, optional): Compression level for the resulting PNG file, in range of [0, 9].
+            Default: ``6``.
 
     Raises:
         TypeError: If `filename` is not of type str.
@@ -678,6 +693,7 @@ def write_png(filename, image, compression_level=6):
         ``CPU``
 
     Examples:
+        >>> import mindspore.dataset.vision as vision
         >>> import numpy as np
         >>> # Generate a random image with height=120, width=340, channels=3
         >>> image = np.random.randint(256, size=(120, 340, 3), dtype=np.uint8)

mindspore/dataset/vision/validators.py

@@ -24,7 +24,7 @@ from mindspore.dataset.core.validator_helpers import check_value, check_uint8, F
     check_pos_float32, check_float32, check_2tuple, check_range, check_positive, INT32_MAX, INT32_MIN, \
     parse_user_args, type_check, type_check_list, check_c_tensor_op, UINT8_MAX, UINT8_MIN, check_value_normalize_std, \
     check_value_cutoff, check_value_ratio, check_odd, check_non_negative_float32, check_non_negative_int32, \
-    check_pos_int32, check_int32, check_tensor_op, deprecator_factory
+    check_pos_int32, check_int32, check_tensor_op, deprecator_factory, check_valid_str
 from mindspore.dataset.transforms.validators import check_transform_op_type
 from .utils import Inter, Border, ImageBatchFormat, ConvertMode, SliceMode, AutoAugmentPolicy
 
@@ -339,6 +339,16 @@ def check_resize_interpolation(method):
 
     return new_method
 
+def check_device_target(method):
+    """A wrapper that wraps a parameter checker"""
+
+    @wraps(method)
+    def new_method(self, *args, **kwargs):
+        [device_target], _ = parse_user_args(method, *args, **kwargs)
+        check_valid_str(device_target, ["CPU", "Ascend"], "device_target")
+        return method(self, *args, **kwargs)
+    return new_method
+
 
 def check_resized_crop(method):
     """A wrapper that wraps a parameter checker around the original function(ResizedCrop operation)."""
@@ -715,7 +725,7 @@ def check_pad_to_size(method):
             else:
                 if len(offset) not in [0, 2]:
                     raise ValueError("The offset must be empty or a sequence of length 2.")
-                for i, value in enumerate(offset):
+                for i, _ in enumerate(offset):
                     check_non_negative_int32(offset[i], "offset{0}".format(i))
 
         check_fill_value(fill_value)

mindspore/experimental/map_parameter.py

@@ -17,6 +17,7 @@ from __future__ import absolute_import
 
 __all__ = ['MapParameter']
 
+import os
 import sys
 from copy import copy
 import numbers
@@ -46,7 +47,7 @@ class MapParameter(Parameter):
         default_value (Union[numbers.Number, str]): The default value number or initializer name. Default: 'normal'.
         permit_filter_value (numbers.Number): The permit filter value number. Default: 1.
         evict_filter_value (numbers.Number): The evict filter value number. Default: MAX_SIZE.
-        name (str): Name of the map parameter. Default: None.
+        name (str): Name of the map parameter. Default: ``None``.
         requires_grad (bool): True if the parameter requires gradient. Default: True.
 
 
@@ -256,15 +257,28 @@ class MapParameter(Parameter):
 
         Args:
             incremental (bool): False for full export, otherwise for incremental export. Default: False.
-            When exporting data incrementally, the value_array does not contain erased data, so the length of the
-            key_array and the length of the value_array may be inconsistent.The length of the key_array and the length
-            of the status_array are consistent.
+            When exporting data incrementally, the value_array does not contain unchanged data.The length
+            of the key_array and the length of the status_array are consistent.
 
         Returns:
             Tuple(key_array, value_array, status_array), The exported data as a tuple.
         """
         return self._map_tensor.export_data(incremental)
 
+    def export_bytes(self, incremental=False):
+        """
+        Export bytes from this map parameter.
+
+        Args:
+            incremental (bool): False for full export, otherwise for incremental export. Default: False.
+            When exporting data incrementally, the value_array does not contain unchanged data. The length
+            of the key_array and the length of the status_array are consistent.
+
+        Returns:
+            Tuple(bytes, bytes, bytes), The exported bytes as a tuple.
+        """
+        return self._map_tensor.export_bytes(incremental)
+
     def import_data(self, data):
         """
         Import this map parameter from exported data.
@@ -273,3 +287,23 @@ class MapParameter(Parameter):
             data (Tuple): The data tuple with key_array, value_array and status_array.
         """
         self._map_tensor.import_data(data)
+
+    def export_slice_data(self, incremental=False):
+        """
+        Export a slice data from this map parameter.
+        When MapParameter occupies a large memory, only one slice
+        of MapParameter is exported at a time (the default slice size is 1GB).
+
+        Args:
+            incremental (bool): False for full export, otherwise for incremental export. Default: False.
+            When exporting data incrementally, the value_array does not contain unchanged data.The length
+            of the key_array and the length of the status_array are consistent.
+
+        Returns:
+            Tuple(key_array, value_array, status_array, last_slice), The exported data as a tuple, and
+            the last_slice is bool variable and means whether finish export.
+        """
+        enable_persistent = "MS_EMBEDDING_REMOTE_CACHE_MEMORY_SIZE" in os.environ
+        if not enable_persistent:
+            return self._map_tensor.export_slice_data(incremental)
+        return self._map_tensor.export_persistent_slice_data(self.key, incremental)

mindspore/{dataset/datapreprocess → experimental/optim}/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2019 Huawei Technologies Co., Ltd
+# Copyright 2023 Huawei Technologies Co., Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -11,10 +11,20 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# ==============================================================================
+# ============================================================================
+"""
+Optimizer.
 
-"""Preprocess of dataset.
+Provide common optimizers for training, such as SGD, ADAM, Momentum.
+The optimizer is used to calculate and update the gradients.
 """
 from __future__ import absolute_import
 
-from mindspore.dataset.datapreprocess.preprocess_imagenet_validate_dataset import *
+from mindspore.experimental.optim.optimizer import Optimizer
+from mindspore.experimental.optim.adamw import AdamW
+from mindspore.experimental.optim.sgd import SGD
+from mindspore.experimental.optim.adam import Adam
+from mindspore.experimental.optim import lr_scheduler
+
+
+__all__ = ['Optimizer', 'AdamW', 'SGD', 'Adam']

mindspore/experimental/optim/adam.py

@@ -0,0 +1,192 @@
+# Copyright 2023 Huawei Technologies Co., Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+"""adam"""
+from __future__ import absolute_import
+
+from mindspore.ops import functional as F, composite as C, operations as P
+from mindspore.common.parameter import Parameter
+from mindspore.common.tensor import Tensor
+import mindspore.common.dtype as mstype
+from mindspore.experimental.optim.optimizer import Optimizer
+
+_adam_opt = C.MultitypeFuncGraph("adam_opt")
+
+
+@_adam_opt.register("Function", "Tensor", "Tensor", "Float", "Float", "Float", "Tensor",
+                    "Tensor", "Tensor", "Tensor", "Tensor")
+def _run_adam_opt(opt, beta1_power, beta2_power, beta1, beta2, eps, lr, gradient, param, moment1, moment2):
+    """Apply adam optimizer to the weight parameter."""
+    success = True
+    success = F.depend(success, opt(param, moment1, moment2, beta1_power, beta2_power, lr, beta1, beta2, eps, gradient))
+    return success
+
+
+@_adam_opt.register("Function", "Tensor", "Tensor", "Tensor", "Tensor", "Tensor", "Tensor", "Tensor", "Tensor")
+def _run_adam_with_amsgrad_opt(opt, beta1_power, beta2_power, lr, gradient, param, moment1, moment2, vhat):
+    """Apply adam optimizer to the weight parameter with amsgrad."""
+    success = True
+    success = F.depend(success, opt(param, moment1, moment2, vhat, beta1_power, beta2_power, lr, gradient))
+    return success
+
+
+class Adam(Optimizer):
+    r"""
+    Implements Adam algorithm..
+
+    The updating formulas are as follows:
+
+    .. math::
+        \begin{aligned}
+            &\textbf{input}      : \gamma \text{ (lr)}, \beta_1, \beta_2
+                \text{ (betas)},\theta_0 \text{ (params)},f(\theta) \text{ (objective)}          \\
+            &\hspace{13mm}      \lambda \text{ (weight decay)},  \: \textit{amsgrad},
+                \:\textit{maximize}                                                              \\
+            &\textbf{initialize} :  m_0 \leftarrow 0 \text{ ( first moment)},
+                v_0\leftarrow 0 \text{ (second moment)},\: \widehat{v_0}^{max}\leftarrow 0\\[-1.ex]
+            &\textbf{for} \: t=1 \: \textbf{to} \: \ldots \: \textbf{do}                         \\
+            &\hspace{5mm}\textbf{if} \: \textit{maximize}:                                       \\
+            &\hspace{10mm}g_t           \leftarrow   -\nabla_{\theta} f_t (\theta_{t-1})         \\
+            &\hspace{5mm}\textbf{else}                                                           \\
+            &\hspace{10mm}g_t           \leftarrow   \nabla_{\theta} f_t (\theta_{t-1})          \\
+            &\hspace{5mm}\textbf{if} \: \lambda \neq 0                                           \\
+            &\hspace{10mm} g_t \leftarrow g_t + \lambda  \theta_{t-1}                            \\
+            &\hspace{5mm}m_t           \leftarrow   \beta_1 m_{t-1} + (1 - \beta_1) g_t          \\
+            &\hspace{5mm}v_t           \leftarrow   \beta_2 v_{t-1} + (1-\beta_2) g^2_t          \\
+            &\hspace{5mm}\widehat{m_t} \leftarrow   m_t/\big(1-\beta_1^t \big)                   \\
+            &\hspace{5mm}\widehat{v_t} \leftarrow   v_t/\big(1-\beta_2^t \big)                   \\
+            &\hspace{5mm}\textbf{if} \: amsgrad                                                  \\
+            &\hspace{10mm}\widehat{v_t}^{max} \leftarrow \mathrm{max}(\widehat{v_t}^{max},
+                \widehat{v_t})                                                                   \\
+            &\hspace{10mm}\theta_t \leftarrow \theta_{t-1} - \gamma \widehat{m_t}/
+                \big(\sqrt{\widehat{v_t}^{max}} + \epsilon \big)                                 \\
+            &\hspace{5mm}\textbf{else}                                                           \\
+            &\hspace{10mm}\theta_t \leftarrow \theta_{t-1} - \gamma \widehat{m_t}/
+                \big(\sqrt{\widehat{v_t}} + \epsilon \big)                                       \\
+            &\bf{return} \:  \theta_t                                                     \\[-1.ex]
+       \end{aligned}
+
+    .. warning::
+        This is an experimental optimizer API that is subject to change.
+        This module must be used with lr scheduler module in `LRScheduler Class
+        <https://www.mindspore.cn/docs/en/r2.2/api_python/mindspore.nn.html#learningrateschedule-class>`_ .
+
+    Args:
+        params (Union[list(Parameter), list(dict)]): list of parameters to optimize or dicts defining
+            parameter groups
+        lr (Union[int, float, Tensor], optional): learning rate. Default: ``1e-3``.
+        betas (Tuple[float, float], optional): The exponential decay rate for the moment estimations.
+            Default: ``(0.9, 0.999)``.
+        eps (float, optional): term added to the denominator to improve
+            numerical stability. Default: ``1e-8``.
+        weight_decay (float, optional): weight decay (L2 penalty). Default: ``0``.
+        amsgrad (bool, optional): whether to use the AMSGrad algorithm. Default: ``False``.
+
+    Keyword Args:
+        maximize (bool, optional): maximize the params based on the objective, instead of minimizing.
+            Default: ``False``.
+
+    Inputs:
+        - **gradients** (tuple[Tensor]) - The gradients of `params`.
+
+    Raises:
+        ValueError: If the `lr` is not int, float or Tensor.
+        ValueError: If the `lr` is less than 0.
+        ValueError: If the `eps` is less than 0.0.
+        ValueError: If the `betas` not in the range of 0-1.
+        ValueError: If the `weight_decay` is less than 0.
+
+    Supported Platforms:
+        ``Ascend`` ``GPU`` ``CPU``
+
+    Examples:
+        >>> import mindspore
+        >>> from mindspore import nn
+        >>> from mindspore.experimental import optim
+        >>> # Define the network structure of LeNet5. Refer to
+        >>> # https://gitee.com/mindspore/docs/blob/r2.2/docs/mindspore/code/lenet.py
+        >>> net = LeNet5()
+        >>> loss_fn = nn.SoftmaxCrossEntropyWithLogits(sparse=True)
+        >>> optimizer = optim.Adam(net.trainable_params(), lr=0.1)
+        >>> def forward_fn(data, label):
+        ...     logits = net(data)
+        ...     loss = loss_fn(logits, label)
+        ...     return loss, logits
+        >>> grad_fn = mindspore.value_and_grad(forward_fn, None, optimizer.parameters, has_aux=True)
+        >>> def train_step(data, label):
+        ...     (loss, _), grads = grad_fn(data, label)
+        ...     optimizer(grads)
+        ...     return loss
+    """
+    def __init__(self, params, lr=1e-3, betas=(0.9, 0.999), eps=1e-8,
+                 weight_decay=0, amsgrad=False, *, maximize=False):
+        if lr < 0.0:
+            raise ValueError("Invalid learning rate: {}".format(lr))
+        if eps < 0.0:
+            raise ValueError("Invalid epsilon value: {}".format(eps))
+        if not 0.0 <= betas[0] < 1.0:
+            raise ValueError("Invalid beta parameter at index 0: {}".format(betas[0]))
+        if not 0.0 <= betas[1] < 1.0:
+            raise ValueError("Invalid beta parameter at index 1: {}".format(betas[1]))
+        if weight_decay < 0.0:
+            raise ValueError("Invalid weight_decay value: {}".format(weight_decay))
+
+        defaults = dict(lr=lr, betas=betas, eps=eps,
+                        weight_decay=weight_decay, amsgrad=amsgrad,
+                        maximize=maximize)
+        super(Adam, self).__init__(params, defaults)
+
+        self.exp_avg = self.parameters.clone(prefix="exp_avg", init='zeros')
+        self.exp_avg_sq = self.parameters.clone(prefix="exp_avg_sq", init='zeros')
+        self.max_exp_avg_sq = self.parameters.clone(prefix="max_exp_avg_sq", init='zeros')
+        self.state_step = Parameter(Tensor(0, mstype.int32), "state_step")
+        self.increase_tensor = Tensor(1, mstype.int32)
+        self.assignadd = P.AssignAdd()
+        self.op_add = P.AddN()
+        self.op_mul = P.Mul()
+        self.op_pow = P.Pow()
+        self.adam_opt = P.Adam(False, False)
+        self.op_cast = P.Cast()
+
+    def construct(self, gradients):
+        self.assignadd(self.state_step, self.increase_tensor)
+        for group_id, group in enumerate(self.param_groups):
+            start_id = self.group_start_id[group_id]
+            end_id = self.group_start_id[group_id+1]
+
+            lr = group.get("lr")
+            weight_decay = group.get("weight_decay")
+            beta1, beta2 = group.get("betas")
+            maximize = group.get("maximize")
+            eps = group.get("eps")
+
+            beta1_power = self.op_pow(beta1, self.state_step)
+            beta2_power = self.op_pow(beta2, self.state_step)
+            adam_with_amsgrad_opt = P.ApplyAdamWithAmsgrad(beta1, beta2, eps, False)
+            params = self.parameters[start_id: end_id]
+            grads = gradients[start_id: end_id]
+            grads = grads if not maximize else -grads
+            grads = self._decay_weight(weight_decay, params, grads)
+            if isinstance(lr, float):
+                lr = self.op_cast(group.get("lr"), mstype.float32)
+            if group.get("amsgrad"):
+                self.hyper_map(F.partial(_adam_opt, adam_with_amsgrad_opt, beta1_power, beta2_power, lr),
+                               grads, params,
+                               self.exp_avg[start_id: end_id], self.exp_avg_sq[start_id: end_id],
+                               self.max_exp_avg_sq[start_id: end_id])
+            else:
+                self.hyper_map(F.partial(_adam_opt, self.adam_opt, beta1_power, beta2_power, beta1, beta2, eps, lr),
+                               grads, params,
+                               self.exp_avg[start_id: end_id], self.exp_avg_sq[start_id: end_id])
+        return True