# Arithmetic
### `+max`
Yield the maximum value in an array.
**Accepts**
A `$ray`.
**Produces**
A `$ray`.
**Source**
```hoon
++ max
~/ %max
|= a=ray
?> (check a)
=/ fun
|: [b=1 c=-:(ravel a)]
?. =(((fun-scalar meta.a %gth) b c) 0)
b c
(scalar-to-ray meta.a (reel (ravel a) fun))
```
***
### `+argmax`
Yield the index of the maximum value in an array. Only returns the first match.
**Accepts**
A `$ray`.
**Produces**
A `@ud`.
**Source**
```hoon
++ argmax :: Only returns first match
~/ %argmax
|= a=ray
^- @ud
?> (check a)
+:(find ~[(get-item (max a) ~[0 0])] (ravel a))
```
***
### `+min`
Yield the minimum value in an array.
**Accepts**
A `$ray`.
**Produces**
A `$ray`.
**Source**
```hoon
++ min
~/ %min
|= a=ray
?> (check a)
=/ fun
|: [b=1 c=-:(ravel a)]
?. =(((fun-scalar meta.a %lth) b c) 0)
b c
(scalar-to-ray meta.a (reel (ravel a) fun))
```
***
### `+argmin`
Yield the index of the minimum value in an array. Only returns the first match.
**Accepts**
A `$ray`.
**Produces**
A `@ud`.
**Source**
```hoon
++ argmin :: Only returns first match
~/ %argmin
|= a=ray
^- @ud
?> (check a)
+:(find ~[(get-item (min a) ~[0 0])] (ravel a))
```
***
### `+cumsum`
Yield the cumulative sum of an array.
**Accepts**
A `$ray`.
**Produces**
A `$ray`.
**Source**
```hoon
++ cumsum
~/ %cumsum
|= a=ray
^- ray
?> (check a)
%+ scalar-to-ray meta.a
(reel (ravel a) |=([b=@ c=@] ((fun-scalar meta.a %add) b c)))
```
***
### `+prod`
Yield the cumulative product of an array.
**Accepts**
A `$ray`.
**Produces**
A `$ray`.
**Source**
```hoon
++ prod
|= a=ray
^- ray
?> (check a)
%+ scalar-to-ray meta.a
(reel (ravel a) |=([b=_1 c=_1] ((fun-scalar meta.a %mul) b c)))
```
***
### `+diag`
Return the diagonal of an array. Enforces that the array is square, and returns a 2D ($n \times 1$) array of the diagonal elements.
**Accepts**
A `$ray`.
**Produces**
A `$ray`.
**Source**
```hoon
++ diag
~/ %diag
|= a=ray
^- ray
?> (check a)
=, meta.a
?> =(2 (lent shape))
?> =(-.shape +<.shape)
^- ray
%- en-ray
^- baum
:- `meta`[~[-.shape 1] bloq kind tail]
^- ndray
%+ turn
`(list @)`(flop (gulf 0 (dec -.shape)))
|=(i=@ (get-item a ~[i i]))
```
***
### `+trace`
Compute the trace of an array.
**Accepts**
A `$ray`.
**Produces**
A `$ray`.
**Source**
```hoon
++ trace
~/ %trace
|= a=ray
^- ray
(cumsum (diag a))
```
***
### `+dot`
Dot product of two arrays.
**Accepts**
A pair of `$ray`s with the same shape.
**Produces**
A `$ray`.
**Source**
```hoon
++ dot
~/ %dot
|= [a=ray b=ray]
^- ray
?> =(shape.meta.a shape.meta.b)
(cumsum (mul a b))
```
***
### `+mmul`
Multiply two matrices (linear algebra).
**Accepts**
Parameters as specified in source
**Produces**
See source for return type details.
**Source**
```hoon
++ mmul
~/ %mmul
|= [a=ray b=ray]
?> (check a)
?> (check b)
=/ i 0
=/ j 0
=/ k 0
=/ shape=(list @) ~[(snag 0 shape.meta.a) (snag 1 shape.meta.b)]
=/ prod=ray =,(meta.a (zeros [^shape bloq kind ~]))
::
:: multiplication conditions
?>
?& =(2 (lent shape.meta.b))
=(2 (lent shape.meta.a))
=((snag 1 shape.meta.a) (snag 0 shape.meta.b))
==
|-
?: =(i (snag 0 shape.meta.prod))
prod
%= $
i +(i)
prod
|-
?: =(j (snag 1 shape.meta.prod))
prod
=/ cume 0
%= $
j +(j)
prod
|-
?: =(k (snag 1 shape.meta.a))
(set-item prod `(list @)`~[i j] cume)
%= $
k +(k)
cume
%+ (fun-scalar meta.a %add)
cume
%+ (fun-scalar meta.a %mul)
(get-item a ~[i k])
(get-item b ~[k j])
==
==
==
```
***
### `+abs`
Yield the absolute value of each element of an array as an array.
**Accepts**
A `$ray`.
**Produces**
A `$ray`.
**Source**
```hoon
++ abs
~/ %abs
|= a=ray
^- ray
(el-wise-op a (trans-scalar bloq.meta.a kind.meta.a %abs))
```
***
### `+add-scalar`
Yield the sum of an array and a scalar.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ add-scalar
~/ %add-scal
|= [a=ray n=@]
^- ray
=/ b=ray (fill meta.a n)
(add a b)
```
***
### `+sub-scalar`
Yield the difference of an array and a scalar.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ sub-scalar
~/ %sub-scal
|= [a=ray n=@]
^- ray
=/ b=ray (fill meta.a n)
(sub a b)
```
***
### `+mul-scalar`
Yield the product of an array and a scalar.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ mul-scalar
~/ %mul-scal
|= [a=ray n=@]
^- ray
=/ b=ray (fill meta.a n)
(mul a b)
```
***
### `+div-scalar`
Yield the quotient of an array and a scalar.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ div-scalar
~/ %div-scal
|= [a=ray n=@]
^- ray
=/ b=ray (fill meta.a n)
(div a b)
```
***
### `+mod-scalar`
Yield the modulus of an array and a scalar.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ mod-scalar
~/ %mod-scal
|= [a=ray n=@]
^- ray
=/ b=ray (fill meta.a n)
(mod a b)
```
***
### `+add`
Add two arrays element-wise.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ add
~/ %add-rays
|= [a=ray b=ray]
^- ray
(bin-op a b (fun-scalar meta.a %add))
```
***
### `+sub`
Subtract two arrays element-wise.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ sub
~/ %sub-rays
|= [a=ray b=ray]
^- ray
(bin-op a b (fun-scalar meta.a %sub))
```
***
### `+mul`
Multiply two arrays element-wise.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ mul
~/ %mul-rays
|= [a=ray b=ray]
^- ray
(bin-op a b (fun-scalar meta.a %mul))
```
***
### `+div`
Divide two arrays element-wise.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ div
~/ %div-rays
|= [a=ray b=ray]
^- ray
(bin-op a b (fun-scalar meta.a %div))
```
***
### `+mod`
Yield the modulus of two arrays element-wise.
**Accepts**
A pair of `$ray`s with the same shape.
**Produces**
A `$ray`.
**Source**
```hoon
++ mod
~/ %mod-rays
|= [a=ray b=ray]
^- ray
(bin-op a b (fun-scalar meta.a %mod))
```
***
### `+pow-n`
Raise a `$ray` to the power of an integer $$n$$.
**Accepts**
A `$ray` and an integer power `.n` (as `@ud` not `@r`).
**Produces**
A `$ray`.
**Source**
```hoon
++ pow-n
|= [a=ray n=@ud]
^- ray
?> (check a)
?~ =(0 n) (ones meta.a)
=/ b=ray a
|- ^- ray
?~ =(1 n) b
$(b (mul a b), n (dec n))
```
***
### `+gth`
Return the element-wise `>` greater-than comparison of two arrays, yielding a boolean array.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ gth
~/ %gth
|= [a=ray b=ray]
^- ray
(bin-op a b (fun-scalar meta.a %gth))
```
***
### `+gte`
Return the element-wise `>=` greater-than-or-equal-to comparison of two arrays, yielding a boolean array.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ gte
~/ %gte
|= [a=ray b=ray]
^- ray
(bin-op a b (fun-scalar meta.a %gte))
```
***
### `+lth`
Return the element-wise `<` less-than comparison of two arrays, yielding a boolean array.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ lth
~/ %lth
|= [a=ray b=ray]
^- ray
(bin-op a b (fun-scalar meta.a %lth))
```
***
### `+lte`
Return the element-wise `<=` less-than-or-equal-to comparison of two arrays, yielding a boolean array.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ lte
~/ %lte
|= [a=ray b=ray]
^- ray
(bin-op a b (fun-scalar meta.a %lte))
```
***
### `+equ`
Return the element-wise `==` equality comparison of two arrays, yielding a boolean array.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ equ
|= [a=ray b=ray]
^- ray
(bin-op a b (fun-scalar meta.a %equ))
```
***
### `+neq`
Return the element-wise `!=` inequality comparison of two arrays, yielding a boolean array.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ neq
|= [a=ray b=ray]
^- ray
(bin-op a b (fun-scalar meta.a %neq))
```
***
### `+mpow-n`
Raise a matrix to the power of an integer $$n$$.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ mpow-n
|= [a=ray n=@ud]
^- ray
?~ =(0 n) (ones meta.a)
=/ b=ray a
|- ^- ray
?~ =(1 n) b
$(b (mmul a b), n (dec n))
```
***
### `+is-close`
Check if two arrays are close to each other within a specified tolerance, in absolute or relative terms.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ is-close
|= [a=ray b=ray tol=[@ @]]
^- ray
?> =(shape.meta.a shape.meta.b)
=/ atol (fill meta.a data:(scale meta.a -.tol))
=/ rtol (fill meta.a data:(scale meta.a +.tol))
(lte (abs (sub a b)) (add atol (mul rtol (abs b))))
```
***
### `+any`
Check if any element in an array is loobean false.
**Accepts**
Parameters as specified in source
**Produces**
See source for return type details.
**Source**
```hoon
++ any
|= [a=ray]
^- ?(%.y %.n)
(^lth (get-item (cumsum a) ~[0]) (roll shape.meta.a ^mul))
```
***
### `+all`
Check if all elements in an array are loobean true.
**Accepts**
Parameters as specified in source
**Produces**
See source for return type details.
**Source**
```hoon
++ all
|= [a=ray]
^- ?(%.y %.n)
=((get-item (cumsum a) ~[0]) 0)
```
***
### `+fun-scalar`
Utility function to process a scalar function.
**Accepts**
Parameters as specified in source
**Produces**
A `$-([@ @] @)` gate.
**Source**
```hoon
++ fun-scalar
|= [=meta fun=ops]
^- $-([@ @] @)
=, meta
?- `^kind`kind
%uint
?+ fun !!
%add ~(sum fe bloq)
%sub ~(dif fe bloq)
%mul |=([b=_1 c=_1] (~(sit fe bloq) (^mul b c)))
%div |=([b=_1 c=_1] (~(sit fe bloq) (^div b c)))
%mod |=([b=@ c=@] (~(sit fe bloq) (^mod b c)))
%pow |=([b=@ c=@] (~(sit fe bloq) (pow b c)))
::%exp |=([b=@ c=@] (~(sit fe bloq) (^pow b c)))
::%log |=([b=@ c=@] (~(sit fe bloq) (^pow b c)))
%gth |=([b=@ c=@] !(^gth b c))
%gte |=([b=@ c=@] !(^gte b c))
%lth |=([b=@ c=@] !(^lth b c))
%lte |=([b=@ c=@] !(^lte b c))
%equ |=([b=@ c=@] ?:(.=(b c) 1 0))
%neq |=([b=@ c=@] ?:(.=(b c) 0 1))
==
::
%int2 !!
::
%i754
?+ `^bloq`bloq !!
%7
?+ fun !!
%add ~(add rq rnd)
%sub ~(sub rq rnd)
%mul ~(mul rq rnd)
%div ~(div rq rnd)
%mod |=([a=@rq b=@rq] (~(sub rq rnd) a (~(mul rq rnd) b (~(san rq rnd) (need (~(toi rq rnd) (~(div rq rnd) a b)))))))
%gth |=([a=@rq b=@rq] ?:((~(gth rq rnd) a b) .~~~1 .~~~0))
%gte |=([a=@rq b=@rq] ?:((~(gte rq rnd) a b) .~~~1 .~~~0))
%lth |=([a=@rq b=@rq] ?:((~(lth rq rnd) a b) .~~~1 .~~~0))
%lte |=([a=@rq b=@rq] ?:((~(lte rq rnd) a b) .~~~1 .~~~0))
%equ |=([a=@rq b=@rq] ?:(.=(a b) .~~~1 .~~~0))
%neq |=([a=@rq b=@rq] ?:(.=(a b) .~~~0 .~~~1))
==
%6
?+ fun !!
%add ~(add rd rnd)
%sub ~(sub rd rnd)
%mul ~(mul rd rnd)
%div ~(div rd rnd)
%mod |=([a=@rd b=@rd] (~(sub rd rnd) a (~(mul rd rnd) b (~(san rd rnd) (need (~(toi rd rnd) (~(div rd rnd) a b)))))))
%gth |=([a=@rd b=@rd] ?:((~(gth rd rnd) a b) .~1 .~0))
%gte |=([a=@rd b=@rd] ?:((~(gte rd rnd) a b) .~1 .~0))
%lth |=([a=@rd b=@rd] ?:((~(lth rd rnd) a b) .~1 .~0))
%lte |=([a=@rd b=@rd] ?:((~(lte rd rnd) a b) .~1 .~0))
%equ |=([a=@rd b=@rd] ?:(.=(a b) .~1 .~0))
%neq |=([a=@rd b=@rd] ?:(.=(a b) .~0 .~1))
==
%5
?+ fun !!
%add ~(add rs rnd)
%sub ~(sub rs rnd)
%mul ~(mul rs rnd)
%div ~(div rs rnd)
%mod |=([a=@rs b=@rs] (~(sub rs rnd) a (~(mul rs rnd) b (~(san rs rnd) (need (~(toi rs rnd) (~(div rs rnd) a b)))))))
%gth |=([a=@rs b=@rs] ?:((~(gth rs rnd) a b) .1 .0))
%gte |=([a=@rs b=@rs] ?:((~(gte rs rnd) a b) .1 .0))
%lth |=([a=@rs b=@rs] ?:((~(lth rs rnd) a b) .1 .0))
%lte |=([a=@rs b=@rs] ?:((~(lte rs rnd) a b) .1 .0))
%equ |=([a=@rs b=@rs] ?:(.=(a b) .1 .0))
%neq |=([a=@rs b=@rs] ?:(.=(a b) .0 .1))
==
%4
?+ fun !!
%add ~(add rh rnd)
%sub ~(sub rh rnd)
%mul ~(mul rh rnd)
%div ~(div rh rnd)
%mod |=([a=@rh b=@rh] (~(sub rh rnd) a (~(mul rh rnd) b (~(san rh rnd) (need (~(toi rh rnd) (~(div rh rnd) a b)))))))
%gth |=([a=@rh b=@rh] ?:((~(gth rh rnd) a b) .~~1 .~~0))
%gte |=([a=@rh b=@rh] ?:((~(gte rh rnd) a b) .~~1 .~~0))
%lth |=([a=@rh b=@rh] ?:((~(lth rh rnd) a b) .~~1 .~~0))
%lte |=([a=@rh b=@rh] ?:((~(lte rh rnd) a b) .~~1 .~~0))
%equ |=([a=@rh b=@rh] ?:(.=(a b) .~~1 .~~0))
%neq |=([a=@rh b=@rh] ?:(.=(a b) .~~0 .~~1))
==
== :: bloq real
== :: kind
```
***
### `+trans-scalar`
Utility function to produce a gate for scalar operations.
**Accepts**
Parameters as specified in source
**Produces**
A `$-(@ @)` gate.
**Source**
```hoon
++ trans-scalar
|= [=bloq =kind fun=ops]
^- $-(@ @)
?- kind
%uint
?+ fun !!
%abs |=(b=@ b)
==
::
%int2 !!
::
%i754
?+ bloq !!
%7
?+ fun !!
%abs |=(b=@ ?:((~(gte rq rnd) b .~~~0) b (~(mul rq rnd) b .~~~-1)))
==
%6
?+ fun !!
%abs |=(b=@ ?:((~(gte rd rnd) b .~0) b (~(mul rd rnd) b .~-1)))
==
%5
?+ fun !!
%abs |=(b=@ ?:((~(gte rs rnd) b .0) b (~(mul rs rnd) b .-1)))
==
%4
?+ fun !!
%abs |=(b=@ ?:((~(gte rh rnd) b .~~0) b (~(mul rh rnd) b .~~-1)))
==
==
==
::
```
***
### `+el-wise-op`
Utility function to operate element-wise on an array.
**Accepts**
```hoon
[a=ray fun=$-(@ @)]
```
**Produces**
A `$ray`.
**Source**
```hoon
++ el-wise-op
|= [a=ray fun=$-(@ @)]
^- ray
?> (check a)
%- spac
:- meta.a
=/ ali (flop (ravel a)) :: compensate for LSB
%+ rep bloq.meta.a
%+ turn
ali
|=(e=@ (fun e))
::
```
***
### `+bin-op`
Utility function to perform a binary operation on two arrays.
**Accepts**
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ bin-op
|= [a=ray b=ray op=$-([@ @] @)]
^- ray
?> =(meta.a meta.b)
?> (check a)
?> (check b)
%- spac
:- meta.a
=/ ali (ravel a)
=/ bob (ravel b)
%+ rep bloq.meta.a
%+ turn
(gulf 0 (dec (lent ali)))
|= i=@
(op (snag i ali) (snag i bob))
::
```
***
### `+ter-op`
Utility function to perform a ternary operation on three arrays.
**Accepts**
```hoon
[a=ray b=ray c=ray op=$-([@ @ @] @)]
```
Parameters as specified in source
**Produces**
A `$ray`.
**Source**
```hoon
++ ter-op
|= [a=ray b=ray c=ray op=$-([@ @ @] @)]
^- ray
?> =(meta.a meta.b)
?> =(meta.c meta.b)
?> (check a)
?> (check b)
?> (check c)
%- spac:la
:- meta.a
=/ ali (ravel:la a)
=/ bob (ravel:la b)
=/ car (ravel:la c)
%+ rep bloq.meta.a
%+ turn
(gulf 0 (dec (lent ali)))
|= i=@
(op (snag i ali) (snag i bob) (snag i car))
--
--
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.urbit.org/hoon/lagoon/math.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.