algroots 0.2.0__tar.gz → 0.3.0__tar.gz

algroots-0.3.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## 0.3.0
+
+### Certified rational functional decomposition
+
+`rational_decompose` searches for two-component decompositions of univariate rational functions over a specified rational or algebraic-number constant field. It enumerates eligible products of factors of a near-separated polynomial, reconstructs the inner and outer functions, and verifies the composition identity. Results distinguish complete searches, certified indecomposability, successful decompositions, and searches stopped by candidate or degree limits. Original denominator exclusions are retained when present in the input.
+
+### Multivariate functional decomposition
+
+`multivariate_rational_decompose` implements the decomposition method of Gutiérrez, Rubio and Sevilla, with a univariate rational outer component and multivariate rational inner component. Candidate enumeration is lazy and degree-aware; composition identities and search-status claims are replayable. Passing a tuple or list of variables to `rational_decompose` selects this interface.
+
+### Implicit algebraic decomposition
+
+`algebraic_decompose` reconstructs components from supplied algebraic factors or discovers coefficient extensions and factors automatically. Discovery uses universal monic-factor algebras and Galois-orbit coverage, avoiding construction of a full splitting field in the supported cases. Certificates verify coefficient normalization and the implicit composition through resultant identities, including necessary powers.
+
+### Recursive decomposition chains
+
+Added APIs for rational and implicit algebraic decomposition chains, including an optional supplied initial split. Results retain composed identities, replayable split trees, and reasons for unresolved leaves. Chain completeness describes the selected decomposition tree, not enumeration of every possible tree.
+
+### Constructive subfields and function fields
+
+Finite quotient fields now support generated subfields, exact membership and nonmembership, primitive-element presentations, and verified embeddings. `coefficient_field` builds fields generated by specified coefficients over the declared constants, with saturated image presentations and memebership tests for supported algebraic extensions. Constructive Lüroth generators and inverse maps are available for supported univariate and multivariate rational inputs of transcendence degree at most one.
+
+### Normalized plane curves
+
+`algroots.curves` computes geometric genus through projective normalisation, including singularities at infinity and infinitely near points. For supported genus-zero curves, it constructs and verifies birational parametrisations, records exceptional affine charts, and distinguishes rationality over the original constant field from rationality after an explicit extension. Conic descent can identify rational-point obstructions over `QQ`.
+
+### Rational-function coefficient domains
+
+Finite quotient algebras accept explicit rational-function fields over rational or algebraic-number constants. Multiplication matrices, minimal and characteristic polynomials, traces, norms, inverses, and field checks preserve the coefficient domain. `specialize` reconstructs a quotient from its defining equations at parameter values.
+
+### Finite-field quotient tools
+
+Added finite coefficient-field constructors and univariate factorization, together with nilradical bases, reduced quotients, primary decompositions, and Frobenius operations for supported finite algebras. Nonreduced and nonmonogenic examples are covered.
+
+### Documentation and tests
+
+Added guides and executable examples for functional decomposition, generated function fields, plane curves, and rational-function quotient domains. Expanded regression tests.
+
+## 0.2.0
+
+- Faster exact solving with guarded presolve, improved variable ordering and backend selection, and Gröbner order conversion only when needed.
+- Shared quotient algebra for RURs, multiplication matrices and border bases, with selective caching, lower-memory trace calculations and cost diagnostics.
+- Explicit completeness evidence, radical/nonreduced metadata and multiplicities, exact root certificates and adaptive certification boxes.
+- Bounded singular-root recovery through endgames, deflation and automatic projective chart switching, with clear certification limits.
+- More robust small and clustered roots, bounded Arb precision retries and consistent input checks.
+- Expanded tests, benchmarks, documentation; added 15 examples.

{algroots-0.2.0 → algroots-0.3.0}/CITATION.cff

@@ -5,6 +5,6 @@ type: software
 authors:
   - family-names: "Bhatt"
     given-names: "Bhuvanesh"
-version: "0.2.0"
+version: "0.3.0"
 license: "GPL-3.0-only"
 url: "https://pypi.org/project/algroots/"

algroots-0.3.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include CHANGELOG.md CITATION.cff CONTRIBUTING.md LICENSE README.md
+recursive-include docs *.md
+recursive-include examples *.py *.md *.json
+recursive-include benchmarks *.py *.md *.json *.txt
+recursive-include tests *.py
+recursive-include tools *.py
+recursive-exclude * __pycache__ *.py[cod] .DS_Store
+prune .pytest_cache
+prune .ruff_cache
+prune build
+prune dist

{algroots-0.2.0 → algroots-0.3.0}/PKG-INFO

@@ -1,16 +1,15 @@
-Metadata-Version: 2.5
+Metadata-Version: 2.4
 Name: algroots
-Version: 0.2.0
-Summary: Exact and approximate methods for solving zero-dimensional polynomial and algebraic systems.
+Version: 0.3.0
+Summary: Exact and numerical algebraic computation: polynomial systems, finite algebras, function fields, functional decomposition, and plane curves.
+Author-email: Bhuvanesh Bhatt <bhuvaneshbhatt@gmail.com>
+License-Expression: GPL-3.0-only
 Project-URL: Homepage, https://github.com/BhuvaneshBhatt/algroots
 Project-URL: Documentation, https://github.com/BhuvaneshBhatt/algroots/tree/main/docs
 Project-URL: Repository, https://github.com/BhuvaneshBhatt/algroots.git
 Project-URL: Issues, https://github.com/BhuvaneshBhatt/algroots/issues
 Project-URL: Changelog, https://github.com/BhuvaneshBhatt/algroots/blob/main/CHANGELOG.md
-Author-email: Bhuvanesh Bhatt <bhuvaneshbhatt@gmail.com>
-License-Expression: GPL-3.0-only
-License-File: LICENSE
-Keywords: algebraic-equations,algebraic-geometry,algebraic-numbers,border-basis,groebner-basis,numerical-roots,polynomial-systems,radicals,rational-functions,rational-univariate-representation
+Keywords: algebraic-equations,polynomial-systems,radicals,rational-functions,groebner-basis,algebraic-geometry,numerical-roots,algebraic-numbers,rational-univariate-representation,border-basis
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
@@ -20,35 +19,37 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Requires-Python: >=3.11
-Requires-Dist: algrecognize>=0.1.1
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sympy<2,>=1.14
 Requires-Dist: mpmath<2,>=1.3
 Requires-Dist: python-flint<1,>=0.9
-Requires-Dist: sympy<2,>=1.13
-Provides-Extra: benchmark
-Requires-Dist: pytest-benchmark>=5.2; extra == 'benchmark'
-Requires-Dist: pytest>=8; extra == 'benchmark'
+Requires-Dist: algrecognize>=0.1.1
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: hypothesis>=6; extra == "test"
+Requires-Dist: pytest-cov>=6; extra == "test"
 Provides-Extra: dev
-Requires-Dist: ruff>=0.12; extra == 'dev'
-Provides-Extra: mutation
-Requires-Dist: mutmut>=3; extra == 'mutation'
+Requires-Dist: ruff>=0.12; extra == "dev"
 Provides-Extra: release
-Requires-Dist: build>=1.2; extra == 'release'
-Requires-Dist: twine>=6; extra == 'release'
-Provides-Extra: test
-Requires-Dist: hypothesis>=6; extra == 'test'
-Requires-Dist: pytest-cov>=6; extra == 'test'
-Requires-Dist: pytest>=8; extra == 'test'
-Description-Content-Type: text/markdown
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=6; extra == "release"
+Provides-Extra: benchmark
+Requires-Dist: pytest>=8; extra == "benchmark"
+Requires-Dist: pytest-benchmark>=5.2; extra == "benchmark"
+Provides-Extra: mutation
+Requires-Dist: mutmut>=3; extra == "mutation"
+Dynamic: license-file
 
 # algroots
 
-`algroots` solves **exact polynomial and supported algebraic equations with finite complex solution sets (zero-dimensional systems)**. It combines exact Gröbner and quotient-algebra structure with arbitrary-precision FLINT/Arb root extraction. It also provides exact rational univariate representations, border bases, isolated-root certificates and targeted deflation.
+`algroots` provides exact algebraic computation for polynomial systems, rational functions, finite quotient algebras, function fields, functional decomposition, and algebraic curves. It combines exact Gröbner and quotient-algebra structure with arbitrary-precision FLINT/Arb root extraction. It also provides exact rational univariate representations, border bases, isolated-root certificates and targeted deflation.
 
 Use `polysolve` for polynomials and `algsolve` for rational functions, principal rational powers and nested radicals. For now, coefficients must be exact: use `sp.Rational(1, 10)`, rather than `0.1`. `algroots` does not support positive-dimensional varieties, inequalities, noisy coefficients or transcendental equations.
 
 ## Public API
 
-Use `polysolve` or `algsolve` from the package root. Manual certification, quotient algebra, RURs, border bases and continuation tools use their public submodules. See the [namespace map](docs/api.md#root-and-specialized-namespaces) for the full API.
+Use `polysolve` or `algsolve` from the package root. Manual certification, quotient algebra, RURs, border bases and continuation tools use their public submodules. See the [namespace map](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/api.md#root-and-specialized-namespaces) for the full API.
 
 ## Install and run
 
@@ -74,7 +75,7 @@ print(result.completeness)
 
 In the result each tuple follows the supplied variable order. `.roots` stores distinct geometric points with aligned per-root metadata. Use `root_mode="with_multiplicity"` for repeated-root iteration and `.output_roots`; `.multiplicities` reports established local multiplicities. Results use canonical coordinate ordering, with `.ordering` distinguishing exact ordering from numerical fallback. `root_order="required"` requires exact ordering within the proof budgets. `digits` requests output precision; working precision may increase, and `verification_digits` controls the numerical residual standard. A small residual by itself is not an exact root or completeness proof.
 
-The automatic dispatch applies guarded exact presolve, deterministic ordering and a grevlex (graded reverse lexicographic) Gröbner basis. Action and RUR share quotient work; conversion to lexicographic with FGLM occurs only when needed. Cost hints preserve exact fallback checks. See [Choosing a Backend](docs/choosing-a-backend.md).
+The automatic dispatch applies guarded exact presolve, deterministic ordering and a grevlex (graded reverse lexicographic) Gröbner basis. Action and RUR share quotient work; conversion to lexicographic with FGLM occurs only when needed. Cost hints preserve exact fallback checks. See [Choosing a Backend](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/choosing-a-backend.md).
 
 ## Preserve branches and poles
 
@@ -106,9 +107,9 @@ certificate = result.root_certifications[0].certificate
 assert certificate.multiplicity == 2 and certificate.verify()
 ```
 
-`certify="auto"` records best-effort proof attempts; `certify="required"` raises when a proof cannot be established. Automatic boxes currently require rational coefficients and a globally finite ideal. Exact-point certification also supports algebraic coefficients. Dimension, refinement and box-attempt budgets are explicit.
+`certify="auto"` records best-effort proof attempts; `certify="required"` raises when a proof can't be established. Automatic boxes currently require rational coefficients and a globally finite ideal. Exact-point certification also supports algebraic coefficients.
 
-Recognition is a different operation. By default, solvers attempt exact coordinate recognition through `algrecognize`; successful jointly certified tuples appear in `recognized_roots`. Recognition failure leaves the numerical result available. `recognize=False` disables that post-processing. See [Certification Workflow](docs/certification-workflow.md) and [Reading Results](docs/reading-results.md).
+Recognition is a different operation. By default, solvers attempt exact coordinate recognition through `algrecognize`; successful jointly certified tuples appear in `recognized_roots`. Recognition failure leaves the numerical result available. `recognize=False` disables that post-processing. See [Certification Workflow](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/certification-workflow.md) and [Reading Results](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/reading-results.md).
 
 | Evidence | What it establishes |
 |---|---|
@@ -118,36 +119,50 @@ Recognition is a different operation. By default, solvers attempt exact coordina
 | Certified bounded recovery | Distinct exact endpoint proofs account for the exact finite-root count |
 | Numerical paths / monodromy stopping | Numerical or statistical evidence; no certified path or infinity accounting |
 
-Per-root certificates and recognition don't automatically upgrade the result-wide completeness status.
-
 ## Exact algebra and advanced solving
 
 | Task | API | Guide |
 |---|---|---|
-| Quotient basis, normal forms, matrices, traces | `QuotientAlgebra` | [Quotient tools](docs/quotient-tools.md) |
-| Exact RUR and exact algebraic points | `compute_rational_univariate_representation`, `solve_rur_representation` | [RUR](docs/rational-univariate-representation.md) |
-| Exact rational border bases | `compute_border_basis`, `compute_border_basis_linear` | [Border bases](docs/exact-border-bases.md) |
-| Singular-root proof and exact local deflation | `certify_isolated_root`, `deflate_isolated_root` | [Singular certification](docs/singular-certification-and-charts.md) |
-| Bounded endgame/deflation/chart recovery | `polysolve(method="homotopy", homotopy_recovery=True)` | [Recovery](docs/recovery-workflow.md) |
-| Numerical projective tracking | `projective_homotopy`, `track_projective_path` | [Chart switching](docs/singular-certification-and-charts.md) |
-| Seeded experimental monodromy | `discover_monodromy_orbit` | [Monodromy](docs/continuation-and-monodromy.md) |
+| Quotient basis, normal forms, matrices, traces | `QuotientAlgebra` | [Quotient tools](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/quotient-tools.md) |
+| Exact RUR and exact algebraic points | `compute_rational_univariate_representation`, `solve_rur_representation` | [RUR](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/rational-univariate-representation.md) |
+| Exact rational border bases | `compute_border_basis`, `compute_border_basis_linear` | [Border bases](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/exact-border-bases.md) |
+| Singular-root proof and exact local deflation | `certify_isolated_root`, `deflate_isolated_root` | [Singular certification](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/singular-certification-and-charts.md) |
+| Bounded endgame/deflation/chart recovery | `polysolve(method="homotopy", homotopy_recovery=True)` | [Recovery](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/recovery-workflow.md) |
+| Numerical projective tracking | `projective_homotopy`, `track_projective_path` | [Chart switching](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/singular-certification-and-charts.md) |
+| Seeded experimental monodromy | `discover_monodromy_orbit` | [Monodromy](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/continuation-and-monodromy.md) |
+
+
+## Functional decomposition, fields, and curves
+
+Algebraic methods also address structural questions for which enumerating roots is not the goal:
+
+| Question | Expert API | Guide |
+|---|---|---|
+| Can a rational function be written as a composition of simpler rational functions? | `algroots.functional_decomposition.rational_decompose`, `rational_decomposition_chain` | [Functional decomposition](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/functional-decomposition.md) |
+| Does an algebraic relation admit a compositional factorization, possibly over a coefficient extension? | `algroots.functional_decomposition.algebraic_decompose`, `discover_algebraic_factors` | [Functional decomposition](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/functional-decomposition.md) |
+| What subfield is generated by a collection of algebraic or rational elements? | `QuotientAlgebra.subfield`, `algroots.function_fields.coefficient_field`, `luroth_generator` | [Generated subfields](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/function-fields.md) |
+| What is the geometric genus of a plane curve, and does it have a rational parametrization? | `algroots.curves.PlaneCurve` | [Curve geometry](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/curves.md) |
+| How can a finite quotient algebra be decomposed into local factors or reduced? | `algroots.finite_decomposition.primary_decomposition`, `reduced_algebra`, `nilradical_basis` | [Finite algebras](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/finite-algebras.md) |
+| How can one construct a finite coefficient field and factor polynomials over it? | `algroots.finite_fields.finite_field`, `factor_univariate` | [Finite algebras](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/finite-algebras.md) |
+
+These specialized APIs use exact coefficients and explicit search limits. Successful decompositions carry identities that can be checked. Plane-curve operations are distinct from solving a positive-dimensional system by listing all its points.
 
 Ordinary `method="homotopy"` targets regular square systems whose required Bézout paths reach finite nonsingular endpoints. Recovery is opt-in, sequential, rational-coefficient and bounded. It adds a finite quotient for proof accounting, preserves successful endpoint proofs across retries, and reports unresolved paths. Neither of those modes certifies numerical paths or roots at infinity. Homotopy is not selected by `auto`.
 
 ## Numerical precision and stopping
 
-Numerical precision and integer budgets follow a common contract: nonzero coordinate components are preserved, root comparisons are relative to coordinate scale, and univariate Arb retries respect the working precision ceiling. Monodromy curvature stopping is a heuristic and gives no completeness evidence. See [precision and conditioning](docs/precision-and-conditioning.md) and [continuation and monodromy](docs/continuation-and-monodromy.md).
+Numerical precision and integer budgets follow a common contract: nonzero coordinate components are preserved, root comparisons are relative to coordinate scale, and univariate Arb retries respect the working precision ceiling. Monodromy curvature stopping is a heuristic and gives no completeness evidence. See [precision and conditioning](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/precision-and-conditioning.md) and [continuation and monodromy](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/continuation-and-monodromy.md).
 
 ## Examples and documentation
 
-The [examples catalog](examples/README.md) contains 16 scripts covering solving, branch filtering, recognition, quotient caches, RUR, algebraic fields, multiplicities, clusters, diagnostics, border bases, deflation, recovery, charts, monodromy and failures.
+The [examples catalog](https://github.com/BhuvaneshBhatt/algroots/blob/main/examples/README.md) contains 16 scripts covering solving, branch filtering, recognition, quotient caches, RUR, algebraic fields, multiplicities, clusters, diagnostics, border bases, deflation, recovery, charts, monodromy and failures.
 
 ```bash
 python examples/run_all.py
 python examples/run_all.py 07_multiplicity_and_boxes.py 15_limits_and_failures.py
 ```
 
-Start with [Quick Start](docs/quick-start.md), [Supported Problems](docs/supported-problems.md), [Support Matrix](docs/feature-support-matrix.md) and [Reading Results](docs/reading-results.md). The [documentation index](docs/index.md) links every topic, including the [API reference](docs/api.md), [limitations](docs/limitations.md) and [troubleshooting](docs/troubleshooting.md).
+Start with [Quick Start](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/quick-start.md), [Supported Problems](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/supported-problems.md), [Support Matrix](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/feature-support-matrix.md) and [Reading Results](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/reading-results.md). The [documentation index](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/index.md) links every topic, including the [API reference](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/api.md), [limitations](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/limitations.md) and [troubleshooting](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/troubleshooting.md).
 
 ## Development
 
@@ -157,8 +172,8 @@ python -m ruff check .
 python -m ruff format --check .
 ```
 
-Tests execute marked documentation and every catalog example, check navigation and API defaults, compare exact algebra against independent oracles, and exercise adversarial/resource limits. Benchmarks retain exact correctness checks but do not enforce wall-clock thresholds. See [Testing and Validation](docs/testing-and-validation.md) and [Contributing](CONTRIBUTING.md).
+Tests execute marked documentation and every catalog example, check navigation and API defaults, compare exact algebra against independent oracles, and exercise adversarial/resource limits. Benchmarks retain exact correctness checks but do not enforce wall-clock thresholds. See [Testing and Validation](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/testing-and-validation.md) and [Contributing](https://github.com/BhuvaneshBhatt/algroots/blob/main/CONTRIBUTING.md).
 
 ## License
 
-The package is distributed under the [GPL-3.0 license](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/LICENSE).
+The package is distributed under the [GPL-3.0 license](https://github.com/BhuvaneshBhatt/algroots/blob/main/LICENSE).

{algroots-0.2.0 → algroots-0.3.0}/README.md

@@ -1,12 +1,12 @@
 # algroots
 
-`algroots` solves **exact polynomial and supported algebraic equations with finite complex solution sets (zero-dimensional systems)**. It combines exact Gröbner and quotient-algebra structure with arbitrary-precision FLINT/Arb root extraction. It also provides exact rational univariate representations, border bases, isolated-root certificates and targeted deflation.
+`algroots` provides exact algebraic computation for polynomial systems, rational functions, finite quotient algebras, function fields, functional decomposition, and algebraic curves. It combines exact Gröbner and quotient-algebra structure with arbitrary-precision FLINT/Arb root extraction. It also provides exact rational univariate representations, border bases, isolated-root certificates and targeted deflation.
 
 Use `polysolve` for polynomials and `algsolve` for rational functions, principal rational powers and nested radicals. For now, coefficients must be exact: use `sp.Rational(1, 10)`, rather than `0.1`. `algroots` does not support positive-dimensional varieties, inequalities, noisy coefficients or transcendental equations.
 
 ## Public API
 
-Use `polysolve` or `algsolve` from the package root. Manual certification, quotient algebra, RURs, border bases and continuation tools use their public submodules. See the [namespace map](docs/api.md#root-and-specialized-namespaces) for the full API.
+Use `polysolve` or `algsolve` from the package root. Manual certification, quotient algebra, RURs, border bases and continuation tools use their public submodules. See the [namespace map](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/api.md#root-and-specialized-namespaces) for the full API.
 
 ## Install and run
 
@@ -32,7 +32,7 @@ print(result.completeness)
 
 In the result each tuple follows the supplied variable order. `.roots` stores distinct geometric points with aligned per-root metadata. Use `root_mode="with_multiplicity"` for repeated-root iteration and `.output_roots`; `.multiplicities` reports established local multiplicities. Results use canonical coordinate ordering, with `.ordering` distinguishing exact ordering from numerical fallback. `root_order="required"` requires exact ordering within the proof budgets. `digits` requests output precision; working precision may increase, and `verification_digits` controls the numerical residual standard. A small residual by itself is not an exact root or completeness proof.
 
-The automatic dispatch applies guarded exact presolve, deterministic ordering and a grevlex (graded reverse lexicographic) Gröbner basis. Action and RUR share quotient work; conversion to lexicographic with FGLM occurs only when needed. Cost hints preserve exact fallback checks. See [Choosing a Backend](docs/choosing-a-backend.md).
+The automatic dispatch applies guarded exact presolve, deterministic ordering and a grevlex (graded reverse lexicographic) Gröbner basis. Action and RUR share quotient work; conversion to lexicographic with FGLM occurs only when needed. Cost hints preserve exact fallback checks. See [Choosing a Backend](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/choosing-a-backend.md).
 
 ## Preserve branches and poles
 
@@ -64,9 +64,9 @@ certificate = result.root_certifications[0].certificate
 assert certificate.multiplicity == 2 and certificate.verify()
 ```
 
-`certify="auto"` records best-effort proof attempts; `certify="required"` raises when a proof cannot be established. Automatic boxes currently require rational coefficients and a globally finite ideal. Exact-point certification also supports algebraic coefficients. Dimension, refinement and box-attempt budgets are explicit.
+`certify="auto"` records best-effort proof attempts; `certify="required"` raises when a proof can't be established. Automatic boxes currently require rational coefficients and a globally finite ideal. Exact-point certification also supports algebraic coefficients.
 
-Recognition is a different operation. By default, solvers attempt exact coordinate recognition through `algrecognize`; successful jointly certified tuples appear in `recognized_roots`. Recognition failure leaves the numerical result available. `recognize=False` disables that post-processing. See [Certification Workflow](docs/certification-workflow.md) and [Reading Results](docs/reading-results.md).
+Recognition is a different operation. By default, solvers attempt exact coordinate recognition through `algrecognize`; successful jointly certified tuples appear in `recognized_roots`. Recognition failure leaves the numerical result available. `recognize=False` disables that post-processing. See [Certification Workflow](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/certification-workflow.md) and [Reading Results](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/reading-results.md).
 
 | Evidence | What it establishes |
 |---|---|
@@ -76,36 +76,50 @@ Recognition is a different operation. By default, solvers attempt exact coordina
 | Certified bounded recovery | Distinct exact endpoint proofs account for the exact finite-root count |
 | Numerical paths / monodromy stopping | Numerical or statistical evidence; no certified path or infinity accounting |
 
-Per-root certificates and recognition don't automatically upgrade the result-wide completeness status.
-
 ## Exact algebra and advanced solving
 
 | Task | API | Guide |
 |---|---|---|
-| Quotient basis, normal forms, matrices, traces | `QuotientAlgebra` | [Quotient tools](docs/quotient-tools.md) |
-| Exact RUR and exact algebraic points | `compute_rational_univariate_representation`, `solve_rur_representation` | [RUR](docs/rational-univariate-representation.md) |
-| Exact rational border bases | `compute_border_basis`, `compute_border_basis_linear` | [Border bases](docs/exact-border-bases.md) |
-| Singular-root proof and exact local deflation | `certify_isolated_root`, `deflate_isolated_root` | [Singular certification](docs/singular-certification-and-charts.md) |
-| Bounded endgame/deflation/chart recovery | `polysolve(method="homotopy", homotopy_recovery=True)` | [Recovery](docs/recovery-workflow.md) |
-| Numerical projective tracking | `projective_homotopy`, `track_projective_path` | [Chart switching](docs/singular-certification-and-charts.md) |
-| Seeded experimental monodromy | `discover_monodromy_orbit` | [Monodromy](docs/continuation-and-monodromy.md) |
+| Quotient basis, normal forms, matrices, traces | `QuotientAlgebra` | [Quotient tools](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/quotient-tools.md) |
+| Exact RUR and exact algebraic points | `compute_rational_univariate_representation`, `solve_rur_representation` | [RUR](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/rational-univariate-representation.md) |
+| Exact rational border bases | `compute_border_basis`, `compute_border_basis_linear` | [Border bases](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/exact-border-bases.md) |
+| Singular-root proof and exact local deflation | `certify_isolated_root`, `deflate_isolated_root` | [Singular certification](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/singular-certification-and-charts.md) |
+| Bounded endgame/deflation/chart recovery | `polysolve(method="homotopy", homotopy_recovery=True)` | [Recovery](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/recovery-workflow.md) |
+| Numerical projective tracking | `projective_homotopy`, `track_projective_path` | [Chart switching](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/singular-certification-and-charts.md) |
+| Seeded experimental monodromy | `discover_monodromy_orbit` | [Monodromy](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/continuation-and-monodromy.md) |
+
+
+## Functional decomposition, fields, and curves
+
+Algebraic methods also address structural questions for which enumerating roots is not the goal:
+
+| Question | Expert API | Guide |
+|---|---|---|
+| Can a rational function be written as a composition of simpler rational functions? | `algroots.functional_decomposition.rational_decompose`, `rational_decomposition_chain` | [Functional decomposition](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/functional-decomposition.md) |
+| Does an algebraic relation admit a compositional factorization, possibly over a coefficient extension? | `algroots.functional_decomposition.algebraic_decompose`, `discover_algebraic_factors` | [Functional decomposition](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/functional-decomposition.md) |
+| What subfield is generated by a collection of algebraic or rational elements? | `QuotientAlgebra.subfield`, `algroots.function_fields.coefficient_field`, `luroth_generator` | [Generated subfields](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/function-fields.md) |
+| What is the geometric genus of a plane curve, and does it have a rational parametrization? | `algroots.curves.PlaneCurve` | [Curve geometry](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/curves.md) |
+| How can a finite quotient algebra be decomposed into local factors or reduced? | `algroots.finite_decomposition.primary_decomposition`, `reduced_algebra`, `nilradical_basis` | [Finite algebras](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/finite-algebras.md) |
+| How can one construct a finite coefficient field and factor polynomials over it? | `algroots.finite_fields.finite_field`, `factor_univariate` | [Finite algebras](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/finite-algebras.md) |
+
+These specialized APIs use exact coefficients and explicit search limits. Successful decompositions carry identities that can be checked. Plane-curve operations are distinct from solving a positive-dimensional system by listing all its points.
 
 Ordinary `method="homotopy"` targets regular square systems whose required Bézout paths reach finite nonsingular endpoints. Recovery is opt-in, sequential, rational-coefficient and bounded. It adds a finite quotient for proof accounting, preserves successful endpoint proofs across retries, and reports unresolved paths. Neither of those modes certifies numerical paths or roots at infinity. Homotopy is not selected by `auto`.
 
 ## Numerical precision and stopping
 
-Numerical precision and integer budgets follow a common contract: nonzero coordinate components are preserved, root comparisons are relative to coordinate scale, and univariate Arb retries respect the working precision ceiling. Monodromy curvature stopping is a heuristic and gives no completeness evidence. See [precision and conditioning](docs/precision-and-conditioning.md) and [continuation and monodromy](docs/continuation-and-monodromy.md).
+Numerical precision and integer budgets follow a common contract: nonzero coordinate components are preserved, root comparisons are relative to coordinate scale, and univariate Arb retries respect the working precision ceiling. Monodromy curvature stopping is a heuristic and gives no completeness evidence. See [precision and conditioning](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/precision-and-conditioning.md) and [continuation and monodromy](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/continuation-and-monodromy.md).
 
 ## Examples and documentation
 
-The [examples catalog](examples/README.md) contains 16 scripts covering solving, branch filtering, recognition, quotient caches, RUR, algebraic fields, multiplicities, clusters, diagnostics, border bases, deflation, recovery, charts, monodromy and failures.
+The [examples catalog](https://github.com/BhuvaneshBhatt/algroots/blob/main/examples/README.md) contains 16 scripts covering solving, branch filtering, recognition, quotient caches, RUR, algebraic fields, multiplicities, clusters, diagnostics, border bases, deflation, recovery, charts, monodromy and failures.
 
 ```bash
 python examples/run_all.py
 python examples/run_all.py 07_multiplicity_and_boxes.py 15_limits_and_failures.py
 ```
 
-Start with [Quick Start](docs/quick-start.md), [Supported Problems](docs/supported-problems.md), [Support Matrix](docs/feature-support-matrix.md) and [Reading Results](docs/reading-results.md). The [documentation index](docs/index.md) links every topic, including the [API reference](docs/api.md), [limitations](docs/limitations.md) and [troubleshooting](docs/troubleshooting.md).
+Start with [Quick Start](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/quick-start.md), [Supported Problems](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/supported-problems.md), [Support Matrix](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/feature-support-matrix.md) and [Reading Results](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/reading-results.md). The [documentation index](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/index.md) links every topic, including the [API reference](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/api.md), [limitations](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/limitations.md) and [troubleshooting](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/troubleshooting.md).
 
 ## Development
 
@@ -115,8 +129,8 @@ python -m ruff check .
 python -m ruff format --check .
 ```
 
-Tests execute marked documentation and every catalog example, check navigation and API defaults, compare exact algebra against independent oracles, and exercise adversarial/resource limits. Benchmarks retain exact correctness checks but do not enforce wall-clock thresholds. See [Testing and Validation](docs/testing-and-validation.md) and [Contributing](CONTRIBUTING.md).
+Tests execute marked documentation and every catalog example, check navigation and API defaults, compare exact algebra against independent oracles, and exercise adversarial/resource limits. Benchmarks retain exact correctness checks but do not enforce wall-clock thresholds. See [Testing and Validation](https://github.com/BhuvaneshBhatt/algroots/blob/main/docs/testing-and-validation.md) and [Contributing](https://github.com/BhuvaneshBhatt/algroots/blob/main/CONTRIBUTING.md).
 
 ## License
 
-The package is distributed under the [GPL-3.0 license](https://github.com/BhuvaneshBhatt/asymptotic/blob/main/LICENSE).
+The package is distributed under the [GPL-3.0 license](https://github.com/BhuvaneshBhatt/algroots/blob/main/LICENSE).