math

package module
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: May 4, 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.
Package ntt is the canonical Number-Theoretic-Transform interface for luxfi/math.
 Package ntt is the canonical Number-Theoretic-Transform interface for luxfi/math.
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.

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.