# Builders

### `+eye` <a href="#eye" id="eye"></a>

Identity matrix of shape nxn.

**Accepts**

A `$meta`.

**Produces**

A `$ray`.

**Source**

```hoon
++  eye      ::  produces identity matrix of shape nxn.
  |=  =meta
  ^-  ray
  ~_  leaf+"lagoon-fail"
  ?>  =(2 (lent shape.meta))
  ?>  =((snag 0 shape.meta) (snag 1 shape.meta))
  =/  n  (snag 0 shape.meta)
  =<  +
  %^    spin
      (gulf 0 (dec n))
    ^-  ray  (zeros [~[n n] bloq.meta kind.meta ~])
  |=  [i=@ r=ray]
  :: [i (set-item r ~[i i] 1)]
  :-  i
  %^  set-item
      r
    ~[i i]
  ^-  @
  ?-    kind.meta
      %uint  `@`1
    ::
      %int2  !!
    ::
      %i754
    ?+  bloq.meta  ~|(bloq.meta !!)
      %7  .~~~1
      %6  .~1
      %5  .1
      %4  .~~1
    ==
  ==
```

***

### `+zeros` <a href="#zeros" id="zeros"></a>

An array containing only zeros as values.

**Accepts**

A `$meta` of the target shape and parameters.

**Produces**

A `$ray`.

**Source**

```hoon
++  zeros
  |=  =meta  ^-  ray
  ~_  leaf+"lagoon-fail"
  :-  meta
  (lsh [bloq.meta (roll shape.meta ^mul)] 1)
```

***

### `+ones` <a href="#ones" id="ones"></a>

An array containing only ones as values.

**Accepts**

A `$meta` of the target shape and parameters.

**Produces**

A `$ray`.

**Source**

```hoon
++  ones
  |=  =meta  ^-  ray
  ~_  leaf+"lagoon-fail"
  =/  one
    ?-    kind.meta
        %uint  `@`1
      ::
        %int2  !!
      ::
        %i754
      ?+  bloq.meta  !!
        %7  .~~~1
        %6  .~1
        %5  .1
        %4  .~~1
      ==
    ==
  (fill meta one)
```

***

### `+iota` <a href="#iota" id="iota"></a>

Produce a 1-dimensional index array. Only produces `%uint`. Note that this runs from 0 to $$n-1$$. (The point of `+iota` is to be an index, so it needs to pattern-match the context rather than slavishly follow APL.)

**Accepts**

A `$meta` of the target shape and parameters.

**Produces**

A `$ray`.

**Source**

```hoon
++  iota
  |=  =meta
  ^-  ray
  ?>  =((lent shape.meta) 1)
  =/  n  (snag 0 shape.meta)
  =.  kind.meta  %uint
  (en-ray meta (gulf 0 (dec n)))
```

**Discussion**

The target shape is determined from the length of `.shape` in `.meta`.

***

### `+magic` <a href="#magic" id="magic"></a>

Produce a magic square in $$n$$ dimensions.

**Accepts**

A `$meta` of the target shape and parameters.

**Produces**

A `$ray`.

**Source**

```hoon
++  magic
  |=  =meta
  ^-  ray
  =/  n  (roll shape.meta ^mul)
  %+  reshape
    (en-ray [~[n] bloq.meta %uint ~] (gulf 0 (dec n)))
  shape.meta
```

***

### `+range` <a href="#range" id="range"></a>

Produce a 1-dimensional range along one dimension as $$\[a, b)$$ with interval $$d$$. Only produces `%i754`.

**Accepts**

A `$meta` of the target shape and parameters.

**Produces**

A `$ray`.

**Source**

```hoon
++  range
  ~/  %range
  |=  [=meta [a=@ b=@] d=@]
  ^-  ray
  =.  kind.meta  %i754
  %-  spac
  %-  en-ray
  ::
  ?+    bloq.meta  !!
      %7
    =/  ba  (~(sub rq rnd) b a)
    =/  bad  `(list @)`~[a]
    |-  ^-  baum
    ?:  (?:((~(lth rq rnd) ba .~~~0) ~(lte rq rnd) ~(gte rq rnd)) (~(add rq rnd) (snag 0 bad) d) b)
      =.  shape.meta  ~[(lent bad)]
      [meta (flop bad)]
    $(bad [(~(add rq rnd) (snag 0 bad) d) bad])
    ::
      %6
    =/  ba  (~(sub rd rnd) b a)
    =/  bad  `(list @)`~[a]
    |-  ^-  baum
    ?:  (?:((~(lth rd rnd) ba .~0) ~(lte rd rnd) ~(gte rd rnd)) (~(add rd rnd) (snag 0 bad) d) b)
      =.  shape.meta  ~[(lent bad)]
      [meta (flop bad)]
    $(bad [(~(add rd rnd) (snag 0 bad) d) bad])
    ::
      %5
    =/  ba  (~(sub rs rnd) b a)
    =/  bad  `(list @)`~[a]
    |-  ^-  baum
    ?:  (?:((~(lth rs rnd) ba .0) ~(lte rs rnd) ~(gte rs rnd)) (~(add rs rnd) (snag 0 bad) d) b)
      =.  shape.meta  ~[(lent bad)]
      [meta (flop bad)]
    $(bad [(~(add rs rnd) (snag 0 bad) d) bad])
    ::
      %4
    =/  ba  (~(sub rh rnd) b a)
    =/  bad  `(list @)`~[a]
    |-  ^-  baum
    ?:  (?:((~(lth rh rnd) ba .~~0) ~(lte rh rnd) ~(gte rh rnd)) (~(add rh rnd) (snag 0 bad) d) b)
      [meta (flop bad)]
    $(bad [(~(add rh rnd) (snag 0 bad) d) bad])
  ==
```

***

### `+linspace` <a href="#linspace" id="linspace"></a>

Produce a 1-dimensional range along one dimension as $$\[a, b]$$ with number of steps $$n$$. Only produces `%i754`.

**Accepts**

A `$meta` of the target shape and parameters, a pair of left-hand and right-hand bounds, and a number of intervals.

**Produces**

A `$ray`.

**Source**

```hoon
++  linspace
  ~/  %linspace
  |=  [=meta [a=@ b=@] n=@ud]
  ^-  ray
  =.  shape.meta  ~[n]
  =.  kind.meta  %i754
  ?<  =(n 0)
  ?:  =(n 1)  (en-ray meta ~[a])
  %-  en-ray
  :-  meta
  ::
  ?+    bloq.meta  !!
      %7
    =/  ba  (~(sub rq rnd) b a)
    =/  d  (~(div rq rnd) ba (~(sun rq rnd) (dec n)))
    =|  bad=(list @)
    =|  i=@ud
    |-  ^-  ndray
    ?:  (^lte n +(i))  (flop [b bad])
    $(i +(i), bad [(~(add rq rnd) a (~(mul rq rnd) (~(sun rq rnd) i) d)) bad])
    ::
      %6
    =/  ba  (~(sub rd rnd) b a)
    =/  d  (~(div rd rnd) ba (~(sun rd rnd) (dec n)))
    =|  bad=(list @)
    =|  i=@ud
    |-  ^-  ndray
    ?:  (^lte n +(i))  (flop [b bad])
    $(i +(i), bad [(~(add rd rnd) a (~(mul rd rnd) (~(sun rd rnd) i) d)) bad])
    ::
      %5
    =/  ba  (~(sub rs rnd) b a)
    =/  d  (~(div rs rnd) ba (~(sun rs rnd) (dec n)))
    =|  bad=(list @)
    =|  i=@ud
    |-  ^-  ndray
    ?:  (^lte n +(i))  (flop [b bad])
    $(i +(i), bad [(~(add rs rnd) a (~(mul rs rnd) (~(sun rs rnd) i) d)) bad])
    ::
      %4
    =/  ba  (~(sub rh rnd) b a)
    =/  d  (~(div rh rnd) ba (~(sun rh rnd) (dec n)))
    =|  bad=(list @)
    =|  i=@ud
    |-  ^-  ndray
    ?:  (^lte n +(i))  (flop [b bad])
    $(i +(i), bad [(~(add rh rnd) a (~(mul rh rnd) (~(sun rh rnd) i) d)) bad])
  ==
```

**Discussion**

The number of intervals `n` overrides any size specified in the input `$meta`.

***

### `+urge` <a href="#urge" id="urge"></a>

Coerce 1D array along specified dimension with given overall dimensionality.

**Accepts**

A `$ray`, a target dimension index `.i`, and a resulting overall dimensionality `.n`.

**Produces**

A `$ray`.

**Source**

```hoon
++  urge
  |=  [=ray [i=@ud n=@ud]]
  ^-  ^ray
  ?>  =(1 (lent shape.meta.ray))
  =.  shape.meta.ray  `(list @)`(zing (reap n ~[1]))
  =.  shape.meta.ray  (snap shape.meta.ray i n)
  |-
  ray
```

***

### `+scale` <a href="#scale" id="scale"></a>

Produce an $$n$$-dimensional array containing a single value.

**Accepts**

A `$meta` of the target shape and parameters, and the single value as an atom.

**Produces**

A `$ray`.

**Source**

```hoon
++  scale
  |=  [=meta data=@]
  ^-  ray
  =.  shape.meta  `(list @)`(zing (reap (lent shape.meta) ~[1]))
  ?-    kind.meta
      %uint
    (spac [meta `@ux`data])
    ::
      %int2
    (spac [meta `@ux`data])
    ::
      %i754
    ::  convert date to fl to @r XXX TODO REVISIT whether we want to specify input type
    =/  fin
      ?+    bloq.meta  !!
        %7  (bit:ma:rq (sea:ma:rq data))
        %6  (bit:ma:rd (sea:ma:rd data))
        %5  (bit:ma:rs (sea:ma:rs data))
        %4  (bit:ma:rh (sea:ma:rh data))
      ==
    (spac [meta `@ux`fin])
  ==
```


---

# 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/build.md?ask=<question>
```

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.