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

ries_rs/
lib.rs
