.. _tensor-guide:
.. currentmodule:: megengine
========================
娣卞叆鐞嗚В Tensor 鏁版嵁缁撴瀯
========================
.. toctree::
:hidden:
:maxdepth: 1
fundamental-attributes
indexing
dtype
device
examples
layout
MegEngine 涓彁渚涗簡涓€绉嶅悕涓� 鈥滃紶閲忊€� 锛�:py:class:`Tensor` 锛夌殑鏁版嵁缁撴瀯锛�
鍖哄埆浜庢暟瀛︿腑鐨勫畾涔夛紝鍏舵蹇典笌 NumPy_ 涓殑 :py:class:`~numpy.ndarray` 鏇村姞鐩镐技锛�
鍗冲紶閲忔槸涓€绫诲悓鏋勫缁存暟缁勶紝鍏朵腑姣忎釜鍏冪礌鍗犵敤鐩稿悓澶у皬鐨勫唴瀛樺潡锛屽苟涓旀墍鏈夊潡閮戒互瀹屽叏鐩稿悓鐨勬柟寮忚В閲娿€�
濡備綍瑙ｉ噴 Tensor 涓殑鍏冪礌鐢卞叾 :ref:`鏁版嵁绫诲瀷 <tensor-dtype>` 鍐冲畾锛岃€屾瘡绉嶆暟鎹被鍨嬮兘浠ｈ〃涓€绫� Tensor.
* 鎴戜滑鍙互鍩轰簬 Tensor 鏁版嵁缁撴瀯锛岃繘琛屽悇寮忓悇鏍风殑绉戝璁＄畻锛�
* Tensor 涔熸槸绁炵粡缃戠粶缂栫▼鏃舵墍鐢ㄧ殑涓昏鏁版嵁缁撴瀯锛岀綉缁滅殑杈撳叆銆佽緭鍑哄拰杞崲閮戒娇鐢� Tensor 琛ㄧず銆�
.. _Numpy: https://numpy.org
.. note::
涓� NumPy 鐨勫尯鍒箣澶勫湪浜庯紝MegEngine 杩樻敮鎸佸埄鐢� GPU 璁惧杩涜鏇村姞楂樻晥鐨勮绠椼€�
褰� GPU 鍜� CPU 璁惧閮藉彲鐢ㄦ椂锛孧egEngine 灏嗕紭鍏堜娇鐢� GPU 浣滀负榛樿璁＄畻璁惧锛屾棤闇€鐢ㄦ埛杩涜鎵嬪姩璁惧畾銆�
* 濡傛灉鏈夋煡鐪�/鏀瑰彉榛樿璁＄畻璁惧鐨勯渶姹傦紝璇峰弬鑰� :ref:`tensor-device` 涓殑璇存槑銆�
* 閫氳繃 :meth:`.Tensor.to` 鍜� :func:`.functional.copy` 鍙皢 Tensor 鎷疯礉鍒版寚瀹氳澶囥€�
.. seealso::
濡傛灉浣犺繕涓嶆竻妤氬浣曡幏寰椾竴涓� Tensor, 璇峰弬鑰� :ref:`tensor-creation` 銆�
.. _specific-concepts:
姒傚康锛堟湳璇級浣跨敤涓婄殑鍖哄垎
------------------------
鎴戜滑鎵€鎻愬埌鐨� Tensor 鐨勬蹇靛線寰€鏄叾瀹冩洿鍏蜂綋姒傚康鐨勬鎷紙鎴栬€呰鎺ㄥ箍锛夛紝涓嬮潰鏈変竴浜涗緥瀛愶細
===================== ===================== ======== ===========
鏁板 璁＄畻鏈虹瀛� 鎶借薄姒傚康 鍏疯薄鍖栦緥瀛�
===================== ===================== ======== ===========
鏍囬噺锛坰calar锛� 鏁板瓧锛坣umber锛� 鐐� 寰楀垎銆佹鐜�
鍚戦噺锛坴ector锛� 鏁扮粍锛坅rray锛� 绾� 鍒楄〃
鐭╅樀锛坢atrix锛� 2 缁存暟缁勶紙2d-array锛� 闈� Excel 琛ㄦ牸
===================== ===================== ======== ===========
涓嶅悓鐨勭爺绌堕鍩熷鍚屼竴涓蹇典娇鐢ㄤ笉鍚岀殑鏈杩涜鎻忚堪锛岃繖寰堝父瑙侊紝瀵硅繖浜涙蹇典笉娓呮櫚鐨勮瘽寰堝鏄撲骇鐢熺枒鎯戙€�
Python 涓彁渚涗簡 `array <https://docs.python.org/3/library/array.html>`_ 鐨勫畼鏂瑰疄鐜帮紝
浣嗗叾浣跨敤鏂规硶鍜屾垜浠彁鍒扮殑 NumPy 鏁扮粍鏈夋墍涓嶅悓锛屽洜姝ゆ垜浠彲浠ョ敤 Python 锛堝祵濂楋級鍒楄〃 :py:class:`list` 鏉ョ被姣斾妇渚嬨€�
鍦ㄥ悗缁殑椤甸潰锛屾垜浠細鎱㈡參鍦拌繃娓″埌 Tensor 鐨勫疄闄呬娇鐢ㄥ拰鎿嶄綔涓€�
娉ㄦ剰锛氫负浜嗘柟渚跨悊瑙ｏ紝鎴戜滑杩欓噷鍋囪姝ゅ Python 鍒楄〃涓殑鏁版嵁绫诲瀷鏄竴鑷寸殑锛屾瘮濡傞兘鏄� Number 绫诲瀷銆�
.. note::
鍦ㄦ繁搴﹀涔犻鍩燂紝鎴戜滑閫氬父灏嗕笂杩拌繖浜涙蹇电粺绉颁负寮犻噺锛圱ensor锛夈€�
.. _access-tensor-element:
璁块棶 Tensor 涓煇涓厓绱�
----------------------
瀵逛簬鏁板瓧锛堟垨鑰呰鏍囬噺锛� Tensor, 鏄剧劧鎴戜滑鍙互鐩存帴寰楀埌鍏跺€硷紝鍥犱负瀹冨彧鏈変竴涓厓绱犮€�
>>> a = 20200325
>>> a
20200325
鍏跺畠鎯呭喌涓嬶紝鎯宠鍦� Tensor 涓幏寰楁煇涓厓绱狅紝闇€瑕佹彁渚涘搴斾綅缃殑鏁存暟绱㈠紩锛圛ndex锛夛紝骞朵娇鐢ㄤ笅鏍囪繍绠楃 ``[]``:
* 娉ㄦ剰锛歍ensor 鐨勭储寮曟槸鍩轰簬闆讹紙Zero-based锛夊紑濮嬭鏁扮殑锛屽拰 Python 鍒楄〃 / NumPy 澶氱淮鏁扮粍涓€鑷达紱
* 姣斿鎴戜滑鎯宠鑾峰彇鍚戦噺/鏁扮粍 ``a = [0, 1, 2, 3, 4]`` 涓殑绗� 3 涓厓绱狅紝鎴戜滑闇€瑕佷娇鐢� ``a[2]``;
* 鍙堟瘮濡傛垜浠兂瑕佽幏鍙栦笅闈㈣繖涓� 2d-鏁扮粍 ``b`` 涓€间负 6 鐨勫厓绱狅紝鍒欓渶瑕佷娇鐢� ``b[1][2]``;
>>> b = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
>>> b[1]
[4, 5, 6]
>>> b[1][2]
6
鎴戜滑鍙互鐞嗚В鎴愬厛璁块棶 ``b[1]``, 鍐嶅皢 ``b[1]`` 鐪嬫垚鍗曠嫭鐨勪竴閮ㄥ垎锛屽幓璁块棶 ``b[1]`` 涓储寮曚负 2 鐨勫厓绱犮€�
浜岀淮鎯呭喌鍙互绫绘瘮鎴愭垜浠湪鐭╅樀 :math:`M` 涓寜鐓у厛琛屽悗鍒楃殑椤哄簭鍘昏幏鍙栧厓绱犫€斺€�
.. math::
M =
\begin{bmatrix}
1 & 2 & 3 \\
4 & 5 & \color{blue}{6} \\
7 & 8 & 9 \\
\end{bmatrix}
\quad
M_{(1,2)} = 6
鍦ㄦ洿楂樼淮搴︾殑鎯呭喌涓嬶紝鍐嶇敤涓撻棬鐨� 鈥滄爣閲忊€濓紝鈥滃悜閲忊€濓紝鈥滅煩闃碘€�... 鏈鍘诲畾涔夌粨鏋勬槸寰堜笉鐜板疄鐨勩€�
* 鍥犳鍦ㄦ暟瀛︿腑鎻愪緵浜� n 缁村紶閲忕殑姒傚康锛屽搴斿湴锛孨umPy 涓彁渚涗簡 n 缁存暟缁勶紱
* n 缁村紶閲忓拰 n 缁存暟缁勪腑鐨� n 鍒欒〃鏄庝粠涓幏鍙栧厓绱犻渶瑕佹彁渚� n 涓储寮曞€笺€�
===================== ===================== ======================
鏁板 璁＄畻鏈虹瀛� 鑾峰彇鍊兼墍闇€鏍囬噺绱㈠紩鏁伴噺
===================== ===================== ======================
鏍囬噺锛坰calar锛� 鏁板瓧锛坣umber锛� 0
鍚戦噺锛坴ector锛� 鏁扮粍锛坅rray锛� 1
鐭╅樀锛坢atrix锛� 2 缁存暟缁勶紙2d-array锛� 2
n 缁村紶閲忥紙nd-tensor锛� n 缁存暟缁勶紙nd-array锛� n
===================== ===================== ======================
鐜板湪鎴戜滑宸茬粡鍙互蹇樻帀涓婇潰杩欎簺鏈锛岀粺涓€鐢� n 鏉ョ‘瀹� Tensor 缁村害鐨勬暟閲忋€�
鍥犳鎴戜滑鍙互杩欐牱鐞嗚В锛�
* 涓€涓爣閲忔槸涓€涓� 0 缁� Tensor;
* 涓€涓悜閲忔槸涓€涓� 1 缁� Tensor;
* 涓€涓煩闃垫槸涓€涓� 2 缁� Tensor;
* 涓€涓� n 缁存暟缁勬槸涓€涓� n 缁� Tensor.
鑰屽湪璁块棶 n 缁� Tensor 锛堝亣瀹氫负 :math:`T` 锛夌殑鐗瑰畾鏌愪釜鍏冪礌鏃讹紝鍙互浣跨敤濡備笅璇硶锛�
.. math::
T_{[i_1][i_2]\ldots [i_n]}
鍗虫垜浠鎻愪緵 :math:`i_1, i_2, \ldots ,i_n` 鍏� n 涓储寮曞€硷紝姣忔绱㈠紩闄嶄綆涓€涓淮搴︼紝鏈€缁堝緱鍒� 0 缁存暟瀛楋紙鏍囬噺锛夈€�
姣斿鎴戜滑寰楃煡瑕佹壘鐨勬煇涓汉浣忓湪鏌愬皬鍖虹殑 23 鍙锋ゼ 3 鍗曞厓 902 瀹わ紝鍥犳鎴戜滑闇€瑕佽闂� ``court[23][3][9][2]``;
.. seealso::
瀹為檯涓婏紝瀵逛簬 Tensor 鍜屽缁存暟缁勶紝鏈夌潃鏇村姞楂樻晥鐨勭储寮曟柟娉曪紝鍙弬鑰� :ref:`multi-dim-indexing` 鐨勭敤娉曘€�
.. note::
娣卞害瀛︿範棰嗗煙鐨� Tensor 鍏跺疄灏辨槸涓€涓缁存暟缁勶紙N 缁存暟缁勶級銆�
.. _tensor-slice:
浣跨敤鍒囩墖鑾峰彇閮ㄥ垎鍏冪礌
--------------------
鍓嶉潰鎴戜滑灞曠ず浜嗗浣曡闂崟涓殑鍏冪礌锛屽彟涓€绉嶆瘮杈冨父瑙佺殑鎯呭喌鏄渶瑕佸閮ㄥ垎鍏冪礌杩涜璁块棶銆�
涓� Python 涓€鑷达紝鎴戜滑鍙互浣跨敤鍒囩墖锛圫licing锛夋搷浣滅鏉ヨ闂拰淇敼 Tensor 瀵硅薄涓殑閮ㄥ垎鍏冪礌锛�
>>> a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> a[2:8:2]
[2, 4, 6]
瑙傚療涓婇潰鐨勪緥瀛愶紝鎴戜滑閫氳繃 ``:`` 绗﹀彿杩涜浜嗗垏鐗囨搷浣滐紝璇硶涓� ``start:stop:step``, 瀵瑰簲璧峰绱㈠紩銆佺粓姝㈢储寮曞拰姝ラ暱銆�
杩欑鍐欐硶瀹為檯涓婂湪鑳屽悗涓烘垜浠敓鎴愪簡涓€涓垏鐗囧璞� ``slice(start:stop:step)``, 浜岃€呮槸绛変环鐨勶細
>>> myslice = slice(2, 8, 2)
>>> a[myslice]
[2, 4, 6]
.. note::
* ``start``, ``stop``, ``step`` 涔熷彲浠ユ槸璐熸暟锛屾剰鍛崇潃绱㈠紩鍙樺寲椤哄簭涓庨粯璁ゆ儏鍐电浉鍙嶃€�
* ``start`` 鍜� ``stop`` 绱㈠紩鍖洪棿鏄乏闂彸寮€鐨� ``[start, stop)`` 褰㈠紡锛屽嵆 ``a[stop]`` 鏈韩涓嶅湪鍒囩墖鑼冨洿涔嬪唴銆�
* 杩欎釜璁捐鍏跺疄涓庡熀浜庨浂鐨勭储寮曟柟寮忓搴旓紝璇ヨ璁＄殑濂藉鏈夊緢澶氾細
褰撳彧鏈夋渶鍚庝竴涓綅缃俊鎭椂锛屾垜浠篃鍙互蹇€熻绠楀嚭鍒囩墖鍜屽尯闂村唴鏈夊嚑涓厓绱�;
鍚岀悊浣跨敤 ``stop`` 鍑忓幓 ``start`` 鍙互蹇€熻绠楀嚭鍒囩墖鍜屽尯闂寸殑闀垮害锛屼笉瀹规槗娣锋穯锛�
涓庢鍚屾椂锛屾垜浠彲浠ョ敤 ``a[:i]`` 鍜� ``a[i:]`` 鑾峰緱鍘熷鏁版嵁鍒嗗壊鍚庝笉閲嶅彔鐨勪袱閮ㄥ垎銆�
.. seealso::
璁＄畻鏈虹瀛﹀锛孍dsger W. Dijkstra 鏁欐巿鍦ㄣ€奰Why numbering should start at zero
<https://www.cs.utexas.edu/users/EWD/transcriptions/EWD08xx/EWD831.html>`_ 銆�
涓殑鍐呭涓哄熀浜� 0 鐨勪笅鏍囦互鍙婂乏闂彸寮€鐨勫尯闂翠範鎯繘琛屼簡寰堝ソ鐨勮В閲娿€�
鍙﹀锛屽垏鐗囪娉曚腑鐨勯儴鍒嗗厓绱犲彲浠ヨ鐪佺暐锛�
* 濡傛灉涓嬫爣杩愮畻绗︿腑娌℃湁浠讳綍鍐掑彿杩愮畻绗﹀ ``a[i]``, 鍒欒繑鍥炰笌璇ョ储寮曚綅缃搴旂殑鍗曚釜鍏冪礌锛�
* 濡傛灉涓嬫爣杩愮畻绗︿腑鍙湁涓€涓啋鍙疯繍绠楃锛屽垯闇€瑕佹牴鎹笉鍚岀殑鍐欐硶杩涜鍒ゆ柇锛�
* 濡傛灉涓� ``a[start:]``, 鍒欒〃鏄庝粠 ``start`` 浣嶇疆寰€鍚庣殑鎵€鏈夐」閮借鎻愬彇锛�
* 濡傛灉涓� ``a[:stop]``, 鍒欒〃鏄庝粠 ``stop`` 浣嶇疆寰€鍓嶇殑鎵€鏈夐」閮借鎻愬彇锛�
* 濡傛灉涓� ``a[start:stop]``, 鍒欒〃鏄庝粠 ``start`` 鍒� ``stop`` 鐨勬墍鏈夐」灏嗚鎻愬彇锛�
* 濡傛灉娌℃湁鎸囧畾 ``step``, 鍒欓粯璁ゆ彁鍙栧垏鐗囪寖鍥村唴鐨勬墍鏈夐」鐩€�
澶氱淮鏁扮粍涔熸敮鎸佷娇鐢ㄥ垏鐗囪娉曪細
>>> b = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
>>> b[0:2]
[[1, 2, 3], [4, 5, 6]]
姝ゆ椂鍙互灏嗗叾褰撲綔鏄竴涓竴缁存暟缁勫幓鐞嗚В锛岄噷闈㈢殑姣忎釜鍏冪礌鍙堟槸涓€缁存暟缁勶細
>>> a1 = [1, 2, 3]
>>> a2 = [4, 5, 6]
>>> a3 = [7, 8, 9]
>>> b = [a1, a2, a3]
>>> b[0:2]
[[1, 2, 3], [4, 5, 6]]
>>> [a1, a2]
[[1, 2, 3], [4, 5, 6]]
鎴戜滑杩欓噷浠呬粎瀵规渶澶栭潰杩欎竴灞傝繘琛屼簡绱㈠紩锛屽湪 :ref:`tensor-indexing` 涓細璁茶В鏇村鏉傜殑鎯呭喌銆�
.. seealso::
浣跨敤鍒囩墖绱㈠紩鍙互浠� Tensor 涓闂儴鍒嗗厓绱狅紝浣嗘湁浜涙椂鍊欐垜浠笇鏈涜幏寰楃殑閮ㄥ垎鍏冪礌鏄笉杩炵画鐨勶紝
鑰屾槸鍑犱釜鐗瑰畾浣嶇疆鍏冪礌鐨勭粍鍚堬紝姝ゆ椂鍙互浣跨敤 :ref:`鏁扮粍绱㈠紩 <array-indexing>` 銆�
鎺ヤ笅鏉ワ細Tensor 鍩虹灞炴€�
-----------------------
閫氳繃鏈皬鑺傜殑鍐呭锛岀敤鎴疯兘澶熸帉鎻℃渶鍩烘湰鐨� Tensor 姒傚康銆�
涓轰簡鏂逛究鍒濆鑰呭涔犲拰杩囨浮锛屽湪涓婇潰鐨勪唬鐮佺ず渚嬩腑锛屾垜浠竴鐩村湪浣跨敤 Python 鐨� ``list`` 鏉ヤ妇渚嬶紝
浠ヨ〃鏄� MegEngine Tensor 鏁版嵁缁撴瀯涓� Python 宓屽鍒楄〃璁捐鐨勪竴鑷存€э紝浣嗗疄闄呬笂浜岃€呰繕鏄瓨鍦ㄧ潃涓€瀹氱殑鍖哄埆銆�
鎴戜滑鍐嶄妇涓€浜涗緥瀛愶紝璇蜂綘灏濊瘯鐚滄祴涓€涓嬭緭鍑猴細
.. panels::
:container: +full-width
:card:
Python nested list
^^^^^^^^^^^^^^^^^^
>>> c = [[1, 2, 3],
>>> [4, 5, 6],
>>> [7, 8, 9]]
>>> c[1, 1]
---
MegEngine 2-d Tensor
^^^^^^^^^^^^^^^^^^^^
>>> c = Tensor([[1, 2, 3],
>>> [4, 5, 6],
>>> [7, 8, 9]])
>>> c[1, 1]
Python 宓屽鍒楄〃骞朵笉鏀寔杩欑璇硶锛屼綘鑳界寽娴嬪嚭鍦� ``[]`` 杩愮畻绗︿腑浣跨敤 ``,`` 鐨勪綔鐢ㄥ悧锛�
鍋囪鎴戜滑鐜板湪闇€瑕佷粠涓嬮潰杩欎釜 2 缁� Tensor 涓彇鍑鸿摑鑹查儴鍒嗙殑鍏冪礌锛屽張闇€瑕佸浣曞仛鍛紵
锛� :ref:`瑙ｉ噴 <multi-dim-slicing>` 锛�
.. math::
M =
\begin{bmatrix}
1 & 2 & 3 \\
\color{blue}{4} & \color{blue}{5} & 6 \\
7 & 8 & 9 \\
\end{bmatrix}
\quad
M_{(?, ?)} = (4 \ 5)
鎯宠瑙ｇ瓟杩欎簺闂锛屼綘蹇呴』鍏堢悊瑙� Tensor 鐨� :ref:`tensor-fundamental-attributes` 绛夋湁鍏虫蹇碉紝
鏇村ソ鍦扮悊瑙� Tensor 鎵€鍏峰鐨勪竴浜涚壒鐐癸紝鎺ョ潃浠� :ref:`tensor-indexing` 鐨勫唴瀹逛腑鎵惧埌绛旀銆�
.. seealso::
Tensor 鏁版嵁绫诲瀷
鎴戜滑鎻愬埌浜� Tensor 涓殑姣忎釜鍏冪礌鐨勬暟鎹被鍨嬩竴鑷达紝濡傛灉浣犳兂瑕佺煡閬撳叿浣撴湁鍝簺鏁版嵁绫诲瀷鐨� Tensor,
璇峰弬鑰� :ref:`tensor-dtype` 銆�
Tensor 鎵€鍦ㄨ澶�
鑳藉鍒╃敤 GPU 璁惧杩涜楂樻晥杩愮畻鏄� MegEngine 鐩歌緝浜� NumPy 鐨勪紭鍔匡紝鎯宠浜嗚В涓嶅悓璁惧涔嬮棿鐨勫尯鍒紝
璇峰弬鑰� :ref:`tensor-device` 銆�
Tensor 鍏疯薄鍖栦妇渚�
濡傛灉浣犵洰鍓嶅浜� Tensor 鐨勬蹇典笉澶熺洿瑙傦紝鍙互鍙傝€� :ref:`tensor-examples` 銆�
Tensor 鍐呭瓨甯冨眬
涓€浜涙湁缁忛獙鐨勫紑鍙戣€呭枩娆㈢爺绌跺簳灞傜殑缁嗚妭锛屽彲浠ュ弬鑰� :ref:`tensor-layout` 銆�
.. admonition:: Python 鏁版嵁 API 鏍囧噯鑱旂洘鍗忎細
:class: note
MegEngine 涓殑璁稿 Tensor 鏍囧噯 API 璁捐閬靛惊浜� Python 鏁版嵁 API 鏍囧噯鑱旂洘鍗忎細鐨勫€″锛�
涓€浜涘父瑙佺殑瀹炵幇灏藉彲鑳藉湴鍚� NumPy 闈犺繎锛屾洿澶氱粏鑺傚彲浠ュ弬鑰� `Consortium for Python Data API Standards
<https://data-apis.org/>`_ .