Skip to content

Commit a732ded

Browse files
committed
Rename L2Denorm to Normalized
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
1 parent 780d4d0 commit a732ded

15 files changed

Lines changed: 376 additions & 348 deletions

File tree

‎vortex-tensor/src/encodings/mod.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,4 @@
66
// TODO(connor):
77
// pub mod spherical; // Spherical transform on unit-normalized vectors.
88

9-
pub mod l2_denorm;
9+
pub mod normalized;

vortex-tensor/src/encodings/l2_denorm/array.rs renamed to vortex-tensor/src/encodings/normalized/array.rs

Lines changed: 46 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,14 @@ use vortex_error::vortex_panic;
2828
use vortex_session::VortexSession;
2929
use vortex_session::registry::CachedId;
3030

31-
use crate::encodings::l2_denorm::execute::denormalize;
32-
use crate::encodings::l2_denorm::rules::RULES;
33-
use crate::encodings::l2_denorm::validate::validate_l2_denorm_children;
34-
use crate::encodings::l2_denorm::validate::validate_l2_normalized_rows_against_norms;
31+
use crate::encodings::normalized::execute::denormalize;
32+
use crate::encodings::normalized::rules::RULES;
33+
use crate::encodings::normalized::validate::validate_l2_normalized_rows_against_norms;
34+
use crate::encodings::normalized::validate::validate_normalized_children;
3535
use crate::utils::validate_tensor_float_input;
3636

37-
/// An [`L2Denorm`]-encoded Vortex array.
38-
pub type L2DenormArray = Array<L2Denorm>;
37+
/// An [`Normalized`]-encoded Vortex array.
38+
pub type NormalizedArray = Array<Normalized>;
3939

4040
/// The norm-split encoding for tensor-like columns.
4141
///
@@ -45,7 +45,7 @@ pub type L2DenormArray = Array<L2Denorm>;
4545
///
4646
/// # Invariants
4747
///
48-
/// Every [`L2DenormArray`] structurally guarantees, via [`VTable::validate`]:
48+
/// Every [`NormalizedArray`] structurally guarantees, via [`VTable::validate`]:
4949
///
5050
/// - `normalized` is a tensor-like extension array with a float element type.
5151
/// - `norms` is a primitive column whose ptype equals the tensor element ptype.
@@ -75,11 +75,11 @@ pub type L2DenormArray = Array<L2Denorm>;
7575
/// [`InnerProduct`]: crate::scalar_fns::inner_product::InnerProduct
7676
/// [`CosineSimilarity`]: crate::scalar_fns::cosine_similarity::CosineSimilarity
7777
#[derive(Clone, Debug)]
78-
pub struct L2Denorm;
78+
pub struct Normalized;
7979

80-
/// The two child arrays of an [`L2DenormArray`].
81-
#[array_slots(L2Denorm)]
82-
pub struct L2DenormSlots {
80+
/// The two child arrays of an [`NormalizedArray`].
81+
#[array_slots(Normalized)]
82+
pub struct NormalizedSlots {
8383
/// The unit-norm (or zero) direction of each row, as a tensor-like extension array.
8484
#[slot(0)]
8585
pub normalized: ArrayRef,
@@ -89,8 +89,8 @@ pub struct L2DenormSlots {
8989
pub norms: ArrayRef,
9090
}
9191

92-
impl L2Denorm {
93-
/// Builds an [`L2DenormArray`], validating that `normalized` really is row-wise L2-normalized
92+
impl Normalized {
93+
/// Builds an [`NormalizedArray`], validating that `normalized` really is row-wise L2-normalized
9494
/// against `norms`.
9595
///
9696
/// This is the constructor for exact norm splits. It scans both children, so it costs
@@ -99,59 +99,63 @@ impl L2Denorm {
9999
/// # Errors
100100
///
101101
/// Returns an error if the children are structurally incompatible, or if they violate any of
102-
/// the semantic invariants listed on [`L2Denorm`].
102+
/// the semantic invariants listed on [`Normalized`].
103103
pub fn try_new(
104104
normalized: ArrayRef,
105105
norms: ArrayRef,
106106
ctx: &mut ExecutionCtx,
107-
) -> VortexResult<L2DenormArray> {
107+
) -> VortexResult<NormalizedArray> {
108108
let len = normalized.len();
109109
let dtype = normalized
110110
.dtype()
111111
.union_nullability(norms.dtype().nullability());
112-
let slots = L2DenormSlots { normalized, norms }.into_slots();
112+
let slots = NormalizedSlots { normalized, norms }.into_slots();
113113

114114
// Structural validation has to come first: the row scan walks both children in lockstep
115115
// and assumes they are a matching-length tensor/float pair.
116-
let denorm = Array::try_from_parts(
117-
ArrayParts::new(L2Denorm, dtype, len, EmptyArrayData).with_slots(slots),
116+
let normalized_array = Array::try_from_parts(
117+
ArrayParts::new(Normalized, dtype, len, EmptyArrayData).with_slots(slots),
118+
)?;
119+
validate_l2_normalized_rows_against_norms(
120+
normalized_array.normalized(),
121+
Some(normalized_array.norms()),
122+
ctx,
118123
)?;
119-
validate_l2_normalized_rows_against_norms(denorm.normalized(), Some(denorm.norms()), ctx)?;
120124

121-
Ok(denorm)
125+
Ok(normalized_array)
122126
}
123127

124-
/// Builds an [`L2DenormArray`] without validation.
128+
/// Builds an [`NormalizedArray`] without validation.
125129
///
126130
/// # Safety
127131
///
128-
/// The caller must uphold the structural invariants listed on [`L2Denorm`]. In particular,
132+
/// The caller must uphold the structural invariants listed on [`Normalized`]. In particular,
129133
/// both children must have the same length, `normalized` must be a float tensor, and `norms`
130134
/// must be a primitive column with the same element ptype.
131135
///
132136
/// This does not check the unit-norm relationship. Violating it can produce wrong answers but
133137
/// not memory unsafety.
134-
pub unsafe fn new_unchecked(normalized: ArrayRef, norms: ArrayRef) -> L2DenormArray {
138+
pub unsafe fn new_unchecked(normalized: ArrayRef, norms: ArrayRef) -> NormalizedArray {
135139
let len = normalized.len();
136140
let dtype = normalized
137141
.dtype()
138142
.union_nullability(norms.dtype().nullability());
139-
let slots = L2DenormSlots { normalized, norms }.into_slots();
143+
let slots = NormalizedSlots { normalized, norms }.into_slots();
140144

141145
unsafe {
142146
Array::from_parts_unchecked(
143-
ArrayParts::new(L2Denorm, dtype, len, EmptyArrayData).with_slots(slots),
147+
ArrayParts::new(Normalized, dtype, len, EmptyArrayData).with_slots(slots),
144148
)
145149
}
146150
}
147151
}
148152

149-
/// Metadata for a serialized [`L2DenormArray`]: its children's nullabilities.
153+
/// Metadata for a serialized [`NormalizedArray`]: its children's nullabilities.
150154
///
151155
/// The parent dtype supplies the tensor shape and element ptype. Its nullability is the union of
152156
/// the children, so it cannot identify which child is nullable.
153157
#[derive(Clone, prost::Message)]
154-
pub struct L2DenormMetadata {
158+
pub struct NormalizedMetadata {
155159
/// Whether the `normalized` child is nullable.
156160
#[prost(bool, tag = "1")]
157161
pub normalized_is_nullable: bool,
@@ -161,14 +165,14 @@ pub struct L2DenormMetadata {
161165
pub norms_is_nullable: bool,
162166
}
163167

164-
impl VTable for L2Denorm {
168+
impl VTable for Normalized {
165169
type TypedArrayData = EmptyArrayData;
166170

167171
type OperationsVTable = Self;
168172
type ValidityVTable = Self;
169173

170174
fn id(&self) -> ArrayId {
171-
static ID: CachedId = CachedId::new("vortex.tensor.l2_denorm");
175+
static ID: CachedId = CachedId::new("vortex.tensor.normalized");
172176
*ID
173177
}
174178

@@ -179,21 +183,21 @@ impl VTable for L2Denorm {
179183
len: usize,
180184
slots: &[Option<ArrayRef>],
181185
) -> VortexResult<()> {
182-
let slots = L2DenormSlotsView::from_slots(slots);
186+
let slots = NormalizedSlotsView::from_slots(slots);
183187

184-
validate_l2_denorm_children(slots.normalized, slots.norms, dtype, len)
188+
validate_normalized_children(slots.normalized, slots.norms, dtype, len)
185189
}
186190

187191
fn nbuffers(_array: ArrayView<'_, Self>) -> usize {
188192
0
189193
}
190194

191195
fn buffer(_array: ArrayView<'_, Self>, idx: usize) -> BufferHandle {
192-
vortex_panic!("L2DenormArray buffer index {idx} out of bounds")
196+
vortex_panic!("NormalizedArray buffer index {idx} out of bounds")
193197
}
194198

195199
fn buffer_name(_array: ArrayView<'_, Self>, idx: usize) -> Option<String> {
196-
vortex_panic!("L2DenormArray buffer_name index {idx} out of bounds")
200+
vortex_panic!("NormalizedArray buffer_name index {idx} out of bounds")
197201
}
198202

199203
fn with_buffers(
@@ -209,7 +213,7 @@ impl VTable for L2Denorm {
209213
_session: &VortexSession,
210214
) -> VortexResult<Option<Vec<u8>>> {
211215
Ok(Some(
212-
L2DenormMetadata {
216+
NormalizedMetadata {
213217
normalized_is_nullable: array.normalized().dtype().is_nullable(),
214218
norms_is_nullable: array.norms().dtype().is_nullable(),
215219
}
@@ -226,22 +230,22 @@ impl VTable for L2Denorm {
226230
children: &dyn ArrayChildren,
227231
_session: &VortexSession,
228232
) -> VortexResult<ArrayParts<Self>> {
229-
let metadata = L2DenormMetadata::decode(metadata)
230-
.map_err(|e| vortex_err!("Failed to decode L2DenormMetadata: {e}"))?;
233+
let metadata = NormalizedMetadata::decode(metadata)
234+
.map_err(|e| vortex_err!("Failed to decode NormalizedMetadata: {e}"))?;
231235

232236
let element_ptype = validate_tensor_float_input(dtype)?.element_ptype();
233237
let normalized_dtype = dtype.with_nullability(metadata.normalized_is_nullable.into());
234238
let norms_dtype = DType::Primitive(element_ptype, metadata.norms_is_nullable.into());
235239

236240
let normalized = children.get(0, &normalized_dtype, len)?;
237241
let norms = children.get(1, &norms_dtype, len)?;
238-
let slots = L2DenormSlots { normalized, norms }.into_slots();
242+
let slots = NormalizedSlots { normalized, norms }.into_slots();
239243

240244
Ok(ArrayParts::new(self.clone(), dtype.clone(), len, EmptyArrayData).with_slots(slots))
241245
}
242246

243247
fn slot_name(_array: ArrayView<'_, Self>, idx: usize) -> String {
244-
L2DenormSlots::NAMES[idx].to_string()
248+
NormalizedSlots::NAMES[idx].to_string()
245249
}
246250

247251
fn execute(array: Array<Self>, ctx: &mut ExecutionCtx) -> VortexResult<ExecutionResult> {
@@ -261,18 +265,18 @@ impl VTable for L2Denorm {
261265
}
262266
}
263267

264-
impl ValidityVTable<L2Denorm> for L2Denorm {
265-
fn validity(array: ArrayView<'_, L2Denorm>) -> VortexResult<Validity> {
268+
impl ValidityVTable<Normalized> for Normalized {
269+
fn validity(array: ArrayView<'_, Normalized>) -> VortexResult<Validity> {
266270
array
267271
.normalized()
268272
.validity()?
269273
.and(array.norms().validity()?)
270274
}
271275
}
272276

273-
impl OperationsVTable<L2Denorm> for L2Denorm {
277+
impl OperationsVTable<Normalized> for Normalized {
274278
fn scalar_at(
275-
array: ArrayView<'_, L2Denorm>,
279+
array: ArrayView<'_, Normalized>,
276280
index: usize,
277281
ctx: &mut ExecutionCtx,
278282
) -> VortexResult<Scalar> {

0 commit comments

Comments
 (0)