algroots 0.1.0__py3-none-any.whl

algroots/__init__.py

@@ -0,0 +1,123 @@
+"""Numerical and exact roots of zero-dimensional algebraic equation systems."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .algebraic import AlgebraicSystemRoots, algsolve
+from .algebraization import AlgebraizedSystem, algebraize_system
+from .border_basis import (
+    BorderBasisDiagnostics,
+    BorderBasisError,
+    BorderBasisResult,
+    compute_border_basis,
+    compute_border_basis_linear,
+)
+from .continuation import (
+    HomotopySystem,
+    PathResult,
+    PathStep,
+    PathStepError,
+    PathTrackerOptions,
+    PathTrackingError,
+    SympyHomotopy,
+    track_path,
+)
+from .errors import (
+    ActionMatrixError,
+    HomotopySolveError,
+    NotZeroDimensionalError,
+    NumericalRootError,
+    PolynomialSystemError,
+    PolynomialSystemInputError,
+    ShapePositionError,
+    SystemSolveLimitError,
+    TriangularSolveError,
+)
+from .monodromy import (
+    MonodromyLoop,
+    MonodromyOrbitResult,
+    MonodromyPermutation,
+    MonodromyRootInfo,
+    closed_additive_loop,
+    discover_monodromy_orbit,
+    monodromy_permutation,
+    track_loop,
+)
+from .monodromy_stopping import (
+    CaptureRecaptureEstimate,
+    capture_recapture_estimate,
+    second_order_trace_test,
+)
+from .rational_univariate import (
+    RationalUnivariateError,
+    RationalUnivariatePoint,
+    RationalUnivariateRepresentation,
+    compute_rational_univariate_representation,
+    solve_rur_points,
+    solve_rur_representation,
+    solve_zero_dimensional_system_with_rur,
+)
+from .recognition import (
+    ExactCertificationError,
+    RecognizedSystemRoot,
+    recognize_system_roots,
+)
+from .solver import PolynomialSystemRoots, RootDiagnostics, polysolve
+
+try:
+    __version__ = version("algroots")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+__all__ = [
+    "HomotopySystem",
+    "SympyHomotopy",
+    "PathTrackerOptions",
+    "PathStep",
+    "PathResult",
+    "PathTrackingError",
+    "PathStepError",
+    "track_path",
+    "CaptureRecaptureEstimate",
+    "capture_recapture_estimate",
+    "second_order_trace_test",
+    "MonodromyLoop",
+    "MonodromyPermutation",
+    "MonodromyOrbitResult",
+    "MonodromyRootInfo",
+    "closed_additive_loop",
+    "track_loop",
+    "monodromy_permutation",
+    "discover_monodromy_orbit",
+    "algsolve",
+    "polysolve",
+    "algebraize_system",
+    "AlgebraicSystemRoots",
+    "AlgebraizedSystem",
+    "recognize_system_roots",
+    "PolynomialSystemRoots",
+    "RootDiagnostics",
+    "RecognizedSystemRoot",
+    "ExactCertificationError",
+    "PolynomialSystemError",
+    "PolynomialSystemInputError",
+    "NotZeroDimensionalError",
+    "ActionMatrixError",
+    "HomotopySolveError",
+    "ShapePositionError",
+    "TriangularSolveError",
+    "NumericalRootError",
+    "SystemSolveLimitError",
+    "RationalUnivariateError",
+    "RationalUnivariateRepresentation",
+    "RationalUnivariatePoint",
+    "compute_rational_univariate_representation",
+    "solve_zero_dimensional_system_with_rur",
+    "solve_rur_representation",
+    "solve_rur_points",
+    "BorderBasisDiagnostics",
+    "BorderBasisError",
+    "BorderBasisResult",
+    "compute_border_basis",
+    "compute_border_basis_linear",
+    "__version__",
+]

algroots/_validation.py

@@ -0,0 +1,48 @@
+"""Shared lightweight input and option validation."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+import sympy as sp
+
+from .errors import PolynomialSystemInputError
+
+
+def validate_variables(variables: Sequence[Any]) -> tuple[Any, ...]:
+    """Validate and normalize a nonempty sequence of distinct SymPy symbols."""
+    vars_tuple = tuple(variables)
+    if not vars_tuple:
+        raise PolynomialSystemInputError("at least one variable is required")
+    if len(set(vars_tuple)) != len(vars_tuple):
+        raise PolynomialSystemInputError("variables must be distinct")
+    if any(not isinstance(var, sp.Symbol) for var in vars_tuple):
+        raise PolynomialSystemInputError("variables must be SymPy Symbol objects")
+    return vars_tuple
+
+
+def normalize_equation(equation: Any, *, expand: bool = False) -> Any:
+    """Convert an equality/expression to a zero-form expression."""
+    equation = sp.sympify(equation)
+    if equation is sp.true:
+        expression = sp.Integer(0)
+    elif equation is sp.false:
+        expression = sp.Integer(1)
+    elif isinstance(equation, sp.Equality):
+        expression = equation.lhs - equation.rhs
+    elif equation.is_Relational:
+        raise PolynomialSystemInputError(
+            "only equalities are supported; inequalities are outside algroots' scope"
+        )
+    else:
+        expression = equation
+    return sp.expand(expression) if expand else expression
+
+
+def validate_recognition_options(recognize: bool, max_degree: int) -> None:
+    """Validate common automatic-recognition options."""
+    if not isinstance(recognize, bool):
+        raise TypeError("recognize must be bool")
+    if not isinstance(max_degree, int) or max_degree <= 0:
+        raise ValueError("recognition_max_degree must be a positive integer")

algroots/algebraic.py

@@ -0,0 +1,329 @@
+"""All-roots solving for exact algebraic equation systems."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import mpmath as mp
+import sympy as sp
+
+from ._validation import validate_recognition_options
+from .algebraization import AlgebraizedSystem, algebraize_system
+from .numerical import NumericExpression, number_to_mpc
+from .solver import (
+    PolynomialSystemRoots,
+    RootDiagnostics,
+    SolveMethod,
+    _roots_close,
+    polysolve,
+)
+
+
+@dataclass(frozen=True)
+class AlgebraicSystemRoots(PolynomialSystemRoots):
+    """Verified roots of an algebraic system and its polynomialization metadata."""
+
+    polynomial_equations: tuple[Any, ...] = ()
+    polynomial_variables: tuple[Any, ...] = ()
+    auxiliary_variables: tuple[Any, ...] = ()
+    nonzero_constraints: tuple[Any, ...] = ()
+    homotopy_projected_candidates: int | None = None
+    homotopy_projected_roots_rejected: int | None = None
+
+
+@dataclass(frozen=True)
+class _ProjectedRoot:
+    """Projected algebraic root with aligned diagnostics and residual."""
+
+    root: tuple[Any, ...]
+    diagnostics: RootDiagnostics
+    residual: Any
+
+
+@dataclass(frozen=True)
+class _ProjectedCandidate:
+    """Projected algebraic root and its original-system residual."""
+
+    root: tuple[Any, ...]
+    relative_residual: mp.mpf
+
+
+class _AlgebraicProjector:
+    """Lift original seeds and verify projected roots for one algebraization."""
+
+    def __init__(self, algebraized: AlgebraizedSystem):
+        self.algebraized = algebraized
+        self.original_count = len(algebraized.original_variables)
+        self._equation_evals = tuple(
+            _CompiledAlgResidual.build(eq, algebraized.original_variables)
+            for eq in algebraized.original_equations
+        )
+        self._constraint_evals = tuple(
+            NumericExpression(constraint, algebraized.augmented_variables)
+            for constraint in algebraized.nonzero_constraints
+        )
+        lift_evals = []
+        for index, expression in enumerate(algebraized.auxiliary_lift_expressions):
+            variables = algebraized.original_variables + algebraized.auxiliary_variables[:index]
+            lift_evals.append(NumericExpression(expression, variables))
+        self._lift_evals = tuple(lift_evals)
+
+    def lift(self, root: Sequence[Any], digits: int) -> tuple[mp.mpc, ...]:
+        """Lift an original-variable root to the principal algebraic sheet."""
+        if len(root) != self.original_count:
+            raise ValueError("every seed root must have one coordinate per variable")
+        with mp.workdps(digits + 10):
+            values = [number_to_mpc(value, digits + 5) for value in root]
+            for evaluator in self._lift_evals:
+                values.append(evaluator.evaluate(tuple(values), digits + 5))
+            return tuple(values)
+
+    def project(
+        self,
+        full_root: Sequence[Any],
+        *,
+        work_digits: int,
+        verification_digits: int,
+    ) -> _ProjectedCandidate | None:
+        """Project and verify one augmented root against the original system."""
+        if len(full_root) != len(self.algebraized.augmented_variables):
+            raise ValueError("augmented root dimension does not match polynomial variables")
+        with mp.workdps(work_digits + 10):
+            values = tuple(number_to_mpc(value, work_digits + 5) for value in full_root)
+            threshold = mp.power(10, -verification_digits)
+            if any(
+                abs(evaluator.evaluate(values, work_digits + 5)) <= threshold
+                for evaluator in self._constraint_evals
+            ):
+                return None
+            projected_values = values[: self.original_count]
+            residual = max(
+                (
+                    evaluator.evaluate(projected_values, work_digits + 5)
+                    for evaluator in self._equation_evals
+                ),
+                default=mp.mpf(0),
+            )
+            if not mp.isfinite(residual) or residual > threshold:
+                return None
+            return _ProjectedCandidate(
+                tuple(full_root[: self.original_count]),
+                mp.mpf(residual),
+            )
+
+
+def _project_candidates(
+    projector: _AlgebraicProjector,
+    roots: Sequence[Sequence[Any]],
+    precisions: Sequence[tuple[int, int]],
+):
+    """Yield projected candidates using aligned work/verification precisions."""
+    if len(roots) != len(precisions):
+        raise ValueError("projection precision metadata must align with roots")
+    for root, (work_digits, verification_digits) in zip(roots, precisions, strict=True):
+        yield projector.project(
+            root,
+            work_digits=work_digits,
+            verification_digits=verification_digits,
+        )
+
+
+@dataclass(frozen=True)
+class _CompiledAlgResidual:
+    evaluator: NumericExpression
+    term_evaluators: tuple[NumericExpression, ...]
+
+    @classmethod
+    def build(cls, expression: Any, variables: tuple[Any, ...]):
+        return cls(
+            evaluator=NumericExpression(expression, variables),
+            term_evaluators=tuple(
+                NumericExpression(term, variables) for term in sp.Add.make_args(expression)
+            ),
+        )
+
+    def evaluate(self, values: tuple[Any, ...], digits: int) -> mp.mpf:
+        with mp.workdps(digits + 8):
+            value = self.evaluator.evaluate(values, digits + 5)
+            if len(self.term_evaluators) == 1:
+                scale = max(mp.mpf(1), abs(value))
+            else:
+                scale = sum(
+                    (abs(term.evaluate(values, digits + 5)) for term in self.term_evaluators),
+                    mp.mpf(0),
+                )
+                scale = max(mp.mpf(1), scale)
+            return abs(value) / scale
+
+
+def _filter_algebraic_roots(
+    polynomial_result: PolynomialSystemRoots,
+    algebraized: AlgebraizedSystem,
+    *,
+    include_projection_counts: bool = False,
+):
+    digits = polynomial_result.precision_digits
+    verify_digits = polynomial_result.verification_digits
+    work_digits = polynomial_result.working_digits
+    projector = _AlgebraicProjector(algebraized)
+
+    records: list[_ProjectedRoot] = []
+    rejected = 0
+    precisions = ((work_digits + 5, verify_digits),) * len(polynomial_result.roots)
+    for index, candidate in enumerate(
+        _project_candidates(projector, polynomial_result.roots, precisions)
+    ):
+        if candidate is None:
+            rejected += 1
+            continue
+        residual = sp.Float(mp.nstr(candidate.relative_residual, work_digits), work_digits)
+        if index < len(polynomial_result.diagnostics):
+            diagnostics = polynomial_result.diagnostics[index]
+        else:
+            diagnostics = RootDiagnostics(
+                initial_relative_residual=residual,
+                final_relative_residual=residual,
+                refinement_attempted=False,
+                refinement_succeeded=False,
+                refinement_improved=False,
+            )
+        records.append(_ProjectedRoot(candidate.root, diagnostics, residual))
+
+    tolerance_sp = sp.Float(10, digits) ** (-max(8, digits - 5))
+    comparison_digits = max(30, digits + 10)
+    unique: list[_ProjectedRoot] = []
+    for record in records:
+        if any(
+            _roots_close(
+                record.root,
+                existing.root,
+                tolerance_sp,
+                comparison_digits=comparison_digits,
+            )
+            for existing in unique
+        ):
+            continue
+        unique.append(record)
+
+    roots = tuple(record.root for record in unique)
+    diagnostics = tuple(record.diagnostics for record in unique)
+    max_relative_residual = max(
+        (record.residual for record in unique),
+        default=sp.Integer(0),
+    )
+    if include_projection_counts:
+        return (
+            roots,
+            diagnostics,
+            max_relative_residual,
+            len(records),
+            rejected + (len(records) - len(unique)),
+        )
+    return roots, diagnostics, max_relative_residual
+
+
+def algsolve(
+    equations: Iterable[Any],
+    variables: Sequence[Any],
+    *,
+    digits: int = 50,
+    verification_digits: int | None = None,
+    guard_digits: int = 10,
+    maxsteps: int = 200,
+    max_solutions: int = 10_000,
+    max_action_dimension: int = 256,
+    max_precision_digits: int | None = None,
+    max_auxiliary_variables: int = 32,
+    method: SolveMethod = "auto",
+    recognize: bool = True,
+    recognition_max_degree: int = 8,
+    max_homotopy_paths: int = 10_000,
+    homotopy_seed: int = 0,
+    homotopy_gamma_attempts: int = 4,
+    homotopy_parallel: bool = False,
+    homotopy_max_workers: int | None = None,
+) -> AlgebraicSystemRoots:
+    """Find all distinct roots of a zero-dimensional exact algebraic system.
+
+    Exact algebraic recognition is attempted by default for the final projected
+    roots. Pass ``recognize=False`` to disable recognition.
+
+    Supported variable-dependent algebraic operations are rational functions and
+    rational powers, including nested radicals. Rational powers use SymPy's
+    principal-branch semantics. Algebraization may introduce extra polynomial
+    branches, so every projected result is checked against the original equations
+    and all retained denominator constraints before it is returned.
+    """
+    validate_recognition_options(recognize, recognition_max_degree)
+    algebraized = algebraize_system(
+        equations,
+        variables,
+        max_auxiliary_variables=max_auxiliary_variables,
+    )
+    polynomial_result = polysolve(
+        algebraized.polynomial_equations,
+        algebraized.augmented_variables,
+        digits=digits,
+        verification_digits=verification_digits,
+        guard_digits=guard_digits,
+        maxsteps=maxsteps,
+        max_solutions=max_solutions,
+        max_action_dimension=max_action_dimension,
+        max_precision_digits=max_precision_digits,
+        method=method,
+        recognize=False,
+        max_homotopy_paths=max_homotopy_paths,
+        homotopy_seed=homotopy_seed,
+        homotopy_gamma_attempts=homotopy_gamma_attempts,
+        homotopy_parallel=homotopy_parallel,
+        homotopy_max_workers=homotopy_max_workers,
+    )
+    (
+        roots,
+        diagnostics,
+        max_residual,
+        projected_candidates,
+        projected_rejected,
+    ) = _filter_algebraic_roots(
+        polynomial_result,
+        algebraized,
+        include_projection_counts=True,
+    )
+
+    result = AlgebraicSystemRoots(
+        roots=roots,
+        variables=algebraized.original_variables,
+        equations=algebraized.original_equations,
+        groebner_basis=polynomial_result.groebner_basis,
+        precision_digits=polynomial_result.precision_digits,
+        working_digits=polynomial_result.working_digits,
+        verification_digits=polynomial_result.verification_digits,
+        max_relative_residual=max_residual,
+        method=polynomial_result.method,
+        diagnostics=diagnostics,
+        eliminant=polynomial_result.eliminant,
+        parameter_variable=polynomial_result.parameter_variable,
+        quotient_dimension=polynomial_result.quotient_dimension,
+        standard_monomials=polynomial_result.standard_monomials,
+        separator_coeffs=polynomial_result.separator_coeffs,
+        rational_univariate_representation=polynomial_result.rational_univariate_representation,
+        homotopy_paths_total=polynomial_result.homotopy_paths_total,
+        homotopy_paths_succeeded=polynomial_result.homotopy_paths_succeeded,
+        homotopy_paths_failed=polynomial_result.homotopy_paths_failed,
+        homotopy_paths_divergent=polynomial_result.homotopy_paths_divergent,
+        homotopy_gamma=polynomial_result.homotopy_gamma,
+        homotopy_gamma_attempts=polynomial_result.homotopy_gamma_attempts,
+        homotopy_endpoint_smallest_singular_values=polynomial_result.homotopy_endpoint_smallest_singular_values,
+        homotopy_endpoint_condition_estimates=polynomial_result.homotopy_endpoint_condition_estimates,
+        polynomial_equations=algebraized.polynomial_equations,
+        polynomial_variables=algebraized.augmented_variables,
+        auxiliary_variables=algebraized.auxiliary_variables,
+        nonzero_constraints=algebraized.nonzero_constraints,
+        homotopy_projected_candidates=(projected_candidates if method == "homotopy" else None),
+        homotopy_projected_roots_rejected=(projected_rejected if method == "homotopy" else None),
+    )
+    from .recognition import _auto_recognize
+
+    return _auto_recognize(result, recognize=recognize, max_degree=recognition_max_degree)