nerdamer 1.1.13 → 2.0.0-rc.1

package/output/algebra/algorithms/groebnerBase.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @module groebner
+ *
+ * Gröbner basis computation, elimination, ideal membership, and solving.
+ *
+ * This implementation is a Buchberger-style engine with:
+ * - configurable monomial order (LEX, GRLEX, GREVLEX)
+ * - sugar-strategy pair selection for performance
+ * - optional budgets and stats
+ * - fraction-free normal form helpers
+ * - elimination ideals
+ * - ideal membership testing
+ * - triangular back-substitution solver
+ */
+import { MultiPoly } from './multiPoly/MultiPoly';
+/** Monomial order used for leading terms, pair processing, and reduction. */
+export type MonomialOrder = 'LEX' | 'GRLEX' | 'GREVLEX';
+/** Deterministic work counters captured when a Groebner resource budget is exceeded. */
+export type GroebnerStats = {
+    /** Critical pairs removed from the processing queue. */
+    pairsPopped: number;
+    /** Pairs skipped because their leading monomials are relatively prime. */
+    pairsSkippedProduct: number;
+    /** Pairs skipped by Buchberger's chain criterion. */
+    pairsSkippedChain: number;
+    /** Processed pairs whose reduced S-polynomial was zero. */
+    pairsReducedToZero: number;
+    /** Nonzero reduced S-polynomials appended to the working basis. */
+    basisAppends: number;
+};
+/** Controls monomial order, result normalization, pair strategy, and deterministic budgets. */
+export type GroebnerBasisOptions = {
+    /** Monomial order; defaults to `LEX`. Variable priority follows exponent index order. */
+    order?: MonomialOrder;
+    /**
+     * If true (default), return a reduced/normalized basis (canonicalize/interreduce/primitive normalize).
+     * If false, returns the raw Buchberger basis as produced by the pair loop.
+     */
+    reduced?: boolean;
+    /** Hard cap on Buchberger pair iterations (deterministic, not time-based). */
+    maxPairsPopped?: number;
+    /** Hard cap on basis size (including initial generators). */
+    maxBasisSize?: number;
+    /**
+     * Pair selection strategy.
+     * - 'sugar' (default): use sugar degree heuristic for better performance
+     * - 'fifo': simple first-in first-out (original behavior)
+     */
+    strategy?: 'sugar' | 'fifo';
+};
+/**
+ * Thrown when a Groebner pair-count or basis-size budget is exhausted.
+ *
+ * {@link GroebnerBudgetExceeded.stats} is the live counter snapshot from the aborted
+ * computation. The error keeps that object by reference and does not freeze it.
+ */
+export declare class GroebnerBudgetExceeded extends Error {
+    /** Work counters at the point the budget was exceeded. */
+    readonly stats: GroebnerStats;
+    /**
+     * @param message - Human-readable budget condition.
+     * @param stats - Counter snapshot retained on the error.
+     */
+    constructor(message: string, stats: GroebnerStats);
+}
+/**
+ * Computes a Groebner basis for an exact integer-coefficient ideal.
+ *
+ * @remarks
+ * Variable indices in every {@link MultiPoly} must agree with `vars`. The Buchberger
+ * engine uses fraction-free reduction. With `reduced: true`, it interreduces, removes
+ * coefficient content, normalizes leading signs, and makes a polynomial monic only
+ * when exact integer division permits it. The returned basis is sorted deterministically,
+ * and the routine works from normalized copies rather than editing the supplied generators.
+ *
+ * @param polys - Ideal generators over integer coefficients.
+ * @param vars - Variable names aligned with exponent indices.
+ * @param order - Monomial order; defaults to `LEX`.
+ * @param reduced - Return the normalized/interreduced basis; defaults to `true`.
+ * @returns New basis polynomials in deterministic presentation order.
+ */
+export declare function Groebner(polys: MultiPoly[], vars: string[], order?: MonomialOrder, reduced?: boolean): MultiPoly[];
+/**
+ * Computes a Groebner basis with ordering, strategy, and budget control.
+ *
+ * @param polys - Exact integer-coefficient generators with consistent variable indices.
+ * @param opts - Ordering, normalization, pair-selection, and deterministic budget options.
+ * @returns New basis polynomials. Work statistics are exposed only when a budget is
+ * exceeded; successful calls return the basis itself.
+ * @throws {@link GroebnerBudgetExceeded} Thrown after a configured pair-count or
+ * basis-size limit is exceeded.
+ */
+export declare function groebnerBasisWithOptions(polys: readonly MultiPoly[], opts?: GroebnerBasisOptions): MultiPoly[];
+/**
+ * Computes the part of the ideal that lies in the polynomial ring generated by `keepVars`.
+ *
+ * @param polys - Exact integer-coefficient generators.
+ * @param vars - All variables in exponent-index order. Variables to eliminate must
+ * precede retained variables for lexicographic elimination.
+ * @param keepVars - Variables to retain, expected to be a suffix of `vars`.
+ * @param opts - Reduction, pair strategy, and budgets; order is always `LEX`.
+ * @returns New basis polynomials involving only retained variables.
+ * @throws {@link GroebnerBudgetExceeded} Thrown when a configured budget is exceeded.
+ */
+export declare function eliminate(polys: MultiPoly[], vars: string[], keepVars: string[], opts?: Omit<GroebnerBasisOptions, 'order'>): MultiPoly[];
+/**
+ * Tests exact ideal membership by reducing against a computed Groebner basis.
+ *
+ * @param f - Polynomial to test.
+ * @param polys - Exact integer-coefficient ideal generators.
+ * @param order - Monomial order; defaults to `LEX`.
+ * @param opts - Pair strategy and deterministic budgets.
+ * @returns Whether the normal form of `f` is zero.
+ * @throws {@link GroebnerBudgetExceeded} Thrown when basis computation exceeds a budget.
+ */
+export declare function idealMembership(f: MultiPoly, polys: MultiPoly[], order?: MonomialOrder, opts?: Omit<GroebnerBasisOptions, 'order' | 'reduced'>): boolean;
+/**
+ * Reduces a polynomial by a basis or arbitrary reducer set using fraction-free arithmetic.
+ *
+ * @remarks
+ * This does not compute or verify a Groebner basis. The result is a canonical ideal
+ * normal form only when `basis` is already a basis for the selected order. Reduction
+ * works from normalized polynomial copies, leaving the supplied objects alone.
+ *
+ * @param f - Polynomial to reduce.
+ * @param basis - Reducers, normally a Groebner basis.
+ * @param order - Monomial order used to select leading terms.
+ * @returns The primitive-normalized remainder.
+ */
+export declare function reduceByBasis(f: MultiPoly, basis: readonly MultiPoly[], order?: MonomialOrder): MultiPoly;
+/**
+ * Maps each solved variable to a reduced rational numerator/denominator pair.
+ *
+ * Only rational coordinates discovered by triangular back-substitution are represented.
+ */
+export type RationalSolution = Map<string, {
+    n: bigint;
+    d: bigint;
+}>;
+/**
+ * Solves a zero-dimensional polynomial system for rational coordinates.
+ *
+ * @remarks
+ * This is the low-level exact solver used with the Groebner representation, not the
+ * ordinary expression solver. It computes a reduced lexicographic basis, walks variables
+ * from least to most significant, applies the Rational Root Theorem to univariate
+ * constraints, and substitutes each partial assignment into its own basis copy.
+ * Irrational and complex roots are outside this routine's result set.
+ *
+ * @param polys - Exact integer-coefficient system generators.
+ * @param vars - Variables in lexicographic elimination order, most significant first.
+ * @param opts - Pair strategy and budgets forwarded to basis computation.
+ * @returns New solution maps. An empty array can mean inconsistency, no rational roots,
+ * or a non-finite/unsupported triangular result; these cases are not distinguished.
+ * @throws {@link GroebnerBudgetExceeded} Thrown when basis computation exceeds a budget.
+ */
+export declare function solve(polys: MultiPoly[], vars: string[], opts?: Omit<GroebnerBasisOptions, 'order' | 'reduced'>): RationalSolution[];