# Superfloat Python

- [Overview](https://docs.superfloat.si/index.md): sf is the Python library for Superfloat, the number format of the Atreides chip. Write ordinary Python and get the chip's exact results, bit for bit.
- [Installation](https://docs.superfloat.si/get-started/installation.md): Install sf from the repository. Python 3.10 or newer, NumPy is the only runtime dependency.
- [Quickstart](https://docs.superfloat.si/get-started/quickstart.md): From a single value to a matrix multiply on the device, with the chip's exact results at every step.
- [Project status](https://docs.superfloat.si/get-started/status.md): What is implemented, what is verified, and what still needs the hardware.
- [The Superfloat format](https://docs.superfloat.si/concepts/format.md): What an sfN value is: a signed integer code, a fixed scale, and a range that stops just short of 1.
- [Rounding and truncation](https://docs.superfloat.si/concepts/rounding-and-truncation.md): Casts round to nearest. Arithmetic truncates toward zero. This one distinction explains most results that look off by one code.
- [Events: overflow, underflow, divide, invalid](https://docs.superfloat.si/concepts/events.md): The four things that can go wrong in Superfloat arithmetic, what the hardware does for each, and how sf reports them.
- [Exactness: literals and comparisons](https://docs.superfloat.si/concepts/exactness.md): How sf treats plain Python numbers that appear next to Superfloat values. Arithmetic quantizes them; comparisons do not.
- [Host and device](https://docs.superfloat.si/concepts/host-and-device.md): Which operations run where, the rule that nothing reaches the chip that the host could decide, and what a result's status tells you.
- [Creating values](https://docs.superfloat.si/scalars/creating.md): The thirteen scalar types, what they accept, and what you get back.
- [Arithmetic](https://docs.superfloat.si/scalars/arithmetic.md): Add, subtract, multiply, divide, fused multiply-add, square root and powers, each with the exact rule the chip applies.
- [Comparisons and selection](https://docs.superfloat.si/scalars/comparisons.md): Exact comparisons, truth value, and the selection functions that never produce an event.
- [Casting between widths](https://docs.superfloat.si/scalars/casting.md): Widening is free and exact. Narrowing re-quantizes and goes through the error policy. Nothing narrows on its own.
- [Inspecting a value](https://docs.superfloat.si/scalars/inspecting.md): The code, the exact fraction, the bit pattern, and the format constants.
- [Creating arrays](https://docs.superfloat.si/arrays/creating.md): An SFArray is a NumPy int64 array of codes plus a dtype and a placement. Here is every way to make one.
- [Elementwise operations and broadcasting](https://docs.superfloat.si/arrays/elementwise.md): Every scalar rule applied element by element, with NumPy broadcasting and events counted across the array.
- [Reductions](https://docs.superfloat.si/arrays/reductions.md): sum, dot, max and min, and the one rule that makes a reduction reproducible: the order of accumulation.
- [Matrix multiply](https://docs.superfloat.si/arrays/matmul.md): a @ b, with NumPy's shape rules, built from the same fma chain as dot so every output is reproducible.
- [Running on the device](https://docs.superfloat.si/arrays/device.md): Place arrays on a target, run the heavy operations there, and read the results back. Nothing is launched that the host could have decided.
- [Reading result.status](https://docs.superfloat.si/arrays/status.md): What SFStatus contains, when its numbers are exact, and how to make them exact when they are not.
- [Configuration](https://docs.superfloat.si/arrays/configuration.md): sf.config: the pre-flight strictness, the probe, how status is obtained, offloading, and the default device.
- [Error policy](https://docs.superfloat.si/errors/policy.md): Raise, warn or ignore, per event. Set it globally, for a block, or for a function. The value is always the hardware value.
- [Exceptions and warnings](https://docs.superfloat.si/errors/exceptions.md): Every exception and warning sf can raise, what triggers it, and what it inherits from.
- [How sf is tested](https://docs.superfloat.si/testing/how-sf-is-tested.md): An independent oracle in exact fractions, every input pair for the small widths, all 4.3 billion sf16 pairs nightly, and integer codes only.
- [Scalar types](https://docs.superfloat.si/reference/types.md): sf.sf4 to sf.sf16, their attributes and operators, and the helpers that describe a format.
- [Arrays](https://docs.superfloat.si/reference/arrays.md): Constructors and the SFArray class: creating, placing, indexing, and reading codes back.
- [Math functions](https://docs.superfloat.si/reference/math.md): fma, div, sqrt, maximum, minimum, clip, where. All accept scalars and arrays and broadcast.
- [Reductions and linear algebra](https://docs.superfloat.si/reference/linalg.md): sum, dot, matmul, addmm, max, min, argmax, argmin.
- [Devices](https://docs.superfloat.si/reference/devices.md): The registered targets, the Device interface, and how to add your own.
- [Policy and configuration](https://docs.superfloat.si/reference/policy-and-config.md): sf.seterr, sf.geterr, sf.errstate, sf.config, sf.getconfig, and the SFStatus object.
- [Plugging in a simulator or the hardware](https://docs.superfloat.si/reference/hardware.md): 9. Plugging in a real simulator or the hardware
- [PyTorch models](https://docs.superfloat.si/guides/pytorch.md): Stage 2: quantize, convert, compile
- [sf.torch (Stage 2)](https://docs.superfloat.si/reference/torch.md): 5. Stage 2: `sf.torch` (import as `sft`)
- [Stage 2 tour](https://docs.superfloat.si/tours/stage_2_tour.md): examples/stage_2_tour.py, runnable end to end
- [Writing kernels](https://docs.superfloat.si/guides/kernels.md): Stage 3: thread and block kernels on the simulator
- [Kernels (Stage 3)](https://docs.superfloat.si/reference/kernels.md): 6. Stage 3: kernels
- [Stage 3 tour](https://docs.superfloat.si/tours/stage_3_tour.md): examples/stage_3_tour.py, runnable end to end
- [Design notes](https://docs.superfloat.si/decisions/overview.md): How to read the decisions log
- [Design rule for the device path: decide on the host, launch only the undecidable](https://docs.superfloat.si/decisions/design-rule-for-the-device-path-decide-on-the-host-launch-only-the-undecidable.md): Decision log: design rule for the device path: decide on the host, launch only the undecidable
- [Error policy mechanics](https://docs.superfloat.si/decisions/error-policy-mechanics.md): Decision log: error policy mechanics
- [Immutability](https://docs.superfloat.si/decisions/immutability.md): Decision log: immutability
- [Representation](https://docs.superfloat.si/decisions/representation.md): Decision log: representation
- [Review history](https://docs.superfloat.si/decisions/review-history.md): Decision log: review history
- [Semantics not fixed by the spec](https://docs.superfloat.si/decisions/semantics-not-fixed-by-the-spec.md): Decision log: semantics not fixed by the spec
- [Stage 1.1 decisions](https://docs.superfloat.si/decisions/stage-1-1-decisions.md): Decision log: stage 1.1 decisions
- [Stage 2 decisions](https://docs.superfloat.si/decisions/stage-2-decisions.md): Decision log: stage 2 decisions
- [Stage 3 decisions](https://docs.superfloat.si/decisions/stage-3-decisions.md): Decision log: stage 3 decisions
- [Still open for the compiler / hardware teams (spec section 12)](https://docs.superfloat.si/decisions/still-open-for-the-compiler-hardware-teams.md): Decision log: still open for the compiler / hardware teams (spec section 12)
- [Test cost](https://docs.superfloat.si/decisions/test-cost.md): Decision log: test cost


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.