robin978 commented 2 years ago

[x] 阅读 pytorch 的 API 文档，初步寻找其优点，总结出
[x] 参考 pytorch 源码，做一些试验。
[ ] 具体到每一个模块的细分和分类：
- [x] https://github.com/Oneflow-Inc/oneflow-documentation/issues/480
- [ ] https://github.com/Oneflow-Inc/oneflow-api-cn/pull/77 以及完成的文档重构（暂定6月15完成）
- [x] oneflow、nn、functional、tensor、autograd 五个模块的重构（6月9完成）https://github.com/Oneflow-Inc/oneflow/pull/8392/files
- [ ] 环境变量的嵌入工作 https://github.com/Oneflow-Inc/OneTeam/issues/654
- [ ] 使用 katex 替代 mathjax，以提高渲染速度 https://github.com/Oneflow-Inc/oneflow-api-cn/issues/74
- [ ] 大约5月中旬推进合并文档主题修改的工作 https://github.com/Oneflow-Inc/oneflow/pull/7989

doombeaker commented 2 years ago

目录分级、列出所有函数是基本的技术层次的东西（掌握 sphinx-build）。当然这个也需要了解，建议可以参照 torch 的文档源码，自己做试验，看如何达到这些效果：https://github.com/pytorch/pytorch/tree/master/docs/source

更重要的是，需要通过学习 PyTorch、OneFlow或者其它的资料，列出一个重构的”大纲“，规划以下的问题：

有那些一级、二级目录
以上分类好的一二级目录中，各放什么 API （现有的的 docstring）
在哪些地方，放 ”附上简单的介绍“，简单的介绍包含什么

这不是一个随便调研就可以整理好的事情，也不是一个特别困难的事情，需要的就是专注去逐渐深入了解 PyTorch 的文档、OneFlow 的文档。

robin978 commented 2 years ago

与 pytorch 的 API 文档相比较：

pytorch 中一级目录下还有二级目录，例：torch目录下将所有函数列出，并附上函数返回的内容或功能，每个函数的介绍是单独的页面。这样组织的好处在于方便用户寻找要使用的函数，不会使页面中的内容过于繁杂。

在每个一级目录下，按照函数的使用场景和函数类型将函数分类。例：torch目录中分为以下类别，更加清晰直观。

robin978 commented 2 years ago

oneflow.nn

将每一个 class 按功能划分： oneflow.nn.Parameter

robin978 commented 2 years ago

oneflow.optim

A package implementing various optimization algorithms. 可按照使用优化器的步骤对api进行分类。

How to use a optimizer

you have to construct an optimizer object, that will hold the current state and will update the parameters based on the computed gradients.

Base Class

oneflow.optim.Optimizer

Algorithms:

oneflow.optim.Adagrad , oneflow.optim.Adam , oneflow.optim.AdamW , oneflow.optim.LAMB , oneflow.optim.RMSprop , oneflow.optim.SGD

Adjust Learning Rate

oneflow.optim.lr_scheduler.CosineAnnealingLR , oneflow.optim.lr_scheduler.CosineDecayLR , oneflow.optim.lr_scheduler.ExponentialLR , oneflow.optim.lr_scheduler.LambdaLR , oneflow.optim.lr_scheduler.MultiStepLR , oneflow.optim.lr_scheduler.PolynomialLR , oneflow.optim.lr_scheduler.ReduceLROnPlateau , oneflow.optim.lr_scheduler.StepLR

robin978 commented 2 years ago

oneflow.nn.functional

Convolution functions:

oneflow.nn.functional.conv1d , oneflow.nn.functional.conv2d , oneflow.nn.functional.conv3d ,

Pooling functions:

oneflow.nn.functional.adaptive_avg_pool1d , oneflow.nn.functional.adaptive_avg_pool2d , oneflow.nn.functional.adaptive_avg_pool3d ,

Non-linear activation functions:

Linear functions:

oneflow.nn.functional.linear ,

Dropout functions:

oneflow.nn.functional.dropout

Sparse functions:

oneflow.nn.functional.embedding , oneflow.nn.functional.one_hot

Loss functions:

oneflow.nn.functional.sparse_softmax_cross_entropy , oneflow.nn.functional.cross_entropy , oneflow.nn.functional.triplet_margin_loss

Vision functions:

oneflow.nn.functional.pad , oneflow.nn.functional.interpolate , oneflow.nn.functional.upsample , oneflow.nn.functional.affine_grid , oneflow.nn.functional.grid_sample

robin978 commented 2 years ago

oneflow.Tensor

a multi-dimensional matrix containing elements of a single data type. 参考 pytorch 文档可以先介绍数据的类型，以及如何定义 tensor。

Initializing and basic operations

在此部分可以详细介绍如何定义 tensor 张量。在 oneflow 模块中有对 bool、float 等类型张量的定义，是否可以考虑罗列在此处。

Tensor class reference：

将相关的函数罗列在此部分。 oneflow.Tensor

robin978 commented 2 years ago

oneflow:

contains data structures for multi-dimensional tensors and defines mathematical operations over these tensors. Additionally, it provides many utilities for efficient serializing of Tensors and arbitrary types, and other useful utilities.

Tensors:

oneflow.is_tensor , oneflow.is_floating_point , oneflow.is_nonzero , oneflow.numel , oneflow.set_printoptions ,

Creation Ops:

oneflow.as_tensor , oneflow.as_strided , oneflow.from_numpy , oneflow.zeros , oneflow.zeros_like , oneflow.ones , oneflow.ones_like , oneflow.arange , oneflow.linspace , oneflow.eye , oneflow.empty , oneflow.full

Indexing, Slicing, Joining, Mutating Ops:

oneflow.argwhere , oneflow.cat , oneflow.concat , oneflow.chunk , oneflow.gather , oneflow.hsplit , oneflow.index_select , oneflow.masked_select , oneflow.movedim , oneflow.narrow , oneflow.nonzero , oneflow.permute , oneflow.reshape , oneflow.select , oneflow.scatter , oneflow.scatter_add , oneflow.scatter_nd , oneflow.split , oneflow.squeeze , oneflow.stack , oneflow.swapaxes , oneflow.swapdims , oneflow.t , oneflow.tensor_split , oneflow.tile , oneflow.transpose , oneflow.unbind , oneflow.unsqueeze , oneflow.vsplit , oneflow.where

Random Sampling:

oneflow.seed , oneflow.initial_seed , oneflow.manual_seed , oneflow.get_rng_state , oneflow.bernoulli , oneflow.rand , oneflow.randint , oneflow.randn , oneflow.randperm

Serialization:

oneflow.save , oneflow.load

Parallelism

oneflow.set_num_threads

Locally disabling gradient computation:

oneflow.no_grad , oneflow.grad_enable , oneflow.is_grad_enabled , oneflow.inference_mode

Math Operations:

Pointwise Ops:

oneflow.abs , oneflow.acos , oneflow.acosh , oneflow.arccos , oneflow.add , oneflow.asin , oneflow.asinh , oneflow.arcsin , oneflow.arcsinh , oneflow.atan ,oneflow.atanh , oneflow.arctan , oneflow.arctanh , oneflow.atan2 , oneflow.ceil , oneflow.clamp , oneflow.clip , oneflow.cos , oneflow.cosh , oneflow.div , oneflow.erf , oneflow.erfc , oneflow.erfin , oneflow.exp , oneflow.expm1 , oneflow.floor , oneflow.floor_ , oneflow.fmod , oneflow.log , oneflow.log1p , oneflow.log2 , oneflow.logical_and , oneflow.logical_not , oneflow.logical_or , oneflow.logical_slice , oneflow.logical_xor , oneflow.mul , oneflow.neg , oneflow.negative , oneflow.pow , oneflow.reciprocal , oneflow.round , oneflow.rsqrt , oneflow.sigmoid , oneflow.sign , oneflow.sin , oneflow.sinh , oneflow.sin_ , oneflow.sqrt , oneflow.square , oneflow.sub , oneflow.tan , oneflow.tanh

Reduction Ops:

oneflow.argmax , oneflow.argmin , oneflow.min , oneflow.mean , [oneflow.prod] (https://oneflow.readthedocs.io/en/master/oneflow.html#oneflow.prod) , oneflow.std , oneflow.sum , oneflow.var

Comparison Ops:

oneflow.argsort , oneflow.eq , oneflow.equal , oneflow.gt , #oneflow.isinf , oneflow.isnan , oneflow.le , oneflow.lt , oneflow.ne , oneflow.sort , oneflow.topk

Other Ops:

oneflow.broadcast_like , oneflow.cumprod , oneflow.cumsum , oneflow.diag , oneflow.diagonal , oneflow.einsum , oneflow.flatten , oneflow.flip , oneflow.meshgrid , oneflow.roll , oneflow.tril

BLAS and LAPACK Operations:

oneflow.addmm , oneflow.bmm , oneflow.dot , oneflow.matmul ,

robin978 commented 2 years ago

为了重构 v0.8.0 的API 文档，想对 oneflow 中的数据类型进行整合，参考 pytorch 数据类型表格，请开发组同事帮忙，将整理好的数据类型回复在这个 issue 里。

MARD1NO commented 2 years ago

Data type	dtype	CPU tensor	GPU tensor
Boolean	oneflow.bool	oneflow.BoolTensor	oneflow.cuda.BoolTensor
8-bit integer (unsigned)	oneflow.uint8	oneflow.ByteTensor	oneflow.cuda.ByteTensor
8-bit integer (signed)	oneflow.int8	oneflow.CharTensor	oneflow.cuda.CharTensor
64-bit floating point	oneflow.float64 / oneflow.double	oneflow.DoubleTensor	oneflow.cuda.DoubleTensor
32-bit floating point	oneflow.float32 / oneflow.float	oneflow.FloatTensor	oneflow.cuda.FloatTensor
16-bit floating point	oneflow.float16/oneflow.half	oneflow.HalfTensor	oneflow.cuda.HalfTensor
32-bit integer (signed)	oneflow.int32/oneflow.int	oneflow.IntTensor	oneflow.cuda.IntTensor
64-bit integer (signed)	oneflow.int64/oneflow.long	oneflow.LongTensor	oneflow.cuda.LongTensor

Oneflow-Inc / oneflow-api-cn

API 文档重构草案 #70

与 pytorch 的 API 文档 相比较：

oneflow.nn

Containers:

Convolution Layers:

Pooling layers:

Padding Layers:

Non-linear Activations (weighted sum, nonlinearity):

Non-linear Activations (other):

Normalization Layers:

Linear Layers:

Dropout Layers:

Sparse Layers:

Loss Functions:

Vision Layers:

DataParallel Layers:

Utilities:

oneflow.optim

How to use a optimizer

Base Class

Algorithms:

Adjust Learning Rate

oneflow.nn.functional

Convolution functions:

Pooling functions:

Non-linear activation functions:

Linear functions:

Dropout functions:

Sparse functions:

Loss functions:

Vision functions:

oneflow.Tensor

Data types

Initializing and basic operations

Tensor class reference：

oneflow:

Tensors:

Creation Ops:

Indexing, Slicing, Joining, Mutating Ops:

Random Sampling:

Serialization:

Parallelism

Locally disabling gradient computation:

Math Operations:

Pointwise Ops:

Reduction Ops:

Comparison Ops:

Other Ops:

BLAS and LAPACK Operations:

与 pytorch 的 API 文档相比较：