18. Program Style Guide

Programmer Preface

A recommended set of conventions, patterns, idioms, and best practices for writing clear, maintainable, and correct UNS programs.

This guide is designed for:

• authors of examples,
• contributors adding new documentation,
• researchers exploring UNS numerics, and
• anyone who wants their .unse code to be readable and consistent.

These are strong recommendations, not hard rules—but they will make your work significantly easier.

---

Style Guide for .unse Programs

1. General Principles

✔ Prefer clarity over cleverness

UNS is an expression language—nesting can become unreadable quickly. Favor stepwise construction using multiple let bindings.

✔ Name things based on intent, not mechanism

Use window, region, wave, signal, maskA, localPsi rather than x1, tmp, etc.

✔ Keep states separate from signals

state is for measurement, not computation. let is for building UValues.

Do not mix the two roles.

---

2. File Organization

✔ Bind values at the top, diagnostics at the bottom

Example:

// 1. Construct base signals
let idx = lift1(index, const(0))
let wave = lift1(sin, idx)

// 2. Build masks or windows
let taper = lift1(windowWeight_3_4, idx)

// 3. Convert to a state
state psi = state(taper)

// 4. Measurements (final)
let value = read(wave | psi)
plotU(wave)

---

3. Naming Conventions

✔ Use lowercase-with-underscores for UValues

let wave_sin = ...
let region_mask = ...
let noise_field = ...
let weight_soft = ...

✔ Use short, meaningful names for states

state psi = ...
state psi_local = ...
state psiBand = ...

✔ Use uppercase only for scalar functions used in lifting

lift1(SIN, idx) → ❌ incorrect  
lift1(sin, idx) → ✔ lowercase functions

✔ Use descriptive operator names

let modulated_signal = base *u taper

---

4. Comments

✔ Use comments to explain intent, not mechanics

Bad:

// multiply wave by window
let w = wave *u window

Better:

// Apply soft taper to prevent edge artifacts
let w = wave *u window

---

5. White Space & Grouping

✔ Put spaces around infix operators

base +u mod *s 0.5          // ❌ messy
(base +u mod) *s 0.5        // ✔ clearer

✔ Put each let or state binding on its own line

This helps visually scan program structure.

✔ Group related expressions with blank lines

let idx = lift1(index, const(0))
let wave = lift1(sin, idx)

let mask = mask_range(0,128)
state psi = state_from_mask(mask)

let result = read(wave | psi)

---

6. Function Calls

✔ Prefer explicit parameter expressions

Avoid:

let w = mask_range(0,128)

Prefer to space parameters and include descriptive comments:

// Window covering the first quarter of the domain
let w = mask_range(0, 128)

✔ Do not put complex expressions inside arguments unnecessarily

Bad:

read(lift1(sin, lift1(index, const(0))) *u someMask | psi)

Good:

let idx = lift1(index, const(0))
let wave = lift1(sin, idx)
let masked = wave *u someMask

read(masked | psi)

---

7. States: Conventions & Best Practices

✔ Always convert masks into states explicitly

Bad:

state psi = mask_range(0,150)   // ❌ normalizes incorrectly

Good:

let m = mask_range(0, 150)
state psi = state_from_mask(m)

✔ Keep state construction compact and visible

let mask = mask_range(100,150)
let weight = lift1(windowWeight_96_48, idx)
state psi = state(mask *u weight)

✔ Prefer descriptive names

state psi = ...
state psi_local = ...
state psi_band_soft = ...

---

8. Signals & UValues: Best Practices

✔ Build signals step-by-step

Avoid single giant expressions. Prefer:

let idx   = lift1(index, const(0))
let base  = lift1(sin, idx)
let mod   = lift1(cos, idx)
let wave  = base +u (mod *s 0.5)

✔ Apply windows and masks last

Build the signal, then shape it.

---

9. Readout

✔ Use a vertical layout for clarity

Bad:

let r = read(wave *u window | psi)

Better:

let windowed = wave *u window
let r = read(windowed | psi)

✔ Always name the measured value

let local_mean = read(signal | psi_local)

✔ Use explicit state names in readout (do not inline)

Bad:

let r = read(signal | state_range(0, 100))

Good:

state psi = state_range(0, 100)
let r = read(signal | psi)

---

10. Diagnostic Helpers

✔ Use plotU and printU generously

They are essential for debugging.

Always separate diagnostics at the bottom:

plotU(signal)
plotU(psi)
printU(signal)

---

11. Working with Division & Edge Conditions

✔ Guard every divide operation

Bad:

let ratio = lift2(divide, a, b)

Good:

let ratio = lift2(divide, a, b +u const(0.01))

✔ Apply masks when constructing unstable signals

This prevents undefined values from contaminating readout.

---

12. Mask Usage

✔ Construct masks separately

let m_range = mask_range(0,128)
let m_peak  = mask_threshold(signal, 0.5)
let m = m_range *u m_peak

✔ Plot masks often

plotU(m)

---

13. Window Functions

✔ Use lifted windows to soften edges

Hard regions create digital artifacts.

let taper = lift1(windowWeight_3_4, idx)
let windowed = signal *u taper

✔ Combine masks and windows thoughtfully

let mask = mask_range(100,150)
let tapered = mask *u taper

---

14. Spacing & Formatting

✔ Use 4 spaces for indentation (if indenting inside braces)

Example:

let structured = assemble {
    10: 1,
    11: 0.5,
    12: -0.25
}

✔ Put spaces after commas and around colons

---

15. Example: “Ideal” Program Style

// ==== BUILD INDEX ====
let idx = lift1(index, const(0))

// ==== BUILD SIGNAL ====
let base = lift1(sin, idx)
let mod  = lift1(cos, idx)
let wave = base +u (mod *s 0.5)

// ==== BUILD WINDOW ====
let taper = lift1(windowWeight_3_4, idx)
let band  = mask_range(0, 128)
let window = taper *u band

// ==== CONVERT TO STATE ====
state psi = state(window)

// ==== READOUT ====
let value = read(wave | psi)

// ==== DIAGNOSTICS ====
plotU(wave)
plotU(psi)

---

16. Summary of Best Practices

• Use many small let bindings
• Keep state bindings separate and minimal
• Avoid inlining huge expressions
• Use consistent naming patterns
• Plot and print intermediate signals
• Guard divide operations
• Prefer smooth windows over hard cutoffs
• Use descriptive comments explaining intent

---