API reference

derivative(
    f::Function,
    x::Union{Cdouble,Vector{Cdouble}},
    mode::Symbol;
    dir::Union{Vector{Cdouble},Matrix{Cdouble}}=Vector{Cdouble}(),
    weights::Union{Vector{Cdouble},Matrix{Cdouble}}=Vector{Cdouble}(),
    tape_id::Integer=0,
    reuse_tape::Bool=false,
)

A variant of the derivative driver, which can be used to compute first-order and second-order derivatives, as well as the abs-normal-form of the given function f at the point x. The available modes are listed here. The formulas in the tables define weights (left multiplier) and dir (right multiplier). Most modes leverage a tape, which has the identifier tape_id. If there is already a valid tape for the function f at the selected point x use reuse_tape=true and set the tape_id accordingly to avoid the re-creation of the tape.

Examples:

First-Order:

f(x) = sin(x)
res = derivative(f, float(π), :jac)

# output

1-element CxxVector:
 -1.0

Second-Order:

f(x) = [x[1]*x[2]^2, x[1]^2*x[3]^3]
x = [1.0, 2.0, -1.0]
dir = [1.0, 0.0, 0.0]
weights = [1.0, 1.0]
res = derivative(f, x, :vec_hess_vec, dir=dir, weights=weights)

# output

3-element CxxVector:
 -2.0
  4.0
  6.0

Abs-Normal-Form:

f(x) = max(x[1]*x[2], x[1]^2)
x = [1.0, 1.0]
res = derivative(f, x, :abs_normal)

# output

AbsNormalForm(0, 1, 2, 1, [1.0, 1.0], [1.0], [0.0], [0.0], [1.0], [1.5 0.5], [0.5;;], [1.0 -1.0], [0.0;;])

derivative(
    f::Function,
    x::Union{Cdouble,Vector{Cdouble}},
    param::Union{Cdouble,Vector{Cdouble}},
    mode::Symbol;
    dir=Vector{Cdouble}(),
    weights=Vector{Cdouble}(),
    tape_id::Integer=0,
    reuse_tape::Bool=false,
)

This version of the derivative driver allows the definition of function parameters (param), which can be changed in subsequent calls without retaping. The given function f is expected to have the shape f(x, param).

Example:

function f(x, param)
    x1 = x[1] * param[1]
    return [x1*x[2], x[2]] 
end
x = [-1.0, 1/2]
param = 3.0
dir = [2.0, -2.0]
res = derivative(f, x, param, :jac_vec, dir=dir, tape_id=1)

##res[1] == 9.0
##res[2] == -2.0

param = -3.0
x = [1.0, 1.0]
res = derivative(f, x, param, :jac_vec, dir=dir, tape_id=1, reuse_tape=true)
res 

# output

2-element CxxVector:
  0.0
 -2.0

derivative(
    f::Function,
    x::Union{Cdouble,Vector{Cdouble}},
    partials::Vector{Vector{Int64}};
    tape_id::Integer=0,
    reuse_tape::Bool=false,
    id_seed::Bool=false,
    adolc_format::Bool=false,
)

A variant of the derivative driver, which can be used to compute higher-order derivatives of the function f at the point x. The derivatives are specified as mixed-partials in the partials vector. To define the partial-derivatives use either the Partial-Format or the ADOLC-Format and set adolc_format accordingly. The flag id_seed is used to specify the method for seed-matrix generation. The underlying method leverages a tape, which has the identifier tape_id. If there is already a valid tape for the function f at the selected point x use reuse_tape=true and set the tape_id accordingly to avoid the re-creation of the tape.

Examples:

Partial-Format:

f(x) = [x[1]^2*x[2]^2, x[3]^2*x[4]^2]
x = [1.0, 2.0, 3.0, 4.0]
partials = [[1, 1, 0, 0], [0, 0, 1, 1], [2, 2, 0, 0]]
res = derivative(f, x, partials)

# output

2×3 CxxMatrix:
 8.0   0.0  4.0
 0.0  48.0  0.0

ADOLC-Format:

f(x) = [x[1]^2*x[2]^2, x[3]^2*x[4]^2]
x = [1.0, 2.0, 3.0, 4.0]
partials = [[2, 1, 0, 0], [4, 3, 0, 0], [2, 2, 1, 1]]
res = derivative(f, x, partials, adolc_format=true)

# output

2×3 CxxMatrix:
 8.0   0.0  4.0
 0.0  48.0  0.0

derivative(
    f::Function,
    x::Union{Cdouble,Vector{Cdouble}},
    partials::Vector{Vector{Int64}},
    seed::Matrix{Cdouble};
    tape_id::Integer=0,
    reuse_tape::Bool=false,
    adolc_format::Bool=false,
)

Variant of the derivative driver for the computation of higher-order derivatives, that requires a seed. Details on the idea behind seed can be found here.

Example:

f(x) = [x[1]^4, x[2]^3*x[1]]
x = [1.0, 2.0]
partials = [[1], [2], [3]]
seed = CxxMatrix([[1.0, 1.0];;])
res = derivative(f, x, partials, seed)


# output

2×3 CxxMatrix:
  4.0  12.0  24.0
 20.0  36.0  42.0

derivative(
f,
x::Union{Cdouble, Vector{Cdouble}},
degree::Integer;
tape_id::Integer=0,
reuse_tape::Bool=false

)

derivative(
f,
x::Union{Cdouble, Vector{Cdouble}},
degree::Integer,
seed::CxxMatrix;
tape_id::Integer=0,
reuse_tape::Bool=false

)

derivative!(
    res,
    f::Function,
    m::Integer,
    n::Integer,
    x::Union{Cdouble,Vector{Cdouble}},
    mode::Symbol;
    dir::Union{Vector{Cdouble},Matrix{Cdouble}}=Vector{Cdouble}(),
    weights::Union{Vector{Cdouble},Matrix{Cdouble}}=Vector{Cdouble}(),
    tape_id::Integer=0,
    reuse_tape::Bool=false,
)

A variant of the derivative driver for first-, second-order and abs-normal-form computations that allows the user to provide a pre-allocated container for the result res. The container can be allocated by leveraging the methods allocator or init_abs_normal_form. In addition to the arguments of derivative, the output dimension m and input dimension n of the function f is required. If there is already a valid tape for the function f at the selected point x use reuse_tape=true and set the tape_id accordingly to avoid the re-creation of the tape.

Example:

f(x) = [cos(x[1]), x[2]*x[3]]
x = [0.0, 1.5, -1.0]
mode = :hess_mat
dir = [[1.0, -1.0, 1.0] [0.5, -0.5, 1.0]]
m = 2
n = 3
res =  allocator(m, n, mode, size(dir, 2)[1], 0)
derivative!(res, f, m, n, x, mode, dir=dir)
res
# output

2×3×2 CxxTensor:
[:, :, 1] =
 -1.0  0.0   0.0
  0.0  1.0  -1.0

[:, :, 2] =
 -0.5  0.0   0.0
  0.0  1.0  -0.5

f(x) = max(x[1]*x[2], x[1]^2)
x = [1.0, 1.0]
m = 1
n = 2
abs_normal_form = init_abs_normal_form(f, x)
derivative!(abs_normal_form, f, m, n, x, :abs_normal, tape_id=abs_normal_form.tape_id, reuse_tape=true)
abs_normal_form
# output

AbsNormalForm(0, 1, 2, 1, [1.0, 1.0], [1.0], [0.0], [0.0], [1.0], [1.5 0.5], [0.5;;], [1.0 -1.0], [0.0;;])

derivative!(
    res,
    f::Function,
    x::Union{Cdouble,Vector{Cdouble}},
    param::Union{Cdouble,Vector{Cdouble}},
    mode::Symbol;
    dir=Vector{Cdouble}(),
    weights=Vector{Cdouble}(),
    tape_id::Integer=0,
    reuse_tape::Bool=false,
)

This version of the derivative! driver allows the definition of function parameters (param), which can be changed in subsequent calls without retaping. The given function f is expected to have the shape f(x, param).

Example:

function f(x, param)
    a = x*param
    return a^2
end
x = 3.0
param = -1.0
tape_id = 0
m = n = 1
res = CxxVector(1)
derivative!(res, f, m, n, x, param, :jac, tape_id=tape_id)
##res[1] = 6.0

param = -4.5
derivative!(res, f, m, n, x, param, :jac, reuse_tape=true, tape_id=tape_id)
res

# output

1-element CxxVector:
 121.5

derivative!(
    res,
    f,
    m::Integer,
    n::Integer,
    x::Union{Cdouble,Vector{Cdouble}},
    partials::Vector{Vector{Int64}};
    tape_id::Integer=0,
    reuse_tape::Bool=false,
    id_seed::Bool=false,
    adolc_format::Bool=false,
)

A variant of the derivative driver for the computation of higher-order derivatives that allows the user to provide a pre-allocated container for the result res. In addition to the arguments of derivative, the output dimension m and input dimension n of the function f is required. If there is already a valid tape for the function f at the selected point x use reuse_tape=true and set the tape_id accordingly to avoid the re-creation of the tape.

Example:

f(x) = x[1]^4*x[2]*x[3]*x[4]^2
x = [3.0, -1.5, 1.5, -2.0]
partials = [[4, 0, 0, 0], [3, 0, 1, 2]]
m = 1
n = 4
res = CxxMatrix(m, length(partials))
derivative!(res, f, m, n, x, partials)
res

# output

1×2 CxxMatrix:
 -216.0  -216.0

derivative!(
    res,
    f,
    m::Integer,
    n::Integer,
    x::Union{Cdouble,Vector{Cdouble}},
    partials::Vector{Vector{Int64}},
    seed::CxxMatrix;
    tape_id::Integer=0,
    reuse_tape::Bool=false,
    adolc_format::Bool=false,
)

Variant of the derivative! driver for the computation of higher-order derivatives, that requires a seed. Details on the idea behind seed can be found here.

Example:

f(x) = [x[1]^4, x[2]^3*x[1]]
x = [1.0, 2.0]
partials = [[1], [2], [3]]
seed = CxxMatrix([[1.0, 1.0];;])
m = 2
n = 2
res = CxxMatrix(m, length(partials))
derivative!(res, f, m, n, x, partials, seed)
res

# output

2×3 CxxMatrix:
  4.0  12.0  24.0
 20.0  36.0  42.0

function_and_derivative_value!(
    res::Vector,
    f::Function,
    m::Integer,
    n::Integer,
    x::Union{Cdouble,Vector{Cdouble}},
    mode::Symbol;
    dir=Vector{Cdouble}(),
    weights=Vector{Cdouble}(),
    tape_id::Integer=0,
    reuse_tape::Bool=false,
)

Variant of the derivative! function, which stores the value of f at x in the first entry of res. The second entry stores the derivatives.

Example

f(x) = sin(x)
jac_val = CxxVector([0.0])
func_val = [0.0]
res = [func_val, jac_val]
function_and_derivative_value!(res, f, 1, 1, float(π), :jac)
res 
# output

2-element Vector{AbstractVector{Float64}}:
 [1.2246467991473532e-16]
 [-1.0]

tensor_address(degree::Integer, adolc_partial::Vector{Integer})
tensor_address(degree::Integer, adolc_partial::Vector{Cint})

Generates the index (address) of the mixed-partial specified by adolc_partial in an higher-order derivative tensor of derivative order degree.

partial_to_adolc_format(partial::Vector{I_1}, degree::I_2) where {I_1<:Integer, I_2<:Integer}

Transforms a given partial to the ADOLC-Format.

Example:

partial = [1, 0, 4]
degree = sum(partial)
partial_to_adolc_format(partial, degree)

# output

5-element Vector{Int32}:
 3
 3
 3
 3
 1

partial_to_adolc_format!(res::Vector{Cint}, partial::Vector{I_1}, degree::I_2) where {I_1<:Integer, I_2<:Integer}
partial_to_adolc_format!(res::Vector{Cint}, partial::Vector{Cint}, degree::I) where I <: Integer

Variant of partial_to_adolc_format that writes the result to res.

Example:

partial = [1, 3, 2, 0]
degree = sum(partial)
res = zeros(Int32, degree)
partial_to_adolc_format!(res, partial, degree)

# output

6-element Vector{Int32}:
 3
 3
 2
 2
 2
 1

create_cxx_identity(n::I_1, m::I_2) where {I_1 <: Integer, I_2 <: Integer}

Creates a identity matrix of shape (n, m) of type CxxPtr{CxxPtr{Float64}} (wrapper of C++'s double**).

Example

id = CxxMatrix(create_cxx_identity(2, 4), 2, 4)


# output

2×4 CxxMatrix:
 1.0  0.0  0.0  0.0
 0.0  1.0  0.0  0.0

create_partial_cxx_identity(n::I_1, idxs::Vector{I_2}) where {I_1 <: Integer, I_2 <: Integer}

Creates a matrix of shape (n, length(idxs)) of type CxxPtr{CxxPtr{Float64}} (wrapper of C++'s double**). The columns are canonical basis vectors corresponding to the entries of idxs. The order of the basis vectors is defined by the order of the indices in idxs. Details about the application can be found in this guide.

Examples

n = 4
idxs = [1, 3]
id = CxxMatrix(create_partial_cxx_identity(n, idxs), n, length(idxs))
# output

4×2 CxxMatrix:
 1.0  0.0
 0.0  0.0
 0.0  1.0
 0.0  0.0

The order in idxs defines the order of the basis vectors.

n = 3
idxs = [3, 0, 1]
id = CxxMatrix(create_partial_cxx_identity(n, idxs), n, length(idxs))


# output

3×3 CxxMatrix:
 0.0  0.0  1.0
 0.0  0.0  0.0
 1.0  0.0  0.0

seed_idxs_partial_format(partials::Vector{Vector{I}}) where I <: Integer

Extracts the actually required derivative directions of partials and returns them ascendet sorted.

Example

partials = [[1, 0, 0, 0, 3], [1, 0, 1, 0, 0], [0, 0, 3, 0, 0]]
seed_idxs_partial_format(partials)

# output

3-element Vector{Int64}:
 1
 3
 5

seed_idxs_adolc_format(partials::Vector{Vector{I}}) where I <: Integer

Extracts the actually required derivative directions of partials and returns them ascendet sorted.

Example

partials = [[5, 5, 5, 1], [3, 1, 0, 0], [3, 3, 3, 0]]
seed_idxs_adolc_format(partials)

# output

3-element Vector{Int64}:
 1
 3
 5

partial_format_to_seed_space(partials::Vector{Vector{I_1}}, seed_idxs::Vector{I_2}) where {I_1 <: Integer, I_2 <: Integer}
partial_format_to_seed_space(partials::Vector{Vector{I}}) where I <: Integer

Converts partials in Partial-Format to partials of the same format but with (possible) reduced number of derivatives directions. The seed_idxs is expected to store the result of seed_idxs_partial_format(seed_idxs). Without seed_idxs the function first calls seed_idxs_partial_format(seed_idxs) to get the indices.

Examples

partials = [[0, 1, 1], [0, 2, 0]]
seed_idxs = seed_idxs_partial_format(partials)
partial_format_to_seed_space(partials, seed_idxs)

# output

2-element Vector{Vector{Int64}}:
 [1, 1]
 [2, 0]

Without seed_idxs

partials = [[0, 1, 1], [0, 2, 0]]
partial_format_to_seed_space(partials)

# output

2-element Vector{Vector{Int64}}:
 [1, 1]
 [2, 0]

adolc_format_to_seed_space(partials::Vector{Vector{I_1}}, seed_idxs::Vector{I_2}) where {I_1 <: Integer, I_2 <: Integer}
adolc_format_to_seed_space(partials::Vector{Vector{I}}) where I <: Integer

Same as partial_format_to_seed_space but with ADOLC-Format.

Examples

partials = [[3, 2], [2, 2]]
seed_idxs = seed_idxs_adolc_format(partials)
adolc_format_to_seed_space(partials, seed_idxs)

# output

2-element Vector{Vector{Int64}}:
 [2, 1]
 [1, 1]

Without seed_idxs

partials = [[3, 2], [2, 2]]
seed_idxs = seed_idxs_adolc_format(partials)
adolc_format_to_seed_space(partials, seed_idxs)

# output

2-element Vector{Vector{Int64}}:
 [2, 1]
 [1, 1]

create_independent(x::Union{Cdouble, Vector{Cdouble}})

Marks the argument x as independent variable on the tape and create differentiable Adouble{TbAlloc} for x.

create_independent(x::Union{Cdouble, Vector{Cdouble}}, param::Union{Cdouble,Vector{Cdouble}})

The argument x is stored as differentiable Adouble{TbAlloc} and marked as independent. param is marked as parameters on the tape to be changeble without retaping.

dependent(b::Union{Adouble{TbAlloc}, Vector{Adouble{TbAlloc}}})

Marks a differentiable Adouble{TbAlloc} b as dependent.

allocator(m::Integer, n::Integer, mode::Symbol, num_dir::Integer, num_weights::Integer)

jl_allocator(m::Int64, n::Int64, mode::Symbol, num_dir::Int64, num_weights::Int64)

cxx_res_to_jl_res!(jl_res::AbstractVector{Cdouble}, cxx_res::CxxVector)
cxx_res_to_jl_res!(jl_res::AbstractMatrix{Float64}, cxx_res::CxxMatrix)
cxx_res_to_jl_res!(jl_res::AbstractArray{Float64, 3}, cxx_res::CxxTensor)

Copies the entries of a CxxVector, CxxMatrix or CxxTensor to a AbstractVector{Cdouble}, AbstractMatrix{Cdouble} or AbstractArray{Cdouble, 3}.

cxx_res_to_jl_res(cxx_res::CxxVector) 
cxx_res_to_jl_res(cxx_res::CxxMatrix)
cxx_res_to_jl_res(cxx_res::CxxTensor)

Creates a Vector{Cdouble}, Matrix{Cdouble} or Array{Cdouble, 3} and copies the values from the given input CxxVector, CxxMatrix or CxxTensor to it.

jl_res_to_cxx_res!(cxx_res::CxxVector, jl_res::AbstractVector{Cdouble}) 
jl_res_to_cxx_res!(cxx_res::CxxMatrix, jl_res::AbstractMatrix{Cdouble})
jl_res_to_cxx_res!(cxx_res::CxxTensor, jl_res::AbstractArray{Cdouble, 3})

Copies the values of a AbstractVector{Cdouble}, AbstractMatrix{Cdouble} or AbstractArray{Cdouble, 3} to a corresponding CxxVector, CxxMatrix or CxxTensor.

jl_res_to_cxx_res(jl_res::AbstractVector{Cdouble}) 
jl_res_to_cxx_res(jl_res::AbstractMatrix{Cdouble})
jl_res_to_cxx_res(jl_res::AbstractArray{Cdouble, 3})

Creates a CxxVector, CxxMatrix or CxxTensor and copies the values from the given input AbstractVector{Cdouble}, AbstractMatrix{Cdouble} or AbstractArray{Cdouble, 3} to it.

mutable struct CxxTensor <: AbstractArray{Cdouble, 3}

Wrapper for CxxPtr{CxxPtr{CxxPtr{Cdouble}}}, which is used as double*** in C++.

mutable struct CxxVector <: AbstractVector{Cdouble}

Wrapper of a double* (CxxPtr{Cdouble}).

mutable struct CxxMatrix <: AbstractMatrix{Cdouble}

Wrapper for CxxPtr{CxxPtr{Cdouble}}, which is used as double** in C++.

init_abs_normal_form(
    f, x::Union{Cdouble,Vector{Cdouble}}; tape_id::Integer=0, reuse_tape=false
)

init_abs_normal_form(
    f, x::Union{Cdouble,Vector{Cdouble}}, param::Union{Cdouble, Vector{Cdouble}}; tape_id::Integer=0, reuse_tape=false
)

univariate_tpp(
    f,
    x::Union{Cdouble,Vector{Cdouble}},
    degree::Integer;
    keep::Bool=false,
    tape_id::Integer=0,
    reuse_tape::Bool=false,
)

The driver propagates univariate Taylor polynomials through the given function f at the point x up to degree. The keep flag is used to prepare the tape for subsequent reverse-mode computations on the Taylor polynomial. The tape_id specifies the identifier of the tape and the flag reuse_tape should be used for suppressing the tape creation. More information is given in the guide: Univariate Taylor Polynomial Propagation.

univariate_tpp(
    f,
    x::Union{Cdouble,Vector{Cdouble}},
    degree::Integer,
    init_tp::CxxMatrix;
    keep::Bool=false,
    tape_id::Integer=0,
    reuse_tape::Bool=false,
)

Version of the univariate_tpp driver, which allows additional control over the initial Taylor polynomial. More information is given in the guide: Univariate Taylor Polynomial Propagation.

univariate_tpp!(
    res::CxxMatrix,
    f,
    x::Union{Cdouble,Vector{Cdouble}},
    degree::Integer,
    init_tp::CxxMatrix;
    keep::Bool=false,
    tape_id::Integer=0,
    reuse_tape::Bool=false,
)

A version of the univariate_tpp driver that allows a user to pass in a pre-allocated CxxMatrix. More information is given in the guide: Univariate Taylor Polynomial Propagation.