Results

Result

The result of solve. This is a wrapper around the results of each single path (PathResult) and it contains some additional information like a random seed to replicate the result.

seed(::Result)

Returns the seed to replicate the result.

path_results(::Result)

Returns the stored PathResults.

results(
    result;
    only_real = false,
    real_atol = 1e-6,
    real_rtol = 0.0,
    only_nonsingular = false,
    only_singular = false,
    only_finite = true,
    multiple_results = false,
)
results(f, result; options...)

Return all PathResults for which satisfy the given conditions and apply, if provided, the function f.

results(result::MonodromyResult)

Returns the computed PathResults.

results(W::WitnessSet)

Get the results stored in W.

solutions(result; only_nonsingular = true, conditions...)

Returns all solutions for which the given conditions apply, see results for the possible conditions.

Example

julia> @var x y
julia> F = System([(x-2)y, y+x+3]);
julia> solutions(solve(F))
2-element Array{Array{Complex{Float64},1},1}:
 [2.0 + 0.0im, -5.0 + 0.0im]
 [-3.0 + 0.0im, 0.0 + 0.0im]

solutions(result::MonodromyResult)

Return all solutions.

solutions(W::WitnessSet)

Get the solutions stored in W.

solutions(d::DistinctCertifiedSolutions)

Return a vector of solutions in the DistinctSolutionCertificates object.

real(result; kwargs...)

Get all results where the solutions are real with the given tolerance tol. See is_real for details regarding how kwargs affect the determination of 'realness'.

real_solutions(result; atol=1e-6, rtol = 0.0, conditions...)

Return all real solution for which the given conditions apply. For the possible conditions see results. Note that only_real is always true, real_atol is now atol and real_rtol is now rtol.

Example

julia> @var x y;
julia> F = System([(x-2)y, y+x+3]);
julia> real_solutions(solve(F))
2-element Array{Array{Float64,1},1}:
 [2.0, -5.0]
 [-3.0, 0.0]

nonsingular(result; conditions...)

Return all PathResults for which the solution is non-singular. This is just a shorthand for results(R; only_nonsingular=true, conditions...). For the possible conditions see results.

singular(result; multiple_results=false, kwargs...)

Return all [PathResult]s for which the solution is singular. If multiple_results=false only one point from each cluster of multiple solutions is returned. If multiple_results = true all singular solutions in R are returned. For the possible kwargs see results.

at_infinity(result)

Get all results where the solutions is at infinity.

failed(result)

Get all results where the path tracking failed.

nresults(
    result;
    only_real = false,
    real_atol = 1e-6,
    real_rtol = 0.0,
    only_nonsingular = false,
    only_singular = false,
    only_finite = true,
    multiple_results = false,
)

Count the number of results which satisfy the corresponding conditions. See also results.

nresults(result::MonodromyResult)

Returns the number of results computed.

nsolutions(result; only_nonsingular = true, options...)

The number of solutions. See results for the possible options.

nsolutions(result::MonodromyResult)

Returns the number solutions of the result.

nreal(result; kwargs...)

The number of real solutions. See also is_real.

nnonsingular(result)

The number of non-singular solutions. See also is_singular.

nsingular(
    result;
    counting_multiplicities = false,
    kwargs...,
)

The number of singular solutions. A solution is considered singular if its winding number is larger than 1 or the condition number is larger than tol. If counting_multiplicities=true the number of singular solutions times their multiplicities is returned.

nat_infinity(result)

The number of solutions at infinity.

nexcess_solutions(result)

The number of exess solutions. See also excess_solution_check.

nfailed(result)

The number of failed paths.

PathResult

A PathResult is the result of tracking of a path with track using an AbstractPathTracker ( e.g. EndgameTracker)

Fields

General solution information:

• return_code: See the list of return codes below.
• solution::V: The solution vector.
• t::Float64: The value of t at which solution was computed. Note that if return_code is :at_infinity, then t is the value when this was decided.
• accuracy::Float64: An estimate the (relative) accuracy of the computed solution.
• residual::Float64: The infinity norm of H(solution,t).
• condition_jacobian::Float64: This is the condition number of the Jacobian at the solution. A high condition number indicates a singular solution or a solution on a positive dimensional component.
• singular::Bool: Whether the solution is considered singular.
• winding_number:Union{Nothing, Int}: The computed winding number. This is a lower bound on the multiplicity of the solution. It is $nothing$ if the Cauchy endgame was not used.
• extended_precision::Bool: Indicate whether extended precision is necessary to achieve the accuracy of the solution.
• path_number::Union{Nothing,Int}: The number of the path (optional).
• start_solution::Union{Nothing,V}: The start solution of the path (optional).

Performance information:

• accepted_steps::Int: The number of accepted steps during the path tracking.
• rejected_steps::Int: The number of rejected steps during the path tracking.
• extended_precision_used::Bool: Indicates whether extended precision was necessary to track the path.

Additional path and solution informations

• valuation::Vector{Float64}: An approximation of the valuation of the Puiseux series expansion of $x(t)$.
• last_path_point::Tuple{V,Float64}: The last pair $(x,t)$ before the solution was computed. If the solution was computed with the Cauchy endgame, then the pair $(x,t)$ can be used to rerun the endgame.

Return codes

Possible return codes are:

• :success: The EndgameTracker obtained a solution.
• :at_infinity: The EndgameTracker stopped the tracking of the path since it determined that that path is diverging towards infinity.
• :at_zero: The EndgameTracker stopped the tracking of the path since it determined that that path has a solution where at least one coordinate is 0. This only happens if the option zero_is_at_infinity is true.
• :excess_solution: For the solution of the system, the system had to be modified which introduced artificial solutions and this solution is one of them.
• various return codes indicating termination of the tracking

solution(r::PathResult)

Get the solution of the path.

is_success(r::PathResult)

Checks whether the path is successfull.

is_at_infinity(r::PathResult)

Checks whether the path goes to infinity.

is_excess_solution(r::PathResult)

Checks whether gives an excess solution that was artificially introduced by the homotopy continuation from the modified system.

is_failed(r::PathResult)

Checks whether the path failed.

is_finite(r::PathResult)

Checks whether the path result is finite.

is_singular(r::PathResult)

Checks whether the path result r is singular.

is_nonsingular(r::PathResult)

Checks whether the path result is non-singular. This is true if it is not singular.

is_real(r::PathResult; atol::Float64 = 1e-6, rtol::Float64 = 0.0)

We consider a result as real if either:

• the infinity-norm of the imaginary part of the solution is less than atol
• the infinity-norm of the imaginary part of the solution is less than rtol * norm(s, 1), where s is the solution in PathResult.

accuracy(r::PathResult)

Get the accuracy of the solution. This is an estimate of the (relative) distance to the true solution.

residual(r::PathResult)

Get the residual of the solution.

steps(r::PathResult)

Total number of steps the path tracker performed.

accepted_steps(r::PathResult)

Total number of steps the path tracker accepted.

rejected_steps(r::PathResult)

Total number of steps the path tracker rejected.

winding_number(r::PathResult)

Get the winding number of the solution of the path. Returns nothing if it wasn't computed.

path_number(r::PathResult)

Get the number of the path. Returns nothing if it wasn't provided.

start_solution(r::PathResult)

Get the start solution of the path.

multiplicity(r::PathResult)

Get the multiplicity of the solution of the path.

last_path_point(r::PathResult)

Returns a tuple (x,t) containing the last zero of H(x, t) before the Cauchy endgame was used. Returns nothing if the endgame strategy was not invoked.

valuation(r::PathResult)

Get the computed valuation of the path.

ResultIterator{Iter} <: AbstractResult

A struct which represents a result. Its fields are

• starts: An iterator over the start solutions of a solver.
• S: The solver which was used to compute the results.
• bitmask (optional): A BitVector which is used to filter the results.

It is an iterator over the start solutions of a solver, which may also be passed as an iterator. Objects of this type can be treated just like a Result object, i.e. you can iterate over it, get the length, etc. The distinction is that it does not store the results but rather computes them on-the-fly when iterated over. This is useful for large sets of results or when you want to apply a filter to the results without storing them all in memory.

Example

julia> @var x y a[1:6];
julia> F = System(
        [
            (a[1] * x^2 + a[2] * y) * (a[3] * x + a[4] * y) + 1,
            (a[1] * x^2 + a[2] * y) * (a[5] * x + a[6] * y) + 1,
        ];
        parameters = a,
    )
julia> P = randn(ComplexF64,6)
julia> res = solve(
        F;
        iterator_only = true,
        target_parameters = P,
    )
ResultIterator
==============
•  start solutions: PolyhedralStartSolutionsIterator
•  homotopy: Polyhedral

You may collect res to obtain the results. Doing so actually tracks the paths.

collect(res)

Now, res may be passed along to solve as a set of start solutions.

solve(F, res; 
    iterator_only = true, 
    target_parameters = randn(ComplexF64,6)
)

bitmask_filter(f::Function, ri::ResultIterator)

Given a boolean valued function f and a ResultIterator ri, this function returns a new ResultIterator which represents the results for which f returns true. It does this by iterating through ri and applying f to each result to create a BitVector that serves to cache the results of f for each solution in ri.

julia> @var x y;
julia> F = System([x^3 + y^3 - 1, x + y - 1])
julia> res = solve(F; iterator_only = true)
julia> bm = bitmask_filter(is_real, res)
ResultIterator
==============
•  start solutions: PolyhedralStartSolutionsIterator
•  homotopy: Polyhedral
•  filtering bitmask

trace(ri::ResultIterator)

This function computes the coordinate-wise sum, or trace, of the solutions in a ResultIterator by iterating through the solutions and summing them up one at a time.

julia> @var x y;
julia> F = System([x^3 + y^3 - 1, x + y - 1])
julia> res = solve(F; iterator_only = true)
julia> tr = trace(res)
2-element Vector{ComplexF64}:
 1.0 + 0.0im
 1.0 + 0.0im

trace(result::MonodromyResult)

Return the result of the trace test computed during the monodromy.