math

package module
v1.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 13, 2026 License: BSD-3-Clause Imports: 9 Imported by: 80

README

Lux Math Library

A comprehensive mathematical utilities library for the Lux ecosystem.

Features

  • Big integer utilities: HexOrDecimal256, ParseBig256, U256, BigPow etc.
  • Safe arithmetic: Overflow-checked SafeAdd, SafeSub, SafeMul
  • Bit operations: XOR, AND, compression utilities
  • Set operations: Efficient set implementations including bit sets
  • Data structures: Linked lists, hash maps, heaps
  • Averagers: Time-windowed averaging utilities

Installation

go get github.com/luxfi/math

Package Structure

Package Description
github.com/luxfi/math Root package with re-exports for backwards compatibility
github.com/luxfi/math/big Big integer utilities (HexOrDecimal256, U256, parsing)
github.com/luxfi/math/safe Overflow-safe arithmetic operations
github.com/luxfi/math/bit Bit manipulation utilities
github.com/luxfi/math/set Set data structures
github.com/luxfi/math/linked Linked data structures
github.com/luxfi/math/heap Heap implementations

Usage

// Import root package (re-exports from subpackages)
import "github.com/luxfi/math"

// Or import specific subpackages directly
import (
    "github.com/luxfi/math/big"
    "github.com/luxfi/math/safe"
    "github.com/luxfi/math/set"
)
Big Integer Operations
import "github.com/luxfi/math/big"

// Parse hex or decimal
val, _ := big.ParseBig256("0x1234")

// 256-bit unsigned operations
result := big.U256(someInt)

// Power operation
power := big.BigPow(2, 256)
Safe Arithmetic
import "github.com/luxfi/math/safe"

// Returns (result, overflow bool)
sum, overflow := safe.SafeAdd(a, b)
product, overflow := safe.SafeMul(x, y)

// Returns (result, error)
sum, err := safe.Add64(a, b)

License

See the LICENSE file for licensing terms.

Documentation

Overview

Package math re-exports big.Int utilities for backwards compatibility. New code should import github.com/luxfi/math/big directly.

Index

Constants

This section is empty.

Variables

View Source 
var (
	NewHexOrDecimal256 = luxbig.NewHexOrDecimal256
	NewDecimal256      = luxbig.NewDecimal256
	ParseBig256        = luxbig.ParseBig256
	MustParseBig256    = luxbig.MustParseBig256
	ParseUint64        = luxbig.ParseUint64
	MustParseUint64    = luxbig.MustParseUint64
	BigPow             = luxbig.BigPow
	BigMax             = luxbig.BigMax
	BigMin             = luxbig.BigMin
	PaddedBigBytes     = luxbig.PaddedBigBytes
	ReadBits           = luxbig.ReadBits
	U256               = luxbig.U256
	U256Bytes          = luxbig.U256Bytes
)

Function aliases for backwards compatibility.

View Source 
var (
	ErrOverflow  = errors.New("overflow")
	ErrUnderflow = errors.New("underflow")

	// Deprecated: Add64 is deprecated. Use Add[uint64] instead.
	Add64 = Add[uint64]

	// Deprecated: Mul64 is deprecated. Use Mul[uint64] instead.
	Mul64 = Mul[uint64]
)
View Source 
var MaxBig256 = new(big.Int).Set(luxbig.MaxBig256)

MaxBig256 is the maximum value for a 256-bit unsigned integer.

Functions

func AbsDiff 

func AbsDiff[T constraints.Unsigned](a, b T) T

AbsDiff returns the absolute difference between a and b.

func Add 

func Add[T constraints.Unsigned](a, b T) (T, error)

Add returns: 1) a + b 2) If there is overflow, an error

func IsSortedBytes 

func IsSortedBytes[T ~[]byte](s []T) bool

IsSortedBytes returns true if s is sorted in ascending order.

func MaxUint 

func MaxUint[T constraints.Unsigned]() T

MaxUint returns the maximum value of an unsigned integer of type T.

func Mul 

func Mul[T constraints.Unsigned](a, b T) (T, error)

Mul returns: 1) a * b 2) If there is overflow, an error

func SafeAdd 

func SafeAdd(x, y uint64) (uint64, bool)

SafeAdd returns x+y and whether overflow occurred.

func SafeMul 

func SafeMul(x, y uint64) (uint64, bool)

SafeMul returns x*y and whether overflow occurred.

func SafeSub 

func SafeSub(x, y uint64) (uint64, bool)

SafeSub returns x-y and whether underflow occurred.

func Sub 

func Sub[T constraints.Unsigned](a, b T) (T, error)

Sub returns: 1) a - b 2) If there is underflow, an error

func Zero 

func Zero[T any]() T

Zero returns the zero value of any type T.

Types

type Averager 

type Averager interface {
	// Observe the value at the given time
	Observe(value float64, currentTime time.Time)

	// Read returns the average of the provided values.
	Read() float64
}

Averager tracks a continuous time exponential moving average of the provided values.

func NewAverager 

func NewAverager(
	initialPrediction float64,
	halflife time.Duration,
	currentTime time.Time,
) Averager

func NewSyncAverager 

func NewSyncAverager(averager Averager) Averager

func NewUninitializedAverager 

func NewUninitializedAverager(halfLife time.Duration) Averager

NewUninitializedAverager creates a new averager with the given halflife. If [Read] is called before [Observe], the zero value will be returned. When [Observe] is called the first time, the averager will be initialized with [value] at that time.

type AveragerHeap 

type AveragerHeap[K comparable] interface {
	// Add the average to the heap. If key is already in the heap, the
	// average will be replaced and the old average will be returned. If there
	// was not an old average, false will be returned.
	Add(key K, averager Averager) (Averager, bool)
	// Remove attempts to remove the average that was added with the provided
	// key, if none is contained in the heap, [false] will be returned.
	Remove(key K) (Averager, bool)
	// Pop attempts to remove the node with either the largest or smallest
	// average, depending on if this is a max heap or a min heap, respectively.
	Pop() (K, Averager, bool)
	// Peek attempts to return the node with either the largest or smallest
	// average, depending on if this is a max heap or a min heap, respectively.
	Peek() (K, Averager, bool)
	// Len returns the number of nodes that are currently in the heap.
	Len() int
}

AveragerHeap maintains a heap of the averagers keyed by a comparable type. K is the key type (e.g., ids.NodeID).

func NewMaxAveragerHeap 

func NewMaxAveragerHeap[K comparable]() AveragerHeap[K]

NewMaxAveragerHeap returns a new empty max heap. The returned heap is not thread safe.

type Decimal256 

type Decimal256 = luxbig.Decimal256

Type aliases for backwards compatibility.

type HexOrDecimal64 

type HexOrDecimal64 = luxbig.HexOrDecimal64

Type aliases for backwards compatibility.

type HexOrDecimal256 

type HexOrDecimal256 = luxbig.HexOrDecimal256

Type aliases for backwards compatibility.

Source Files

View all Source files

Directories

Path Synopsis
Package backend defines how `luxfi/math` selects between CPU and GPU implementations of the same primitive.
 Package backend defines how `luxfi/math` selects between CPU and GPU implementations of the same primitive.
big module
Package codec is the bounded-decode contract for every wire format in luxfi/math (and downstream luxfi/lattice, luxfi/pulsar, luxfi/fhe).
 Package codec is the bounded-decode contract for every wire format in luxfi/math (and downstream luxfi/lattice, luxfi/pulsar, luxfi/fhe).
cmd/emit_codec_kat command
Package modarith provides modular-arithmetic primitives shared across every Lux cryptographic protocol.
 Package modarith provides modular-arithmetic primitives shared across every Lux cryptographic protocol.
cmd/emit_modarith_kat command
ntt
Package ntt is the canonical Number-Theoretic-Transform interface for luxfi/math.
 Package ntt is the canonical Number-Theoretic-Transform interface for luxfi/math.
cmd/emit_ntt_kat command
subring
Package subring owns the Lattigo-derived Montgomery NTT body — SubRing layout, root-table generator, scalar primitives (MRed/MRedLazy/MForm/BRed/CRed/...), the loop-unrolled-by-16 NTT kernel, and the SIMD AVX2 dispatch hooks.
 Package subring owns the Lattigo-derived Montgomery NTT body — SubRing layout, root-table generator, scalar primitives (MRed/MRedLazy/MForm/BRed/CRed/...), the loop-unrolled-by-16 NTT kernel, and the SIMD AVX2 dispatch hooks.
Package params is the single Lux registry of cryptographic parameter identifiers.
 Package params is the single Lux registry of cryptographic parameter identifiers.
Package poly provides polynomial-arithmetic primitives over R_q = Z_q[X] / (X^N + 1) used by every Lux lattice protocol.
 Package poly provides polynomial-arithmetic primitives over R_q = Z_q[X] / (X^N + 1) used by every Lux lattice protocol.
Package rns provides the Residue Number System primitives that FHE schemes use to operate over a chain of small primes instead of one large modulus.
 Package rns provides the Residue Number System primitives that FHE schemes use to operate over a chain of small primes instead of one large modulus.
safe module
Package sample provides primitive samplers — uniform mod q, ternary, centered binomial, discrete Gaussian — used as building blocks by every Lux lattice protocol.
 Package sample provides primitive samplers — uniform mod q, ternary, centered binomial, discrete Gaussian — used as building blocks by every Lux lattice protocol.
cmd/emit_sample_kat command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.