<commit_before><a name="torch.maths.dok"/>
# Math Functions #

Torch provides Matlab-like functions for manipulating
[Tensor](README.md#Tensor) objects.  Functions fall into several types of
categories:
  * [constructors](#torch.construction.dok) like [zeros](#torch.zeros), [ones](#torch.ones)
  * extractors like  [diag](#torch.diag)  and [triu](#torch.triu),
  * [Element-wise](#torch.elementwise.dok) mathematical operations like [abs](#torch.abs) and [pow](#torch.pow),
  * [BLAS](#torch.basicoperations.dok) operations,
  * [column or row-wise operations](#torch.columnwise.dok) like [sum](#torch.sum) and [max](#torch.max),
  * [matrix-wide operations](#torch.matrixwide.dok) like [trace](#torch.trace) and [norm](#torch.norm).
  * [Convolution and cross-correlation](#torch.conv.dok) operations like [conv2](#torch.conv2).
  * [Basic linear algebra operations](#torch.linalg.dok) like [eigen value/vector calculation](#torch.eig).
  * [Logical Operations on Tensors](#torch.logical.dok).

By default, all operations allocate a new tensor to return the
result. However, all functions also support passing the target
tensor(s) as the first argument(s), in which case the target tensor(s)
will be resized accordingly and filled with result. This property is
especially useful when one wants have tight control over when memory
is allocated.

The torch package adopts the same concept, so that calling a function
directly on the tensor itself using an object-oriented syntax is
equivalent to passing the tensor as the optional resulting tensor. The
following two calls are equivalent.

```lua
torch.log(x,x)
x:log()
```

Similarly, `torch.conv2` function can be used in the following manner.
```lua

x = torch.rand(100,100)
k = torch.rand(10,10)
res1 = torch.conv2(x,k)

res2 = torch.Tensor()
torch.conv2(res2,x,k)

=res2:dist(res1)
0

```

The advantage of second case is, same `res2` tensor can be used successively in a loop without any new allocation.

```lua
-- no new memory allocations...
for i=1,100 do
    torch.conv2(res2,x,k)
end
=res2:dist(res1)
0
```

<a name="torch.construction.dok"/>
## Construction or extraction functions ##

<a name="torch.cat"/>
### [res] torch.cat( [res,] x_1, x_2, [dimension] ) ###
<a name="torch.Tensor.cat"/>
`x=torch.cat(x_1,x_2,[dimension])` returns a tensor `x` which is the concatenation of tensors x_1 and x_2 along dimension `dimension`. 

If `dimension` is not specified it is the last dimension.

The other dimensions of x_1 and x_2 have to be equal.

Examples:
```lua
> print(torch.cat(torch.ones(3),torch.zeros(2)))

 1
 1
 1
 0
 0
[torch.Tensor of dimension 5]


> print(torch.cat(torch.ones(3,2),torch.zeros(2,2),1))

 1  1
 1  1
 1  1
 0  0
 0  0
[torch.DoubleTensor of dimension 5x2]


> print(torch.cat(torch.ones(2,2),torch.zeros(2,2),1))
 1  1
 1  1
 0  0
 0  0
[torch.DoubleTensor of dimension 4x2]

> print(torch.cat(torch.ones(2,2),torch.zeros(2,2),2))
 1  1  0  0
 1  1  0  0
[torch.DoubleTensor of dimension 2x4]


> print(torch.cat(torch.cat(torch.ones(2,2),torch.zeros(2,2),1),torch.rand(3,2),1))

 1.0000  1.0000
 1.0000  1.0000
 0.0000  0.0000
 0.0000  0.0000
 0.3227  0.0493
 0.9161  0.1086
 0.2206  0.7449
[torch.DoubleTensor of dimension 7x2]

```


<a name="torch.diag"/>
### [res] torch.diag([res,] x [,k]) ###
<a name="torch.Tensor.diag"/>

`y=torch.diag(x)` when x is of dimension 1 returns a diagonal matrix with diagonal elements constructed from x.

`y=torch.diag(x)` when x is of dimension 2 returns a tensor of dimension 1
with elements constructed from the diagonal of x.

`y=torch.diag(x,k)` returns the k-th diagonal of x,
wher k=0 is the main diagonal, k>0 is above the main diagonal and k<0 
is below the main diagonal.

<a name="torch.eye"/>
### [res] torch.eye([res,] n [,m]) ###
<a name="torch.Tensor.eye"/>

`y=torch.eye(n)` returns the n-by-n identity matrix.

`y=torch.eye(n,m)` returns an m-by-m identity matrix with ones on the diagonal and zeros elsewhere.


<a name="torch.linspace"/>
### [res] torch.linspace([res,] x1, x2, [,n]) ###
<a name="torch.Tensor.linspace"/>

`y=torch.linspace(x1,x2)` returns a one-dimensional tensor of size 100 equally spaced points between x1 and x2.

`y=torch.linspace(x1,x2,n)` returns a one-dimensional tensor of n equally spaced points between x1 and x2.


<a name="torch.logspace"/>
### [res] torch.logspace([res,] x1, x2, [,n]) ###
<a name="torch.Tensor.logspace"/>

`y=torch.logspace(x1,x2)` returns a one-dimensional tensor of 50 logarithmically eqally spaced points between x1 and x2.

`y=torch.logspace(x1,x2,n)` returns a one-dimensional tensor of n logarithmically equally spaced points between x1 and x2.

<a name="torch.multinomial"/>
### [res] torch.multinomial([res,], p, n, [,flag]) ###
<a name="torch.Tensor.multinomial"/>

`y=torch.multinomial(p,n)` returns a tensor `y` where each row contains
`n` indices sampled __with replacement__ (`flag=true`) from the <commit_msg>Fix typo of n by m<commit_after><a name="torch.maths.dok"/>
# Math Functions #

Torch provides Matlab-like functions for manipulating
[Tensor](README.md#Tensor) objects.  Functions fall into several types of
categories:
  * [constructors](#torch.construction.dok) like [zeros](#torch.zeros), [ones](#torch.ones)
  * extractors like  [diag](#torch.diag)  and [triu](#torch.triu),
  * [Element-wise](#torch.elementwise.dok) mathematical operations like [abs](#torch.abs) and [pow](#torch.pow),
  * [BLAS](#torch.basicoperations.dok) operations,
  * [column or row-wise operations](#torch.columnwise.dok) like [sum](#torch.sum) and [max](#torch.max),
  * [matrix-wide operations](#torch.matrixwide.dok) like [trace](#torch.trace) and [norm](#torch.norm).
  * [Convolution and cross-correlation](#torch.conv.dok) operations like [conv2](#torch.conv2).
  * [Basic linear algebra operations](#torch.linalg.dok) like [eigen value/vector calculation](#torch.eig).
  * [Logical Operations on Tensors](#torch.logical.dok).

By default, all operations allocate a new tensor to return the
result. However, all functions also support passing the target
tensor(s) as the first argument(s), in which case the target tensor(s)
will be resized accordingly and filled with result. This property is
especially useful when one wants have tight control over when memory
is allocated.

The torch package adopts the same concept, so that calling a function
directly on the tensor itself using an object-oriented syntax is
equivalent to passing the tensor as the optional resulting tensor. The
following two calls are equivalent.

```lua
torch.log(x,x)
x:log()
```

Similarly, `torch.conv2` function can be used in the following manner.
```lua

x = torch.rand(100,100)
k = torch.rand(10,10)
res1 = torch.conv2(x,k)

res2 = torch.Tensor()
torch.conv2(res2,x,k)

=res2:dist(res1)
0

```

The advantage of second case is, same `res2` tensor can be used successively in a loop without any new allocation.

```lua
-- no new memory allocations...
for i=1,100 do
    torch.conv2(res2,x,k)
end
=res2:dist(res1)
0
```

<a name="torch.construction.dok"/>
## Construction or extraction functions ##

<a name="torch.cat"/>
### [res] torch.cat( [res,] x_1, x_2, [dimension] ) ###
<a name="torch.Tensor.cat"/>
`x=torch.cat(x_1,x_2,[dimension])` returns a tensor `x` which is the concatenation of tensors x_1 and x_2 along dimension `dimension`. 

If `dimension` is not specified it is the last dimension.

The other dimensions of x_1 and x_2 have to be equal.

Examples:
```lua
> print(torch.cat(torch.ones(3),torch.zeros(2)))

 1
 1
 1
 0
 0
[torch.Tensor of dimension 5]


> print(torch.cat(torch.ones(3,2),torch.zeros(2,2),1))

 1  1
 1  1
 1  1
 0  0
 0  0
[torch.DoubleTensor of dimension 5x2]


> print(torch.cat(torch.ones(2,2),torch.zeros(2,2),1))
 1  1
 1  1
 0  0
 0  0
[torch.DoubleTensor of dimension 4x2]

> print(torch.cat(torch.ones(2,2),torch.zeros(2,2),2))
 1  1  0  0
 1  1  0  0
[torch.DoubleTensor of dimension 2x4]


> print(torch.cat(torch.cat(torch.ones(2,2),torch.zeros(2,2),1),torch.rand(3,2),1))

 1.0000  1.0000
 1.0000  1.0000
 0.0000  0.0000
 0.0000  0.0000
 0.3227  0.0493
 0.9161  0.1086
 0.2206  0.7449
[torch.DoubleTensor of dimension 7x2]

```


<a name="torch.diag"/>
### [res] torch.diag([res,] x [,k]) ###
<a name="torch.Tensor.diag"/>

`y=torch.diag(x)` when x is of dimension 1 returns a diagonal matrix with diagonal elements constructed from x.

`y=torch.diag(x)` when x is of dimension 2 returns a tensor of dimension 1
with elements constructed from the diagonal of x.

`y=torch.diag(x,k)` returns the k-th diagonal of x,
wher k=0 is the main diagonal, k>0 is above the main diagonal and k<0 
is below the main diagonal.

<a name="torch.eye"/>
### [res] torch.eye([res,] n [,m]) ###
<a name="torch.Tensor.eye"/>

`y=torch.eye(n)` returns the n-by-n identity matrix.

`y=torch.eye(n,m)` returns an n-by-m identity matrix with ones on the diagonal and zeros elsewhere.


<a name="torch.linspace"/>
### [res] torch.linspace([res,] x1, x2, [,n]) ###
<a name="torch.Tensor.linspace"/>

`y=torch.linspace(x1,x2)` returns a one-dimensional tensor of size 100 equally spaced points between x1 and x2.

`y=torch.linspace(x1,x2,n)` returns a one-dimensional tensor of n equally spaced points between x1 and x2.


<a name="torch.logspace"/>
### [res] torch.logspace([res,] x1, x2, [,n]) ###
<a name="torch.Tensor.logspace"/>

`y=torch.logspace(x1,x2)` returns a one-dimensional tensor of 50 logarithmically eqally spaced points between x1 and x2.

`y=torch.logspace(x1,x2,n)` returns a one-dimensional tensor of n logarithmically equally spaced points between x1 and x2.

<a name="torch.multinomial"/>
### [res] torch.multinomial([res,], p, n, [,flag]) ###
<a name="torch.Tensor.multinomial"/>

`y=torch.multinomial(p,n)` returns a tensor `y` where each row contains
`n` indices sampled __with replacement__ (`flag=true`) from the 
{'fraction_non_alphanumeric': 0.14647028948704927, 'fraction_numerical': 0.04164550533265617, 'mean_word_length': 4.600682593856655, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 43, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7166547', 'n_tokens_mistral': 3718, 'n_tokens_neox': 3569, 'n_words': 1101}