1mod bridge;
48
49use std::collections::{HashMap, HashSet};
50use std::fmt;
51use std::path::Path;
52use std::sync::Mutex;
53
54use bridge::ffi;
55
56pub use ffi::{HealthStats, Neighbors};
57
58#[derive(Debug, Clone, PartialEq, Eq)]
60pub enum ScannError {
61 InvalidArgument(String),
64 Scann(String),
66}
67
68impl fmt::Display for ScannError {
69 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
70 match self {
71 ScannError::InvalidArgument(m) => write!(f, "invalid argument: {m}"),
72 ScannError::Scann(m) => write!(f, "{m}"),
73 }
74 }
75}
76
77impl std::error::Error for ScannError {}
78
79impl From<cxx::Exception> for ScannError {
80 fn from(e: cxx::Exception) -> Self {
81 ScannError::Scann(e.what().to_string())
82 }
83}
84
85pub type Result<T, E = ScannError> = std::result::Result<T, E>;
86
87fn invalid<T>(msg: impl Into<String>) -> Result<T> {
88 Err(ScannError::InvalidArgument(msg.into()))
89}
90
91fn opt_i32(v: Option<usize>, what: &str) -> Result<i32> {
93 match v {
94 None => Ok(-1),
95 Some(n) => i32::try_from(n).or_else(|_| invalid(format!("{what} = {n} does not fit in i32"))),
96 }
97}
98
99fn to_i32(n: usize, what: &str) -> Result<i32> {
100 i32::try_from(n).or_else(|_| invalid(format!("{what} = {n} does not fit in i32")))
101}
102
103fn rows(data: &[f32], dim: usize, what: &str) -> Result<usize> {
105 if dim == 0 {
106 return invalid("dimensionality must be > 0");
107 }
108 if !data.len().is_multiple_of(dim) {
109 return invalid(format!(
110 "{what}: {} floats is not a multiple of the dimensionality {dim}",
111 data.len()
112 ));
113 }
114 Ok(data.len() / dim)
115}
116
117#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
124#[must_use = "search options do nothing until passed to a search"]
125pub struct SearchOptions {
126 pub final_num_neighbors: Option<usize>,
128 pub pre_reorder_num_neighbors: Option<usize>,
130 pub leaves_to_search: Option<usize>,
132}
133
134impl SearchOptions {
135 pub fn k(k: usize) -> Self {
137 SearchOptions { final_num_neighbors: Some(k), ..Default::default() }
138 }
139 pub fn pre_reorder_num_neighbors(mut self, n: usize) -> Self {
140 self.pre_reorder_num_neighbors = Some(n);
141 self
142 }
143 pub fn leaves_to_search(mut self, n: usize) -> Self {
144 self.leaves_to_search = Some(n);
145 self
146 }
147
148 fn ffi(&self) -> Result<(i32, i32, i32)> {
149 Ok((
150 opt_i32(self.final_num_neighbors, "final_num_neighbors")?,
151 opt_i32(self.pre_reorder_num_neighbors, "pre_reorder_num_neighbors")?,
152 opt_i32(self.leaves_to_search, "leaves_to_search")?,
153 ))
154 }
155}
156
157pub struct ScannIndex {
166 inner: cxx::UniquePtr<ffi::ScannIndex>,
167 health_stats_lock: Mutex<()>,
169}
170
171unsafe impl Send for ScannIndex {}
181unsafe impl Sync for ScannIndex {}
182
183impl fmt::Debug for ScannIndex {
184 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
185 f.debug_struct("ScannIndex")
186 .field("len", &self.len())
187 .field("dimensionality", &self.dimensionality())
188 .finish()
189 }
190}
191
192impl ScannIndex {
193 fn wrap(inner: cxx::UniquePtr<ffi::ScannIndex>) -> Self {
194 ScannIndex { inner, health_stats_lock: Mutex::new(()) }
195 }
196
197 pub fn new(dataset: &[f32], dimensionality: usize, config: &str) -> Result<Self> {
200 Self::with_training_threads(dataset, dimensionality, config, 0)
201 }
202
203 pub fn with_training_threads(
206 dataset: &[f32],
207 dimensionality: usize,
208 config: &str,
209 training_threads: usize,
210 ) -> Result<Self> {
211 let n = rows(dataset, dimensionality, "dataset")?;
212 if n == 0 {
213 return invalid("dataset is empty");
214 }
215 if u32::try_from(n).is_err() {
216 return invalid(format!("{n} datapoints exceed the 32-bit index space"));
217 }
218 let threads = to_i32(training_threads, "training_threads")?;
219 Ok(ScannIndex::wrap(ffi::scann_new(dataset, n as u64, config, threads)?))
220 }
221
222 pub fn load(dir: impl AsRef<Path>) -> Result<Self> {
225 let dir = path_str(dir.as_ref())?;
226 Ok(ScannIndex::wrap(ffi::scann_load(dir)?))
227 }
228
229 pub fn serialize(&mut self, dir: impl AsRef<Path>, relative_path: bool) -> Result<()> {
241 let dir = path_str(dir.as_ref())?;
242 Ok(ffi::scann_serialize(self.inner.pin_mut(), dir, relative_path)?)
243 }
244
245 pub fn search(&self, query: &[f32], options: SearchOptions) -> Result<Neighbors> {
247 self.check_query(query.len())?;
248 let (k, pre, leaves) = options.ffi()?;
249 Ok(ffi::scann_search(&self.inner, query, k, pre, leaves)?)
250 }
251
252 pub fn search_batched(&self, queries: &[f32], options: SearchOptions) -> Result<Vec<Neighbors>> {
255 self.batched(queries, options, false, 256)
256 }
257
258 pub fn search_batched_parallel(
262 &self,
263 queries: &[f32],
264 options: SearchOptions,
265 batch_size: usize,
266 ) -> Result<Vec<Neighbors>> {
267 if batch_size == 0 {
268 return invalid("batch_size must be > 0");
269 }
270 self.batched(queries, options, true, batch_size)
271 }
272
273 fn batched(
274 &self,
275 queries: &[f32],
276 options: SearchOptions,
277 parallel: bool,
278 batch_size: usize,
279 ) -> Result<Vec<Neighbors>> {
280 let n = rows(queries, self.dimensionality(), "queries")?;
281 let (k, pre, leaves) = options.ffi()?;
282 let bs = to_i32(batch_size, "batch_size")?;
283 Ok(ffi::scann_search_batched(&self.inner, queries, n as u64, k, pre, leaves, parallel, bs)?)
284 }
285
286 fn check_query(&self, len: usize) -> Result<()> {
287 let dim = self.dimensionality();
288 if len != dim {
289 return invalid(format!("query has {len} dimensions, the index has {dim}"));
290 }
291 Ok(())
292 }
293
294 pub fn len(&self) -> usize {
296 ffi::scann_size(&self.inner) as usize
297 }
298
299 pub fn is_empty(&self) -> bool {
300 self.len() == 0
301 }
302
303 pub fn dimensionality(&self) -> usize {
304 ffi::scann_dimensionality(&self.inner) as usize
305 }
306
307 pub fn config(&mut self) -> String {
309 ffi::scann_config(self.inner.pin_mut())
310 }
311
312 pub fn set_num_threads(&mut self, num_threads: usize) -> Result<()> {
321 let n = to_i32(num_threads, "num_threads")?;
322 ffi::scann_set_num_threads(self.inner.pin_mut(), n);
323 Ok(())
324 }
325
326 pub fn reserve(&mut self, n_points: usize) -> Result<()> {
328 Ok(ffi::scann_reserve(self.inner.pin_mut(), n_points as u64)?)
329 }
330
331 pub fn add(&mut self, vectors: &[f32]) -> Result<Vec<u32>> {
333 let n = rows(vectors, self.dimensionality(), "vectors")?;
334 self.upsert(&vec![None; n], vectors, 1)
335 }
336
337 pub fn upsert(&mut self, ids: &[Option<u32>], vectors: &[f32], batch_size: usize) -> Result<Vec<u32>> {
349 let n = rows(vectors, self.dimensionality(), "vectors")?;
350 if n != ids.len() {
351 return invalid(format!("{} ids for {n} vectors", ids.len()));
352 }
353 if batch_size == 0 {
354 return invalid("batch_size must be > 0");
355 }
356 let mut seen = HashSet::new();
357 if let Some(dup) = ids.iter().flatten().find(|&&id| !seen.insert(id)) {
358 return invalid(format!("upsert: index {dup} listed more than once"));
359 }
360 let ids: Vec<i64> = ids.iter().map(|id| id.map_or(-1, i64::from)).collect();
361 let bs = to_i32(batch_size, "batch_size")?;
362 Ok(ffi::scann_upsert(self.inner.pin_mut(), &ids, vectors, bs)?)
363 }
364
365 pub fn delete(&mut self, ids: &[u32]) -> Result<Vec<(u32, u32)>> {
372 let len = self.len();
373 if let Some(&bad) = ids.iter().find(|&&id| id as usize >= len) {
374 return invalid(format!("delete: index {bad} out of range ({len} points)"));
375 }
376 let mut order = ids.to_vec();
380 order.sort_unstable_by(|a, b| b.cmp(a));
381 if let Some(w) = order.windows(2).find(|w| w[0] == w[1]) {
382 return invalid(format!("delete: index {} listed more than once", w[0]));
383 }
384 ffi::scann_delete(self.inner.pin_mut(), &order)?;
385
386 let mut origin: HashMap<u32, u32> = HashMap::new();
389 let mut remaining = len as u32;
390 for &id in &order {
391 let last = remaining - 1;
392 let moved = origin.remove(&last).unwrap_or(last);
393 origin.remove(&id);
394 if id != last {
395 origin.insert(id, moved);
396 }
397 remaining -= 1;
398 }
399 let mut moves: Vec<(u32, u32)> = origin.into_iter().map(|(now, was)| (was, now)).collect();
400 moves.sort_unstable();
401 Ok(moves)
402 }
403
404 pub fn rebalance(&mut self, config: Option<&str>) -> Result<()> {
407 Ok(ffi::scann_rebalance(self.inner.pin_mut(), config.unwrap_or(""))?)
408 }
409
410 pub fn health_stats(&self) -> Result<HealthStats> {
421 let _guard = self.health_stats_lock.lock().unwrap_or_else(|e| e.into_inner());
422 Ok(ffi::scann_health_stats(&self.inner)?)
423 }
424
425 pub fn initialize_health_stats(&mut self) -> Result<()> {
428 Ok(ffi::scann_initialize_health_stats(self.inner.pin_mut())?)
429 }
430}
431
432fn path_str(p: &Path) -> Result<&str> {
433 p.to_str()
434 .ok_or_else(|| ScannError::InvalidArgument(format!("path {p:?} is not valid UTF-8")))
435}
436
437#[derive(Debug, Clone, Copy, PartialEq, Eq)]
442pub enum DistanceMeasure {
443 DotProduct,
444 SquaredL2,
445}
446
447#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
449pub enum Quantization {
450 #[default]
451 Float32,
452 Int8,
453 Bfloat16,
454}
455
456#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
457pub enum HashType {
458 #[default]
459 Lut16,
460 Lut256,
461}
462
463#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
465pub enum IncrementalMode {
466 #[default]
467 None,
468 Online,
469 OnlineIncremental,
470}
471
472#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
475pub enum AutopilotRules {
476 #[default]
479 Tuned,
480 Upstream,
482}
483
484#[derive(Debug, Clone, Copy, PartialEq, Eq)]
486pub struct AutopilotOptions {
487 pub mode: IncrementalMode,
488 pub quantize: Quantization,
490 pub rules: AutopilotRules,
491 pub allow_l2_as_dot_product: bool,
495}
496
497impl Default for AutopilotOptions {
498 fn default() -> Self {
499 AutopilotOptions {
500 mode: IncrementalMode::None,
501 quantize: Quantization::Float32,
502 rules: AutopilotRules::Tuned,
503 allow_l2_as_dot_product: true,
504 }
505 }
506}
507
508impl AutopilotOptions {
509 pub fn new() -> Self {
510 Self::default()
511 }
512 pub fn mode(mut self, mode: IncrementalMode) -> Self {
513 self.mode = mode;
514 self
515 }
516 pub fn quantize(mut self, quantize: Quantization) -> Self {
517 self.quantize = quantize;
518 self
519 }
520 pub fn rules(mut self, rules: AutopilotRules) -> Self {
521 self.rules = rules;
522 self
523 }
524 pub fn allow_l2_as_dot_product(mut self, allow: bool) -> Self {
525 self.allow_l2_as_dot_product = allow;
526 self
527 }
528}
529
530#[derive(Debug, Clone, Copy, PartialEq)]
533pub enum IncrementalThreshold {
534 Points(u64),
535 Fraction(f64),
536}
537
538fn q(q: Quantization) -> ffi::Quantization {
539 match q {
540 Quantization::Float32 => ffi::Quantization::Float32,
541 Quantization::Int8 => ffi::Quantization::Int8,
542 Quantization::Bfloat16 => ffi::Quantization::Bfloat16,
543 }
544}
545
546fn nan_if_none(v: Option<f64>) -> f64 {
547 v.unwrap_or(f64::NAN)
548}
549
550#[derive(Debug, Clone, PartialEq)]
552#[must_use = "options do nothing until passed to ConfigBuilder"]
553pub struct TreeOptions {
554 pub num_leaves: u32,
555 pub num_leaves_to_search: u32,
556 pub training_sample_size: u64,
557 pub min_partition_size: u32,
558 pub training_iterations: u32,
559 pub spherical: bool,
560 pub quantize_centroids: bool,
561 pub random_init: bool,
565 pub incremental_threshold: Option<IncrementalThreshold>,
566 pub avq: Option<f64>,
568 pub soar_lambda: Option<f64>,
570 pub overretrieve_factor: Option<f64>,
571}
572
573impl TreeOptions {
574 pub fn new(num_leaves: u32, num_leaves_to_search: u32) -> Self {
575 TreeOptions {
576 num_leaves,
577 num_leaves_to_search,
578 training_sample_size: 100_000,
579 min_partition_size: 50,
580 training_iterations: 12,
581 spherical: false,
582 quantize_centroids: false,
583 random_init: true,
584 incremental_threshold: None,
585 avq: None,
586 soar_lambda: None,
587 overretrieve_factor: None,
588 }
589 }
590 pub fn training_sample_size(mut self, n: u64) -> Self {
591 self.training_sample_size = n;
592 self
593 }
594 pub fn min_partition_size(mut self, n: u32) -> Self {
595 self.min_partition_size = n;
596 self
597 }
598 pub fn training_iterations(mut self, n: u32) -> Self {
599 self.training_iterations = n;
600 self
601 }
602 pub fn spherical(mut self, v: bool) -> Self {
605 self.spherical = v;
606 self
607 }
608 pub fn quantize_centroids(mut self, v: bool) -> Self {
609 self.quantize_centroids = v;
610 self
611 }
612 pub fn random_init(mut self, v: bool) -> Self {
613 self.random_init = v;
614 self
615 }
616 pub fn incremental_threshold(mut self, t: IncrementalThreshold) -> Self {
617 self.incremental_threshold = Some(t);
618 self
619 }
620 pub fn avq(mut self, eta: f64) -> Self {
621 self.avq = Some(eta);
622 self
623 }
624 pub fn soar_lambda(mut self, lambda: f64) -> Self {
625 self.soar_lambda = Some(lambda);
626 self
627 }
628 pub fn overretrieve_factor(mut self, f: f64) -> Self {
629 self.overretrieve_factor = Some(f);
630 self
631 }
632
633 fn ffi(&self) -> Result<ffi::FfiTreeOptions> {
634 let (points, fraction) = match self.incremental_threshold {
635 None => (-1, f64::NAN),
636 Some(IncrementalThreshold::Points(p)) => {
637 (i64::try_from(p).or_else(|_| invalid("incremental_threshold too large"))?, f64::NAN)
638 }
639 Some(IncrementalThreshold::Fraction(f)) => (-1, f),
640 };
641 Ok(ffi::FfiTreeOptions {
642 num_leaves: to_i32(self.num_leaves as usize, "num_leaves")?,
643 num_leaves_to_search: to_i32(self.num_leaves_to_search as usize, "num_leaves_to_search")?,
644 training_sample_size: i64::try_from(self.training_sample_size)
645 .or_else(|_| invalid("training_sample_size too large"))?,
646 min_partition_size: to_i32(self.min_partition_size as usize, "min_partition_size")?,
647 training_iterations: to_i32(self.training_iterations as usize, "training_iterations")?,
648 spherical: self.spherical,
649 quantize_centroids: self.quantize_centroids,
650 random_init: self.random_init,
651 incremental_threshold_points: points,
652 incremental_threshold_fraction: fraction,
653 avq: nan_if_none(self.avq),
654 soar_lambda: nan_if_none(self.soar_lambda),
655 overretrieve_factor: nan_if_none(self.overretrieve_factor),
656 })
657 }
658}
659
660#[derive(Debug, Clone, PartialEq)]
663#[must_use = "options do nothing until passed to ConfigBuilder"]
664pub struct UpperTreeOptions {
665 pub num_leaves: u32,
666 pub num_leaves_to_search: u32,
667 pub avq: Option<f64>,
668 pub soar_lambda: Option<f64>,
669 pub overretrieve_factor: Option<f64>,
670 pub scoring_mode: Quantization,
671 pub anisotropic_quantization_threshold: Option<f64>,
672}
673
674impl UpperTreeOptions {
675 pub fn new(num_leaves: u32, num_leaves_to_search: u32) -> Self {
676 UpperTreeOptions {
677 num_leaves,
678 num_leaves_to_search,
679 avq: None,
680 soar_lambda: None,
681 overretrieve_factor: None,
682 scoring_mode: Quantization::Int8,
683 anisotropic_quantization_threshold: None,
684 }
685 }
686 pub fn avq(mut self, eta: f64) -> Self {
687 self.avq = Some(eta);
688 self
689 }
690 pub fn soar_lambda(mut self, lambda: f64) -> Self {
691 self.soar_lambda = Some(lambda);
692 self
693 }
694 pub fn overretrieve_factor(mut self, f: f64) -> Self {
695 self.overretrieve_factor = Some(f);
696 self
697 }
698 pub fn scoring_mode(mut self, m: Quantization) -> Self {
699 self.scoring_mode = m;
700 self
701 }
702 pub fn anisotropic_quantization_threshold(mut self, t: f64) -> Self {
703 self.anisotropic_quantization_threshold = Some(t);
704 self
705 }
706
707 fn ffi(&self) -> Result<ffi::FfiUpperTreeOptions> {
708 Ok(ffi::FfiUpperTreeOptions {
709 num_leaves: to_i32(self.num_leaves as usize, "num_leaves")?,
710 num_leaves_to_search: to_i32(self.num_leaves_to_search as usize, "num_leaves_to_search")?,
711 avq: nan_if_none(self.avq),
712 soar_lambda: nan_if_none(self.soar_lambda),
713 overretrieve_factor: nan_if_none(self.overretrieve_factor),
714 scoring_mode: q(self.scoring_mode),
715 anisotropic_quantization_threshold: nan_if_none(self.anisotropic_quantization_threshold),
716 })
717 }
718}
719
720#[derive(Debug, Clone, PartialEq)]
723#[must_use = "options do nothing until passed to ConfigBuilder"]
724pub struct AhOptions {
725 pub dimensions_per_block: u32,
726 pub anisotropic_quantization_threshold: Option<f64>,
728 pub training_sample_size: u64,
729 pub hash_type: HashType,
730 pub training_iterations: u32,
731 pub residual_quantization: Option<bool>,
733}
734
735impl AhOptions {
736 pub fn new(dimensions_per_block: u32) -> Self {
737 AhOptions {
738 dimensions_per_block,
739 anisotropic_quantization_threshold: None,
740 training_sample_size: 100_000,
741 hash_type: HashType::Lut16,
742 training_iterations: 10,
743 residual_quantization: None,
744 }
745 }
746 pub fn anisotropic_quantization_threshold(mut self, t: f64) -> Self {
747 self.anisotropic_quantization_threshold = Some(t);
748 self
749 }
750 pub fn training_sample_size(mut self, n: u64) -> Self {
751 self.training_sample_size = n;
752 self
753 }
754 pub fn hash_type(mut self, h: HashType) -> Self {
755 self.hash_type = h;
756 self
757 }
758 pub fn training_iterations(mut self, n: u32) -> Self {
759 self.training_iterations = n;
760 self
761 }
762 pub fn residual_quantization(mut self, v: bool) -> Self {
763 self.residual_quantization = Some(v);
764 self
765 }
766
767 fn ffi(&self) -> Result<ffi::FfiAhOptions> {
768 Ok(ffi::FfiAhOptions {
769 dimensions_per_block: to_i32(self.dimensions_per_block as usize, "dimensions_per_block")?,
770 anisotropic_quantization_threshold: nan_if_none(self.anisotropic_quantization_threshold),
771 training_sample_size: i64::try_from(self.training_sample_size)
772 .or_else(|_| invalid("training_sample_size too large"))?,
773 hash_type: match self.hash_type {
774 HashType::Lut16 => ffi::HashType::Lut16,
775 HashType::Lut256 => ffi::HashType::Lut256,
776 },
777 training_iterations: to_i32(self.training_iterations as usize, "training_iterations")?,
778 has_residual_quantization: self.residual_quantization.is_some(),
779 residual_quantization: self.residual_quantization.unwrap_or(false),
780 })
781 }
782}
783
784#[derive(Debug, Clone, PartialEq)]
787#[must_use = "options do nothing until passed to ConfigBuilder"]
788pub struct ReorderOptions {
789 pub reordering_num_neighbors: u32,
790 pub quantize: Quantization,
791 pub anisotropic_quantization_threshold: Option<f64>,
792}
793
794impl ReorderOptions {
795 pub fn new(reordering_num_neighbors: u32) -> Self {
796 ReorderOptions {
797 reordering_num_neighbors,
798 quantize: Quantization::Float32,
799 anisotropic_quantization_threshold: None,
800 }
801 }
802 pub fn quantize(mut self, q: Quantization) -> Self {
803 self.quantize = q;
804 self
805 }
806 pub fn anisotropic_quantization_threshold(mut self, t: f64) -> Self {
807 self.anisotropic_quantization_threshold = Some(t);
808 self
809 }
810}
811
812#[derive(Debug, Clone, Copy, Default, PartialEq)]
819#[must_use = "options do nothing until passed to ConfigBuilder"]
820pub struct L2AsDotProductOptions {
821 pub scale: Option<f64>,
824 pub center: Option<f64>,
827}
828
829impl L2AsDotProductOptions {
830 pub fn new() -> Self {
831 Self::default()
832 }
833 pub fn scale(mut self, s: f64) -> Self {
834 self.scale = Some(s);
835 self
836 }
837 pub fn center(mut self, c: f64) -> Self {
838 self.center = Some(c);
839 self
840 }
841}
842
843#[derive(Debug, Clone, PartialEq)]
846#[must_use = "options do nothing until passed to ConfigBuilder"]
847pub struct PcaOptions {
848 pub reduction_dim: Option<u32>,
849 pub pca_significance_threshold: Option<f64>,
850 pub pca_truncation_threshold: f64,
851}
852
853impl Default for PcaOptions {
854 fn default() -> Self {
855 PcaOptions { reduction_dim: None, pca_significance_threshold: None, pca_truncation_threshold: 0.6 }
856 }
857}
858
859impl PcaOptions {
860 pub fn reduction_dim(dim: u32) -> Self {
861 PcaOptions { reduction_dim: Some(dim), ..Default::default() }
862 }
863 pub fn significance_threshold(t: f64) -> Self {
864 PcaOptions { pca_significance_threshold: Some(t), ..Default::default() }
865 }
866}
867
868#[must_use = "a ConfigBuilder does nothing until build() or build_index() is called"]
875pub struct ConfigBuilder {
876 inner: cxx::UniquePtr<ffi::ConfigBuilder>,
877 dimensionality: usize,
878 training_threads: usize,
879 error: Option<ScannError>,
880}
881
882impl fmt::Debug for ConfigBuilder {
883 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
884 f.debug_struct("ConfigBuilder").field("dimensionality", &self.dimensionality).finish()
885 }
886}
887
888impl ConfigBuilder {
889 pub fn new(num_neighbors: usize, distance: DistanceMeasure, dimensionality: usize) -> Self {
890 let mut error = None;
891 let k = to_i32(num_neighbors, "num_neighbors").unwrap_or_else(|e| {
892 error = Some(e);
893 0
894 });
895 let dim = u32::try_from(dimensionality).unwrap_or_else(|_| {
896 error = Some(ScannError::InvalidArgument("dimensionality too large".into()));
897 0
898 });
899 let d = match distance {
900 DistanceMeasure::DotProduct => ffi::DistanceMeasure::DotProduct,
901 DistanceMeasure::SquaredL2 => ffi::DistanceMeasure::SquaredL2,
902 };
903 ConfigBuilder {
904 inner: ffi::config_builder_new(k, d, dim),
905 dimensionality,
906 training_threads: 0,
907 error,
908 }
909 }
910
911 fn apply<T>(mut self, v: Result<T>, f: impl FnOnce(std::pin::Pin<&mut ffi::ConfigBuilder>, &T)) -> Self {
914 match v {
915 Ok(v) => f(self.inner.pin_mut(), &v),
916 Err(e) => {
917 self.error.get_or_insert(e);
918 }
919 }
920 self
921 }
922
923 pub fn tree(self, o: TreeOptions) -> Self {
925 let v = o.ffi();
926 self.apply(v, ffi::config_builder_tree)
927 }
928
929 pub fn upper_tree(self, o: UpperTreeOptions) -> Self {
931 let v = o.ffi();
932 self.apply(v, ffi::config_builder_upper_tree)
933 }
934
935 pub fn score_ah(self, o: AhOptions) -> Self {
937 let v = o.ffi();
938 self.apply(v, ffi::config_builder_score_ah)
939 }
940
941 pub fn score_brute_force(self, quantize: Quantization) -> Self {
943 self.apply(Ok(q(quantize)), |b, &qq| ffi::config_builder_score_brute_force(b, qq))
944 }
945
946 pub fn reorder(self, o: ReorderOptions) -> Self {
947 let v = to_i32(o.reordering_num_neighbors as usize, "reordering_num_neighbors").map(|k| {
948 ffi::FfiReorderOptions {
949 reordering_num_neighbors: k,
950 quantize: q(o.quantize),
951 anisotropic_quantization_threshold: nan_if_none(o.anisotropic_quantization_threshold),
952 }
953 });
954 self.apply(v, ffi::config_builder_reorder)
955 }
956
957 pub fn pca(self, o: PcaOptions) -> Self {
959 let v = match o.reduction_dim {
960 None => Ok(-1),
961 Some(d) => to_i32(d as usize, "reduction_dim"),
962 }
963 .map(|d| ffi::FfiPcaOptions {
964 reduction_dim: d,
965 pca_significance_threshold: nan_if_none(o.pca_significance_threshold),
966 pca_truncation_threshold: o.pca_truncation_threshold,
967 });
968 self.apply(v, ffi::config_builder_pca)
969 }
970
971 pub fn truncate(self, reduction_dim: usize) -> Self {
973 let v = to_i32(reduction_dim, "reduction_dim");
974 self.apply(v, |b, &d| ffi::config_builder_truncate(b, d))
975 }
976
977 pub fn autopilot(self, mode: IncrementalMode, quantize: Quantization) -> Self {
982 self.autopilot_with(AutopilotOptions::new().mode(mode).quantize(quantize))
983 }
984
985 pub fn autopilot_with(self, o: AutopilotOptions) -> Self {
989 let m = match o.mode {
990 IncrementalMode::None => ffi::IncrementalMode::None,
991 IncrementalMode::Online => ffi::IncrementalMode::Online,
992 IncrementalMode::OnlineIncremental => ffi::IncrementalMode::OnlineIncremental,
993 };
994 let v = ffi::FfiAutopilotOptions {
995 mode: m,
996 quantize: q(o.quantize),
997 upstream_rules: o.rules == AutopilotRules::Upstream,
998 allow_l2_as_dot_product: o.allow_l2_as_dot_product,
999 };
1000 self.apply(Ok(v), ffi::config_builder_autopilot)
1001 }
1002
1003 pub fn l2_as_dot_product(self, o: L2AsDotProductOptions) -> Self {
1011 let v = match (o.scale, o.center) {
1012 (Some(s), _) if !(s.is_finite() && s > 0.0) => {
1013 invalid(format!("l2_as_dot_product: scale must be positive and finite, not {s}"))
1014 }
1015 (_, Some(c)) if !c.is_finite() => {
1016 invalid(format!("l2_as_dot_product: center must be finite, not {c}"))
1017 }
1018 (s, c) => Ok((nan_if_none(s), nan_if_none(c))),
1019 };
1020 self.apply(v, |b, &(s, c)| ffi::config_builder_l2_as_dot_product(b, s, c))
1021 }
1022
1023 pub fn training_threads(mut self, n: usize) -> Self {
1025 self.training_threads = n;
1026 self
1027 }
1028
1029 pub fn build(&self, num_points: u64) -> Result<String> {
1036 if let Some(e) = &self.error {
1037 return Err(e.clone());
1038 }
1039 Ok(ffi::config_builder_build(&self.inner, num_points)?)
1040 }
1041
1042 pub fn build_index(&self, dataset: &[f32]) -> Result<ScannIndex> {
1044 let n = rows(dataset, self.dimensionality, "dataset")?;
1045 let config = self.build(n as u64)?;
1046 ScannIndex::with_training_threads(dataset, self.dimensionality, &config, self.training_threads)
1047 }
1048}