Index

AbstractGuidingTermSolver{Tmode}

Supertype for ODE solvers (solving H,F,c system or M,L,μ system or P,ν system). Tmode is a flag for whether computations are done in-place (with states represented by vectors), out-of-place (with state represented by StaticArrays), or on GPUs (with states represented by cuArrays).

struct HFcBuffer{
        T,D,TB,Tβ,Tσ,Ta,Tmat,Tvec
        } <: DiffusionDefinition.AbstractBuffer{T}
    data::Vector{T}
    B::TB
    β::Tβ
    σ::Tσ
    a::Ta
    mat::Tmat
    vec::Tvec
end

A buffer for temporary computations of in-place ODE solvers solving for H,F,c system.

struct HFcContainer{T,D,TH,TF,Tc} <: AbstractBuffer{T}
    data::Vector{T}
    H::TH
    F::TF
    c::Tc
end

A buffer containing data for in-place computations of H,F,c terms.

struct HFcSolver{Tmode,Tsv,Tps,Tcb,Ts,T,Ta} <: AbstractGuidingTermSolver{Tmode}
    saved_values::Tsv
    problem_setup::Tps
    callback::Tcb
    solver::Ts
    HFc0::T
    access::Ta
end

Struct for solving a (H,F,c)-system of ODEs.

    HFcSolver(
        ::Val{:inplace},
        tt,
        xT_plus,
        P,
        obs,
        choices,
    )
Constructor for an ODE solver with in-place operations. Pre-allocates space
and solves a (H,F,c)-system of ODEs once, backward in time on the interval
`(tt[1], tt[end])`, with a terminal condition computed from `xT_plus`. `P`
is the auxiliary diffusion law, `obs` is the observation made at time
`tt[end]` and `choices` contains information about eltype and the algorithm
for solving ODEs. H,F,c are saved on a grid of time-points `tt`.

    HFcSolver(
        ::Val{:outofplace},
        tt,
        xT_plus,
        P,
        obs,
        choices
    )
Constructor for an ODE solver with out-of-place operations using
StaticArrays. Initialises the object and solves a (H,F,c)-system of ODEs
once, backward in time on the interval `(tt[1], tt[end])`, with a terminal
condition computed from `xT_plus`. `P` is the auxiliary diffusion law, `obs`
is the observation made at time `tt[end]` and `choices` contains information
about eltype and the algorithm for solving ODEs. H,F,c are saved on a grid
of time-points `tt`.

IntegrationRule

Supertype of all integration rules. In this package we currently approximate the integrals by step functions with evaluations at the left side of the intervals.

LeftRule <: IntegrationRule

Integration rule flag, indicating to approximate functions with step functions with height equal to function evaluation at the left side of the intevals.

Base.time(P::GuidProp, i)

Return time-point tt[i] corresponding to a saved state of ODEs (with tt[1] indicating time 0+ and tt[end] indicating time T).

Base.rand(
    [rng::Random.AbstractRNG],
    PP::AbstractArray{<:GuidProp}, y1=zero(PP[1]); f=DD.__DEFAULT_F
)

Sample a trajectory started from y1, defined for multiple guided proposals PP that correspond to consecutive intervals. Initialize containers in the background and compute the functionals f (one for each interval) at the time of sampling.

Base.rand(
    [rng::Random.AbstractRNG], P::GuidProp, y1=zero(P); f=DD.__DEFAULT_F
)

Sample a trajectory of a guided proposal P started from y1. Initialize containers in the background and compute the functional f at the time of sampling.

DD.dimension(P::GuidProp)

Dimension of the stochastic process and the driving Brownian motion (by default the same as that of the target process)

DD.same_entries(
    PP::AbstractArray{<:GuidProp},
    PP°::AbstractArray{<:GuidProp},
    entries
)

Go through the collections of guided proposals PP and PP° and compare if they share the same values of fields listed in entries.

DD.set_parameters!(
    PP::AbstractArray{<:GuidProp},
    PP°::AbstractArray{<:GuidProp},
    θ°,
    var_p_names,
    var_p_aux_names,
    θ_local_names,
    θ_local_aux_names,
    θ_local_obs_ind,
    critical_change = is_critical_update(
        PP, θ_local_aux_names, θ_local_obs_ind
    ),
)

Set parameters of Guided proposals PP° in an MCMC setting.

...

Arguments

• PP: containers indicating how PP° should look like before θ° update
• θ°: a vector with new parameters to be potentially set inside PP°
• var_p_names: list of all variable parameter names in PP
• var_p_aux_names: list of all variable parameter names of auxiliary laws in

PP

• θ_local_names: list of pairs with relevant θ° entries for the target law

in a format (idx-of-param-in-θ°::Int64, param-name-in-law::Symbol)

• θ_local_aux_names: list of pairs with relevant θ° entries for the aux law

in a format (idx-of-param-in-θ°::Int64, param-name-in-law::Symbol)

• θ_local_obs_ind: list of pairs with relevant θ° entries for the

observations in a format (idx-of-param-in-θ°::Int64, idx-in-obs::Int64)

• critical_change: boolean for whether θ° update alters any critical

parameters prompting for recomputation of the guiding term ...

DD.set_parameters!(
    PP::AbstractArray{<:GuidProp},
    θ°,
    θ_local_names,
    θ_local_aux_names,
    θ_local_obs_ind
)

Go throught the collection of GuidProps in PP and set the new parameters θ° in relevant fields. θ_local_names lists which fields in the target law need changing. θ_local_aux_names lists the same for the auxiliary laws and θ_local_obs_ind for the observations.

DD.set_parameters!(PP::AbstractArray{<:GuidProp}, θ°::Dict)

Convenience parameter setter

DD.set_parameters!(
    P::GuidProp,
    θ°,
    θ_local_names,
    θ_local_aux_names,
    θ_local_obs_ind
)

Set the new parameters θ° in P. θ_local_names lists which fields in the target law need changing. θ_local_aux_names lists the same for the auxiliary law and θ_local_obs_ind for the observation.

DD.set_parameters!(P::GuidProp, θ°::Dict)

Convenience parameter setter

F(P::GuidProp, i)

Return saved vector Fi.

F(s::HFcSolver, i::Integer)

Return saved vector Fi.

H(P::GuidProp, i)

Return saved matrix Hi.

H(s::HFcSolver, i::Integer)

Return saved matrix Hi.

HFc0(P::GuidProp)

Return the container with data that can be used to reconstruct H,F,c evaluated at time 0+ for the guided proposal P.

HFc0(s::HFcSolver)

Return the data containing H,F,c terms for the time 0+

build_artif_obs(obs, proto_obs, ϵ)

Build an artifical observation for the blocking scheme.

build_guid_prop(
    aux_laws::AbstractArray, recording::NamedTuple, tts::Vector, args, kwargs
)

Same as a version with ::Type{AuxLaw}, but aux_laws is a list of auxiliary laws that correspond to each inter-observation interval.

build_guid_prop(
    ::Type{AuxLaw}, recording::NamedTuple, tts::Vector, args...; kwargs...
) where {AuxLaw <: DD.DiffusionProcess}

Initialize multiple instances of GuidProp corresponding to guided proposals for observations stored in recording. The time grids for each inter-observation interval is given in tts and AuxLaw is the auxiliary law for creating guided proposals. args... are passed to each constructor of GuidProp.

c(P::GuidProp, i)

Return saved scalar ci.

c(s::HFcSolver, i::Integer)

Return saved scalar ci.

equalize_law_params!(
    PP::AbstractArray{<:GuidProp},
    PP°::AbstractArray{<:GuidProp},
    var_p_names,
    var_p_aux_names,
)

Go through two collections of GuidProp and compare their variable parameters. If any of the parameters in PP° ends up being different than in PP then equalize them and if any of them belongs to the auxiliary law then return a critical_change flag.

equalize_obs_params!(
    PP::AbstractArray{<:GuidProp},
    PP°::AbstractArray{<:GuidProp}
)

Go through a collection of GuidProp in PP° and make sure that all observation parameters are the same. If not, equalize them and return a critical_change flag indicating that GuidProp laws need to be recomputed.

extract_parameters_to_pass(P_target, P_aux_type)

A helper function for building an instance of P_aux_type using an initialized P_target. Retreive parameter values from P_target for all parameter names that appear also in P_aux_type.

fetch_eltype(choices, P)

Determine the type of the elements that is supposed to be used by the internal containers of this package. If choice.gradients flag is turned on, then use the same type as the eltypes of the parameters in the auxiliary law. Otherwise, use the type specified in choice. If neither the choice.gradients flag is on, nor a default is provided, use Float64.

fetch_xT_plus(::Val{:inplace}, next_guided_prop, el, dim_of_proc)

If this is not the last inter-observation interval, fetch the data containing H,F,c computed for the left time-limit of the subsequent interval. Otherwise, instantiate a zero-term.

get_or_default(container, elem::Symbol, default)

Return container.elem if it exists, otherwise return default

guid_prop_for_blocking(
    P::GuidProp,
    AuxLaw=remove_curly(R2),
    artificial_noise=1e-11,
    solver_choice=(
        solver=Tsit5(),
        ode_type=:HFc,
        convert_to_HFc=false,
        mode=:outofplace,
        gradients=false,
        eltype=Float64,
    )
)

Initializer for GuidProp struct when doing blocking. It is used to initialize a GuidProp on the last interval of each block. It uses an existing GuidProp instance P from a no-blocking scheme as a template for parameter values and uses a new auxiliary law AuxLaw that is adjusted for the fact that the terminal observation is observed exactly. artificial_noise is added to the exact observation for the numerical purposes. solver choices works as with GuidProp initializer.

init_solver(
    ::Val{:hfc},
    ::Any,
    tt,
    P_aux,
    obs,
    mode::Val,
    choices,
    next_guided_prop
)

Initialise ODE solver for H,F,c, preallocate space and solve it once. tt is the time-grid on which ∇logρ is to be saved. P_aux is the auxiliary law, obs is the terminal observation, mode is for differentiating between in-place, out-of-place and gpu constructors for the guiding term solver, choices contains additional information that is passed on (and which is about eltype and a chosen algorithm for the ODE solvers) and finally, next_guided_prop is the guided proposal used on the subsequent inter-observation interval.

is_critical_update(
    PP::AbstractArray{<:GuidProp},
    θ_local_aux_names,
    θ_local_obs_ind
)

Check if the update of parameters that updates the fields of the auxiliary law listed in θ_local_aux_names and the observations listed in θ_local_obs_ind is critical i.e. whether it prompts for recomputation of the guiding term.

loglikhd_obs(P::GuidProp, x0)

Compute the contribution of end-points to the log-likelihood function, i.e.: $\log\rho(t,x)$.

mode(P::GuidProp)

Return the mode of solving ODE systems (:inplace, :outofplace or :gpu) [TODO not used much, for multiple dispatch needs to return Val{mode}() instead, change or remove].

outer(x)

Compute an outer product

prepare_static_saving_types(::Val{:hfc}, ::Val{D}, el) where D

Define data-types for H,F,c computed by out-of-place solver that are to be saved internally.

recompute_guiding_term!(P::GuidProp, next_guided_prop=nothing)

Recompute the guiding term (most often used after update of parameters or change of an observation). next_guided_prop is the guided proposal law from the subsequent interval

recompute_guiding_term!(PP::Vector{<:GuidProp})

Recompute the guiding term for the entire trajectory with all observations (most often used after update of parameters or change of an observation).

reformat(solver_choice::NamedTuple, last_interval::Bool, P_aux)

Re-format the solver_choice by splitting it into two NamedTuples and populating any missing entries with defaults. P_aux is the law of the auxiliary diffusion that is needed in case a flag for computing gradients is turned on.

size_of_HFc_solution(d)

Length of a vector containing temporary data needed for in-place solver of H,F,c, when the underlying process has dimension d.

size_of_HFc_solution(d)

Compute the size of a vector containing H,F,c elements

solve_and_ll!(X, W, P, y1)

Compute the trajectory under the law P for a given Wiener noise W and a starting point y1. Store the trajectory in XX. Compute the log-likelihood (path contribution) along the way. Return success_flag and log-likelihood. success_flag is set to false only if sampling was prematurely halted due to XX violating assumptions about state space.

standard_guid_prop_time_transf(tt)

Standard time transformation used for guided proposals:

applied to a vector tt where $t_0:=$tt[1] and $T:=$tt[end]

static_accessor_HFc(u::SVector, ::Val{T}) where T

Access data stored in the container u so that it matches the shapes of H,F,c and points to the correct points in u. T is the dimension of the stochastic process.

update_HFc!(u_T, u_Tplus, obs, access)

Update equations for H,F,c at the times of observations. Save the data into u_T.

update_HFc(u_Tplus, obs, access)

Update equations for H,F,c at the times of observations.

Random.rand!(
    [rng::Random.AbstractRNG]
    P::GuidProp,
    X°, W°, W, ρ, v::Val{:ll}, y1=zero(P);
    Wnr=Wiener()
)

Sample a trajectory of a guided proposal P started from y1. Use containers X° and W° to save the results. Use a preconditioned Crank-Nicolson scheme with memory parameter ρ and a previously sampled Wiener noise W. Compute log-likelihood (only path contribution) along the way.

Random.rand!(
    [rng::Random.AbstractRNG]
    PP::AbstractArray{<:GuidProp},
    XX, WW, v::Val{:ll}, y1=zero(PP[1]);
    Wnr=Wiener()
)

Sample a trajectory started from y1 over multiple intervals for guided proposals PP that correspond to consecutive intervals. Use containers XX° and WW° to save the results. Compute log-likelihood (path contribution AND end-points contribution) along the way.

Random.rand!(
    [rng::Random.AbstractRNG]
    PP::AbstractArray{<:GuidProp},
    XX°, WW°, WW, ρρ, v::Val{:ll}, y1=zero(PP[1]);
    Wnr=Wiener()
)

Sample a trajectory started from y1 over multiple intervals for guided proposals PP that correspond to consecutive intervals. Use containers XX° and WW° to save the results. Use a preconditioned Crank-Nicolson scheme with memory parameters ρ (one for the entire interval) and a previously sampled Wiener noise WW. Compute log-likelihood (path contribution AND end-points contribution) along the way.

Random.rand!(
    [rng::Random.AbstractRNG]
    PP::AbstractArray{<:GuidProp},
    XX, WW, y1=zero(PP[1]);
    f=DD.__DEFAULT_F, f_out=DD.__DEFAULT_F, Wnr=Wiener()
)

Sample a trajectory started from y1 over multiple intervals for guided proposals PP that correspond to consecutive intervals. Use containers XX and WW to save the results. Compute the functionals f (one for each interval) at the time of sampling and store the results in f_out.

Random.rand!(
    [rng::Random.AbstractRNG]
    PP::AbstractArray{<:GuidProp},
    XX°, WW°, WW, ρρ, y1=zero(PP[1]);
    f=DD.__DEFAULT_F, f_out=DD.__DEFAULT_F, Wnr=Wiener()
)

Sample a trajectory started from y1 over multiple intervals for guided proposals PP that correspond to consecutive intervals. Use containers XX° and WW° to save the results. Use a preconditioned Crank-Nicolson scheme with memory parameter ρ (one for the entire interval) and a previously sampled Wiener noise WW. Compute the functionals f (one for each interval) at the time of sampling and store the results in f_out.

Random.rand!(
    [rng::Random.AbstractRNG],
    P::GuidProp,
    X, W, y1=zero(P);
    f=DD.__DEFAULT_F, Wnr=Wiener()
)

Sample a trajectory of a guided proposal P started from y1. Use containers X and W to save the results. Compute the functional f at the time of sampling.

Random.rand!(
    [rng::Random.AbstractRNG]
    P::GuidProp,
    X, W, v::Val{:ll}, y1=zero(P);
    Wnr=Wiener()
)

Sample a trajectory of a guided proposal P started from y1. Use containers X and W to save the results. Compute log-likelihood (only path contribution) along the way.

Random.rand!(
    [rng::Random.AbstractRNG],
    P::GuidProp,
    X°, W°, W, ρ, y1=zero(P);
    f=DD.__DEFAULT_F, Wnr=Wiener()
)

Sample a trajectory of a guided proposal P started from y1. Use containers X° and W° to save the results. Use a preconditioned Crank-Nicolson scheme with memory parameter ρ and a previously sampled Wiener noise W. Compute the functional f at the time of sampling.