Development¶

Start with the design principles before changing arithmetic or storage. They define the exactness and ownership guarantees your changes must preserve. The sections below cover setup, focused checks, and the Mojo practices used in the implementation.

Environment¶

Set up your development environment using Pixi as described in the installation guide. Run the commands below from the project directory containing pixi.toml.

• The default Pixi environment pins Mojo 1.1.0.
• The comparison environment adds Python reference libraries (mpmath, gmpy2 with MPFR and MPC, and python-flint with Arb) and requires Cargo to build Rug.
• The docs environment provides MkDocs and Pygments.

Library programs and documentation builds run on Linux and macOS. The test, docs-test, and report runners require Linux: their compiler memory guards use systemd or prlimit to enforce the 12 GB cap.

Repository layout¶

Temporary build artifacts and micro-benchmarks belong in build/ or .cache/, both of which are git-ignored.

Verification gates¶

Run the suites affected by the changed components. Use focused AddressSanitizer checks when ownership changes; reserve full sweeps for an explicit request. The commands below include both focused and full-suite forms:

Build times depend on the suite, compiler cache and machine. A cached test executable starts quickly; a cold build can take several minutes.

The harness caches binaries by source hash and compiler identity. If neither changes, the next run executes the cached binary immediately. AddressSanitizer builds use -O1 because Mojo 1.1.0's runner can crash with -O0 --sanitize=address.

Before a commit, measure only the speedup of the functions the change is about, on the scalar benchmark or by cycle counts, and run nothing else: the suites, AddressSanitizer, compare, the differential check and the corpus are not gates before a commit. Changes affecting the public API still update documentation, docstrings and verified examples.

Iterating on a kernel¶

Choose the suites that exercise the area you changed. Each is a separate executable, typically taking about a minute to compile and seconds to run. For elementary functions, use:

1. Correctness: pixi run --locked test --suite elementary (every rounding mode against MPFR's fixtures, ball inclusion and Arb's tightness), and --suite constants after touching ball/_tables.mojo.
2. Speed: pixi run --locked report --area float_function --area ball_function times our functions against MPFR and Arb; add --baseline HEAD for a before-and-after column. For where the time goes, run the worker's calls command under callgrind (see Benchmarks).

Before a commit, measure the changed functions' speedup and nothing else (see above).

When submitting changes:

• Arithmetic modifications require passing the affected functional suites.
• Changes to pointer manipulation or memory ownership require focused AddressSanitizer checks of the affected ownership paths (--asan --suite NAME).
• Numerical changes require running compare against reference libraries.
• Changes affecting the public API require updating documentation, docstrings, and verified examples.

Mojo 1.1 practices¶

• Lambdas: Use the syntax lambda (x: T, y: T) raises -> R: expr. Lambdas that capture closures cannot be passed as compile-time parameters to vmap or lift. Because lambda bodies must be single expressions, in-place updates are written as acc.__iadd__(x).
• Struct return costs: Returning large structs (such as multi-limb results or Optional types) across non-inlined function boundaries incurs a 15–20 ns overhead. Inline small fast paths, and prefer sentinel values over Optional wrappers in internal kernels.
• Reference counting: Copying heap-allocated structs triggers atomic reference count increments and decrements. Pass arguments by borrowing (ref), and prefer rebind_var over rebind for owned variables. Note that evaluating x and y on arbitrary-precision types creates a full copy.
• Tuples of heap values: Unpacking a returned tuple (var q, r = f()) copies each element, and the tuple's release undoes the copy: two atomic reference-count updates per heap element. Keep the tuple and move parts out with a swap (_taken in integer/value.mojo), or return it whole (return parts^). A conditional expression (a if c else b) with a heap result also copies it once more; use statements.
• Optional of a large record: Building an Optional[ComplexContext] (or Optional[FloatFormat]) can compile to an out-of-line initializer that stores the payload a byte at a time, hundreds of instructions. Argument records use a plain slot instead: the value, a presence flag and a placeholder (_FormatSlot, _ComplexContextArgument). Taking a large value out of an Optional has the same problem: Optional.take() is inlined only while few call sites use it, and otherwise moves the payload byte by byte, about 400 instructions for a Ball. A new call site elsewhere can push it out of line everywhere: adding the derived Ball functions made the 53-bit Ball sin 12% slower that way. Where the Optional is dropped next, copy the value out with .value() instead; check hot paths' instruction counts after adding take() calls.
• Fast paths beside slow ones: The compiler hoists cheap computations out of the branches of an inlined function, so an inlined fast path can pay for its alternatives' setup. Keep the alternatives behind one @no_inline call, and choose an operation at compile time (_float_operation_of[operation]) rather than at run time in one function. A large function with many live values spills: a small hot routine can run faster out of line, with its operands in registers. Measure both.
• Constant tables: A comptime Array or SIMD table indexed at run time is copied to the stack on every call (an Array needs materialize). A string literal is static data: encode entries as printable characters and read them through unsafe_ptr() (see _RECIPROCAL_SEEDS).
• Native wide integers: Use native UInt128 and UInt256 types along with count_leading_zeros and count_trailing_zeros. Variable 256-bit divisions lower to bit-serial routines; for inner loops, prefer reciprocal multiplication.
• Compiler warnings: Compiling with --Werror flags unused variables; declare variables only in the code paths where they are initialized.
• Trait declarations: Traits added via __extension are invisible to modules compiled before the extension is imported. All library types must declare trait conformances directly on their definitions.
• Constraints on types: A where clause cannot evaluate a call to a library function, even a compile-time one, so overload resolution cannot search a type list. Give the types a marker trait and test conforms_to(T, Marker); a comptime assert in a body may call functions.
• Unreachable code: abort() returns Never, and code after comptime assert False counts as unreachable; under --Werror both are errors. Assert the condition itself (comptime assert T == A or T == B) and write no code after abort().
• Owned generic values: A var argument whose type is only known to be IterableOwned cannot be abandoned or rebound; consume it with iter(value^), whose iterator is movable.
• Converting from None: The literal None has type type_of(None), not NoneType; an implicit constructor that accepts the literal takes type_of(None). One taking NoneType is not found for it.
• Float64 elementary functions: std.math's exp2, log2 and ** on Float64 are good to about \(2^{-31}\) relatively (measured over 200,000 arguments), cbrt to about \(2^{-42}\), and exp2 is not exact at integers. Build powers of two from their bits (bitcast), refine an estimate with a Newton step in Float64 or on an exact residual, and never let a result's correctness rest on these functions' accuracy.
• Stack scratch behind a pointer: Once a stack array is written through a pointer cast to MutUntrackedOrigin, read and write it only through that pointer, and keep the array alive until the last access (_ = scratch^), as _long_divide does. A native quotient that wrote its limbs through cast pointers and read them back by array name got the arrays' initial zero fill: the compiler did not connect the two.

Performance discipline¶

Before optimizing, estimate how much time the change could save. Measure it against the same workload and an unchanged baseline, then record the method and results in the relevant architecture chapter. The benchmark guide describes the measurement protocol. Keep the change only when its measured gain justifies the added complexity.