m53297601
/
mindspore
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

!4006 Second round of the enhancement of API comments

Browse Source 
Merge pull request !4006 from Simson/enhancement-API
pull/4006/MERGE
mindspore-ci-bot 5 years ago committed by Gitee
parent 40ff2fbabf a346a1b2b4
commit 76668bef16
8 changed files with 82 additions and 79 deletions
Show Stats Download Patch File Download Diff File

19
mindspore/common/api.py
Unescape View File

@ -206,23 +206,24 @@ class _MindSporeFunction:
def ms_function(fn=None, obj=None, input_signature=None):
"""
Creates a callable MindSpore graph from a python function.
Create a callable MindSpore graph from a python function.
This allows the MindSpore runtime to apply optimizations based on graph.
Args:
fn (Function): The Python function that will be run as a graph. Default: None.
obj (Object): The Python Object that provide information for identify compiled function. Default: None.
input_signature (MetaTensor): The MetaTensor to describe the input arguments. The MetaTensor specifies
obj (Object): The Python Object that provides the information for identifying the compiled function.Default:
None.
input_signature (MetaTensor): The MetaTensor which describes the input arguments. The MetaTensor specifies
the shape and dtype of the Tensor and they will be supplied to this function. If input_signature
is specified, every input to `fn` must be a `Tensor`. And the input parameters of `fn` cannot accept
`**kwargs`. The shape and dtype of actual inputs should keep same with input_signature, or TypeError
will be raised. Default: None.
is specified, each input to `fn` must be a `Tensor`. And the input parameters of `fn` cannot accept
`**kwargs`. The shape and dtype of actual inputs should keep the same as input_signature. Otherwise,
TypeError will be raised. Default: None.
Returns:
Function, if `fn` is not None, returns a callable that will execute the compiled function; If `fn` is None,
returns a decorator and when this decorator invokes with a single `fn` argument, the callable is equal to the
case when `fn` is not None.
Function, if `fn` is not None, returns a callable function that will execute the compiled function; If `fn` is
None, returns a decorator and when this decorator invokes with a single `fn` argument, the callable function is
equal to the case when `fn` is not None.
Examples:
>>> def tensor_add(x, y):

6
mindspore/common/dtype.py
Unescape View File

@ -166,7 +166,7 @@ def pytype_to_dtype(obj):
def get_py_obj_dtype(obj):
"""
Get the corresponding MindSpore data type by python type or variable.
Get the MindSpore data type which corresponds to python type or variable.
Args:
obj: An object of python type, or a variable in python type.
@ -186,7 +186,7 @@ def get_py_obj_dtype(obj):
def dtype_to_nptype(type_):
"""
Get numpy data type corresponding to MindSpore dtype.
Convert MindSpore dtype to numpy data type.
Args:
type_ (:class:`mindspore.dtype`): MindSpore's dtype.
@ -213,7 +213,7 @@ def dtype_to_nptype(type_):
def dtype_to_pytype(type_):
"""
Get python type corresponding to MindSpore dtype.
Convert MindSpore dtype to python data type.
Args:
type_ (:class:`mindspore.dtype`): MindSpore's dtype.

12
mindspore/common/parameter.py
Unescape View File

@ -53,7 +53,7 @@ class Parameter(MetaTensor):
name (str): Name of the child parameter.
requires_grad (bool): True if the parameter requires gradient. Default: True.
layerwise_parallel (bool): A kind of model parallel mode. When layerwise_parallel is true in paralle mode,
broadcast and gradients communication would not be applied on parameters. Default: False.
broadcast and gradients communication would not be applied to parameters. Default: False.
"""
__base_type__ = {}
@ -196,7 +196,7 @@ class Parameter(MetaTensor):
@property
def is_init(self):
"""Get init status of the parameter."""
"""Get the initialization status of the parameter."""
return self._is_init
@is_init.setter
@ -322,7 +322,7 @@ class Parameter(MetaTensor):
def init_data(self, layout=None, set_sliced=False):
"""
Init data of the parameter.
Initialize the parameter data.
Args:
layout (list[list[int]]): Parameter slice layout [dev_mat, tensor_map, slice_shape].
@ -330,11 +330,11 @@ class Parameter(MetaTensor):
- dev_mat (list[int]): Device matrix.
- tensor_map (list[int]): Tensor map.
- slice_shape (list[int]): Shape of slice.
set_sliced (bool): True if should set parameter sliced after init the data of initializer.
set_sliced (bool): True if the parameter is set sliced after initializing the data.
Default: False.
Returns:
Parameter, the `Parameter` after init data. If current `Parameter` already initialized before,
Parameter, the `Parameter` after initializing data. If current `Parameter` was already initialized before,
returns the same initialized `Parameter`.
"""
if self.init_mode is None:
@ -371,7 +371,7 @@ class ParameterTuple(tuple):
Class for storing tuple of parameters.
Note:
Used to store the parameters of the network into the parameter tuple collection.
It is used to store the parameters of the network into the parameter tuple collection.
"""
def __new__(cls, iterable):
"""Create instance object of ParameterTuple."""

24
mindspore/common/tensor.py
Unescape View File

@ -29,14 +29,14 @@ np_types = (np.int8, np.int16, np.int32, np.int64,
class Tensor(Tensor_):
"""
Tensor for data storage.
Tensor is used for data storage.
Tensor inherits tensor object in C++ side, some functions are implemented
in C++ side and some functions are implemented in Python layer.
Tensor inherits tensor object in C++.
Some functions are implemented in C++ and some functions are implemented in Python.
Args:
input_data (Tensor, float, int, bool, tuple, list, numpy.ndarray): Input data of the tensor.
dtype (:class:`mindspore.dtype`): Should be None, bool or numeric type defined in `mindspore.dtype`.
dtype (:class:`mindspore.dtype`): Input data should be None, bool or numeric type defined in `mindspore.dtype`.
The argument is used to define the data type of the output tensor. If it is None, the data type of the
output tensor will be as same as the `input_data`. Default: None.
@ -44,13 +44,13 @@ class Tensor(Tensor_):
Tensor, with the same shape as `input_data`.
Examples:
>>> # init a tensor with input data
>>> # initialize a tensor with input data
>>> t1 = Tensor(np.zeros([1, 2, 3]), mindspore.float32)
>>> assert isinstance(t1, Tensor)
>>> assert t1.shape == (1, 2, 3)
>>> assert t1.dtype == mindspore.float32
>>>
>>> # init a tensor with a float scalar
>>> # initialize a tensor with a float scalar
>>> t2 = Tensor(0.1)
>>> assert isinstance(t2, Tensor)
>>> assert t2.dtype == mindspore.float64
@ -280,18 +280,18 @@ class IndexedSlices:
The dense tensor dense represented by an IndexedSlices slices has
`dense[slices.indices[i], :, :, :, ...] = slices.values[i, :, :, :, ...]`.
IndexedSlices can only be used in `Cell`'s contruct method.
IndexedSlices can only be used in the `Cell`'s construct method.
Pynative mode not supported at the moment.
It is not supported in pynative mode at the moment.
Args:
indices (Tensor): A 1-D integer Tensor of shape [D0].
values (Tensor): A Tensor of any dtype of shape [D0, D1, ..., Dn].
dense_shape (tuple): A integer tuple containing the shape
dense_shape (tuple): An integer tuple which contains the shape
of the corresponding dense tensor.
Returns:
IndexedSlices, composed of `indices`, `values`, `dense_shape`.
IndexedSlices, composed of `indices`, `values`, and `dense_shape`.
Examples:
>>> class Net(nn.Cell):
@ -327,7 +327,7 @@ class SparseTensor:
"""
A sparse representation of a set of nonzero elememts from a tensor at given indices.
SparseTensor can only be used in `Cell`'s contruct method.
SparseTensor can only be used in the `Cell`'s construct method.
Pynative mode not supported at the moment.
@ -344,7 +344,7 @@ class SparseTensor:
which specifies the dense_shape of the sparse tensor.
Returns:
SparseTensor, composed of `indices`, `values`, `dense_shape`.
SparseTensor, composed of `indices`, `values`, and `dense_shape`.
Examples:
>>> class Net(nn.Cell):

2
mindspore/nn/optim/optimizer.py
Unescape View File

@ -220,7 +220,7 @@ class Optimizer(Cell):
"""Check weight decay, and convert int to float."""
if isinstance(weight_decay, (float, int)):
weight_decay = float(weight_decay)
validator.check_number_range("weight_decay", weight_decay, 0.0, 1.0, Rel.INC_BOTH, self.cls_name)
validator.check_number_range("weight_decay", weight_decay, 0.0, float("inf"), Rel.INC_LEFT, self.cls_name)
return weight_decay
raise TypeError("Weight decay should be int or float.")

4
mindspore/ops/primitive.py
Unescape View File

@ -364,8 +364,8 @@ def prim_attr_register(fn):
def constexpr(fn=None, get_instance=True, name=None):
"""
Makes a PrimitiveWithInfer operator that can infer the value at compile time. We can define a function
to compute between constant variable and used in constructß.
Make a PrimitiveWithInfer operator that can infer the value at compile time. We can use it to define a function to
compute constant value using the constants in the constructor.
Args:
fn (function): A `fn` use as the infer_value of the output operator.

17
mindspore/train/dataset_helper.py
Unescape View File

@ -39,19 +39,20 @@ def _send_data_no_flag(dataset, epoch_num):
class DatasetHelper:
"""
Help function to use the Minddata dataset.
Help function to use the MindData dataset.
According to different context, change the iter of dataset, to use the same for loop in different context.
According to different contexts, change the iterations of dataset and use the same iteration for loop in different
contexts.
Note:
The iter of DatasetHelper will give one epoch data.
The iteration of DatasetHelper will provide one epoch data.
Args:
dataset (DataSet): The training dataset iterator.
dataset_sink_mode (bool): If true use GetNext to fetch the data, or else feed the data from host. Default: True.
sink_size (int): Control the amount of data each sink.
If sink_size=-1, sink the complete dataset each epoch.
If sink_size>0, sink sink_size data each epoch. Default: -1.
sink_size (int): Control the amount of data in each sink.
If sink_size=-1, sink the complete dataset for each epoch.
If sink_size>0, sink sink_size data for each epoch. Default: -1.
epoch_num (int): Control the number of epoch data to send. Default: 1.
Examples:
@ -90,11 +91,11 @@ class DatasetHelper:
# A temp solution for loop sink. Delete later
def types_shapes(self):
"""Get the types and shapes from dataset on current config."""
"""Get the types and shapes from dataset on the current configuration."""
return self.iter.types_shapes()
def sink_size(self):
"""Get sink_size for every iteration."""
"""Get sink_size for each iteration."""
return self.iter.get_sink_size()
def stop_send(self):

77
mindspore/train/model.py
Unescape View File

@ -45,20 +45,20 @@ class Model:
`Model` groups layers into an object with training and inference features.
Args:
network (Cell): The training or testing network.
network (Cell): A training or testing network.
loss_fn (Cell): Objective function, if loss_fn is None, the
network should contain the logic of loss and grads calculation, and the logic
of parallel if needed. Default: None.
optimizer (Cell): Optimizer for updating the weights. Default: None.
metrics (Union[dict, set]): Dict or set of metrics to be evaluated by the model during
metrics (Union[dict, set]): A Dictionary or a set of metrics to be evaluated by the model during
training and testing. eg: {'accuracy', 'recall'}. Default: None.
eval_network (Cell): Network for evaluation. If not defined, `network` and `loss_fn` would be wrapped as
`eval_network`. Default: None.
eval_indexes (list): In case of defining the `eval_network`, if `eval_indexes` is None, all outputs of
eval_indexes (list): When defining the `eval_network`, if `eval_indexes` is None, all outputs of the
`eval_network` would be passed to metrics, otherwise `eval_indexes` must contain three
elements, representing the positions of loss value, predict value and label, the loss
value would be passed to `Loss` metric, predict value and label would be passed to other
metric. Default: None.
elements, including the positions of loss value, predicted value and label. The loss
value would be passed to the `Loss` metric, the predicted value and label would be passed
to other metric. Default: None.
amp_level (str): Option for argument `level` in `mindspore.amp.build_train_network`, level for mixed
precision training. Supports [O0, O2, O3]. Default: "O0".
@ -68,10 +68,11 @@ class Model:
O2 is recommended on GPU, O3 is recommended on Ascend.
loss_scale_manager (Union[None, LossScaleManager]): If None, not scale the loss, or else
scale the loss by LossScaleManager. If it is set, overwrite the level setting. It's a eyword argument.
loss_scale_manager (Union[None, LossScaleManager]): If it is None, the loss would not be scaled. Otherwise,
scale the loss by LossScaleManager. It is a key argument.
e.g. Use `loss_scale_manager=None` to set the value.
keep_batchnorm_fp32 (bool): Keep Batchnorm run in `float32`. If set, overwrite the level setting. Default: True.
keep_batchnorm_fp32 (bool): Keep Batchnorm running in `float32`. If it is set to true, the level setting before
will be overwritten. Default: True.
Examples:
>>> class Net(nn.Cell):
@ -255,16 +256,16 @@ class Model:
def init(self, train_dataset=None, valid_dataset=None):
"""
Initializes compute graphs and data graphs with sink mode.
Initialize compute graphs and data graphs with the sink mode.
Note:
Pre-init process only supports `GRAPH_MODE` and `Ascend` target currently.
Args:
train_dataset (Dataset): A training dataset iterator. If define `train_dataset`, training graphs will be
train_dataset (Dataset): A training dataset iterator. If `train_dataset` is defined, training graphs will be
initialized. Default: None.
valid_dataset (Dataset): A evaluating dataset iterator. If define `valid_dataset`, evaluation graphs will
be initialized, and `metrics` in `Model` can not be None. Default: None.
valid_dataset (Dataset): A evaluating dataset iterator. If `valid_dataset` is defined, evaluation graphs
will be initialized, and `metrics` in `Model` can not be None. Default: None.
Examples:
>>> train_dataset = get_train_dataset()
@ -327,15 +328,16 @@ class Model:
Args:
epoch (int): Total number of iterations on the data.
train_dataset (Dataset): A training dataset iterator. If there is no
loss_fn, a tuple with multiply data (data1, data2, data3, ...) will be
loss_fn, a tuple with multiple data (data1, data2, data3, ...) will be
returned and passed to the network. Otherwise, a tuple (data, label) will
be returned, and the data and label are passed to the network and loss
be returned. The data and label would be passed to the network and loss
function respectively.
callbacks (list): List of callback object. Callbacks which should be executed while training. Default: None.
dataset_sink_mode (bool): Determines whether to pass the data through dataset channel. Default: True.
callbacks (list): List of callback objects which should be executed while training. Default: None.
dataset_sink_mode (bool): Determine whether the data should be passed through the dataset channel.
Default: True.
Configure pynative mode, the training process will be performed with
dataset not sink.
sink_size (int): Control the amount of data each sink. Default: -1.
sink_size (int): Control the amount of data in each sink. Default: -1.
"""
epoch = check_int_positive(epoch)
self._train_network.set_train()
@ -392,13 +394,13 @@ class Model:
Args:
epoch (int): Total number of iterations on the data.
train_dataset (Dataset): A training dataset iterator. If there is no
loss_fn, a tuple with multiply data (data1, data2, data3, ...) should be
loss_fn, a tuple with multiple data (data1, data2, data3, ...) should be
returned and passed to the network. Otherwise, a tuple (data, label) should
be returned, and the data and label are passed to the network and loss
be returned. The data and label would be passed to the network and loss
function respectively.
list_callback (Callback): Executor of callback list. Default: None.
cb_params (_InternalCallbackParam): Callback parameters. Default: None.
sink_size (int): Control the amount of data each sink. Default: -1.
sink_size (int): Control the amount of data in each sink. Default: -1.
"""
if sink_size == -1:
epoch_num = epoch
@ -450,9 +452,9 @@ class Model:
Args:
epoch (int): Total number of iterations on the data.
train_dataset (Dataset): A training dataset iterator. If there is no
loss_fn, a tuple with multiply data (data1, data2, data3, ...) should be
loss_fn, a tuple with multiple data (data1, data2, data3, ...) should be
returned and passed to the network. Otherwise, a tuple (data, label) should
be returned, and the data and label are passed to the network and loss
be returned. The data and label would be passed to the network and loss
function respectively.
list_callback (Callback): Executor of callback list. Default: None.
cb_params (_InternalCallbackParam): Callback parameters. Default: None.
@ -518,7 +520,7 @@ class Model:
CPU is not supported when dataset_sink_mode is true.
If dataset_sink_mode is True, epoch of training should be equal to the count of repeat
operation in dataset processing. Otherwise, errors could occur since the amount of data
is not the amount training requires.
is not equal to the required amount of training .
If dataset_sink_mode is True, data will be sent to device. If device is Ascend, features
of data will be transferred one by one. The limitation of data transmission per time is 256M.
@ -527,18 +529,18 @@ class Model:
When dataset_sink_mode is set to true and sink_size>0, each epoch sink sink_size
steps on the data instead of total number of iterations.
train_dataset (Dataset): A training dataset iterator. If there is no
loss_fn, a tuple with multiply data (data1, data2, data3, ...) should be
loss_fn, a tuple with multiple data (data1, data2, data3, ...) should be
returned and passed to the network. Otherwise, a tuple (data, label) should
be returned, and the data and label are passed to the network and loss
be returned. The data and label would be passed to the network and loss
function respectively.
callbacks (list): List of callback object. Callbacks which should be excuted while training. Default: None.
callbacks (list): List of callback objects which should be executed while training. Default: None.
dataset_sink_mode (bool): Determines whether to pass the data through dataset channel. Default: True.
Configure pynative mode, the training process will be performed with
dataset not sink.
sink_size (int): Control the amount of data each sink.
If sink_size=-1, sink the complete dataset each epoch.
If sink_size>0, sink sink_size data each epoch.
If dataset_sink_mode is False, set sink_size invalid. Default: -1.
sink_size (int): Control the amount of data in each sink.
If sink_size=-1, sink the complete dataset for each epoch.
If sink_size>0, sink sink_size data for each epoch.
If dataset_sink_mode is False, set sink_size as invalid. Default: -1.
Examples:
>>> dataset = get_dataset()
@ -573,7 +575,7 @@ class Model:
cb_params (_InternalCallbackParam): Callback parameters. Default: None.
Returns:
Dict, returns the loss value & metrics values for the model in test mode.
Dict, which returns the loss value and metrics values for the model in the test mode.
"""
run_context = RunContext(cb_params)
@ -612,7 +614,7 @@ class Model:
cb_params (_InternalCallbackParam): Callback parameters. Default: None.
Returns:
Dict, returns the loss value & metrics values for the model in test mode.
Dict, which returns the loss value and metrics values for the model in the test mode.
"""
run_context = RunContext(cb_params)
list_callback.begin(run_context)
@ -650,12 +652,11 @@ class Model:
Args:
valid_dataset (Dataset): Dataset to evaluate the model.
callbacks (list): List of callback object. Callbacks which should be excuted
while training. Default: None.
callbacks (list): List of callback objects which should be executed while training. Default: None.
dataset_sink_mode (bool): Determines whether to pass the data through dataset channel. Default: True.
Returns:
Dict, returns the loss value & metrics values for the model in test mode.
Dict, which returns the loss value and metrics values for the model in the test mode.
Examples:
>>> dataset = get_dataset()
@ -690,9 +691,9 @@ class Model:
def predict(self, *predict_data):
"""
Generates output predictions for the input samples.
Generate output predictions for the input samples.
Data could be single tensor, or list of tensor, tuple of tensor.
Data could be a single tensor, a list of tensor, or a tuple of tensor.
Note:
Batch data should be put together in one tensor.

Write Preview
Loading…
Cancel
Save