ginger package

Submodules

ginger.aberth module

Aberth’s Method for Polynomial Root Finding

This code implements Aberth’s method, which is an algorithm for finding the roots of polynomials. In simple terms, it’s a way to solve equations like x^3 + 2x^2 - 5x + 3 = 0, finding the values of x that make the equation true.

The main input for this code is a list of coefficients that represent a polynomial. For example, [1, 2, -5, 3] would represent the polynomial x^3 + 2x^2 - 5x + 3. The code also takes initial guesses for where the roots might be.

The output is a list of complex numbers that represent the roots of the polynomial. These are the solutions to the equation. The code also returns the number of iterations it took to find the roots and whether it was successful in finding them within the specified tolerance.

To achieve its purpose, the code uses an iterative process. It starts with initial guesses for the roots and then repeatedly improves these guesses until they’re close enough to the actual roots. The main algorithm, Aberth’s method, is implemented in the aberth function. This function uses a clever mathematical formula to update each guess based on the current polynomial value and its derivative at that point, as well as the positions of all the other guesses.

The code includes several variations of the algorithm. There’s a basic version (aberth), a multithreaded version for faster computation (aberth_mt), and versions that use autocorrelation (aberth_autocorr and aberth_autocorr_mt). These autocorrelation versions are designed to work better for certain types of polynomials.

An important part of the process is finding good initial guesses for the roots. The code includes several functions for this, like initial_aberth and initial_aberth_autocorr. These functions use mathematical insights about where roots are likely to be located to make educated guesses.

The code also includes helper functions like horner_eval and horner_backward which are efficient ways to evaluate polynomials and their derivatives.

Overall, this code provides a comprehensive toolkit for finding the roots of polynomials using Aberth’s method, with various optimizations and variations to handle different scenarios efficiently.

ginger.aberth.aberth(coeffs: ~typing.List[float], zs: ~typing.List[complex], options: ~ginger.rootfinding.Options = <ginger.rootfinding.Options object>) → Tuple[List[complex], int, bool]

Core implementation of Aberth’s root-finding algorithm. Iteratively improves root estimates using polynomial evaluations and derivative approximations. Convergence is achieved when all residuals fall below specified tolerance.

The aberth function implements Aberth’s method for polynomial root-finding. It works by: 1. Evaluating the polynomial and its derivative at each current root estimate 2. Adjusting each estimate based on the ratio of polynomial value to derivative 3. Including correction terms from all other root estimates 4. Repeating until convergence or maximum iterations reached

Parameters:

• coeffs (List[float]) – The coeffs parameter is a list of coefficients of a polynomial. The coefficients are ordered from highest degree to lowest degree. For example, if the polynomial is 3x^2 + 2x + 1, then the coeffs list would be [3, 2, 1]

• zs (List[complex]) – The zs parameter in the aberth function represents the initial guesses for the roots of the polynomial. It is a list of complex numbers. Each complex number represents an initial guess for a root of the polynomial

• options (Options) – The options parameter is an instance of the Options class, which contains various options for the Aberth’s method algorithm. It is an optional parameter, and if not provided, it will default to an instance of the Options class with default values

Returns:

The function aberth returns a tuple containing three elements: 1. zs: a list of complex numbers representing the approximate roots of the polynomial. 2. niter: an integer representing the number of iterations performed by Aberth’s method. 3. found: a boolean value indicating whether the roots were found within the specified tolerance.

Examples

>>> h = [5.0, 2.0, 9.0, 6.0, 2.0]
>>> z0s = initial_aberth(h)
>>> opt = Options()
>>> opt.tolerance = 1e-8
>>> zs, niter, found = aberth(h, z0s, opt)
>>> found
True

>>> h = [1.0, -1.0, -1.0, 1.0]
>>> z0s = initial_aberth(h)
>>> zs, niter, found = aberth(h, z0s)
>>> found
True

ginger.aberth.aberth_autocorr(coeffs: ~typing.List[float], zs: ~typing.List[complex], options=<ginger.rootfinding.Options object>) → Tuple[List[complex], int, bool]

Aberth’s method variant for autocorrelation polynomials. Accounts for reciprocal root pairs (z and 1/z̄) in derivative calculation. Particularly useful for polynomials with symmetric coefficient structures.

The aberth_autocorr function implements the Aberth method for finding the roots of a polynomial using autocorrelation. This version is specialized for polynomials where roots come in reciprocal conjugate pairs (common in signal processing applications). It modifies the standard Aberth method to account for these symmetric root structures.

Parameters:

• coeffs (List[float]) – The coeffs parameter is a list of coefficients of a polynomial. The coefficients are ordered from highest degree to lowest degree. For example, if the polynomial is 3x^2 + 2x + 1, then the coeffs list would be [3, 2, 1]

• zs (List[complex]) – The zs parameter is a list of complex numbers. It represents the initial guesses for the roots of a polynomial

• options – The options parameter is an instance of the Options class, which contains various options for the algorithm. It is an optional parameter and if not provided, it will default to an instance of the Options class with default values

Returns:

The function aberth_autocorr returns a tuple containing the following elements: - List of refined roots - Number of iterations performed - Boolean indicating whether convergence was achieved

Examples

>>> h = [5.0, 2.0, 9.0, 6.0, 2.0]
>>> z0s = initial_aberth_autocorr(h)
>>> zs, niter, found = aberth_autocorr(h, z0s)
>>> opt = Options()
>>> opt.tolerance = 1e-8
>>> zs, niter, found = aberth_autocorr(h, z0s, opt)

ginger.aberth.aberth_autocorr_job(coeffs: List[float], i: int, zsc: List[complex]) → Tuple[float, int, complex]

Worker function for multithreaded autocorrelation Aberth method. Handles individual root updates while considering reciprocal root pairs. Returns updated root estimate along with its residual for convergence checking.

This function performs the core calculations for a single root in the multithreaded autocorrelation version of Aberth’s method. It evaluates the polynomial and its derivative at the current root estimate, applies corrections for all other roots and their reciprocals, and returns the updated root estimate.

Parameters:

• coeffs – Polynomial coefficients in descending order of degree

• i – Index of the root being processed

• zsc – Current list of root estimates (complex numbers)

Returns:

Tuple containing: - Residual (absolute value of polynomial at current estimate) - Index of the root being processed - New root estimate

ginger.aberth.aberth_autocorr_mt(coeffs: ~typing.List[float], zs: ~typing.List[complex], options: ~ginger.rootfinding.Options = <ginger.rootfinding.Options object>) → Tuple[List[complex], int, bool]

Multithreaded version of autocorrelation Aberth’s method. Parallelizes root updates across multiple threads for improved performance. Maintains thread safety by keeping root updates in separate jobs.

This function implements the autocorrelation version of Aberth’s method using multiple threads. Each root update is performed in parallel, which can significantly speed up computation for high-degree polynomials. The function maintains the same mathematical operations as the single-threaded version but distributes the workload across available processors.

Parameters:

• coeffs – List of polynomial coefficients in descending order of degree

• zs – Initial guesses for the roots (complex numbers)

• options – Configuration options including max iterations and tolerance

Returns:

Tuple containing: - List of refined roots - Number of iterations performed - Boolean indicating whether convergence was achieved

ginger.aberth.aberth_mt(coeffs: ~typing.List[float], zs: ~typing.List[complex], options: ~ginger.rootfinding.Options = <ginger.rootfinding.Options object>) → Tuple[List[complex], int, bool]

Multithreaded implementation of Aberth’s method. Uses ThreadPoolExecutor to parallelize root updates across available CPUs. Maintains convergence checking in main thread while parallelizing computations.

This function implements Aberth’s method for finding polynomial roots using multiple threads. Each root update is performed in parallel, which can significantly speed up computation for high-degree polynomials. The function maintains the same mathematical operations as the single-threaded version but distributes the workload across available processors.

Parameters:

• coeffs – List of polynomial coefficients in descending order of degree

• zs – Initial guesses for the roots (complex numbers)

• options – Configuration options including max iterations and tolerance

Returns:

Tuple containing: - List of refined roots - Number of iterations performed - Boolean indicating whether convergence was achieved

ginger.aberth.horner_backward(coeffs1: List, degree: int, alpha: complex) → complex

Backward polynomial evaluation using Horner’s method for root refinement. Evaluates polynomial at x=α using coefficients in reverse order. This implementation modifies coefficients in-place for efficiency.

The horner_backward function evaluates a polynomial using the Horner’s method in backward form. This is particularly useful for root refinement in iterative methods like Aberth’s. It works by transforming the polynomial coefficients to center them around α, which helps in accurately evaluating the polynomial and its derivatives at α.

Parameters:

• coeffs1 (List) – The parameter coeffs1 is a list of coefficients of a polynomial in descending order of degree. For example, if the polynomial is 3x^3 - 2x^2 + 5x - 1, then coeffs1 would be [3, -2, 5, -1]

• degree (int) – The degree of the polynomial, which is the highest power of the variable in the polynomial. For example, if the polynomial is 3x^2 + 2x + 1, then the degree is 2

• alpha (complex) – The value of alpha is a constant that is used in the Horner’s method for backward polynomial evaluation. It is typically a scalar value

Returns:

The function horner_backward returns the value of the polynomial evaluated at the given alpha value.

Examples

>>> coeffs = [1.0, -6.7980, 2.9948, -0.043686, 0.000089248]
>>> degree = len(coeffs) - 1
>>> alpha = 6.3256
>>> p_eval = horner_backward(coeffs, degree, alpha)
>>> -p_eval * pow(alpha, 5)
-0.013355264987140483
>>> coeffs[3]
0.006920331351966613

ginger.aberth.initial_aberth(coeffs: List[float]) → List[complex]

Generates initial root guesses using geometric distribution around a center point. Calculates center from polynomial coefficients and radius from evaluation at center. Uses low-discrepancy sequence (Circle generator) for even angular distribution.

The initial_aberth function calculates the initial guesses for the roots of a polynomial using the Aberth method. It computes a center point based on the polynomial coefficients and then distributes initial guesses evenly around a circle centered at this point. The radius is determined by evaluating the polynomial at the center point and taking the nth root.

Parameters:

coeffs (List[float]) – The coeffs parameter is a list of coefficients of a polynomial. Each element in the list represents the coefficient of a term in the polynomial, starting from the highest degree term down to the constant term. For example, if the polynomial is 3x^3 - 2x^2 + 5x - 1, then coeffs would be [3, -2, 5, -1]

Returns:

The function initial_aberth returns a list of complex numbers.

Examples

>>> h = [5.0, 2.0, 9.0, 6.0, 2.0]
>>> z0s = initial_aberth(h)

ginger.aberth.initial_aberth_autocorr(coeffs: List[float]) → List[complex]

Generates initial guesses for autocorrelation polynomials. Special case handling for polynomials with reciprocal root pairs. Adjusts radius to ensure roots stay within unit circle when possible.

The function initial_aberth_autocorr calculates the initial values for the Aberth method for finding the roots of a polynomial. This version is specialized for autocorrelation polynomials, which have symmetric root structures (roots come in reciprocal conjugate pairs). It ensures the initial guesses are within the unit circle when possible.

Parameters:

coeffs (List[float]) – The coeffs parameter is a list of coefficients of a polynomial. The coefficients are ordered from highest degree to lowest degree. For example, if the polynomial is 3x^2 + 2x + 1, then the coeffs list would be [3, 2, 1]

Returns:

The function initial_aberth_autocorr returns a list of complex numbers.

Examples

>>> h = [5.0, 2.0, 9.0, 6.0, 2.0]
>>> z0s = initial_aberth_autocorr(h)

ginger.aberth.initial_aberth_autocorr_orig(coeffs: List[float]) → List[complex]

Original trigonometric implementation for autocorrelation polynomials. Generates initial guesses on a circle with angular spacing considering reciprocal roots. Particularly suited for polynomials with symmetric root structures.

The function initial_aberth_autocorr_orig calculates the initial guesses for the roots of a polynomial using the Aberth method. This version uses trigonometric functions to distribute the initial guesses and is specialized for autocorrelation polynomials, which have symmetric root structures (roots come in reciprocal conjugate pairs).

Parameters:

coeffs (List[float]) – The coeffs parameter is a list of coefficients of a polynomial. The coefficients are ordered from highest degree to lowest degree. For example, if the polynomial is 3x^2 + 2x + 1, then the coeffs list would be [3, 2, 1]

Returns:

The function initial_aberth_autocorr_orig returns a list of complex numbers.

Examples

>>> h = [5.0, 2.0, 9.0, 6.0, 2.0]
>>> z0s = initial_aberth_autocorr_orig(h)

ginger.aberth.initial_aberth_orig(coeffs: List[float]) → List[complex]

Original implementation of initial guess generation using trigonometric distribution. Places roots equally spaced around a circle with calculated radius and center. Includes angular offset of 0.25 to avoid alignment with coordinate axes.

The function initial_aberth_orig calculates the initial approximations for the roots of a polynomial using the Aberth method. This version uses trigonometric functions to distribute the initial guesses evenly around a circle, with a small angular offset to prevent roots from aligning with the coordinate axes.

Parameters:

coeffs (List[float]) – The coeffs parameter is a list of coefficients of a polynomial. Each element in the list represents the coefficient of a term in the polynomial, starting from the highest degree term down to the constant term. For example, if the polynomial is 3x^3 - 2x^2 + 5x - 1, then coeffs would be [3, -2, 5, -1]

Returns:

The function initial_aberth_orig returns a list of complex numbers.

Examples

>>> h = [5.0, 2.0, 9.0, 6.0, 2.0]
>>> z0s = initial_aberth_orig(h)

ginger.autocorr module

ginger.autocorr.extract_autocorr(vr: Vector2) → Vector2

Normalizes quadratic factors to ensure roots within unit circle.

Strategy: 1. Calculate roots of quadratic x² - rx - q 2. If roots are outside unit circle, take reciprocals 3. Return new quadratic with roots inside unit circle

Parameters:

vr – Vector2 representing quadratic coefficients (r, q)

Returns:

Normalized Vector2 with roots inside unit circle

ginger.autocorr.initial_autocorr(coeffs: List[float]) → List[Vector2]

Calculates initial guesses for autocorrelation roots using coefficient analysis.

The method: 1. Computes a root radius estimate from the constant term 2. Adjusts radius to focus on roots outside unit circle 3. Generates initial guesses using cosine spaced angles with quadratic terms

Parameters:

coeffs – Polynomial coefficients from highest to lowest degree

Returns:

List of Vector2 representing quadratic factors (x² - rx - q)

ginger.autocorr.pbairstow_autocorr(coeffs: ~typing.List[float], vrs: ~typing.List[~ginger.vector2.Vector2], options: ~ginger.rootfinding.Options = <ginger.rootfinding.Options object>)

Implements Bairstow’s method for polynomial root finding with autocorrelation.

Process outline: 1. Iterates until convergence or max iterations 2. Evaluates polynomial and first derivative using Horner’s scheme 3. Suppresses interference from other roots 4. Updates estimates using Newton-Raphson step

Parameters:

• coeffs – Polynomial coefficients (degree must be even)

• vrs – Initial guesses for quadratic factors

• options – Algorithm control parameters

Returns:

Tuple of (updated factors, iterations, convergence status)

ginger.matrix2 module

class ginger.matrix2.Matrix2(x: Vector2, y: Vector2)

Bases: object

det() → float

Calculate the determinant of the 2x2 matrix.

Formula:

det = (x.x * y.y) - (x.y * y.x)

Returns:

Determinant value

Return type:

float

Examples

>>> m = Matrix2(Vector2(1.0, 2.0), Vector2(3.0, 4.0))
>>> print(m.det())
-2.0

mdot(rhs: Vector2) → Vector2

Matrix-vector multiplication: M * v.

Parameters:

rhs (Vector2) – Right-hand side vector for multiplication

Returns:

Result vector of the matrix-vector product

Return type:

Vector2

Calculation:

[x•rhs] # Dot product of first row with vector [y•rhs] # Dot product of second row with vector

Examples

>>> m = Matrix2(Vector2(1.0, 2.0), Vector2(3.0, 4.0))
>>> print(m.mdot(Vector2(5.0, 6.0)))
<17.0, 39.0>

property x

Get the first row vector of the matrix.

Returns:

The first row vector

Return type:

Vector2

Examples

>>> m = Matrix2(Vector2(1.0, 2.0), Vector2(3.0, 4.0))
>>> print(m.x)
<1.0, 2.0>

property y

Get the second row vector of the matrix.

Returns:

The second row vector

Return type:

Vector2

Examples

>>> m = Matrix2(Vector2(1.0, 2.0), Vector2(3.0, 4.0))
>>> print(m.y)
<3.0, 4.0>

ginger.rootfinding module

rootfinding.py

This code is a collection of functions and classes designed to find the roots of polynomial equations. In mathematics, finding the roots of a polynomial means determining the values of x that make the polynomial equal to zero. This is a common problem in various fields like engineering, physics, and computer science.

The main purpose of this code is to implement the Bairstow’s method, which is an algorithm for finding complex roots of polynomials. It takes as input the coefficients of a polynomial and initial guesses for the roots, and outputs the calculated roots of the polynomial.

The code starts by importing necessary modules and defining some utility classes and functions. The main algorithm is implemented in the pbairstow_even function. This function takes three inputs:

1. A list of coefficients representing the polynomial

2. A list of initial guesses for the roots

3. An optional Options object to control the algorithm’s behavior

The output of pbairstow_even is a tuple containing:

1. A list of the calculated roots

2. The number of iterations performed

3. A boolean indicating whether the algorithm successfully converged

The algorithm works by iteratively refining the initial guesses for the roots. It uses a technique called “suppression” to improve the accuracy of each root estimate. The process continues until either the desired accuracy is achieved or the maximum number of iterations is reached.

Some important parts of the code include:

• The initial_guess function, which generates starting points for the algorithm

• The suppress function, which helps improve the accuracy of root estimates

• The horner function, which efficiently evaluates polynomials

• The delta function, which calculates adjustments to the root estimates

The code also includes helper functions for polynomial evaluation and manipulation, such as horner_eval and horner_backward.

Overall, this code provides a sophisticated tool for solving polynomial equations, even when the roots are complex numbers. It’s designed to be efficient and accurate, making it useful for applications that require finding roots of high-degree polynomials.

class ginger.rootfinding.Options

Bases: object

Configuration options for root-finding algorithms.

This class provides control parameters for iterative root-finding methods: - max_iters: Maximum number of iterations allowed (default: 2000) - tolerance: Convergence tolerance for the algorithm (default: 1e-12) - tol_ind: Individual root tolerance threshold (default: 1e-15)

These parameters allow fine-tuning of the algorithm’s behavior and stopping criteria.

max_iters: int = 2000

tol_ind: float = 1e-15

tolerance: float = 1e-12

ginger.rootfinding.delta(vA: Vector2, vr: Vector2, vp: Vector2) → Vector2

Calculate adjustment vector for Bairstow’s method.

The delta function computes the correction vector used in Bairstow’s method to update root estimates. It solves a 2x2 linear system derived from polynomial division to find the optimal adjustment to current root estimates.

Parameters:

• vA (Vector2) – Residual vector (A,B) from polynomial division

• vr (Vector2) – Current root estimate vector (r,q)

• vp (Vector2) – Vector used in suppression calculations (p,s)

Returns:

Correction vector to adjust root estimates

Return type:

Vector2

Examples

>>> d = delta(Vector2(1, 2), Vector2(-2, 0), Vector2(4, 5))
>>> print(d)
<0.2, 0.4>

ginger.rootfinding.find_rootq(vr: Vector2) → Tuple[float | complex, float | complex]

Solve quadratic equation x² - r·x - q = 0.

This function finds the roots of a quadratic equation represented by the Vector2 vr, where vr.x is r and vr.y is q in the equation above. It handles both real and complex roots appropriately.

Parameters:

vr (Vector2) – Vector containing quadratic coefficients (r,q)

Returns:

Tuple containing the two roots (real or complex)

Return type:

Tuple[Num, Num]

Examples

>>> vr = find_rootq(Vector2(5, -6))
>>> print(vr)
(3.0, 2.0)

ginger.rootfinding.horner(coeffs: List[float], degree: int, vr: Vector2) → Vector2

Evaluate quadratic polynomial factor and return remainder.

This specialized version of Horner’s method evaluates a polynomial divided by a quadratic factor (x² - r·x - q). It returns the linear remainder (A·x + B) and modifies the coefficients array to contain the quotient polynomial.

Parameters:

• coeffs (List[float]) – List of polynomial coefficients in descending order

• degree (int) – Degree of the polynomial (must be ≥ 2)

• vr (Vector2) – Vector representing quadratic factor coefficients (r,q)

Returns:

Remainder vector (A,B)

Return type:

Vector2

Examples

>>> coeffs = [1, -8, -72, 382, 727, -2310]
>>> vp = horner(coeffs, 5, Vector2(-1, 6))  # x^2 + x - 6
>>> coeffs
[1, -9, -57, 385, 0, 0]
>>> coeffs = [1, -8, -72, 382, 727, -2310]
>>> vp = horner(coeffs, 5, Vector2(2, 3))  # x^2 - 2x - 3
>>> coeffs
[1, -6, -81, 202, 888, -1704]

ginger.rootfinding.horner_eval(coeffs: List, zval) → Tuple[Any, List]

Evaluate polynomial and return intermediate coefficients.

This function uses Horner’s method to evaluate a polynomial and also returns the intermediate coefficients that result from the synthetic division process. These coefficients can be used for further computations like derivatives.

Parameters:

• coeffs (List) – List of polynomial coefficients in descending order of degree

• zval – Point at which to evaluate the polynomial (can be complex)

Returns:

Tuple containing: - Value of polynomial at zval - List of intermediate coefficients from synthetic division

Return type:

Tuple[Any, List]

Examples

>>> coeffs = [1, -8, -72, 382, 727, -2310]
>>> horner_eval(coeffs, 3)
(960, [1, -5, -87, 121, 1090, 960])
>>> horner_eval(coeffs, 3+0j)
((960+0j), [1, (-5+0j), (-87+0j), (121+0j), (1090+0j), (960+0j)])

ginger.rootfinding.horner_eval_f(coeffs: List, zval)

Evaluate polynomial using Horner’s method (functional version).

This function computes the value of a polynomial at a given point using Horner’s method, which is more efficient than direct evaluation. It uses Python’s reduce function for a concise implementation.

Parameters:

• coeffs (List) – List of polynomial coefficients in descending order of degree

• zval – Point at which to evaluate the polynomial (can be complex)

Returns:

Value of the polynomial at zval

Return type:

Same type as zval (float or complex)

Examples

>>> coeffs = [1, -8, -72, 382, 727, -2310]
>>> horner_eval_f(coeffs, 3)
960

ginger.rootfinding.initial_guess(coeffs: List[float]) → List[Vector2]

Generate initial root estimates for Bairstow’s method.

This function creates reasonable starting points for the root-finding algorithm by distributing estimates around a circle in the complex plane. The circle’s center and radius are determined from the polynomial’s coefficients.

Parameters:

coeffs (List[float]) – List of polynomial coefficients in descending order

Returns:

List of initial root estimates as Vector2 objects (r,q pairs)

Return type:

List[Vector2]

Examples

>>> h = [10.0, 34.0, 75.0, 94.0, 150.0, 94.0, 75.0, 34.0, 10.0]
>>> vr0s = initial_guess(h)

ginger.rootfinding.pbairstow_even(coeffs: ~typing.List[float], vrs: ~typing.List[~ginger.vector2.Vector2], options=<ginger.rootfinding.Options object>) → Tuple[List[Vector2], int, bool]

Parallel implementation of Bairstow’s root-finding method.

This function implements a parallel version of Bairstow’s method for finding all roots of a polynomial simultaneously. It works by iteratively improving estimates of quadratic factors of the polynomial.

Parameters:

• coeffs (List[float]) – List of polynomial coefficients in descending order

• vrs (List[Vector2]) – Initial estimates for quadratic factors (as Vector2 pairs)

• options (Options) – Configuration parameters for the algorithm

Returns:

Tuple containing: - Final root estimates - Number of iterations performed - Convergence status (True if converged)

Return type:

Tuple[List[Vector2], int, bool]

Examples

>>> h = [10.0, 34.0, 75.0, 94.0, 150.0, 94.0, 75.0, 34.0, 10.0]
>>> vr0s = initial_guess(h)
>>> vrs, niter, found = pbairstow_even(h, vr0s)
>>> print(found)
True

ginger.rootfinding.suppress(vA: Vector2, vA1: Vector2, vri: Vector2, vrj: Vector2)

Improved zero suppression for Bairstow’s method.

This function calculates modified residual vectors that account for interference from other roots in the system. It uses matrix operations to efficiently compute the suppression terms, providing better numerical stability than the original version.

Parameters:

• vA (Vector2) – Current residual vector (A,B)

• vA1 (Vector2) – First derivative residual vector (A1,B1)

• vri (Vector2) – Current root estimate being refined (ri,qi)

• vrj (Vector2) – Another root estimate that might interfere (rj,qj)

Returns:

Tuple of modified residual vectors (vA, vA1)

Return type:

Tuple[Vector2, Vector2]

Reference:

D. C. Handscomb, Computation of the latent roots of a Hessenberg matrix by Bairsow’s method, Computer Journal, 5 (1962), pp. 139-141.

Examples

>>> vA = Vector2(3, 3)
>>> vA1 = Vector2(1, 2)
>>> vri = Vector2(-2, 0)
>>> vrj = Vector2(4, 5)
>>> vA, vA1 = suppress(vA, vA1, vri, vrj)
>>> dr = delta(vA, vri, vA1)
>>> print(dr)
<-16.78082191780822, 1.4383561643835616>

ginger.rootfinding.suppress_old(vA: Vector2, vA1: Vector2, vri: Vector2, vrj: Vector2)

Original implementation of zero suppression in Bairstow’s method.

This function modifies the residual vectors vA and vA1 to suppress the influence of other roots (vrj) when estimating the current root (vri). This helps prevent interference between root estimates during iteration.

Note: This is the original implementation that modifies vectors in-place. The newer version returns modified vectors instead.

Parameters:

• vA (Vector2) – Current residual vector (A,B)

• vA1 (Vector2) – First derivative residual vector (A1,B1)

• vri (Vector2) – Current root estimate being refined (ri,qi)

• vrj (Vector2) – Another root estimate that might interfere (rj,qj)

Reference:

D. C. Handscomb, Computation of the latent roots of a Hessenberg matrix by Bairsow’s method, Computer Journal, 5 (1962), pp. 139-141.

Examples

>>> vA = Vector2(3, 3)
>>> vA1 = Vector2(1, 2)
>>> vri = Vector2(-2, 0)
>>> vrj = Vector2(4, 5)
>>> suppress_old(vA, vA1, vri, vrj)
>>> dr = delta(vA, vri, vA1)
>>> print(dr)
<-16.78082191780822, 1.4383561643835616>

ginger.skeleton module

This is a skeleton file that can serve as a starting point for a Python console script. To run this script uncomment the following lines in the [options.entry_points] section in setup.cfg:

console_scripts =
     fibonacci = ginger.skeleton:run

Then run pip install . (or pip install -e . for editable mode) which will install the command fibonacci inside your current environment.

Besides console scripts, the header (i.e. until _logger…) of this file can also be used as template for Python modules.

Note

This file can be renamed depending on your needs or safely removed if not needed.

References

• https://setuptools.pypa.io/en/latest/userguide/entry_point.html

• https://pip.pypa.io/en/stable/reference/pip_install

ginger.skeleton.fib(n)

Fibonacci example function

Parameters:

n (int) – integer

Returns:

n-th Fibonacci number

Return type:

int

ginger.skeleton.main(args)

Wrapper allowing fib() to be called with string arguments in a CLI fashion

Instead of returning the value from fib(), it prints the result to the stdout in a nicely formatted message.

Parameters:

args (List[str]) – command line parameters as list of strings (for example ["--verbose", "42"]).

ginger.skeleton.parse_args(args)

Parse command line parameters

Parameters:

args (List[str]) – command line parameters as list of strings (for example ["--help"]).

Returns:

command line parameters namespace

Return type:

argparse.Namespace

ginger.skeleton.run()

Calls main() passing the CLI arguments extracted from sys.argv

This function can be used as entry point to create console scripts with setuptools.

ginger.skeleton.setup_logging(loglevel)

Setup basic logging

Parameters:

loglevel (int) – minimum loglevel for emitting messages

ginger.vector2 module

class ginger.vector2.Vector2(x, y)

Bases: object

A 2D vector class for mathematical vector operations.

This class represents a two-dimensional vector with x and y components. It provides basic vector operations like addition, subtraction, scalar multiplication, dot product, and string representation. The class uses slots for memory efficiency and implements proper operator overloading.

dot(rhs)

Calculate the dot product of this vector with another vector.

The dot product (also called scalar product) is a fundamental operation in vector mathematics that returns a single scalar value representing the magnitude of the projection of one vector onto another.

Parameters:

rhs (Vector2) – The right-hand side vector for the dot product operation

Returns:

The scalar dot product result

Return type:

float

Examples

>>> v1 = Vector2(1, 2)
>>> v2 = Vector2(3, 4)
>>> v1.dot(v2)
11

property x

Getter property for the x-component of the vector.

This property provides read-only access to the private _x attribute, maintaining encapsulation while allowing external access to the value.

Returns:

The x-component of the vector as a float

Return type:

float

Examples

>>> v = Vector2(3.0, 4.0)
>>> v.x
3.0

property y

Getter property for the y-component of the vector.

This property provides read-only access to the private _y attribute, maintaining encapsulation while allowing external access to the value.

Returns:

The y-component of the vector as a float

Return type:

float

Examples

>>> v = Vector2(3.0, 4.0)
>>> v.y
4.0

Module contents