Documentation
¶
Overview ¶
Package brq implements the TreeDB brq_1bit v1 oracle.
The package is intentionally internal and reference-oriented: it defines the codec identity, canonical config bytes, deterministic rotation, golden data encoding, query uint4 bit-plane encoding, and score formula used to validate future optimized asset/search implementations. It does not publish collection runtime behavior or mutate rabitq_1bit semantics.
Index ¶
- Constants
- Variables
- type Config
- type EncodedVector
- type Plan
- func (p *Plan) BitProduct(code, q1, q2, q4, q8 []byte) (uint32, error)
- func (p *Plan) BytesPerCode() int
- func (p *Plan) CodeDimensions() int
- func (p *Plan) Config() Config
- func (p *Plan) CountCodeBits(code []byte) uint32
- func (p *Plan) Encode(dst []byte, vector []float32, ws *Workspace) (EncodedVector, error)
- func (p *Plan) EncodeQuery(query []float32, ws *Workspace) (Query, error)
- func (p *Plan) ScoreCosine(query Query, code []byte, codeCount uint32, quantizedDotProductInv float32) (float64, error)
- func (p *Plan) ScoreCosineSlow(query Query, code []byte, codeCount uint32, quantizedDotProductInv float32) (float64, error)
- func (p *Plan) ScoreEncoded(query Query, encoded EncodedVector) (float64, error)
- func (p *Plan) ValidateCode(code []byte, codeCount uint32) error
- func (p *Plan) ValidateQuantizedDotProductInv(value float32) error
- func (p *Plan) ValidateQuery(q Query) error
- func (p *Plan) VectorDimensions() int
- type Query
- type Workspace
Constants ¶
const ( // CodecName is the durable quantized codec name for TreeDB BRQ v1. CodecName = "brq_1bit" // CodecVersion is the first TreeDB BRQ codec contract version. CodecVersion uint32 = 1 // CodeWidthBits is the number of stored bits per code dimension. CodeWidthBits = 1 // QueryWeightBits is the runtime query-weight bit width. QueryWeightBits = 4 // StorageRole is the quantizedasset role selected by the v1 contract. StorageRole = "packed_codes" // StorageLogicalType is the typed-column logical/physical code shape. StorageLogicalType = "packed_bit_vector" // StorageEncoding is the raw typed-column encoding for StorageLogicalType. StorageEncoding = "raw_packed_bit_vector" // BitOrder documents the TreeDB packed-code bit order used on disk. BitOrder = "lsb0" // WordOrder documents little-endian uint64 scratch views for scorer kernels. WordOrder = "little_endian_uint64" // Padding is the only valid padding policy for partial final bytes. Padding = "zero" // QueryWeightQuantizer is the runtime query-weight quantizer identity. QueryWeightQuantizer = "max_abs_uint4_round_half_up" // ScoreLabel is the public label for quantized-only approximate scores. ScoreLabel = "brq_1bit_estimated_cosine_q4" // DataScaleSideArray is the required data side-array name. DataScaleSideArray = "quantized_dot_product_inv" // RotationName is part of the canonical codec config identity. RotationName = "signed_permutation_fwht_padded_v1" // DefaultSeed is the deterministic v1 seed used when callers do not supply a // workload-specific seed. It intentionally differs from rabitq_1bit. DefaultSeed uint64 = 0x6272713162697401 )
Variables ¶
var ( // ErrInvalidConfig reports an impossible or unsupported codec shape. ErrInvalidConfig = errors.New("brq: invalid config") // ErrDimensionMismatch reports vector/query/code shape mismatch. ErrDimensionMismatch = errors.New("brq: dimension mismatch") // ErrDegenerateVector reports zero, non-finite, or otherwise unencodable input. ErrDegenerateVector = errors.New("brq: degenerate vector") )
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Seed uint64
}
Config is the v1 codec configuration identity. Vector dimensions are schema shape rather than serialized config; NewPlan binds Config to dimensions.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns the stable TreeDB brq_1bit v1 config.
func (Config) CanonicalBytes ¶
CanonicalBytes returns the stable byte identity used for manifest config comparison and hashing. The format is line-oriented ASCII by design so docs, tests, and future non-Go implementations can reproduce it exactly.
type EncodedVector ¶
EncodedVector contains the data-code row and side-array values produced by Encode. Code is a packed_bit_vector row using TreeDB LSB-first layout.
type Plan ¶
type Plan struct {
// contains filtered or unexported fields
}
Plan binds a Config to a vector dimension and owns deterministic rotation metadata. Plan is immutable and safe for concurrent use; caller-provided Workspace values are not safe for concurrent sharing.
func NewPlan ¶
NewPlan validates dimensions, derives code shape, and precomputes the v1 deterministic signed permutation. CodeDimensions is next_power_of_two(dims), matching the padded Walsh-Hadamard rotation length.
func (*Plan) BitProduct ¶
BitProduct evaluates the weighted bit-product formula over q1/q2/q4/q8 masks.
func (*Plan) BytesPerCode ¶
BytesPerCode returns ceil(CodeDimensions/8), the packed row width.
func (*Plan) CodeDimensions ¶
CodeDimensions returns the number of one-bit dimensions stored per row.
func (*Plan) CountCodeBits ¶
CountCodeBits returns the popcount over logical code dimensions, excluding any zero padding bits in the final byte.
func (*Plan) Encode ¶
Encode normalizes vector, rotates it, packs sign bits into dst, and returns code_count plus quantized_dot_product_inv side-array values. It allocates only when dst or workspace scratch lacks capacity.
func (*Plan) EncodeQuery ¶
EncodeQuery normalizes and rotates query, quantizes absolute rotated values to uint4 weights, then prepares sign bits and positive/negative q1/q2/q4/q8 bit-planes consumed by ScoreCosine. Returned slices alias ws.
func (*Plan) ScoreCosine ¶
func (p *Plan) ScoreCosine(query Query, code []byte, codeCount uint32, quantizedDotProductInv float32) (float64, error)
ScoreCosine validates side-array inputs and returns the v1 estimated cosine score for one encoded data vector. This is the reference bit-product oracle; accelerated implementations may skip repeated validation only after matching this result bit-for-bit under golden tests.
func (*Plan) ScoreCosineSlow ¶
func (p *Plan) ScoreCosineSlow(query Query, code []byte, codeCount uint32, quantizedDotProductInv float32) (float64, error)
ScoreCosineSlow validates inputs and evaluates the same score by walking one logical dimension at a time. It is useful for parity tests of fused kernels.
func (*Plan) ScoreEncoded ¶
func (p *Plan) ScoreEncoded(query Query, encoded EncodedVector) (float64, error)
ScoreEncoded is a convenience wrapper around ScoreCosine.
func (*Plan) ValidateCode ¶
ValidateCode verifies row width, zero high padding bits, and code_count.
func (*Plan) ValidateQuantizedDotProductInv ¶
ValidateQuantizedDotProductInv verifies the finite side-array range implied by unit-L2 vectors and an orthonormal rotation: L1(rotated) is in [1, sqrt(CodeDimensions)], so its inverse is in [1/sqrt(CodeDimensions), 1] modulo float32 rounding tolerance.
func (*Plan) ValidateQuery ¶
ValidateQuery verifies query shape, sign-bit padding, uint4 weights, finite positive scale, integer sums, and exact q1/q2/q4/q8 plane consistency.
func (*Plan) VectorDimensions ¶
VectorDimensions returns the source float32 vector dimensions.
type Query ¶
type Query struct {
SignBits []byte
Weights []uint8
PosQ1 []byte
PosQ2 []byte
PosQ4 []byte
PosQ8 []byte
NegQ1 []byte
NegQ2 []byte
NegQ4 []byte
NegQ8 []byte
QueryWeightScale float64
QueryWeightSumInt uint32
NegativeWeightSumInt uint32
CodeDimensions int
}
Query contains the runtime brq_1bit query representation. SignBits and all q-planes use TreeDB LSB0 packed rows. Weights stores one uint4 value per logical code dimension for validation and slow oracle scoring.
Source Files