Skip to main content

•prefs — Session settings

•prefs Y applies the settings in the record Y for the whole process, and returns every setting except seed. The result is shy when Y sets something, as an assignment’s is. •prefs ⍬ changes nothing, and shows every setting.

Setting Holds Default
box $t draws matrices and nested arrays in boxes. Simple vectors and strings stay plain $t in the REPL, the BPL Jupyter kernel and IPython once it loads BPL’s magics, $f elsewhere
trees $t shows functions and dissected expressions as trees; $f uses linear notation. Independent of box as box
fns $f leaves output made inside functions unboxed as box
dissect $t shows the bound expression before each normal result, using trees $f
fusion $t writes a line for each call that computes a pending result, as described below $f
limit The most items display shows in full. ∞ shows every item 1000
edges Positions shown at each end of a long axis 3
prec Significant digits shown for each float. ∞ shows every digit 10
width The widest line display shows. ∞ allows any width The terminal’s width in the REPL, ∞ elsewhere
notation Generated function and operator notation: "apl", "simplified" or "traditional" "apl"
hanzi_aliases $t enables Hanzi glyph aliases. Other Hanzi remain name characters. Requires a leading declaration on a literal record $f
mathish $t applies Mathish mode to Mathish types under dynamic kinds $t
float The width of new floats in bits, 16, 32 or 64 64
kinds "static" makes each result’s kind follow from its arguments’ kinds and these settings alone. "dynamic" lets some functions choose it from values, as described below "dynamic"
int The width of integers in bits under static kinds, 32 or 64 32
threads The number of threads that large calls split across. 0 gives the default. 1 keeps every call on one thread 0
batch $t lets each map call its operand once on all its cells together, as described below $t
seed A nonnegative whole number that seeds the session’s random numbers A seed from the operating system

Display shows part of an array of more than limit items: the first and last edges positions of each axis longer than twice edges. … replaces hidden columns, ⋮ hidden rows, and ⋱ sits where they cross. A nested array follows the same rule on its own. So does an array that a function holds, such as ι10000 in (ι10000)↣+. A line wider than width keeps as many positions at each end as fit.

Character vectors display as quoted strings, including inside arrays and with box on. Embedded quotes are doubled and line breaks stay as line breaks. Other control characters display as escapes such as \t. limit counts characters in a single-line string and lines in a multiline string. A preview keeps a prefix and up to edges trailing characters or lines, with … or a ⋮ line between. At least half the budget goes to the prefix. Long lines use the same prefix-and-tail rule to fit width.

⎕← always shows every item and rounds floats to prec as display does. ⍕ and source text always hold every item and every digit. "-" •nput text writes raw text without quotes or truncation.

notation changes generated function and operator displays, including trees and dissected expressions. Dfn source, strings, record keys and field separators stay unchanged. Generated source and structural APIs keep canonical APL spellings.

hanzi_aliases controls accepted input independently of notation. Put •prefs ["hanzi_aliases":$t] before any other code to enable Hanzi glyph spellings. The setting persists across notebook cells and REPL inputs. Loaded files use and update the same preferences as their caller. See Hanzi spellings.

Static calculations ignore mathish. •prefs ⍬ still reports its configured value.

float sets the default width of floats, in bits: the width of bare numbers in code parsed after the change, of numbers that •csv, •json, •vfi and •image read, of random numbers, and of floats that a function gives from exact arguments. Until float is set, that width follows kinds: 64 bits under dynamic kinds and 32 under static kinds. Once set, it holds under both. Code already parsed keeps its numbers. A change partway through some code therefore applies from the next input, or from text that ⍎ parses later. Leading •prefs calls on a literal record are the exception. They run before the rest of their code is parsed, as in the examples below. A script, a notebook cell, a line typed at the REPL, a module that •load runs and text that ⍎ runs can each set its own width this way. See Numbers.

kinds sets whether a result’s kind can depend on its arguments’ values. Under the default, "dynamic", √¯4 gives 0ⱼ2, 1j0 reads as the float 1, and ⌊2.5 gives the exact integer 2. Under "static", each result’s kind follows from the function, its arguments’ kinds and these settings. Real arguments give real results, with NaN outside a function’s domain. Complex results stay complex. ⌊, ⌈ and monadic × of floats give floats, where ⌊ₓ, ⌈ₓ and ×ₓ give integers, converting as Rust’s as does. Integers compute at the int width, or at a wider integer’s width, and wrap where a result doesn’t fit. Exact fractions stay exact. An integer beside a float takes the float’s width. An atom promotes as an array does. A fused group and a GPU need each result’s kind before they run. Under static kinds more calls join a fused group, as Performance shows. A literal reads under the settings in force when its code is parsed, as with float. See Numbers.

threads sets how many threads large calls split across. A call splits only when it has enough work to repay the extra threads. Float results can differ in their last bits between thread counts. The default, 0, uses the number in the RAYON_NUM_THREADS environment variable where it’s set, and one thread for each core otherwise. 1 runs every call on the thread that evaluates the code. When several BPL processes run at once, such as a pool of Python workers, set 1 in each of them to keep them from competing for the cores. The browser build runs every call on one thread, whatever the setting.

With batch on, a map calls its operand once on all its cells together where it can, as Evaluation describes. With batch set to $f, every map calls its operand once for each cell. Floating results follow Accuracy. Seeded draws can differ.

seed restarts the session’s random numbers from the seed given. Draws of ¿ and a distribution’s sample need not agree across batching, thread counts, execution routes or builds. The settings that •prefs returns leave seed out because the stream moves on with each draw. Restoring saved settings never reseeds it.

fusion shows where large computations stop waiting. Calls on large arrays wait, and then run together as a fused group, as Calls that wait describes. With fusion set to $t, the innermost call that computes items of a pending result writes a line naming its function and position, such as fusion ends at ⍋ (<input>:1:46). A reduction such as +/ of a pending result runs with the fused group and writes nothing. A pending call uses the settings that were in force when it was called.

•explain records the same calls in its forced field. Here monadic ⌊ computes the pending result of y×2:

y←¿1000000ρ0
(•explain "+/⌊y×2").forced.function         ⍝ ["⌊"]
•prefs ["mathish":$f] ◇ 0.3=0.1+0.2    ⍝ $f
•prefs ["mathish":$t] ◇ 0.3=0.1+0.2    ⍝ $t
1ₛ=1.0000001ₛ                        ⍝ $f
•prefs ["kinds":"static"] ◇ (•storage 1.5).kind    ⍝ "float32"
•prefs ["float":32] ◇ (•storage 1.5).kind    ⍝ "float32"
•prefs ["float":64] ◇ (•storage 1.5).kind    ⍝ "float64"
•prefs ["threads":1] ◇ "threads"⊃•prefs ⍬    ⍝ 1ₓ
•prefs ["kinds":"static"] ◇ √¯4    ⍝ $n
•prefs ["kinds":"static"] ◇ 2147483647ₓ+1ₓ    ⍝ ¯2147483648ₓ
•prefs ["int":64] ◇ 2147483647ₓ+1ₓ    ⍝ 2147483648ₓ
•prefs ["kinds":"dynamic" "int":32] ◇ √¯4    ⍝ 0ⱼ2
•prefs ["seed":42] ◇ a←¿6 6 6 ◇ •prefs ["seed":42] ◇ a≡¿6 6 6    ⍝ $t

Errors: DOMAIN for an unknown setting or an invalid value. Under static kinds, LIMIT for an exact integer literal that doesn’t fit the int width.