Manual

solve(Algorithm::CDCPSolver, obj, S::Integer, args...; kwargs...) = cdcp::CDCProblem

Solve a combinatorial discrete choice problem over S possible items, using a given solution algorithm that can be SqueezingPolicy, Squeezing or Naive. Results are returned as a CDCProblem. See the methods below.

The objective function obj should return the value evaluated at a choice vector ℒ with an optional parameter z that is typically a number (e.g. productivity).

obj must have a method of either obj(ℒ) (if no parameter is specified) or obj(ℒ, z) (if a parameter is specified). obj must not restrict the specific type of ℒ but only assume ℒ is a vector of length S with element type being Bool. Specifically, obj must not try to modify the elements in ℒ when it is called. It should only read from ℒ with getindex.

solve(Squeezing, obj, scdca::Bool; z=nothing)

The problem should satisfy SCD-C from above if scdca is true and SCD-C from below if scdca is false.

Keywords

• z=nothing

solve(SqueezingPolicy, obj, S::Integer, scdca::Bool, equal_obj, zbounds::Tuple{Z,Z}=(-Inf, Inf); kwargs...)

The problem should satisfy SCD-C from above if scdca is true and SCD-C from below if scdca is false.

The function equal_obj should returns the cutoff type z with zleft <= z0 <= zright that is indifferent between two decision sets ℒ1 and ℒ2.

equal_obj can be defined with one of the two following methods:

• equal_obj((ℒ1, ℒ2), zleft, zright): where the pair of input choices is accepted as a tuple
• equal_obj(obj1::Objective, obj2::Objective, zleft, zright): where obj1 and obj2 are the same objective function attached with different input vectors obj1.ℒ and obj2.ℒ that correspond to ℒ1 and ℒ2 respectively

zbounds determines the domain of the parameter z, which defaults to (-Inf, Inf).

Keywords

• zero_margin=nothing: a function that returns the type z that is indifferent to adding item ℓ to decision set ℒ; it should have the method zero_margin(obj::Objective, ℓ::Int, zleft, zright) with ℒ attached to obj and if not supplied, this function will be generated automatically from equal_obj
• policy0::Policy=Policy(obj, zbounds): initial policy which on top of which optimisation occurs
• skiprefinement::Bool=false: skip the refinement step that searches resolves intervals for which squeezing doesn't pin down optimal policy
• singlekw=NamedTuple(): keyword arguments passed to the single-agent solver as a NamedTuple used in the branching stage.
• maxfcall=1_000_000_000: maximum calls to the objective function

solve(Naive, obj, S::Integer; kwargs...)

Solve with exhaustion by checking all potential decision sets. This method should be used with extreme caution.

Keywords

• z=nothing: the type parameterising the problem

CDCProblem{M<:CDCPSolver, O<:Objective, T, F<:AbstractFloat}

Results from solving a combinatorial discrete choice problem with solve. When a solution is attained, it can be retrieved from the field x.

Fields

• solver::CDCPSolver
• obj::[Objective]: the objective function
• x: the solution, once solved
• value: the maximum value found by the solver
• state::SolverState

SolverState::Int8

An Enum type with values:

• inprogress
• success
• maxfcall_reached

See also solve, CDCProblem.

ItemState::Int8

An Enum type describing the state of item ℓ with values:

• excluded: from squeezing, definitely excluded
• included: from squeezing, definitely included
• aux: checked, but cannot definitively include or exclude based on squeezing
• undetermined: not yet checked

See also solve, CDCProblem.

Policy{Z,V<:AbstractVector{ItemState}} <: AbstractVector{IntervalChoice{Z,V}}

Policy function derived from SqueezingPolicy.

Given a policy function policy::Policy, the optimal decision set of a type z can be retrieved as expected, i.e. policy(z).

See also solve, CDCProblem.

Fields

• cutoffs::Vector{Z}: cutoff types at which optimal decision set switches
• itemstates_s::Vector{V}: a vector of decision sets, so that itemstates_s[k] corresponds to the types above cutoffs[k] and below cutoffs[k+1]
• zright::Z: the maximum type z (can be Inf).