Custom Homotopies

For this guide, we're going to walk through the process to construct a custom homotopy for your specific problem.


To track solutions from a start system $G$ to the target system $F$ we use by default the straight-line homotopy

$$ H(x,t) := (1-t)F+tG\;. $$

But this is in general not the best choice since you usually leave the solution space of your problem. Therefore we support the ability to define arbitrary homotopies where you have the full power of Julia available.

In the following we will illustrate how to setup a custom homotopy on the following example. For polynomial systems $F$ and $G$ we want to define the homotopy

$$ H(x,t) = (1 - t) F( U(t) x ) + tG( U(t) x ) $$

where $U(t)$ is a random path in the space of unitary matrices with $U(0) = U(1) = I$ and $I$ is the identity matrix. Such a random path can be constructed by

$$ U(t) = U \begin{bmatrix}\cos(2\pi t) & -\sin(2\pi t) & 0 &\cdots & 0 \\ \sin(2\pi t) & \cos(2\pi t) & 0 &\cdots & 0 \\ 0 & 0 & 1 &\cdots & 0\\ 0 & 0 & 0 &\ddots & 0\\ 0 & 0 & 0 &\cdots & 1 \end{bmatrix} U^T. $$

with a random unitary matrix $U$.

Figuring out the math

To define a homotopy we have to know how to compute for all $x \in \mathbb{C}^n$, $t \in \mathbb{C}$

$$ H(x,t), \quad \frac{\partial H}{\partial x}(x,t) \quad \text{ and } \quad \frac{\partial H}{\partial t}(x,t)\;. $$

We denote the partial derivative of $H$ w.r.t. $x$ as the Jacobian of $H$. For simplification (in the math as well as in the implementation) we introduce the helper homotopy

$$ \tilde{H}(y, t) := (1 - t) F( y ) + tG(y)\;. $$

Note $H(x,t) = \tilde{H}(U(t)x, t)$. Using the chain rule we get for the partial derivatives

$$ \frac{\partial H}{\partial x}(x,t) = \frac{\partial \tilde{H}}{\partial y}(U(t)x,t) U(t) $$


$$ \frac{\partial H}{\partial t}(x,t) = \frac{\partial \tilde{H}}{\partial y}(U(t)x,t) U’(t) x + \frac{\partial \tilde{H}}{\partial t}(U(t)x,t) $$


$$ U’(t)= U \begin{bmatrix}-2\pi\sin(2\pi t) & -2\pi\cos(2\pi t) & 0 &\cdots & 0 \\ 2\pi\cos(2\pi t) & -2\pi\sin(2\pi t) & 0 &\cdots & 0 \\ 0 & 0 & 0 &\cdots & 0\\ 0 & 0 & 0 &\ddots & 0\\ 0 & 0 & 0 &\cdots & 0 \end{bmatrix} U^T. $$

Constructing the homotopy data structures

A custom homotopy has to satisfy a certain interface. We start with the data structure for the homotopy. A homotopy is represented by a struct which is a subtype of Homotopies.AbstractHomotopy. Since $\tilde{H}$ is the standard straight-line homotopy we can reuse this implementation to safe us some work since homotopies compose easily.

using HomotopyContinuation, LinearAlgebra

struct RandomUnitaryPath{Start,Target} <: Homotopies.AbstractHomotopy
    straightline::StraightLineHomotopy{Start, Target}
function RandomUnitaryPath(start::Systems.AbstractSystem, target::Systems.AbstractSystem)
    m, n = size(start)
    # construct a random unitary matrix
    U = Matrix(qr(randn(n,n) + im * randn(n,n)).Q)
    RandomUnitaryPath(Homotopies.StraightLineHomotopy(start, target), U)
# We have to define the size
Base.size(H::RandomUnitaryPath) = size(H.straightline)

To get good performance it is important to be careful about memory allocations. It is much much better to initialize a chunk of memory once and to reuse this memory. To support this optimization we have the concept of a cache. This is a struct with supertype Homotopies.AbstractHomotopyCache where we allocate all memory necessary to evaluate and differentiate our homotopy. This is an optimization and not necessary to have at the beginning, but for the best it is necessary to implement it. To illustrate how to do this, we will implement here a cache. Don’t look with too much detail on the exact type definition for now, we just allocate a bunch of stuff which will make much more sense later. As a constructor for the cache we have to define the Homotopies.cache method.

struct RandomUnitaryPathCache{C, T1, T2} <: Homotopies.AbstractHomotopyCache
    # More temporary storage necessary to avoid allocations
    jac::Matrix{T2} # holds a jacobian
    dt::Vector{T2} # holds a derivative w.r.t. t
    U::Matrix{ComplexF64} # holds something like U

# A cache is always constructed by this method.
function Homotopies.cache(H::RandomUnitaryPath, x, t)
    U_t = copy(H.U)
    y = U_t * x
    straightline = Homotopies.cache(H.straightline, y, t)

    jac = Homotopies.jacobian(H.straightline, y, t, straightline)
    dt = jac * y
    U = copy(U_t)
    RandomUnitaryPathCache(straightline, U_t, y, jac, dt, U)

Implementing the evaluation and derivatives

We start with implementing subroutines to evaluate and differentiate $U(t)$ as well as computing $U(t)x$ and $U’(t)x$. We use the U_t and y fields in cache to store the values $U(t)$ and $U(t)x$ (resp. $U’(t)$ and $U’(t)x$)

# U(t)x
function Ut_mul_x!(cache, U, x, t)
    # We start with U * (the 2x2 sin-cos block + I)
    cache.U .= U
    s, c = sin(2π*t), cos(2π*t)
    for i=1:size(U, 1)
        cache.U[i, 1] = U[i,2] * s + U[i,1] * c
        cache.U[i, 2] = U[i,2] * c - U[i,1] * s
    # U(t) = cache.U * U'
    # y = cache.y = U(t) * x
    mul!(cache.y, mul!(cache.U_t, cache.U, U'), x)

# U'(t)x
function U_dot_t_mul_x!(cache, U, x, t)
    # We start with U * (the derivative of the 2x2 sin-cos block + 0)
    cache.U .= zero(eltype(U))
    s, c = 2π*sin(2π*t), 2π*cos(2π*t)
    for i=1:size(U, 1)
        cache.U[i, 1] =  U[i,2] * c - U[i,1] * s
        cache.U[i, 2] = -U[i,2] * s - U[i,1] * c

    # U'(t) = cache.U * U'
    # y' = cache.y = U'(t) * x
    mul!(cache.y, mul!(cache.U_t, cache.U, U'), x)

Now we are ready to implement $H(x,t)$, its Jacobian and the derivative w.r.t. $t$.

function Homotopies.evaluate!(out, H::RandomUnitaryPath, x, t, cache)
    y = Ut_mul_x!(cache, H.U, x, t)
    Homotopies.evaluate!(out, H.straightline, y, t, cache.straightline)

function Homotopies.jacobian!(out, H::RandomUnitaryPath, x, t, cache)
    y = Ut_mul_x!(cache, H.U, x, t)
    Homotopies.jacobian!(cache.jac, H.straightline, y, t, cache.straightline)
    mul!(out, cache.jac, cache.U_t) # out = J_H(y, t) * U(t)

function Homotopies.dt!(out, H::RandomUnitaryPath, x, t, cache)
    y = Ut_mul_x!(cache, H.U, x, t)
    # chain rule
    Homotopies.jacobian_and_dt!(cache.jac, out, H.straightline, y, t, cache.straightline)
    y_dot = U_dot_t_mul_x!(cache, H.U, x, t) # y_dot = U'(t)x
    mul!(cache.dt, cache.jac, y_dot) # dt = J_H(y, t) * y_dot
    out .+= cache.dt

We also support to compute evaluate! and jacobian! simultaneously as well as to compute jacobian! and dt! simultaneously. This can be very beneficial for the performance, so let’s implement this here since this mostly involve copy-paste.

function Homotopies.evaluate_and_jacobian!(val, jac, H::RandomUnitaryPath, x, t, cache)
    y = Ut_mul_x!(cache, H.U, x, t)
    Homotopies.evaluate_and_jacobian!(val, cache.jac, H.straightline, y, t, cache.straightline)
    mul!(jac, cache.jac, cache.U_t)

function Homotopies.jacobian_and_dt!(jac, dt, H::RandomUnitaryPath, x, t, cache)
    y = Ut_mul_x!(cache, H.U, x, t)
    Homotopies.jacobian_and_dt!(cache.jac, dt, H.straightline, y, t, cache.straightline)
    mul!(jac, cache.jac, cache.U_t) # jac = J_H(y, t) * U(t)
    y_dot = U_dot_t_mul_x!(cache, H.U, x, t) # y_dot = U'(t)x
    mul!(cache.dt, cache.jac, y_dot) # dt = J_H(y, t) * y_dot
    dt .+= cache.dt

Testing our implementation

Implementing these methods without ever testing them is … not a good idea. Also just throwing the homotopy into solve can result in confusing error messages. Therefore we provide a set of tests against which we can test our implementation. Although they do not check that we implemented the math correctly (or that our math is correct in the first place), they will catch any runtime errors.

# Let us construct some test systems
@polyvar x y z;

F = SPSystem([x^2*y-3x*z, z^2*x+3y^2]);
G = SPSystem([z*x^2-3x*y^2, z^3*x-2x*y*z^2]);

# Here we can test that our implementation does not produce an error
InterfaceTest.homotopy(RandomUnitaryPath(G, F))
Test Passed

Using our new homotopy

We are now ready to use our new homotopy!

solve([x^2 - y, y^3*x-x], homotopy=RandomUnitaryPath)
AffineResult with 8 tracked paths
• 6 non-singular solutions (2 real)
• 1 singular solution (1 real)
• 1 solution at infinity
• 0 failed paths
• random seed: 847463

Alternatively we could also construct the homotopy directly and give it to solve together with start solutions. Note that in this case we have to ensure that our homotopy is already homogenous.