Public API

# ConstraintCommons.Automaton — Type.

Automaton{S, T, F <: Union{S, Vector{S}, Set{S}}} <: AbstractAutomaton

A minimal implementation of a deterministic automaton structure.

source

# ConstraintCommons.MDD — Type.

MDD{S,T} <: AbstractMultivaluedDecisionDiagram

A minimal implementation of a multivalued decision diagram structure.

source

# ConstraintCommons.accept — Method.

accept(a::Union{Automaton, MDD}, w)

Return true if a accepts the word w and false otherwise.

source

# ConstraintCommons.consin — Method.

consin(::Any, ::Nothing)

Extends Base.in (or ∈) when the set is nothing. Returns false.

source

# ConstraintCommons.consisempty — Method.

consisempty(::Nothing)

Extends Base.isempty when the set is nothing. Returns true.

source

# ConstraintCommons.extract_parameters — Method.

extract_parameters(m::Union{Method, Function}; parameters)

Extracts the intersection between the kargs of m and parameters (defaults to USUAL_CONSTRAINT_PARAMETERS).

source

# ConstraintCommons.incsert! — Function.

incsert!(d::Union{AbstractDict, AbstractDictionary}, ind, val = 1)

Increase or insert a counter in a dictionary-based collection. The counter insertion defaults to val = 1.

source

# ConstraintCommons.oversample — Method.

oversample(X, f)

Oversample elements of X until the boolean function f has as many true and false configurations.

source

# ConstraintCommons.symcon — Function.

symcon(s1::Symbol, s2::Symbol, connector::AbstractString="_")

Extends * to Symbols multiplication by connecting the symbols by an _.

source

# ConstraintCommons.δ_extrema — Method.

δ_extrema(X...)

Compute both the difference between the maximum and the minimum of over all the collections of X.

source

# ConstraintDomains.AbstractDomain — Type.

AbstractDomain

An abstract super type for any domain type. A domain type D <: AbstractDomain must implement the following methods to properly interface AbstractDomain.

• Base.∈(val, ::D)

• Base.rand(::D)

• Base.length(::D) that is the number of elements in a discrete domain, and the distance between bounds or similar for a continuous domain

Additionally, if the domain is used in a dynamic context, it can extend

• add!(::D, args)

• delete!(::D, args)

where args depends on D's structure

source

# ConstraintDomains.ContinuousDomain — Type.

ContinuousDomain{T <: Real} <: AbstractDomain

An abstract supertype for all continuous domains.

source

# ConstraintDomains.DiscreteDomain — Type.

DiscreteDomain{T <: Number} <: AbstractDomain

An abstract supertype for discrete domains (set, range).

source

# ConstraintDomains.ExploreSettings — Method.

ExploreSettings(domains; 
                complete_search_limit = 10^6, 
                max_samplings = sum(domain_size, domains), 
                search = :flexible, 
                solutions_limit = floor(Int, sqrt(max_samplings)))

Create an ExploreSettings object to configure the exploration of a search space composed of a collection of domains.

Arguments

• domains: A collection of domains to be explored.

• complete_search_limit: An integer specifying the maximum limit for complete search iterations. Default is 10^6.

• max_samplings: An integer specifying the maximum number of samplings. Default is the sum of domain sizes.

• search: A symbol indicating the type of search to perform. Default is :flexible.

• solutions_limit: An integer specifying the limit on the number of solutions. Default is the floor of the square root of max_samplings.

Returns

• ExploreSettings object with the specified settings.

source

# ConstraintDomains.RangeDomain — Type.

RangeDomain

A discrete domain defined by a range <: AbstractRange{Real}. As ranges are immutable in Julia, changes in RangeDomain must use set_domain!.

source

# ConstraintDomains.SetDomain — Type.

SetDomain{T <: Number} <: DiscreteDomain{T}

Domain that stores discrete values as a set of (unordered) points.

source

# Base.delete! — Method.

Base.delete!(d::SetDomain, value)(d::SetDomain, value)

Delete value from the list of points in d.

source

# ConstraintDomains.add! — Method.

add!(d::SetDomain, value)

Add value to the list of points in d.

source

# ConstraintDomains.domain — Method.

domain(values)
domain(range::R) where {T <: Real, R <: AbstractRange{T}}

Construct either a SetDomain or a RangeDomain.

d1 = domain(1:5)
d2 = domain([53.69, 89.2, 0.12])
d3 = domain([2//3, 89//123])
d4 = domain(4.3)
d5 = domain(1,42,86.9)

source

# ConstraintDomains.domain — Method.

domain()

Construct an EmptyDomain.

source

# ConstraintDomains.domain — Method.

domain(a::Tuple{T, Bool}, b::Tuple{T, Bool}) where {T <: Real}
domain(intervals::Vector{Tuple{Tuple{T, Bool},Tuple{T, Bool}}}) where {T <: Real}

Construct a domain of continuous interval(s).

source

# ConstraintDomains.domain_size — Method.

domain_size(itv::Intervals)

Return the difference between the highest and lowest values in itv.

source

# ConstraintDomains.domain_size — Method.

domain_size(d <: AbstractDomain)

Fallback method for domain_size(d) that return length(d).

source

# ConstraintDomains.domain_size — Method.

domain_size(d::D) where D <: DiscreteDomain

Return the maximum distance between two points in d.

source

# ConstraintDomains.explore — Method.

explore(domains, concept; settings = ExploreSettings(domains), parameters...)

Search (a part of) a search space and return a pair of vectors of configurations: (solutions, non_solutions). The exploration behavior is determined based on the settings.

Arguments

• domains: A collection of domains to be explored.

• concept: The concept representing the constraint to be targeted.

• settings: An optional ExploreSettings object to configure the exploration. Default is ExploreSettings(domains).

• parameters...: Additional parameters for the concept.

Returns

• A tuple of sets: (solutions, non_solutions).

source

# ConstraintDomains.generate_parameters — Method.

generate_parameters(d<:AbstractDomain, param)

Generates random parameters based on the domain d and the kind of parameters param.

source

# ConstraintDomains.get_domain — Method.

get_domain(::AbstractDomain)

Access the internal structure of any domain type.

source

# ConstraintDomains.intersect_domains — Method.

intersect_domains(d₁, d₂)

Compute the intersections of two domains.

source

# ConstraintDomains.merge_domains — Method.

merge_domains(d₁::AbstractDomain, d₂::AbstractDomain)

Merge two domains of same nature (discrete/contiuous).

source

# ConstraintDomains.to_domains — Method.

to_domains(args...)

Convert various arguments into valid domains format.

source

# Constraints.USUAL_CONSTRAINTS — Constant.

USUAL_CONSTRAINTS::Dict

Dictionary that contains all the usual constraints defined in Constraint.jl. It is based on XCSP3-core specifications available at https://arxiv.org/abs/2009.00514

Adding a new constraint is as simple as defining a new function with the same name as the constraint and using the @usual macro to define it. The macro will take care of adding the new constraint to the USUAL_CONSTRAINTS dictionary.

Example

@usual concept_all_different(x; vals=nothing) = xcsp_all_different(list=x, except=vals)

source

# Constraints.USUAL_SYMMETRIES — Constant.

USUAL_SYMMETRIES

A Dictionary that contains the function to apply for each symmetry to avoid searching a whole space.

source

# Constraints.Constraint — Type.

Constraint

Parametric structure with the following fields.

• concept: a Boolean function that, given an assignment x, outputs true if x satisfies the constraint, and false otherwise.

• error: a positive function that works as preferences over invalid assignments. Return 0.0 if the constraint is satisfied, and a strictly positive real otherwise.

source

# ConstraintCommons.extract_parameters — Function.

extract_parameters(s::Symbol, constraints_dict=USUAL_CONSTRAINTS; parameters=ConstraintCommons.USUAL_CONSTRAINT_PARAMETERS)

Return the parameters of the constraint s in constraints_dict.

Arguments

• s::Symbol: the constraint name.

• constraints_dict::Dict{Symbol,Constraint}: dictionary of constraints. Default is USUAL_CONSTRAINTS.

• parameters::Vector{Symbol}: vector of parameters. Default is ConstraintCommons.USUAL_CONSTRAINT_PARAMETERS.

Example

extract_parameters(:all_different)

source

# Constraints.args — Method.

args(c::Constraint)

Return the expected length restriction of the arguments in a constraint c. The value nothing indicates that any strictly positive number of value is accepted.

source

# Constraints.concept — Method.

concept(c::Constraint)

Return the concept (function) of constraint c. concept(c::Constraint, x...; param = nothing) Apply the concept of c to values x and optionally param.

source

# Constraints.concept — Method.

concept(s::Symbol, args...; kargs...)

Return the concept of the constraint s applied to args and kargs. This is a shortcut for concept(USUAL_CONSTRAINTS[s])(args...; kargs...).

Arguments

• s::Symbol: the constraint name.

• args...: the arguments to apply the concept to.

• kargs...: the keyword arguments to apply the concept to.

Example

concept(:all_different, [1, 2, 3])

source

# Constraints.constraints_descriptions — Function.

constraints_descriptions(C=USUAL_CONSTRAINTS)

Return a pretty table with the descriptions of the constraints in C.

Arguments

• C::Dict{Symbol,Constraint}: dictionary of constraints. Default is USUAL_CONSTRAINTS.

Example

constraints_descriptions()

source

# Constraints.constraints_parameters — Function.

constraints_parameters(C=USUAL_CONSTRAINTS)

Return a pretty table with the parameters of the constraints in C.

Arguments

• C::Dict{Symbol,Constraint}: dictionary of constraints. Default is USUAL_CONSTRAINTS.

Example

constraints_parameters()

source

# Constraints.describe — Function.

describe(constraints::Dict{Symbol,Constraint}=USUAL_CONSTRAINTS; width=150)

Return a pretty table with the description of the constraints in constraints.

Arguments

• constraints::Dict{Symbol,Constraint}: dictionary of constraints to describe. Default is USUAL_CONSTRAINTS.

• width::Int: width of the table.

Example

describe()

source

# Constraints.error_f — Method.

error_f(c::Constraint)

Return the error function of constraint c. error_f(c::Constraint, x; param = nothing) Apply the error function of c to values x and optionally param.

source

# Constraints.params_length — Method.

params_length(c::Constraint)

Return the expected length restriction of the arguments in a constraint c. The value nothing indicates that any strictly positive number of parameters is accepted.

source

# Constraints.symmetries — Method.

symmetries(c::Constraint)

Return the list of symmetries of c.

source

# CompositionalNetworks.Composition — Method.

Composition(f::F, symbols) where {F<:Function}

Construct a Composition.

source

# CompositionalNetworks.Composition — Type.

struct Composition{F<:Function}

Store the all the information of a composition learned by an ICN.

source

# CompositionalNetworks.ICN — Type.

ICN(; nvars, dom_size, param, transformation, arithmetic, aggregation, comparison)

Construct an Interpretable Compositional Network, with the following arguments:

• nvars: number of variable in the constraint

• dom_size: maximum domain size of any variable in the constraint

• param: optional parameter (default to nothing)

• transformation: a transformation layer (optional)

• arithmetic: a arithmetic layer (optional)

• aggregation: a aggregation layer (optional)

• comparison: a comparison layer (optional)

source

# CompositionalNetworks.aggregation_layer — Method.

aggregation_layer()

Generate the layer of aggregations of the ICN. The operations are mutually exclusive, that is only one will be selected.

source

# CompositionalNetworks.arithmetic_layer — Method.

arithmetic_layer()

Generate the layer of arithmetic operations of the ICN. The operations are mutually exclusive, that is only one will be selected.

source

# CompositionalNetworks.code — Function.

code(c::Composition, lang=:maths; name="composition")

Access the code of a composition c in a given language lang. The name of the generated method is optional.

source

# CompositionalNetworks.comparison_layer — Function.

comparison_layer(param = false)

Generate the layer of transformations functions of the ICN. Iff param value is set, also includes all the parametric comparison with that value. The operations are mutually exclusive, that is only one will be selected.

source

# CompositionalNetworks.compose — Function.

compose(icn, weights=nothing)

Return a function composed by some of the operations of a given ICN. Can be applied to any vector of variables. If weights are given, will assign to icn.

source

# CompositionalNetworks.compose_to_file! — Method.

compose_to_file!(concept, name, path; domains, param = nothing, language = :Julia, search = :complete, global_iter = 10, local_iter = 100, metric = hamming, popSize = 200)

Explore, learn and compose a function and write it to a file.

Arguments:

• concept: the concept to learn

• name: the name to give to the constraint

• path: path of the output file

Keywords arguments:

• domains: domains that defines the search space

• param: an optional parameter of the constraint

• language: the language to export to, default to :julia

• search: either :partial or :complete search

• global_iter: number of learning iteration

• local_iter: number of generation in the genetic algorithm

• metric: the metric to measure the distance between a configuration and known solutions

• popSize: size of the population in the genetic algorithm

source

# CompositionalNetworks.composition — Method.

composition(c::Composition)

Access the actual method of an ICN composition c.

source

# CompositionalNetworks.composition_to_file! — Function.

composition_to_file!(c::Composition, path, name, language=:Julia)

Write the composition code in a given language into a file at path.

source

# CompositionalNetworks.explore_learn_compose — Method.

explore_learn_compose(concept; domains, param = nothing, search = :complete, global_iter = 10, local_iter = 100, metric = hamming, popSize = 200, action = :composition)

Explore a search space, learn a composition from an ICN, and compose an error function.

Arguments:

• concept: the concept of the targeted constraint

• domains: domains of the variables that define the training space

• param: an optional parameter of the constraint

• search: either flexible,:partial or :complete search. Flexible search will use search_limit and solutions_limit to determine if the search space needs to be partially or completely explored

• global_iter: number of learning iteration

• local_iter: number of generation in the genetic algorithm

• metric: the metric to measure the distance between a configuration and known solutions

• popSize: size of the population in the genetic algorithm

• action: either :symbols to have a description of the composition or :composition to have the composed function itself

source

# CompositionalNetworks.hamming — Method.

hamming(x, X)

Compute the hamming distance of x over a collection of solutions X, i.e. the minimal number of variables to switch in xto reach a solution.

source

# CompositionalNetworks.lazy — Method.

lazy(funcs::Function...)

Generate methods extended to a vector instead of one of its components. A function f should have the following signature: f(i::Int, x::V).

source

# CompositionalNetworks.lazy_param — Method.

lazy_param(funcs::Function...)

Generate methods extended to a vector instead of one of its components. A function f should have the following signature: f(i::Int, x::V; param).

source

# CompositionalNetworks.learn_compose — Method.

learn_compose(;
    nvars, dom_size, param=nothing, icn=ICN(nvars, dom_size, param),
    X, X_sols, global_iter=100, local_iter=100, metric=hamming, popSize=200
)

Create an ICN, optimize it, and return its composition.

source

# CompositionalNetworks.manhattan — Method.

manhattan(x, X)

source

# CompositionalNetworks.minkowski — Method.

minkowski(x, X, p)

source

# CompositionalNetworks.nbits — Method.

nbits(icn)

Return the expected number of bits of a viable weight of an ICN.

source

# CompositionalNetworks.regularization — Method.

regularization(icn)

Return the regularization value of an ICN weights, which is proportional to the normalized number of operations selected in the icn layers.

source

# CompositionalNetworks.show_layers — Method.

show_layers(icn)

Return a formatted string with each layers in the icn.

source

# CompositionalNetworks.symbols — Method.

symbols(c::Composition)

Output the composition as a layered collection of Symbols.

source

# CompositionalNetworks.transformation_layer — Function.

transformation_layer(param = Vector{Symbol}())

Generate the layer of transformations functions of the ICN. Iff param value is non empty, also includes all the related parametric transformations.

source

# CompositionalNetworks.weights! — Method.

weights!(icn, weights)

Set the weights of an ICN with a BitVector.

source

# CompositionalNetworks.weights — Method.

weights(icn)

Access the current set of weights of an ICN.

source

# CompositionalNetworks.weights_bias — Method.

weights_bias(x)

A metric that bias x towards operations with a lower bit. Do not affect the main metric.

source

# QUBOConstraints.QUBO_linear_sum — Method.

QUBO_linear_sum(n, σ)

One valid QUBO matrix given n variables and parameter σ for the linear sum constraint.

source

# QUBOConstraints.binarize — Method.

binarize(x[, domain]; binarization = :one_hot)

Binarize x following the binarization encoding. If x is a vector (instead of a number per say), domain is optional.

source

# QUBOConstraints.debinarize — Method.

debinarize(x[, domain]; binarization = :one_hot)

Transform a binary vector into a number or a set of number. If domain is not given, it will compute a default value based on binarization and x.

source

# QUBOConstraints.is_valid — Function.

is_valid(x, encoding::Symbol = :none)

Check if x has a valid format for encoding.

For instance, if encoding == :one_hot, at most one bit of x can be set to 1.

source

# QUBOConstraints.train — Method.

train(args...)

Default train method for any AbstractOptimizer.

source