tempura_sa/
lib.rs

1// Crate-level lint policy (fine-grained overrides live in each module).
2// Deny-level lints are compile errors; warn-level appear in `cargo clippy`.
3// These mirror the [lints] table in Cargo.toml but apply to doc-tests too.
4#![deny(missing_docs, missing_debug_implementations)]
5#![warn(unused_qualifications, future_incompatible)]
6#![warn(clippy::pedantic, clippy::nursery)]
7#![allow(
8    // Common false-positives in a numerical library
9    clippy::module_name_repetitions,
10    clippy::must_use_candidate,
11    clippy::cast_precision_loss,
12    clippy::cast_possible_truncation,
13    clippy::cast_sign_loss,
14    clippy::missing_panics_doc,
15    clippy::similar_names,
16)]
17
18//! # Tempura — Temperature-Driven Optimization Primitives for Rust
19//!
20//! Tempura is a high-performance annealing framework providing composable
21//! primitives for temperature-based stochastic optimization.
22//!
23//! ## Quick Start
24//!
25//! ```rust
26//! use tempura_sa::prelude::*;
27//!
28//! fn main() -> Result<(), AnnealError> {
29//!     let result = Annealer::builder()
30//!         .objective(FnEnergy(|x: &Vec<f64>| x.iter().map(|v| v * v).sum()))
31//!         .moves(GaussianMove::new(0.5))
32//!         .schedule(Exponential::new(100.0, 0.9999))
33//!         .iterations(100_000)
34//!         .seed(42)
35//!         .build()?
36//!         .run(vec![5.0, -3.0, 7.0]);
37//!
38//!     println!("Best energy: {}", result.best_energy);
39//!     Ok(())
40//! }
41//! ```
42
43/// Single-solution simulated annealing engine with builder pattern.
44pub mod annealer;
45/// Run diagnostics, trajectory recording, and result types.
46pub mod diagnostics;
47/// Energy (cost function) trait and helpers.
48pub mod energy;
49/// Error types for configuration and runtime failures.
50pub mod error;
51/// Benchmark landscapes for testing and validation.
52pub mod landscape;
53/// Numerical primitives: acceptance functions, fast exp, quantum tunneling.
54pub mod math;
55/// Move operators: Gaussian perturbation, neighbor swap, and custom moves.
56pub mod moves;
57/// Parallel tempering (replica exchange) algorithm.
58pub mod parallel;
59/// Population annealing with Boltzmann-weighted resampling.
60pub mod population;
61/// Deterministic pseudo-random number generators.
62pub mod rng;
63/// Cooling schedules: linear, exponential, logarithmic, adaptive, and more.
64pub mod schedule;
65/// State trait (blanket impl for `Clone + Debug`).
66pub mod state;
67
68/// Convenience re-exports for the most common types.
69pub mod prelude {
70    pub use crate::annealer::builder as annealer_builder;
71    pub use crate::diagnostics::{AnnealResult, RunDiagnostics};
72    pub use crate::energy::{Energy, FnEnergy};
73    pub use crate::error::AnnealError;
74    pub use crate::moves::{GaussianMove, MoveOperator, SwapMove};
75    pub use crate::rng::{DefaultRng, Rng, Xoshiro256PlusPlus};
76    pub use crate::schedule::{
77        Adaptive, Cauchy, CoolingSchedule, Exponential, Fast, Linear, Logarithmic,
78    };
79
80    /// Entry point for building an annealer.
81    #[derive(Debug, Clone, Copy)]
82    pub struct Annealer;
83
84    impl Annealer {
85        /// Create a new annealer builder.
86        pub const fn builder<S>() -> crate::annealer::AnnealerBuilder<S, (), (), ()> {
87            crate::annealer::builder()
88        }
89    }
90}
tempura_sa/lib.rs

tempura_sa/
lib.rs
