From 232f937ba1440f7f1fa2653b37b5c16a87b5228f Mon Sep 17 00:00:00 2001 From: "scriptalert(\"suleyman\");/script" Date: Sun, 4 Aug 2024 03:07:12 +0300 Subject: [PATCH] update readme --- poly/README.md | 145 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 110 insertions(+), 35 deletions(-) diff --git a/poly/README.md b/poly/README.md index 2fe043dcb..c9f9334c7 100644 --- a/poly/README.md +++ b/poly/README.md @@ -1,10 +1,9 @@ # Polynomials -This chapter describes functions for evaluating and solving polynomials. -There are routines for finding real and complex roots of quadratic and -cubic equations using analytic methods. An iterative polynomial solver -is also available for finding the roots of general polynomials with real -coefficients (of any order). The functions are declared in the module `vsl.poly`. +This chapter describes functions for evaluating and solving polynomials. There are routines +for finding real and complex roots of quadratic and cubic equations using analytic methods. +An iterative polynomial solver is also available for finding the roots of general polynomials +with real coefficients (of any order). The functions are declared in the module `vsl.poly`. ## Polynomial Evaluation @@ -20,16 +19,17 @@ using Horner's method for stability. fn eval(c []f64, x f64) f64 ``` -This function evaluates a polynomial with real coefficients for the real variable `x`. +This function evaluates a polynomial and its derivatives, storing the results in the array +`res` of size `lenres`. The output array contains the values of `d^k P(x)/d x^k` for the +specified value of `x`, starting with `k = 0`. ```v ignore fn eval_derivs(c []f64, x f64, lenres u64) []f64 ``` -This function evaluates a polynomial and its derivatives storing the -results in the array `res` of size `lenres`. The output array -contains the values of `d^k P(x)/d x^k` for the specified value of -`x` starting with `k = 0`. +This function evaluates a polynomial and its derivatives, storing the results in the array +`res` of size `lenres`. The output array contains the values of `d^k P(x)/d x^k` for the +specified value of `x`, starting with `k = 0`. ## Quadratic Equations @@ -43,22 +43,17 @@ This function finds the real roots of the quadratic equation, a x^2 + b x + c = 0 ``` -The number of real roots (either zero, one or two) is returned, and -their locations are are returned as `[ x0, x1 ]`. If no real roots -are found then `[]` is returned. If one real root -is found (i.e. if `a=0`) then it is are returned as `[ x0 ]`. When two -real roots are found they are are returned as `[ x0, x1 ]` in -ascending order. The case of coincident roots is not considered -special. For example `(x-1)^2=0` will have two roots, which happen -to have exactly equal values. +The number of real roots (either zero, one or two) is returned, and their locations are +returned as `[ x0, x1 ]`. If no real roots are found then `[]` is returned. If one real root +is found (i.e. if `a=0`) then it is returned as `[ x0 ]`. When two real roots are found they +are returned as `[ x0, x1 ]` in ascending order. The case of coincident roots is not considered +special. For example `(x-1)^2=0` will have two roots, which happen to have exactly equal values. -The number of roots found depends on the sign of the discriminant -`b^2 - 4 a c`. This will be subject to rounding and cancellation -errors when computed in double precision, and will also be subject to -errors if the coefficients of the polynomial are inexact. These errors -may cause a discrete change in the number of roots. However, for -polynomials with small integer coefficients the discriminant can always -be computed exactly. +The number of roots found depends on the sign of the discriminant `b^2 - 4 a c`. This will +be subject to rounding and cancellation errors when computed in double precision, and will +also be subject to errors if the coefficients of the polynomial are inexact. These errors may +cause a discrete change in the number of roots. However, for polynomials with small integer +coefficients the discriminant can always be computed exactly. ## Cubic Equations @@ -72,13 +67,93 @@ This function finds the real roots of the cubic equation, x^3 + a x^2 + b x + c = 0 ``` -with a leading coefficient of unity. The number of real roots (either -one or three) is returned, and their locations are returned as `[ x0, x1, x2 ]`. -If one real root is found then only `[ x0 ]` -is returned. When three real roots are found they are returned as -`[ x0, x1, x2 ]` in ascending order. The case of -coincident roots is not considered special. For example, the equation -`(x-1)^3=0` will have three roots with exactly equal values. As -in the quadratic case, finite precision may cause equal or -closely-spaced real roots to move off the real axis into the complex -plane, leading to a discrete change in the number of real roots. +with a leading coefficient of unity. The number of real roots (either one or three) is +returned, and their locations are returned as `[ x0, x1, x2 ]`. If one real root is found +then only `[ x0 ]` is returned. When three real roots are found they are returned as +`[ x0, x1, x2 ]` in ascending order. The case of coincident roots is not considered special. +For example, the equation `(x-1)^3=0` will have three roots with exactly equal values. As +in the quadratic case, finite precision may cause equal or closely-spaced real roots to move +off the real axis into the complex plane, leading to a discrete change in the number of real roots. + +## Companion Matrix + +```v ignore +fn companion_matrix(a []f64) [][]f64 +``` + +Creates a companion matrix for the polynomial + +```console +P(x) = a_n * x^n + a_{n-1} * x^{n-1} + ... + a_1 * x + a_0 +``` + +The companion matrix `C` is defined as: + +``` +[0 0 0 ... 0 -a_0/a_n] +[1 0 0 ... 0 -a_1/a_n] +[0 1 0 ... 0 -a_2/a_n] +[. . . ... . ........] +[0 0 0 ... 1 -a_{n-1}/a_n] +``` + +## Balanced Companion Matrix + +```v ignore +fn balance_companion_matrix(cm [][]f64) [][]f64 +``` + +Balances a companion matrix `C` to improve numerical stability. It uses an iterative scaling +process to make the row and column norms as close to each other as possible. The output is +a balanced matrix `B` such that `D^(-1)CD = B`, where `D` is a diagonal matrix. + +## Polynomial Operations + +```v ignore +fn add(a []f64, b []f64) []f64 +``` + +Adds two polynomials: + +```console +(a_n * x^n + ... + a_0) + (b_m * x^m + ... + b_0) +``` + +Returns the result as `[a_0 + b_0, a_1 + b_1, ..., max(a_k, b_k), ...]`. + +```v ignore +fn subtract(a []f64, b []f64) []f64 +``` + +Subtracts two polynomials: + +```console +(a_n * x^n + ... + a_0) - (b_m * x^m + ... + b_0) +``` + +Returns the result as `[a_0 - b_0, a_1 - b_1, ..., a_k - b_k, ...]`. + +```v ignore +fn multiply(a []f64, b []f64) []f64 +``` + +Multiplies two polynomials: + +```console +(a_n * x^n + ... + a_0) * (b_m * x^m + ... + b_0) +``` + +Returns the result as `[c_0, c_1, ..., c_{n+m}]` where `c_k = ∑_{i+j=k} a_i * b_j`. + +```v ignore +fn divide(a []f64, b []f64) ([]f64, []f64) +``` + +Divides two polynomials: + +```console +(a_n * x^n + ... + a_0) / (b_m * x^m + ... + b_0) +``` + +Uses polynomial long division algorithm. Returns `(q, r)` where `q` is the quotient and `r` +is the remainder such that `a(x) = b(x) * q(x) + r(x)` and `degree(r) < degree(b)`.