tensor4all_tensorci/
lib.rs

1#![warn(missing_docs)]
2//! Tensor Cross Interpolation (TCI) library
3//!
4//! This crate provides tensor cross interpolation algorithms for efficiently
5//! approximating high-dimensional tensors as tensor trains. Given a function
6//! `f(i_1, ..., i_N)` defined on a discrete multi-index grid, TCI finds a
7//! low-rank [`TensorTrain`](tensor4all_simplett::TensorTrain) approximation by
8//! evaluating only a small subset of the total entries.
9//!
10//! # Algorithms
11//!
12//! | Entry point | Algorithm | State type | Notes |
13//! |---|---|---|---|
14//! | [`crossinterpolate2`] | TCI2 (two-site) | [`TensorCI2`] | **Primary, actively maintained** |
15//! | [`crossinterpolate1`] | TCI1 (one-site) | [`TensorCI1`] | Legacy, kept for compatibility |
16//!
17//! `TCI2` uses [`MatrixLUCI`](tensor4all_tcicore::MatrixLUCI) for pivot
18//! updates and supports batch evaluation, global pivot search, and two pivot
19//! search strategies ([`PivotSearchStrategy::Full`] and
20//! [`PivotSearchStrategy::Rook`]).
21//!
22//! # Quick start
23//!
24//! ```
25//! use tensor4all_tensorci::{crossinterpolate2, TCI2Options};
26//! use tensor4all_simplett::AbstractTensorTrain;
27//!
28//! // Function to interpolate: f(i, j) = i + j + 1
29//! let f = |idx: &Vec<usize>| (idx[0] + idx[1] + 1) as f64;
30//! let local_dims = vec![4, 4];
31//! let first_pivot = vec![vec![1, 1]];
32//!
33//! let (tci, _ranks, errors) =
34//!     crossinterpolate2::<f64, _, fn(&[Vec<usize>]) -> Vec<f64>>(
35//!         f,
36//!         None,
37//!         local_dims,
38//!         first_pivot,
39//!         TCI2Options::default(),
40//!     )
41//!     .unwrap();
42//!
43//! // Check convergence
44//! assert!(*errors.last().unwrap() < 1e-6);
45//!
46//! // Evaluate through the tensor train
47//! let tt = tci.to_tensor_train().unwrap();
48//! let val = tt.evaluate(&[2, 3]).unwrap();
49//! assert!((val - 6.0).abs() < 1e-10); // f(2,3) = 2+3+1 = 6
50//! ```
51//!
52//! # Related crates
53//!
54//! - [`tensor4all_tcicore`] -- low-level matrix CI primitives and
55//!   [`CachedFunction`]
56//! - [`tensor4all_simplett`] -- the [`TensorTrain`](tensor4all_simplett::TensorTrain)
57//!   data structure produced by TCI
58//! - `tensor4all-quanticstci` -- higher-level quantics TCI on discrete
59//!   or continuous grids (wraps this crate)
60
61#[cfg(doctest)]
62#[doc = include_str!("../README.md")]
63pub struct ReadmeDoctests;
64
65pub mod error;
66pub mod globalpivot;
67pub mod globalsearch;
68pub mod integration;
69pub mod optfirstpivot;
70pub mod tensorci1;
71pub mod tensorci2;
72
73// Re-export main types
74pub use error::{Result, TCIError};
75pub use globalpivot::{DefaultGlobalPivotFinder, GlobalPivotFinder, GlobalPivotSearchInput};
76pub use globalsearch::{estimate_true_error, floating_zone};
77pub use optfirstpivot::opt_first_pivot;
78pub use tensorci1::{crossinterpolate1, SweepStrategy, TCI1Options, TensorCI1};
79pub use tensorci2::{
80    crossinterpolate2, PivotSearchStrategy, Sweep2Strategy, TCI2Options, TensorCI2,
81};
82
83pub use tensor4all_tcicore::{
84    CacheKey, CacheKeyError, CachedFunction, IndexInt, IndexSet, LocalIndex, MultiIndex, Scalar,
85};
tensor4all_tensorci/lib.rs

tensor4all_tensorci/
lib.rs
