1# This file is generated, do not modify it! 2# 3# To update this file, run the update masked docs script as follows: 4# 5# python tools/update_masked_docs.py 6# 7# The script must be called from an environment where the development 8# version of torch package can be imported and is functional. 9# 10 11amax_docstring = """amax(input, dim, *, keepdim=False, dtype=None, mask=None) -> Tensor 12 13Returns maximum of all the elements in the :attr:`input` 14tensor along the given dimension(s) :attr:`dim` while the :attr:`input` 15elements are masked out according to the boolean tensor 16:attr:`mask`. 17 18The identity value of maximum operation, which is used to start the 19reduction, depends on input dtype. For instance, for float32, uint8, 20and int32 dtypes, the identity values are ``-inf``, ``0``, and ``-2147483648``, respectively. 21 22If :attr:`keepdim` is ``True``, the output tensor is of the same size 23as :attr:`input` except in the dimension(s) :attr:`dim` where it is of 24size 1. Otherwise, :attr:`dim` is squeezed (see 25:func:`torch.squeeze`), resulting in the output tensor having 1 (or 26``len(dim)``) fewer dimension(s). 27 28The boolean tensor :attr:`mask` defines the "validity" of 29:attr:`input` tensor elements: if :attr:`mask` element is True 30then the corresponding element in :attr:`input` tensor will be 31included in maximum computation, otherwise the element is 32ignored. 33 34When all elements of :attr:`input` along the given dimension 35:attr:`dim` are ignored (fully masked-out), the corresponding element 36of the output tensor will have undefined value: it may or may not 37correspond to the identity value of maximum operation; the 38choice may correspond to the value that leads to the most efficient 39storage of :attr:`output` tensor. 40 41The mask of the output tensor can be computed as 42``torch.any(torch.broadcast_to(mask, input.shape), dim, keepdim=keepdim, 43dtype=torch.bool)``. 44 45The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 46don't need to match, but they must be :ref:`broadcastable 47<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 48tensor must not be greater than of the :attr:`input` tensor. 49 50Args: 51 input (Tensor): the input tensor 52 dim (int or tuple of ints, optional): the dimension or dimensions to reduce. 53 Default: None that is equivalent to ``tuple(range(input.ndim))``. 54 55Keyword args: 56 keepdim (bool, optional): whether the output tensor has 57 :attr:`dim` retained or not. Default: False. 58 dtype (:class:`torch.dtype`, optional): the desired data type 59 of returned tensor. If specified, the input tensor is 60 casted to :attr:`dtype` before the operation is 61 performed. Default: None. 62 mask (:class:`torch.Tensor`, optional): the boolean tensor 63 containing the binary mask of validity of input tensor 64 elements. 65 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 66 67Example:: 68 69 >>> input = tensor([[-3, -2, -1], [ 0, 1, 2]]) 70 >>> input 71 tensor([[-3, -2, -1], 72 [ 0, 1, 2]]) 73 >>> mask = tensor([[ True, False, True], [False, False, False]]) 74 >>> mask 75 tensor([[ True, False, True], 76 [False, False, False]]) 77 >>> torch.masked._ops.amax(input, 1, mask=mask) 78 tensor([ -1, -9223372036854775808]) 79""" 80 81amin_docstring = """amin(input, dim, *, keepdim=False, dtype=None, mask=None) -> Tensor 82 83Returns minimum of all the elements in the :attr:`input` 84tensor along the given dimension(s) :attr:`dim` while the :attr:`input` 85elements are masked out according to the boolean tensor 86:attr:`mask`. 87 88The identity value of minimum operation, which is used to start the 89reduction, depends on input dtype. For instance, for float32, uint8, 90and int32 dtypes, the identity values are ``inf``, ``255``, and ``2147483647``, respectively. 91 92If :attr:`keepdim` is ``True``, the output tensor is of the same size 93as :attr:`input` except in the dimension(s) :attr:`dim` where it is of 94size 1. Otherwise, :attr:`dim` is squeezed (see 95:func:`torch.squeeze`), resulting in the output tensor having 1 (or 96``len(dim)``) fewer dimension(s). 97 98The boolean tensor :attr:`mask` defines the "validity" of 99:attr:`input` tensor elements: if :attr:`mask` element is True 100then the corresponding element in :attr:`input` tensor will be 101included in minimum computation, otherwise the element is 102ignored. 103 104When all elements of :attr:`input` along the given dimension 105:attr:`dim` are ignored (fully masked-out), the corresponding element 106of the output tensor will have undefined value: it may or may not 107correspond to the identity value of minimum operation; the 108choice may correspond to the value that leads to the most efficient 109storage of :attr:`output` tensor. 110 111The mask of the output tensor can be computed as 112``torch.any(torch.broadcast_to(mask, input.shape), dim, keepdim=keepdim, 113dtype=torch.bool)``. 114 115The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 116don't need to match, but they must be :ref:`broadcastable 117<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 118tensor must not be greater than of the :attr:`input` tensor. 119 120Args: 121 input (Tensor): the input tensor 122 dim (int or tuple of ints, optional): the dimension or dimensions to reduce. 123 Default: None that is equivalent to ``tuple(range(input.ndim))``. 124 125Keyword args: 126 keepdim (bool, optional): whether the output tensor has 127 :attr:`dim` retained or not. Default: False. 128 dtype (:class:`torch.dtype`, optional): the desired data type 129 of returned tensor. If specified, the input tensor is 130 casted to :attr:`dtype` before the operation is 131 performed. Default: None. 132 mask (:class:`torch.Tensor`, optional): the boolean tensor 133 containing the binary mask of validity of input tensor 134 elements. 135 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 136 137Example:: 138 139 >>> input = tensor([[-3, -2, -1], [ 0, 1, 2]]) 140 >>> input 141 tensor([[-3, -2, -1], 142 [ 0, 1, 2]]) 143 >>> mask = tensor([[ True, False, True], [False, False, False]]) 144 >>> mask 145 tensor([[ True, False, True], 146 [False, False, False]]) 147 >>> torch.masked._ops.amin(input, 1, mask=mask) 148 tensor([ -3, 9223372036854775807]) 149""" 150 151argmax_docstring = """argmax(input, dim, *, keepdim=False, dtype=None, mask=None) -> Tensor 152Returns argmax of all the elements in the :attr:`input` 153tensor along the given dimension(s) :attr:`dim` while the :attr:`input` 154elements are masked out according to the boolean tensor 155:attr:`mask`. 156The identity value of argmax operation, which is used to start the 157reduction, depends on input dtype. For instance, for float32, uint8, 158and int32 dtypes, the identity values are ``-inf``, ``0``, and ``-2147483648``, respectively. 159If :attr:`keepdim` is ``True``, the output tensor is of the same size 160as :attr:`input` except in the dimension(s) :attr:`dim` where it is of 161size 1. Otherwise, :attr:`dim` is squeezed (see 162:func:`torch.squeeze`), resulting in the output tensor having 1 (or 163``len(dim)``) fewer dimension(s). 164 165The boolean tensor :attr:`mask` defines the "validity" of 166:attr:`input` tensor elements: if :attr:`mask` element is True 167then the corresponding element in :attr:`input` tensor will be 168included in argmax computation, otherwise the element is 169ignored. 170 171When all elements of :attr:`input` along the given dimension 172:attr:`dim` are ignored (fully masked-out), the corresponding element 173of the output tensor will have undefined value: it may or may not 174correspond to the identity value of argmax operation; the 175choice may correspond to the value that leads to the most efficient 176storage of :attr:`output` tensor. 177 178The mask of the output tensor can be computed as 179``torch.any(torch.broadcast_to(mask, input.shape), dim, keepdim=keepdim, 180dtype=torch.bool)``. 181 182The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 183don't need to match, but they must be :ref:`broadcastable 184<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 185tensor must not be greater than of the :attr:`input` tensor. 186 187Args: 188 input (Tensor): the input tensor 189 dim (int): the dimension along which argmax is computed. 190 191Keyword args: 192 keepdim (bool, optional): whether the output tensor has 193 :attr:`dim` retained or not. Default: False. 194 dtype (:class:`torch.dtype`, optional): the desired data type 195 of returned tensor. If specified, the input tensor is 196 casted to :attr:`dtype` before the operation is 197 performed. Default: None. 198 mask (:class:`torch.Tensor`, optional): the boolean tensor 199 containing the binary mask of validity of input tensor 200 elements. 201 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 202Example:: 203 204 >>> input = tensor([[-3, -2, -1], [ 0, 1, 2]]) 205 >>> input 206 tensor([[-3, -2, -1], 207 [ 0, 1, 2]]) 208 >>> mask = tensor([[ True, False, True], [False, False, False]]) 209 >>> mask 210 tensor([[ True, False, True], 211 [False, False, False]]) 212 >>> torch.masked._ops.argmax(input, 1, mask=mask) 213 tensor([2, 0]) 214""" 215 216argmin_docstring = """argmin(input, dim, *, keepdim=False, dtype=None, mask=None) -> Tensor 217Returns argmin of all the elements in the :attr:`input` 218tensor along the given dimension(s) :attr:`dim` while the :attr:`input` 219elements are masked out according to the boolean tensor 220:attr:`mask`. 221The identity value of argmin operation, which is used to start the 222reduction, depends on input dtype. For instance, for float32, uint8, 223and int32 dtypes, the identity values are ``inf``, ``255``, and ``2147483647``, respectively. 224If :attr:`keepdim` is ``True``, the output tensor is of the same size 225as :attr:`input` except in the dimension(s) :attr:`dim` where it is of 226size 1. Otherwise, :attr:`dim` is squeezed (see 227:func:`torch.squeeze`), resulting in the output tensor having 1 (or 228``len(dim)``) fewer dimension(s). 229 230The boolean tensor :attr:`mask` defines the "validity" of 231:attr:`input` tensor elements: if :attr:`mask` element is True 232then the corresponding element in :attr:`input` tensor will be 233included in argmin computation, otherwise the element is 234ignored. 235 236When all elements of :attr:`input` along the given dimension 237:attr:`dim` are ignored (fully masked-out), the corresponding element 238of the output tensor will have undefined value: it may or may not 239correspond to the identity value of argmin operation; the 240choice may correspond to the value that leads to the most efficient 241storage of :attr:`output` tensor. 242 243The mask of the output tensor can be computed as 244``torch.any(torch.broadcast_to(mask, input.shape), dim, keepdim=keepdim, 245dtype=torch.bool)``. 246 247The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 248don't need to match, but they must be :ref:`broadcastable 249<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 250tensor must not be greater than of the :attr:`input` tensor. 251 252Args: 253 input (Tensor): the input tensor 254 dim (int): the dimension along which argmin is computed. 255 256Keyword args: 257 keepdim (bool, optional): whether the output tensor has 258 :attr:`dim` retained or not. Default: False. 259 dtype (:class:`torch.dtype`, optional): the desired data type 260 of returned tensor. If specified, the input tensor is 261 casted to :attr:`dtype` before the operation is 262 performed. Default: None. 263 mask (:class:`torch.Tensor`, optional): the boolean tensor 264 containing the binary mask of validity of input tensor 265 elements. 266 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 267Example:: 268 269 >>> input = tensor([[-3, -2, -1], [ 0, 1, 2]]) 270 >>> input 271 tensor([[-3, -2, -1], 272 [ 0, 1, 2]]) 273 >>> mask = tensor([[ True, False, True], [False, False, False]]) 274 >>> mask 275 tensor([[ True, False, True], 276 [False, False, False]]) 277 >>> torch.masked._ops.argmin(input, 1, mask=mask) 278 tensor([0, 0]) 279""" 280 281cumprod_docstring = """cumprod(input, dim, *, dtype=None, mask=None) -> Tensor 282 283Returns cumulative_prod of all the slices in the :attr:`input` tensor 284along :attr:`dim` while the :attr:`input` elements are masked out 285according to the boolean tensor :attr:`mask`. 286 287Let ``x`` be a sequence of unmasked elements of one-dimensional slice 288of the :attr:`input` tensor. Cumsum of i-th element in ``x`` is 289defined as ``prod(x[:i])``. 290 291The boolean tensor :attr:`mask` defines the "validity" of 292:attr:`input` tensor elements: if :attr:`mask` element is True then 293the corresponding element in :attr:`input` tensor will be included in 294cumulative_prod computation, otherwise the element is ignored. 295 296The values of masked-out elements of the output tensor have undefined 297value: it may or may not be set to zero or nan; the choice may correspond to 298the value that leads to the most efficient storage of :attr:`output` 299tensor. 300 301The mask of the cumulative_prod output tensor can be computed as 302``torch.broadcast_to(mask, input.shape)``. 303 304The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 305don't need to match, but they must be :ref:`broadcastable 306<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 307tensor must not be greater than of the :attr:`input` tensor. 308 309Args: 310 input (Tensor): the input tensor 311 dim (int): the dimension along which cumulative_prod is computed. 312 313Keyword args: 314 dtype (:class:`torch.dtype`, optional): the desired data type 315 of returned tensor. If specified, the input tensor is 316 casted to :attr:`dtype` before the operation is 317 performed. Default: None. 318 mask (:class:`torch.Tensor`, optional): the boolean tensor 319 containing the binary mask of validity of input tensor 320 elements. 321 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 322 323Example:: 324 325 >>> input = tensor([[-3., -2., -1.], [ 0., 1., 2.]]) 326 >>> input 327 tensor([[-3., -2., -1.], 328 [ 0., 1., 2.]]) 329 >>> mask = tensor([[ True, False, True], [False, False, False]]) 330 >>> mask 331 tensor([[ True, False, True], 332 [False, False, False]]) 333 >>> torch.masked._ops.cumprod(input, 1, mask=mask) 334 tensor([[-3., -3., 3.], 335 [ 1., 1., 1.]]) 336""" 337 338cumsum_docstring = """cumsum(input, dim, *, dtype=None, mask=None) -> Tensor 339 340Returns cumulative_sum of all the slices in the :attr:`input` tensor 341along :attr:`dim` while the :attr:`input` elements are masked out 342according to the boolean tensor :attr:`mask`. 343 344Let ``x`` be a sequence of unmasked elements of one-dimensional slice 345of the :attr:`input` tensor. Cumsum of i-th element in ``x`` is 346defined as ``sum(x[:i])``. 347 348The boolean tensor :attr:`mask` defines the "validity" of 349:attr:`input` tensor elements: if :attr:`mask` element is True then 350the corresponding element in :attr:`input` tensor will be included in 351cumulative_sum computation, otherwise the element is ignored. 352 353The values of masked-out elements of the output tensor have undefined 354value: it may or may not be set to zero or nan; the choice may correspond to 355the value that leads to the most efficient storage of :attr:`output` 356tensor. 357 358The mask of the cumulative_sum output tensor can be computed as 359``torch.broadcast_to(mask, input.shape)``. 360 361The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 362don't need to match, but they must be :ref:`broadcastable 363<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 364tensor must not be greater than of the :attr:`input` tensor. 365 366Args: 367 input (Tensor): the input tensor 368 dim (int): the dimension along which cumulative_sum is computed. 369 370Keyword args: 371 dtype (:class:`torch.dtype`, optional): the desired data type 372 of returned tensor. If specified, the input tensor is 373 casted to :attr:`dtype` before the operation is 374 performed. Default: None. 375 mask (:class:`torch.Tensor`, optional): the boolean tensor 376 containing the binary mask of validity of input tensor 377 elements. 378 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 379 380Example:: 381 382 >>> input = tensor([[-3., -2., -1.], [ 0., 1., 2.]]) 383 >>> input 384 tensor([[-3., -2., -1.], 385 [ 0., 1., 2.]]) 386 >>> mask = tensor([[ True, False, True], [False, False, False]]) 387 >>> mask 388 tensor([[ True, False, True], 389 [False, False, False]]) 390 >>> torch.masked._ops.cumsum(input, 1, mask=mask) 391 tensor([[-3., -3., -4.], 392 [ 0., 0., 0.]]) 393""" 394 395log_softmax_docstring = """log_softmax(input, dim, *, dtype=None, mask=None) -> Tensor 396 397Returns log_softmax of all the slices in the :attr:`input` tensor 398along :attr:`dim` while the :attr:`input` elements are masked out 399according to the boolean tensor :attr:`mask`. 400 401Let ``x`` be a sequence of unmasked elements of one-dimensional slice 402of the :attr:`input` tensor. LogSoftmax of i-th element in ``x`` is 403defined as ``log(exp(x[i])/sum(exp(x)))``. 404 405The boolean tensor :attr:`mask` defines the "validity" of 406:attr:`input` tensor elements: if :attr:`mask` element is True then 407the corresponding element in :attr:`input` tensor will be included in 408log_softmax computation, otherwise the element is ignored. 409 410The values of masked-out elements of the output tensor have undefined 411value: it may or may not be set to zero or nan; the choice may correspond to 412the value that leads to the most efficient storage of :attr:`output` 413tensor. 414 415The mask of the log_softmax output tensor can be computed as 416``torch.broadcast_to(mask, input.shape)``. 417 418The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 419don't need to match, but they must be :ref:`broadcastable 420<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 421tensor must not be greater than of the :attr:`input` tensor. 422 423Args: 424 input (Tensor): the input tensor 425 dim (int): the dimension along which log_softmax is computed. 426 427Keyword args: 428 dtype (:class:`torch.dtype`, optional): the desired data type 429 of returned tensor. If specified, the input tensor is 430 casted to :attr:`dtype` before the operation is 431 performed. Default: None. 432 mask (:class:`torch.Tensor`, optional): the boolean tensor 433 containing the binary mask of validity of input tensor 434 elements. 435 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 436 437Example:: 438 439 >>> input = tensor([[-3., -2., -1.], [ 0., 1., 2.]]) 440 >>> input 441 tensor([[-3., -2., -1.], 442 [ 0., 1., 2.]]) 443 >>> mask = tensor([[ True, False, True], [False, False, False]]) 444 >>> mask 445 tensor([[ True, False, True], 446 [False, False, False]]) 447 >>> torch.masked._ops.log_softmax(input, 1, mask=mask) 448 tensor([[-2.1269, -inf, -0.1269], 449 [ nan, nan, nan]]) 450""" 451 452logsumexp_docstring = """logsumexp(input, dim, *, keepdim=False, dtype=None, mask=None) -> Tensor 453 454Returns logsumexp of all the elements in the :attr:`input` 455tensor along the given dimension(s) :attr:`dim` while the :attr:`input` 456elements are masked out according to the boolean tensor 457:attr:`mask`. 458 459The identity value of logsumexp operation, which is used to start the reduction, is ``-2147483648``. 460 461If :attr:`keepdim` is ``True``, the output tensor is of the same size 462as :attr:`input` except in the dimension(s) :attr:`dim` where it is of 463size 1. Otherwise, :attr:`dim` is squeezed (see 464:func:`torch.squeeze`), resulting in the output tensor having 1 (or 465``len(dim)``) fewer dimension(s). 466 467The boolean tensor :attr:`mask` defines the "validity" of 468:attr:`input` tensor elements: if :attr:`mask` element is True 469then the corresponding element in :attr:`input` tensor will be 470included in logsumexp computation, otherwise the element is 471ignored. 472 473When all elements of :attr:`input` along the given dimension 474:attr:`dim` are ignored (fully masked-out), the corresponding element 475of the output tensor will have undefined value: it may or may not 476correspond to the identity value of logsumexp operation; the 477choice may correspond to the value that leads to the most efficient 478storage of :attr:`output` tensor. 479 480The mask of the output tensor can be computed as 481``torch.any(torch.broadcast_to(mask, input.shape), dim, keepdim=keepdim, 482dtype=torch.bool)``. 483 484The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 485don't need to match, but they must be :ref:`broadcastable 486<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 487tensor must not be greater than of the :attr:`input` tensor. 488 489Args: 490 input (Tensor): the input tensor 491 dim (int or tuple of ints, optional): the dimension or dimensions to reduce. 492 Default: None that is equivalent to ``tuple(range(input.ndim))``. 493 494Keyword args: 495 keepdim (bool, optional): whether the output tensor has 496 :attr:`dim` retained or not. Default: False. 497 dtype (:class:`torch.dtype`, optional): the desired data type 498 of returned tensor. If specified, the input tensor is 499 casted to :attr:`dtype` before the operation is 500 performed. Default: None. 501 mask (:class:`torch.Tensor`, optional): the boolean tensor 502 containing the binary mask of validity of input tensor 503 elements. 504 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 505 506Example:: 507 508 >>> input = tensor([[-3, -2, -1], [ 0, 1, 2]]) 509 >>> input 510 tensor([[-3, -2, -1], 511 [ 0, 1, 2]]) 512 >>> mask = tensor([[ True, False, True], [False, False, False]]) 513 >>> mask 514 tensor([[ True, False, True], 515 [False, False, False]]) 516 >>> torch.masked._ops.logsumexp(input, 1, mask=mask) 517 tensor([ 0, -9223372036854775808]) 518""" 519 520mean_docstring = """mean(input, dim, *, keepdim=False, dtype=None, mask=None) -> Tensor 521 522Returns mean of all the elements in the :attr:`input` 523tensor along the given dimension(s) :attr:`dim` while the :attr:`input` 524elements are masked out according to the boolean tensor 525:attr:`mask`. 526 527By definition, the identity value of a mean operation is the mean 528value of the tensor. If all elements of the input tensor along given 529dimension(s) :attr:`dim` are masked-out, the identity value of the 530mean is undefined. Due to this ambiguity, the elements of output 531tensor with strided layout, that correspond to fully masked-out 532elements, have ``nan`` values. 533 534If :attr:`keepdim` is ``True``, the output tensor is of the same size 535as :attr:`input` except in the dimension(s) :attr:`dim` where it is of 536size 1. Otherwise, :attr:`dim` is squeezed (see 537:func:`torch.squeeze`), resulting in the output tensor having 1 (or 538``len(dim)``) fewer dimension(s). 539 540The boolean tensor :attr:`mask` defines the "validity" of 541:attr:`input` tensor elements: if :attr:`mask` element is True 542then the corresponding element in :attr:`input` tensor will be 543included in mean computation, otherwise the element is 544ignored. 545 546When all elements of :attr:`input` along the given dimension 547:attr:`dim` are ignored (fully masked-out), the corresponding element 548of the output tensor will have undefined value: it may or may not 549correspond to the identity value of mean operation; the 550choice may correspond to the value that leads to the most efficient 551storage of :attr:`output` tensor. 552 553The mask of the output tensor can be computed as 554``torch.any(torch.broadcast_to(mask, input.shape), dim, keepdim=keepdim, 555dtype=torch.bool)``. 556 557The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 558don't need to match, but they must be :ref:`broadcastable 559<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 560tensor must not be greater than of the :attr:`input` tensor. 561 562Args: 563 input (Tensor): the input tensor 564 dim (int or tuple of ints, optional): the dimension or dimensions to reduce. 565 Default: None that is equivalent to ``tuple(range(input.ndim))``. 566 567Keyword args: 568 keepdim (bool, optional): whether the output tensor has 569 :attr:`dim` retained or not. Default: False. 570 dtype (:class:`torch.dtype`, optional): the desired data type 571 of returned tensor. If specified, the input tensor is 572 casted to :attr:`dtype` before the operation is 573 performed. Default: None. 574 mask (:class:`torch.Tensor`, optional): the boolean tensor 575 containing the binary mask of validity of input tensor 576 elements. 577 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 578 579Example:: 580 581 >>> input = tensor([[-3, -2, -1], [ 0, 1, 2]]) 582 >>> input 583 tensor([[-3, -2, -1], 584 [ 0, 1, 2]]) 585 >>> mask = tensor([[ True, False, True], [False, False, False]]) 586 >>> mask 587 tensor([[ True, False, True], 588 [False, False, False]]) 589 >>> torch.masked._ops.mean(input, 1, mask=mask) 590 tensor([-2., nan]) 591""" 592 593median_docstring = """median(input, dim, *, keepdim=False, dtype=None, mask=None) -> Tensor 594Returns median of all the elements in the :attr:`input` 595tensor along the given dimension(s) :attr:`dim` while the :attr:`input` 596elements are masked out according to the boolean tensor 597:attr:`mask`. 598By definition, the identity value of a median operation is the median 599value of the tensor. If all elements of the input tensor along given 600dimension(s) :attr:`dim` are masked-out, the identity value of the 601median is undefined. Due to this ambiguity, the elements of output 602tensor with strided layout, that correspond to fully masked-out 603elements, have ``nan`` values. 604If :attr:`keepdim` is ``True``, the output tensor is of the same size 605as :attr:`input` except in the dimension(s) :attr:`dim` where it is of 606size 1. Otherwise, :attr:`dim` is squeezed (see 607:func:`torch.squeeze`), resulting in the output tensor having 1 (or 608``len(dim)``) fewer dimension(s). 609 610The boolean tensor :attr:`mask` defines the "validity" of 611:attr:`input` tensor elements: if :attr:`mask` element is True 612then the corresponding element in :attr:`input` tensor will be 613included in median computation, otherwise the element is 614ignored. 615 616When all elements of :attr:`input` along the given dimension 617:attr:`dim` are ignored (fully masked-out), the corresponding element 618of the output tensor will have undefined value: it may or may not 619correspond to the identity value of median operation; the 620choice may correspond to the value that leads to the most efficient 621storage of :attr:`output` tensor. 622 623The mask of the output tensor can be computed as 624``torch.any(torch.broadcast_to(mask, input.shape), dim, keepdim=keepdim, 625dtype=torch.bool)``. 626 627The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 628don't need to match, but they must be :ref:`broadcastable 629<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 630tensor must not be greater than of the :attr:`input` tensor. 631 632Args: 633 input (Tensor): the input tensor 634 dim (int): the dimension along which median is computed. 635 636Keyword args: 637 keepdim (bool, optional): whether the output tensor has 638 :attr:`dim` retained or not. Default: False. 639 dtype (:class:`torch.dtype`, optional): the desired data type 640 of returned tensor. If specified, the input tensor is 641 casted to :attr:`dtype` before the operation is 642 performed. Default: None. 643 mask (:class:`torch.Tensor`, optional): the boolean tensor 644 containing the binary mask of validity of input tensor 645 elements. 646 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 647Example:: 648 649 >>> input = tensor([[-3., -2., -1.], [ 0., 1., 2.]]) 650 >>> input 651 tensor([[-3., -2., -1.], 652 [ 0., 1., 2.]]) 653 >>> mask = tensor([[ True, False, True], [False, False, False]]) 654 >>> mask 655 tensor([[ True, False, True], 656 [False, False, False]]) 657 >>> torch.masked._ops.median(input, 1, mask=mask) 658 tensor([-3., nan]) 659""" 660 661norm_docstring = """norm(input, ord, dim, *, keepdim=False, dtype=None, mask=None) -> Tensor 662 663Returns norm of all the elements in the :attr:`input` 664tensor along the given dimension(s) :attr:`dim` while the :attr:`input` 665elements are masked out according to the boolean tensor 666:attr:`mask`. 667 668The identity value of norm operation, which is used to start the 669reduction, is ``0.0``, except for ``ord=-inf`` it is 670``inf``. 671 672If :attr:`keepdim` is ``True``, the output tensor is of the same size 673as :attr:`input` except in the dimension(s) :attr:`dim` where it is of 674size 1. Otherwise, :attr:`dim` is squeezed (see 675:func:`torch.squeeze`), resulting in the output tensor having 1 (or 676``len(dim)``) fewer dimension(s). 677 678The boolean tensor :attr:`mask` defines the "validity" of 679:attr:`input` tensor elements: if :attr:`mask` element is True 680then the corresponding element in :attr:`input` tensor will be 681included in norm computation, otherwise the element is 682ignored. 683 684When all elements of :attr:`input` along the given dimension 685:attr:`dim` are ignored (fully masked-out), the corresponding element 686of the output tensor will have undefined value: it may or may not 687correspond to the identity value of norm operation; the 688choice may correspond to the value that leads to the most efficient 689storage of :attr:`output` tensor. 690 691The mask of the output tensor can be computed as 692``torch.any(torch.broadcast_to(mask, input.shape), dim, keepdim=keepdim, 693dtype=torch.bool)``. 694 695The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 696don't need to match, but they must be :ref:`broadcastable 697<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 698tensor must not be greater than of the :attr:`input` tensor. 699 700Args: 701 input (Tensor): the input tensor 702 ord (int, float, optional): the order of vector norm. Default: 2. 703 See :func:`torch.linalg.vector_norm` for a list of supported norms. 704 dim (int or tuple of ints, optional): the dimension or dimensions to reduce. 705 Default: None that is equivalent to ``tuple(range(input.ndim))``. 706 707Keyword args: 708 keepdim (bool, optional): whether the output tensor has 709 :attr:`dim` retained or not. Default: False. 710 dtype (:class:`torch.dtype`, optional): the desired data type 711 of returned tensor. If specified, the input tensor is 712 casted to :attr:`dtype` before the operation is 713 performed. Default: None. 714 mask (:class:`torch.Tensor`, optional): the boolean tensor 715 containing the binary mask of validity of input tensor 716 elements. 717 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 718 719Example:: 720 721 >>> input = tensor([[-3., -2., -1.], [ 0., 1., 2.]]) 722 >>> input 723 tensor([[-3., -2., -1.], 724 [ 0., 1., 2.]]) 725 >>> mask = tensor([[ True, False, True], [False, False, False]]) 726 >>> mask 727 tensor([[ True, False, True], 728 [False, False, False]]) 729 >>> torch.masked._ops.norm(input, 2.0, 1, mask=mask) 730 tensor([3.1623, 0.0000]) 731""" 732 733normalize_docstring = """normalize(input, ord, dim, *, eps=1e-12, dtype=None, mask=None) -> Tensor 734 735Returns normalize of all the slices in the :attr:`input` tensor 736along :attr:`dim` while the :attr:`input` elements are masked out 737according to the boolean tensor :attr:`mask`. 738 739Let ``x`` be a sequence of unmasked elements of one-dimensional slice 740of the :attr:`input` tensor. Normalize of i-th element in ``x`` is 741defined as ``x[i]/max(norm(x, p), eps)``. 742 743The boolean tensor :attr:`mask` defines the "validity" of 744:attr:`input` tensor elements: if :attr:`mask` element is True then 745the corresponding element in :attr:`input` tensor will be included in 746normalize computation, otherwise the element is ignored. 747 748The values of masked-out elements of the output tensor have undefined 749value: it may or may not be set to zero or nan; the choice may correspond to 750the value that leads to the most efficient storage of :attr:`output` 751tensor. 752 753The mask of the normalize output tensor can be computed as 754``torch.broadcast_to(mask, input.shape)``. 755 756The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 757don't need to match, but they must be :ref:`broadcastable 758<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 759tensor must not be greater than of the :attr:`input` tensor. 760 761Args: 762 input (Tensor): the input tensor 763 ord (int, float): the order of vector norm. Default: 2. 764 See :func:`torch.linalg.vector_norm` for a list of supported norms. 765 dim (int): the dimension along which normalize is computed. 766 767Keyword args: 768 eps (float, optional): small value to avoid division by zero. Default: 1e-12. 769 dtype (:class:`torch.dtype`, optional): the desired data type 770 of returned tensor. If specified, the input tensor is 771 casted to :attr:`dtype` before the operation is 772 performed. Default: None. 773 mask (:class:`torch.Tensor`, optional): the boolean tensor 774 containing the binary mask of validity of input tensor 775 elements. 776 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 777 778Example:: 779 780 >>> input = tensor([[-3., -2., -1.], [ 0., 1., 2.]]) 781 >>> input 782 tensor([[-3., -2., -1.], 783 [ 0., 1., 2.]]) 784 >>> mask = tensor([[ True, False, True], [False, False, False]]) 785 >>> mask 786 tensor([[ True, False, True], 787 [False, False, False]]) 788 >>> torch.masked._ops.normalize(input, 2.0, 1, mask=mask) 789 tensor([[-0.9487, 0.0000, -0.3162], 790 [ 0.0000, 0.0000, 0.0000]]) 791""" 792 793prod_docstring = """prod(input, dim, *, keepdim=False, dtype=None, mask=None) -> Tensor 794 795Returns product of all the elements in the :attr:`input` 796tensor along the given dimension(s) :attr:`dim` while the :attr:`input` 797elements are masked out according to the boolean tensor 798:attr:`mask`. 799 800The identity value of product operation, which is used to start the reduction, is ``1``. 801 802If :attr:`keepdim` is ``True``, the output tensor is of the same size 803as :attr:`input` except in the dimension(s) :attr:`dim` where it is of 804size 1. Otherwise, :attr:`dim` is squeezed (see 805:func:`torch.squeeze`), resulting in the output tensor having 1 (or 806``len(dim)``) fewer dimension(s). 807 808The boolean tensor :attr:`mask` defines the "validity" of 809:attr:`input` tensor elements: if :attr:`mask` element is True 810then the corresponding element in :attr:`input` tensor will be 811included in product computation, otherwise the element is 812ignored. 813 814When all elements of :attr:`input` along the given dimension 815:attr:`dim` are ignored (fully masked-out), the corresponding element 816of the output tensor will have undefined value: it may or may not 817correspond to the identity value of product operation; the 818choice may correspond to the value that leads to the most efficient 819storage of :attr:`output` tensor. 820 821The mask of the output tensor can be computed as 822``torch.any(torch.broadcast_to(mask, input.shape), dim, keepdim=keepdim, 823dtype=torch.bool)``. 824 825The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 826don't need to match, but they must be :ref:`broadcastable 827<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 828tensor must not be greater than of the :attr:`input` tensor. 829 830Args: 831 input (Tensor): the input tensor 832 dim (int or tuple of ints, optional): the dimension or dimensions to reduce. 833 Default: None that is equivalent to ``tuple(range(input.ndim))``. 834 835Keyword args: 836 keepdim (bool, optional): whether the output tensor has 837 :attr:`dim` retained or not. Default: False. 838 dtype (:class:`torch.dtype`, optional): the desired data type 839 of returned tensor. If specified, the input tensor is 840 casted to :attr:`dtype` before the operation is 841 performed. Default: None. 842 mask (:class:`torch.Tensor`, optional): the boolean tensor 843 containing the binary mask of validity of input tensor 844 elements. 845 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 846 847Example:: 848 849 >>> input = tensor([[-3, -2, -1], [ 0, 1, 2]]) 850 >>> input 851 tensor([[-3, -2, -1], 852 [ 0, 1, 2]]) 853 >>> mask = tensor([[ True, False, True], [False, False, False]]) 854 >>> mask 855 tensor([[ True, False, True], 856 [False, False, False]]) 857 >>> torch.masked._ops.prod(input, 1, mask=mask) 858 tensor([3, 1]) 859""" 860 861softmax_docstring = """softmax(input, dim, *, dtype=None, mask=None) -> Tensor 862 863Returns softmax of all the slices in the :attr:`input` tensor 864along :attr:`dim` while the :attr:`input` elements are masked out 865according to the boolean tensor :attr:`mask`. 866 867Let ``x`` be a sequence of unmasked elements of one-dimensional slice 868of the :attr:`input` tensor. Softmax of i-th element in ``x`` is 869defined as ``exp(x[i])/sum(exp(x))``. 870 871The boolean tensor :attr:`mask` defines the "validity" of 872:attr:`input` tensor elements: if :attr:`mask` element is True then 873the corresponding element in :attr:`input` tensor will be included in 874softmax computation, otherwise the element is ignored. 875 876The values of masked-out elements of the output tensor have undefined 877value: it may or may not be set to zero or nan; the choice may correspond to 878the value that leads to the most efficient storage of :attr:`output` 879tensor. 880 881The mask of the softmax output tensor can be computed as 882``torch.broadcast_to(mask, input.shape)``. 883 884The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 885don't need to match, but they must be :ref:`broadcastable 886<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 887tensor must not be greater than of the :attr:`input` tensor. 888 889Args: 890 input (Tensor): the input tensor 891 dim (int): the dimension along which softmax is computed. 892 893Keyword args: 894 dtype (:class:`torch.dtype`, optional): the desired data type 895 of returned tensor. If specified, the input tensor is 896 casted to :attr:`dtype` before the operation is 897 performed. Default: None. 898 mask (:class:`torch.Tensor`, optional): the boolean tensor 899 containing the binary mask of validity of input tensor 900 elements. 901 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 902 903Example:: 904 905 >>> input = tensor([[-3., -2., -1.], [ 0., 1., 2.]]) 906 >>> input 907 tensor([[-3., -2., -1.], 908 [ 0., 1., 2.]]) 909 >>> mask = tensor([[ True, False, True], [False, False, False]]) 910 >>> mask 911 tensor([[ True, False, True], 912 [False, False, False]]) 913 >>> torch.masked._ops.softmax(input, 1, mask=mask) 914 tensor([[0.1192, 0.0000, 0.8808], 915 [ nan, nan, nan]]) 916""" 917 918softmin_docstring = """softmin(input, dim, *, dtype=None, mask=None) -> Tensor 919 920Returns softmin of all the slices in the :attr:`input` tensor 921along :attr:`dim` while the :attr:`input` elements are masked out 922according to the boolean tensor :attr:`mask`. 923 924Let ``x`` be a sequence of unmasked elements of one-dimensional slice 925of the :attr:`input` tensor. Softmin of i-th element in ``x`` is 926defined as ``exp(-x[i])/sum(exp(-x))``. 927 928The boolean tensor :attr:`mask` defines the "validity" of 929:attr:`input` tensor elements: if :attr:`mask` element is True then 930the corresponding element in :attr:`input` tensor will be included in 931softmin computation, otherwise the element is ignored. 932 933The values of masked-out elements of the output tensor have undefined 934value: it may or may not be set to zero or nan; the choice may correspond to 935the value that leads to the most efficient storage of :attr:`output` 936tensor. 937 938The mask of the softmin output tensor can be computed as 939``torch.broadcast_to(mask, input.shape)``. 940 941The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 942don't need to match, but they must be :ref:`broadcastable 943<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 944tensor must not be greater than of the :attr:`input` tensor. 945 946Args: 947 input (Tensor): the input tensor 948 dim (int): the dimension along which softmin is computed. 949 950Keyword args: 951 dtype (:class:`torch.dtype`, optional): the desired data type 952 of returned tensor. If specified, the input tensor is 953 casted to :attr:`dtype` before the operation is 954 performed. Default: None. 955 mask (:class:`torch.Tensor`, optional): the boolean tensor 956 containing the binary mask of validity of input tensor 957 elements. 958 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 959 960Example:: 961 962 >>> input = tensor([[-3., -2., -1.], [ 0., 1., 2.]]) 963 >>> input 964 tensor([[-3., -2., -1.], 965 [ 0., 1., 2.]]) 966 >>> mask = tensor([[ True, False, True], [False, False, False]]) 967 >>> mask 968 tensor([[ True, False, True], 969 [False, False, False]]) 970 >>> torch.masked._ops.softmin(input, 1, mask=mask) 971 tensor([[0.8808, 0.0000, 0.1192], 972 [ nan, nan, nan]]) 973""" 974 975std_docstring = """std(input, dim, unbiased, *, keepdim=False, dtype=None, mask=None) -> Tensor 976Returns standard_deviation of all the elements in the :attr:`input` 977tensor along the given dimension(s) :attr:`dim` while the :attr:`input` 978elements are masked out according to the boolean tensor 979:attr:`mask`. 980The identity value of sample standard deviation operation is undefined. The 981elements of output tensor with strided layout, that correspond to 982fully masked-out elements, have ``nan`` values. 983If :attr:`keepdim` is ``True``, the output tensor is of the same size 984as :attr:`input` except in the dimension(s) :attr:`dim` where it is of 985size 1. Otherwise, :attr:`dim` is squeezed (see 986:func:`torch.squeeze`), resulting in the output tensor having 1 (or 987``len(dim)``) fewer dimension(s). 988 989The boolean tensor :attr:`mask` defines the "validity" of 990:attr:`input` tensor elements: if :attr:`mask` element is True 991then the corresponding element in :attr:`input` tensor will be 992included in standard_deviation computation, otherwise the element is 993ignored. 994 995When all elements of :attr:`input` along the given dimension 996:attr:`dim` are ignored (fully masked-out), the corresponding element 997of the output tensor will have undefined value: it may or may not 998correspond to the identity value of standard_deviation operation; the 999choice may correspond to the value that leads to the most efficient 1000storage of :attr:`output` tensor. 1001 1002The mask of the output tensor can be computed as 1003``torch.any(torch.broadcast_to(mask, input.shape), dim, keepdim=keepdim, 1004dtype=torch.bool)``. 1005 1006The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 1007don't need to match, but they must be :ref:`broadcastable 1008<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 1009tensor must not be greater than of the :attr:`input` tensor. 1010 1011Args: 1012 input (Tensor): the input tensor 1013 dim (int or tuple of ints, optional): the dimension or dimensions to reduce. 1014 Default: None that is equivalent to ``tuple(range(input.ndim))``. 1015 unbiased (bool): when True, use Bessel's correction, otherwise, compute 1016 the uncorrected sample variance. 1017 1018Keyword args: 1019 keepdim (bool, optional): whether the output tensor has 1020 :attr:`dim` retained or not. Default: False. 1021 dtype (:class:`torch.dtype`, optional): the desired data type 1022 of returned tensor. If specified, the input tensor is 1023 casted to :attr:`dtype` before the operation is 1024 performed. Default: None. 1025 mask (:class:`torch.Tensor`, optional): the boolean tensor 1026 containing the binary mask of validity of input tensor 1027 elements. 1028 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 1029Example:: 1030 1031 >>> input = tensor([[-3, -2, -1], [ 0, 1, 2]]) 1032 >>> input 1033 tensor([[-3, -2, -1], 1034 [ 0, 1, 2]]) 1035 >>> mask = tensor([[ True, False, True], [False, False, False]]) 1036 >>> mask 1037 tensor([[ True, False, True], 1038 [False, False, False]]) 1039 >>> torch.masked._ops.std(input, 1, False, mask=mask) 1040 tensor([1., nan]) 1041""" 1042 1043sum_docstring = """sum(input, dim, *, keepdim=False, dtype=None, mask=None) -> Tensor 1044 1045Returns sum of all the elements in the :attr:`input` 1046tensor along the given dimension(s) :attr:`dim` while the :attr:`input` 1047elements are masked out according to the boolean tensor 1048:attr:`mask`. 1049 1050The identity value of sum operation, which is used to start the reduction, is ``0``. 1051 1052If :attr:`keepdim` is ``True``, the output tensor is of the same size 1053as :attr:`input` except in the dimension(s) :attr:`dim` where it is of 1054size 1. Otherwise, :attr:`dim` is squeezed (see 1055:func:`torch.squeeze`), resulting in the output tensor having 1 (or 1056``len(dim)``) fewer dimension(s). 1057 1058The boolean tensor :attr:`mask` defines the "validity" of 1059:attr:`input` tensor elements: if :attr:`mask` element is True 1060then the corresponding element in :attr:`input` tensor will be 1061included in sum computation, otherwise the element is 1062ignored. 1063 1064When all elements of :attr:`input` along the given dimension 1065:attr:`dim` are ignored (fully masked-out), the corresponding element 1066of the output tensor will have undefined value: it may or may not 1067correspond to the identity value of sum operation; the 1068choice may correspond to the value that leads to the most efficient 1069storage of :attr:`output` tensor. 1070 1071The mask of the output tensor can be computed as 1072``torch.any(torch.broadcast_to(mask, input.shape), dim, keepdim=keepdim, 1073dtype=torch.bool)``. 1074 1075The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 1076don't need to match, but they must be :ref:`broadcastable 1077<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 1078tensor must not be greater than of the :attr:`input` tensor. 1079 1080Args: 1081 input (Tensor): the input tensor 1082 dim (int or tuple of ints, optional): the dimension or dimensions to reduce. 1083 Default: None that is equivalent to ``tuple(range(input.ndim))``. 1084 1085Keyword args: 1086 keepdim (bool, optional): whether the output tensor has 1087 :attr:`dim` retained or not. Default: False. 1088 dtype (:class:`torch.dtype`, optional): the desired data type 1089 of returned tensor. If specified, the input tensor is 1090 casted to :attr:`dtype` before the operation is 1091 performed. Default: None. 1092 mask (:class:`torch.Tensor`, optional): the boolean tensor 1093 containing the binary mask of validity of input tensor 1094 elements. 1095 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 1096 1097Example:: 1098 1099 >>> input = tensor([[-3, -2, -1], [ 0, 1, 2]]) 1100 >>> input 1101 tensor([[-3, -2, -1], 1102 [ 0, 1, 2]]) 1103 >>> mask = tensor([[ True, False, True], [False, False, False]]) 1104 >>> mask 1105 tensor([[ True, False, True], 1106 [False, False, False]]) 1107 >>> torch.masked._ops.sum(input, 1, mask=mask) 1108 tensor([-4, 0]) 1109""" 1110 1111var_docstring = """var(input, dim, unbiased, *, keepdim=False, dtype=None, mask=None) -> Tensor 1112Returns variance of all the elements in the :attr:`input` 1113tensor along the given dimension(s) :attr:`dim` while the :attr:`input` 1114elements are masked out according to the boolean tensor 1115:attr:`mask`. 1116The identity value of sample variance operation is undefined. The 1117elements of output tensor with strided layout, that correspond to 1118fully masked-out elements, have ``nan`` values. 1119If :attr:`keepdim` is ``True``, the output tensor is of the same size 1120as :attr:`input` except in the dimension(s) :attr:`dim` where it is of 1121size 1. Otherwise, :attr:`dim` is squeezed (see 1122:func:`torch.squeeze`), resulting in the output tensor having 1 (or 1123``len(dim)``) fewer dimension(s). 1124 1125The boolean tensor :attr:`mask` defines the "validity" of 1126:attr:`input` tensor elements: if :attr:`mask` element is True 1127then the corresponding element in :attr:`input` tensor will be 1128included in variance computation, otherwise the element is 1129ignored. 1130 1131When all elements of :attr:`input` along the given dimension 1132:attr:`dim` are ignored (fully masked-out), the corresponding element 1133of the output tensor will have undefined value: it may or may not 1134correspond to the identity value of variance operation; the 1135choice may correspond to the value that leads to the most efficient 1136storage of :attr:`output` tensor. 1137 1138The mask of the output tensor can be computed as 1139``torch.any(torch.broadcast_to(mask, input.shape), dim, keepdim=keepdim, 1140dtype=torch.bool)``. 1141 1142The shapes of the :attr:`mask` tensor and the :attr:`input` tensor 1143don't need to match, but they must be :ref:`broadcastable 1144<broadcasting-semantics>` and the dimensionality of the :attr:`mask` 1145tensor must not be greater than of the :attr:`input` tensor. 1146 1147Args: 1148 input (Tensor): the input tensor 1149 dim (int or tuple of ints, optional): the dimension or dimensions to reduce. 1150 Default: None that is equivalent to ``tuple(range(input.ndim))``. 1151 unbiased (bool): when True, use Bessel's correction, otherwise, compute 1152 the uncorrected sample variance. 1153 1154Keyword args: 1155 keepdim (bool, optional): whether the output tensor has 1156 :attr:`dim` retained or not. Default: False. 1157 dtype (:class:`torch.dtype`, optional): the desired data type 1158 of returned tensor. If specified, the input tensor is 1159 casted to :attr:`dtype` before the operation is 1160 performed. Default: None. 1161 mask (:class:`torch.Tensor`, optional): the boolean tensor 1162 containing the binary mask of validity of input tensor 1163 elements. 1164 Default: None that is equivalent to ``torch.ones(input.shape, dtype=torch.bool)``. 1165Example:: 1166 1167 >>> input = tensor([[-3, -2, -1], [ 0, 1, 2]]) 1168 >>> input 1169 tensor([[-3, -2, -1], 1170 [ 0, 1, 2]]) 1171 >>> mask = tensor([[ True, False, True], [False, False, False]]) 1172 >>> mask 1173 tensor([[ True, False, True], 1174 [False, False, False]]) 1175 >>> torch.masked._ops.var(input, 1, False, mask=mask) 1176 tensor([1., nan]) 1177""" 1178