Scalar precision, literals, and binary data¶

Status: Shipped in lic typechecker (width rules, suffixes, binary literals). MIR/codegen for packed float4/float8 and full binary runtime is partial — see Codegen maturity below.

Li exposes explicit integer and float widths for HPC, quantization, and per-domain accuracy. The org does not enforce one global float width — each package and simulation chooses.

Normative registry (compiler): compiler/types/numeric_types.cpp
Physics metadata API: packages/li-physics-core/src/lib.li (ScalarPrecision, PhysicsProfile)

You set precision yourself¶

You (package author, game dev, simulation author) choose scalar width — not the Li org, not a parent li.toml, and not physics.core defaults alone. Pick the accuracy that fits your module; other packages in the same repo may use different widths.

Nothing in the toolchain forces your project to float64 or float32. Defaults (float, int, unsuffixed 3.14 / 42) are 64-bit for ergonomics; narrow them explicitly when you want less precision or smaller storage.

End-to-end example (FP32 simulation)¶

# Your package — you chose float32 everywhere in this module
type Real = float32

def step(dt: Real) -> Real
  requires dt > 0.0f32
  ensures result >= 0.0f32
  decreases 0
=
  var t: Real = 0.0f32
  return t + dt

def main() -> int
  requires true
  ensures result == 0
  decreases 0
=
  var dt: Real = 0.016f32
  var _ = step(dt)
  return 0

Optional manifest (documents your choice; does not rewrite dependent code):

[numerics]
default_float = "float32"
default_int = "int32"

Optional physics metadata (records width for dispatch / assets):

var p: PhysicsProfile = profile_for_tier(physics_tier_arcade())
p.float_bits = 32
p.int_bits = 32

For shared math at multiple widths in one codebase, see Precision polymorphism (generics [S], duplicate modules per Real, proposed precision float32: block).

Design principle: no global accuracy¶

See Strict by default — gates apply to proof/security/perf, not to forcing float64 everywhere.

Float types (complete list)¶

Integer types (complete list)¶

Type rules (compiler-enforced)¶

Literal suffixes¶

Suffix is parsed after the numeric token (not part of stod / integer digits).

Float suffixes¶

Integer suffixes¶

Example (typed locals)¶

def integrate_step(dt: float32) -> float32
  requires dt > 0.0f32
  ensures result >= 0.0f32
  decreases 0
=
  var x: float32 = 1.0f32
  var y: float32 = 2.0f32
  return x + y

Tests: li-tests/typecheck/literal_suffix_ok.li, scalar_width_ok.li, scalar_width_mix_fail.li

Binary type (binary)¶

Use binary for bit-packed data (quantized weight masks, sign planes, custom packings).
Use bytes for byte-aligned buffers (I/O, UTF-8, network).

Binary literals¶

def weight_mask() -> binary
  requires true
  ensures true
  decreases 0
=
  return 0b10110100

def main() -> int
  requires true
  ensures result == 0
  decreases 0
=
  var mask: binary = weight_mask()
  return 0

Tests: li-tests/typecheck/binary_literal_ok.li

Roadmap (binary)¶

• Bitwise ops (and, or, xor, shifts) with proofs
• MIR/codegen for packed storage
• Contract literals referencing binary (ensures result == 0b…) when proof surface supports them

Choosing accuracy in physics packages¶

physics.core stores metadata only — the compiler does not read float_bits to change codegen yet. Callers use it to select kernels, assets, or code paths.

ScalarPrecision¶

Presets¶

PhysicsProfile¶

import physics.core

def configure_arcade_fast() -> PhysicsProfile
  requires true
  ensures result.float_bits == 32
  decreases 0
=
  var p: PhysicsProfile = profile_for_tier(physics_tier_arcade())
  p.float_bits = 32
  p.int_bits = 32
  return p

Package README: packages/li-physics-core/docs/scalar-precision.md

li.toml (project preference, optional)¶

Documents intent for agents and humans; not enforced on dependencies.

[numerics]
default_float = "float32"   # or float64, float16, float8, …
default_int = "int64"
# default_weights = "binary"   # documentation only until manifest schema lands

See li.toml manifest.

Codegen maturity¶

Track gaps: Provability gaps.

Agent checklist¶

1. Read this page before adding quantization or physics numerics.
2. Use explicit widths in new APIs (float32, not bare float) when the module targets narrow storage.
3. Use binary + weights_encoding = 1 for bit-packed weights; do not overload bytes.
4. Do not add org-wide CI rules that mandate a single float_bits.
5. Run li-tests/typecheck/scalar_width_*, literal_suffix_ok, binary_literal_ok when touching numeric_types.cpp or the lexer.

Precision-polymorphic APIs (math / physics / numerics)¶

To make all widths applicable in shared code (not only float64):

Examples: li-tests/generics/precision_real_alias.li (Pattern A), precision_generic_fn.li (Pattern B def)
Copy-paste sample: docs/language/examples/precision-physics-math.li

Related¶

• Precision polymorphism — math/physics/numerics patterns
• Types and data
• Numerics
• Contracts and proofs
• Release notes: scalar precision