ries_rs/
lib.rs

1// Allow field reassignment with default in test code - common pattern for config building
2#![cfg_attr(test, allow(clippy::field_reassign_with_default))]
3
4//! # RIES-RS: Find algebraic equations given their solution
5//!
6//! A Rust implementation of Robert Munafo's RIES (RILYBOT Inverse Equation Solver).
7//!
8//! Given a numeric target value, RIES searches for algebraic equations
9//! that have the target as a solution. For example, given π, it finds
10//! equations like `x = π`, `x² = 10`, `sin(πx) = 0`, etc.
11//!
12//! ## Features
13//!
14//! - **Parallel search** using Rayon for multi-core speedup
15//! - **Automatic differentiation** for Newton-Raphson refinement
16//! - **User-defined constants and functions** via profiles
17//! - **Multiple output formats**: default, pretty (Unicode), Mathematica, SymPy
18//! - **Complexity scoring** to find simplest equations first
19//!
20//! ## Quick Start
21//!
22//! ```rust,no_run
23//! use ries_rs::{search, search::level_to_complexity, GenConfig};
24//!
25//! let (max_lhs, max_rhs) = level_to_complexity(2);
26//! let config = GenConfig {
27//!     max_lhs_complexity: max_lhs,
28//!     max_rhs_complexity: max_rhs,
29//!     ..GenConfig::default()
30//! };
31//! let matches = search(2.5, &config, 10);
32//!
33//! // Should find equations like x = 5/2, x-2 = 1/2, etc.
34//! assert!(!matches.is_empty());
35//! ```
36//!
37//! ## Command-Line Usage
38//!
39//! ```bash
40//! # Find equations for π
41//! ries-rs 3.141592653589793
42//!
43//! # Higher search level (more results)
44//! ries-rs 2.5 -l 5
45//!
46//! # Restrict to algebraic solutions
47//! ries-rs 1.41421356 -a
48//! ```
49//!
50//! ## API Levels
51//!
52//! The library provides three API levels:
53//!
54//! ### High-Level API
55//!
56//! Simple functions for common use cases:
57//! - [`search()`] - Find equations for a target value
58//!
59//! ### Mid-Level API
60//!
61//! Configuration and control structures:
62//! - [`GenConfig`](gen::GenConfig) - Configure expression generation
63//! - [`SearchConfig`](search::SearchConfig) - Configure search behavior
64//! - [`Match`](search::Match) - A matched equation
65//!
66//! ### Low-Level API
67//!
68//! Building blocks for custom implementations:
69//! - [`Expression`](expr::Expression) - Symbolic expression representation
70//! - [`Symbol`](symbol::Symbol) - Individual symbols (constants, operators)
71//! - [`evaluate()`](eval::evaluate) - Evaluate expressions with derivatives
72//!
73//! ## Modules
74//!
75//! - [`eval`] - Expression evaluation with automatic differentiation
76//! - [`expr`] - Expression representation and manipulation
77//! - [`gen`] - Expression generation
78//! - [`metrics`] - Match scoring and categorization
79//! - [`pool`] - Bounded priority pool for match collection
80//! - [`precision`] - Precision abstraction for numeric types
81//! - [`profile`] - Profile file support for configuration
82//! - [`report`] - Categorized match output
83//! - [`search`] - Search algorithms and matching
84//! - [`symbol`] - Symbol definitions and type system
85//! - [`thresholds`] - Named threshold constants
86//! - [`udf`] - User-defined functions
87
88pub mod eval;
89pub mod expr;
90mod fast_match;
91pub mod gen;
92mod highprec_verify;
93mod manifest;
94mod match_summary;
95mod metrics;
96pub mod pool;
97#[cfg(feature = "highprec")]
98pub mod precision;
99mod presets;
100pub mod profile;
101mod pslq;
102mod report;
103pub mod search;
104mod solver;
105mod stability;
106pub mod symbol;
107mod symbol_table;
108mod thresholds;
109pub mod udf;
110#[cfg(feature = "wasm")]
111mod wasm;
112
113// WASM re-exports (when feature is enabled)
114#[cfg(feature = "wasm")]
115pub use wasm::{init, list_presets, search as wasm_search, version, SearchOptions, WasmMatch};
116
117// =============================================================================
118// Type Aliases
119// =============================================================================
120
121/// Type alias for complexity scores
122///
123/// Complexity scores measure how "simple" an expression is.
124/// Lower values indicate simpler expressions that will be shown first.
125///
126/// Uses `u32` to allow for very long expressions without overflow risk,
127/// though practical expressions typically have complexity < 500.
128pub type Complexity = u32;
129
130// =============================================================================
131// Re-exports for convenience
132// =============================================================================
133
134// High-level API
135pub use search::search;
136pub use solver::{canonical_expression_key, solve_for_x_rhs_expression};
137
138// Fast exact match detection
139pub use fast_match::{find_fast_match, find_fast_match_with_context, FastMatchConfig};
140
141// Common types
142pub use eval::{EvalContext, EvalError, EvalResult, DEFAULT_TRIG_ARGUMENT_SCALE};
143pub use expr::{Expression, OutputFormat};
144pub use gen::{expression_respects_constraints, ExpressionConstraintOptions, GenConfig};
145pub use profile::{Profile, UserConstant};
146pub use search::{Match, SearchConfig, SearchContext, SearchStats};
147pub use symbol::{NumType, Symbol};
148pub use symbol_table::SymbolTable;
149pub use udf::UserFunction;
150
151// Threshold constants
152pub use thresholds::{DEGENERATE_DERIVATIVE, EXACT_MATCH_TOLERANCE, NEWTON_TOLERANCE};
153
154// High-precision types (when feature is enabled)
155#[cfg(feature = "highprec")]
156pub use precision::{HighPrec, RiesFloat, DEFAULT_PRECISION};
157
158// Manifest types for reproducibility
159pub use manifest::{MatchInfo, RunManifest, SearchConfigInfo, UserConstantInfo};
160pub use match_summary::MatchSummary;
161
162// Structured reporting and analysis
163pub use highprec_verify::{
164    format_verification_report, verify_matches_highprec, verify_matches_highprec_with_trig_scale,
165    VerificationResult,
166};
167pub use metrics::MatchMetrics;
168pub use presets::{print_presets, Preset};
169pub use pslq::{find_integer_relation, find_rational_approximation, IntegerRelation, PslqConfig};
170pub use report::{DisplayFormat as ReportDisplayFormat, Report, ReportConfig};
171pub use stability::{
172    format_stability_report, StabilityAnalyzer, StabilityClass, StabilityConfig, StabilityResult,
173};
ries_rs/lib.rs

ries_rs/
lib.rs
