struct Composition{F<:Function}

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

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

Construct a Composition.

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)

Layer

A structure to store a LittleDict of operations that can be selected during the learning phase of an ICN. If the layer is exclusive, only one operation can be selected at a time.

length(layer)

Return the number of operations in a layer.

Base.length(icn)

Return the total number of operations of an ICN.

_compose(icn)

Internal function called by compose and show_composition.

ag_count_positive(x)

Count the number of strictly positive elements of x.

ag_sum(x)

Aggregate through + a vector into a single scalar.

aggregation_layer()

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

ar_prod(x)

Reduce k = length(x) vectors through product to a single vector.

ar_sum(x)

Reduce k = length(x) vectors through sum to a single vector.

arithmetic_layer()

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

as_bitvector(n::Int, max_n::Int = n)

Convert an Int to a BitVector of minimal size (relatively to max_n).

as_int(v::AbstractVector)

Convert a BitVector into an Int.

co_abs_diff_var_val(x; val)

Return the absolute difference between x and val.

co_abs_diff_var_vars(x; nvars)

Return the absolute difference between x and the number of variables nvars.

co_euclidean(x; dom_size)

Compute an euclidean norm with domain size dom_size of a scalar.

co_euclidean_val(x; val, dom_size)

Compute an euclidean norm with domain size dom_size, weighted by val, of a scalar.

co_identity(x)

Identity function. Already defined in Julia as identity, specialized for scalars in the comparison layer.

co_val_minus_var(x; val)

Return the difference val - x if positive, 0.0 otherwise.

co_var_minus_val(x; val)

Return the difference x - val if positive, 0.0 otherwise.

co_var_minus_vars(x; nvars)

Return the difference x - nvars if positive, 0.0 otherwise, where nvars denotes the numbers of variables.

co_vars_minus_var(x; nvars)

Return the difference nvars - x if positive, 0.0 otherwise, where nvars denotes the numbers of variables.

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.

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.

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.

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

composition(c::Composition)

Access the actual method of an ICN composition c.

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

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

exclu(layer)

Return true if the layer has mutually exclusive operations.

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

functions(layer)

Access the operations of a layer. The container is ordered.

generate(c::Composition, name, lang)

Generates the code of c in a specific language lang.

generate_exclusive_operation(max_op_number)

Generates the operations (weights) of a layer with exclusive operations.

generate_inclusive_operations(predicate, bits)
generate_exclusive_operation(max_op_number)

Generates the operations (weights) of a layer with inclusive/exclusive operations.

generate_weights(layers)
generate_weights(icn)

Generate the weights of a collection of layers or of an ICN.

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.

is_viable(layer, w)
is_viable(icn)
is_viable(icn, w)

Assert if a pair of layer/icn and weights compose a viable pattern. If no weights are given with an icn, it will check the current internal value.

layers(icn)

Return the ordered layers of an ICN.

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).

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).

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.

make_transformations(param::Symbol)

Generates a dictionary of transformation functions based on the specified parameterization. This function facilitates the creation of parametric layers for constraint transformations, allowing for flexible and dynamic constraint manipulation according to the needs of different constraint programming models.

Parameters

• param::Symbol: Specifies the type of transformations to generate. It can be :none for basic transformations that do not depend on external parameters, or :val for transformations that operate with respect to a specific value parameter.

Returns

• LittleDict{Symbol, Function}: A dictionary mapping transformation names (Symbol) to their corresponding functions (Function). The functions encapsulate various types of transformations, such as counting, comparison, and contiguous value processing.

Transformation Types

• When param is :none, the following transformations are available:

  • :identity: No transformation is applied.
  • :count_eq, :count_eq_left, :count_eq_right: Count equalities under different conditions.
  • :count_greater, :count_lesser: Count values greater or lesser than a threshold.
  • :count_g_left, :count_l_left, :count_g_right, :count_l_right: Count values with greater or lesser comparisons from different directions.
  • :contiguous_vals_minus, :contiguous_vals_minus_rev: Process contiguous values with subtraction in normal and reverse order.

• When param is :val, the transformations relate to operations involving a parameter value:

  • :count_eq_param, :count_l_param, :count_g_param: Count equalities or comparisons against a parameter value.
  • :count_bounding_param: Count values bounding a parameter value.
  • :val_minus_param, :param_minus_val: Subtract a parameter value from values or vice versa.

The function delegates to a version that uses Val(param) for dispatch, ensuring compile-time selection of the appropriate transformation set.

Examples

# Get basic transformations
basic_transforms = make_transformations(:none)

# Apply an identity transformation
identity_result = basic_transforms[:identity](data)

# Get value-based transformations
val_transforms = make_transformations(:val)

# Apply a count equal to parameter transformation
count_eq_param_result = val_transforms[:count_eq_param](data, param)

manhattan(x, X)

map_tr!(f, x, X, param)

Return an anonymous function that applies f to all elements of x and store the result in X, with a parameter param (which is set to nothing for function with no parameter).

minkowski(x, X, p)

nbits(icn)

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

nbits_exclu(layer)

Convert the length of an exclusive layer into a number of bits.

reduce_symbols(symbols, sep)

Produce a formatted string that separates the symbols by sep. Used internally for show_composition.

regularization(icn)

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

selected_size(layer, layer_weights)

Return the number of operations selected by layer_weights in layer.

show_layer(layer)

Return a string that contains the elements in a layer.

show_layers(icn)

Return a formatted string with each layers in the icn.

symbol(layer, i)

Return the i-th symbols of the operations in a given layer.

symbols(c::Composition)

Output the composition as a layered collection of Symbols.

tr_contiguous_vars_minus(i, x)
tr_contiguous_vars_minus(x)
tr_contiguous_vars_minus(x, X::AbstractVector)

Return the difference x[i] - x[i + 1] if positive, 0.0 otherwise. Extended method to vector with sig (x) are generated. When X is provided, the result is computed without allocations.

tr_contiguous_vars_minus_rev(i, x)
tr_contiguous_vars_minus_rev(x)
tr_contiguous_vars_minus_rev(x, X::AbstractVector)

Return the difference x[i + 1] - x[i] if positive, 0.0 otherwise. Extended method to vector with sig (x) are generated. When X is provided, the result is computed without allocations.

tr_count_bounding_val(i, x; val)
tr_count_bounding_val(x; val)
tr_count_bounding_val(x, X::AbstractVector; val)

Count the number of elements bounded (not strictly) by x[i] and x[i] + val. An extended method to vector with sig (x, val) is generated. When X is provided, the result is computed without allocations.

tr_count_eq(i, x)
tr_count_eq(x)
tr_count_eq(x, X::AbstractVector)

Count the number of elements equal to x[i]. Extended method to vector with sig (x) are generated. When X is provided, the result is computed without allocations.

tr_count_eq_left(i, x)
tr_count_eq_left(x)
tr_count_eq_left(x, X::AbstractVector)

Count the number of elements to the left of and equal to x[i]. Extended method to vector with sig (x) are generated. When X is provided, the result is computed without allocations.

tr_count_eq_right(i, x)
tr_count_eq_right(x)
tr_count_eq_right(x, X::AbstractVector)

Count the number of elements to the right of and equal to x[i]. Extended method to vector with sig (x) are generated. When X is provided, the result is computed without allocations.

tr_count_eq_val(i, x; val)
tr_count_eq_val(x; val)
tr_count_eq_val(x, X::AbstractVector; val)

Count the number of elements equal to x[i] + val. Extended method to vector with sig (x, val) are generated. When X is provided, the result is computed without allocations.

tr_count_g_left(i, x)
tr_count_g_left(x)
tr_count_g_left(x, X::AbstractVector)

Count the number of elements to the left of and greater than x[i]. Extended method to vector with sig (x) are generated. When X is provided, the result is computed without allocations.

tr_count_g_right(i, x)
tr_count_g_right(x)
tr_count_g_right(x, X::AbstractVector)

Count the number of elements to the right of and greater than x[i]. Extended method to vector with sig (x) are generated.

tr_count_g_val(i, x; val)
tr_count_g_val(x; val)
tr_count_g_val(x, X::AbstractVector; val)

Count the number of elements greater than x[i] + val. Extended method to vector with sig (x, val) are generated. When X is provided, the result is computed without allocations.

tr_count_greater(i, x)
tr_count_greater(x)
tr_count_greater(x, X::AbstractVector)

Count the number of elements greater than x[i]. Extended method to vector with sig (x) are generated. When X is provided, the result is computed without allocations.

tr_count_l_left(i, x)
tr_count_l_left(x)
tr_count_l_left(x, X::AbstractVector)

Count the number of elements to the left of and lesser than x[i]. Extended method to vector with sig (x) are generated. When X is provided, the result is computed without allocations.

tr_count_l_right(i, x)
tr_count_l_right(x)
tr_count_l_right(x, X::AbstractVector)

Count the number of elements to the right of and lesser than x[i]. Extended method to vector with sig (x) are generated. When X is provided, the result is computed without allocations.

tr_count_l_val(i, x; val)
tr_count_l_val(x; val)
tr_count_l_val(x, X::AbstractVector; val)

Count the number of elements lesser than x[i] + val. Extended method to vector with sig (x, val) are generated. When X is provided, the result is computed without allocations.

tr_count_lesser(i, x)
tr_count_lesser(x)
tr_count_lesser(x, X::AbstractVector)

Count the number of elements lesser than x[i]. Extended method to vector with sig (x) are generated. When X is provided, the result is computed without allocations.

tr_identity(i, x)
tr_identity(x)
tr_identity(x, X::AbstractVector)

Identity function. Already defined in Julia as identity, specialized for vectors. When X is provided, the result is computed without allocations.

tr_in(tr, X, x, param)

Application of an operation from the transformation layer. Used to generate more efficient code for all compositions.

tr_val_minus_var(i, x; val)
tr_val_minus_var(x; val)
tr_val_minus_var(x, X::AbstractVector; val)

Return the difference val - x[i] if positive, 0.0 otherwise. Extended method to vector with sig (x, val) are generated. When X is provided, the result is computed without allocations.

tr_var_minus_val(i, x; val)
tr_var_minus_val(x; val)
tr_var_minus_val(x, X::AbstractVector; val)

Return the difference x[i] - val if positive, 0.0 otherwise. Extended method to vector with sig (x, val) are generated. When X is provided, the result is computed without allocations.

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.

weights!(icn, weights)

Set the weights of an ICN with a BitVector.

weights(icn)

Access the current set of weights of an ICN.

weights_bias(x)

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